docs: improve jsr docs refs

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',

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`
+ * ```
+ */

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

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))

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')
 

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))

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``)

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;

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`
+ * ```
+ */

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<T = any> = {

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;

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<R> {