feat: Add TTY and test adapters (#53)

* add TTY and test adapters

* add docs and make a small refactor

* added more in-code docs

* refactor exit handlers

* rename `Text` to `View`

* update README

Author: zamotany

README.md

@@ -18,51 +18,151 @@ yarn add react-stream-renderer
 
 ```js
 import React from 'react';
-import { render, Text } from 'react-stream-renderer';
+import { render, View, makeTTYAdapter } from 'react-stream-renderer';
 
 class App extends React.Component {
   render() {
     return (
-      <Text style={{ color: 'green' }}>
+      <View style={{ color: 'green' }}>
         Hello world!
-      </Text>
+      </View>
     );
   }
 }
 
-render(<App />, process.stdout);
+render(<App />, makeTTYAdapter(process.stdout).makeEffects());
 ```
 
 ## API
 ---
 
 ## Functions
 
-### `render(element, writableStream, options): void`
+### `render(element: React.Element, adapter: BaseAdapter): () => void`
+
+Render given element using a given adapter (`makeTTYAdapter` for TTY streams or `makeTestAdapter` for testing purposes).
+
+Returns `forceRender` function which triggers full re-render.
+
+### `makeTTYAdapter(ttyStream: NodeTTYStream): TTYAdapter`
+
+Creates an adapter a TTY Node stream.
+Use chainable API from `TTYAdapter` for configuring the behavior:
+
+#### `withCustomConsole(options: OverwriteConsoleOptions): TTYAdapter`
+
+Redirect console output to specified streams or files.
+
+This method won't have any effect unless `makeEffects` is called.
+
+`options: OverwriteConsoleOptions`:
+
+* `exitOnWarning: boolean` - Exit on first call to `console.warning`.
+* `exitOnError: boolean` - Exit on first call to `console.error`.
+* `outStream: boolean | string | NodeWritableStream` - Redirect console output to:
+  * `stdout.log` if `true`
+  * custom file if `string` with path is supplied
+  * custom Node stream if writable node stream is supplied
+* `errStream: boolean | string | NodeWritableStream` - Redirect console error output to:
+  * `stderr.log` if `true`
+  * custom file if `string` with path is supplied
+  * custom Node stream if writable node stream is supplied
+
+#### `hideCursor(): TTYAdapter`
+
+Hides cursor.
+
+This method won't have any effect unless `makeEffects` is called.
+
+#### `clearOnExit(shouldClearScrollback: boolean = false): TTYAdapter`
+
+Clear screen or scrollback (if `shouldClearScrollback` is `true`) when process is about to exit.
+
+This method won't have any effect unless `makeEffects` is called.
+
+#### `clearOnError(): TTYAdapter`
+
+Clear screen (scrollback will be untouched) when process is about to exit due to an error.
+
+This method won't have any effect unless `makeEffects` is called.
+
+#### `makeEffects(): TTYAdapter`
+
+Perform accumulated side effects.
+__This method must always be called!__
+
+__Example__
+
+```js
+render(
+  <View>Hello world</View>,
+  makeTTYAdapter(process.stdout)
+    .withCustomConsole({ outStream: true, errStream: true })
+    .hideCursor()
+    .clearOnExit(true)
+    .makeEffects()
+);
+```
+
+### `makeTestAdapter(options: Options): TestAdapter`
+
+Creates an adapter for testing. You can provide hooks to assert the rendered content.
+
+#### `options: Options` 
+
+* `height: number = 40` - Canvas height (default: `40`)
+* `width: number = 80` - Canvas width (default: `80`)
+* `onPrint?: (data: string) => void` - Testing hook executed on each render, `data` will be a string with full rendered content.
+* `onClear: () => void` - Testing hook executed when canvas should be cleared.
+* `onSetCursorPosition: (x: number, y: number) => void`- Testing hook executed when cursor should be changed.
 
-Render given element to writable (Node) stream.
+#### Example
+
+```js
+test('render should draw content', () => {
+  const onDraw = jest.fn();
+  const adapter = makeTestAdapter({ onDraw });
 
-#### `options`
+  render(<View>Test</View>, adapter);
 
-* `hideCursor?: boolean` - Hide cursor if true.
-* `clearOnError?: boolean` - Clear screen when process exits due to error being thrown.
-* `clearScreenOnExit?: boolean` - Clear screen when process is about to exit.
-* `clearScrollbackOnExit?: boolean` - Clear scrollback when process is about to exit (__clearing scrollback also clears the whole screen__).
-* `exitOnWarning?: boolean` - Exit when there's a call to `console.warn`.
-* `exitOnError?: boolean` - Exit when there's a call to `console.error`.
-* `outStream?: any` - Custom writable stream or file path for output from `console`.
-* `errStream?: any` - Custom writable stream or file path for errors logged with `console.error`.
+  expect(onDraw).toHaveBeenCalledWith('Test');
+});
+```
 
 ## Components
 
-### `Text`
+### `View` (aka `Text`)
+
+Basic building block. Can render text (strings), arrays and other nested components.
 
-Basic building block. Can render text (strings) or other nested components.
+`Text` component is exposed for compatibility and it's the same as `View`.
 
 #### Props
 
 * `style?: Style` - Object with [Style properties](#style-properties)
 
+#### Example
+
+```js
+class App extends React.Component {
+  render() {
+    return (
+      <View>
+        <View style={styles.title}>Hello world!</View>
+        Today is {new Date().toLocaleString()}
+      </View>
+    );
+  }
+}
+
+const styles = {
+  title: {
+    margin: '0 1',
+    color: 'green',
+  },
+};
+```
+
 
 ### `KeyPress`
 

example/src/index.js

@@ -1,6 +1,8 @@
+// @TODO: refactor this
+
 import React from 'react';
 // eslint-disable-next-line
-import { render, Chunk, Endl, Text } from 'react-stream-renderer';
+import { render, Text, makeTTYAdapter } from 'react-stream-renderer';
 
 import Dev from './dev';
 import ListViewer from './listViewer';
@@ -20,12 +22,4 @@ switch (process.argv[2]) {
     App = ListViewer;
 }
 
-render(<App />, process.stdout, {
-  debug: false,
-  renderOptimizations: false,
-  hideCursor: true,
-  exitOnError: true,
-  clearOnError: true,
-  clearScreenOnExit: false,
-  clearScrollbackOnExit: true,
-});
+render(<App />, makeTTYAdapter(process.stdout).makeEffects());

src/adapters/BaseAdapter.js

@@ -0,0 +1,71 @@
+/* @flow */
+/* eslint-disable class-methods-use-this */
+
+export interface IBaseAdapter {
+  /**
+   * Tells if the adapter is ready. For example if there's a need to
+   * trigger some side effects this flag can be used to distinct if they're
+   * applied or not.
+   */
+  isReady: boolean;
+
+  /**
+   * Error message to show if the adapter is not ready yet.
+   */
+  notReadyErrorMessage: string;
+
+  /**
+   * Switches to rendering full content of the canvas instead of drawing
+   * only damaged lines.
+   */
+  forceFullPrint: boolean;
+
+  /**
+   * Provides width and height of the canvas on which the content will be rendered.
+   */
+  getSize(): { width: number, height: number };
+
+  /**
+   * Prints rendered content. This is the place to flush content to the host environment.
+   */
+  print(data: string, metadata: { isFullPrint: boolean }): void;
+
+  /**
+   * Clear the content below the cursor position, which will be set before
+   * using `setCursorPosition`.
+   */
+  clear(): void;
+
+  /**
+   * Moves cursor to specific coordinates.
+   */
+  setCursorPosition(x: number, y: number): void;
+}
+
+type BaseAdapterOptions = {
+  forceFullPrint: boolean | null | void,
+};
+
+export default class BaseAdapter implements IBaseAdapter {
+  isReady: boolean = false;
+  notReadyErrorMessage: string;
+  forceFullPrint: boolean;
+
+  constructor({ forceFullPrint }: BaseAdapterOptions = {}) {
+    this.forceFullPrint = Boolean(forceFullPrint);
+  }
+
+  getSize() {
+    throw new Error('Adapter#getSize must be provided');
+  }
+
+  // eslint-disable-next-line no-unused-vars
+  print(data: string, metadata: *) {
+    throw new Error('Adapter#print must be provided');
+  }
+
+  clear() {}
+
+  // eslint-disable-next-line no-unused-vars
+  setCursorPosition(x: number, y: number) {}
+}

src/adapters/TTY/TTYAdapter.js

@@ -0,0 +1,121 @@
+/* @flow */
+
+import readline from 'readline';
+
+import type { NodeStream } from '../../types';
+
+import BaseAdapter from '../BaseAdapter';
+import clearCallbacksOnExit from './effects/clearCallbacksOnExit';
+import overwriteConsole from './effects/overwriteConsole';
+import {
+  hideCursor,
+  clearOnExit,
+  clearScrollbackOnExit,
+  clearOnError,
+} from './effects/terminal';
+
+/**
+ * Adapter for TTY streams like `process.{stdout,stderr}` with chainable API for
+ * enhancing the experience with terminal apps.
+ *
+ * @example
+ * const adapter = new TTYAdapter()
+ *   .withCustomConsole({ outStream: true, errStream: true })
+ *   .hideCursor()
+ *   .makeEffects();
+ */
+export default class TTYAdapter extends BaseAdapter {
+  notReadyErrorMessage: string = 'Adapter is not ready. Did you forgot to call `makeEffects`?';
+  effects: Function[];
+  stream: NodeStream;
+
+  constructor({
+    effects,
+    stream,
+  }: {
+    effects: Function[],
+    stream: NodeStream,
+  }) {
+    super();
+    this.stream = stream;
+    this.effects = effects;
+  }
+
+  /**
+   * Redirect console output to specified streams or files.
+   * This method won't have any effect unless `makeEffects` is called.
+   */
+  withCustomConsole(params: *) {
+    return new TTYAdapter({
+      stream: this.stream,
+      effects: [...this.effects, () => overwriteConsole(params)],
+    });
+  }
+
+  /**
+   * Hides cursor.
+   * This method won't have any effect unless `makeEffects` is called.
+   */
+  hideCursor() {
+    return new TTYAdapter({
+      stream: this.stream,
+      effects: [...this.effects, hideCursor],
+    });
+  }
+
+  /**
+   * Clear screen or scrollback when process is about to exit.
+   * This method won't have any effect unless `makeEffects` is called.
+   */
+  clearOnExit(shouldClearScrollback: boolean) {
+    return new TTYAdapter({
+      stream: this.stream,
+      effects: [
+        ...this.effects,
+        adapter => {
+          if (shouldClearScrollback) {
+            clearScrollbackOnExit(adapter);
+          } else {
+            clearOnExit(adapter);
+          }
+        },
+      ],
+    });
+  }
+
+  /**
+   * Clear screen when process is about to exit due to an error.
+   * This method won't have any effect unless `makeEffects` is called.
+   */
+  clearOnError() {
+    return new TTYAdapter({
+      stream: this.stream,
+      effects: [...this.effects, clearOnError],
+    });
+  }
+
+  /**
+   * Perform accumulated side effects.
+   */
+  makeEffects() {
+    clearCallbacksOnExit();
+    this.effects.forEach(effect => effect(this));
+    this.isReady = true;
+    return this;
+  }
+
+  getSize() {
+    // $FlowFixMe
+    return { width: this.stream.columns, height: this.stream.rows };
+  }
+
+  print(data: string) {
+    this.stream.write(data);
+  }
+  clear() {
+    readline.clearScreenDown((this.stream: any));
+  }
+  setCursorPosition(x: number, y: number) {
+    readline.cursorTo((this.stream: any), x, y);
+  }
+}