feat: improve types event emitter & global aliases

Author: cpreston321

examples/basic/index.ts

@@ -7,6 +7,14 @@ async function main() {
 
 	await setTimeout(1000);
 
+	p.setGlobalAliases([
+		['w', 'up'],
+		['s', 'down'],
+		['a', 'left'],
+		['d', 'right'],
+		['escape', 'cancel'],
+	]);
+
 	p.intro(`${color.bgCyan(color.black(' create-app '))}`);
 
 	const project = await p.group(

packages/core/src/index.ts

@@ -2,9 +2,8 @@ export { default as ConfirmPrompt } from './prompts/confirm';
 export { default as GroupMultiSelectPrompt } from './prompts/group-multiselect';
 export { default as MultiSelectPrompt } from './prompts/multi-select';
 export { default as PasswordPrompt } from './prompts/password';
-export { default as Prompt, isCancel } from './prompts/prompt';
-export type { State } from './prompts/prompt';
+export { default as Prompt, isCancel, type State } from './prompts/prompt';
 export { default as SelectPrompt } from './prompts/select';
 export { default as SelectKeyPrompt } from './prompts/select-key';
 export { default as TextPrompt } from './prompts/text';
-export { block } from './utils';
+export { block, setGlobalAliases } from './utils';

packages/core/src/prompts/prompt.ts

@@ -7,6 +7,8 @@ import { WriteStream } from 'node:tty';
 import { cursor, erase } from 'sisteransi';
 import wrap from 'wrap-ansi';
 
+import { type InferSetType, aliases, keys, hasAliasKey } from '../utils';
+
 function diffLines(a: string, b: string) {
 	if (a === b) return;
 
@@ -30,14 +32,6 @@ function setRawMode(input: Readable, value: boolean) {
 	if ((input as typeof stdin).isTTY) (input as typeof stdin).setRawMode(value);
 }
 
-const aliases = new Map([
-	['k', 'up'],
-	['j', 'down'],
-	['h', 'left'],
-	['l', 'right'],
-]);
-const keys = new Set(['up', 'down', 'left', 'right', 'space', 'enter']);
-
 export interface PromptOptions<Self extends Prompt> {
 	render(this: Omit<Self, 'prompt'>): string | void;
 	placeholder?: string;
@@ -50,23 +44,49 @@ export interface PromptOptions<Self extends Prompt> {
 
 export type State = 'initial' | 'active' | 'cancel' | 'submit' | 'error';
 
+/**
+ * Typed event emitter for clack
+ */
+interface ClackHooks {
+	'initial': (value?: any) => void;
+	'active': (value?: any) => void;
+	'cancel': (value?: any) => void;
+	'submit': (value?: any) => void;
+	'error': (value?: any) => void;
+	'cursor': (key?: InferSetType<typeof keys>) => void;
+	'key': (key?: string) => void;
+	'value': (value?: string) => void;
+	'confirm': (value?: boolean) => void;
+	'finalize': () => void;
+}
+
 export default class Prompt {
 	protected input: Readable;
 	protected output: Writable;
+
 	private rl!: ReadLine;
 	private opts: Omit<PromptOptions<Prompt>, 'render' | 'input' | 'output'>;
-	private _track: boolean = false;
 	private _render: (context: Omit<Prompt, 'prompt'>) => string | void;
-	protected _cursor: number = 0;
+	private _track = false;
+	private _prevFrame = '';
+	private _subscribers = new Map<string, { cb: (...args: any) => any; once?: boolean }[]>();
+	protected _cursor = 0;
 
 	public state: State = 'initial';
+	public error = '';
 	public value: any;
-	public error: string = '';
 
 	constructor(
-		{ render, input = stdin, output = stdout, ...opts }: PromptOptions<Prompt>,
+		options: PromptOptions<Prompt>,
 		trackValue: boolean = true
 	) {
+		const {
+			input = stdin,
+			output = stdout,
+			render,
+			...opts
+		} = options;
+
 		this.opts = opts;
 		this.onKeypress = this.onKeypress.bind(this);
 		this.close = this.close.bind(this);
@@ -78,6 +98,63 @@ export default class Prompt {
 		this.output = output;
 	}
 
+	/**
+	 * Unsubscribe all listeners
+	 */
+	protected unsubscribe() {
+		this._subscribers.clear();
+	}
+
+	/**
+	 * Set a subscriber with opts
+	 * @param event - The event name
+	 */
+	private setSubscriber<T extends keyof ClackHooks>(event: T, opts: { cb: ClackHooks[T]; once?: boolean }) {
+		const params = this._subscribers.get(event) ?? [];
+		params.push(opts);
+		this._subscribers.set(event, params);
+	}
+
+	/**
+	 * Subscribe to an event
+	 * @param event - The event name
+	 * @param cb - The callback
+	 */
+	public on<T extends keyof ClackHooks>(event: T, cb: ClackHooks[T]) {
+		this.setSubscriber(event, { cb });
+	}
+
+	/**
+	 * Subscribe to an event once
+	 * @param event - The event name
+	 * @param cb - The callback
+	 */
+	public once<T extends keyof ClackHooks>(event: T, cb: ClackHooks[T]) {
+		this.setSubscriber(event, { cb, once: true });
+	}
+
+	/**
+	 * Emit an event with data
+	 * @param event - The event name
+	 * @param data - The data to pass to the callback
+	 */
+	public emit<T extends keyof ClackHooks>(event: T, ...data: Parameters<ClackHooks[T]>) {
+		const cbs = this._subscribers.get(event) ?? [];
+		const cleanup: (() => void)[] = [];
+
+		for (const subscriber of cbs) {
+			subscriber.cb(...data);
+
+			if (subscriber.once) {
+				cleanup.push(() => cbs.splice(cbs.indexOf(subscriber), 1));
+			}
+		}
+
+		for (const cb of cleanup) {
+			cb();
+		}
+	}
+
 	public prompt() {
 		const sink = new WriteStream(0);
 		sink._write = (chunk, encoding, done) => {
@@ -125,43 +202,15 @@ export default class Prompt {
 		});
 	}
 
-	private subscribers = new Map<string, { cb: (...args: any) => any; once?: boolean }[]>();
-	public on(event: string, cb: (...args: any) => any) {
-		const arr = this.subscribers.get(event) ?? [];
-		arr.push({ cb });
-		this.subscribers.set(event, arr);
-	}
-	public once(event: string, cb: (...args: any) => any) {
-		const arr = this.subscribers.get(event) ?? [];
-		arr.push({ cb, once: true });
-		this.subscribers.set(event, arr);
-	}
-	public emit(event: string, ...data: any[]) {
-		const cbs = this.subscribers.get(event) ?? [];
-		const cleanup: (() => void)[] = [];
-		for (const subscriber of cbs) {
-			subscriber.cb(...data);
-			if (subscriber.once) {
-				cleanup.push(() => cbs.splice(cbs.indexOf(subscriber), 1));
-			}
-		}
-		for (const cb of cleanup) {
-			cb();
-		}
-	}
-	private unsubscribe() {
-		this.subscribers.clear();
-	}
-
 	private onKeypress(char: string, key?: Key) {
 		if (this.state === 'error') {
 			this.state = 'active';
 		}
 		if (key?.name && !this._track && aliases.has(key.name)) {
 			this.emit('cursor', aliases.get(key.name));
 		}
-		if (key?.name && keys.has(key.name)) {
-			this.emit('cursor', key.name);
+		if (key?.name && keys.has(key.name as InferSetType<typeof keys>)) {
+			this.emit('cursor', key.name as InferSetType<typeof keys>);
 		}
 		if (char && (char.toLowerCase() === 'y' || char.toLowerCase() === 'n')) {
 			this.emit('confirm', char.toLowerCase() === 'y');
@@ -189,7 +238,8 @@ export default class Prompt {
 				this.state = 'submit';
 			}
 		}
-		if (char === '\x03') {
+
+		if (hasAliasKey([key?.name, key?.sequence], 'cancel')) {
 			this.state = 'cancel';
 		}
 		if (this.state === 'submit' || this.state === 'cancel') {
@@ -217,7 +267,6 @@ export default class Prompt {
 		this.output.write(cursor.move(-999, lines * -1));
 	}
 
-	private _prevFrame = '';
 	private render() {
 		const frame = wrap(this._render(this) ?? '', process.stdout.columns, { hard: true });
 		if (frame === this._prevFrame) return;

packages/core/src/utils/aliases.ts

@@ -0,0 +1,45 @@
+
+export type InferSetType<T> = T extends Set<infer U> ? U : never;
+
+const DEFAULT_KEYS = ['up', 'down', 'left', 'right', 'space', 'enter', 'cancel'] as const;
+export const keys = new Set(DEFAULT_KEYS);
+
+export const aliases = new Map<string, InferSetType<typeof keys>>([
+	['k', 'up'],
+	['j', 'down'],
+	['h', 'left'],
+	['l', 'right'],
+	['\x03', 'cancel'],
+]);
+
+/**
+ * Set custom global aliases for the default keys - This will not overwrite existing aliases just add new ones
+ *
+ * @param aliases - A map of aliases to keys
+ * @default
+ * new Map([['k', 'up'], ['j', 'down'], ['h', 'left'], ['l', 'right'], ['\x03', 'cancel'],])
+ */
+export function setGlobalAliases(alias: Array<[string, InferSetType<typeof keys>]>) {
+	for (const [newAlias, key] of alias) {
+		if (!aliases.has(newAlias)) {
+			aliases.set(newAlias, key);
+		}
+	}
+}
+
+/**
+ * Check if a key is an alias for a default key
+ * @param key - The key to check for
+ * @param type - The type of key to check for
+ * @returns boolean
+ */
+export function hasAliasKey(key: string | Array<string | undefined>, type: InferSetType<typeof keys>) {
+	if (typeof key === 'string') {
+		return aliases.has(key) && aliases.get(key) === type;
+	}
+
+	return key.map((n) => {
+		if (n !== undefined && aliases.has(n) && aliases.get(n) === type) return true;
+		return false;
+	}).includes(true);
+}

packages/core/src/utils.ts packages/core/src/utils/index.tspackages/core/src/utils.ts renamed to packages/core/src/utils/index.ts

@@ -3,6 +3,7 @@ import type { Key } from 'node:readline';
 import { stdin, stdout } from 'node:process';
 import * as readline from 'node:readline';
 import { cursor } from 'sisteransi';
+import { hasAliasKey } from './aliases';
 
 const isWindows = globalThis.process.platform.startsWith('win');
 
@@ -21,16 +22,16 @@ export function block({
 	readline.emitKeypressEvents(input, rl);
 	if (input.isTTY) input.setRawMode(true);
 
-	const clear = (data: Buffer, { name }: Key) => {
+	const clear = (data: Buffer, { name, sequence }: Key) => {
 		const str = String(data);
-		if (str === '\x03') {
+		if (hasAliasKey([str, name, sequence], 'cancel')) {
 			if (hideCursor) output.write(cursor.show);
 			process.exit(0);
 			return;
 		}
 		if (!overwrite) return;
-		let dx = name === 'return' ? 0 : -1;
-		let dy = name === 'return' ? -1 : 0;
+		const dx = name === 'return' ? 0 : -1;
+		const dy = name === 'return' ? -1 : 0;
 
 		readline.moveCursor(output, dx, dy, () => {
 			readline.clearLine(output, 1, () => {
@@ -53,3 +54,5 @@ export function block({
 		rl.close();
 	};
 }
+
+export * from './aliases';

packages/prompts/src/index.ts

@@ -14,7 +14,7 @@ import isUnicodeSupported from 'is-unicode-supported';
 import color from 'picocolors';
 import { cursor, erase } from 'sisteransi';
 
-export { isCancel } from '@clack/core';
+export { isCancel, setGlobalAliases } from '@clack/core';
 
 const unicode = isUnicodeSupported();
 const s = (c: string, fallback: string) => (unicode ? c : fallback);