@j-o-r/sh 1.1.31 → 1.2.0

package/types/internal.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Per-`within()`-block option overrides.
+ *
+ * A plain object keyed by option name. A key present in the store shadows the
+ * global default for every command created inside the `within()` block; a key
+ * absent from the store inherits the enclosing scope (or the global default).
+ */
+export type OptionScopeStore = {
+    [x: string]: any;
+};
+/**
+ * Default options applied to all SH commands unless overridden.
+ *
+ * `cwd` is intentionally lazy: the getter resolves `process.cwd()` at read
+ * time, so commands created after a `cd()` run in the new directory instead of
+ * the directory the process was started in. `SHDispatch` spreads these
+ * defaults (`{ ...defaultOptions }`) per command, which invokes the getters and
+ * freezes the values for that command — "defaults captured at creation time".
+ * Do not "optimize" this into a static snapshot.
+ *
+ * Every getter/setter is scope-aware: inside a `within()` block it reads/writes
+ * the block's scoped override (see {@link optionScope}); outside it reads/writes
+ * the global default. An explicit `SH.cwd = dir` assignment takes precedence
+ * over `process.cwd()` (it only redirects SH commands; it does not `chdir` the
+ * process). `cd()` clears the override again, so the most recent of the two
+ * always wins.
+ *
+ * @type {import('./SHDispatch.js').SHOptions}
+ */
+export const defaultOptions: import("./SHDispatch.js").SHOptions;
+/**
+ * Known global option keys exposed by the `SH` proxy in `lib/SH.js`.
+ *
+ * Derived from the own keys of {@link defaultOptions}, so the key set can
+ * never drift from the defaults. (The previous hard-coded list in `lib/SH.js`
+ * readable-exposed `maxBuffer`/`detached`, which were uninitialized in the
+ * defaults.) The proxy routes reads/writes for these keys to
+ * `defaultOptions` and throws a `TypeError` on writes to any other key
+ * (decision D1).
+ *
+ * @type {Set<string>}
+ */
+export const defaultOptionKeys: Set<string>;
+/**
+ * Clears the `SH.cwd` override so the lazy `cwd` getter follows
+ * `process.cwd()` again. Called by `cd()` after a successful
+ * `process.chdir()`.
+ */
+export function clearCwdOverride(): void;
+/**
+ * Default maximum buffered bytes per stdout/stderr stream: 512000 (500 KiB).
+ * Used by `SHExecute` when `options.maxBuffer` is unset or invalid.
+ */
+export const DEFAULT_MAX_BUFFER: number;
+/**
+ * Parses a human-readable duration into milliseconds.
+ *
+ * Accepts finite non-negative numbers (milliseconds) and strings in the exact
+ * forms `'Nms'`, `'Ns'`, or a bare `'N'`. The bare-number form is treated as
+ * milliseconds on purpose: it preserves the leniency of the former `SHExecute`
+ * parser, so e.g. `timeout: '100'` keeps working.
+ *
+ * `null`/`undefined` are not special-cased here; call sites that allow an
+ * absent duration handle it themselves (e.g. `parseDuration(timeout ?? 0)`).
+ *
+ * @param {number|string} d - Duration as number (ms) or string ('5s', '100ms', '100').
+ * @returns {number} Duration in milliseconds.
+ * @throws {Error} If the duration type or format is invalid.
+ */
+export function parseDuration(d: number | string): number;
+/**
+ * Per-`within()`-block option overrides.
+ *
+ * A plain object keyed by option name. A key present in the store shadows the
+ * global default for every command created inside the `within()` block; a key
+ * absent from the store inherits the enclosing scope (or the global default).
+ *
+ * @typedef {Object<string, any>} OptionScopeStore
+ */
+/**
+ * AsyncLocalStorage backing `within()` scoping (decision D2).
+ *
+ * `within()` runs its callback inside a fresh store seeded with a shallow copy
+ * of the enclosing store, so nested blocks inherit their parent's scoped
+ * values but never leak their own assignments outward. `getDefault`/`setDefault`
+ * consult the current store first and fall back to the global defaults.
+ *
+ * @type {AsyncLocalStorage<OptionScopeStore>}
+ */
+export const optionScope: AsyncLocalStorage<OptionScopeStore>;
+import { AsyncLocalStorage } from 'node:async_hooks';

package/TODO.md

@@ -1,8 +0,0 @@
-# TODOs for @j-o-r/sh project
-
-## lib/SH.js review findings (2026-06-26)
-
-## In Progress
-
-## Done
-