Add TypeScript definition (#101)

sindresorhus · Mar 2, 2019 · 2768e75 · 2768e75
1 parent 3f5ae20
commit 2768e75
Show file tree

Hide file tree

Showing 4 changed files with 280 additions and 4 deletions.
diff --git a/index.d.ts b/index.d.ts
@@ -0,0 +1,222 @@
+/// <reference types="node"/>
+import {Writable} from 'stream';
+import {SpinnerName} from 'cli-spinners';
+
+export type Spinner = Readonly<{
+	interval?: number;
+	frames: string[];
+}>;
+
+export type Color =
+	| 'black'
+	| 'red'
+	| 'green'
+	| 'yellow'
+	| 'blue'
+	| 'magenta'
+	| 'cyan'
+	| 'white'
+	| 'gray';
+
+export type Options = Readonly<{
+	/**
+	 * Text to display after the spinner.
+	 */
+	text?: string;
+
+	/**
+	 * Name of one of the provided spinners. See [`example.js`](https://github.com/BendingBender/ora/blob/master/example.js) in this repo if you want to test out different spinners. On Windows, it will always use the line spinner as the Windows command-line doesn't have proper Unicode support.
+	 *
+	 * @default 'dots'
+	 *
+	 * Or an object like:
+	 *
+	 * @example
+	 *
+	 * {
+	 *     interval: 80, // optional
+	 *     frames: ['-', '+', '-']
+	 * }
+	 *
+	 */
+	spinner?: SpinnerName | Spinner;
+
+	/**
+	 * Color of the spinner.
+	 *
+	 * @default 'cyan'
+	 */
+	color?: Color;
+
+	/**
+	 * Set to `false` to stop Ora from hiding the cursor.
+	 *
+	 * @default true
+	 */
+	hideCursor?: boolean;
+
+	/**
+	 * Indent the spinner with the given number of spaces.
+	 *
+	 * @default 0
+	 */
+	indent?: number;
+
+	/**
+	 * Interval between each frame.
+	 *
+	 * Spinners provide their own recommended interval, so you don't really need to specify this. Default value: Provided by the spinner or `100`.
+	 */
+	interval?: number;
+
+	/**
+	 * Stream to write the output.
+	 *
+	 * You could for example set this to `process.stdout` instead.
+	 *
+	 * @default process.stderr
+	 */
+	stream?: Writable;
+
+	/**
+	 * Force enable/disable the spinner. If not specified, the spinner will be enabled if the `stream` is being run inside a TTY context (not spawned or piped) and/or not in a CI environment.
+	 *
+	 * Note that `{isEnabled: false}` doesn't mean it won't output anything. It just means it won't output the spinner, colors, and other ansi escape codes. It will still log text.
+	 */
+	isEnabled?: boolean;
+}>;
+
+/**
+ * Elegant terminal spinner.
+ *
+ * @param options - If a string is provided, it is treated as a shortcut for `options.text`.
+ */
+export default function ora(options?: Options | string): Ora;
+
+/**
+ * Starts a spinner for a promise. The spinner is stopped with `.succeed()` if the promise fulfills or with `.fail()` if it rejects.
+ *
+ * @param action - The promise to start the spinner for.
+ * @param options - If a string is provided, it is treated as a shortcut for `options.text`.
+ * @returns The spinner instance.
+ */
+export function promise(
+	action: PromiseLike<unknown>,
+	options?: Options | string
+): Ora;
+
+export interface PersistOptions {
+	/**
+	 * Symbol to replace the spinner with.
+	 *
+	 * @default ' '
+	 */
+	symbol?: string;
+
+	/**
+	 * Text to be persisted. Default value: Current text.
+	 */
+	text?: string;
+}
+
+export interface Ora {
+	/**
+	 * A boolean of whether the instance is currently spinning.
+	 */
+	readonly isSpinning: boolean;
+
+	/**
+	 * Change the text.
+	 */
+	text: string;
+
+	/**
+	 * Change the spinner color.
+	 */
+	color: Color;
+
+	/**
+	 * Change the spinner.
+	 */
+	spinner: SpinnerName | Spinner;
+
+	/**
+	 * Change the spinner indent.
+	 */
+	indent: number;
+
+	/**
+	 * Start the spinner.
+	 *
+	 * @param text - Set the current text.
+	 * @returns The spinner instance.
+	 */
+	start(text?: string): Ora;
+
+	/**
+	 * Stop and clear the spinner.
+	 *
+	 * @returns The spinner instance.
+	 */
+	stop(): Ora;
+
+	/**
+	 * Stop the spinner, change it to a green `✔` and persist the current text, or `text` if provided.
+	 *
+	 * @param text - Will persist text if provided.
+	 * @returns The spinner instance.
+	 */
+	succeed(text?: string): Ora;
+
+	/**
+	 * Stop the spinner, change it to a red `✖` and persist the current text, or `text` if provided.
+	 *
+	 * @param text - Will persist text if provided.
+	 * @returns The spinner instance.
+	 */
+	fail(text?: string): Ora;
+
+	/**
+	 * Stop the spinner, change it to a yellow `⚠` and persist the current text, or `text` if provided.
+	 *
+	 * @param text - Will persist text if provided.
+	 * @returns The spinner instance.
+	 */
+	warn(text?: string): Ora;
+
+	/**
+	 * Stop the spinner, change it to a blue `ℹ` and persist the current text, or `text` if provided.
+	 *
+	 * @param text - Will persist text if provided.
+	 * @returns The spinner instance.
+	 */
+	info(text?: string): Ora;
+
+	/**
+	 * Stop the spinner and change the symbol or text.
+	 *
+	 * @returns The spinner instance.
+	 */
+	stopAndPersist(options?: PersistOptions): Ora;
+
+	/**
+	 * Clear the spinner.
+	 *
+	 * @returns The spinner instance.
+	 */
+	clear(): Ora;
+
+	/**
+	 * Manually render a new frame.
+	 *
+	 * @returns The spinner instance.
+	 */
+	render(): Ora;
+
+	/**
+	 * Get a new frame.
+	 *
+	 * @returns The spinner instance.
+	 */
+	frame(): Ora;
+}
diff --git a/index.js b/index.js
@@ -194,10 +194,13 @@ class Ora {
 	}
 }
 
-module.exports = function (opts) {
+const oraFactory = function (opts) {
 	return new Ora(opts);
 };
 
+module.exports = oraFactory;
+module.exports.default = oraFactory;
+
 module.exports.promise = (action, options) => {
 	if (typeof action.then !== 'function') {
 		throw new TypeError('Parameter `action` must be a Promise');

diff --git a/index.test-d.ts b/index.test-d.ts
@@ -0,0 +1,48 @@
+import {expectType} from 'tsd-check';
+import {PassThrough} from 'stream';
+import ora, {promise} from '.';
+
+const spinner = ora('Loading unicorns');
+ora({text: 'Loading unicorns'});
+ora({spinner: 'squish'});
+ora({spinner: {frames: ['-', '+', '-']}});
+ora({spinner: {interval: 80, frames: ['-', '+', '-']}});
+ora({color: 'cyan'});
+ora({hideCursor: true});
+ora({indent: 1});
+ora({interval: 80});
+ora({stream: new PassThrough()});
+ora({isEnabled: true});
+
+spinner.color = 'yellow';
+spinner.text = 'Loading rainbows';
+expectType<boolean>(spinner.isSpinning);
+spinner.spinner = 'dots';
+spinner.indent = 5;
+
+spinner.start();
+spinner.start('Test text');
+spinner.stop();
+spinner.succeed();
+spinner.succeed('fooed');
+spinner.fail();
+spinner.fail('failed to foo');
+spinner.warn();
+spinner.warn('warn foo');
+spinner.info();
+spinner.info('info foo');
+spinner.stopAndPersist();
+spinner.stopAndPersist({text: 'all done'});
+spinner.stopAndPersist({symbol: '@', text: 'all done'});
+spinner.clear();
+spinner.render();
+spinner.frame();
+
+const resolves = Promise.resolve(1);
+promise(resolves, 'foo');
+promise(resolves, {
+	stream: new PassThrough(),
+	text: 'foo',
+	color: 'blue',
+	isEnabled: true
+});
diff --git a/package.json b/package.json
@@ -13,10 +13,11 @@
 		"node": ">=6"
 	},
 	"scripts": {
-		"test": "xo && ava"
+		"test": "xo && ava && tsd-check"
 	},
 	"files": [
-		"index.js"
+		"index.js",
+		"index.d.ts"
 	],
 	"keywords": [
 		"cli",
@@ -37,14 +38,16 @@
 	"dependencies": {
 		"chalk": "^2.4.2",
 		"cli-cursor": "^2.1.0",
-		"cli-spinners": "^1.3.1",
+		"cli-spinners": "^2.0.0",
 		"log-symbols": "^2.2.0",
 		"strip-ansi": "^5.0.0",
 		"wcwidth": "^1.0.1"
 	},
 	"devDependencies": {
+		"@types/node": "^11.9.5",
 		"ava": "^1.2.1",
 		"get-stream": "^4.1.0",
+		"tsd-check": "^0.3.0",
 		"xo": "^0.24.0"
 	}
 }