docs: add jsdocs

src/main/ts/error.ts

@@ -1,5 +1,5 @@
 /**
- * @module zurk/error
+ * @module
  *
  * Zurk spawn error codes & handling utilities
  *

src/main/ts/index.ts

@@ -8,7 +8,7 @@ export { zurk } from './zurk.js'
 export { type Promisified, buildCmd } from './util.js'
 
 /**
- * @module zurk
+ * @module
  *
  * A generic process spawner
  *

src/main/ts/mixin/kill.ts

@@ -4,6 +4,12 @@ import { assign } from '../util.js'
 import type { TMixin, TShell, TShellCtx } from '../x.js'
 import { type TZurk, type TZurkPromise, isZurkAny } from '../zurk.js'
 
+/**
+ * @module
+ *
+ * Zurk $ pipe mixin
+ */
+
 // https://github.com/nodejs/node/issues/37518
 // https://github.com/nodejs/node/issues/46865
 const kill = (child?: ChildProcess, signal: null | string | number | NodeJS.Signals = 'SIGTERM') => new Promise<typeof signal>((resolve, reject) => {

src/main/ts/mixin/pipe.ts

@@ -4,6 +4,12 @@ import { VoidStream } from '../spawn.js'
 import type { TShell, TMixin, TShellCtx } from '../x.js'
 import { type TZurk, type TZurkPromise, isZurkAny } from '../zurk.js'
 
+/**
+ * @module
+ *
+ * Zurk $ pipe mixin
+ */
+
 // eslint-disable-next-line sonarjs/cognitive-complexity
 export const pipeMixin: TMixin = <T extends TZurk | TZurkPromise >($: TShell, result: T, ctx: TShellCtx) =>
   isZurkAny(result)

src/main/ts/mixin/timeout.ts

@@ -3,6 +3,12 @@ import { assign, pFinally } from '../util.js'
 import type { TMixin, TShell, TShellCtx } from '../x.js'
 import { type TZurk, type TZurkPromise, isZurkPromise } from '../zurk.js'
 
+/**
+ * @module
+ *
+ * Zurk $ timeout mixin
+ */
+
 const attachTimeout = <T extends TZurkPromise & { kill?: (signal: NodeJS.Signals) => void }>(
   ctx: TShellCtx,
   result: T

src/main/ts/spawn.ts

@@ -6,7 +6,7 @@ import { Readable, Writable, Stream, Transform } from 'node:stream'
 import { assign, noop, randomId, g, immediate } from './util.js'
 
 /**
- * @module zurk/spawn
+ * @module
  *
  * Zurk internal child_process caller API
  *
@@ -105,6 +105,9 @@ export interface TSpawnCtxNormalized {
   stack:      string
 }
 
+/**
+ * zurk default settings
+ */
 export const defaults: TSpawnCtxNormalized = {
   get id()    { return randomId() },
   cmd:        '',
@@ -132,11 +135,22 @@ export const defaults: TSpawnCtxNormalized = {
   stack:      ''
 }
 
+/**
+ * Normalizes spawn context.
+ *
+ * @param ctxs Contexts to normalize
+ * @returns
+ */
 export const normalizeCtx = (...ctxs: TSpawnCtx[]): TSpawnCtxNormalized => assign({
   ...defaults,
   get signal() { return this.ac?.signal }},
   ...ctxs)
 
+/**
+ * Redirects input to child process stdin
+ * @param child
+ * @param input
+ */
 export const processInput = (child: TChild, input?: TInput | null): void => {
   if (input && child.stdin && !child.stdin.destroyed) {
     if (input instanceof Stream) {
@@ -148,13 +162,21 @@ export const processInput = (child: TChild, input?: TInput | null): void => {
   }
 }
 
+/**
+ * Transformer that emits data but does not consume it.
+ */
 export class VoidStream extends Transform {
   _transform(chunk: any, _: string, cb: (err?: Error) => void) {
     this.emit('data', chunk)
     cb()
   }
 }
 
+/**
+ * Builds spawn options
+ * @param ctx
+ * @returns spawn options
+ */
 export const buildSpawnOpts = ({spawnOpts, stdio, cwd, shell, input, env, detached, signal}: TSpawnCtxNormalized) => ({
   ...spawnOpts,
   env,
@@ -167,6 +189,12 @@ export const buildSpawnOpts = ({spawnOpts, stdio, cwd, shell, input, env, detach
   signal
 })
 
+/**
+ * Toggles event listeners
+ * @param pos 'on' | 'off'
+ * @param ee EventEmitter
+ * @param on listeners map
+ */
 export const toggleListeners = (pos: 'on' | 'off', ee: EventEmitter, on: Partial<TSpawnListeners> = {}): void => {
   for (const [name, listener] of Object.entries(on)) {
     ee[pos](name, listener as any)
@@ -175,12 +203,20 @@ export const toggleListeners = (pos: 'on' | 'off', ee: EventEmitter, on: Partial
     ee.once('end', () => toggleListeners('off', ee, on))
 }
 
+/**
+ * Creates a new spawn store
+ */
 export const createStore = (): TSpawnStore => ({
   stdout: [],
   stderr: [],
   stdall: [],
 })
 
+/**
+ * Invokes a child process
+ * @param c Normalized context.
+ * @returns Normalized context.
+ */
 // eslint-disable-next-line sonarjs/cognitive-complexity
 export const invoke = (c: TSpawnCtxNormalized): TSpawnCtxNormalized => {
   const now = Date.now()
@@ -296,6 +332,11 @@ export const invoke = (c: TSpawnCtxNormalized): TSpawnCtxNormalized => {
   return c
 }
 
+/**
+ * Executes a child process
+ * @param ctx TSpawnCtx
+ * @returns TSpawnCtxNormalized
+ */
 export const exec = (ctx: TSpawnCtx): TSpawnCtxNormalized => invoke(normalizeCtx(ctx))
 
 // https://2ality.com/2018/05/child-process-streams.html

src/main/ts/util.ts

@@ -3,7 +3,7 @@ import process from 'node:process'
 import { Buffer } from 'node:buffer'
 
 /**
- * @module zurk/util
+ * @module
  *
  * Zurk utility functions
  *

src/main/ts/x.ts

@@ -26,6 +26,20 @@ import { pipeMixin } from './mixin/pipe.js'
 import { killMixin } from './mixin/kill.js'
 import { timeoutMixin } from './mixin/timeout.js'
 
+
+/**
+ * @module
+ *
+ * Zurk $ API
+ *
+ * @example
+ * ```ts
+ * import {$} from 'zurk/x'
+ *
+ * const p = await $`echo foo`'
+ * ```
+ */
+
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface TShellCtxExtra {
 }
@@ -88,6 +102,12 @@ export interface TShellSync {
   (opts: TShellOptions): TShellSync
 }
 
+/**
+ * Zurk $ template API
+ *
+ * @param pieces
+ * @param args
+ */
 export const $: TShell = function(this: any, pieces?: any, ...args: any): any {
   const self =  (this !== g) && this
   const preset = self || {}
@@ -125,6 +145,13 @@ const zurkMixin: TMixin = ($: TShell, target: TShellOptions | TZurk | TZurkPromi
 
 $.mixins = [zurkMixin, killMixin, pipeMixin, timeoutMixin]
 
+/**
+ * Applies mixins to the result.
+ * @param $
+ * @param result
+ * @param parent
+ * @returns TZurk | TZurkPromise | TShellOptions
+ */
 export const applyMixins = ($: TShell, result: TZurk | TZurkPromise | TShellOptions, parent?: TZurk | TZurkPromise): TZurk | TZurkPromise | TShellOptions => {
   let ctx: TShellCtx = (parent as TZurkPromise | TZurk)?.ctx
 

src/main/ts/zurk.ts

@@ -19,7 +19,7 @@ import {
 
 
 /**
- * @module zurk/zurk
+ * @module
  *
  * Zurk process spawner
  *