Skip to content

Commit

Permalink
docs: improve jsr docs refs
Browse files Browse the repository at this point in the history
  • Loading branch information
antongolub committed Dec 9, 2024
1 parent 794d08c commit 254fac7
Show file tree
Hide file tree
Showing 12 changed files with 157 additions and 2 deletions.
13 changes: 13 additions & 0 deletions src/main/ts/error.ts
Original file line number Diff line number Diff line change
@@ -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',
Expand Down
15 changes: 15 additions & 0 deletions src/main/ts/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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`
* ```
*/
21 changes: 21 additions & 0 deletions src/main/ts/spawn.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
13 changes: 13 additions & 0 deletions src/main/ts/util.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
15 changes: 15 additions & 0 deletions src/main/ts/zurk.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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')

Expand Down
5 changes: 4 additions & 1 deletion src/scripts/build-jsr.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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))
6 changes: 5 additions & 1 deletion src/test/ts/util.test.ts
Original file line number Diff line number Diff line change
@@ -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', () => {
Expand All @@ -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``)
Expand Down
12 changes: 12 additions & 0 deletions target/dts/error.d.ts
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
14 changes: 14 additions & 0 deletions target/dts/index.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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`
* ```
*/
20 changes: 20 additions & 0 deletions target/dts/spawn.d.ts
Original file line number Diff line number Diff line change
@@ -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> = {
Expand Down
12 changes: 12 additions & 0 deletions target/dts/util.d.ts
Original file line number Diff line number Diff line change
@@ -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;
Expand Down
13 changes: 13 additions & 0 deletions target/dts/zurk.d.ts
Original file line number Diff line number Diff line change
@@ -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> {
Expand Down

0 comments on commit 254fac7

Please sign in to comment.