From 770c84686468686762e61f2a733c70dfe63efe62 Mon Sep 17 00:00:00 2001 From: Anton Golub Date: Tue, 10 Dec 2024 00:02:48 +0300 Subject: [PATCH] docs: improve jsr docs refs --- src/main/ts/error.ts | 13 +++++++++++++ src/main/ts/index.ts | 15 +++++++++++++++ src/main/ts/spawn.ts | 21 +++++++++++++++++++++ src/main/ts/util.ts | 13 +++++++++++++ src/main/ts/zurk.ts | 15 +++++++++++++++ src/scripts/build-jsr.mjs | 5 ++++- src/test/ts/util.test.ts | 6 +++++- target/dts/error.d.ts | 12 ++++++++++++ target/dts/index.d.ts | 14 ++++++++++++++ target/dts/spawn.d.ts | 20 ++++++++++++++++++++ target/dts/util.d.ts | 12 ++++++++++++ target/dts/zurk.d.ts | 13 +++++++++++++ 12 files changed, 157 insertions(+), 2 deletions(-) diff --git a/src/main/ts/error.ts b/src/main/ts/error.ts index 698be75..c8228ec 100644 --- a/src/main/ts/error.ts +++ b/src/main/ts/error.ts @@ -1,3 +1,16 @@ +/** + * @module zurk/error + * + * Zurk spawn error codes & handling utilities + * + * @example + * ```ts + * import {EXIT_CODES} from 'zurk/error' + * + * console.log(EXIT_CODES[2]) // 'Misuse of shell builtins' + * ``` + */ + export const EXIT_CODES = { 2: 'Misuse of shell builtins', 126: 'Invoked command cannot execute', diff --git a/src/main/ts/index.ts b/src/main/ts/index.ts index d7f9ac6..b9384be 100644 --- a/src/main/ts/index.ts +++ b/src/main/ts/index.ts @@ -6,3 +6,18 @@ export { invoke, exec, defaults } from './spawn.js' export { $ } from './x.js' export { zurk } from './zurk.js' export { type Promisified, buildCmd } from './util.js' + +/** + * @module zurk + * + * A generic process spawner + * + * @example + * ```ts + * import {$, exec, zurk} from 'zurk' + * + * const r1 = exec({sync: true, cmd: 'echo foo'}) + * const r2 = await zurk({sync: false, cmd: 'echo foo'}) + * const r3 = await $`echo foo` + * ``` + */ diff --git a/src/main/ts/spawn.ts b/src/main/ts/spawn.ts index 2d924e3..5b89f3e 100644 --- a/src/main/ts/spawn.ts +++ b/src/main/ts/spawn.ts @@ -4,6 +4,27 @@ import EventEmitter from 'node:events' import { Readable, Writable, Stream, Transform } from 'node:stream' import { assign, noop, randomId, g, immediate } from './util.js' +/** + * @module zurk/spawn + * + * Zurk internal child_process caller API + * + * @example + * ```ts + * import {invoke, normalizeCtx, TSpawnCtx} from 'zurk/spawn' + * + * const results: string[] = [] + * const callback: TSpawnCtx['callback'] = (_err, result) => results.push(result.stdout) + * + * invoke(normalizeCtx({ + * sync: true, + * cmd: 'echo', + * args: ['hello'], + * callback, + * })) + * ``` + */ + export * from './util.js' export type TSpawnError = any diff --git a/src/main/ts/util.ts b/src/main/ts/util.ts index 1c698e5..3bd8bff 100644 --- a/src/main/ts/util.ts +++ b/src/main/ts/util.ts @@ -2,6 +2,19 @@ import { Stream } from 'node:stream' import process from 'node:process' import { Buffer } from 'node:buffer' +/** + * @module zurk/util + * + * Zurk utility functions + * + * @example + * ```ts + * import {randomId} from 'zurk/util' + * + * randomId() // 'kdrx9bngrb' + * ``` + */ + export const g = (!process.versions.deno && global) || globalThis export const immediate = g.setImmediate || ((f: any): NodeJS.Timeout => g.setTimeout(f, 0)) diff --git a/src/main/ts/zurk.ts b/src/main/ts/zurk.ts index d9ea9e4..9b0d159 100644 --- a/src/main/ts/zurk.ts +++ b/src/main/ts/zurk.ts @@ -17,6 +17,21 @@ import { formatExitMessage } from './error.js' + +/** + * @module zurk/zurk + * + * Zurk process spawner + * + * @example + * ```ts + * import {zurk} from 'zurk/zurk' + * + * const r1 = zurk({ sync: true, cmd: 'echo', args: ['foo']}) + * const r2 = await zurk({ sync: false, cmd: 'echo', args: ['foo']}) + * ``` + */ + export const ZURK = Symbol('Zurk') export const ZURKPROXY = Symbol('ZurkProxy') diff --git a/src/scripts/build-jsr.mjs b/src/scripts/build-jsr.mjs index 3865f1c..48d9124 100644 --- a/src/scripts/build-jsr.mjs +++ b/src/scripts/build-jsr.mjs @@ -13,6 +13,9 @@ fs.writeFileSync(path.resolve(cwd, 'jsr.json'), JSON.stringify({ './zurk': './src/main/ts/zurk.ts' }, publish: { - include: ['src/main/ts'] + include: [ + 'src/main/ts', + 'README.md' + ] } }, null, 2)) diff --git a/src/test/ts/util.test.ts b/src/test/ts/util.test.ts index 177e7a1..fc3293c 100644 --- a/src/test/ts/util.test.ts +++ b/src/test/ts/util.test.ts @@ -1,6 +1,6 @@ import * as assert from 'node:assert' import {describe, it, test} from 'node:test' -import { assign, isStringLiteral } from '../../main/ts/util.js' +import { assign, isStringLiteral, randomId } from '../../main/ts/util.js' import tslib from 'tslib' describe('util', () => { @@ -9,6 +9,10 @@ describe('util', () => { assert.deepEqual(assign({a: 1}, {a: undefined}), {a: 1}) }) + it('randomId()', () => { + assert.match(randomId(), /^[\da-z]+$/) + }) + test('isStringLiteral()', () => { const bar = 'baz' assert.ok(isStringLiteral``) diff --git a/target/dts/error.d.ts b/target/dts/error.d.ts index 8c40b9d..129207c 100644 --- a/target/dts/error.d.ts +++ b/target/dts/error.d.ts @@ -1,3 +1,15 @@ +/** + * @module zurk/error + * + * Zurk spawn error codes & handling utilities + * + * @example + * ```ts + * import {EXIT_CODES} from 'zurk/error' + * + * console.log(EXIT_CODES[2]) // 'Misuse of shell builtins' + * ``` + */ export declare const EXIT_CODES: { 2: string; 126: string; diff --git a/target/dts/index.d.ts b/target/dts/index.d.ts index e9f0ca7..dd733b7 100644 --- a/target/dts/index.d.ts +++ b/target/dts/index.d.ts @@ -5,3 +5,17 @@ export { invoke, exec, defaults } from './spawn.js'; export { $ } from './x.js'; export { zurk } from './zurk.js'; export { type Promisified, buildCmd } from './util.js'; +/** + * @module zurk + * + * A generic process spawner + * + * @example + * ```ts + * import {$, exec, zurk} from 'zurk' + * + * const r1 = exec({sync: true, cmd: 'echo foo'}) + * const r2 = await zurk({sync: false, cmd: 'echo foo'}) + * const r3 = await $`echo foo` + * ``` + */ diff --git a/target/dts/spawn.d.ts b/target/dts/spawn.d.ts index c917689..06661b3 100644 --- a/target/dts/spawn.d.ts +++ b/target/dts/spawn.d.ts @@ -1,6 +1,26 @@ import * as cp from 'node:child_process'; import EventEmitter from 'node:events'; import { Readable, Writable, Stream, Transform } from 'node:stream'; +/** + * @module zurk/spawn + * + * Zurk internal child_process caller API + * + * @example + * ```ts + * import {invoke, normalizeCtx, TSpawnCtx} from 'zurk/spawn' + * + * const results: string[] = [] + * const callback: TSpawnCtx['callback'] = (_err, result) => results.push(result.stdout) + * + * invoke(normalizeCtx({ + * sync: true, + * cmd: 'echo', + * args: ['hello'], + * callback, + * })) + * ``` + */ export * from './util.js'; export type TSpawnError = any; export type TPushable = { diff --git a/target/dts/util.d.ts b/target/dts/util.d.ts index 37827fe..3b2d8a2 100644 --- a/target/dts/util.d.ts +++ b/target/dts/util.d.ts @@ -1,5 +1,17 @@ import { Stream } from 'node:stream'; import { Buffer } from 'node:buffer'; +/** + * @module zurk/util + * + * Zurk utility functions + * + * @example + * ```ts + * import {randomId} from 'zurk/util' + * + * randomId() // 'kdrx9bngrb' + * ``` + */ export declare const g: typeof globalThis; export declare const immediate: typeof setImmediate; export declare const noop: () => void; diff --git a/target/dts/zurk.d.ts b/target/dts/zurk.d.ts index c5476fe..23f0167 100644 --- a/target/dts/zurk.d.ts +++ b/target/dts/zurk.d.ts @@ -1,5 +1,18 @@ import { type TSpawnCtxNormalized, type TSpawnResult, type TSpawnListeners } from './spawn.js'; import { type Promisified } from './util.js'; +/** + * @module zurk/zurk + * + * Zurk process spawner + * + * @example + * ```ts + * import {zurk} from 'zurk/zurk' + * + * const r1 = zurk({ sync: true, cmd: 'echo', args: ['foo']}) + * const r2 = await zurk({ sync: false, cmd: 'echo', args: ['foo']}) + * ``` + */ export declare const ZURK: unique symbol; export declare const ZURKPROXY: unique symbol; export interface TZurkOn {