Skip to content
Permalink
Browse files

Add TypeScript definition (#101)

  • Loading branch information...
BendingBender authored and sindresorhus committed Mar 2, 2019
1 parent 3f5ae20 commit 2768e75126bbe328e9efe8d2f6d32e6585eb2e8b
Showing with 280 additions and 4 deletions.
  1. +222 −0 index.d.ts
  2. +4 −1 index.js
  3. +48 −0 index.test-d.ts
  4. +6 −3 package.json
@@ -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;
}
@@ -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');
@@ -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
});
@@ -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"
}
}

0 comments on commit 2768e75

Please sign in to comment.
You can’t perform that action at this time.