# fynjs

> fyn is a fast node.js package manager. fynpo is a zero setup monorepo manager built on it. fynjs is their monorepo, plus the small packages they are built from.

<!-- fyn v3.2.3: https://fynjs.pages.dev/ref/fyn.md -->

# fyn reference

`fyn` is a Node.js package manager CLI. It installs from the npm registry and from local directories, links local packages by hardlinking their packed files, can keep one copy of each package in a central store, and runs as the installer for fynpo monorepos. It is a command line tool. The package has no documented JS API.

## Binaries and requirements

| Binary | Behavior |
| --- | --- |
| `fyn` | The CLI. |
| `fun` | Shortcut for `fyn run`: `fun <script> [args]` is `fyn run <script> [args]`. Exits 0 on success and 1 on any rejection. |
| `0-npx-please-run-this-for-fyn` | Same entry as `fyn`. |

- Requires Node `>= 22.22.2`. An older Node prints `fyn requires node >= 22.22.2, and this is <version>.` and exits 1 before loading the bundle.
- `fyn` enables the V8 compile cache. `NODE_DISABLE_COMPILE_CACHE=1` turns it off and `NODE_COMPILE_CACHE` moves it. Both are Node variables.
- The package exports a programmatic entry (`run`, `fun`, `getAuditFilePath` from `bin/index.mjs`) that loads `dist/fyn.mjs` on first call. It is the CLI entry, not a library API.

## Invocation rules

```
fyn [options] <command> [command options] [args]
```

- No command: runs `install`. `fyn --verbose` and `fyn --fi` are installs.
- A first word that is not a command is treated as `fyn run <word>`. `fyn build` runs the `build` script.
- Global options (the table below) can be given before or after the command name.
- Boolean options take `<flag boolean>`. `--name`, `--name=true` and `--no-name` all work. Names are kebab-case on the command line and camelCase in rc files.
- `-- <args>` after `run` passes the remaining args to the script.
- `fyn --help` prints help. `fyn --version` prints the version.
- A parse error prints the error and leaves exit code 1 (the bin wrapper calls `process.exit()` with no argument, so a code already set is kept).

## Commands

Aliases are in parentheses. Command options are listed with each command. Global options are in "Global options".

| Command | Purpose |
| --- | --- |
| `install` (`i`) | Resolve, fetch and install dependencies. Default command. |
| `add` (`a`) | Add packages to `package.json`, then install. |
| `remove` (`rm`) | Remove packages from `package.json`, then install. |
| `stat` | Show where an installed package comes from and who depends on it. |
| `outdated` | List direct registry dependencies that have newer versions. |
| `audit` | Check resolved packages for known vulnerabilities. |
| `run` (`rum`, `r`) | Run a `package.json` script. |
| `init` | Create a `package.json`. |
| `install-scripts` | Review and record install script approvals. |
| `prod-prune` | Remove non-runtime files from a production `node_modules`. |
| `sync-local` (`sl`) | Re-link files of local packages. |
| `global` | Install and manage global packages. |

### `install`

```
fyn [install] [options]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--run-npm [scripts..]` | | string list | none | Extra npm scripts to run after install. Not saved to `.fyn.json`. |
| `--force-install` | `--fi` | boolean | false | Install even when no file changed since the last install. |
| `--audit` | | boolean | true | Run a summary audit after install. `--no-audit` skips it. |
| `--audit-file <path>` | | string | none | After install, write the full audit report as JSON. A relative path is relative to the project dir. |
| `--allow-scripts-pending` | | boolean | false | Also record which packages would need approval under policy `review`, without changing what runs. |

Sequence:

1. Load `package.json`, then merge `package-fyn.json` over it (see "Package fyn section").
2. Skip with the message `No changes detected since last fyn install` when all of these hold: not `--force-install`, not changing production mode, the saved `fynlocal` equals the current one, a saved install time exists, no scanned file is newer than that time, no local package changed, and `fyn-lock.yaml` exists. The audit summary still runs in this case. Exit code is 0.
3. Take the install lock `<targetDir>/.f/.installing.lock` (waits 3 s, treats a lock older than 30 minutes as stale). A second concurrent install in the same dir fails to get the lock.
4. Run the project's `preinstall` script, if it has one.
5. Resolve dependencies, fetch tarballs, install into `node_modules`.
6. Run the project's `install`, `postinstall` and `prepare` scripts (those that exist, in that order). `prepublish` is not run.
7. Run the npm scripts from `--run-npm` and from the fynpo `command.bootstrap.npmRunScripts` setting, when `--auto-run` is on. In a fynpo package the default is `["build"]` unless `npmRunScripts` is `false`. An entry that is an array runs only its first script that exists.
8. Refresh hardlinks of local packages if scripts ran, save `fyn-lock.yaml` and the installed copy, save `.fyn.json`, and print the audit summary.

Files scanned for the freshness check include `package.json`, `package-fyn.json`, `fyn-lock.yaml`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `.npmrc`, `.fynrc`, `fynpo.json`, `fynpo.config.js`, `fynpo.config.json`.

Production mode is sticky. If the existing `node_modules` was installed with `--production` and the flag source is the default, fyn keeps production mode. `--no-production` switches it off and reinstalls. `--production` on a non-production tree switches it on.

Layout is sticky. If `.fyn.json` records a different `layout`, that layout is used. A warning appears when `--layout` was given. Remove `node_modules` to change layout.

Exit codes:

| Code | Cause |
| --- | --- |
| 0 | Success, or "No Change". |
| 1 | Install failure (resolution, fetch, script, local build, unapproved scripts with no terminal, fatal config error). |

On failure fyn writes the log to `--save-logs` if set, else to `<os tmpdir>/fyn-debug-<pid>-<timestamp>.log`, and prints the path. Resolution and registry failures are "expected": the stack goes to the log, not the console.

### `add`

```
fyn add [packages..] [--dev <pkgs..>] [--opt <pkgs..>] [--peer <pkgs..>] [options]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `[packages..]` | | string list | none | Added to `dependencies`. |
| `--dev [packages..]` | `-d` | string list | none | Added to `devDependencies`. |
| `--opt [packages..]` | | string list | none | Added to `optionalDependencies`. |
| `--peer [packages..]` | `-p` | string list | none | Added to `peerDependencies`. |
| `--install` | | boolean | true | Run `install` after adding. `--no-install` only edits `package.json`. |
| `--pkg-fyn` | | boolean | false | Save local-path entries in `package-fyn.json` instead of `package.json`. |
| `--audit` | | boolean | true | Passed to the follow-up install. |

Package argument forms:

- `name` or `name@spec`. A missing spec is `latest`.
- `name@tag` resolves a dist-tag to `^<version>`. If that is not a valid range it saves the bare version.
- `name@range` is saved as given when at least one published version satisfies it. Otherwise `no matching version found for <arg>` is logged and the package is skipped.
- `alias@npm:real@spec` saves the `npm:` specifier.
- A directory path, `file:` path, absolute path, `./`, `../` or `~/` path adds a local dependency. If the directory exists it is made relative to the project dir. The `package.json` gets `^<its version>` and a `fyn.<section>.<name>` entry holds the path. In a fynpo monorepo, a name that is a monorepo package gets no `fyn` entry.

Rules:

- Keys in each edited section are sorted.
- Up to 10 metadata lookups run at once. The first lookup error stops the rest.
- The add phase runs with the lockfile off. The install phase runs with it restored.
- No packages given: `No packages to add`, exit 1.
- No package resolved: `No packages found for add`, `package.json` unchanged, no install, exit code unchanged (0).

### `remove`

```
fyn remove <packages..> [--install] [--audit]
```

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `--install` | boolean | true | Run `install` after removing. |
| `--audit` | boolean | true | Passed to the follow-up install. |

Removes each name from `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies`, and from the same sections inside the `fyn` block. Empty sections are deleted. Names not found are logged as `These packages don't exist in your package.json`. If nothing was removed it logs `No package was removed`, skips the install and does not set a failing exit code. No names given: `No packages to remove`, exit 1.

### `stat`

```
fyn stat <package-name>[@semver] [...]
```

Resolves dependencies without building local packages, then for each argument lists the installed versions that match. For each match it prints dependents, circular dependencies, and the dependency paths (all of them, or the most significant ones when there are many). A name that matches nothing prints `<arg> is not installed`. At least one argument is required. Exit code 0 unless resolution fails.

### `outdated`

```
fyn outdated [package-name ...] [--json]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--json` | `-j` | boolean | false | Print records as a JSON array on stdout. Logging is set to `none` for the run so stdout is only JSON. |

Rules:

- Checks direct dependencies from `dependencies`, `devDependencies`, `optionalDependencies` and `devOptDependencies`. When a name is in several sections, `optionalDependencies` wins, then `dependencies`, then `devOptDependencies`, then `devDependencies`.
- A named package that is not declared throws `dependency "<name>" is not declared`.
- Skipped without a comparison: local, URL and git dependencies, dependencies that fynlocal resolves to a local path, and optional dependencies whose `os`/`cpu` do not fit this machine.
- `wanted` is the dist-tag version when the spec is a tag. Otherwise it is the registry `latest` when `latest` satisfies the range, else the highest version that satisfies it. With `--lock-time`, versions published after that time are excluded in the fallback search.
- `latest` is the registry `latest` tag, or `null`.
- `current` is the version in `<targetDir>/<name>/package.json`, or `null` (shown as `MISSING`) when it is not installed.
- A dependency is reported unless `current === wanted` and (`latest` is missing or `wanted === latest`).
- Record fields: `name`, `type` (`prod`, `dev`, `optional`, `devOptional`), `requested`, `current`, `wanted`, `latest`, and `resolvedName` for aliases.
- The table has columns `Package`, `Current`, `Wanted`, `Latest`, `Type`, `Requested`. Empty results print nothing.
- Errors (bad spec, missing tag target, no matching version, registry failure, unreadable installed `package.json`) are thrown and make the process exit 1.

Exit code: 1 when at least one record is reported, 0 when none. It does not change any file.

### `audit`

```
fyn audit [options]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--json` | `-j` | boolean | false | Print `{ vulnerabilities, metadata, advisories }` as JSON. |
| `--omit [types..]` | | string list | none | Dependency types to leave out: `dev`, `optional`, `peer`. A package is dropped only when every path to it is of an omitted type. |
| `--audit-level <level>` | | string | `info` | Lowest severity reported: `info`, `low`, `moderate`, `high`, `critical`. |
| `--cache` | | boolean | true | Use the audit cache. `--no-cache` always fetches. |

Rules:

- Resolves dependencies (without building local packages), then POSTs the package/version map to `<registry>/-/npm/v1/security/advisories/bulk`. The main `registry` is used, not scoped registries.
- One attempt, 10 second timeout, no retries.
- Cache: `<fynDir>/audit`, entries valid 30 minutes. On a network error an expired cache entry is still used with a warning.
- Failures are logged as `Audit failed: <message>` and do not set a failing exit code. `FYN_DEBUG` set also prints the stack.
- The exit code is 0 even when vulnerabilities are found.
- After `install`, a summary (`audited N packages`, counts by severity) is printed. An audit failure there only logs `Security audit failed:`.

### `run`

```
fyn run [script] [args...] [-- <args>...] [options]
fyn <script> [args...]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--list` | `-l` | boolean | false | Print script names, one per line, and exit 0. Does not look for fynpo. |
| `--if-present` | | boolean | false | A missing script returns without error. |

Rules:

- No script name: prints `Lifecycle scripts included in <name>:` and the script names, exit 0.
- A missing script logs `Error: missing script: "<name>" - not found in package.json scripts` and exits 1, unless `--if-present`.
- For a name that does not start with `pre` or `post`, `pre<name>` and `post<name>` run around it when they exist. A name starting with `pre` or `post` runs alone.
- Args before and after `--` are all passed, but only to the main script, not to its pre/post scripts.
- Environment follows npm: `npm_*` variables from package data and config, `npm_node_execpath`, `NODE` (kept if set), `npm_execpath` (the fyn CLI), `INIT_CWD` (the project dir). `node_modules/.bin` of the fynpo top dir is added to the front of `PATH` in a monorepo. The node-gyp environment is set up.
- The rc key `script-shell` selects the shell.
- Scripts run with inherited stdio.
- A failing script exits with the script's exit code (`err.code`, else `errno`, else 1). The error report prints the event, path, command, exit code and signal.

### `init`

```
fyn init [--yes]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--yes` | `-y` | boolean | false | Skip prompts and use defaults. |

Runs the `init-package` generator. Any error exits 1.

### `install-scripts`

Reviews and records which packages may run install scripts. See "Install script policy" for the rules these commands write to. All four subcommands load the project, then read the last install's recorded blocked and pending packages from `<targetDir>/.f/.fyn.json`. Any error is logged and exits 1.

| Subcommand | Alias | Args | Options | Behavior |
| --- | --- | --- | --- | --- |
| `ls` | `list` | none | `--json` | Lists packages awaiting review: those the last install blocked, plus those recorded by `--allow-scripts-pending`. `--json` writes the records to stdout. With none it logs `No packages are awaiting install-script review.` |
| `approve` | | `[packages..]` | `--all`, `--local` | Writes approvals to `allowScripts`. |
| `deny` | | `[packages..]` | `--local` | Writes `{}` entries to `denyScripts`. |
| `prune` | | none | `--local` | Drops `allowScripts` entries for packages that are not installed. |

Common option: `--local` (boolean) writes to the project's `package.json` `fyn` block. Without it, inside a fynpo monorepo the target is `<fynpo dir>/fynpo.json` under `fyn.options`. Outside a monorepo the target is always `package.json`. A missing `fynpo.json` target throws `cannot read <file> - the monorepo allowlist needs a fynpo.json. Use --local ...`.

`approve`:

- Each name must be awaiting review, or carry an explicit `@version`. Otherwise `not awaiting review: <names>` is logged and nothing is written.
- `--all` approves every awaiting package.
- Entries are keyed by the bare package name and hold `{ semver, scripts }`. `semver` is a caret range of the reviewed version, unless `--no-allow-scripts-pin` is set. `scripts` lists the blocked scripts and is omitted when it would cover all three. Approving a second version widens `semver` to a union.
- A package already denied (in `denyScripts` of any scope, or an `allowScripts` `false`) is skipped with a `denied, not approved` warning.
- Nothing runs retroactively. Run `fyn install` afterward.

`deny`: no names logs `no packages named to deny`. A name already in the list logs `already denied`. Names with `@spec` are cut to the bare name.

`prune`: installed names come from `<targetDir>` entries and the `.f/_` store. If none are found it logs an error and writes nothing.

### `prod-prune`

```
fyn prod-prune [dir] [--max-kb <n>] [--max-files <n>] [--force]
```

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `[dir]` | string | the output dir (`<cwd>/<targetDir>`) | Tree to prune. Resolved against the project dir. |
| `--max-kb <n>` | number | 0 (none) | Fail when the remaining tree is larger than `n` kB. Overrides `prodPruning.maxKb`. |
| `--max-files <n>` | number | 0 (none) | Fail when more than `n` files remain. Overrides `prodPruning.maxFiles`. |
| `--force` | boolean | false | Prune even when the tree is not from `fyn install --production`. |

Rules:

- Without `--force` the tree must have `.f/.fyn.json` with `production: true`. Otherwise it exits 1 with `<dir> is not from a production install (fyn install --production). Use --force to prune it anyway.`
- A missing directory throws `no such directory: <dir>` (exit 1).
- Removes by directory name (`test`, `tests`, `__tests__`, `spec`, `__mocks__`, `docs`, `doc`, `example`, `examples`, `benchmark`, `benchmarks`, `coverage`, `.nyc_output`, `.github`, `.circleci`, `.husky`, `.idea`, `.vscode`) and by file type (source maps, TypeScript sources, and other non-runtime files), only inside package roots. License files are merged into `THIRD-PARTY-LICENSES.txt` at the tree root.
- The `package.json` beside the tree can hold `prodPruning`: `{ "maxKb": n, "maxFiles": n, "keepPaths": ["pkg/dir-or-file", ...] }`. `keepPaths` spares those files or directories. A command line budget beats the manifest budget.
- Files larger than 100 kB are always listed. Size never decides what is removed.
- Exit 1 when a budget is exceeded or any error occurs.

### `sync-local`

```
fyn sync-local
```

Re-hardlinks the packed files of each local package recorded in `.fyn.json` (`localPkgLinks`) and refreshes `fyn.localExports` links. Logs `There are no local packages` when there are none. Any error exits 1. It does not resolve dependencies or touch the lockfile.

### `global`

Manages packages installed outside any project.

```
fyn global [--tag <tag>] <subcommand> [options]
```

| Parent option | Type | Behavior |
| --- | --- | --- |
| `--tag <tag>` | string | Operate on one installed copy by tag id such as `g1`, `g2`. Used by `remove` and `link` when no package is named. |

Every subcommand takes `--dir <dir>` (string, default `~/.fyn/global`), the global root. All the fully merged global/rc options (registry, concurrency, and so on) are passed to the installs.

| Subcommand | Alias | Args | Extra options | Behavior |
| --- | --- | --- | --- | --- |
| `add` | | `<packages..>` | `--yes`/`-y`, `--new-tag` | Install each package. Local paths (`./x`, `file:`, existing dir) are supported. |
| `remove` | `rm` | `[package]` | `--yes`/`-y` | Remove a package, a `name@version`, or the copy named by `--tag`. |
| `link` | | `[package]` | none | Make one installed version the active one (`name@version`, or `--tag`). |
| `list` | `ls` | `[name]` | none | List installed packages. |
| `update` | | `[package]` | none | Update a global package. |
| `use` | | `[version]` | none | Point `<root>/current` at `v<node major>` (default: the running Node major). |
| `cleanup` | | `[package]` | none | Remove versions that are not linked. Skips a package with no linked version. |
| `setup-path` | | none | none | Print `PATH` instructions for `<root>/bin`. |

Layout and rules:

- Root `~/.fyn/global`. Per runtime dir `<root>/v<node major>` (`bun<major>` on Bun) with `packages/<gN>/`, `bin/`, and `installed.json`. `<root>/bin` is a symlink to the current runtime's `bin`.
- Each install lives in `packages/g<N>` with its own `node_modules`. A different version gets a new `gN`. Installs take `packages/.install.lock`.
- Installs always use `targetDir: node_modules`, `layout: normal`, `flattenTop: true`, `centralStore: true`, `lockfile: true`, `sourceMaps: false`. The central store is `<root>/_central-storage` (it sets `FYN_CENTRAL_DIR` in the process).
- A spec that looks like a package name but exists as a local path fails with `Ambiguous package spec`. Use `./name`.
- `add`: no packages logs `No packages specified`, exit 1. A failed package logs `Failed to install <pkg>: ...` and exits 1.
- `remove` with no name and no `--tag` logs usage and exits 1. `remove`, `link` and `update` exit 1 when they report failure.
- `cleanup` logs `Nothing to clean up` or `Cleaned up N version(s)`.

## Global options

Defined on the root command. All appear in `fyn --help`.

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--cwd <dir>` | | string | process cwd | Project directory. A relative path is joined to the process cwd. When explicit, fyn does not search parent dirs for `package.json`. A fynpo config can not change it. |
| `--fyn-dir <dir>` | | string | `~/.fyn` | Cache and data dir. Used as given. |
| `--registry <url>` | `--reg` | string | `https://registry.npmjs.org` | Registry URL. |
| `--production` | `--prod` | boolean | false | Ignore `devDependencies`. Also set by `NODE_ENV`. |
| `--lockfile` | `--lf` | boolean | true | Read and write `fyn-lock.yaml`. `--no-lockfile` disables both. |
| `--lock-only` | `-k` | boolean | false | Resolve only from the lockfile. Fails if changes are needed, or if the lockfile cannot be read (exit 1). Does not write `fyn-lock.yaml`. Tarballs are still fetched. |
| `--prefer-lock` | | boolean | false | Prefer versions in the lockfile. |
| `--lock-time <time>` | | string | none | Resolve only versions published at or before this time (anything `new Date()` accepts). Needs full registry metadata. |
| `--npm-lock` | | boolean | unset | `true` always reads `npm-shrinkwrap.json` or `package-lock.json`. `false` never does. Unset reads them only when no fyn lockfile exists. |
| `--offline` | | boolean | false | Use only the lockfile and the local cache. Fails on a miss. |
| `--force-cache` | `-f` | boolean | false | Do not check the registry when the cache has the entry. A cache miss still hits the registry. |
| `--refresh-meta` | | boolean | false | Force refresh of package metadata from the registry. |
| `--refresh-optionals` | | boolean | false | Re-check all `optionalDependencies` instead of trusting the lockfile record. |
| `--always-fetch-dist` | | boolean | false | Fetch the dist tarball while resolving. |
| `--deep-resolve` | `--dr` | boolean | false | Resolve the dependency tree as deep as possible. |
| `--ignore-dist` | `-i` | boolean | unset | Ignore the host in the tarball URL from metadata. No code outside the option getter reads it. |
| `--ignore-lock-url` | | boolean | false | Rebuild tarball URLs from the registry setting instead of the lockfile URL. |
| `--enforce-registry-deps` | | boolean | unset (on) | Require transitive dependencies to come from a registry. See "Registry-only transitive dependencies". |
| `--show-deprecated` | `-s` | boolean | unset | Always show deprecation messages. |
| `--fynlocal` | | boolean | true | Enable local package linking. See "Local packages (fynlocal)". |
| `--build-local` | | boolean | true | Run `fyn install` and the build scripts in local dependency packages first. |
| `--source-maps` | `--sm` | boolean | false | Generate pseudo source maps for linked local packages. |
| `--auto-run` | | boolean | true | Run the extra npm scripts after install. |
| `--flatten-top` | | boolean | true | Hoist packages to the top `node_modules`. Turning it off while `--layout` is unset switches the layout to `detail`. |
| `--layout <type>` | | string | `normal` | `normal` or `detail`. `detail` puts every package under its own versioned path and symlinks into `node_modules`. |
| `--central-store` | `--central`, `--cs` | boolean | unset | See "Central store". |
| `--hardlink` | | boolean | unset (on) | Hardlink central store files into `node_modules`. |
| `--reflink` | | boolean | true | Clone store files copy-on-write where the filesystem can. `--no-reflink` never uses `@fynjs/reflink`. |
| `--copy-fallback` | | boolean | true | Copy files that cannot be cloned or hardlinked. `--no-copy-fallback` fails the install instead. |
| `--copy [packages..]` | `--cp` | string list | none | Copy these packages even in central store mode. The value is stored but no code reads it. |
| `--script-policy <mode>` | | string | `review` | `all`, `source`, `review` or `off`. See "Install script policy". |
| `--allow-scripts [packages..]` | | string list | none | Allow these packages' install scripts for this run. Commas split names. |
| `--deny-scripts [packages..]` | | string list | none | Deny these packages' install scripts for this run. Wins over every approval. |
| `--allow-scripts-pin` | | boolean | true | Pin written approvals to the reviewed version. |
| `--concurrency <n>` | `--cc` | number | 32 | Network concurrency (registry sockets). |
| `--extract-concurrency <n>` | `--excc` | number | min(4, workers + 1) | Packages extracted at once. |
| `--meta-memoize <url>` | `--meta-mem` | string | none | URL of a server that shares a metadata cache across fyn processes. |
| `--log-level <level>` | `-q` | string | `info` | `debug`, `verbose`, `info`, `warn`, `error`, `fyi`, `none`. A unique prefix works (`-q=d`). The first level that starts with the text wins. An invalid value logs `Invalid log level` and exits 1. |
| `--save-logs [file]` | `--sl` | string | `fyn-debug.log` when given without a value | Save all logs to this file, relative to the project dir. Ignored when the value came from an rc file rather than the command line. |
| `--colors` | | boolean | true | `--no-colors` turns color off. |
| `--progress <type>` | `--pg` | string | `normal` | `normal`, `simple` or `none`. An unknown value means `none`. `normal` becomes `simple` when stdout is not a TTY. |
| `--rcfile` | | boolean | true | `--no-rcfile` skips every rc file and uses only the built-in defaults. |

Built-in defaults (`default-rc`): `registry` `https://registry.npmjs.org`, `targetDir` `node_modules`, `progress` `none` when a CI is detected (`ci-info`), else `normal`.

Options with no command line flag but read by fyn from rc, fynpo or the `Fyn` constructor: `targetDir` (default `node_modules`), `pkgFile` (default `package.json`), `allowTopLevelScripts`, `reviewLocalPackages`, `email`, `username`, `password`, `always-auth`, `script-shell`, `@scope:registry`, `//host/:_authToken`.

## Config sources and precedence

### rc files

rc files are read with an ini parser. Files, from lowest to highest priority (later wins, objects merge deeply):

1. `$NPM_CONFIG_GLOBALCONFIG`
2. `$PREFIX/etc/npmrc`
3. `$NPM_CONFIG_USERCONFIG`
4. `~/.npmrc`
5. `~/.fynrc`
6. `<fynpo dir>/.npmrc` (only when a fynpo dir exists and differs from the project dir)
7. `<fynpo dir>/.fynrc` (same condition)
8. `<project dir>/.npmrc`
9. `<project dir>/.fynrc`

Rules:

- The built-in defaults sit under all of these.
- A missing file is ignored. A file that fails to parse logs `Failed to process <name> RC file`, and is treated as empty.
- Every key from every file goes into the options. Registry keys (`registry`, `<scope>:registry`), `*:_authToken` keys and `email`, `always-auth`, `username`, `password` are read by the registry layer. Auth keys are removed from debug output.
- Keys are written in the file in kebab-case or camelCase (`logLevel`, `central-store`). Both match the option names.
- `${VAR}` in a string value is replaced from the environment. An unset variable stays as `${VAR}`. `\${VAR}` escapes it.
- `.npmrc` values are also exposed to lifecycle scripts as `npm_config_*`.
- `--no-rcfile` loads none of these.

`.fynrc` sections: a top-level key whose value is an ini section is applied only when it matches. Plain top-level keys are the defaults. Section names:

| Section | Matches when |
| --- | --- |
| `[IS_CI]` | `CI` or `BUILD_ENV` is set. |
| `[CI:<value>]` | `CI` or `BUILD_ENV` (the first one set) equals `<value>`. |
| `[VAR:<value>]` | environment variable `VAR` equals `<value>`. |
| `[VAR1\|VAR2:<value>]` | either variable equals `<value>`. |

Applied order: defaults, then env-match sections, then `IS_CI`, then `CI:<value>`. `.npmrc` files do not use sections.

### Order of precedence for an option

1. Command line (highest).
2. `NODE_ENV` for `production` only: when `NODE_ENV` is set, `production` becomes `NODE_ENV === "production"`, unless `--production` was given.
3. rc files, merged into the option set with lodash `defaults`: they fill options the parser has not set.
4. The fynpo config `fyn.options` (see below). The code documents the order as command line, then rc, then fynpo. It applies a fynpo value only when the option did not come from the command line.
5. Built-in defaults.

Unverified: the CLI also applies fynpo options through a second path that overrides every option not set on the command line, so rc versus fynpo order was not confirmed at runtime. Also, the rc step uses `defaults`, so an rc value does not replace an option that already carries a built-in argument default (for example `concurrency`, `progress`). Check with a runtime test before relying on rc to override those.

The `fyn` block of `package.json` does not accept general options. It accepts only the keys listed in "Package fyn section".

### Environment variables

| Variable | Effect |
| --- | --- |
| `FYN_DIR` | fyn data dir, used as given. Fallbacks `USERPROFILE`, then `HOME` get `/.fyn` appended. Default is `<cwd>/.fyn` if none are set. `--fyn-dir` wins. |
| `FYN_REGISTRY` | Registry when no `registry` option exists. The CLI always has one (the built-in default), so this applies only to programmatic use. |
| `FYN_TARGET_DIR` | Same story for `targetDir` (default would be `xout` without the CLI defaults). |
| `FYN_PACKAGE_FILE` | The package file name. Default `package.json`. |
| `FYN_CENTRAL_DIR` | Central store dir. A false value (`0`, `false`, `no`, `off`) disables the store. `1`, `on`, `true` or `yes` uses `<fynDir>/_central-storage`. See "Central store". |
| `FYN_HARDLINK` | Hardlink on or off when `--hardlink` is not given. |
| `FYN_SHORT_PKG_DIR` | Any non-empty value (even `0`): new installs store packages at `.f/_/<name>/<version>/<name>`. Default: `.f/_/<name>/<version>/node_modules/<name>`. An existing install's recorded form wins. |
| `FYN_LOCAL_COPY_MODE` | True: copy local package files instead of hardlinking them. |
| `FYN_LOCAL_PACK_SYMLINKS` | True: include symlinks when packing local package files. |
| `FYN_FYNPO_DIR` | Set by fyn to the detected monorepo top dir. Suppresses the "Detected a ..." message in child fyn processes. |
| `FYN_DEBUG` | Print stack traces for audit failures. |
| `NODE_ENV` | Sets `production`. See above. |
| `NPM_CONFIG_GLOBALCONFIG`, `NPM_CONFIG_USERCONFIG`, `PREFIX` | rc file locations. |
| `CI`, `BUILD_ENV` | `.fynrc` section matching. `ci-info` detection sets the default `progress`, enables prompts only off CI, and stops source map handling for `.js` files. |
| `NOPROXY` | Passed to the registry fetch as `noProxy`. |
| `NODE_DISABLE_COMPILE_CACHE`, `NODE_COMPILE_CACHE` | Node compile cache control. |

`FYN_HARDLINK`, `FYN_LOCAL_COPY_MODE` and `FYN_LOCAL_PACK_SYMLINKS` are read as booleans: unset, empty, `0`, `off`, `false` and `no` are false (case insensitive), anything else is true.

### fynpo.json `fyn` section

When the project is inside a fynpo monorepo (`fynpo.json`, `fynpo.config.js`, `fynpo.config.json`, or a lerna config found by walking up), fyn reads these keys from that config:

| Key | Effect |
| --- | --- |
| `fyn.options` | Object of option names (camelCase) applied as in "Order of precedence". `cwd` and `initCwd` are never taken from it. |
| `fyn.options.allowScripts`, `denyScripts`, `allowTopLevelScripts`, `scriptPolicy`, `reviewLocalPackages` | Have their own merge rules. See "Install script policy". |
| Other `fyn.options` object values | Deep merged with the existing value, with already-set keys winning. |
| `centralDir` | Central store dir for the monorepo (see "Central store"). |
| `noFynLocal` | Package names that must not be auto-linked. |
| `localDepAutoSemver` | `patch`, `minor` or `major`: how a monorepo sibling's range is widened when matching a local copy. |
| `resolutions`, `overrides` | Merged with the same keys in `package.json`. fynpo wins on a conflict. |
| `command.bootstrap.npmRunScripts` | Scripts run after install in a monorepo package. Default `["build"]`; `false` disables. |
| `packages` | Package globs. Used to find local copies. |

A fynpo config that does not parse logs a warning naming the file and exits 1.

### Package fyn section

`package.json` (merged with `package-fyn.json`) can carry:

| Key | Behavior |
| --- | --- |
| `fyn.dependencies`, `fyn.devDependencies`, `fyn.optionalDependencies`, `fyn.peerDependencies` | Map of name to a local path (or `false` or a string containing `no-fyn-local` to opt out of local linking). Only used with fynlocal on. A path that does not exist is ignored. |
| `fyn.allowScripts`, `fyn.denyScripts`, `fyn.allowTopLevelScripts`, `fyn.scriptPolicy`, `fyn.reviewLocalPackages` | Install script policy. |
| `fyn.enforceRegistryDeps` | `false` turns off the registry-only rule. |
| `fyn.localExports`, `fyn.localExportsDir`, `fyn.localExportsDirs` | Local source exports. |
| `resolutions` | Map of dependency path to version. Paths may use `**` between slashes. A bare name matches at any depth. |
| `overrides` | npm style overrides: simple, nested, `name@range` keys, and `$name` references to a direct dependency version. |
| `prodPruning` | Used by `prod-prune`. |

`package-fyn.json` in the project dir is deep merged over `package.json` in memory (the whole file, not only a `fyn` key). `fyn add --pkg-fyn` writes to it.

## Local packages (fynlocal)

`--fynlocal` (default true) lets a dependency resolve to a directory on disk instead of the registry.

Ways a dependency becomes local:

- A spec in `dependencies` and friends that is `file:<path>`, an absolute path, `./...`, `../...`, or `~/...`.
- A `fyn.<section>.<name>` path in `package.json` or `package-fyn.json`. It replaces the registry spec locally while the registry spec stays for publishing.
- In a fynpo monorepo, a dependency whose name is a monorepo package and whose range matches that package's version. Skipped when the name is in the config `noFynLocal`, when `fyn.<section>.<name>` is `false` or contains `no-fyn-local`, or when the spec is a URL. A name that matches no version logs the versions available.

Behavior:

- Local packages get a version tag `-fynlocal_h` (hardlinked). Soft symlink mode was removed and now throws.
- Install hardlinks the files that `npm pack` would include (npm-packlist rules, symlinks only with `FYN_LOCAL_PACK_SYMLINKS`) from the source dir into the consumer's `node_modules`, so edits show up without reinstall. `FYN_LOCAL_COPY_MODE` copies instead. Files in the target that are not in the pack list are removed.
- `--build-local` (default true): before linking, each local dependency whose files changed and which has any of the scripts `preinstall`, `install`, `postinstall`, `prepare`, `build` is built by running `fyn --reg=<registry> -q=d --pg=simple --no-build-local --sl=fyn-debug.log [--no-source-maps] install --no-audit [--force-install]` in its dir. One at a time, deepest dependencies first. Then it runs `prepublish` (skipped with a warning when `prepare` also exists, and a deprecation note is printed), `prepack` and `postpack`. A failed local build prints the primary error, the nested errors and the log path, and fails the install. Its own debug log is `fyn-debug.log` in that dir.
- A package that is the project itself is not built.
- `--source-maps`: for linked `.js` and `.mjs` files with no source map, writes `<file>.fyn.map` mapping each position to the source. A file with its own relative `.map` gets a rewritten map pointing back at the sources. Nothing is generated in CI. `.js.map` and `.mjs.map` files themselves are skipped outside CI.
- Freshness: the "No change" check also looks at local package files and at the linked packed files, so a rebuilt local package triggers a refresh.
- `fyn sync-local` refreshes the links without installing.
- The local link list is stored in `.fyn.json` as `localPkgLinks` (`{ "<node_modules path>": { srcDir, sourceMaps } }`).
- Local entries in `fyn-lock.yaml` have `$: local` and `_: <path>` (relative to the lockfile dir) and are not refreshed from the registry.

`fyn.localExports` (optional): a producer package can declare directories to expose to consumers.

- Producer `package.json`: `"fyn": { "localExports": { "<export name>": "<relative dir>" } }`. `false` disables one export or the whole field.
- Consumer `package.json`: `fyn.localExportsDir` (default `_fyn`) and `fyn.localExportsDirs` (`{ "<package>": "<dir>" }`) set where links go.
- A link is made at `<dir>/<package>/<export>` in the consumer only for fynpo siblings and for `file:`, `link:` or path dependencies. Registry, git and URL dependencies never create exports.
- Dirs must be relative, with no `..`, `node_modules` or `.git`, and must not nest in each other. Names must match `[A-Za-z0-9_][A-Za-z0-9._-]*`. Violations throw errors such as `Unsafe fyn.localExports source ...`.
- Each root dir has an ownership file `.fyn-local-exports.json`. fyn only removes links it owns. The dir is generated content and should be ignored by version control.

## Central store

The central store keeps one extracted copy of each package, keyed by tarball integrity, and `node_modules` gets links or clones of it.

Whether the store is used, in order:

1. `centralDir` already recorded in `<targetDir>/.f/.fyn.json` (an existing install keeps its store). A recorded `false` keeps it off.
2. `FYN_CENTRAL_DIR`: false value disables it, true value uses `<fynDir>/_central-storage`, any other value is the dir.
3. `--central-store` (or rc `centralStore`): `<fynDir>/_central-storage`. `--no-central-store` turns the default (rule 4) off. It does not disable the monorepo store of rule 5.
4. Not a fynpo project: on by default on macOS when `@fynjs/reflink` can clone directories (and `--reflink` is on), and on Linux when hardlink is on or reflink can clone files. Off on Windows and in all other cases.
5. In a fynpo monorepo: `centralDir` from the fynpo config, else `<monorepo>/.fynpo/_store`. If the monorepo is a git linked worktree, the main worktree's `.fynpo/_store` is shared.

The store is skipped (with an info message, and the dir remembered in `.fyn.json`) when it would only copy: `--no-hardlink` and `--no-reflink` together (unless `--no-copy-fallback`); hardlink off on macOS or Windows without `@fynjs/reflink`; or the store is on a different volume than the project.

Storage layout: `<store>/<algorithm>/<hex[0:2]>/<hex[2:4]>/<hex[4:]>/package/` for files, plus a `tree.json` with the file list, a content checksum and a `mutates` flag. Stores of concurrent installs are guarded by marker files. Stale temp entries are cleaned.

Placing files into `node_modules` (per package):

1. One directory clone when `--reflink` is on and the filesystem supports it (APFS).
2. Else per file clone (`@fynjs/reflink`), falling back to hardlink when `--hardlink` is on, then to copy when `--copy-fallback` is on.
3. Else hardlink, with a copy where hardlinking fails.
- `package.json` is always copied because fyn rewrites it.
- A failed hardlink (for example another volume) turns hardlinking off for the rest of the run and copies.
- `--no-copy-fallback` makes a file that cannot be cloned or linked fail the install.

Mutation guard: if a package's install scripts change its files, fyn compares a checksum before and after, marks that package as `mutates` in the store, and never shares it again.

`--hardlink` precedence: command line or rc, then `FYN_HARDLINK`, then the value saved in `.fyn.json`, then on. The choice is saved.

Global installs always use `<global root>/_central-storage`.

## Lockfile

`fyn-lock.yaml` is in the project dir. It is YAML with sorted keys and one space indent.

Top level keys:

| Key | Content |
| --- | --- |
| `$fyn` | Saved config: `layout`, `flattenTop`. |
| `$pkg` | The declared direct dependencies: `dep`, `dev`, `opt` maps of name to spec. |
| `<package name>` | One block per package (below). |

Package block:

| Key | Content |
| --- | --- |
| `_latest` | The registry `latest` version seen. |
| `_` | Map of comma joined semver specs to the resolved version (an array when several). |
| `<version>` | Entry for a resolved version. |

Version entry keys: `top: 1` (requested directly by the project), `$` (integrity, `0` if none, or `local`), `_` (tarball URL, or a local path), `dependencies`, `optionalDependencies`, `peerDependencies`, `bundleDependencies`, `hasPI: 1` (has `preinstall`), `hasI: 1` (has `install` or `postinstall`), `optFailed`, `_missingJson: true`, `deprecated`, `os`, `cpu`, `_hasShrinkwrap: 1`. A platform mismatch is not recorded in the lockfile.

Reading:

- Order of sources: `fyn-lock.yaml`; if absent and `--lockfile` and not `--lock-only`, the installed copy `<targetDir>/.f/lock.yaml`; if still none and not `--npm-lock=false`, `npm-shrinkwrap.json` then `package-lock.json`; then `yarn.lock`.
- A lockfile with git conflict markers is ignored with an error, and everything is resolved again.
- A lock version key that is not valid semver (and is not local) is ignored.
- An unreadable lockfile is an error only with `--lock-only` (exit 1).
- A tarball URL that does not start with the current registry is rewritten onto it when the path matches. `--ignore-lock-url` forces the rewrite.
- `layout` and `flattenTop` stored in the lock win over the defaults. A command line value that differs updates the lock and logs `You are changing <name> in your lockfile`. Other sources are overridden with the lock value and a `Setting <name> to ... from your lockfile` message.

Writing:

- Written after a successful install, only when its checksum changed, never with `--lock-only` and never with `--no-lockfile`.
- The installed copy `<targetDir>/.f/lock.yaml` is written on every install, including `--lock-only`.
- Local package paths are saved relative to the lock dir.
- `add` and `remove` run their edit step with the lockfile off.

Related files in `<targetDir>/.f/`: `.fyn.json` (install config), `lock.yaml` (installed lock copy), `.installing.lock`, `_/` (store for isolated package versions), `.fyn-audit.json` (the path `getAuditFilePath` returns for a generated audit report).

`.fyn.json` fields: `time` (install time in ms, 5 ms after the lock save), `centralDir` (string or `false`), `production`, `fynlocal`, `layout`, `shortPkgDir`, `hardlink`, `blockedScripts`, `pendingScripts`, `localPkgLinks`, `localExports`, `localsByDepth`. It is an internal format and changes without notice.

Caches under `<fynDir>`: `_cacache` (packages and registry cache), `fyn-packuments` (trimmed metadata), `audit`, `tmp`, `links`, `_central-storage`, `global`.

## Install script policy

The install scripts gated are `preinstall`, `install` and `postinstall`. The project's own scripts are not gated.

### Modes

`--script-policy` or `fyn.scriptPolicy`. Default `review`. The value is case insensitive. An unknown value throws `fyn scriptPolicy "<value>" is not valid - expected one of all, source, review, off`.

| Mode | Registry packages | git/URL packages | Workspace-local packages |
| --- | --- | --- | --- |
| `review` | need an `allowScripts` entry | need an entry | run |
| `source` | run | need an entry | run |
| `all` | run | run | run |
| `off` | none run | none run | none run |

- `off` ignores the allowlist.
- `npm:` aliases count as registry. A local path declared by a git or URL package is not workspace-local.
- Workspace-local means `file:`, `link:`, path dependencies and fynpo siblings. `reviewLocalPackages: true` removes their exemption.
- `fyn.allowTopLevelScripts` applies in `source` mode only. `true` or `"*"` allows all scripts, an array allows those script names, for non-registry packages declared directly in the project's `package.json`. It is ignored in every other mode. First defined wins: option (rc or fynpo option), then `package.json`, then fynpo config.

### Maps

`allowScripts` and `denyScripts` are maps of key to value.

Key forms: `name`, `name@<semver range>`, `@scope/name@<range>`, or `name@<requested spec>` for a git/URL spec (matched literally). A key's range is matched against the resolved version.

Value forms for `allowScripts`:

| Value | Meaning |
| --- | --- |
| `{ "semver": "<range>", "scripts": [...] }` | The form fyn writes. A missing field means all versions or all scripts. |
| `true` or `"*"` | All scripts, all versions. |
| `["install"]` or `"install"` | Only those scripts. |
| `"1.2.3"` or `"^1.2.0"` | All scripts, matching versions only (npm form). |
| `false` | Deny the package. |
| `[..., "!postinstall"]` | `!name` denies one script, `!*` denies all, `+name` allows it. A `!` beats an allow of the same name. |

`denyScripts` takes the same shape. A match denies. An empty `{}` entry denies every version and script. `--deny-scripts a,b` makes bare names.

### Precedence

- `denyScripts` is checked first and wins over every approval: the allowlist, `allowTopLevelScripts`, the local exemption and mode `all`. `off` is checked before it.
- `allowScripts` merges loosest to tightest: fynpo `fyn.options`, then `package.json`, then the command line. Approvals add up. A `false` at any scope is final.
- `denyScripts` unions across all three scopes. No scope removes another's denial.
- `scriptPolicy`: the command line overrides outright. Otherwise the stricter of the fynpo and `package.json` values wins (order `all`, `source`, `review`, `off`, loosest to strictest). A package can tighten but never loosen the monorepo's mode.
- `reviewLocalPackages`: on if any scope turns it on.

### Install-time behavior

- Under `review`, an install that would skip unapproved scripts stops before running scripts.
  - With a terminal and no CI, it lists the packages and asks `Approve? [a]ll / [s]elect / [n]one (default)`. Approved packages are written to `package.json` (or the monorepo `fynpo.json`) and run in this install.
  - Without a terminal, or on CI, it throws and exits 1: `N package(s) need approval to run their install scripts, and there is no terminal to ask on: ...`.
  - Denied packages are not prompted. They appear in the end summary.
- Under `source`, `all` and `off`, blocked scripts are reported at the end and the install continues.
- Blocked and pending records are saved in `.fyn.json` for `install-scripts ls`.

## Registry-only transitive dependencies

On by default. A transitive (not top-level) dependency from `github:`, git, `http(s)` tarball or an unparseable selector aborts the install with an error naming the package and its parent. Accepted: registry ranges and tags, `npm:` aliases, local `file:`/`link:`/path deps, fynpo siblings. The project's own `package.json` may use any source.

Precedence: an explicit option value (command line, rc, or fynpo `fyn.options.enforceRegistryDeps`) wins over `package.json` `fyn.enforceRegistryDeps`, which wins over the default (on). Only `false` in `package.json` turns it off.

## Exit codes summary

| Where | Code |
| --- | --- |
| Any command | 0 on success. |
| Parse error | 1. |
| Node older than 22.22.2 | 1. |
| Uncaught rejection in the bin wrapper | 1 (prints the error). |
| `install` | 1 on failure. 0 on success or "No Change". |
| `add`, `remove` | 1 for no package names. Install failures follow `install`. |
| `outdated` | 1 when anything is outdated. Errors also 1. |
| `audit` | 0 even with findings. Failures logged only. |
| `run` | The script's exit code, else 1. Missing script 1 (0 with `--if-present`). |
| `install-scripts`, `prod-prune`, `sync-local`, `init` | 1 on any error. `prod-prune` also 1 when over budget. |
| `global` | 1 on missing arguments or a reported failure. |
| `--log-level` invalid | 1. |
| fynpo config parse failure | 1. |
| `package.json` unreadable | 1. |
| `--lock-only` with unreadable lockfile | 1. |

<!-- fynpo v3.2.3: https://fynjs.pages.dev/ref/fynpo.md -->

# fynpo reference

fynpo is a monorepo manager CLI for npm packages. It discovers packages, installs them with `fyn` in dependency order, runs npm scripts across them, and drives a conventional-commit release flow (changelog, version bump, publish).

## Install and invocation

The package has no `main` or `exports`. It ships only the `fynpo` executable (`bin/fynpo.js`). There is no JS API.

```
fynpo [command] [options]
```

- Requires Node `^22.22.2 || ^24.15.0 || >=26.0.0`.
- With no command, `bootstrap` runs. `fynpo --help` and `fynpo --version` (or `-v`, `-V`) show the root help and version instead.
- `fynpo --help <command>` shows help for one command. `-h` and `-?` are aliases of `--help`.
- `--no-<flag>` negates a boolean flag, for example `--no-bail`.
- Arguments after `--` are not forwarded to package scripts. `fynpo run t -- --foo` runs `npm run t` with no extra args (the code reads `opts["--"]`, which the parser never sets).
- Errors thrown out of a command that does not handle them end in `fynpo failed` plus the stack on stderr, exit code 1.

## Commands

| Command | Alias | Purpose |
| --- | --- | --- |
| `bootstrap` | `b` | Run `fyn install` in every package in topological order. Default command. |
| `local` | `l` | Builds the dependency graph and returns. It installs and changes nothing. |
| `prepare` | `p` | Apply the versions in CHANGELOG.md to package.json files, bootstrap, run `fynpo:prepare` hooks, commit `[Publish]`. |
| `updated` | `u` | Print packages changed since the last release. |
| `changelog` | `c` | Write a new CHANGELOG.md entry from commits, optionally with version bumps. |
| `run <script>` | `r` | Run an npm script in each package that defines it. |
| `version` | `v` | Write the changelog entry, bump package versions, and commit. |
| `publish` | `pb` | Pack and `npm publish` the packages named in the HEAD `[Publish]` commit, then tag. |
| `init` | `i` | Prepare a repo for fynpo. |
| `commitlint` | `cl` | Lint a commit message against the configured rules. |

Typical release flow: `fynpo changelog`, then `fynpo prepare`, then `fynpo publish`. `fynpo version` is a one-step alternative to `changelog` plus `prepare` without the bootstrap and hooks.

### Config bootstrap on first use

Every command except `init` first searches for config (see Config file). When none is found anywhere up the tree, fynpo writes `fynpo.json` into the current directory with this content and continues:

```json
{ "changeLogMarkers": ["## Packages", "## Commits"], "command": { "publish": { "tags": {}, "versionTagging": {} } } }
```

If the file exists but no config could be loaded from it, fynpo logs an error and throws `Unable to load fynpo config from existing file <path>` instead of overwriting it.

## Global options

Defined at the root. Each is accepted only by the commands in the last column. Values here are merged with the config file: command line values override same-named top-level config keys, and CLI defaults (for example `concurrency` 6) also override them.

| Option | Alias | Type | Default | Commands | Behavior |
| --- | --- | --- | --- | --- | --- |
| `--cwd <path>` | | string | process cwd | root | Sets the starting directory. Logs `Setting CWD to <path>` and calls `process.chdir`. The fynpo top directory (where the config file was found) then replaces it. `init` and `commitlint` use only their own parsed options and did not apply `--cwd` when tested. |
| `--ignore <names..>` | `-i` | string list | none | bootstrap, local, run | Packages to skip. Each entry matches package name, path, or `name@version`. |
| `--scope <scopes..>` | `-s` | string list | none | bootstrap, local, run | Keep only packages whose npm scope is listed. The `@` is optional. Unscoped packages are always dropped once `--scope` is given. Implemented by adding the out-of-scope names to `ignore`. |
| `--deps [n]` | `-d` | number | `10` | bootstrap, local, run | Declared as "level of deps to include even if ignored". No code reads it. It has no effect. |
| `--commit [bool]` | | boolean | `true` | changelog, version, prepare | Commit the generated changes. `--no-commit` writes files and skips the commit. |
| `--force-publish <names..>` | `--fp` | string list | none | updated, changelog, version | Treat these packages as changed. `*` forces all. |
| `--since <ref>` | | string | none | updated, changelog, version | Use this commit-ish as the change boundary instead of the latest release tag. |
| `--only <names..>` | `-o` | string list | none | bootstrap, local, run, updated, changelog, version, prepare | Limit to these packages. See Selection. For releases, version lock groups expand. |
| `--ignore-changes <globs..>` | `--ic` | string list | none | updated, changelog, version | Minimatch patterns (`matchBase`, `dot`) for files to ignore in change detection and commit collation. |
| `--save-log` | `--sl` | flag | off | all | Write `fynpo-debug.log` in the current directory. Only `bootstrap` reads it (it is also written whenever bootstrap fails). |
| `--version` | `-V`, `-v` | flag | | root | Print the version. |
| `--help` | `-h`, `-?` | string list | | root | Print help. |

Because `--only`, `--ignore`, `--scope` and others are flat option names, the same names at the top level of the config file act as defaults for the commands that read them (for example `"ignore": ["pkg-demo"]`).

## `fynpo bootstrap`

```
fynpo bootstrap [--build] [--concurrency <n>] [--skip <names..>]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--build [bool]` | | boolean | `true` | Accepted and passed to the bootstrap step, which does not read it. `--no-build` changes nothing in fynpo. The fyn side runs `build` after install via `command.bootstrap.npmRunScripts`. |
| `--concurrency [n]` | `--cc` | number | `6` | Packages installed at once. No range check. |
| `--skip <names..>` | | string list | none | Package names (name only) logged as `bootstrap skipping` and not installed. They are not ignored, so dependents still order after them. |

Plus the global options `--ignore`, `--scope`, `--only`, `--deps`, `--save-log`.

Behavior:

- Packages run in topological order. A package starts only after its local dependencies finish. A cycle is logged as `detected circular deps a > *b*` and the members are still scheduled. See Topological ordering.
- `--only` and `--ignore` filtering is applied in the scheduler. `--only` pulls the selected packages' local dependencies in transitively.
- Per package it runs, in the package directory: `node <fyn bin> [fynOpts] [-q d] install --sl --no-build-local --audit-file '<path>' --meta-mem=http://localhost:<port>`. In CI it prepends `--pg simple`. `-q d` is added unless `-q` or `--log-level` is in the fyn options. fyn is resolved from fynpo's own dependency (`fyn/bin/fyn.mjs`), not from PATH.
- A warning is logged when a globally installed fyn has a different version from the bundled one.
- fyn instances share a localhost HTTP server for package-meta memoization (`--meta-mem`). If the server fails to start, the option is omitted.
- The first failure stops scheduling (`stopOnError`). Running installs finish. Each failure prints a framed block with the primary error line, the failing command, exit code, and the path `<pkg>/fyn-debug.log`. In CI it also prints stdout and stderr (last 50 lines of each when longer than 100).
- After a successful run, a security audit summary is printed from the per-package audit files fyn wrote (`No audit reports found from bootstrap.` when none). Up to 20 packages with vulnerabilities are listed.
- If `.fynpo-data.json` `__timestamp` changed during the run (fyn recorded new indirect local deps), fynpo logs `fynpo data changed - running bootstrap again` and runs once more. Commit that file.
- Output ends with `bootstrap completed in <s>secs` or `bootstrap failed in <s>secs`.
- Exit code: `0` on success, `1` on any failure or thrown error. On failure, or with `--save-log`, `fynpo-debug.log` is written and its path is logged.
- An error that looks like a fynpo import bug (`__WEBPACK_IMPORTED_MODULE_`, `is not a constructor`, or a not-a-function style error from fynpo's own stack) logs `*** INTERNAL FYNPO BUG DETECTED ***` first.

Config keys read: `packageCache.default` (build cache, see Caching), `caching`, `noFynLocal`, `packages`, `resolutions` (cache input), `fynOpts` (see below).

`fynOpts` (string array of fyn CLI options): `bootstrap` reads `fynOpts` only from the parsed command line options, and no command line option by that name is defined, so a config `fynOpts` does not reach `fynpo bootstrap`. `prepare` reads `fynOpts` from the merged config and passes it to its internal bootstrap.

## `fynpo local`

Builds the graph (printing the discovery notice) and returns. No installs, no file changes. It accepts `--ignore`, `--scope`, `--only`, `--deps`.

## `fynpo run <script>`

```
fynpo run <script> [--stream] [--parallel] [--prefix] [--bail] [--concurrency <n>] [--sort] [--cache]
```

`<script>` is required. Without it the parser reports `Not enough arguments for command 'run'`.

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--stream` | | flag | off | Stream child output live, line prefixed with the package name, instead of printing each package's buffered output in a box when it finishes. |
| `--parallel` | | flag | off | Ignore topological order. Run up to `concurrency` packages at once. Takes precedence over `--sort`. |
| `--prefix [bool]` | | boolean | `true` | Prefix streamed lines with the package name, colored by a rotating palette. Only matters with `--stream`. |
| `--bail [bool]` | | boolean | `true` | When a package script fails, packages not yet started are skipped. Packages already running finish. `--no-bail` runs every package and reports all failures at the end. |
| `--concurrency [n]` | `--cc` | number | `6` | Packages at once. An integer from 1 to 100 is used. Anything else falls back to `3`. |
| `--sort [bool]` | | boolean | `true` | Run in topological order. `--no-sort` runs the candidate list in its listed order with no waiting on dependencies, using the same `concurrency` (logged as `lexical order`). In effect it behaves like `--parallel`. |
| `--cache` | | flag | off | Use the lifecycle cache. Needs `lifecycleCache.default` rules. See Caching. |

Plus the global options `--ignore`, `--scope`, `--only`, `--deps`, `--save-log`.

Behavior:

1. Candidates are packages whose `package.json` has `scripts.<script>`. Then `--only`, `--ignore` and `--scope` narrow them, and unmanaged packages (nested, see Discovery) are removed. `--sort`, `--no-sort` and `--parallel` never change which packages run.
2. With no candidates: `No packages found with script <script>` is logged and the command returns. When the script exists but the selection removed all of it: `No packages left to run script <script> after --only/--ignore`.
3. Before running, stale local dependency copies produce a warning (see Stale local dependency check). It never fails the run.
4. Each package runs `npm run <script>` in its directory (`npm` is hard coded as the client).
5. If a package has no `node_modules` directory, fyn installs it first (`installing node_modules in <path> to run script <script>`). Set `lifecycleCache.default.requireDeps` to `false` to skip this.
6. Each package's start is logged in a box. A finished package logs its box plus its stdout and stderr (not with `--stream`).
7. Summary on success: `Finished run npm script '<script>' in N package(s) in <s>s:` with the names of the packages that actually ran.
8. Exit code: `0` when all scripts pass. On failure it logs each failing package with its exit code and exits with the highest failing code, at least `1`. `process.exit(1)` for an exception thrown inside the run.
9. Config `continueOnError: true` (top level) keeps running packages after a failure even with bail on. It has no CLI flag.

Top-level config keys `concurrency` and `sort` are overridden by the CLI defaults (6 and true) for this command, and `command.run` is not read.

## `fynpo updated`

Lists packages changed since the release boundary. Options: `--force-publish`, `--since`, `--only`, `--ignore-changes`.

Output: `No changed packages!` or `Changed packages:` followed by ` - <name>` lines. The exit code is `0` either way. See Change detection.

## `fynpo changelog`

```
fynpo changelog [--publish] [--tag] [--confirm-version-bumps]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--publish` | | flag | off | Also write the new versions into package.json files and create the `[Publish]` commit (and tags with `--tag`). Without it, only CHANGELOG.md is committed. |
| `--tag` | | flag | off | Create a git tag `<name>@<version>` for each released package. Takes effect only together with `--publish`. |
| `--confirm-version-bumps [bool]` | `--cvb` | boolean | `true` | Ask before minor, major and indirect bumps. `--no-confirm-version-bumps` or `--no-cvb` skips all prompts. |

Plus `--commit`, `--force-publish`, `--since`, `--only`, `--ignore-changes`, `--cwd`. The command switches to the fynpo top directory.

Steps:

1. Errors out with `No commits in this repository. Please commit something before using changelog.` if the repo has no commits, and exits `1` on a detached HEAD (`Detached git HEAD, please checkout a branch to choose versions.`).
2. Change detection and release boundary (see Change detection). Prints `No changed packages to update changelog.` and returns when nothing changed.
3. Collates commits per package and determines bumps (see Version bumps).
4. Prompts (skipped without a TTY, in CI, or with `--no-cvb`):
   - Major: `OK to bump major versions? [y/N]`. Anything but `y` or `yes` stops the release with exit code `1`.
   - Minor: `Bump minor versions? [Y/n]`. `n` or `no` turns every minor bump into patch.
   - Indirect bumps (packages with no commits of their own, bumped by a dependency or lock): `Approve [a]ll, [s]elect, or [n]one? [A/s/n]`. Skipped packages are dropped from the changelog and get only a dependency range update in `prepare`. Lock groups get one answer. Input closed or Ctrl-C cancels with exit code `1`.
   - Without a terminal, minor and major bumps proceed with the bump types from the commit messages and a warning is logged.
5. Writes a new entry at the top of `CHANGELOG.md` (format below). If the entry equals the previous one apart from the date, nothing is written and `Changelog is already up to date; no changes to commit` is printed.
6. Commit: `git add <CHANGELOG.md> && git commit -n -m "Update changelog"`. Skipped (with a warning) when `--no-commit` or when the working tree is not clean.
7. With `--publish`: package.json versions are written and the commit is `[Publish]` instead (see `prepare` commit format).

CHANGELOG.md entry format:

```
# M/D/YYYY

## Packages

### Directly Updated        (only present when there are indirect bumps)

-   `name@1.2.3` `(1.2.2 => 1.2.3)`

### Fynpo Updated           (indirect bumps)

## Commits

-   `packages/<dir>`

    -   <commit subject> [commit](<repo-url>/commit/<sha>)
```

- Repo URL comes from the root `package.json` `repository.url` (trailing `.git` removed). Default text is `REPO_URL`. A trailing `(#123)` in a subject becomes a PR link.
- Commits excluded: subjects starting `Merge pull request #`, subjects containing `[no-changelog]`, reverted commits (with their reverts), and a commit named `Update changelog` that touches only the changelog file.
- Private packages and packages failing the publish filter get no `## Packages` line.
- Files outside any package are listed under their top-level directory, root files under `MISC`.

## `fynpo version`

```
fynpo version [--tag]
```

Same detection, collation and bump logic as `changelog`, with no prompts. It writes the changelog entry, bumps package.json versions and dependency ranges, then commits `CHANGELOG.md` and the package files as `[Publish]` (or `[Publish][Selective]`). Options: `--tag` (git tag `<name>@<version>` per package), `--commit`, `--force-publish`, `--since`, `--only`, `--ignore-changes`.

- Same no-commits and detached HEAD errors as `changelog`.
- `No changed packages to version` when nothing changed.
- It reads `CHANGELOG.md` relative to the process directory (it does not switch to the top directory), falling back to the top directory path with empty content.
- It reads `command.version`, `command.changelog`, `command.updated`, and `command.prepare` for option defaults.
- If no package ends up with a version (all private or filtered), it logs `No versions found in CHANGELOG.md` and the following commit step throws a TypeError. The same applies to `changelog --publish`.

## `fynpo prepare`

```
fynpo prepare [--force] [--tag] [--indirect-bumps] [--commit-msg <msg>]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--force` | | flag | off | Continue to bootstrap and hooks even when no version or dependency range changed. |
| `--tag` | | flag | off | Create a git tag `<name>@<version>` per released package. |
| `--indirect-bumps [bool]` | | boolean | unset (acts as true) | `--no-indirect-bumps` ignores the `### Fynpo Updated` section of the changelog. Those packages only get dependency range updates. Config key `indirectBumps: false` does the same. |
| `--commit-msg <msg>` | | string | none | Extra text appended to the `[Publish]` commit body after the package list. |

Plus `--commit`, `--only`, `--cwd`. The command switches to the fynpo top directory.

Steps and rules:

1. The working tree must be clean (`git status --porcelain --untracked-files=all`). Otherwise `PrepareError`: `Cannot prepare with a dirty working tree. Run 'git status --short' to inspect it. Commit or stash your changes first.`
2. Reads the newest changelog entry, the lines from the first `changeLogMarkers[0]` line to the first `changeLogMarkers[1]` line (default `## Packages` and `## Commits`). A package version is matched by the regex ``[ `]<name>@<x.y.z><suffix>[ `]``.
3. No versions found: logs `No versions found in CHANGELOG.md`, or `No packages were discovered, so nothing could be matched against CHANGELOG.md.` when discovery found nothing. It returns without an error code.
4. For each package whose changelog version differs from its package.json version: private packages are skipped with a warning. Otherwise `version` is set, `publishConfig.tag` is set from `command.publish.tags` / `versionTagging` (see Publish tags), and dependency ranges to every released package are rewritten.
5. Dependency range rewrite: sections `dependencies`, `optionalDependencies`, `peerDependencies`, `devDependencies`. A range starting with `^` or `~` keeps that prefix, an exact version stays exact, and ranges that start with anything else non-numeric (`*`, `>=`, `workspace:`...) are untouched.
6. Packages not being released get the same range rewrite but no version bump (warning `Updated <name> dependency range - not released, will bump next time`).
7. If nothing changed and `--force` is not set: `Nothing to update - every package already has the version CHANGELOG.md asks for`.
8. Writes package.json files, then bootstraps (full graph, ignoring `--only`, `--ignore` and `--scope`; repeats once if `.fynpo-data.json` changed), then runs the npm script `fynpo:prepare` in every package that has it (topological order, concurrency 6, bail, no cache). Failure of either raises `PrepareError` and no commit or tags are made.
9. Commits every changed tracked file and every untracked non-ignored file (`git add -- ...`, `git commit -n`). Skipped with a warning when `--no-commit` or the tree was unclean.
10. Commit format: first `-m` is `[Publish]` (or `[Publish][Selective]` when `--only` is used), second `-m` lists ` - <name>@<version>` lines, then any `--commit-msg`.
11. If HEAD is already an unpushed `[Publish]` commit with the identical package list, `git commit --amend` is used (no new commit). Existing tags pointing at the old commit are moved. A tag that already exists elsewhere raises `Cannot amend prepare: tag <tag> already points elsewhere.`
12. `--tag` creates the `<name>@<version>` tags sequentially.
13. Result messages: `Updated N package version(s) across M file(s)`, plus `committed`, `release commit amended`, `and K tag(s) created`, or `not committed`.
14. A `PrepareError` is logged as an error and sets exit code `1`.

## `fynpo publish`

```
fynpo publish [--dist-tag <tag>] [--dry-run] [--push]
```

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `--dist-tag <tag>` | string | none | Passed as `npm publish --tag <tag>` for every package. A per package `publishConfig.tag` in package.json is still honored by npm. |
| `--dry-run` | flag | off | Packs the tarballs and runs the scripts, skips `npm publish`. The release tag commands are prefixed with `echo DRY RUN` so no tag is created or pushed. Tarballs stay on disk. |
| `--push [bool]` | boolean | `true` | Push the release tag. `--no-push` creates the tag locally and prints the push command. |

Plus global config keys. `publish` accepts no `--only`, `--ignore` or `--commit` flags.

Flow:

1. Fails with exit `1` if `HEAD` already has a release tag matching the full or the `selective-` tag pattern (`HEAD commit already has a release tag...`).
2. Reads HEAD. If the commit message does not contain `[Publish]`, logs `Head git commit message doesn't have '[Publish]' - skip publish` and, because the list is empty, prints `No changed packages to publish!` and exits `1`.
3. A package is published only when all hold: its `package.json` changed in the HEAD commit, its `name` appears as a ` - name@version` line in the HEAD message body, it is not `"private": true`, and it passes the publish filter (see Publish jurisdiction).
4. A message containing `[Publish][Selective]` marks a selective release (see Tags).
5. Stale local dependency check (hard stop, see below).
6. Runs the root package.json `prepublishOnly` script (via fyn run), if defined.
7. In topological order, one package at a time: runs `prepublishOnly` (via `fyn run`), `npm pack`, then scripts `publish` and `postpublish`, each only when defined. `FYNPO_PUBLISH=1` is set in the environment while these scripts run, then restored.
8. Unless `--dry-run`, runs `npm publish [--tag <tag>] <tarball>` for each tarball in order and deletes the tarball on success. A failure where npm reports `EPUBLISHCONFLICT` (or `cannot publish over the previously published`) for the exact version being published is treated as already published: it is reported and does not count as a failure. If npm names a different conflicting version, it is a failure.
9. If any real failure happened: `Some packages failed to publish - skipping git release tag`, exit `1`.
10. Otherwise creates the annotated tag `git tag -a <tag> -m "Release Tag"`, then (with `--push`) `git push <remote> <tag>`. The remote is the branch upstream's remote, else `origin`, else the only remote, else none. With none: `Unable to determine a git remote - release tag <tag> created locally only`. Other thrown errors: `Failure encountered publishing packages`, exit `1`.

### Stale local dependency check

fyn installs a local package as a copy, so a rebuilt `dist` leaves consumers with the old copy until the next bootstrap. For every package to publish, fynpo compares each local dependency's source with the installed copy in `<pkg>/node_modules/<dep>`.

- Compared: a fixed set of manifest fields (`version`, `type`, `main`, `module`, `browser`, `types`, `typings`, `exports`, `imports`, `bin`, `dependencies`, `peerDependencies`, `optionalDependencies`, `engines`) and the bytes of every installed file (same inode counts as equal, `package.json` and `.map` files are skipped). Only copies that are fyn local links of that source are checked.
- `fynpo run` logs a warning: `WARNING: N local package(s) changed since installed - run 'fynpo bootstrap' to refresh`.
- `fynpo publish` exits `1` when any file differs. A manifest-only difference is a warning. Set `FYNPO_ALLOW_STALE_LOCAL_DEPS` (any non-empty value) to publish anyway.

## `fynpo init`

```
fynpo init [--commitlint]
```

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `--commitlint` | flag | off | Add commitlint setup. |

Steps:

1. Loads or creates config. With `--commitlint` and no config found, copies the template `fynpo.config.js` (includes the `commitlint` block). Otherwise creates `fynpo.json`.
2. Runs `git init` if the directory is not a git repo.
3. Requires a `package.json` in the config's directory. Missing: logs `Could not load package.json from the directory <dir>.` and exits `1`.
4. With `--commitlint`: adds `@commitlint/config-conventional` `^12.0.1` and `husky` `^5.1.3` (to `dependencies` when already there, else `devDependencies`) and appends `husky install` to `scripts.prepare`. Rewrites `package.json`. This also applies when a config with a `commitlint` key already exists.
5. With `--commitlint` and a JSON config without a `commitlint` key: writes `fynpo.config.js` (same content plus the generated commitlint block, formatted with prettier when installed) and asks you to delete the JSON file.
6. Creates `packages/`.
7. Prints next steps (`fyn`, and the husky hook command `npx husky add .husky/commit-msg 'npx --no-install fynpo commitlint --edit $1'` when `--commitlint` is set).

`init` searches upward for existing config. Run it in an empty directory to avoid modifying a parent repo.

## `fynpo commitlint`

```
fynpo commitlint [--config <path>] [--color] [--edit <file>] [--verbose]
```

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--config <path>` | | string | none | Config file to take lint fields from. Its top level keys are used (not a nested `commitlint` key). Without it, the `commitlint` key of the fynpo config is used. |
| `--color [bool]` | `-c` | boolean | `true` | Colored output. `--no-color` disables. |
| `--edit <file>` | `-e` | string | none | Read the message from this file via `@commitlint/read`. The option text says it falls back to `./.git/COMMIT_EDITMSG`. Without `--edit`, the message is read from stdin. |
| `--verbose` | `-V` | flag | off | Print reports for messages with no problems too. |

Behavior:

- Lint fields read: `extends`, `rules`, `plugins`, `parserPreset`, `formatter`, `ignores`, `defaultIgnores`, `helpUrl`. `extends` resolves with prefix `commitlint-config`. `formatter` defaults to `@commitlint/format`. Empty rules produce an `empty-rules` error.
- Empty input: logs `input is required.` and exits `1`. A missing formatter module: `Using format <name>, but cannot find the module.` exit `1`.
- Prints the formatted report. Exit code `1` when any message is invalid, otherwise `0`.
- The template header pattern is `/^\[([^\]]+)\] ?(\[[^\]]+\])? +(.+)$/` with parts `type`, `scope`, `subject`, so messages look like `[patch] fix thing`. The template rule allows types `patch`, `minor`, `major`, `chore` (level 2). Messages starting with `[Publish]` or containing `Update changelog` are ignored.

## Config file

### Location and format

fynpo searches from the working directory upward, up to 50 levels, and stops at the first directory that contains any of these, in this order:

1. `fynpo.config.js` (loaded with `require`; the module's `default` export is used when present)
2. `fynpo.config.json`
3. `fynpo.json`
4. `lerna.json`

A directory containing a file named `.no-fynpo` stops the search with no config. fynpo accepts any `lerna.json`. When it has no `fynpo` key, fynpo adds `"fynpo": true` and rewrites the file. The directory that holds the config file is the monorepo top directory. All relative paths and git commands use it as the working directory.

A JSON syntax error, or a `.js` config that throws, prints a framed `INVALID CONFIG FILE` or `CONFIG FILE FAILED TO LOAD` banner as a warning and exits `1`. `fyn` reads the same files with the same search.

All keys below are top-level keys of that file.

### Merge rules

- Each command builds its options as: config keys, overridden by parsed CLI options (including CLI defaults), with `cwd` set to the top directory.
- `changelog`, `version`, `updated`, `prepare`, `init` and `commitlint` additionally fill in missing keys from `command.<name>` (`version` also reads `command.changelog`, `command.updated`, `command.prepare`; `changelog` also reads `command.updated`). These fill only keys not already set, so a key that has a CLI default (`commit`, `confirmVersionBumps`) cannot be changed this way.
- `bootstrap`, `run`, `local` and `publish` do not read `command.<name>`.

### `packages`

Controls discovery and publish jurisdiction. Two shapes.

Array (legacy): `["packages/*", "samples/*"]`. Entries are additive `include` paths (auto-search stays on) and also become the publish allow list: each entry is a `path:` ref unless it starts with `id:`, `name:` or `path:`.

Object:

| Key | Type | Default | Behavior |
| --- | --- | --- | --- |
| `autoSearch` | boolean or object | on | `false` turns auto-search off. An object takes the keys below. Anything else (`true`, absent) is on. |
| `autoSearch.enable` | boolean | `true` | `false` turns auto-search off. |
| `autoSearch.respectGitignore` | boolean | `false` | When `true`, auto-search skips gitignored paths. Does not affect the publish veto. |
| `autoSearch.stopOnPackageJsonFound` | boolean | `true` | Auto-search stops descending below a found package.json (except paths matched by `include`). `false` also finds packages nested below other packages. |
| `include` | string or string[] | `[]`; `["packages/*"]` when auto-search is off | Minimatch patterns on package directories. With auto-search on they add packages found below package boundaries and mark them managed. With auto-search off they are the only scan paths. |
| `exclude` | string or string[] | `[]` | Minimatch patterns on package directories. Matching directories are not scanned and their package.json is not discovered. Applies in every mode. |
| `publishInclude` | string or string[] | `[]` | Publish allow list of package refs. Empty means every discovered package is eligible. Non-empty means only matching packages are. |
| `publishExclude` | string or string[] | `[]` | Publish deny list, applied after the allow list. It always wins. |

Blank or non-string entries are dropped. A single string is accepted for any list.

Top-level `patterns` (string array of minimatch patterns): when non-empty, scans exactly those patterns, auto-search off, and ignores `packages.include`. `packages.exclude` still applies.

Package refs (used by `publishInclude`, `publishExclude`, `versionLocks`, and `publishUtil` keys):

| Form | Matches |
| --- | --- |
| `name:<value>` or a bare `<value>` | package name |
| `id:<value>` or a bare value with `@` after position 0 | `name@version` |
| `path:<glob>` | package path from the top directory (minimatch) |
| `/<regex>/<flags>` as the value (for example `name:/^@scope\//`) | regex against the name, id or path, per the prefix |

An unknown prefix throws `package ref '<ref>' has unknown type '<x>' - must be 'id', 'path', or 'name'`. Path globs need the explicit `path:` prefix. A `:` splits the ref, so a value cannot contain a second `:`.

### `versionLocks`

`string[][]`: groups of package refs that always share one version bump. When any member changes, the whole group is pulled in with the highest bump in the group. `["*"]` (first element `*`) locks every package together at one repo-wide version bump (`lockAll`), and every managed package is treated as changed. A package in two groups logs `package <name> at <path> version is already locked`.

### Release keys

| Key | Type | Default | Behavior |
| --- | --- | --- | --- |
| `changeLogMarkers` | `[string, string]` | `["## Packages", "## Commits"]` | Lines bounding the package list in a changelog entry, read by `prepare`. |
| `indirectBumps` | boolean | true | `false` makes `prepare` skip the `### Fynpo Updated` section. |
| `versionCascade.bumpType` | `"patch"` or `"inherit"` | `"patch"` | How much of a dependency's bump a dependent takes. `patch` gives dependents a patch. `inherit` copies the dependency's bump type, except devDependencies which only patch. |
| `graduate` | string[] | `[]` | Package names (or `["*"]`) whose prerelease versions release as the plain version instead of the next prerelease. |
| `forcePublish` | string[] | `[]` | Same as `--force-publish`. |
| `ignoreChanges` | string[] | `[]` | Same as `--ignore-changes`. |
| `commitlint` | object | none | Lint config (see `commitlint`). Also read by version bump rules: `commitlint.minor` (default `["feat", "minor"]`), `commitlint.major` (default `["breaking", "major"]`), `commitlint.parserPreset.parserOpts`. |
| `noFynLocal` | string[] | `[]` | Package names never resolved as local packages in the graph. fyn reads this too. |
| `continueOnError` | boolean | false | See `run`. |
| `fynOpts` | string[] | none | Extra fyn CLI options for the install step of `prepare`'s bootstrap. |
| `resolutions` | object | none | Included in the build-cache input hash unless `input.includeResolutions` is `false`. fyn also reads it. |

### `command.publish`

| Key | Type | Default | Behavior |
| --- | --- | --- | --- |
| `gitTagTemplate` | string | `fynpo-rel-{YYYY}{MM}{DD}-{COMMIT}` | Release tag template. See Tags. |
| `tags` | object | `{}` | npm dist-tag assignment per package. See Publish tags. |
| `versionTagging` | object | `{}` | Keys are package names. Publishes each under tag `ver<major>`. |
| `allowForeignRepos` | boolean | false | Allow releasing packages that live in a nested git repo. Default skips them with a warning. |

### `command.bootstrap`, `publishUtil`, `fyn`, `centralDir`, `overrides`

These are read by fyn, not by the fynpo CLI, when fyn runs inside a fynpo repo:

- `command.bootstrap.npmRunScripts`: string, string array, or array of arrays (run the first existing script of each sub array), or `false`. Scripts fyn runs after install in a monorepo package. Default `["build"]`.
- `fyn.options`: object of fyn options applied to every fyn run. Precedence is CLI over rc over this block. `cwd` and `initCwd` are ignored, and the script policy keys (`allowScripts`, `denyScripts`, `allowTopLevelScripts`, `scriptPolicy`, `reviewLocalPackages`) have their own merge.
- `centralDir`: central package store path. Default `<top>/.fynpo/_store` (the main worktree's `.fynpo/_store` in a git linked worktree).
- `resolutions`, `overrides`: dependency overrides applied to all packages.
- `publishUtil`: object keyed by package ref, giving per package publish-util config. First matching ref wins.

## Caching

Caches the output of bootstrap (per package install and build) and of `fynpo run --cache`. Local and optional remote storage.

### Where rules are read

| Key | Used by | Notes |
| --- | --- | --- |
| `packageCache.default` | `bootstrap` | Label `bootstrap`. Caching runs only when this object is non-empty. |
| `lifecycleCache.default` | `run --cache` | Label `run-<script>`. Needs `--cache` and a non-empty object. `lifecycleCache.default.requireDeps: false` skips the automatic install. |

A cache rules object has `input` and `output`. `output` is required, otherwise copying to cache throws a TypeError (swallowed by the caller, no cache is saved).

`input`:

| Key | Type | Behavior |
| --- | --- | --- |
| `include` | string or string[] | Minimatch patterns of files to hash. No `include` means no files are hashed. |
| `exclude` | string or string[] | Patterns to drop after `include`. |
| `npmScripts` | string or string[] | `package.json` script names whose text is part of the hash. |
| `includeEnv` | string or string[] | Environment variable names and values in the hash. |
| `includeVersions` | string or string[] | Keys of `process.versions` to include (for example `node`). |
| `includeResolutions` | boolean | Default true. `false` leaves the config `resolutions` out. |
| `minimatchOptions` | object | Passed to minimatch. Default `{ "dot": true }`. |

`output`:

| Key | Type | Behavior |
| --- | --- | --- |
| `include`, `exclude`, `minimatchOptions` | as above | Files to store after the build. |
| `filesFromNpmPack` | boolean | Add the file list `npm pack` would produce, minus `exclude`. |

The input hash (sha256, base64url) covers the selected input files' hashes, env, versions, scripts, `resolutions`, the label, and for each local dependency its recorded input and output hashes. If any local dependency has no recorded cache meta, the package does a full build (`doing full build in '<path>'. missing cache meta for its dep`).

### `caching`

| Key | Type | Default | Behavior |
| --- | --- | --- | --- |
| `enable` | boolean | `true` | `false` disables caching. |
| `dir` | string | per-user cache dir for `fynpo` from `env-paths` | Local cache root. Layout `<dir>/<label>/<package name>/<inputHash>.json` and `files/<hash><ext>`. |
| `server` | string | none | Remote cache base URL. A trailing `/` is added. Meta is read from `<server><label>/<segmented hash>.json`. |
| `compression` | `"brotli"` or `"gzip"` | none (uncompressed) | Compress stored files (`.br`, `.gz`). Any other value throws `fynpo caching: unknown compression algorithm <x>`. |
| `alwaysUploadToRemote` | boolean | false | Upload to the remote outside CI. Without it uploads happen only in CI. |
| `pruning.highCount` | number | `20` | Prune when a package's cache dir has more than this many entries. |
| `pruning.keepCount` | number | `10` | Keep this many most recently accessed entries when pruning. |

Behavior:

- Local lookup first, then remote when `server` is set (10 s timeout). A hit restores the output files into the package, verifying hashes of uncompressed files. A restore failure logs `Failed restore from cache ... doing full bootstrap` and builds normally.
- Remote uploads use `PUT` and retry with `POST` after a `405`. The first remote failure logs once (`remote cache server failure`) and disables further remote calls in that process.
- Cache meta for dependents is kept in `<top>/.fynpo/_cache-meta/<label>/`.
- On a miss with earlier meta, a diff is written to `<package>/<label>-cache-diff.log`.

## Discovery

Packages are directories with a `package.json` that has a `name`.

1. Auto-search (default): scans the whole tree below the top directory. Skipped: `node_modules`, directories starting with `.`, the top level `package.json`, a `package.json` in a directory that also contains `fynpo.json` (a nested fynpo root), and paths matched by `packages.exclude`. With `respectGitignore: true`, gitignored paths are skipped too.
2. By default it stops descending below a found package. A package found under another package is `nested`. Nested packages are kept only when `include` matches them, and then they are managed.
3. With auto-search off: only directories matching `include` (default `packages/*`) are scanned.
4. A `package.json` with `"fynpo": false` is dropped. One without `name` is skipped.
5. Packages not managed (nested, not matched by `include`) join the graph and are bootstrapped, but `run`, changed-package detection, changelog, version, and publish skip them.
6. A package outside the repo's git ownership (a nested clone, submodule, or linked worktree with its own `.git`) cannot be released from this repo. It is skipped with a warning unless `command.publish.allowForeignRepos` is `true`.
7. Auto-search is announced when used: `Auto-search is enabled; "packages" include paths add to discovered packages - found N.` at info level, or a warning when N is zero.

The same name may exist at several paths. Within a name, versions sort newest first, managed before unmanaged, then by path. Release commands use the first managed copy.

Local dependency resolution: a dependency name in `dependencies`, `devDependencies` or `optionalDependencies` that is a local package resolves to the local copy whose version satisfies the range, or the first copy when none does. `peerDependencies` are never resolved. A name in `noFynLocal`, or a package.json `fyn.<section>.<name>` set to `false` or a string containing `no-fyn-local`, resolves from the registry. A `.fynpo-data.json` file at the top directory (written by fyn, key `indirects`) adds indirect relations.

## Selection

`--only`, `--ignore`, `--scope` for `bootstrap`, `local`, `run`:

- Entries match package name, path, or `name@version`.
- `ignore` drops a package at any depth, including as a dependency of a selected package.
- `only` applies to the top level of the selection. The selected packages' local dependencies are included transitively.

For releases (`updated`, `changelog`, `version`, `prepare`) `--only` makes a selective release:

- Names must exist, else `--only names packages that do not exist here: <names>` and exit `1`.
- The selection expands across `versionLocks` groups.
- The commit subject is `[Publish][Selective]`, and tags use the `selective-` prefix, so the changelog boundary stays at the last full release.
- Commits already covered by an earlier selective release are not counted again for the packages it listed.

## Topological ordering

- Order is by local dependencies from `dependencies` and `devDependencies`. `optionalDependencies` and `peerDependencies` edges are ignored for ordering.
- Packages with no local dependencies come first. Cycle members are detected, then ordering is recomputed ignoring edges to cycle members so they still get scheduled. A cycle is logged as `detected circular deps a > *b*`.
- `bootstrap`, `run` (with sort), and `publish` use it. Concurrency applies within the constraint that a package waits for its pending dependencies.

## Change detection

Used by `updated`, `changelog`, `version`.

1. Boundary: `--since <ref>` when given. It must resolve to a commit and be an ancestor of HEAD, else `Invalid --since Git ref '<ref>': it must resolve to a commit.` or `--since Git ref '<ref>' resolves to <sha>, which is not an ancestor of HEAD.` Otherwise the latest release tag: `git describe --tags --long --first-parent --match <pattern>`, retried without `--first-parent`. `<pattern>` is `gitTagTemplate` with every `{token}` replaced by `*`.
2. No matching tag (and no tags at all): every publishable package counts as changed and all commits are in range.
3. Tags exist but none match the template: fynpo looks for a `[Publish]` commit that has tags. On a TTY it asks `Use this commit as the release boundary? [y/N]`. In CI or without a TTY, or if declined or none found, it throws with a message telling you to pass `--since <ref>`.
4. No commits since the boundary and no `--force-publish`: `No commits since previous release. Skipping change detection`.
5. A package changed when `git diff --name-only <boundary>...HEAD -- <path>` lists a file not removed by `ignoreChanges`.
6. Added to the changed set: force-published packages, members of version lock groups, and dependents of changed packages (when the dependent passes the publish filter). `--force-publish *` or `versionLocks: ["*"]` makes every publishable package changed.
7. Only packages that pass the publish filter, are managed, and are not in a foreign repo are considered. `Excluded N package(s) from publishing` is logged.

## Version bumps

Per package, from its commits since the boundary. The highest wins.

| Bump | Trigger |
| --- | --- |
| major | header `type` in `commitlint.major` (default `breaking`, `major`), or the message contains `[maj` |
| minor | header `type` in `commitlint.minor` (default `feat`, `minor`), or the message contains `[min` |
| patch | everything else |

Header parsing uses `commitlint.parserPreset.parserOpts` (`headerPattern`, `headerCorrespondence`), defaulting to `/^\[([^\]]+)\] ?(\[[^\]]+\])? +(.+)$/` with `type, scope, subject`.

Then:

- Version lock group members take at least the bump of the member that changed.
- Dependents of a bumped package are bumped too (`versionCascade.bumpType`): a patch by default.
- `versionLocks: ["*"]` bumps every package to the highest bump found.
- The new version is computed from the package's `major.minor.patch`. A prerelease version increments its prerelease counter, unless the package is in `graduate`.

### Publish tags

`command.publish.tags` is an object keyed by dist-tag name. Tag names must match `[0-9A-Za-z-]+`, else `tag <name> invalid. Only [0-9A-Za-z-] characters allowed.`

```json
{ "command": { "publish": { "tags": { "next": { "enabled": true, "addToVersion": true, "packages": { "pkg-a": true } } } } } }
```

| Key | Behavior |
| --- | --- |
| `enabled` | `false` skips this tag. |
| `packages` | Object of package name to boolean. Required. A package must be listed. `true` sets `publishConfig.tag` to this tag. `false` removes `publishConfig.tag` (publishes as `latest`). |
| `addToVersion` | For `true` packages with a tag other than `latest`: new versions become `<version>-<tag>.0`, or the next prerelease number when already on that tag. |
| `regex` | Read, but only consulted when the package key exists with an undefined value, which JSON cannot express. It has no effect from a config file. |

`versionTagging`: a package listed there gets `publishConfig.tag` of `ver<major>`. Listing a package in both `tags` and `versionTagging` fails with `package <name> has both tag and versionTagging`.

## Tags

### Release tag

`gitTagTemplate` replaces tokens with the current local time. Unknown tokens throw `unknown token '<tok>' in command.publish.gitTagTemplate - valid tokens are: ...`.

| Token | Value |
| --- | --- |
| `{YYYY}` | four digit year |
| `{MM}` | two digit month |
| `{DD}` | two digit day |
| `{hh}`, `{mm}`, `{ss}` | two digit hour (24h), minute, second |
| `{COMMIT}` | first 8 characters of the HEAD short hash (`git log --format=%h -n 1`) |

Default: `fynpo-rel-{YYYY}{MM}{DD}-{COMMIT}`. Selective releases prefix the tag with `selective-`. The prefix keeps `git describe --match fynpo-rel-*` from finding them.

### Package tags

With `--tag`, `prepare`, `version`, and `changelog --publish` create a lightweight tag `<name>@<version>` per released package.

## Publish jurisdiction

A package can be published only when all hold: not `"private": true`, managed, not gitignored, matches `publishInclude` when that list is non-empty, and does not match `publishExclude`. The gitignore veto uses the root `.gitignore` and `.git/info/exclude` only (not nested `.gitignore` files or the global excludes file). It cannot be lifted by `publishInclude` and is independent of `respectGitignore`. The same filter limits changed-package detection, the changelog, version bumps, and `publish`. It does not affect `bootstrap`, `run`, or discovery.

## Environment variables

| Variable | Direction | Behavior |
| --- | --- | --- |
| `CI` (and other vars detected by `ci-info`) | read | Prints `CI env detected` to stderr and disables the log item type. Adds `--pg simple` to fyn installs. Prints full output on bootstrap failures. Disables interactive prompts. Enables remote cache uploads. |
| `FYNPO_PUBLISH` | set | `1` while `publish` runs package `prepublishOnly`, `publish` and `postpublish` scripts. Lets guards such as `publish-util` accept the call. |
| `FYNPO_ALLOW_STALE_LOCAL_DEPS` | read | Any non-empty value lets `publish` continue with stale local dependency copies. |

fynpo sets `PWD` to the working directory for shell commands it runs.

## Files fynpo reads and writes

| File | Behavior |
| --- | --- |
| `fynpo.json`, `fynpo.config.js`, `fynpo.config.json`, `lerna.json` | Config. `fynpo.json` is created when no config exists. |
| `CHANGELOG.md` | Written at the top by `changelog` and `version`. Read by `prepare`. |
| `.fynpo-data.json` | Written by fyn (`indirects`, `__timestamp`). Read by every command. Commit it. |
| `fynpo-debug.log` | Written by `bootstrap` on failure or with `--save-log`. |
| `.fynpo/_cache-meta/`, `<package>/<label>-cache-diff.log` | Cache bookkeeping. |

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Success. Also `local`, `updated`, and a `prepare` that found nothing to do. |
| `1` | `bootstrap` failure, `run` caught exception, failed config load, `publish` failure or refusal, `commitlint` invalid or empty message, `init` without package.json, a declined major bump, detached HEAD, unknown `--only` package, `PrepareError`, uncaught error. |
| script code | `run` exits with the highest failing package script exit code (at least `1`). |

<!-- @fynpo/base v2.1.12: https://fynjs.pages.dev/ref/fynpo-base.md -->

# @fynpo/base reference

`@fynpo/base` is the shared core of fynpo and fyn. It loads fynpo config files, discovers the packages of a monorepo, builds the local dependency graph with topological sort, and provides the file-hash helpers behind build caching. ESM only (`"type": "module"`), Node `^22.22.2 || ^24.15.0 || >=26.0.0`.

## Imports

```js
import { FynpoConfigManager, FynpoDepGraph, resolvePackagesConfig, caching } from "@fynpo/base";
import * as base from "@fynpo/base";
```

Everything is a named export from the package root. There is no default export. The only subpath is `@fynpo/base/package.json`.

Runtime exports: `getDepSection`, `makeDepStep`, `pkgId`, `pkgInfoId`, `PackageRef`, `FynpoDepGraph`, `FynpoConfigManager`, `FynpoConfigError`, `isFynpoConfigError`, `formatFynpoConfigError`, `resolvePackagesConfig`, `packageScope`, `outOfScopePackages`, `scanPatterns`, `includeFilter`, `makeGitignoreMatcher`, `posixify`, `writeJson`, `writeJsonSync`, `readJson`, `readJsonSync`, `readPkgJson`, `readPkgJsonSync`, `caching` (namespace: `readHashDigest`, `processInput`, `processLifecycleInput`, `processOutput`).

Type-only exports: `PackageBasicInfo`, `DEP_SECTIONS`, `PackageDepRef`, `PackageDepRelation`, `FynpoPackageInfo`, `FynpoPackages`, `FynpoTopoPackages`, `PackageDepData`, `ReadFynpoOptions`, `ConfigOptions`, `AutoSearchConfig`, `PackagesConfig`, `GitignoreMatcher`.

Not exported: the helpers in `minimatch-group` (`groupMM`, `deconstructMM`, `checkMmMatch`, `unrollMmMatch`, type `MMGroups`), the type `PackageRefType`, and the caching rule types (`CacheInputRule`, `CacheOutputRule`, `CacheBaseRule`, `FilesFilterPatterns`). The caching rule types appear in signatures but cannot be imported by name. The old discovery API (`PackageInfo`, `readFynpoPackages`, `makePkgDeps`) no longer exists.

## Config loading

### `FynpoConfigManager`

```ts
type ConfigOptions = {
  cwd?: string;
  configPath?: string;
  allowLernaWithoutFynpo?: boolean;
};

class FynpoConfigManager {
  constructor(opts?: ConfigOptions);
  load(): Promise<any>;
  loadSync(): any;
  get config(): any;
  get repoType(): string | undefined;
  get cwd(): string | undefined;
  get topDir(): string | undefined;
  get fileName(): string | undefined;
  get filePath(): string | undefined;
}
```

Finds and loads a fynpo (or lerna) config. `load()` and `loadSync()` return the loaded config object, or `undefined` when none was found. Both only load when no config is held yet, so after a successful load later calls return the same object. After a failed search (nothing found) they search again.

| option | type | default | behavior |
| --- | --- | --- | --- |
| `cwd` | `string` | `process.cwd()` | Where the upward search starts. Also the base for resolving a relative `configPath`. |
| `configPath` | `string` | none | Load exactly this file and skip the search. |
| `allowLernaWithoutFynpo` | `boolean` | none (falsy) | Accept a `lerna.json` that has no `fynpo` field. |

Getters:

| getter | value |
| --- | --- |
| `config` | the loaded config, `undefined` before loading or when none was found |
| `repoType` | `"fynpo monorepo"`, `"lerna monorepo with fynpo"`, or `"lerna monorepo"`. `undefined` when none was found |
| `cwd` | `options.cwd` |
| `topDir` | directory that holds the config file. `undefined` when the search found nothing |
| `fileName` | base name of the loaded file, such as `fynpo.config.js` |
| `filePath` | absolute path of the loaded file |

Search (when `configPath` is not set). Starting at `cwd`, for each directory, in this order:

1. If a file named `.no-fynpo` exists, stop the search. Nothing is loaded and `topDir` is `undefined`.
2. `fynpo.config.js`. The config is `module.default ?? module`.
3. `fynpo.config.json`.
4. `fynpo.json`.
5. `lerna.json`, accepted only if it has a truthy `fynpo` field or `allowLernaWithoutFynpo` is set. `repoType` is `"lerna monorepo with fynpo"` when `fynpo` is truthy, else `"lerna monorepo"`. A `lerna.json` that is rejected does not stop the search.

Then move to the parent directory. The search stops at the filesystem root or after 50 directories. Files that do not exist are skipped.

Explicit `configPath`:

- `topDir`, `fileName` and `filePath` are set from the resolved path before the file is read, even if the file turns out to be missing.
- A path ending in `.js`, `.cjs` or `.mjs` is loaded as code (`default ?? module`, `repoType` `"fynpo monorepo"`). If the JS file does not exist, `config` stays `undefined` and nothing is thrown.
- Any other extension is read as JSON. `repoType` is `"lerna monorepo"` when the file name is `lerna.json`, else `"fynpo monorepo"`. A missing JSON file throws the raw ENOENT error, not `FynpoConfigError`.

Sync versus async:

- `load()` imports JS configs with `optional-import` (works for ESM and CJS). `loadSync()` uses `require`, so an ESM-only config relies on the running Node supporting `require` of ESM.
- Errors are the same in both flavors.

Errors:

- A config file that exists but is invalid JSON throws `FynpoConfigError` (no `cause`).
- A JS config that throws while loading throws `FynpoConfigError` with `cause` set to the original error.
- A missing file is never an error during the search. It is skipped.
- Other JSON read failures (for example permissions) are also wrapped in `FynpoConfigError`, since only `ENOENT` is treated as absent.

### `FynpoConfigError`

```ts
class FynpoConfigError extends Error {
  readonly code: "FYNPO_BAD_CONFIG";
  readonly filePath: string;
  readonly reason: string;
  readonly cause?: Error;
  constructor(filePath: string, reason: string, cause?: Error);
}
```

`name` is `"FynpoConfigError"`. `message` is `Failed to load <filePath> - <reason>` when `cause` is given, else `Failed to read JSON file <filePath> - <reason>`. `reason` is the underlying error message.

### `isFynpoConfigError`

```ts
function isFynpoConfigError(err: unknown): err is FynpoConfigError
```

True when `err` is truthy and `err.code === "FYNPO_BAD_CONFIG"`. Prefer this over `instanceof`: fyn and fynpo each bundle their own copy of the class, so an error crossing between them is not an instance of the local class.

### `formatFynpoConfigError`

```ts
function formatFynpoConfigError(err: FynpoConfigError, cmdName: string): string
```

Returns a multi-line banner string (72 `=` bars, `file:` and `error:` lines). Does not print anything. `cmdName` is the CLI name shown in the text. With `err.cause` set, the title is `CONFIG FILE FAILED TO LOAD` and the banner includes the cause stack (or `String(cause)`). Without a cause, the title is `INVALID CONFIG FILE` and the text says the file is not valid JSON.

## Packages config

### `resolvePackagesConfig`

```ts
type AutoSearchConfig = {
  enable: boolean;
  respectGitignore: boolean;
  stopOnPackageJsonFound: boolean;
};

type PackagesConfig = {
  autoSearch: AutoSearchConfig;
  include: string[];
  exclude: string[];
  publishInclude: string[];
  publishExclude: string[];
};

function resolvePackagesConfig(packages?: unknown): PackagesConfig
```

Normalizes the raw `packages` value from a fynpo config into a fully populated `PackagesConfig`. Never throws.

Array form (`packages: ["packages/*"]`):

- `include` is the cleaned list. `publishInclude` is the same list with each entry prefixed `path:` unless it already starts with `id:`, `name:` or `path:`.
- `autoSearch` is `{ enable: true, respectGitignore: false, stopOnPackageJsonFound: true }`.
- `exclude` and `publishExclude` are `[]`.

Object form (also anything else, including `undefined`, which acts as `{}`):

| field | type | default | behavior |
| --- | --- | --- | --- |
| `autoSearch` | `boolean \| object` | on | `false` gives `{ enable: false, respectGitignore: false, stopOnPackageJsonFound: true }`. An object gives `enable: obj.enable !== false`, `respectGitignore: obj.respectGitignore === true`, `stopOnPackageJsonFound: obj.stopOnPackageJsonFound !== false`. Anything else (including `true`, `undefined`) gives `{ enable: true, respectGitignore: false, stopOnPackageJsonFound: true }`. |
| `include` | `string \| string[]` | `[]` | If auto-search is disabled and the cleaned list is empty, becomes `["packages/*"]`. |
| `exclude` | `string \| string[]` | `[]` | |
| `publishInclude` | `string \| string[]` | `[]` | Not prefixed in object form. Entries are `PackageRef` strings. |
| `publishExclude` | `string \| string[]` | `[]` | |

List cleaning: a bare string becomes a one-item list. Non-string and blank entries are dropped. Entries are trimmed. A non-array, non-object `packages` (for example a string) is treated as `{}`.

### `packageScope`

```ts
function packageScope(name: string): string | undefined
```

Returns the npm scope including `@` (for `@fynjs/x` returns `"@fynjs"`). Returns `undefined` for unscoped names, an empty name, or a name starting with `@` with no `/` after position 0.

### `outOfScopePackages`

```ts
function outOfScopePackages(scopes: unknown, names: string[]): string[]
```

Returns the names in `names` that are outside the given scopes (the ones a `--scope` option should exclude).

- `scopes` may be a string or array. Entries are trimmed, blanks dropped, and `@` is prefixed when missing.
- Returns `[]` when no usable scope is given.
- An unscoped name is always returned once any scope is given.

### `scanPatterns`

```ts
function scanPatterns(config: PackagesConfig): string[] | null
```

Returns `null` when `config.autoSearch.enable` is true (meaning scan the whole repo). Otherwise returns `config.include`, or `["packages/*"]` when `include` is empty. `include` alone never turns auto-search off.

### `includeFilter`

```ts
function includeFilter(config: PackagesConfig): string[]
```

Returns `config.include`. These patterns add nested paths as managed packages when auto-search is on, and restrict discovery when it is off.

## Gitignore

### `makeGitignoreMatcher`

```ts
type GitignoreMatcher = {
  ignores(relPath: string): boolean;
  hasRules: boolean;
};

function makeGitignoreMatcher(cwd: string): GitignoreMatcher
```

Builds a matcher from `<cwd>/.gitignore` and `<cwd>/.git/info/exclude`. Nested `.gitignore` files and the global excludes file are not read. Does not run git.

- Missing files (`ENOENT`, `ENOTDIR`) are skipped. Any other read error is thrown.
- When neither file exists (or both are empty strings), the returned matcher has `hasRules: false` and `ignores` always returns `false`. Otherwise `hasRules` is `true`.
- `ignores(relPath)` takes a repo-relative path. It returns `false` for empty, `"."`, absolute paths, and paths starting with `..`. It converts the platform separator to `/` and strips a leading `./`, then applies the rules (npm `ignore` semantics).

## Package graph

### `FynpoDepGraph`

```ts
class FynpoDepGraph {
  packages: FynpoPackages;
  depMapByPath: Record<string, PackageDepData>;
  resolvedCache: Record<string, string>;
  autoSearched: boolean;
  _options: ReadFynpoOptions;

  constructor(options?: ReadFynpoOptions);
  resolve(indirects?: boolean): Promise<void>;
  updateDepMap(): void;
  readPackages(): Promise<FynpoPackages>;
  addPackageByFile(pkgFile: string, management?: { managed?: boolean; nested?: boolean }): Promise<FynpoPackageInfo | undefined>;
  addPackage(pkgJson: Record<string, any>, pkgPath: string, pkgStr?: string, management?: { managed?: boolean; nested?: boolean }): FynpoPackageInfo | undefined;
  updateAuxPackageData(): void;
  resolvePackage(name: string, semver: string, fallbackToFirst?: boolean): FynpoPackageInfo;
  checkNoFynLocal(pkgInfo: FynpoPackageInfo, depName: string): boolean;
  addDepByPath(from: string, to: string, depSection: DEP_SECTIONS, indirectSteps?: string[]): void;
  addDepById(from: string, to: string, depSection: DEP_SECTIONS, indirectSteps?: string[]): void;
  addDepRelations(relations: PackageDepRelation[]): void;
  addDep(pkgInfo: FynpoPackageInfo, depPkg: FynpoPackageInfo, depSection: DEP_SECTIONS, indirectSteps?: string[]): boolean;
  checkCircular(pkgInfo: FynpoPackageInfo, depPkg: FynpoPackageInfo): boolean;
  getTopoSortPackagePaths(avoidCircs?: boolean): { noCircSorted: string[]; sorted: string[]; circulars: string[] };
  getTopoSortPackages(): FynpoTopoPackages;
  getPackageAtDir(dir: string): FynpoPackageInfo;
  getPackageByName(name: string): FynpoPackageInfo;
}
```

Typical use:

```js
const graph = new FynpoDepGraph({ cwd: topDir, packages: config.packages });
await graph.resolve();
const { sorted, circulars } = graph.getTopoSortPackages();
```

Constructor options:

```ts
type ReadFynpoOptions = {
  patterns?: string[];
  cwd?: string;
  noFynLocal?: string[];
  packages?: unknown;
};
```

| option | type | default | behavior |
| --- | --- | --- | --- |
| `cwd` | `string` | `process.cwd()` | Monorepo top dir. Package paths are relative to it. |
| `patterns` | `string[]` | none | Explicit scan patterns (minimatch). When non-empty they override `scanPatterns` and `include` from `packages`: scanning is limited to those patterns, auto-search is off, and `include` is not applied. `packages.exclude` still applies. |
| `packages` | `unknown` | none | Raw `packages` config, passed to `resolvePackagesConfig`. Drives discovery. |
| `noFynLocal` | `string[]` | none | Dependency names never resolved as local packages. |

Fields:

| field | meaning |
| --- | --- |
| `packages` | `{ byName, byPath, byId }`, see `FynpoPackages`. |
| `depMapByPath` | dep data per package path. Filled by `resolve()`. |
| `resolvedCache` | cache from `name@<semver>` to the resolved `name@version`. |
| `autoSearched` | set by `readPackages()`: `true` when the scan was an auto-search of the whole repo. `undefined` before. |

#### `resolve`

`resolve(indirects = false)`: if `packages.byName` is empty it calls `readPackages()`, then resolves direct local deps into `depMapByPath`. With `indirects: true` it also resolves indirect deps. Topological sort needs only direct deps.

Direct dep resolution looks at `dependencies` (`dep`), `devDependencies` (`dev`) and `optionalDependencies` (`opt`) of each package. `peerDependencies` are not resolved into the graph. A dependency name is local when some discovered package has that name. When several versions exist, the first one satisfying the semver wins, else the first in `byName` (highest version) is used. A dependency is skipped when `checkNoFynLocal` is true. Because a name match always links (falling back to the first version), a dep whose range matches no local version is still linked.

#### `updateDepMap`

Runs direct and then indirect dep resolution. Safe to call repeatedly. Use it after adding packages or relations by hand.

#### `readPackages`

Scans the repo and returns `this.packages`. Does not reset `packages`, so calling twice adds duplicate entries by name. Rules:

- The top dir `package.json` is never a package. A directory containing a `fynpo.json` is skipped. `node_modules` is never entered.
- With auto-search on (default), the whole repo is walked, and directories starting with `.` are skipped. With `stopOnPackageJsonFound` true, anything below a found package is skipped unless `include` patterns match it. A package found below another is `nested: true`, and is `managed` only if an `include` pattern matches it.
- With auto-search off, only paths matching the scan patterns (`include` or `["packages/*"]`, or `patterns`) are packages. Those are all `managed: true`, `nested: false`.
- `packages.exclude` patterns exclude directories and packages in both modes. With `respectGitignore` on and auto-search on, gitignored paths are skipped. Auto-search is the only mode that honors `respectGitignore`.
- A `package.json` with `"fynpo": false` or with no `name` is ignored.
- A `package.json` that is not valid JSON throws the `JSON.parse` error (not `FynpoConfigError`).
- Insertion order is lexical by `package.json` path. `updateAuxPackageData()` runs at the end.

`publishInclude` and `publishExclude` are not consulted by this class. They are for callers.

#### `addPackageByFile`

Reads `<cwd>/<pkgFile>`, parses it and calls `addPackage` with the posix directory of `pkgFile`. Does not call `updateAuxPackageData`. Throws on a missing file or invalid JSON.

#### `addPackage`

Adds one package to `packages.byName` and returns its `FynpoPackageInfo`.

- Returns `undefined` when `pkgJson.fynpo === false`.
- Throws an `assert` error `package at <pkgPath> doesn't have name` when there is no `name`.
- `pkgPath` must use `/`.
- `management.managed` is `true` unless set to `false`. `management.nested` is `false` unless set to `true`.
- It does not update `byPath` or `byId`. Call `updateAuxPackageData()` afterwards.
- `pkgDir` is `pkgJson.name` when the name is scoped and `pkgPath` ends with `/<name>` or equals it, else the last segment of `pkgPath`.

#### `updateAuxPackageData`

Rebuilds `byId` and `byPath` from `byName`. Sorts each `byName` list by version, newest first. On equal versions, managed packages come before unmanaged ones, then by path. For `byId`, a managed package replaces an unmanaged one with the same id. Otherwise the first in sort order wins.

#### `resolvePackage`

Looks up `name` in `byName` and returns the first version satisfying `semver`. If none satisfies and `fallbackToFirst` is `true` (default), returns the first (highest version) entry. Returns `undefined` when the name is unknown, or when nothing matches and `fallbackToFirst` is `false`.

#### `checkNoFynLocal`

Returns `true` when `depName` is in `options.noFynLocal`, or when the package's `pkgJson.fyn` has, in `dependencies`, `devDependencies` or `optionalDependencies`, an entry for `depName` that is `false` or a string containing `no-fyn-local`. Otherwise `false`.

#### `addDep`, `addDepByPath`, `addDepById`, `addDepRelations`

- `addDep` records the dependency in `depMapByPath[from].localDepsByPath[to.path]` and the reverse in `depMapByPath[to].dependentsByPath[from.path]`, then runs `checkCircular`. Returns `false` (no change) for a self dependency or an existing relation, `true` when added. `depMapByPath` entries must already exist for both packages (created by `resolve()`), else it throws a `TypeError`. `indirectSteps`, if given, is stored on both records.
- `addDepByPath` and `addDepById` look the packages up in `byPath` or `byId`. They do nothing when either is missing and return nothing.
- `addDepRelations` calls `addDepByPath` for each `PackageDepRelation`, using `fromPkg.path` and `onPkg.path`.

#### `checkCircular`

If `depPkg` already depends on `pkgInfo`, records `depPkg.path` in `depMapByPath[pkgInfo.path].pathOfCirculars` (no duplicates) and returns `true`. Otherwise returns `true` only when `depPkg` has a non-empty `pathOfCirculars`, else `false`.

#### `getTopoSortPackagePaths` and `getTopoSortPackages`

`getTopoSortPackagePaths(avoidCircs = false)` returns arrays of package paths. `getTopoSortPackages()` returns the same three lists as `PackageDepData` objects.

- Dependencies first: a package comes after all its local deps. Only `dep` and `dev` relations count. `opt` and `peer` are ignored.
- `noCircSorted`: packages that sort without cycles.
- `circulars`: paths still unsorted (part of or behind a cycle).
- `sorted`: all packages. When there are circulars, each gets `hasCircular = true` on its dep data, and the sort is redone ignoring relations to those packages.
- Requires `resolve()` to have filled `depMapByPath`. With no resolve, all lists are empty.
- Tie order is not specified beyond the above.

#### `getPackageAtDir`

Returns the package whose path equals `dir`. An absolute `dir` is made relative to `cwd`. Returns `undefined` when none.

#### `getPackageByName`

Returns the first entry in `byName[name]` (highest version), or `undefined`.

### Types

```ts
type PackageBasicInfo = {
  name: string;
  version: string;
  /** path from monorepo top dir, always `/`, unique per package */
  path: string;
};

type DEP_SECTIONS = "dep" | "dev" | "opt" | "peer";

type PackageDepRef = PackageBasicInfo & {
  depSection: DEP_SECTIONS;
  indirectSteps?: string[];
};

type PackageDepRelation = {
  fromPkg: PackageBasicInfo;
  onPkg: PackageBasicInfo;
  depSection: DEP_SECTIONS;
  indirectSteps?: string[];
};

type FynpoPackageInfo = PackageBasicInfo & {
  dependencies: Record<string, string>;
  devDependencies: Record<string, string>;
  optionalDependencies: Record<string, string>;
  peerDependencies: Record<string, string>;
  private: boolean;
  managed: boolean;
  nested: boolean;
  pkgDir: string;
  pkgStr: string;
  pkgJson: Record<string, unknown>;
};

type FynpoPackages = {
  byName: Record<string, FynpoPackageInfo[]>;
  byPath: Record<string, FynpoPackageInfo>;
  byId: Record<string, FynpoPackageInfo>;
};

type PackageDepData = {
  pkgInfo: FynpoPackageInfo;
  localDepsByPath: Record<string, PackageDepRef>;
  dependentsByPath: Record<string, PackageDepRef>;
  pathOfCirculars?: string[];
  hasCircular?: boolean;
};

type FynpoTopoPackages = {
  noCircSorted: PackageDepData[];
  sorted: PackageDepData[];
  circulars: PackageDepData[];
};
```

Notes:

- `FynpoPackageInfo` dependency maps and `private` are copied from `package.json` only when present, so they can be `undefined` despite the types.
- `pkgStr`, `pkgJson`, `managed` and `nested` are non-enumerable. They are readable but absent from `Object.keys`, spreads and `JSON.stringify`.
- `managed` means fynpo lifecycle and release commands manage the package. `nested` means it was found below another package during auto-search.
- `byName` lists are sorted newest version first after `updateAuxPackageData()`.
- `byId` keys are `name@version`.
- `DEP_SECTIONS` includes `"peer"`, but `resolve()` never produces `peer` relations. Callers may add them with `addDep`.

### `PackageRef`

```ts
class PackageRef {
  type: "id" | "path" | "name";
  value: string;
  regex?: RegExp;
  mm?: Minimatch;
  constructor(ref: string);
  parseRef(ref: string): void;
  match(pkgInfo: PackageBasicInfo): boolean;
}
```

Parses a string reference to a package and tests `PackageBasicInfo` against it.

Parsing (`parseRef`, called by the constructor):

- The string is split on `:`. With more than one part, the first part (trimmed) must be `id`, `path` or `name`, else it throws `package ref '<ref>' has unknown type '<x>' - must be 'id', 'path', or 'name'`. The value is the second part, trimmed. Anything after a second `:` is dropped.
- With no `:`, `type` is `id` when the value has an `@` at an index above 0 (for example `foo@1.0.0`, `@s/foo@1.0.0`), else `name`. A scoped name `@s/foo` is `name`.
- A value starting with `/` and with a later `/` at index above 1 becomes a `RegExp` (text between the slashes, flags after the last slash) stored in `regex`. An invalid regex throws the `RegExp` error.
- A `path` value that is not a regex becomes a `Minimatch` stored in `mm`.

Matching (`match`):

| type | tested against | with `regex` | without |
| --- | --- | --- | --- |
| `path` | `pkgInfo.path` | regex test | minimatch match |
| `id` | `name@version` | regex test | exact equality |
| `name` | `pkgInfo.name` | regex test | exact equality |

### `pkgId`

```ts
function pkgId(name: string, version?: string): string
```

Returns `name@version`, or just `name` when `version` is falsy.

### `pkgInfoId`

```ts
function pkgInfoId(info: PackageBasicInfo): string
```

`pkgId(info.name, info.version)`.

### `getDepSection`

```ts
function getDepSection(fullName: string): DEP_SECTIONS
```

Maps `dependencies`, `devDependencies`, `optionalDependencies`, `peerDependencies` (and the short names `dep`, `dev`, `opt`, `peer`) to the short form. Any other value returns `"dep"`.

### `makeDepStep`

```ts
function makeDepStep(name: string, version: string, sec: string): string
```

Returns `<name>@<version>(<sec>)`, the format of entries in `indirectSteps`.

## Utilities

```ts
const posixify: (path: string) => string
function writeJson(file: string, data: unknown): Promise<void>
function writeJsonSync(file: string, data: unknown): void
function readJson<T = any>(file: string): Promise<T>
function readJsonSync<T = any>(file: string): T
function readPkgJson(dir: string): Promise<Record<string, any>>
function readPkgJsonSync(dir: string): Record<string, any>
```

- `posixify` is the identity function on platforms where `path.sep` is `/`. Elsewhere it replaces every `\` with `/`.
- `writeJson` and `writeJsonSync` write `JSON.stringify(data, null, 2)` plus a trailing newline, using `fs.writeFile` semantics (overwrite).
- `readJson` and `readJsonSync` read UTF-8 and `JSON.parse`. They throw the raw fs error (for example `ENOENT`) or `SyntaxError`. They do not wrap errors in `FynpoConfigError`.
- `readPkgJson` and `readPkgJsonSync` read `<dir>/package.json`.

## Caching

### `caching`

```ts
import { caching } from "@fynpo/base";
```

Namespace export (`export * as caching`). Its members are not exported at the package root. Contents: `readHashDigest`, `processInput`, `processLifecycleInput`, `processOutput`.

Hashes are sha256, encoded `base64url`. File discovery uses minimatch patterns. Files are scanned under `cwd`, directories are not returned, and the result is sorted.

Rule types (not importable by name):

```ts
type FilesFilterPatterns = {
  include?: string | string[];
  exclude?: string | string[];
};
type CacheBaseRule = { minimatchOptions?: any };
type CacheInputRule = FilesFilterPatterns & CacheBaseRule & {
  npmScripts?: string | string[];
  includeEnv?: string | string[];
  includeVersions?: string | string[];
};
type CacheOutputRule = FilesFilterPatterns & CacheBaseRule & {
  filesFromNpmPack?: boolean;
};
```

Rules for patterns:

- A file is kept when it matches `include` and does not match `exclude`. With no `include`, no files match.
- `minimatchOptions` defaults to `{ dot: true }`. Passing it replaces the default entirely.
- `CacheOutputRule.filesFromNpmPack` is declared but not read by any code.

### `caching.processInput`

```ts
function processInput(args?: {
  cwd?: string;
  input: CacheInputRule;
  packageJson?: Record<string, string | unknown>;
  extra?: any;
}): Promise<{
  files: string[];
  data: {
    env: Record<string, string>;
    versions: Record<string, string>;
    npmScripts: Record<string, string>;
    fileHashes: Record<string, string>;
    extra: any;
  };
  hash: string;
}>
```

Computes the cache key of a build input.

- `files`: the sorted files under `cwd` matching `input.include` and not `input.exclude`, relative to `cwd`.
- `data.env`: the `process.env` entries named by `input.includeEnv`. `data.versions`: the `process.versions` entries named by `input.includeVersions`.
- `data.npmScripts`: the `scripts` entries of `packageJson` named by `input.npmScripts`. When `packageJson` is not passed, `<cwd>/package.json` is read.
- `data.fileHashes`: file name to sha256 of its contents, in `files` order.
- `data.extra`: `extra`, or `{}`.
- `hash`: sha256 (`base64url`) of `JSON.stringify(data)`.
- `cwd` is needed in practice. Without it, hashing a file path or reading `package.json` fails.
- Throws if a file cannot be read, or if `packageJson` is not passed and `<cwd>/package.json` is missing or invalid.

### `caching.processLifecycleInput`

```ts
function processLifecycleInput(args?: {
  cwd?: string;
  input: CacheInputRule;
  packageJson?: Record<string, string | unknown>;
}): Promise<{} | Awaited<ReturnType<typeof processInput>>>
```

Reads `packageJson` (or `<cwd>/package.json`). If none of the scripts named in `input.npmScripts` exist in its `scripts`, resolves `{}` (no `files`, `data` or `hash`). Otherwise returns the result of `processInput` for the same arguments. Callers must check for the empty object.

### `caching.processOutput`

```ts
function processOutput(args?: {
  cwd?: string;
  inputHash?: string;
  calcHash?: boolean;
  output: CacheOutputRule;
  preFiles?: string[];
}): Promise<{
  files: string[];
  data: { inputHash?: string; fileHashes: Record<string, string> };
  hash: string;
  access: number;
  create: number;
}>
```

Computes the output file list of a build, and optionally its hash.

| option | type | default | behavior |
| --- | --- | --- | --- |
| `cwd` | `string` | none | Directory to scan. Treat as required. |
| `inputHash` | `string` | none | Stored in `data.inputHash`. |
| `calcHash` | `boolean` | falsy | When true, hash every output file and set `hash`. Otherwise `hash` is `""` and `data.fileHashes` is `{}`. |
| `output` | `CacheOutputRule` | required | `include`, `exclude`, `minimatchOptions`. |
| `preFiles` | `string[]` | `[]` | Extra files to add. Falsy entries and entries matching `output.exclude` (checked at each directory level) are dropped. A `cwd` prefix is stripped. |

- `files` is the unique sorted union of scanned files and `preFiles`.
- `hash` (when `calcHash`) is sha256 (`base64url`) of `JSON.stringify({ inputHash, fileHashes })`.
- `access` and `create` are both the same `Date.now()` value.

### `caching.readHashDigest`

```ts
function readHashDigest(hash: import("crypto").Hash, encoding?: BufferEncoding): string
```

Finishes a Node `crypto.Hash` and returns its digest string. `encoding` defaults to `"base64url"`. It ends the stream (`hash.end()`), so the hash cannot be updated afterwards. On Node versions without `base64url`, it computes base64 and converts it.

<!-- fynpo-cli v3.2.3: https://fynjs.pages.dev/ref/fynpo-cli.md -->

# fynpo-cli reference

fynpo-cli is a global launcher. It installs a `fynpo` command that finds the `fynpo` package installed in the current directory's monorepo and runs it in-process. It has no logic, no dependencies and no bundled copy of fynpo.

For commands, flags and config, see https://fynjs.pages.dev/ref/fynpo.md.

## Install

```
npm install -g fynpo-cli
```

- The package has no `main` or `exports`. It ships only the executable `dist/fynpo.js` (bin `fynpo`). There is no JS API.
- `package.json` sets `preferGlobal: true` and `dependencies: {}`.
- Requires Node `^22.22.2 || ^24.15.0 || >=26.0.0`. The bin uses top-level `await`, so it is ESM only.
- The target monorepo must have `fynpo` installed so that `fynpo/package.json` resolves from the current directory (normally a dev dependency at the repo top level).

## Relation to `fynpo`

- `fynpo` is the real tool. `fynpo-cli` only locates and starts it.
- Version selection: the launcher runs whichever `fynpo` version Node resolves from the current directory. The version of `fynpo-cli` does not matter. Different repos get the fynpo version they declare.
- There is no fallback to a global or bundled fynpo. If none resolves, it exits with an error.
- To skip this package, run the repo's local fynpo directly instead.

## How `fynpo` resolves and runs

1. Build a `require` rooted at `process.cwd()` (not at fynpo-cli's own location). Resolution follows normal Node lookup upward from the current directory, so it works from any subdirectory of the monorepo.
2. Resolve `fynpo/package.json`. If this throws for any reason, print the not-in-monorepo error and exit 1.
3. Read that package.json. The entry file is its `bin` field: the string if `bin` is a string, else `bin.fynpo`. If neither exists, default to `bin/fynpo.js`.
4. Join that path onto the directory of the resolved package.json.
5. Dynamic `import()` the file (as a `file://` URL). fynpo's bin runs its own main on load, so argv, stdout, stderr and the exit code are fynpo's own. The launcher has no argument handling or flags of its own, including `--help` and `--version`: they reach fynpo.

The launcher does not read fynpo's `dist/` layout. Only the `bin` field is relied on.

## Errors

Both errors go to stderr and exit with code 1.

| Condition | Message |
| --- | --- |
| `fynpo/package.json` does not resolve from the current directory | `ERROR: Unable to find the fynpo module from dir <cwd>`, then guidance to be in a fynpo monorepo with fynpo installed at its top level. |
| Import fails with `ERR_MODULE_NOT_FOUND` and the error text contains the bin path (leading `./` removed) | The same not-in-monorepo message. |
| Any other import failure, including errors thrown while fynpo loads | `Fail to load fynpo for your monorepo from dir <cwd>`, then the error object. |

Notes:

- The `ERR_MODULE_NOT_FOUND` check is a substring match on the error text. A missing dependency inside fynpo normally lacks the bin path and gets the load-failure message.
- Errors fynpo handles itself after it starts are not the launcher's. They carry fynpo's own output and exit code.

<!-- @fynjs/run v1.1.9: https://fynjs.pages.dev/ref/xarc-run.md -->

# @fynjs/run reference

`@fynjs/run` runs npm scripts, shell commands and JavaScript tasks, serially or concurrently, from the `xrun` command or from code. It installs two bins, `xrun` and `qrun` (`xrun` with logs silenced).

## Imports

The package root has one export, the shared `xrun` instance. Every API below is a property or method of that instance.

```js
// ESM
import xrun from "@fynjs/run";

// CommonJS: require() returns the instance itself, not a namespace
const xrun = require("@fynjs/run");
```

- There are no named exports. `import { load, serial } from "@fynjs/run"` does not work. Use `xrun.load` and `xrun.serial`.
- The root default export is typed `any`.
- The instance also carries the classes `xrun.XRun` (alias `xrun.XClap`), `xrun.XTaskSpec` and `xrun.XReporterConsole`.
- `@fynjs/run/cli/xrun` exports `xrunMain` as its default, see [`xrunMain`](#xrunmain). `@fynjs/run/package.json` is also exported.
- The package is ESM (`"type": "module"`). It needs Node `^22.22.2 || ^24.15.0 || >=26.0.0`.

## `xrun` and `qrun` commands

```
xrun [options] [--] [task1 [task options] task2 [task options] ...]
```

`qrun` sets `XRUN_QUIET=1` and then behaves exactly like `xrun`.

When a project has its own installed `@fynjs/run`, the bin runs that copy rather than the one it lives in. A copy is looked up from the current directory first, then from the bin file.

### CLI Options

Every option defined by the CLI is listed here. Booleans accept `--name`, `--name=false` and `--no-name`.

| Option | Alias | Type | Default | Behavior |
| --- | --- | --- | --- | --- |
| `--cwd <path>` | `-w` | string | process CWD | Set xrun's CWD. Passing it turns off the upward search for a task file. |
| `--dir <path>` | `-d` | string | CWD | Directory, relative to CWD, to look for the task file. |
| `--npm [bool]` | `-n` | boolean | `true` | Load `package.json` scripts into namespace `npm`. `--no-npm` disables. |
| `--nmbin [bool]` | `-b` | boolean | `true` | Add `CWD/node_modules/.bin` to the front of `PATH`, if that directory exists. |
| `--list [namespaces]` | `-l` | string | all namespaces | List task names from comma separated namespaces, then exit 0. |
| `--full` | `-f` | count | 0 | With `--list`, print full names: `ns/name`, and `/name` for the root namespace. Repeat (`-ff`) to also put a leading `/` on every name. |
| `--ns` | `-m` | boolean | `false` | List all namespaces, then exit 0. |
| `--soe [mode]` | `-e` | `no`, `soft`, `full` | `full` | Stop on error mode, see [Stop on Error Modes](#stop-on-error-modes). `no` means `""`. Any other value fails an assertion. |
| `--quiet [bool]` | `-q` | boolean | `false` | Suppress xrun's own logs. When not given, the value of env `XRUN_QUIET` (`"1"` means quiet) is used. When given, it sets `XRUN_QUIET=1` for nested runs. |
| `--serial [bool]` | `-s`, `-x`, `--ser` | boolean | `false` | Run the tasks named on the command line serially. |
| `--concurrent [bool]` | `-c`, `--conc` | boolean | `true` | Run the tasks named on the command line concurrently. This is the default. |
| `--env <K=V...>` | none | string array | none | Set env vars in `process.env` before running tasks, ie: `--env NODE_ENV=development FOO=BAR -.`. Only text up to the next `=` is kept as the value. |
| `--require <modules...>` | `-r` | string array | none | Load these modules for tasks instead of the task file. Resolved from CWD, loaded in the order given. |
| `--help` | `-h`, `-?` | | | Added by the argument parser. |
| `--version` | `-V`, `-v` | | | Added by the argument parser. |
| `--options` | none | | | Only recognized as the sole argument (`xrun --options`). Prints `--name` and `-alias` for each option above, for shell auto completion, then exits 0. |

Notes:

- `--serial` is applied only when there is more than one task on the command line.
- With no task on the command line, xrun prints the task list and usage, then exits 1.
- If no task is found at all, xrun prints a diagnostic and exits 1.
- The options of the xrun command come first. Options after a task name belong to that task, see [Task Options](#task-options).

### Task Execution

Tasks can be executed in various ways:

```bash
# Run single task
xrun build

# Run multiple tasks concurrently
xrun lint test

# Run multiple tasks serially
xrun --serial build test deploy

# Run namespaced task
xrun npm/test
xrun pkg/hello

# Optional task execution (won't fail if task not found)
xrun ?optional-task
```

Task name rules:

- A leading `?` makes the task optional. A missing optional task is skipped.
- `ns/name` selects a namespace. A leading `/` alone selects the root namespace. See [Namespace](#namespace).
- When a `--` follows, see [Argument Passing](#argument-passing).
- A leading `/` on a name that has a second `/` is stripped, so `xrun /ns/name` runs `ns/name`.

### Argument Passing

Arguments after `--` are appended to the shell command of the task named last on the command line. This applies only when that task is itself a shell command task. It does not reach shell commands inside an array task.

```bash
xrun test -- --grep "specific test"
xrun build -- --watch --verbose
```

Appended arguments that contain a space are wrapped in double quotes.

Options and arguments written after a task name, before `--`, are also appended to the shell command of that task. For a function task they are parsed into the [execution context](#execution-context).

### Array Tasks from Command Line

You can specify complex task arrays directly from the command line:

```bash
# Concurrent execution
xrun [task1, task2, task3]

# Serial execution with --serial
xrun --serial [task1, task2, task3]

# Mixed execution (serial then concurrent)
xrun --serial [task1, task2, [task3, task4]]

# As a quoted string
xrun "[task1, task2, [task3, task4]]"
```

If the first argument starts with `[`, all arguments are joined with a space and parsed as an array. A parse failure prints `Parsing array of tasks failed` and the run does not start.

### Task File Discovery

Unless `--require` is used, xrun looks for a task file in the search directory, which is CWD joined with `--dir`.

1. A directory entry is a match if its name starts with one of these prefixes, tried in this order: `xrun-tasks`, `xrun`, `xclap.`, `clapfile.`, `clap.`, `gulpfile.`. Any extension matches.
2. If the directory has no match, the subdirectories `scripts`, `tools`, `build` and `tasks` are checked the same way.
3. If still not found, and `--cwd` was not given, xrun moves to the parent directory and repeats. It stops at the first directory that has a `package.json`, or at the file system root.
4. When a file is found, xrun changes its CWD to the directory where it was found.

The file is loaded with `import()`, so a task file can use top-level await. Files ending in `.ts`, `.tsx`, `.mts` or `.cts` first start a TypeScript runner, see [TypeScript Support](#typescript-support).

What a task file or `--require` module may export:

- A function. It is called with the `xrun` instance and should call `xrun.load`.
- An object. A `default` export is processed the same way. Otherwise a non-empty object is loaded into namespace `xrun`.
- Nothing. A file that calls `xrun.load` itself needs no export.

The task file name `xrun-tasks.js` is the default name used in messages. `--require` modules that cannot be resolved are logged as errors and skipped.

### `xrunMain`

```ts
xrunMain(argv?: string[], offset?: number, xrunPath?: string, done?: (err?: Error) => void): Promise<unknown>
```

The default export of `@fynjs/run/cli/xrun`, also what the `xrun` bin calls. It is async. A caller must `await` it to observe the run.

- With no `argv`, it parses `process.argv` from index 2. Otherwise it parses `argv` from `offset`.
- Without `done`, xrun exits the process on listing, help and error conditions. With `done`, it calls `done` with an error that carries `exitCode`, even for exit code 0.

## Provider Packages

Provider packages allow you to create reusable task libraries that can be shared across projects.

### Using Provider Packages

Provider packages are searched in the dependencies of CWD's `package.json` (`optionalDependencies`, `devDependencies` and `dependencies`) when:

1. No task file or `--require` module was loaded (automatic discovery), or
2. The `package.json` has `"loadProviderModules": true` under its `@fynjs/run` key, see [Package.json Configuration](#packagejson-configuration).

A dependency is treated as a provider if either is true:

- Its `package.json` has an `xrunProvider` field.
- Its own `dependencies` list `@fynjs/run` (or the older name `@xarc/run`).

For each provider, xrun requires the module and calls its `loadTasks` export with the `xrun` instance. A provider without a `loadTasks` function is ignored. The module required is the package name, or `<name>/<module>` if `xrunProvider.module` is set.

#### Installation and Configuration

1. Install the provider package:

```bash
fyn add --dev @my-org/build-tasks
```

2. (Optional) Explicitly enable provider module loading in your `package.json`:

```json
{
  "@fynjs/run": {
    "loadProviderModules": true
  }
}
```

3. Create an `xrun-tasks.js` to use the provider:

```js
const { loadTasks } = require("@my-org/build-tasks");
loadTasks();

// You can also load your own tasks
const xrun = require("@fynjs/run");
xrun.load({
  "my-custom-task": "echo hello"
});
```

### Creating Provider Packages

To create a provider package:

1. Create a module that exports a `loadTasks` function:

```js
// index.js of your provider package
function loadTasks(xrun) {
  const runner = xrun || require("@fynjs/run");

  runner.load("build", {
    compile: "babel src -d lib",
    bundle: "webpack --mode production",
    clean: "rimraf lib dist"
  });

  runner.load("test", {
    unit: "jest",
    e2e: "cypress run",
    coverage: "nyc npm run test:unit"
  });
}

module.exports = { loadTasks };
```

2. Mark the package as a provider so xrun finds it. Either list `@fynjs/run` in its `dependencies`, or add an `xrunProvider` field:

```json
{
  "name": "@my-org/build-tasks",
  "main": "index.js",
  "xrunProvider": {
    "module": "lib/tasks.js"
  }
}
```

`xrunProvider.module` is optional. It is a path inside the package.

## TypeScript Support

xrun loads TypeScript task files after starting a runner. It tries these in order and uses the first that loads:

1. `@fynjs/ts-resolve/register`. A resolve hook feeding Node's own type stripping. Needs Node >= 22.15.
2. `ts-node/register/transpile-only`.

Neither is a dependency of `@fynjs/run`. Install one in the project. If neither loads, xrun logs `Unable to load a typescript runner` with each error. `tsx` is not used by xrun.

### Supported Files

- `xrun-tasks.ts` - TypeScript task file
- `xrun-tasks.mts` - TypeScript ES modules
- `xrun-tasks.cts` - TypeScript CommonJS
- `xrun-tasks.tsx` - the runner starts, but whether the file loads depends on the runner

Node's type stripping cannot transform enums, namespaces or parameter properties. A file using them fails with a message naming the limit. Rewrite them, or run Node with `--experimental-transform-types`.

### Example TypeScript Task File

```typescript
import xrun from "@fynjs/run";

interface BuildOptions {
  production?: boolean;
  watch?: boolean;
}

const buildTask = (options: BuildOptions = {}) => {
  const mode = options.production ? "production" : "development";
  const watchFlag = options.watch ? "--watch" : "";
  return xrun.exec(`webpack --mode ${mode} ${watchFlag}`);
};

xrun.load({
  build: buildTask(),
  "build:prod": buildTask({ production: true }),
  "build:watch": buildTask({ watch: true }),

  test: xrun.concurrent(xrun.exec("jest"), xrun.exec("eslint src/")),

  ci: xrun.serial("test", "build:prod")
});
```

## Package.json Configuration

xrun reads one config object from the `package.json` in CWD. The key is the first one present of `xclap`, `xrun`, `@fynjs/run`. Only two fields are used. `cwd` is ignored.

| Field | Type | Default | Behavior |
| --- | --- | --- | --- |
| `tasks` | object | none | Tasks loaded into namespace `pkg`. |
| `loadProviderModules` | boolean | `false` | Search dependencies for [provider packages](#provider-packages) even when a task file loaded. |

Other CLI options, such as `npm` or `soe`, are not read from `package.json`. Set them on the command line.

### Task Definition in Package.json

You can define simple tasks directly in `package.json` without JavaScript capability:

```json
{
  "name": "my-app",
  "@fynjs/run": {
    "tasks": {
      "hello": "echo hello from package.json",
      "build": "webpack --mode production",
      "test": ["lint", "unit-test"],
      "deploy": {
        "desc": "Deploy to production",
        "task": ["build", "upload", "notify"]
      }
    }
  }
}
```

These tasks are loaded into the `pkg` namespace and can be invoked as:

- `xrun pkg/hello`
- `xrun hello` (if no conflicts with other namespaces)

### npm Scripts

Unless `--no-npm` is given, the `scripts` of the nearest `package.json` (searched upward from CWD) are loaded into namespace `npm`.

- Each script runs as a shell command with the `npm` flag, which implies `tty` and `spawn`.
- The environment gets `npm_lifecycle_event`, `npm_lifecycle_script`, `npm_package_name`, `npm_package_version`, `npm_package_json`, `npm_execpath`, `npm_node_execpath`, `NODE`, `INIT_CWD` and `PWD`.
- A script whose name does not start with `pre` or `post` runs as a serial array of `pre<name>` (if defined), the script, and `post<name>` (if defined).
- A script whose name starts with `pre` or `post` is loaded as a plain script, with no hooks of its own.

## Creating Tasks

Tasks are defined in an object, for example:

```js
const tasks = {
  xfoo1: `echo "a direct shell command xfoo1"`,
  xfoo2: `echo "a direct shell command xfoo2"`,
  xfoo3: `echo "a direct shell command xfoo3"`,
  xfoo4: () => console.log("hello, this is xfoo4"),
  foo2: ["xfoo1", "xfoo2", "xfoo3", "xfoo4"],
  foo3: {
    desc: "description for task foo3",
    task: () => {
      console.log("function task for foo3");
    }
  }
};
```

## Loading Tasks

Tasks can be loaded with `xrun.load`. You can specify a namespace for the tasks. See [`load`](#loadnamespace-tasks-priority).

```js
import xrun from "@fynjs/run";
xrun.load(tasks);
// or load into a namespace
xrun.load("myapp", tasks);
```

## Task Definition

### Direct Action Task

Ultimately, a task would eventually resolve to some kind of runnable action that's either a function, a shell string, or a list of other tasks to run.

A task can define its direct action as one of:

- [A string](#string) - as a shell command to be spawned, or as a [string that contains an array](#string-array)
- [An array](#array) - list of tasks to be processed and execute [serially](#serially) or [concurrently](#concurrently).
- [A function](#function) - to be called, which can return more tasks to execute.
- [Task Spec](#task-spec) - created using the [exec API](#execspec-options), as a shell command to run.

### A Task Object

To allow decorating a task with more information such as name and description, the task definition can be an [object](#object), which should contain a `task` field that defines a [direct action task](#direct-action-task).

### String

- A string primarily is executed as a shell command.
- A string [started with `"~["`](#string-array) is parsed into an [array task](#array).

```js
{
  foo: "echo hello";
}
```

`xrun foo` will cause the shell command `echo hello` to be spawned.

Shell commands run through `child_process.exec` unless a [flag](#shell-task-flags) says otherwise. Arguments from the command line or from [inline task options](#inline-task-options) are appended to the command.

These environment variables are defined for a shell command, mainly for the [`finally`](#finally-hook) hook:

- `XRUN_ERR` - If the task failed, this contains the error message.
- `XRUN_FAILED` - If any task failed, this is set to `true`.

`XCLAP_ERR` and `XCLAP_FAILED` are set to the same values for older scripts.

#### String Array

If a string task starts with `"~["` then it's parsed as an array with string elements and executed as [array task](#array).

For example:

```js
{
  foo: "~[ foo1, foo2, foo3 ]";
}
```

Will be the same as specifying `foo: [ "foo1", "foo2", "foo3" ]` and processed as [array task](#array).

### Array

If the task is an array, then it can contain elements that are strings, functions or task specs.

- Functions are treated as a [task function](#function) to be called.
- Strings in a task array are primarily treated as name of another task to look up and execute.
- String started with `"~$"` or `"~@"` are treated as [anonymous shell commands](#anonymous-string-shell-command) to be executed.

The [array serial/concurrent rules](#array-serialconcurrent-rules) will be applied.

```js
{
  foo: ["foo1", "foo2", "foo3"];
}
```

`xrun foo` will cause the three tasks `foo1`, `foo2`, `foo3` to be executed **_serially_**.

#### Anonymous String Shell Command

If the task name in a task array starts with `"~$"` or `"~@"` then the rest of it is executed as an anonymous shell command directly.

For example:

```js
{
  foo: ["foo1", "~$echo hello"];
}
```

Will cause the task `foo1` to be executed and then the shell command `echo hello` to be executed.

##### Shell Task Flags

Any string that's to be a shell command can have flags like this:

```js
{
  foo: `~(tty)$node -e "console.log('isTTY', process.stdout.isTTY)"`;
}
```

- The leading part `~(tty)$` is specifying a shell command with flags `(tty)`. The closing can be `)$` or `)@`.
- Multiple flags can be specified like this: `~(tty,sync)$`.
- Flag names are case insensitive. An unknown flag fails the task with `Unknown flag`. A missing closing `)$` fails the task with `Missing )$`.

These are supported flags:

- `tty` - Use [child_process.spawn] to launch the shell command with TTY control. **WARNING** Only one task at a time can take over the TTY.
- `spawn` - Use [child_process.spawn] API instead of [child_process.exec] to launch the shell process. TTY control is not given.
- `sync` - If either `tty` or `spawn` flag exist, then use [child_process.spawnSync] API. This will cause concurrent tasks to wait. It has no effect alone.
- `noenv` - Do not pass `process.env` to child process.
- `npm` - Implies `tty` and `spawn`. Used for npm scripts.

### Function

```js
{
  foo: function (context) { return Promise.resolve("hello"); }
}
```

`xrun foo` will cause the function to be called.

The `this` context for the function will be the xrun [Execution Context](#execution-context), also passed as the first argument. If you don't want to use `this`, then you can use arrow functions for your task.

How a function signals completion:

- Two parameters: `(context, done)`. The task ends when `done(err, value)` is called.
- One parameter on a non-async function: if the parameter is named `ctx` or `context`, it receives the context. Any other name receives the `done` callback, and the task ends when `done` is called. xrun decides this by reading the function source text.
- Otherwise the function gets the context and its return value decides, see below.

The function can return:

- `Promise` - `xrun` will await for the promise.
- [node.js stream] - `xrun` will wait for the stream to close or error.
- `array` - `xrun` will treat the array as a list of tasks to be executed
  - The [array serial/concurrent rules](#array-serialconcurrent-rules) applied to the array.
  - The [anonymous shell command](#anonymous-string-shell-command) rule applied to each string element.
- `string` - `xrun` will treat the string as a task name, an [anonymous shell command to be executed](#anonymous-string-shell-command), or a `"~["` string array.
- `function` - `xrun` will call the function as another task function.
- a [task spec](#task-spec) or the value of [`stop()`](#stop) - run as a task.
- a child process, or an object with a `child` field that is a child process - the child is tracked so it can be killed on stop.
- `undefined` or any other value - the task is done as soon as the function returns.

An error thrown by the function, or a rejected promise, fails the task. A child process killed with SIGTERM is not treated as a failure.

### Task Spec

A direct action task can also be defined as a task spec.

Right now the supported spec types are a shell command, created with [`exec`](#execspec-options), and an environment update, created with [`env`](#envspec-options).

This is a more systematic approach to declare an [anonymous string shell command](#anonymous-string-shell-command).

A task spec shell command can be declared as the task or a task in the array:

```js
const xrun = require("@fynjs/run");

const tasks = {
  hello: xrun.exec("echo hello"),
  foo: [xrun.exec("echo foo"), xrun.exec("echo bar")]
};

xrun.load(tasks);
```

### Object

You can define your task as an object in order to specify more information.

For example:

```js
{
  task1: {
    desc: "description",
    task: <task-definition>,
    dep: <task-definition>,
    finally: <finally-hook-definition>
  }
}
```

Where:

| Field | Type | Behavior |
| --- | --- | --- |
| `desc` | string | Description, shown in the task list. An object task without `desc` is listed as a task with no description. |
| `task` | direct action | Defines a [direct action task](#direct-action-task). |
| `dep` | direct action | Runs before `task`. When it is an array it runs serially. |
| `finally` | direct action | Always runs after the task finishes or fails, see [finally hook](#finally-hook). |
| `flags` | object | Shell task flags to merge in, ie: `{ tty: true }`. Applies when `task` is a shell command. |
| `options` | object | Options for `child_process` (ie: `env`, `cwd`) used when `task` is a shell command. |
| `argOpts` | object | CLI options this task accepts, see [Task Options](#task-options). |
| `cliParser` | object | `{ options, subCommands, allowUnknownOption }`. Full option and sub command spec for the task. `options` is used when `argOpts` is absent. |
| `allowUnknownOption` | boolean | Default `true`. Set `false` to fail on options the task does not define. `cliParser.allowUnknownOption` takes precedence. |

#### finally hook

When defining task as an object, you can have a `finally` property that defines [direct action task](#direct-action-task) which is always executed after the task completes or fails. Generally for doing clean up chores.

Note that the finally hook is processed the same way as a task. Other tasks that are referenced by the `finally` hook will not have their `finally` hook invoked.

The task's error is available as `context.err` in a function hook, and as `XRUN_ERR` in a shell hook. Hooks do not run after [`stop()`](#stop) was invoked.

If you set `stopOnError` to `full`, then be careful if you have concurrent running tasks, because `full` stop immediately abandon all pending async sub tasks, but since xrun can't reliably cancel them, they could be continuing to run, and therefore could cause concurrent conflict with your finally hook. xrun emits a `warn-finally` event when any loaded task has a `finally` and the mode is `full`.

If you have async task, it's best you set [`stopOnError`](#stoponerror) to `soft`.

## Array serial/concurrent rules

When you define a task as an array, it should contain a list of task names to be executed serially or concurrently.

Generally, the array of tasks is executed concurrently, and only serially when [certain conditions](#serially) are true.

An task array can also be explicitly created as concurrent using the [concurrent API](#concurrenttasks--task1-task2-taskn)

### Serially

Each task in the array is executed serially if one of the following is true:

- The array is defined at the [top level](#top-level).
- The array is created by the [serial API](#serialtasks--task1-task2-taskn).
- The first element of the array is [`"."`](#first-element-dot) **DEPRECATED** use the [serial API](#serialtasks--task1-task2-taskn) instead. The first element `"-s"`, `"--serial"` or `"--ser"` has the same effect.

#### Using serial API

Create an array of serial tasks within another concurrent array:

```js
const xrun = require("@fynjs/run");

const tasks = {
  foo: xrun.concurrent("a", xrun.serial("foo1", "foo2", "foo3"))
};

xrun.load(tasks);
```

#### top level

At top level, an array of task names will be executed serially. Top level means the array is the `task` of a task object or the task definition itself. An array returned by a function, or passed to `run`, is not top level.

```js
const tasks = {
  foo: ["foo1", "foo2", "foo3"]
};

xrun.load(tasks);
```

#### First element dot

> **DEPRECATED** - Please use the [serial API](#serialtasks--task1-task2-taskn) instead.

If the first element of the array is `"."` then the rest of tasks in the array will be executed serially.

```js
{
  foo: ["bar", [".", "foo1", "foo2", "foo3"]];
}
```

#### Concurrently

By default, an ordinary array of tasks is executed concurrently, except when it's defined at the [top level](#top-level). A first element of `"--concurrent"`, `"-c"` or `"--conc"` also marks an array concurrent.

If you need to have an array of tasks at the top level to execute concurrently, use the [concurrent API](#concurrenttasks--task1-task2-taskn) to create it.

```js
const xrun = require("@fynjs/run");

const tasks = {
  foo: xrun.concurrent("foo1", "foo2", "foo3")
};

xrun.load(tasks);
```

> `xrun foo` will execute tasks `foo1`, `foo2`, and `foo3` **_concurrently_**.

## Namespace

A group of tasks can be assigned a namespace and allows you to have tasks with the same name so you can modify certain tasks without replacing them.

For example:

```js
xrun.load([namespace], tasks);
```

You refer to the namespaces with `/`, ie: `ns/foo`.

Anything that was loaded without a namespace is assigned to the default namespace `/`, which can be accessed with a simple leading `/`, ie: `/foo`.

If you run a task without specifying the namespace, then it's searched through all namespaces until it's found. The default namespace is the first one to search. The rest follow their [priority and override order](#namespace-overrides), and namespaces of equal priority are searched in the order they were loaded.

> For obvious reasons, this means task names cannot contain `/`.

Namespaces created by xrun itself: `npm` (npm scripts), `pkg` (`package.json` tasks), and `xrun` (object exports of a task file).

### Auto Complete with namespace

To assist shell auto completion, you may specify all namespaces with a leading `/` when invoking from the command line. It will be stripped before xrun runs them.

ie:

```bash
$ xrun /foo/bar
```

That way, you can press `tab` after the first `/` to get auto completion with namespaces.

### Namespace Overrides

Namespaces can be configured with priority and override relationships. A namespace searched earlier wins when two have a task of the same name.

```js
// namespace "test" is searched before namespace "build"
xrun.load({ namespace: "test", overrides: "build" }, tasks);

// a higher priority value is searched earlier
xrun.load("hot", tasks, 5);
```

- Each namespace starts with its `priority` (default `1`). A higher value is searched earlier.
- `overrides` is a namespace name or an array of names. A namespace is raised above every namespace it overrides.
- Namespaces with equal values keep load order.
- Calling `load` again for the same namespace adds to its `overrides`.
- Mutual overrides between two namespaces throw `circular namespace override`.

## Execution Context

A continuous execution context is maintained from the top whenever you invoke a task with `xrun <n>`.

The execution context is passed to any task function as the first parameter and as `this`. It has the following properties:

- `run` - a function to run another task, `run(tasks, callback?)`
- `argv` - arguments to the task (array)
- `cliCmd` - the CLI command object from argument parser
- `argp` - parsed arguments metadata (JSON format)
- `args` - parsed arguments list
- `argOpts` - parsed CLI options for the task (object)
- `err` - For the [`finally`](#finally-hook) hook, if task failed, this would be the error
- `failed` - The first task failure error, or `null`. Further errors are in its `more` array.

You can run more tasks under the same context with `this.run` or `context.run`:

- run a single task

  - `this.run("task_name")`
  - `context.run("task_name")`

- execute tasks serially.

  - `this.run(xrun.serial("name1", "name2", "name3"))`
  - `this.run([ ".", "name1", "name2", "name3"])`

- execute tasks concurrently
  - `this.run(["name1", "name2", "name3"])`

The tasks given to `run` start after the calling function finishes. The optional `callback(err, data)` is called when they complete.

For example:

```js
const tasks = {
  bar: {},
  foo: function(context) {
    console.log("hello from foo");
    context.run("bar");
  }
};
```

### Task Options

The execution context also has `argv` which is an array of the task options. The first one is the name as used to invoke the task.

Examples:

- `xrun foo` - argv: `["foo"]`
- `xrun foo --bar` - argv: `["foo", "--bar"]`
- `xrun ?foo --bar --woo` - argv: `["?foo", "--bar", "--woo"]`
- `xrun ?ns/foo --bar` - argv: `["?ns/foo", "--bar"]`

For a shell command task, the options after the task name, minus the task name itself, are appended to the command.

For a function task, `context.argOpts` holds the parsed options. Declare the options a task accepts with `argOpts` in the task object:

```js
const tasks = {
  foo: function(context) {
    console.log(context.argv, context.argOpts);
  },
  boo: {
    desc: "show argv from task options",
    argOpts: {
      level: { alias: "l", args: "<val string>", desc: "log level" },
      verbose: { alias: "v" }
    },
    task: function(context) {
      console.log(context.argv, context.argOpts);
    }
  }
};
```

- An option spec uses the `@fynjs/cli-args` format, ie: `{ alias, args, desc, required }`.
- These older forms are also accepted: `require: true`, `type: "string"` (also `number`, `boolean`, `float`, `int`, `integer`), `type: "array"`, `type: "count"`.
- Options not in `argOpts` are accepted by default. If `allowUnknownOption` is `false`, they fail the task with `Unknown options for task <name>: ...`.
- An option parsing error fails the task with `Error parsing options for task <name>: ...`.

#### Inline Task Options

Task options can be specified inline in the task definition also, not just in command line.

Only the first part separated by space `" "` is used as the task name.

For example,

```js
const tasks = {
  foo: function(context) {
    console.log(context.argv);
  },
  zoo: "foo --bar --woo",
  moo: ["?bad", "foo --bar --woo"]
};
```

### Accessing Arguments

Options written after a task name on the command line are parsed for that task:

```js
const tasks = {
  test: function(context) {
    console.log("Parsed options:", context.argOpts);
    // If called with: xrun test --watch --verbose
    // context.argOpts would be: { watch: true, verbose: true }
  }
};
```

The `--` remainder is not part of the context. It is only appended to a shell command, see [Argument Passing](#argument-passing).

## Error Handling

### Environment Variables

xrun sets these environment variables for shell commands:

- `XRUN_ERR` - If task failed, this contains the error message
- `XRUN_FAILED` - If any task failed, this is set to `true`

These are particularly useful in [finally hooks](#finally-hook) for cleanup based on execution results.

The `xrun` command sets or reads these variables in `process.env`:

| Variable | Behavior |
| --- | --- |
| `XRUN_ID` | Set to `1`, or incremented when xrun runs inside another xrun. |
| `FORCE_COLOR` | Set to `1` if not already set. |
| `XRUN_QUIET` | `1` means quiet. Set by `qrun` and by `--quiet`. Read when `--quiet` is not given. |
| `XRUN_CWD` | CWD of the run. |
| `XRUN_INIT_CWD` | CWD at first invocation. Becomes `INIT_CWD` for npm scripts. |
| `XRUN_VERSION`, `XRUN_BIN_DIR`, `XRUN_NODE_BIN` | Version, install directory and node binary of the running xrun. Used to skip repeated logs in nested runs. |
| `XRUN_TASKFILE` | Path of the loaded task file, or `not found`. |
| `XRUN_PACKAGE_PATH` | Path of the `package.json` whose npm scripts were loaded. |

### Stop on Error Modes

xrun supports different error handling modes via the `stopOnError` setting:

- `false` or `""` - Continue execution even if tasks fail
- `"soft"` - Allow existing async tasks to complete, but don't start new tasks
- `"full"` - Stop immediately and abandon all pending tasks (default)

```js
// Set globally
const xrun = require("@fynjs/run");
xrun.stopOnError = "soft";

// Or via CLI
// xrun --soe=soft task1 task2
```

When the `xrun` command finishes with a failure and no `done` callback, it prints the errors and exits with code 1, but only if the mode is not `""`. With `--soe no`, the process is not exited with code 1 by xrun.

## APIs

All APIs are members of the `xrun` instance. Methods that return `this` can be chained.

### `stopOnError`

```ts
xrun.stopOnError: "" | "soft" | "full"
```

Configure `xrun`'s behavior if any task execution failed.

Accepted values when setting are:

- `false`, `""` - completely turn off, march on if any tasks failed.
- `"soft"` - Allow existing async tasks to run to completion and invoke `finally` hooks, but no new tasks will be executed.
- `true`, `"full"` - Stop and exit immediately, don't wait for any pending async tasks, `finally` hooks invocation is unreliable.

Any other value throws an assertion error. The getter returns `""`, `"soft"`, `"full"` or `undefined` if never set.

> If never set, `run` sets it to `"full"`.

Example:

```js
const xrun = require("@fynjs/run");

xrun.stopOnError = "full";
```

> Note: If user specify this in CLI with option `--soe=<value>` then that will always be used.

### `load([namespace], tasks, [priority])`

```ts
xrun.load(tasks: object): this
xrun.load(namespace: string | { namespace: string; overrides?: string | string[] }, tasks: object, priority?: number): this
```

Load `tasks` into `[namespace]` (optional).

If no `namespace`, then tasks are loaded into the root namespace `/`.

- `tasks` must be an object, otherwise it throws `Invalid tasks`.
- Tasks are merged into the namespace with `Object.assign`. A task with the same name replaces the earlier one.
- `priority` defaults to `1`. See [Namespace Overrides](#namespace-overrides). It has no effect on the root namespace, which is always searched first.

```js
// Load into default namespace
xrun.load({
  hello: "echo hello"
});

// Load into specific namespace
xrun.load("build", {
  compile: "babel src -d lib",
  bundle: "webpack"
});

// Load with namespace options
xrun.load(
  { namespace: "test", overrides: "build" },
  {
    unit: "jest",
    e2e: "cypress run"
  }
);
```

### `run(tasks, [done])`

```ts
xrun.run(tasks: string | any[], done?: (err?: Error) => void): this
```

Run the task specified by `tasks`.

- `tasks` - Either a string or an array of names. A string may carry a `?` prefix, a namespace, and inline task options. An array follows the [array rules](#array-serialconcurrent-rules) and is concurrent unless it starts with a serial marker.
- `done` - Optional callback, called once with the first failure error, or nothing on success. Further failures are in `err.more`. If it's not given, an internal handler prints the failures and exits the process with code 1, see [Stop on Error Modes](#stop-on-error-modes).

If `stopOnError` was never set, it is set to `"full"`.

```js
// Run single task
xrun.run("build", err => {
  if (err) console.error("Build failed:", err);
  else console.log("Build completed");
});

// Run multiple tasks
xrun.run(["lint", "test"], done);
```

### `asyncRun(tasks)`

```ts
xrun.asyncRun(tasks: string | any[]): Promise<undefined>
```

Promise-based version of `run()`. It resolves with `undefined` and rejects with the same error `done` would receive.

```js
async function buildAndDeploy() {
  try {
    await xrun.asyncRun("build");
    await xrun.asyncRun("deploy");
    console.log("Build and deploy completed");
  } catch (err) {
    console.error("Failed:", err);
  }
}
```

### `stop()`

```ts
xrun.stop(): symbol
```

Returns a marker. It does nothing by itself. When xrun executes the marker as a task, it kills all tracked child processes and no further task or `finally` hook starts.

Use it as a task, or return it from a function task:

```js
const tasks = {
  "long-running-server": () => {
    // Start a server
    return new Promise(resolve => {
      // This would run indefinitely
      setInterval(() => {}, 1000);
    });
  },

  "test-and-stop": xrun.serial(
    "long-running-server",
    () => {
      // Run some tests
      return runTests();
    },
    () => xrun.stop() // Stop everything
  )
};
```

### `waitAllPending(done)`

```ts
xrun.waitAllPending(done: () => void): this
```

Wait for all pending concurrent tasks to complete and then call `done` with no arguments. It polls every 10 ms.

```js
xrun.run("background-task");
xrun.waitAllPending(() => {
  console.log("All tasks completed");
});
```

### `env(spec, [options])`

```ts
xrun.env(spec: Record<string, string | null | undefined>, options?: { override?: boolean }): XTaskSpec
```

Create a task to set environment variables in `process.env`.

- `spec` - Object of environment variables. A `null` or `undefined` value deletes the variable.
- `options.override` - Default `true`. When `false`, variables that already exist are kept.

Example:

```js
{
  someTask: [xrun.env({ FOO: "bar" }), xrun.exec("echo $FOO")];
}
```

> Note that this can be achieved easily with a function task:

```js
{
  someTask: [() => Object.assign(process.env, { FOO: "bar" }), xrun.exec("echo $FOO")];
}
```

> However, using `xrun.env` will log out the env variables and values nicely.

### `updateEnv(envValues, [options])`

```ts
xrun.updateEnv(envValues: Record<string, any>, options?: { target?: object; override?: boolean }): object
```

Immediately apply `envValues` to `options.target` (default `process.env`) and return the target. A `null` or `undefined` value deletes the key. `override` defaults to `true`. When `false`, existing keys are kept. This is the function behind [`env`](#envspec-options).

### `concurrent([tasks] | task1, task2, taskN)`

```ts
xrun.concurrent(...tasks: any[]): any[] | any
```

Explicitly creates an array of tasks to be executed concurrently.

- The tasks can be passed in as a single array
- Or they can be passed in as a list of variadic arguments
- Falsy arguments are dropped. With no arguments it throws `no tasks passed`.
- A single argument that is not an array is returned as is.

Returns an array of tasks that's marked for concurrent execution. `xrun.parallel` is an alias.

```js
// Using array
xrun.concurrent(["task1", "task2", "task3"]);

// Using variadic arguments
xrun.concurrent("task1", "task2", "task3");

// Nested example
const tasks = {
  "build-all": xrun.concurrent("build-client", "build-server", "build-docs")
};
```

### `serial([tasks] | task1, task2, taskN)`

```ts
xrun.serial(...tasks: any[]): any[] | any
```

Explicitly creates an array of tasks to be executed serially. Argument handling is the same as [`concurrent`](#concurrenttasks--task1-task2-taskn).

- The tasks can be passed in as a single array
- Or they can be passed in as a list of variadic arguments

Returns an array of tasks that's marked for serial execution.

```js
// Using array
xrun.serial(["build", "test", "deploy"]);

// Using variadic arguments
xrun.serial("build", "test", "deploy");

// Complex example
const tasks = {
  "ci-pipeline": xrun.serial(
    "clean",
    xrun.concurrent("lint", "typecheck"),
    "build",
    "test",
    "deploy"
  )
};
```

### `exec(spec, [options])`

```ts
xrun.exec(spec: string | string[] | ExecSpec, options?: string | string[] | Omit<ExecSpec, "cmd">): XTaskSpec

interface ExecSpec {
  cmd: string | string[];
  flags?: string | string[];
  execOptions?: object;
  xrun?: { delayRunMs?: number };
  env?: Record<string, string>;
}
```

Create a shell command task spec with _optional_ [`flags`](#shell-task-flags) or `options`.

- `spec` - an object that specifies the following fields:

| Field | Type | Default | Behavior |
| --- | --- | --- | --- |
| `cmd` | string, string[] | none | The shell command. An array is joined with a space. `command` is accepted as an alias. |
| `flags` | string, string[] | `{}` | [Shell Task Flags](#shell-task-flags), ie: `"tty,sync"` or `["tty", "sync"]`. |
| `execOptions` | object | `{}` | Options to pass to [child_process.spawn] or [child_process.exec]. |
| `xrun` | object | `{ delayRunMs: 0 }` | xrun execution options. `delayRunMs` is milliseconds to wait before running the command. |
| `env` | object | none | `Object.assign`ed into `execOptions.env`. It is added to `process.env` unless the `noenv` flag is set. |

> Alternatively this can also be called as `exec(cmd, [flags|options])`

Where:

- `flags` - string or array as [Shell Task Flags](#shell-task-flags)
- `options` - Object to specify: `{ flags, execOptions, xrun, env }`

Any other `spec` type throws `xrun.exec - unknown spec type`.

Examples:

```js
const xrun = require("@fynjs/run");

const tasks = {
  cmd1: xrun.exec("echo hello", "tty"),
  cmd2: [
    // run `echo foo` with env FOO=bar
    xrun.exec("echo foo", { env: { FOO: "bar" } }),
    // run `echo hello world` with tty enabled
    xrun.exec(["echo", "hello", "world"], "tty"),
    // with a single spec object
    xrun.exec({
      cmd: ["echo", "hello", "world"],
      flags: "tty",
      env: { FOO: "bar" }
    })
  ]
};

xrun.load(tasks);
```

### `printTasks()`

```ts
xrun.printTasks(): this
```

Print the loaded tasks and their descriptions to the console.

### `countTasks()` and `getNamespaces()`

```ts
xrun.countTasks(): number
xrun.getNamespaces(): string[]
```

`countTasks` returns the number of loaded tasks across all namespaces. `getNamespaces` returns the namespaces in search order, starting with `/`.

### `XRun`

```ts
new xrun.XRun(namespace?: string, tasks?: object)
```

The class behind the shared instance. Use it to create an independent runner with its own tasks. It extends `EventEmitter` and has the same methods as `xrun`. Its `load` and `run` are not pre-bound.

### Internal members

These are public on the instance but exist for the CLI and the executor. Do not call them from task code.

| Member | Behavior |
| --- | --- |
| `xqTree` | The execution queue tree. The executor creates and looks up queue items in it. |
| `addTaskChild(child, sym)`, `removeTaskChild(child, sym)` | Track or untrack a spawned child process under a symbol key. Both return the tracking map. |
| `killChildProcess(child)` | Kills one child. Uses `taskkill /T /F` on Windows, `child.kill()` elsewhere. Errors are ignored. Marks the child as stopped. |
| `killTaskChildren()` | After a 10 ms timer, kills every tracked child and clears the tracking map. |
| `actStop()` | Kills tracked children and marks the run as stopped. |
| `exit(code)` | Calls `process.exit(code)` only when `stopOnError` is set. With tracked children it kills them first and exits after 100 ms. Without `stopOnError` it does nothing. |
| `setCliContext(cliContext)`, `getCliContext()` | Set or get the CLI context. The CLI sets it before running tasks. `setCliContext` returns the instance. |

### Events

`xrun` is an `EventEmitter`. These events are emitted:

| Event | Data | When |
| --- | --- | --- |
| `run` | `{ name }` or `{ tasks }` | `run` was called. |
| `execute` | `{ type, qItem, ... }` | A task item executes. `type` is `lookup`, `serial-arr`, `concurrent-arr`, `env`, `shell` or `function`. |
| `dep` | `{ qItem }` | A task's `dep` is about to run. |
| `search` | `{ qItem, found }` | A task name without a namespace was found by searching namespaces. |
| `not-found` | error | An optional task was not found. |
| `spawn-async`, `done-async` | none, `{ name }` | A concurrent branch started or finished. |
| `done-item` | timing data | A task finished. |
| `warn-finally` | none | A `finally` hook exists and `stopOnError` is `"full"`. |
| `fail-cancel` | watch object | A pending task was cancelled by a failure. |

[child_process.spawn]: https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options
[child_process.spawnsync]: https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
[child_process.exec]: https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback
[node.js stream]: https://nodejs.org/api/stream.html

<!-- @fynjs/cli-args v1.1.7: https://fynjs.pages.dev/ref/cli-args.md -->

# @fynjs/cli-args reference

`@fynjs/cli-args` parses command line arguments for Node.js CLIs. It supports options, aliases, sub-commands, typed arguments, defaults, generated help and version output, and `exec` handlers. It has no runtime dependencies. ESM only (`"type": "module"`).

## Imports

```js
import { NixClap } from "@fynjs/cli-args";
import { Command, InvalidArgSpecifierError, UnknownOptionError, UnknownCliArgError } from "@fynjs/cli-args";
```

```ts
import type {
  NixClapConfig, CommandSpec, OptionSpec, ParseResult, CommandNode,
  CommandMeta, CommandExecFunc, OptionValue, ArgumentValue, OptionSource
} from "@fynjs/cli-args";
```

Everything is a named export from the package root. There is no default export and there are no subpaths (only `@fynjs/cli-args/package.json`).

Runtime exports: `NixClap`, `Command` (the internal `CommandBase` class, renamed), `InvalidArgSpecifierError`, `UnknownOptionError`, `UnknownCliArgError`.

Type-only exports: `NixClapConfig`, `ParseResult`, `CommandSpec`, `OptionSpec`, `CommandExecFunc`, `CommandNode`, `CommandMeta`, `OptionValue`, `ArgumentValue`, `OptionSource`. `CommandNode` is exported as a type only: you receive instances in `exec` handlers and in `ParseResult`, you cannot construct one.

Not exported: `BaseSpec` (its fields are inherited by `OptionSpec` and `CommandSpec`, documented below), `CustomTypeFunc`, `GroupOptionSpec`, `OptionMatch`, `CommandExecAsyncFunc`, `OptionNode`, `ClapNode`, `Parser`, `Options`, `defaultOutput`, `defaultExit`.

## Quick use

```js
import { NixClap } from "@fynjs/cli-args";

const parsed = new NixClap({ name: "mycli", version: "1.0.0" })
  .init2({
    options: { verbose: { alias: "v2", desc: "be loud" } },
    subCommands: {
      build: {
        args: "<target string> [more..]",
        options: { out: { args: "<dir>", argDefault: "dist" } },
        exec: cmd => console.log(cmd.args, cmd.opts)
      }
    }
  })
  .parse();
```

Call order is `new NixClap(config)`, then `.version()`, `.help()`, `.usage()`, `.cmdUsage()` as needed, then `init`/`init2`, then `parse`/`parseAsync`. `version()` and `help()` must run before `init`/`init2`, which reads them. `parse`, `parse2`, `makeHelp` before init: `makeHelp` returns `["Error: CLI not initialized. Call init() or init2() first."]`; `parse`/`parse2` throw a `TypeError`.

## `NixClap`

```ts
class NixClap extends EventEmitter {
  constructor(config?: NixClapConfig);
  output: (s: string) => void;           // public field
  init(options?: Record<string, OptionSpec>, commands?: Record<string, CommandSpec>): this;
  init2(rootCommandSpec?: CommandSpec): this;
  version(v: number | string): this;
  help(custom: any): this;
  usage(msg: string): this;
  cmdUsage(msg: string): this;
  skipExec(skip?: boolean): void;        // default true
  removeDefaultHandlers(...events: string[]): this;
  parse(argv?: string[], start?: number): ParseResult;
  parseAsync(argv?: string[], start?: number): Promise<ParseResult>;
  parse2(argv: string[], start?: number): ParseResult;
  runExec(parsed: ParseResult): number;
  runExecAsync(parsed: ParseResult): Promise<number>;
  applyConfig(config: Record<string, any>, parsed: ParseResult, src?: "cli" | "user" | "default"): this;
  makeHelp(cmdPath?: string | string[]): string[];
  showHelp(err?: Error, cmdPath?: string | string[]): void;
  showError(err: Error): void;
  showVersion(): void;
}
```

### `NixClapConfig`

All fields optional. The constructor copies the object shallowly.

| option | type | default | behavior |
| --- | --- | --- | --- |
| `name` | `string` | derived | Program name used in help and error text. When unset, `parse`/`parse2` with `start > 0` set it to `path.basename(argv[start - 1], ".js")`. Otherwise help shows `program` in some places and an empty string in others. |
| `version` | `number \| string` | none | If truthy at `init`/`init2` time, a `--version` option is added to the root command. `showVersion` prints `${version}\n`. |
| `versionAlias` | `string` | `["V", "v"]` | Aliases for `--version`. When set it is used as is (typed `string`, though an array also works at runtime). When unset, `V` and `v` are used minus any that a root option already uses in its `alias`. |
| `help` | `OptionSpec \| false` | built-in | If the key is present in the config (even `undefined`) it replaces the built-in help option. `false` disables help entirely. A custom spec is not the built-in help, so the `help` event is not emitted for it (see `parse`). |
| `helpAlias` | `string \| string[]` | `["?", "h"]` | Aliases of the built-in `--help` option. Ignored when `help` is set. |
| `defaultCommand` | `string` | none | Name (or alias) of a top-level command to run when the argv has only options (see Default command). |
| `allowUnknownCommand` | `boolean` | `false` | Unknown non-option words become sub-commands named after the word instead of errors. Root level only, or where a command requires a sub-command. |
| `unknownCommandFallback` | `string` | none | Name of a root sub-command that takes an unknown first word as its first argument. Ignored when `allowUnknownCommand` is true or the named command does not exist. |
| `allowUnknownOption` | `boolean` | `false` | Default for the root command (`spec.allowUnknownOption ?? config.allowUnknownOption`). Also selects which internal unknown-command helper is used for `allowUnknownCommand`. It is not copied to sub-commands. |
| `usage` | `string` | `"$0"` | Root usage text. `$0` is replaced by the program name. |
| `cmdUsage` | `string` | `"$0 $1"` | Usage text for sub-command help. `$1` is replaced by the command name used. |
| `skipExec` | `boolean` | `false` | `parse`/`parseAsync` do not call `runExec`/`runExecAsync`. |
| `skipExecDefault` | `boolean` | `false` | The parser does not insert `defaultCommand` upfront. No other code inserts it later. |
| `output` | `(text: string) => void` | `process.stdout.write` | Receives all help, version and error text. |
| `exit` | `(code: number) => void` | emit `"exit"` event | Called after help, version and error output. When set, the `"exit"` event is never emitted. |
| `handlers` | `Record<string, ((parsed?: ParseResult) => void \| Promise<void>) \| false>` | none | Replaces the default handler of an event by name. `false` removes it. Only the names `pre-help`, `help`, `post-help`, `version`, `parse-fail`, `no-action` take effect. Ignored when `noDefaultHandlers` is true. |
| `noDefaultHandlers` | `boolean` | `false` | Installs no default handlers and no default `"exit"` listener. `handlers` is ignored. `parse` returns the result (errors in `errorNodes`) and prints nothing. |
| `helpZebra` | `boolean` | `true` | Alternating dim rows in help. `false` turns it off. The setting is module global, so the last constructed `NixClap` wins. |
| `allowDuplicateOption` | `boolean` | `false` | When false, a sub-command declaring an option with the same name as an ancestor's option throws at `init`. When true it is allowed. The `help` option is always exempt. |

### Constructor behavior

- The default exit behavior emits `"exit"` with the code. The default listener sets `process.exitCode = code`. It never calls `process.exit`, so `parse` always returns normally.
- Default handlers are registered with `this.on(...)` for `pre-help`, `help`, `post-help`, `version`, `parse-fail`, `no-action`, and an `"exit"` listener.

### `init2(rootCommandSpec?)` and `init(options?, commands?)`

`init2` builds the command tree from a root `CommandSpec` and returns `this`. `init(options, commands)` is `init2({ options: options || {}, subCommands: commands || {} })`.

Rules applied by `init2`:

- Root `alias` is forced to the internal name `~root-command~`. Root `desc` defaults to `""`. Used root spec fields: `desc`, `args`, `argDefault`, `exec`, `usage`, `customTypes`, `options`, `subCommands`, `allowUnknownOption`. Root `alias` and `required` are ignored.
- If a version is set, `options.version` is added with `desc: "Show version number"`.
- If help is not `false`, `options.help` is set (this overwrites a user option named `help` on the root) and a `help` option is added to every sub-command at every depth unless the command already has an option named `help`. In sub-commands, help aliases that collide with an alias of an option in the same command are dropped. At the root there is no filtering, so a root option using alias `h` or `?` throws the duplicate alias error.
- Throws `Error` for a duplicate alias within a command's options (`Init command <name> failed - Option alias <a> already used by option <o>`), a duplicate sub-command alias (`Command <name> alias <a> already used by command <c>`), and a sub-command option name that exists on an ancestor (`Command <c> option <o> already used by parent command '<p>'`, skipped with `allowDuplicateOption`). Argument specifier errors are described under Argument specifiers.
- Specs are copied (one level of plain-object copy), so mutating the original after `init` has no effect.

### `parse(argv?, start?)`

Parses, handles help, version and errors, then runs `exec` handlers. Returns `ParseResult`.

Steps:

1. `parse2(argv, start)`.
2. If `_checkFailures` is true, return the result. Order of checks:
   1. If the built-in help is active and some command node has `help` with source `"cli"`: set `parsed.helpNode`, emit `help` with `parsed`, stop. This wins over missing required options and other errors.
   2. If a version is set and the root has `version` from the command line: emit `version`, stop.
   3. If `errorNodes.length > 0`: emit `parse-fail` with `parsed`, stop.
3. If not `skipExec`: `runExec(parsed)`.

Default handlers:

| event | default behavior |
| --- | --- |
| `pre-help`, `post-help` | no-op. Emitted around help output with `{ self }`. |
| `help` | `showHelp(undefined, path)`. `path` is the `--help <cmd...>` words if given, otherwise the chain of commands from `helpNode` (nothing for root). Exit code 0. |
| `version` | `showVersion()`: prints `<version>\n`, exit code 0. |
| `parse-fail` | `showError(firstErrorNode.error)`: prints `Error: <message>\n` and `<name or "program"> --help for more info\n`, exit code 1. |
| `no-action` | `showHelp(new Error("No command given"))`: help, then `\nError: No command given\n`, exit code 1. |
| `"exit"` | sets `process.exitCode`. |

`no-action` is emitted by `runExec` when no `exec` ran and the tree has at least one `exec` handler anywhere (`getExecCount() > 0`).

A custom `help` option (`config.help` or `.help(spec)`) is never given the `help` event. Check its option value yourself after parse, or use `noDefaultHandlers`.

### `parseAsync(argv?, start?)`

Same as `parse`, but awaits `runExecAsync`. Use it when any `exec` is async.

### `parse2(argv, start = 0)`

Parses only. No help, version, error handling or `exec`.

```ts
// returns
{ command: CommandNode; argv: string[]; errorNodes: ClapNode[]; _: string[]; index: number }
```

- `argv === undefined` means `process.argv` with `start = 2`.
- When the name is unset and `start > 0`, name becomes `Path.basename(argv[start - 1], ".js")`.
- Parse errors (unknown option or argument, missing args, custom type failures) are stored on nodes and surface through `errorNodes`. `parse2` does not throw for them.
- After parsing: missing required options add the error `missing these required options a, b` to the root node (checked before defaults, so a default does not satisfy `required`). Then defaults are applied (`source: "default"`) and camelCase option keys are added.
- `_` is `argv.slice(index)`: the entries after a bare `--`. `index` is where parsing stopped (one past the `--`, or `argv.length`).

### `runExec(parsed)` and `runExecAsync(parsed)`

Run `exec` handlers and return the number of handlers run.

Order:

1. Every command node in the parsed tree that has `exec`, depth first, parent before children, in the order the nodes were created. The root is never in this list. Each handler is called as `exec(node, parsed)`. `parsed.execCmd` is set to the first node run.
2. The root `exec` runs if nothing ran in step 1, no sub-command node exists, the root has `exec`, and either root args were given (`argsList.length > 0`) or the root has no `args` spec. Then `parsed.execCmd` is the root and the count is 1.
3. If the count is 0 and any `exec` exists in the spec tree, the `no-action` event is emitted.

`runExec` cannot await. If a handler returns a thenable, it keeps running detached, and after the run `runExec` prints `Warning: async exec handler ... invoked synchronously ...` through `output`. Use `parseAsync` (or `skipExec` and `runExecAsync`). `runExecAsync` awaits each handler in sequence and does not warn. Calling `runExec` or `runExecAsync` after `parse` already ran handlers runs them again.

Handlers must not mutate the parsed tree.

### `applyConfig(config, parsed, src = "user")`

Merges outside values (for example a config file) into a parsed result. For each key in `config`:

- If the key matches a known option (by name or alias) of the root command and that option is absent or its source does not start with `"cli"`, it is replaced by the config value with source `src`. A command line value always wins.
- If the key is not a known option and not already present, it is added as an unknown option with source `src`.
- Only root command options are matched. Values may be non-strings; they are placed through the normal argument conversion (`[].concat(value)` per argument).
- The cached `jsonMeta` is cleared for the root so `opts`, `source` reflect the change.

Returns `this`. It does not re-run the required check, so config cannot satisfy a `required` option.

### `removeDefaultHandlers(...events)`

Removes the listeners this instance installed for the named events. `"*"` as the first argument removes every default handler in the handler table, but not the `"exit"` listener. A handler you passed through `config.handlers` is not removed. Returns `this`.

### `version(v)`, `help(custom)`, `usage(msg)`, `cmdUsage(msg)`, `skipExec(skip = true)`

- `version(v)` sets the version. Call before `init`. Returns `this`.
- `help(custom)` sets the help option spec. Pass `false` to disable. Option name is always `help`. Call before `init`. Returns `this`.
- `usage(msg)` and `cmdUsage(msg)` set the usage texts. Return `this`.
- `skipExec(skip = true)` sets both `skipExec` and `skipExecDefault`. Returns nothing (not chainable).

### `makeHelp(cmdPath?)`, `showHelp(err?, cmdPath?)`, `showError(err)`, `showVersion()`

- `makeHelp(cmdPath)` returns help lines. `cmdPath` is a command name or an array of names (sub-command path, aliases allowed). An unknown name returns `["Unknown command: <name>"]`. Layout: a blank line, `Usage: ...`, the description (indented), an alias note when called by alias, `Commands:` (one line per sub-command: `<name> <args> <desc> [aliases: a b]`) and `Options:` (see Help text).
- `showHelp(err, cmdPath)`: emits `pre-help`, writes the help lines plus `\n`, and if `err` is given writes `\nError: <message>\n` and uses exit code 1. Then writes `\n`, emits `post-help`, and calls exit with the code (0 without `err`).
- `showError(err)` and `showVersion()` are as in the default handlers above.

Usage line rules in `makeHelp`: the command's own `usage` wins, then `usage()` for root help, then `cmdUsage()` for sub-commands. When the root has `args` and sub-commands, two usage lines are printed (the usage line and `<name> <command> [command-args] [options]`). With the default usage and only sub-commands the line is `Usage: <name> <command>`. With the default usage and only root `args`, it is `Usage: <name> <args>`.

### Help text

Options lines are `--name, -a, --alias  <desc> [<type>] [default: <JSON>]`, padded so descriptions align and wrapped to the terminal width (`process.stdout.columns`, 80 if unknown). `<type>` is the first argument type, followed by ` ..` when the option takes more than one value. `[default: ...]` shows only for single-argument options with a truthy `argDefault`. Commands without options show `Command <name> has no options` only if the option list is empty. Rows alternate dim styling unless `helpZebra` is false.

### Events

`NixClap` extends `EventEmitter`. All events are emitted synchronously.

| event | arguments | when |
| --- | --- | --- |
| `pre-help` | `{ self }` | start of `showHelp` |
| `help` | `ParseResult` | built-in `--help` given |
| `post-help` | `{ self }` | end of `showHelp`, before exit |
| `version` | none | `--version` given |
| `parse-fail` | `ParseResult` | parse errors present |
| `no-action` | none | no `exec` ran but exec handlers exist |
| `exit` | `code: number` | after help, version or error output (only without a custom `exit`) |

## Argument parsing rules

### Option forms

An argv entry starting with `-` is an option token. Anything else is a command name or an argument.

| token | meaning |
| --- | --- |
| `--name` | option `name` (or an alias with 2 or more characters) |
| `-x` | option or alias `x` |
| `--name=value` | inline value. The `=` must be at index 1 or later of the name. Consumes no more argv entries. |
| `-abc` | cluster: `a` and `b` are set as options with no values, `c` is the last option and may take values. A leading option that expects arguments gets none from the cluster and then fails with `Not enough arguments for option` if it has required args. |
| `--no-name` | sets `name` to `"false"` (so a boolean option becomes `false`). The name is the text after `no-`. A spec option literally named `no-x` cannot be set with this form. |
| `-.` or `--.` | ends the current option's argument gathering. Used when the option is variadic. Also ends greedy mode and ends the current command's argument gathering so a following word can be a sub-command. |
| `-#`, `-`, `---` | greedy mode for the current command: following non-option words are taken as its arguments, even if they match sub-command names. Option tokens are still parsed as options. Leave with `-.`. |
| `--` | stops parsing. Remaining entries are returned in `parsed._` and are not parsed. |

Short and long forms are not distinguished by dash count in matching: `-verbose` is a cluster of single characters, and `--v` matches an option or alias named `v`. Any alias or name works with one or two dashes when it is one character; names longer than one character need `--`.

A negative number such as `-5` is an option token. Give it as `--n=-5`.

### Aliases and names

- `alias` is a string or an array of strings. Each alias is unique within one command's options.
- Matching is exact and case sensitive. Own-property lookup, so names like `constructor` are safe.
- Names with `-` get a camelCase key (`dry-run` and `dryRun`) in `opts` and `source`. Aliases used on the command line also get keys (see Result shape).

### Option values

Value consumption for `--name value ...`:

- An option with no `args`: takes no values. Result `true`, or `false` for `--no-name`. With `--name=value` the inline value is converted by shape: boolean words (`true false yes no on off`, case insensitive) become booleans, numeric strings become numbers, anything else stays a string. Note that `--flag=0` gives the number `0` and `--flag=1` gives `1`.
- An option with `args`: takes following non-option words up to the number of arguments it expects (the sum of the maxima), stopping early at the next option token. A missing required argument adds the error `Not enough arguments for option '<name>'`.
- If the first argument is typed `boolean` and the next word is not a boolean word (`true false yes no on off`), no word is consumed and the value is `true`. `0` and `1` are not boolean words. `--b yes` gives `true`, `--b no` gives `false`.
- A variadic option consumes every following non-option word, including words that match command names.

### Argument specifiers (`args`)

`args` is a string of `<...>` (required) and `[...]` (optional) groups. All required groups must come before optional ones. Each group is `name type..range`, all parts optional:

| group | meaning |
| --- | --- |
| `<name>` | required, type `string` |
| `<name number>` | required, named, typed |
| `<number>` | name omitted only if written with a leading space: `< number>`. A lone word is the name, so `<string>` throws (a name cannot be a type name). |
| `<..>` | variadic, 0 or more |
| `<name..>` | variadic, 0 or more |
| `<..3>` | exactly 3 (array) |
| `<..1,>` or `<..1,Inf>` | 1 or more |
| `<..1,3>` | 1 to 3 |

- Types: `string` (default), `number`, `int`, `integer`, `float`, `boolean`, plus keys of `customTypes`.
- `number` and `float` use `parseFloat`. `int` and `integer` use `parseInt(v, 10)`. Failed numeric parses give `NaN`, with no error.
- `boolean` uses the rules in Boolean conversion below.
- A required group's minimum counts toward the required total. An optional group contributes nothing to the required total.
- Only the last group may be variadic. A variadic group, or any `..` group, yields an array value.
- The type of an unnamed (no name) group is still used. Values are stored by index and by name when named.
- A command or option with `args` set to a string that has no groups throws `InvalidArgSpecifierError`.

Errors thrown at `init` time:

- `InvalidArgSpecifierError` (has `arg: string`): `Invalid args specifier '<x>' for '<name>'.`, `... Unknown type '<t>' for argument '<group>'.` (message prefixed with `option <name>` or `command <name>`), `Required arg '<x>' cannot follow optional arg '<y>'.`, `For args of <name> - Its name is using a type name: <t>.`
- Plain `AssertionError` (from `node:assert`, not `InvalidArgSpecifierError`): `For args specifier of '<name>', only the last one can be variadic`. A malformed range such as `..x` throws a plain `Error` (`Invalid number input 'x' - expected an integer`).

### Boolean conversion

For type `boolean` (and for no-`args` inline values that look like booleans):

- A numeric string is `false` if it equals 0, otherwise `true`.
- `false`, `no`, `off` (case insensitive) are `false`. Any other non-empty string is `true`. An empty string is `false`.
- Auto-boolean detection (`isBoolean`) recognizes only `true false yes no on off`, which is what decides whether `--b word` consumes `word`.

### Custom types

`customTypes: Record<string, fn | RegExp | string>` on an option or command. Every `type` used in `args` that is not a built-in type must be a key.

| handler | result |
| --- | --- |
| function `(value: string) => any` | its return value. If it throws, an error is added to the node with the thrown message, and the value becomes `"<type> custom type function threw error: <message>"`. |
| `RegExp` | `value.match(re)[0]` if it matches. If not and the spec has a truthy `argDefault`, that default is used. Otherwise the error `argument '<v>' didn't match RegExp requirement for <name>` is added and the raw string stays as the value. |
| string | the string, regardless of input. |

A legacy spec key `coercions` is read as a fallback when `customTypes` is absent. It is not in the TypeScript types. Values passed in already non-string (from `applyConfig`) skip conversion.

### Counting options

`counting: number` marks an option as counting. Each time it appears on the command line, its count goes up by one. `opts[name]` is the count and `optsCount[name]` holds the same count. The number given is not enforced by the code: `counting: 3` still counts a fourth occurrence. A counting option with `args` and exactly one argument yields that argument value in `opts` (single-arg takes priority over counting).

Repeating a non-counting option replaces the earlier value.

### Sub-commands

- A non-option word is matched against the current command's sub-commands (name, then alias). A match creates a command node and further words go to it.
- A command first takes arguments for itself while it has gathered fewer than `expectArgs`. A word that matches one of its sub-commands is always treated as a command first.
- Once a command has gathered all its expected arguments, further words go to its parent chain: a sibling sub-command or a parent argument. If nothing takes it: `Encountered unknown CLI argument '<w>' while parsing for command '<cmd>'.`
- A command that has sub-commands, no `exec`, no `args` and no matched sub-command yet requires one: an unknown word gives `Command '<name>' requires a subcommand. Unknown: '<w>'.`
- Multiple sub-commands can follow each other: `prog a b` runs `a` and `b` when both are root sub-commands. A sub-command of a sub-command is nested under its parent.
- Command arguments are gathered when the command ends (a new sub-command, `-.`, a full set, or end of argv). Missing required ones add `Not enough arguments for command '<name>'.`
- Unknown options are checked against the current command, then its ancestors (see Unknown handling).

### Default command

With `defaultCommand: "name"`:

- It triggers only when argv contains no non-option word at all (no word, no `--`), after skipping the values consumed by known root or default-command options, and no help or version token (`--help -h -? --version -v -V`) is present.
- Then the default command node is created up front, its option defaults are applied, and parsing continues under it. Root options still match.
- If the name does not match a command, the root gets the error `default command <name> not found`.
- Not triggered when the first word is an unknown command. That gives the normal unknown-command error (or `unknownCommandFallback`).
- With `skipExecDefault` (or `skipExec()`), the default command is not inserted, so it does not run.

### Unknown handling

- Unknown option: the option is looked up on the current command. If it has `allowUnknownOption` undefined, the lookup continues in the parent commands up to the root. If the command has `allowUnknownOption: false`, it errors there. At the root the effective value is `spec.allowUnknownOption ?? config.allowUnknownOption`. On error the message is `Encountered unknown CLI option '<name>'.` (an `UnknownOptionError` with `data`), and the option is still recorded in `opts`. With the flag true, the option is recorded with no error. Unknown options take no following words. `--x=1` records `1`.
- Unknown command word: see `UnknownCliArgError` and the messages above. With `allowUnknownCommand`, the word becomes a node under the root (or under the command that requires a sub-command), and `parsed.command.subCommands[word]` exists. Unknown-command nodes expect no arguments, so the next unknown word becomes a sibling.
- `unknownCommandFallback: "run"`: at the root, if no command matched yet and no root argument was taken, the first unknown word becomes the first argument of `run`, and later words continue to be gathered by `run`.

### Required options

`required: true` on an option. After parsing, if the option is absent from the root command node or a matched sub-command node, the root gets `missing these required options a, b`. An option satisfied only by `argDefault` is still reported missing. `required` is only checked for options. On commands it is accepted by the type but not used.

### Defaults

`argDefault` on an option: if the option is not in the command line (and was not added by `applyConfig`), after parsing it is added with `source: "default"`, using `[].concat(argDefault)` as its arguments. Applies to the root and to command nodes that exist in the result. Sub-commands not named on the command line get no defaults. A default is added even when the key exists with value `undefined` or `null` (`null` becomes `[null]`). For commands, `argDefault` has no effect except as the RegExp custom-type fallback above.

## Spec types

### `OptionSpec`

```ts
interface OptionSpec extends BaseSpec { counting?: number }
```

Also inherits the `BaseSpec` fields in the shared table below.

### `CommandSpec`

```ts
type CommandSpec = BaseSpec & {
  exec?: CommandExecFunc | ((cmd: CommandNode, parsed?: ParseResult) => Promise<void>);
  usage?: string | (() => string);
  options?: Record<string, OptionSpec>;
  subCommands?: Record<string, CommandSpec>;
  allowUnknownOption?: boolean;
};

type CommandExecFunc = (cmd: CommandNode, parsed?: ParseResult) => void;
```

### Fields shared by both (`BaseSpec`)

| field | type | default | behavior |
| --- | --- | --- | --- |
| `name` | `string` | the key | Declared but unused. The record key is the name. |
| `alias` | `string \| string[]` | none | Other names. Unique per parent (commands) or per command (options). |
| `desc` | `string \| () => string` | none | Help description. A function is called each time help is built. |
| `required` | `boolean` | none | Options only. See Required options. |
| `args` | `string` | none | Argument specifier string. |
| `argDefault` | `string \| string[] \| null` | none | Default arguments. See Defaults. |
| `customTypes` | `Record<string, ((value: string) => any) \| RegExp \| string>` | none | Custom argument types. |

Extra fields on `CommandSpec`:

| field | type | default | behavior |
| --- | --- | --- | --- |
| `exec` | function | none | Called after parse for each matched command. May be async only under `parseAsync`/`runExecAsync`. |
| `usage` | `string \| () => string` | none | Usage text for this command's help. `$0` is replaced by the program name and `$1` by the command name. |
| `options` | `Record<string, OptionSpec>` | `{}` | Options for this command. |
| `subCommands` | `Record<string, CommandSpec>` | none | Nested commands. |
| `allowUnknownOption` | `boolean` | undefined | `true` accepts unknown options. `false` errors on them at this command. Undefined defers to the parent. |

Extra field on `OptionSpec`: `counting?: number` (see Counting options).

### `Command` (class export)

```ts
class Command {
  constructor(name: string, cmdSpec: CommandSpec, ncConfig?: NixClapConfig, parent?: Command);
  name: string;
  args: ArgInfo[];            // parsed argument specifier
  needArgs: number;           // required argument count
  expectArgs: number;         // maximum argument count
  variadic?: { min: number; max: number };
  options: Options;           // option table
  subCmdCount: number;
  subCmdsBase: Record<string, Command>;
  subAliases: Record<string, string>;
  execCount: number;
  parent?: Command;
  readonly desc: string; readonly usage: string; readonly exec: Function | undefined;
  readonly alias: string[]; readonly cmdSpec: CommandSpec;
  readonly allowUnknownOption: boolean | undefined; readonly verbatimArgs: string;
  matchSubCommand(alias: string): { name: string; alias: string; cmd: Command | undefined };
  getExecCount(): number;
  makeHelp(progName?: string): string[];   // sub-command listing lines
  setCommandAliases(alias: string[], name: string): void;
  verifyOptionNotExist(optName: string, from: Command): void;
  verifyNoDupOptions(): void;
}
```

This is the processed form of a `CommandSpec`. Applications normally create commands only through `NixClap`. The constructor builds sub-commands and the option table recursively, and throws the init-time errors listed under `init2`. `ArgInfo` and `Options` are not exported by name.

## Parse results

### `ParseResult`

```ts
type ParseResult = {
  command: CommandNode;       // root command node
  errorNodes?: ClapNode[];    // nodes with errors (always set by parse/parse2)
  execCmd?: CommandNode;      // first node whose exec ran
  helpNode?: CommandNode;     // node that got --help, set by parse before the help event
  _: string[];                // argv entries after `--`
  argv: string[];             // the argv that was parsed
  index: number;              // parse stop index
};
```

`ClapNode` is not exported by name. Each error node has `error` (the first error), `errors`, `hasErrors`, `name`, `alias`, and `argv`.

### `CommandNode`

```ts
class CommandNode {
  name: string; alias: string;      // alias is the word used on the command line
  argsList: string[];               // raw argument words
  argsMap: Record<string, ArgumentValue>;
  argv: string[];                   // verbatim argv consumed (starts with the command name)
  subCmdNodes: Record<string, CommandNode>;
  optNodes: Record<string, OptionNode>;
  optCount: Record<string, number>;
  cmdBase: Command;
  isGreedy: boolean;
  readonly opts: Record<string, OptionValue>;
  readonly args: Record<string, ArgumentValue>;
  readonly source: Record<string, OptionSource>;
  readonly optsFull: Record<string, Record<string, ArgumentValue>>;
  readonly options: Record<string, Record<string, ArgumentValue>>;  // same as optsFull
  readonly subCommands: Record<string, CommandMeta>;
  readonly jsonMeta: CommandMeta;
  readonly rootCmd: CommandNode;
  readonly cmdChain: CommandNode[];  // root to this node, inclusive
  readonly hasErrors: boolean; readonly error: Error; readonly errors: Error[];
  readonly parent: ClapNode;
  getParent<T>(): T;
  getErrorNodes(errorNodes?: ClapNode[]): ClapNode[];
  getExecCommands(cmds: CommandNode[], includeSubCommands: boolean): CommandNode[];
  invokeExec(includeSubCommands: boolean, parsed?: ParseResult): number;
  invokeExecAsync(includeSubCommands: boolean, parsed?: ParseResult): Promise<number>;
  applyConfig(config: Record<string, any>, src?: OptionSource): void;
  applyDefaults(): void;
  makeCamelCaseOptions(): void;
  checkRequiredOptions(missing?: string[]): string[];
}
```

`opts`, `args`, `source`, `optsFull`, `options` and `subCommands` read from `jsonMeta`, which is built lazily and cached. After you mutate nodes yourself, the cache is stale. `NixClap.applyConfig` clears it for you.

### `CommandMeta` (`node.jsonMeta`)

| field | type | content |
| --- | --- | --- |
| `name` | `string` | command name (the root's name is the program name) |
| `alias` | `string` | word used on the command line (`~root-command~` for root) |
| `opts` | `Record<string, OptionValue>` | option values by name (see below) |
| `optsCount` | `Record<string, number>` | occurrence counts. Counts every option, not only counting ones. |
| `optsFull` | `Record<string, Record<string, ArgumentValue>>` | each option's full argument map: keyed by argument name (when named) and index |
| `args` | `Record<string, ArgumentValue>` | command arguments by argument name and index |
| `argList` | `string[]` | raw argument words, including ones beyond the spec |
| `source` | `Record<string, OptionSource>` | where each option came from |
| `verbatim` | `Record<string, string \| string[]>` | always `{}` in this version |
| `subCommands` | `Record<string, CommandMeta>` | matched sub-commands by name |
| `ccLong`, `unknown` | optional | declared, never set |

`opts[name]` value shape:

- Option with exactly one argument in its spec: the converted value (`opts.n`), or an array for `..` arguments.
- Counting option without args: the count.
- No-`args` option: `true`, or `false` for `--no-x`, or the inline value as converted by shape.
- Otherwise (two or more arguments): the argument map (keys are indexes and names, such as `{ "0": "1", "1": 2, a: "1", b: 2 }`).

Keys: the long name, its camelCase form if different, and the alias used on the command line if different from the name. `source` and `optsFull` use the same keys. An option given by an alias that was not used on the command line has no alias key.

`OptionSource` values: `"cli"`, `"default"`, `"user"` are assigned. `"cli-default"` and `"cli-unmatch"` are in the type but never assigned by this code. Unknown options from the command line have `"cli"`.

`OptionValue` and `ArgumentValue` are both `unknown`. Narrow before use.

## Error classes

```ts
class InvalidArgSpecifierError extends Error { arg: string; constructor(msg: string, arg?: string) }
class UnknownOptionError extends Error { data: OptionMatch; constructor(msg: string, data: OptionMatch) }
class UnknownCliArgError extends Error { arg: string; constructor(msg: string, arg: string) }
```

- `InvalidArgSpecifierError`: thrown synchronously from `init`/`init2` (or `new Command`) for a bad `args` string. `arg` is the offending specifier string for the unknown type case and `""` for other cases.
- `UnknownOptionError`: created during parsing and stored on the command node (`errorNodes[i].error`). Not thrown to the caller. `data` has `name`, `alias?`, `value`, `verbatim`, `arg` (the raw token) and `dashes`.
- `UnknownCliArgError`: created during parsing for an argument or command nobody can take, and stored on the node. `arg` is the word. Not thrown to the caller.

All other parse errors (`Not enough arguments ...`, `missing these required options ...`, RegExp mismatch, custom function errors, `default command ... not found`) are plain `Error` objects stored on nodes.

## Defaults and environment

- Output goes to `process.stdout` unless `output` is set. Terminal width comes from `process.stdout.columns`, 80 if unset.
- The package reads no environment variables and no config files. `applyConfig` is the hook for config values.
- `process.argv` is used only when `parse`/`parseAsync`/`parse2` get `argv === undefined`.

<!-- chalker v2.2.1: https://fynjs.pages.dev/ref/chalker.md -->

# chalker reference

`chalker` turns XML-like markers such as `<red>text</red>` in a string into ANSI color codes. It delegates the styling to a colors backend: `chalk`, `ansi-colors`, or Node's `util.styleText`. ESM only (`"type": "module"`).

## Imports

```js
import chalker from "chalker";                 // auto-detect backend (top-level await)
import chalker from "chalker/chalk";           // static: chalk
import chalker from "chalker/ansi-colors";     // static: ansi-colors
import chalker from "chalker/style-text";      // static: node:util styleText, no dependency
import { makeChalker } from "chalker";         // also from every subpath below
import { makeChalker } from "chalker/core";    // no backend, no default export
import { styleTextColors } from "chalker/style-text";
```

Subpaths: `.`, `./chalk`, `./ansi-colors`, `./style-text`, `./core`, `./package.json`.

Runtime exports by entry:

| Entry | Default export | Named runtime exports |
| --- | --- | --- |
| `chalker` | `chalker` function | `makeChalker` |
| `chalker/chalk` | `chalker` function | `makeChalker` |
| `chalker/ansi-colors` | `chalker` function | `makeChalker` |
| `chalker/style-text` | `chalker` function | `makeChalker`, `styleTextColors` |
| `chalker/core` | none | `makeChalker` |

Type-only export from every entry: `ChalkerFn`.

Not exported: `normalizeColors`, `decodeHtml` and `remove` as standalone functions (they exist only as `chalker.decodeHtml` and `chalker.remove`), and the color-model helpers. There is no named export called `chalker`.

Entry differences:

- `chalker` loads its backend at import time with a top-level `await`. Because of that it cannot be loaded by `require()` (source comments cite `ERR_REQUIRE_ASYNC_MODULE`), and a bundler must leave the backend external. The static entries have no top-level await.
- `chalker` tries `chalk`, then `ansi-colors`, then (if neither is installed and `node:util` has a function `styleText`) the built-in `styleTextColors`. If none works it imports `chalk` again and lets the not-found error propagate.
- `chalker/chalk` and `chalker/ansi-colors` hard-import their peer dependency. A missing peer is an import-time resolve error.
- `chalker/style-text` throws `TypeError("chalker/style-text requires a Node.js version with util.styleText")` at import when `util.styleText` is not a function.
- Each entry builds its own chalker through `makeChalker`, so entries do not share `CHALK` state.
- `package.json` peer dependencies: `chalk >=4` and `ansi-colors >=4`, both optional. Runtime dependencies: `color-convert`, `optional-import`. Node engines: `^22.22.2 || ^24.15.0 || >=26.0.0`.

## `makeChalker(colors)`

```ts
function makeChalker(colors: any): ChalkerFn
```

Builds a chalker bound to a colors module. `colors` is a chalk or ansi-colors module or default export, or any object with chalk-shaped chains (such as `styleTextColors`). Every entry's default export is `makeChalker(<its backend>)`.

- `chalker.CHALK` is set to `normalizeColors(colors)`. Normalizing uses `colors.default` when that is a function or object, otherwise `colors` itself. Then the ansi-colors compat step runs (see `CHALK` below).
- No validation of `colors` happens here. A bad value fails later, on the first format call.
- Each call returns a new function with its own `CHALK`, `remove` and `decodeHtml` properties.

## `ChalkerFn`

```ts
type ChalkerFn = {
  (s?: string | readonly string[] | null, ...args: unknown[]): string;
  remove: (s: string, keepHtml?: boolean) => string;
  decodeHtml: (s: string) => string;
  CHALK: any;
};
```

The type of every default export and of the `makeChalker` return value.

## `chalker(s, colors?)` and the tagged template form

```ts
chalker(s?: string | null, colors?: any): string
chalker(strings: readonly string[], ...values: unknown[]): string
```

Converts markers in `s` to ANSI codes and returns the string.

String form:

- The second argument is an optional colors module used for this call instead of `chalker.CHALK`. It is normalized the same way as `CHALK` (`.default` unwrap, ansi-colors compat). Only `args[0]` is read.
- A falsy `colors` argument falls back to `chalker.CHALK`. `CHALK` is read at call time, so assigning `chalker.CHALK = other` takes effect on the next call.
- `s` of `""`, `null` or `undefined` returns `""` when colors are enabled.
- A string with no match for the tokenizer returns unchanged (not entity-decoded). That is only a string made solely of `<` and `>` characters, such as `"<"`, `"<>"`, `">"`.

Tagged template form (detected with `Array.isArray(s)`):

- The cooked strings and `String(value)` of each interpolation are joined into one string first, then that string is formatted. Interpolated text is parsed for markers like any other text, so a value containing `<` can inject or break markers.
- A `colors` override cannot be passed in template form. Every argument after the strings is treated as an interpolated value.
- A plain array passed as the first argument is treated the same way (`["a", "b"]` formats `"a"`, because the loop reads `s[ix]` for `ix` up to `args.length`).

```js
chalker("<red.bgGreen>Red on Green</>");
chalker`<green>hello ${name}</green>`;
chalker("<red>x</>", new chalk.Instance({ level: 2 }));
```

### Color-disabled behavior

After normalizing the colors module, if `colors.supportsColor === false` (strict comparison) the call returns `chalker.remove(s)`. That means:

- All `<...>` tags are stripped without parsing, so malformed, unbalanced or unknown markers do not throw.
- The result is trimmed and entity-decoded.
- `null` or `undefined` input throws `TypeError` (`.replace` on a non-string). `""` returns `""`.
- A stray `<` and later `>` in plain text are removed as if they were a tag (`"a < b > c"` loses `< b >`). The enabled path handles that text differently (see Tokenizing).

Only the exact value `false` disables. `undefined` (for example chalk 6 instances, ansi-colors, `styleTextColors` have no `supportsColor`) means colors stay on in chalker. Whether codes then appear is up to the backend's own level (chalk `level`, ansi-colors `enabled`, Node `styleText` stream checks).

## Marker grammar

### Tokenizing

The string is split with `/(<[^>]+>|[^<>]+)/g`.

- A tag is `<` followed by one or more non-`>` characters and `>`. Everything else between tags is text.
- A `<` with no later `>` and a stray `>` are not matched by either alternative, so they are silently dropped from the output (`"a > b"` gives `"a  b"`, `"a < b"` gives `"a  b"`). `<>` is not a tag and is dropped too (it only survives as the whole string, see above).
- To get a literal `<` or `>` in output, write `&lt;` or `&gt;`. Entities are decoded after styling, so `&lt;red&gt;` becomes the literal text `<red>` and is never parsed as a marker.
- Tags cannot contain `>`.

### Open and close markers

- A tag whose second character is `/` is a close marker. Its name is the text between `</` and `>`. `</>` has the empty name and closes any open marker.
- Any other tag is an open marker. Its name is the text between `<` and `>`, untrimmed.
- Matching is exact string comparison between the open name and the close name, including whitespace and case. `<red>a</red >` is a mismatch. A named close marker must equal its open marker. `</>` always matches.
- There are no self-closing or standalone tags. `<red/>` is an open marker named `red/`.

Nesting is by proper pairing. Text is processed from the end of the string to the start with a stack.

```js
chalker("<red>a<blue>b</>c</>");   // red(a + blue(b) + c), inner applied first
```

Errors (all plain `Error` unless noted):

| Condition | Message |
| --- | --- |
| Open marker with no pending close marker to its right | `unbalanced open/close markers: <text before>[<tag>]...` (the trailing `...` is present when more tokens follow) |
| Open and close names differ | `mismatch markers: <text>[** <open> **]<between>[** <close> **]` |

A close marker with no matching open marker is not an error. Because of how the stack unwinds, the close marker and all text to its right, up to the next open marker that consumes it, behave oddly: `"abc</red>"` returns `""` (text is lost) and `"</red>abc"` returns `"abc"`. Treat stray close markers as a bug in the input.

Whitespace inside text between markers is preserved (`"<red> a </red>"` styles `" a "`). The enabled path never trims.

### Marker name syntax

A marker name is split on `.` (so `.` cannot appear inside a segment) and each segment is trimmed, then applied left to right to build a chain, then the chain is called with the text. The whole name is trimmed first. The chain must end as a function, else `AssertionError("final chalk value is not a function after applying <name>")`.

Segment resolution order, first match wins:

1. Basic style: if `chain[segment]` is truthy, use it. This is any property the backend exposes, such as `red`, `bold`, `bgRed`, `underline`, `gray`. The valid names are whatever the backend provides, they are not listed in chalker. For `styleTextColors` the names are `Object.keys(util.inspect.colors)` of the running Node. A non-function property such as `level` is accepted here and fails at the final function check.
2. Hex: a segment starting with `#` calls `chain.hex(segment)`.
3. Background hex: a segment starting with `bg` whose character at index 2 or index 3 is `#` (`bg#0000FF`, `bg-#0000FF`, `bg #0000FF`) calls `chain.bgHex(segment)` with the whole segment, including the `bg` prefix. The hex parser finds the first 3 or 6 hex digit run, so it works.
4. Parenthesized form: if the segment contains `(` (see below).
5. Keyword fallback: otherwise, optional matching quotes are removed, then a `bg-` or `bg ` prefix selects `bgKeyword` (the first 3 characters are dropped), else `keyword`.

#### Parenthesized form

`name(args)`. Text up to the first `(` is the name (trimmed, may be empty). Args are the text between that `(` and the last `)` in the segment, trimmed.

- No `)` after the `(`: `AssertionError("marker <segment> missing matching ()")`.
- Args containing `,`: split on `,`, each part `parseInt(part.trim(), 10)` (a non-number gives `NaN`, not an error). An empty name becomes `rgb`, name `bg` becomes `bgRgb`.
- Args without `,`: one string value with optional matching quotes removed. An empty name becomes `keyword`, name `bg` becomes `bgKeyword`.
- Any other name is used as is and is case sensitive. Examples: `rgb`, `bgRgb`, `hex`, `bgHex`, `keyword`, `bgKeyword`, `hsl`, `bgHsl`, `hsv`, `bgHsv`, `hwb`, `bgHwb`.
- Quotes are `'`, `"` or a backtick. If the first character is a quote, the last must be the same quote, else `AssertionError("chalk <segment> param must be enclosed with matching quote <q>")`. Both enclosing characters are removed. Commas inside quotes still split.
- The named method is called on the current chain with the values spread. If `chain[name]` is a function it is used. Otherwise, for `keyword`, `bgKeyword`, `hsl`, `bgHsl`, `hsv`, `bgHsv`, `hwb`, `bgHwb`, chalker converts the values to RGB with `color-convert` and calls `rgb` or `bgRgb` instead. For `keyword` the value is lowercased. A failed conversion throws `unknown color <value>`. Any other missing name throws `TypeError("<name> is not a chalk function")`. Errors from this step are rewrapped as `Error("marker <segment> is invalid: calling chalk.<name> failed with: <message>")`.
- So chalk 4 (which has native `keyword`/`hsl`/...) uses its own methods. Chalk 5 and later, ansi-colors and styleText go through `color-convert`.

#### Keyword fallback details

- `<orange>`, `<'orange'>`, `<"orange">`, `` <`orange`> `` all use `keyword`. `<bg-orange>`, `<bg orange>`, `<"bg-orange">` use `bgKeyword("orange")`.
- Keywords are CSS color names via `color-convert`, lowercased, so `<Red>` is not the basic `red` style. It resolves to the keyword `red` and emits 24-bit RGB `38;2;255;0;0` (when the backend supports it).
- Any failure, including a quote mismatch here, becomes `Error("marker <segment> is not found and invalid as a keyword")`. So an unknown marker like `<foo>` throws. Unknown tags are never passed through as text.

#### Examples

| Marker | Effect |
| --- | --- |
| `<red>`, `<blue.bold>` | basic styles |
| `<#FF0000>`, `<hex(#FF0000)>` | `hex` |
| `<bg#0000FF>`, `<bgHex(#0000FF)>` | `bgHex` |
| `<(255,10,20)>`, `<rgb(255,10,20)>` | `rgb` |
| `<bg(255,10,20)>`, `<bgRgb(255,10,20)>` | `bgRgb` |
| `<(orange)>`, `<keyword('orange')>`, `<orange>` | `keyword` |
| `<bg(orange)>`, `<bgKeyword(orange)>`, `<bg-orange>` | `bgKeyword` |
| `<hsl(32,100,50)>`, `<hsv(32,100,100)>`, `<hwb(32,0,50)>` | model converted to RGB |
| `<red.bold.bg#00f>` | chained, in the listed order |

Chain order: segments chain left to right. chalk and ansi-colors give the same output as chaining those names in code (`chalk.red.bold.bgHex(...)`).

### Entities

`chalker.decodeHtml` is applied to the final formatted string (after styling), and by `chalker.remove` unless `keepHtml` is true. Marker names are never decoded.

## `chalker.CHALK`

```ts
CHALK: any
```

The colors module used when a call has no override. Own, writable property of each chalker.

- Assign a chalk instance or module, an ansi-colors module, or `styleTextColors`: `chalker.CHALK = ansiColors`.
- It is normalized on every call. The stored value is not replaced by the normalized one when you assign it.
- ansi-colors compat: if the module has a function `alias` and no function `rgb`, chalker mutates that module in place by adding `rgb`, `bgRgb`, `hex` and `bgHex` (using `color-convert` for hex). Each distinct color is registered once through `colors.alias` under a name like `chalker_rgb_1_2_3` or `chalker_bgRgb_1_2_3`. These mutations are visible to other users of the same ansi-colors module.
- Passing `null`/`undefined` as `CHALK` and no override makes a call throw `TypeError` when reading `supportsColor`.

## `chalker.remove(s, keepHtml?)`

```ts
remove(s: string, keepHtml?: boolean): string
```

Deletes every match of `/<[^>]*>/g` (so `<>` goes too, and any `<` ... `>` span, valid marker or not), trims the result, then decodes entities unless `keepHtml` is truthy.

- No balance or name checks. Never throws on markup.
- A non-string `s` throws `TypeError`.
- Does not use `CHALK`.
- Decoding can throw `RangeError` (see `decodeHtml`).

```js
chalker.remove("<red>a &lt; b</red>");        // "a < b"
chalker.remove("<red>a &lt;</>", true);       // "a &lt;"
```

## `chalker.decodeHtml(s)`

```ts
decodeHtml(s: string): string
```

Replaces each match of `/&[\w#]+;/g` in one pass.

- Named entities, exactly these: `&quot;` `"`, `&amp;` `&`, `&apos;` `'`, `&lt;` `<`, `&gt;` `>`, `&nbsp;` U+00A0, `&copy;` U+00A9, `&reg;` U+00AE.
- `&#x<hex>;` decodes the hex code point with `String.fromCodePoint(parseInt(hex, 16))`. `&#<dec>;` decodes decimal the same way. Lowercase `x` only.
- Any other named entity (`&foo;`) is left as is.
- Decoding is single pass: `&amp;lt;` gives `&lt;`.
- An invalid numeric reference throws `RangeError`: non-numeric (`&#xZZ;`, `&#X41;`, `&#;`) gives `Invalid code point NaN`, and values above `0x10FFFF` are also a `RangeError`. Surrogate halves such as `&#xD83D;&#xDC69;` decode to two code units that join into one character.

## `styleTextColors`

```ts
const styleTextColors: any  // from "chalker/style-text" only
```

A chalk-shaped chain built on `util.styleText`. It is the backend of `chalker/style-text` and of the fallback in `chalker`.

- Each name in `Object.keys(util.inspect.colors)` is a getter that returns a new chain with that style appended. Chains are callable: `styleTextColors.red.bold("x")`.
- `rgb(r, g, b)`, `bgRgb(r, g, b)`, `hex(value)`, `bgHex(value)` are methods on every chain. They emit 24-bit escapes directly (`38;2;r;g;b` closing with `39`, background `48;2;...` closing `49`) and bypass `styleText`. `hex` parses with `color-convert`.
- Order: the step chained first ends up outermost. Chains mix named and RGB steps in any order.
- No `supportsColor` or `level` property exists on it. Named styles are applied by `util.styleText(name, text)` with default options, so Node's own stream and color checks decide whether named styles emit codes. RGB and hex escapes are always emitted.
- Known gap stated in source: this backend does not re-open an outer style after a nested style closes or after a newline, so nested siblings or multi-line spans can lose the outer style where chalk would keep it.

## Behavior summary

- Marker text is applied inside out: innermost markers first, each result wrapped by its parent.
- Output of the enabled path is passed through `decodeHtml` once at the end.
- Errors are thrown synchronously from the call. There is no non-throwing mode except the color-disabled path.

<!-- visual-logger v2.1.9: https://fynjs.pages.dev/ref/visual-logger.md -->

# visual-logger reference

`visual-logger` is a console logger for Node.js CLIs. It prints log lines and can keep a block of live "items" (status lines with optional spinners) redrawn below them on a TTY. On a non-TTY it prints plain lines and optional progress dots. ESM only (`"type": "module"`). Runtime dependencies: `chalk`, `log-update`.

## Imports

```js
import { VisualLogger, Levels, LevelColors, LogItemTypes, defaultOutput } from "visual-logger";
import VisualLogger from "visual-logger"; // default export, same class
```

```ts
import type {
  LogLevel, LogItemType, ItemOptions, UpdateData, VisualLoggerOptions,
  VisualOutput, OutputInterface
} from "visual-logger";
```

Runtime exports: `VisualLogger` (also the default export), `Levels`, `LevelColors`, `LogItemTypes`, `defaultOutput`.

Type-only exports: `LogLevel`, `LogItemType`, `ItemOptions`, `UpdateData`, `VisualLoggerOptions`, `VisualOutput`, `OutputInterface`.

There are no subpaths (only `visual-logger/package.json`). Not exported: the internal `SpinState` and `SpinTimer` types, although `ItemOptions` references `SpinState` through `_spinning`.

## Concepts

- Log line: a message written with `debug`, `verbose`, `info`, `log`, `warn`, `error` or `fyi`. Written to `output.write` with a trailing newline.
- Item: a named status line added with `addItem` and changed with `updateItem`. Rendered as `<display>: <msg>`, optionally prefixed by a spinner frame.
- Item type (`LogItemTypes`): `normal` is the live redrawn display, `simple` prints dots, `none` prints nothing for items.
- Visual mode: items are drawn live. It is on only when all three hold: item type is `normal`, the log level is `<= info`, and the output is a TTY (see "Rendering modes").
- Log level: there is no public API to change it. It is fixed at `info` (30). See `Levels`.

## `VisualLogger`

```ts
class VisualLogger {
  constructor(options?: VisualLoggerOptions);

  get logData(): string[];
  get color(): boolean;
  set color(enable: boolean);

  static get spinners(): string[];
  static get Levels(): typeof Levels;
  static get LogItemTypes(): typeof LogItemTypes;

  debug(...args: any[]): this;
  verbose(...args: any[]): this;
  info(...args: any[]): this;
  log(...args: any[]): this;
  warn(...args: any[]): this;
  error(...args: any[]): this;
  fyi(...args: any[]): this;

  setPrefix(prefixStr?: string): this;
  prefix(x?: string | false): this;

  addItem(options: ItemOptions): this;
  hasItem(name: string | symbol): boolean;
  updateItem(name: string | symbol, data?: string | UpdateData): this;
  removeItem(name: string | symbol): this;
  setItemType(flag?: string | false): this;

  clearItems(): this;
  freezeItems(showItems?: boolean): this;
  unfreezeItems(): this;
  shutdown(showItems?: boolean): void;
}
```

All methods return `this` (chainable) except `hasItem` (boolean) and `shutdown` (void). The class has no `setLogLevel` or level property. Private members are prefixed with `_`.

### Constructor options: `VisualLoggerOptions`

```ts
interface VisualLoggerOptions {
  renderFps?: number;
  output?: OutputInterface;
  maxDots?: number;
  updatesPerDot?: number;
  color?: boolean;
  saveLogs?: boolean;
}
```

| option | type | default | behavior |
| --- | --- | --- | --- |
| `renderFps` | `number` | `30` | Maximum redraws per second. The render interval is `Math.floor(1000 / renderFps + 0.5)` ms. Throws `Error("VisualLogger renderFps must be >= 1 and < 1000")` when `< 1` or `>= 1000`. |
| `output` | `OutputInterface` | `defaultOutput` | Where text goes. Used when falsy-checked with `\|\|`, so any falsy value selects `defaultOutput`. |
| `maxDots` | `number` | `80` | Simple mode: a newline is written once the current dot count reaches this value. Only `undefined` selects the default, so `0` is kept. |
| `updatesPerDot` | `number` | `5` | Simple mode: one `.` is written per this many item updates. Non-finite values (`NaN`, `Infinity`, `undefined`) select `5`. A value of `0` is kept and means no dot is ever written. |
| `color` | `boolean` | `true` | Enables chalk coloring of prefixes and item display names. Only `undefined` selects `true`; other values are passed through `Boolean()`. |
| `saveLogs` | `boolean` | `true` (saved) | When exactly `false`, nothing is appended to `logData`. Any other value saves. |

Constructor behavior:

- Options are merged as `{ renderFps: 30, ...options }`. Passing `renderFps: undefined` explicitly overrides the default with `undefined`. The range check then does not throw (`undefined < 1` is false) and the render interval becomes `NaN`. Do not pass it.
- `renderFps: NaN` also passes the range check, giving a `NaN` interval.
- The range check runs after the fields are set but before `setPrefix()`, so a thrown constructor leaves no usable object.
- The constructor does not call `setItemType`. The item type starts as `normal`. The log level starts at `info`.
- Calls `setPrefix()` so the default prefix is `"> "`.

### `logData`

```ts
get logData(): string[]
```

Returns the live internal array, not a copy. Each saved entry is one string. It is never cleared by the library. Saved entries:

- Every log call, after prefix and `util.format`, including prefix color escape codes. Entries are saved even when the level filter suppresses the output (for example `debug` and `verbose`).
- Every `updateItem` call that passes `data`, saved as the item's full line text (`<display>: <msg>`, colored display, without a spinner frame). Not saved when the item was added with `save: false` or when `UpdateData._save === false`.
- `addItem` and spinner-only updates (`updateItem(name)` with no data) save nothing.

### `color`

```ts
get color(): boolean
set color(enable: boolean)
```

The setter stores the value as given (no `Boolean()` coercion) and calls `setPrefix()` with no argument. Consequences:

- A custom default prefix set earlier with `setPrefix("x")` is reset to `"> "`.
- Items already added keep their previously computed `_display`; only new items and later `UpdateData.display` values follow the new setting.

### Static members

```ts
static get spinners(): string[]
static get Levels(): typeof Levels
static get LogItemTypes(): typeof LogItemTypes
```

- `VisualLogger.spinners` returns a new 4-element array each access. Each element is a string of frames, indexed by character position:
  - `0`: `"|/-\\"`
  - `1`: a braille sequence of 29 frames (`"⠁⠁⠉⠙⠚⠒⠂⠂⠒⠲⠴⠤⠄⠄⠤⠠⠠⠤⠦⠖⠒⠐⠐⠒⠓⠋⠉⠈⠈"`). This is the one used for `spinner: true`.
  - `2`: `"⢹⢺⢼⣸⣇⡧⡗⡏"`
  - `3`: `"⣾⣽⣻⢿⡿⣟⣯⣷"`
- `VisualLogger.Levels` is the same object as the exported `Levels`.
- `VisualLogger.LogItemTypes` is the same object as the exported `LogItemTypes`.

### Log methods

```ts
debug(...args: any[]): this
verbose(...args: any[]): this
info(...args: any[]): this
log(...args: any[]): this   // alias of info
warn(...args: any[]): this
error(...args: any[]): this
fyi(...args: any[]): this
```

Each call, in order:

1. Builds the line: `prefix + util.format(...args)`. `util.format` rules apply (printf-style `%s %d %o`, objects inspected).
2. Appends the line to `logData` (unless `saveLogs === false`). This happens regardless of level filtering.
3. If `Levels[level] >= 30` (the fixed log level): `clearItems()`, then ends any dot line (see `Simple mode`), then `output.write(line + "\n")`, then schedules an item redraw if visual mode is on.
4. Otherwise nothing is printed. `debug` (10) and `verbose` (20) are therefore always suppressed in the current code. `info`, `log`, `warn`, `error` and `fyi` always print.

Prefix choice:

- If a one-shot prefix was set by `prefix(x)`, it is used once and cleared. It is consumed even when the line is filtered out. It is not colored.
- Otherwise the colored default prefix for the level is used. If `chalk.level` changed since the prefixes were built, they are rebuilt first with the current default prefix.
- Prefix color applies only when `color` is true, the level has a color in `LevelColors`, and `chalk.level > 0`. `info` and `none` have no color, so `info` and `log` use the plain prefix.

Logging does not remove items. It clears the live block, writes the line, then the block is redrawn on the next render tick, so items stay below the newest log line.

### `setPrefix(prefixStr?)`

```ts
setPrefix(prefixStr?: string): this
```

Sets the default prefix and rebuilds the per-level colored prefixes. `undefined` gives `"> "`. An empty string `""` is a valid prefix. The prefix text is colored per level with the colors in `LevelColors` when `color` is true and `chalk.level > 0`. Also records the current `chalk.level`.

### `prefix(x?)`

```ts
prefix(x?: string | false): this
```

Sets a one-shot prefix for the next log call only. `false` means an empty prefix for the next call. `undefined` cancels a pending one-shot prefix. `""` is an empty prefix. It overrides the colored default and is not colored.

### `addItem(options)`

```ts
addItem(options: ItemOptions): this
```

Adds a named item at the bottom of the item list. See `ItemOptions` for fields.

- If an item with the same `name` already exists, returns `this` with no change. The new options are ignored.
- Any currently running spinner on other items is restarted: its state resets to frame 0 and its line is rebuilt. This is so all spinners stay in step.
- `spinInterval` defaults to `100` (ms). `color` defaults to `"white"` when falsy. The display text is `options.display || String(name)`, colored with chalk using `color`.
- The initial line is `<display>: ` (empty message), with the spinner frame in front if the spinner starts.
- Spinners start only while visual mode is on at this moment (see `spinner` in `ItemOptions`).
- Does not draw immediately and does not schedule a render. The item shows on the next render, which is triggered by a log call, `updateItem` or `removeItem`.
- `color` must be a chalk color or modifier function name (such as `"red"`, `"green"`, `"bold"`) because the code calls `chalk[color](str)` when `color` is true. An unknown name throws a `TypeError` from `addItem`. When `color` is false in the logger, the name is not looked up and no error occurs.

### `hasItem(name)`

```ts
hasItem(name: string | symbol): boolean
```

`true` when an item with that name exists.

### `updateItem(name, data?)`

```ts
updateItem(name: string | symbol, data?: string | UpdateData): this
```

Does nothing (returns `this`) when no item has that name. Otherwise:

1. If `data` is not `undefined`, the item's text is replaced with `<display>: <msg>`:
   - String `data`: the string is the message, the display name is unchanged.
   - `UpdateData`: message is `data.msg || ""`. If `data.display` is truthy it replaces the display name for this and later updates (colored with the item's `color`). Without `display`, the item's current display text is kept.
   - The new text is saved to `logData` unless the item has `save === false` or `data._save === false`. Saved text is the whole `<display>: <msg>` line.
   - If `data._render === false`, returns now. The visible line is not refreshed and no dot is counted.
2. In visual mode:
   - With `data === undefined`, the spinner advances one frame. If the item has no running spinner, nothing happens and nothing is redrawn.
   - The item's line is rebuilt (spinner frame plus text) and a redraw is scheduled.
3. Not in visual mode: the item's stored line is set to the plain text (no spinner) and one update is counted for the dot output. In `simple` item type, one `.` is written every `updatesPerDot` updates. In `none` type nothing is written.

An update with `data` clears nothing in visual mode. Rendering is throttled to `renderFps`, so several updates in one interval produce one write.

### `removeItem(name)`

```ts
removeItem(name: string | symbol): this
```

No-op when the name is unknown. Otherwise: calls `clearItems()`, removes the item and its line, stops its spinner, and schedules a redraw of the remaining items. If no items remain, the redraw is skipped, so the live block disappears. The item's `logData` entries are kept.

### `setItemType(flag?)`

```ts
setItemType(flag?: string | false): this
```

Chooses how items are shown.

| flag | resulting type |
| --- | --- |
| `"normal"` | `normal`, but downgraded to `simple` when `output.isTTY()` is falsy at call time |
| `"simple"` | `simple` |
| `"none"`, `false`, `undefined`, `""`, any unknown string | `none` |

- Calls `output.isTTY()` directly. An `output` without an `isTTY` function throws a `TypeError` here only when `flag` is `"normal"`. (For other flags `isTTY` is not called.)
- When the type changes and visual mode was on, the live block is cleared and all spinners are stopped. When the change turns visual mode on, spinners are started for all items.
- Setting `simple` resets the dot counter to 0.
- Before any call to `setItemType`, the type is `normal`. On a non-TTY output visual mode is still off (the TTY check is also made on every render decision), but no dots are written either, because dots are only written when the type is exactly `simple`. Call `setItemType("simple")` or `setItemType("normal")` on a non-TTY to get dots.

### `clearItems()`

```ts
clearItems(): this
```

- Visual mode: cancels any pending redraw. If a frame has been drawn, calls `output.visual.clear()` and marks no frame drawn. If nothing was drawn, does nothing.
- Otherwise: if the type is `simple` and the dot count reached `maxDots`, writes `"\n"` and resets the count.

Items themselves are kept. A later update or log call redraws them.

### `freezeItems(showItems?)`

```ts
freezeItems(showItems?: boolean): this
```

Stops all spinners, cancels any pending redraw, clears a drawn frame, and ends a partial dot line (writes `"\n"` when the dot count is above 0). If `showItems` is truthy, writes the current item lines joined by `"\n"` plus a trailing `"\n"` with `output.write`. The lines are written as last stored, so a spinner frame may be included. (With no items, `showItems` writes a single `"\n"`.) Then saves the current item type and sets the type to `none`. Items are then not drawn, and updates only store text.

Calling `freezeItems` twice in a row saves `none` as the type to restore, so the following `unfreezeItems()` does not restore the display.

### `unfreezeItems()`

```ts
unfreezeItems(): this
```

If a non-`none` type was saved by `freezeItems`, restores it and restarts spinners for all items (if visual mode is on). Otherwise does nothing.

### `shutdown(showItems?)`

```ts
shutdown(showItems?: boolean): void
```

Calls `freezeItems(showItems)` and cancels any pending redraw. Use it before exit to leave a clean terminal. Timers are `unref`ed, so they never keep the process alive. The method returns nothing, but the logger can still be used and `unfreezeItems()` still works afterward.

## Rendering modes

Visual mode is evaluated on each decision as: item type is `normal`, and log level `<= Levels.info`, and the output reports a TTY. The TTY test is `output.isTTY()` coerced to boolean. An `output` where `isTTY` is not a function is treated as a TTY.

Visual mode (TTY):

- A redraw is scheduled with `setTimeout` at the render interval. The timer is `unref`ed. Only one is pending at a time, so writes are throttled to `renderFps`.
- On fire, if visual mode is still on and items exist, writes all item lines joined by `"\n"` (no trailing newline) with `output.visual.write`, which replaces the previous frame.
- Log lines go through `output.write`, after the frame is cleared with `output.visual.clear()`.
- Spinner timers: one `setInterval` per distinct `spinInterval`, unref'ed. Each tick advances every spinning item with that interval and schedules a redraw. A timer is cleared when no item with that interval is still spinning.

Simple mode (item type `simple`, or any item type on non-TTY after `setItemType("normal")`):

- Item updates write nothing but a `.` every `updatesPerDot` updates (only when `data` is not `_render: false`).
- Once the dot count reaches `maxDots`, a newline is written and the count resets (checked after each dot and when `clearItems` runs).
- Before a log line, or on `freezeItems`, a pending dot line is ended with `"\n"`.
- No spinner is shown and none runs.

None mode (`none`, or frozen): items are stored but never written. Log lines still print.

Color:

- `color: false` (or the `color` setter) turns off chalk use for prefixes and item display names. Item message text is never colored by the logger.
- With `color: true`, chalk decides the output. When chalk's level is 0 (for example not a TTY or `NO_COLOR`), escape codes are not emitted.
- Level prefixes are colored only when `chalk.level > 0`. Prefix colors are rebuilt lazily when `chalk.level` changes.

## `ItemOptions`

```ts
interface ItemOptions {
  name: string | symbol;
  color?: string;
  display?: string;
  spinner?: string | boolean | number;
  spinInterval?: number;
  save?: boolean;
  _display?: string;
  _msg?: string;
  _spinning?: SpinState;
  spinIx?: number;
}
```

| option | type | default | behavior |
| --- | --- | --- | --- |
| `name` | `string \| symbol` | required | Unique key. Passed to `updateItem`, `hasItem`, `removeItem`. Duplicates are ignored by `addItem`. |
| `color` | `string` | `"white"` | chalk function name used for the display text. |
| `display` | `string` | `String(name)` | Label shown before the colon. |
| `spinner` | `string \| boolean \| number` | none | `true` selects `VisualLogger.spinners[1]`. A number from `0` to `3` selects that entry. A non-empty string is used as the frame list, one frame per character. `false` and `0`-length strings mean no spinner. A number outside `0..3` is kept as is and misbehaves (frames render as `undefined`), so avoid it. |
| `spinInterval` | `number` | `100` | Milliseconds between frames. Items with the same interval share one timer. |
| `save` | `boolean` | saved | When exactly `false`, `updateItem` does not add this item's updates to `logData`. |
| `_display` | `string` | computed | Internal. Overwritten by `addItem`. |
| `_msg` | `string` | computed | Internal. Overwritten by `addItem`. |
| `_spinning` | `SpinState` | internal | Internal spinner state: `0` off, `1` started, `2` running. |
| `spinIx` | `number` | internal | Internal current frame index. |

Spinner notes:

- The spinner only starts if visual mode is on when the item is added (or when visual mode is turned on later by `setItemType` or `unfreezeItems`). Otherwise `spinner` is stored and unused.
- The `spinner` value on the stored options is replaced with the resolved frame string when the spinner is first started.
- A rendered line is `<frame> <display>: <msg>` while spinning, and `<display>: <msg>` without a spinner. Frame indexing is by JavaScript string index, so frames outside the BMP would split. The built-in sets are all BMP.
- Do not set the underscore fields or `spinIx` yourself.

## `UpdateData`

```ts
interface UpdateData {
  msg?: string;
  display?: string;
  _save?: boolean;
  _render?: boolean;
}
```

| field | type | default | behavior |
| --- | --- | --- | --- |
| `msg` | `string` | `""` | The message shown after `<display>: `. A missing or empty `msg` shows an empty message. |
| `display` | `string` | item display | Replaces the label (colored with the item `color`). Falsy keeps the current label. |
| `_save` | `boolean` | saved | When exactly `false`, this update is not added to `logData`. |
| `_render` | `boolean` | renders | When exactly `false`, the item text is changed but the display is not refreshed and no dot is counted. |

## `Levels`

```ts
const Levels: {
  readonly debug: 10; readonly verbose: 20; readonly info: 30; readonly warn: 40;
  readonly error: 50; readonly fyi: 60; readonly none: 100;
}
type LogLevel = keyof typeof Levels; // "debug" | "verbose" | "info" | "warn" | "error" | "fyi" | "none"
```

A log method prints when its level value is `>=` the logger's level. The logger's level is a private field initialized to `Levels.info` (30) and no code changes it. Effects:

- `debug` and `verbose` never print (they are still saved to `logData`).
- `info`, `log`, `warn`, `error`, `fyi` print.
- `none` (100) has no log method.
- The `<= info` clause of visual mode is always true.

## `LevelColors`

```ts
const LevelColors: Record<LogLevel, string>
```

`{ debug: "blue", verbose: "cyan", info: "", warn: "yellow", error: "red", fyi: "magenta", none: "" }`. The value is the chalk color name used for that level's prefix. An empty string means no color. The object is mutable, but prefixes are built from it in `setPrefix`, so changes apply only after the next `setPrefix` call, `color` setter call or `chalk.level` change.

## `LogItemTypes`

```ts
const LogItemTypes: { readonly normal: 9; readonly simple: 1; readonly none: 0 }
type LogItemType = keyof typeof LogItemTypes; // "normal" | "simple" | "none"
```

- `normal`: live redrawn items (TTY only).
- `simple`: progress dots, for non-TTY output.
- `none`: items are not displayed.

## `defaultOutput`

```ts
const defaultOutput: OutputInterface
```

The output used when `options.output` is not given. Targets `process.stdout`:

- `isTTY()` returns `process.stdout.isTTY`. This is `true` on a TTY and `undefined` otherwise (read each call).
- `write(x)` calls `process.stdout.write(x)` and returns its boolean.
- `visual.write` is `log-update`'s function (replaces the previous frame in place). `visual.clear` is `log-update`'s `clear`.

## `OutputInterface` and `VisualOutput`

```ts
interface VisualOutput {
  write: (text: string) => void;
  clear: () => void;
}

interface OutputInterface {
  isTTY: () => boolean | undefined;
  write: (text: string) => boolean;
  visual: VisualOutput;
}
```

Custom output contract:

- `write(text)` receives log lines (with a trailing `"\n"`), dot characters, newline chars, and the `freezeItems(true)` listing.
- `visual.write(text)` receives the multi-line item block without a trailing newline. It must replace the previous block.
- `visual.clear()` removes the last block. It is called only after a block has been drawn.
- `isTTY()` is called with the output as `this` for the visual-mode check, and as a method call by `setItemType("normal")`. The type requires it, but at runtime visual-mode checks tolerate a missing one (treated as a TTY).
- `visual` is dereferenced only when a frame is drawn or cleared.

## Example

```js
import VisualLogger from "visual-logger";

const logger = new VisualLogger();
logger.setItemType("normal"); // dots instead when stdout is not a TTY
logger.addItem({ name: "build", color: "green", spinner: true });
logger.updateItem("build", "compiling");
logger.info("started");
logger.updateItem("build", { msg: "done", display: "built" });
logger.shutdown(true); // freeze and print the final item lines
```

<!-- visual-exec v1.1.10: https://fynjs.pages.dev/ref/visual-exec.md -->

# visual-exec reference

`visual-exec` runs a shell command through `xsh.exec`, shows its output as a live spinner item on a `visual-logger`, and logs the captured output when the command ends. ESM only (`"type": "module"`).

## Imports

```js
import VisualExec, { getDefaultLogger, parsers } from "visual-exec";
import { VisualExec, jsonLinesParser, keyValueParser } from "visual-exec";
import type { VisualExecOptions, ExecOutput, VisualExecError } from "visual-exec";
```

The default export is `VisualExec`, the same class as the named export. There are no subpaths (only `visual-exec/package.json`).

Runtime exports: `VisualExec` (also `default`), `parsers`, `jsonLinesParser`, `keyValueParser`, `getDefaultLogger`.

Type-only exports: `VisualExecOptions`, `ExecOutput`, `ExecErrorContext`, `VisualExecError`, `OnOutputCallback`, `OnCompleteCallback`, `OutputFileOptions`, `ProgressExtractor`, `OutputMatcher`.

Not exported from the root: `sanitizeText`, `sanitizeForDisplay`, `sanitizeForOutput`, `SanitizeOptions`, `OutputStream` (`"stdout" | "stderr"`, used in `OnOutputCallback`), and the `ChildProcess` shape taken by `show`. The default export of `get-default-logger` is also not re-exported.

## `VisualExec`

```ts
class VisualExec {
  constructor(options: VisualExecOptions);
  execute<T = ExecOutput>(command?: string): Promise<T>;
  show<T = ExecOutput>(child: ChildProcess): Promise<T>;
  abort(signal?: string): void;          // default "SIGTERM"
  kill(signal?: string): void;           // alias of abort
  logResult(err: VisualExecError | null, output?: ExecOutput): void;
  checkForErrors(text: string): RegExpMatchArray | null;
  logFinalOutput(err: VisualExecError | null, output: ExecOutput): void;
}
```

One instance is meant for one run at a time. State such as the output file stream, item keys and the abort flag lives on the instance. `execute` may be called again after it settles. Calling it while a run is in progress overwrites that state.

### Constructor options

```ts
interface VisualExecOptions {
  command: string;
  cwd?: string;
  visualLogger?: VisualLogger;
  spinner?: ItemOptions["spinner"];
  displayTitle?: string;
  logLabel?: string;
  outputLabel?: string;
  outputLevel?: string;
  maxBuffer?: number;
  forceStderr?: boolean;
  checkStdoutError?: boolean | RegExp;
  timeout?: number;
  timeoutGrace?: number;
  onTimeout?: () => void;
  onOutput?: OnOutputCallback;
  onComplete?: OnCompleteCallback;
  outputFile?: string | NodeJS.WritableStream;
  outputFileOptions?: OutputFileOptions;
  signal?: AbortSignal;
  progress?: ProgressExtractor;
  onProgress?: (progress: { current?: number; total?: number; percent?: number }) => void;
  matchers?: OutputMatcher[];
}
```

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `command` | string | none (required) | Command run by `execute()` when it is called with no argument. Nothing validates it at construction. A non-string only changes the default title to `"Running user command"`. `execute()` then fails in `xsh.exec` (see Errors). |
| `cwd` | string | `process.cwd()` | Working directory. Also sets `PWD` in the child env. A falsy value falls back to `process.cwd()`. |
| `visualLogger` | `VisualLogger` | `getDefaultLogger()` | Logger that renders the spinner items and receives all log lines. |
| `spinner` | `ItemOptions["spinner"]` | `VisualLogger.spinners[1]` | Spinner style passed to the stdout item. |
| `displayTitle` | string | `"Running " + command` | Title shown on the stdout item. Also the default for `logLabel` and `outputLabel`. |
| `logLabel` | string | the title | Label in the `Done` and `Failed` lines. |
| `outputLabel` | string | the title | Label in the `No output` line and the `Start of output` and `End of output` markers. |
| `outputLevel` | string | `"verbose"` | Logger method name used for final output when nothing looks like an error. Must name a method on the logger. An unknown name throws `TypeError` from `logFinalOutput`. |
| `maxBuffer` | number | 10 MiB (10485760) | Passed to `child_process.exec` as `maxBuffer`, per stream. |
| `forceStderr` | boolean | `true` | When true, any non-empty captured stderr logs the final output at `error` level, even on exit code 0. |
| `checkStdoutError` | `boolean \| RegExp` | `true` | `true` uses `/error\|warn\|fatal\|unhandled\|reject\|exception\|failure\|fail\|failed/i`. A `RegExp` is used as given. `false` disables the check. A stdout match only raises the log level to `error`. It does not fail the run. |
| `timeout` | number (ms) | none | Starts when `show()` runs. A falsy value (`undefined`, `0`) disables it. See Timeout. |
| `timeoutGrace` | number (ms) | 5000 | Delay between SIGTERM and SIGKILL after a timeout. |
| `onTimeout` | `() => void` | none | Called when the timeout fires, before SIGTERM. Not called if `abort()` or the abort signal already ran. |
| `onOutput` | `OnOutputCallback` | none | Called for each raw stdout or stderr chunk. See Output capture. |
| `onComplete` | `OnCompleteCallback` | none | Called when the command ends. See Completion. |
| `outputFile` | `string \| WritableStream` | none | Where raw output is streamed. See Output file. |
| `outputFileOptions` | `OutputFileOptions` | `{ append: false, includeStderr: true, timestamps: false }` | Merged over the defaults. Only used with `outputFile`. |
| `signal` | `AbortSignal` | none | Aborts the run. See Abort. |
| `progress` | `ProgressExtractor` | none | Progress extraction config. Needs `onProgress` too. |
| `onProgress` | function | none | Called with extracted progress. Without it `progress` does nothing. |
| `matchers` | `OutputMatcher[]` | none | Per-line regex matchers. |

### Related types

```ts
type OnOutputCallback = (data: string, stream: "stdout" | "stderr") => void;
type OnCompleteCallback = (output: ExecOutput, exitCode: number) => unknown;

interface OutputFileOptions {
  append?: boolean;        // default false: open with flag "w". true: "a"
  includeStderr?: boolean; // default true
  timestamps?: boolean;    // default false
}

interface ProgressExtractor {
  pattern?: RegExp;
  extract?: (line: string) => { current?: number; total?: number; percent?: number } | null;
  format?: (p: { current?: number; total?: number; percent?: number }) => string;
}

interface OutputMatcher {
  pattern: RegExp;
  onMatch: (match: RegExpMatchArray) => void;
}

interface ExecOutput { stdout: string; stderr: string }

interface ExecErrorContext {
  exitCode: number;
  signal: string | null;
  cwd: string;
  command: string;
  duration: number;
  lastLines: string[];
  stdout: string;
  stderr: string;
}

interface VisualExecError extends Error {
  output?: ExecOutput;
  code?: number;
  exitCode?: number;
  signal?: string | null;
  cwd?: string;
  command?: string;
  duration?: number;
  lastLines?: string[];
  stdout?: string;
  stderr?: string;
  context?: ExecErrorContext;
}
```

`ProgressExtractor.format` is declared but never read by the code. Setting it has no effect.

### `execute(command?)`

```ts
execute<T = ExecOutput>(command?: string): Promise<T>
```

Runs the command and renders it. `command` overrides the constructor command for this call (`command || this._command`, so an empty string falls back).

How it spawns: it calls `xsh.exec({ silent: true, cwd, env, maxBuffer }, cmd)`. `xsh.exec` calls Node `child_process.exec`, so the command runs in the default system shell (`/bin/sh` on POSIX) as one string, not an argv array. `env` is `process.env` plus `PWD` set to the cwd. `silent: true` means xsh does not pipe the child to `process.stdout` or `process.stderr`. Output is only buffered, shown through the logger, and passed to callbacks. Output is decoded as utf8.

Resets `startTime` and the abort flag at the start of each call, then hands the child to `show()`.

Resolves with `{ stdout, stderr }` (full buffered strings), or with the value returned by `onComplete` if that value is not `undefined`. `T` is a type hint only. Nothing checks it.

Rejects when the shell command exits non-zero, is killed, exceeds `maxBuffer`, times out, or is aborted. See Errors.

### `show(child)`

```ts
show<T = ExecOutput>(child: {
  stdout: NodeJS.ReadableStream;
  stderr: NodeJS.ReadableStream;
  promise: Promise<ExecOutput>;
  child?: { kill(signal?: string): boolean; pid?: number };
}): Promise<T>
```

Attaches rendering, callbacks, timeout and abort handling to an already started child. `execute` is `xsh.exec` plus error enrichment plus `show`. `child.promise` must reject with an object that may carry `output`, `code` or `exitCode`. The enriched error context (`lastLines`, `cwd`, `command`, `duration`, `stdout`, `stderr` on the error) is added only by `execute`, not by `show`. `child.child` is what `abort()`, timeout and the abort signal kill. Without it, nothing is killed.

### `abort(signal?)` and `kill(signal?)`

Sets the abort flag, then calls `child.kill(signal)` (default `"SIGTERM"`) if the child has a truthy `pid`. `kill` calls `abort` with the same argument.

`abort()` alone does not reject by itself. The kill makes the child exit, so the run rejects through the normal failure path (see Errors), unless a timeout or signal rejection won first. After `abort()`, a pending timeout timer does nothing when it fires (the check returns early). Does nothing before `show()` has a child. The abort flag is reset by the next `execute()`.

### `logResult(err, output?)`

Public, called internally once per run when the child promise settles. It needs `show()` to have run (it dereferences the stored child). It:

1. Removes the stdout and stderr items from the logger.
2. Removes the `data` listeners it added to the child streams.
3. On error: `logger.error("Failed <logLabel> - <err.message>")` with `Failed` in red, and takes `output` from `err.output`. On success: `logger.info("Done <logLabel> <secs>secs exit code 0")` with seconds to 2 decimals.
4. Calls `logFinalOutput(err, output)`.

Seconds are measured from `startTime`, which is set in the constructor and again in `execute()`.

### `checkForErrors(text)`

Returns `null` when `checkStdoutError` is `false` or `text` is empty. Otherwise returns `text.match(regex)` using the resolved regex (default or user supplied). A global regex returns all matches without groups. Used by `logFinalOutput` on stdout only.

### `logFinalOutput(err, output)`

Logs the captured output after the run. Documented in the source as overridable. Assign an instance property to replace it (`ve.logFinalOutput = () => {}` suppresses output logging).

- Level is `"error"` if `err` is set, or `forceStderr` is true and `output.stderr` is non-empty, or `checkForErrors(output.stdout)` matches. Otherwise it is `outputLevel`.
- If `output` is missing or both streams are empty: logs `No output from <outputLabel>` (with `No output` in green) at that level and returns.
- Otherwise builds one multi-argument call: `>>>`, `Start of output from <outputLabel> ===`, then `\n<stdout>`, then `\n=== stderr ===\n<stderr>` if stderr is non-empty (header in red), then `\n<<<` and `End of output from <outputLabel> ---`.
- It calls `logger.prefix(false)` first, then the level method. `prefix(false)` sets the logger prefix to `""` and is never restored, so it persists on the logger (including a shared one) after the first call.
- Output text is sanitized by `sanitizeForOutput` (below) and every `ERR!` is colored red.

## Output capture and display

Each `show()` adds two items to the logger:

| Item | Color | `display` | Spinner |
| --- | --- | --- | --- |
| stdout | green | `=== <title>\nstdout` | the `spinner` option |
| stderr | red | `stderr` | default of the logger |

Items are keyed by fresh `Symbol`s, so concurrent instances on one logger do not collide. Both are removed in `logResult`.

Each `data` chunk from stdout or stderr does two things.

1. Updates its item's message with `logger.updateItem(key, { msg, _save: false, _render: false })`. The chunk is sanitized (`sanitizeForDisplay`) first. Lines are trimmed and empty lines dropped. Taking lines from the end, it keeps lines while the sum of their ANSI-stripped lengths stays under 100 characters. Kept lines are joined with an inverse blue `\n` marker. If no whole line fits, the last line is used, cut to its first 100 characters when it is over 120 characters (the cut text is ANSI-stripped). The kept text carries over to the next chunk as the item buffer, so a partial line is joined with the next chunk. `_render: false` means the update does not force a render. The logger's own render timer draws it. `_save: false` keeps the update out of the saved log data.
2. Runs the raw (unsanitized) data handler: `onOutput(data, stream)`, then the output file write, then progress and matchers on each non-empty line from `data.split("\n")`.

Raw means exactly what the child wrote. `onOutput` and the output file get the bytes untouched, per chunk, with no line buffering. A line split across two chunks is seen as two partial lines by progress and matchers.

Full output is not accumulated by `visual-exec`. The final `stdout` and `stderr` come from `child_process.exec`'s own buffers.

### Sanitizing

Child control sequences are removed before display and before the final log output, so a child that moves the cursor cannot erase lines. SGR colour sequences (`ESC[...m`) are kept. These are removed: other CSI sequences, OSC, DCS, PM, APC and SOS strings, charset and single-char escapes, 8-bit C1 controls, and C0 controls other than `\n`, `\t` and the `ESC` of kept SGR. Display profile: tabs become spaces, a lone `\r` is dropped. Output profile: tabs kept, `\r\n` and `\r` become `\n`, and an SGR reset is appended if any colour remained. Callbacks and the output file are not sanitized.

### Progress

Runs per non-empty line, only when both `progress` and `onProgress` are set.

- If `progress.extract` exists it is used and its return is passed on when truthy. `pattern` is ignored then.
- Else if `progress.pattern` matches and the match has `groups`, calls `onProgress({ current, total, percent })`. Each field is `parseInt(group, 10)` when that named group is non-empty, else `undefined`. A pattern with `groups` that matches but defines none of the three names still calls `onProgress` with all fields `undefined`. A pattern with no named groups never calls it.
- `format` is never used.

### Matchers

For each non-empty line and each matcher in order: `line.match(pattern)`, and if truthy, `onMatch(match)`. Same chunk caveats as above. Errors thrown by `onMatch`, `onProgress`, or `onOutput` are not caught by `visual-exec` (they throw inside the stream `data` listener).

### Output file

With `outputFile` as a string: the parent directory is created recursively if missing, the file is opened with flag `w` (or `a` if `append`), and the stream is closed when the run ends. `execute()` waits for the stream's `close` (or `error`) event before settling, so the file is complete when the promise resolves. A stream already destroyed or closed is not waited on.

With `outputFile` as a `WritableStream`: it is written to directly and never ended or closed by `visual-exec`. `execute()` does not wait for it to flush.

Written data is the raw chunk. With `timestamps: true` each chunk is prefixed with `[<ISO timestamp>] `, one prefix per chunk, not per line. With `includeStderr: false` stderr chunks are skipped.

## Timeout

When `timeout` is truthy, a timer starts in `show()`. On fire (unless `abort()` or the signal already ran):

1. `onTimeout()` is called.
2. If the child has a `pid`, it gets SIGTERM, then after `timeoutGrace` ms an unref'd timer sends SIGKILL if a `pid` is still recorded. The grace timer does not keep the process alive. `pid` is not cleared on exit, so SIGKILL is attempted even if the child already exited.
3. The run rejects immediately with a timeout error (below). It does not wait for the child to die.

The timer is cleared when the run settles.

## Abort

With `signal`, the run rejects with an abort error as soon as the signal aborts, and `abort()` is called (SIGTERM). If the signal is already aborted when `show()` runs, the same happens immediately. The `abort` listener is added to the signal and is not removed afterward.

## Completion

`onComplete(output, exitCode)` runs once when the child settles.

- Success: `logResult` runs first, then `onComplete(output, 0)`. If it returns a value other than `undefined`, that value is the resolved result of `execute()`. Otherwise the output object is. A throw from `onComplete` rejects the run. Failure logging is not triggered for that throw.
- Failure: `onComplete(output, exitCode)` runs before `logResult`, with `output` from `err.output` (or empty strings) and `exitCode` from `err.exitCode ?? err.code ?? 1`. Its return value is ignored. The original error is rethrown. A throw from `onComplete` replaces the error and skips `logResult`.
- Timeout and abort rejections happen through a race. `onComplete` still runs later when the killed child's own promise rejects, but its outcome no longer affects the already rejected promise.

## Errors

Process failures reject. One synchronous throw is possible: if the command is not a string (or array of strings), `xsh.exec` throws from `execute()` before anything is shown.

### Command failure

The rejection is the `Error` made by xsh, message `shell cmd '<cmd>' exit code <code>`, with these properties added or kept:

| Property | Value |
| --- | --- |
| `output` | `{ stdout, stderr }`, the full buffered output. From xsh. |
| `code` | From Node's exec error `code`. Normally the exit code. It may be a string such as `"ERR_CHILD_PROCESS_STDIO_MAXBUFFER"` or `null` when killed by a signal, despite the `number` type. From xsh. |
| `exitCode` | `err.code ?? 1`. `1` when `code` is `null` or `undefined`. |
| `signal` | `err.signal`, else `"SIGTERM"` if the child object has `killed === true`, else `null`. xsh does not copy Node's `signal`, so a child killed from outside is `null`. Any kill via `abort()` or timeout reports `"SIGTERM"`, even for SIGKILL. |
| `cwd` | The instance cwd. |
| `command` | The command actually run (the `execute(command)` override if given). |
| `duration` | Milliseconds since `execute()` started. |
| `lastLines` | Last 10 non-empty lines of stdout lines followed by stderr lines. |
| `stdout`, `stderr` | Last 50000 characters of each (sliced from the end). `output` keeps the full text. |
| `context` | An `ExecErrorContext` with the same values. Its `stdout` and `stderr` are not truncated. |

The error is logged with `Failed ...` and the final output before it is rethrown.

### `TimeoutError`

`name` is `"TimeoutError"`, a plain `Error` (no class is exported). Message: `Command timed out after <timeout>ms: <constructor command>`. `context` is `{ command, cwd, exitCode: -1, signal: "SIGTERM", duration: <timeout> }`. The error has none of the enrichment properties (`exitCode`, `stdout`, `stderr`, `lastLines`, `cwd`, `duration`). Only `context` is set, and it has no `stdout`, `stderr` or `lastLines`. `duration` is the timeout value, not measured time. Note `command` here is the constructor command even if `execute(command)` was used.

### `AbortError`

`name` is `"AbortError"`. Message: `Command aborted: <constructor command>`. `context` is `{ command, cwd, exitCode: -1, signal: "SIGTERM", duration }` where `duration` is time since `show()` started. Same missing properties as `TimeoutError`: only `context` is set.

### Which wins

`Promise.race` runs timeout and abort against the command promise. The first to settle sets the rejection. A normal exit or failure beating both gives the normal result or command failure error.

## `getDefaultLogger()`

```ts
function getDefaultLogger(): VisualLogger
```

Returns a module-level singleton `VisualLogger`, created on first call with default options. If `ci-info` reports a CI environment, on creation it logs `visual-exec: CI env detected` at info level and calls `setItemType("none")`, so spinner items are not drawn. This logger is used by `VisualExec` when `visualLogger` is not given. The instance is shared by every `VisualExec` in the process that uses the default. It never changes after creation.

## Parsers

Standalone helpers to use inside `onOutput`, `progress.extract` or `onMatch`. Nothing in the package calls them.

```ts
function jsonLinesParser(line: string): unknown | null
function keyValueParser(line: string): Record<string, string> | null
const parsers: { jsonLines: typeof jsonLinesParser; keyValue: typeof keyValueParser }
```

- `jsonLinesParser`: trims the line. Returns `null` for an empty line, a line starting with `//`, or invalid JSON. Otherwise returns `JSON.parse` of it. A line that is the JSON text `null` also returns `null`.
- `keyValueParser`: matches `^([^=:]+)[=:]\s*(.*)$`. Splits at the first `=` or `:`. Returns `{ [trimmedKey]: trimmedValue }`, or `null` if no match. A line with an empty key returns `null`.
- `parsers`: `{ jsonLines: jsonLinesParser, keyValue: keyValueParser }`.

## Example

```js
const ve = new VisualExec({
  command: "npm test",
  timeout: 60000,
  progress: { pattern: /(?<current>\d+)\/(?<total>\d+)/ },
  onProgress: p => console.log(p.current, p.total),
  outputFile: ".temp/test.log"
});
try {
  const { stdout } = await ve.execute();
} catch (err) {
  console.error(err.name, err.exitCode, err.lastLines);
}
```

<!-- xsh v1.1.8: https://fynjs.pages.dev/ref/xsh.md -->

# xsh reference

`xsh` is a small set of Node.js helpers for shell execution: `exec` (a wrapper over `child_process.exec`), environment variable readers, PATH editing, path scrubbing for CWD and `node_modules`, and a `pushd`/`popd` stack. It has no runtime dependencies. ESM only (`"type": "module"`).

## Imports

```js
import xsh from "xsh";
import { exec, env, envPath, mkCmd, pathCwd, pathCwdNm, pushd, popd } from "xsh";
import type { Xsh, ExecOutput, ExecError, ExecCallback, ExecOptions, ExecFragment, ExecArg, ExecResult, EnvContainer } from "xsh";
```

CommonJS on a Node version that supports `require(esm)`: `const xsh = require("xsh")` returns the `xsh` object itself (the module has a `"module.exports"` export), not a namespace.

Runtime exports: `default` (the `xsh` object), `exec`, `env`, `envPath`, `mkCmd`, `pathCwd`, `pathCwdNm`, `pushd`, `popd`, `"module.exports"` (same object as `default`).

Type-only exports: `Xsh`, `ExecOutput`, `ExecError`, `ExecCallback`, `ExecOptions`, `ExecFragment`, `ExecArg`, `ExecResult`, `EnvContainer`.

Not exported from the package root: `findEnvKey` and `envKey` (only reachable as members of `envPath`), `escapeRegExp`, `util`, and the individual functions `get`, `getAsBool`, `getAsInt`, `addToFront`, `addToEnd`, `add` (only reachable as members of `env` and `envPath`). There is no `$` export and no synchronous exec. There are no subpaths (only `xsh/package.json`).

## `xsh` (default export)

```ts
interface Xsh {
  exec: typeof exec;
  env: typeof env;
  envPath: typeof envPath;
  mkCmd: typeof mkCmd;
  pathCwd: typeof pathCwd;
  pathCwdNm: typeof pathCwdNm;
  pushd: typeof pushd;
  popd: typeof popd;
  /** Promise implementation used by exec */
  Promise: PromiseConstructor;
}
```

A plain object holding the same functions as the named exports, plus a `Promise` accessor property.

- Reading `xsh.Promise` returns the constructor `exec` currently uses. The initial value is the global `Promise`.
- Assigning `xsh.Promise = P` makes later non-callback `exec` calls build their promise with `new P(...)`. Assigning a falsy value (`null`, `undefined`) restores the global `Promise`.
- The setting is process wide and read at call time, so it affects every later `exec` call without a callback.
- The assigned value is not checked. A non-constructor fails when `exec` is next called without a callback.
- `Promise` is defined on the default object only. The named exports have no `Promise`.

## `exec(...args)`

```ts
function exec(...args: Array<ExecFragment | ExecOptions | boolean>): ExecResult;
function exec(...args: [...ExecArg[], ExecCallback]): ChildProcess;

type ExecFragment = string | string[];
type ExecArg = ExecFragment | ExecOptions | ExecCallback | boolean;
type ExecCallback = (err: ExecError | null, output: ExecOutput) => void;

interface ExecOutput { stdout: string; stderr: string }
interface ExecError extends Error { output: ExecOutput; code: number }
```

Runs a shell command with Node's `child_process.exec`. Execution is always asynchronous. There is no synchronous form. The two overloads are the callback form (returns the `ChildProcess`) and the thenable form (no callback, returns an `ExecResult`).

### Argument rules

Arguments are scanned in order. Each argument is one of:

| Argument | Meaning |
| --- | --- |
| string or array | A command fragment. |
| function | The callback. Must be the last argument. |
| `boolean` | Options shorthand for `{ silent: <boolean> }`. |
| non-null object | The options object. |
| anything else (`null`, `undefined`, number) | Throws `Error`. |

- The command is all fragments joined with a single `" "`. An array fragment is first joined with `" "`. No quoting or escaping is applied. The command string goes to the shell as is.
- With no options argument, options are `{ silent: false }`.
- The callback must be the last argument. Otherwise an `AssertionError` is thrown with message `xsh.exec: callback must be the last argument`.
- The options argument (object or boolean) must be the first, the last, or the second to last argument. Otherwise an `AssertionError` is thrown with message `xsh.exec: options must be the first, last, or second to last argument`. If several options arguments appear, the last one scanned wins.
- Zero fragments throws `Error("xsh.exec: expects at least one command fragment")`. This also happens for `exec({ cwd: "/tmp" })` or `exec(cb)`.
- An argument that is `null`, `undefined`, a number or another unsupported type throws `Error("xsh.exec: command fragment must be an array or string")`.
- These errors are thrown synchronously from `exec`, never as a rejected promise.
- Array elements are not type checked. `join` stringifies them.

### Options

`ExecOptions` is `{ silent?: boolean; env?: Record<string, string | undefined>; cwd?: string; [key: string]: unknown }`. Every key other than `silent`, `async` and `fatal` is passed to Node's `child_process.exec` as an option.

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `silent` | `boolean` | `false` | When false, the child's stdout and stderr are piped to `process.stdout` and `process.stderr` while the command runs. When true, nothing is echoed. Output is captured either way. Not passed to Node. |
| `cwd` | `string` | `process.cwd()` at call time | Working directory of the command. |
| `env` | `Record<string, string \| undefined>` | `process.env` | Environment of the command. Replaces the default entirely, it is not merged. |
| `maxBuffer` | `number` | `20 * 1024 * 1024` (20 MiB) | Max bytes buffered per stream. Node's own default is 1 MiB. |
| `encoding` | `string` | `"utf8"` | Output encoding. |
| `async`, `fatal` | any | none | Removed from the options and ignored. They are not passed to Node. |
| any other key | any | Node default | Passed to `child_process.exec` unchanged (for example `timeout`, `shell`, `killSignal`, `signal`, `uid`). |

Defaults are applied with `Object.assign`, so a user value overrides the default, including an explicit `undefined`. The type of `encoding` is not restricted by xsh. A non-`utf8` encoding changes what `stdout` and `stderr` are, because they are passed through, while the types still say `string`.

### Output capture

The `ExecOutput` object is `{ stdout, stderr }`, the strings (or buffers, see `encoding`) Node accumulated. Both streams are captured separately in full, up to `maxBuffer`. Output is captured whether or not `silent` is set. Output is delivered when the process closes. It is not streamed to the callback.

With `silent: false`, xsh pipes `child.stdout` and `child.stderr` to the parent streams.

### Result and errors

The callback form calls `cb(err, output)` once the command finishes.

- On exit code 0, `err` is `null`. Note `null`, not `undefined`.
- Otherwise `err` is a new `Error` with message `shell cmd '<cmd>' exit code <code>`, where `<cmd>` is the joined command string. It has two extra properties: `err.output` (the same `ExecOutput` passed to the callback) and `err.code`.
- `err.code` is taken from Node's error `code`. For a command that exits non-zero this is the numeric exit code. If Node supplies no code, it is `1`.
- Node's `code` is not always numeric. For a signal kill it is `null`, and for a `maxBuffer` overrun it is a string such as `"ERR_CHILD_PROCESS_STDIO_MAXBUFFER"`. xsh copies it as is (only `undefined` becomes `1`), so `err.code` can be a non-number despite the `number` type. `null` and strings still count as failure. The `exitCode === 0` check is strict.
- `output` is always passed, also on error, so failed commands keep their stdout and stderr.
- The original Node error (with `signal`, `killed`, `cmd`) is not attached. Only `output` and `code` are.
- A command that fails to spawn the shell is handled by the same path. There is no separate error type.

The callback form returns the `ChildProcess` from Node. The callback form does not use or require a Promise.

The thenable form returns an `ExecResult`:

```ts
interface ExecResult {
  then: <T = ExecOutput, R = never>(
    onFulfill?: ((output: ExecOutput) => T | PromiseLike<T>) | null,
    onReject?: ((err: ExecError) => R | PromiseLike<R>) | null
  ) => Promise<T | R>;
  catch: <R = never>(onReject?: ((err: ExecError) => R | PromiseLike<R>) | null) => Promise<ExecOutput | R>;
  promise: Promise<ExecOutput>;
  child: ChildProcess;
  stdout: ChildProcess["stdout"];
  stderr: ChildProcess["stderr"];
}
```

- `promise` resolves with `ExecOutput` on exit code 0 and rejects with the `ExecError` otherwise.
- `then(a, b)` and `catch(a)` forward to `promise.then` and `promise.catch`. The result object is a thenable, so `await exec(...)` yields the `ExecOutput`. There is no `finally` on the result object. Use `exec(...).promise.finally(...)`.
- `child`, `stdout` and `stderr` are the child process and its streams, set when `exec` returns. `stdout` and `stderr` are `child.stdout` and `child.stderr` captured at that moment.
- The promise is created with the constructor in `xsh.Promise`. If that setting were falsy at call time, `exec` throws an `AssertionError` (`xsh.exec: No Promise available - see doc on setting one`), but the setter prevents this by falling back to the global `Promise`.
- The command starts immediately when `exec` is called, not when `then` is called.
- A rejected `promise` with no handler attached causes the usual unhandled rejection. The result object does not attach a handler for you.

### Examples

```js
const { stdout } = await xsh.exec("echo", ["hello", "world"], true); // runs: echo hello world, silent

try {
  await xsh.exec("exit 3", { silent: true });
} catch (err) {
  err.code;          // 3
  err.output.stderr; // captured stderr
}

xsh.exec("pwd", { cwd: "/tmp" }, (err, { stdout }) => {
  if (err) throw err;
  console.log(stdout);
});
```

## `mkCmd(...args)`

```ts
function mkCmd(...args: Array<string | string[]>): string
```

Builds a command string. If the first argument is an array, only that array is used and it is joined with `" "`. Any further arguments are ignored. Otherwise all arguments are joined with `" "`.

- `mkCmd(["echo", "hello"])` and `mkCmd("echo", "hello")` both return `"echo hello"`.
- `mkCmd("a", ["b", "c"])` returns `"a b,c"`, because a later array is stringified with its default `toString`, not joined with a space. This differs from `exec`, which joins every array fragment with `" "`.
- `mkCmd()` returns `""`.
- No quoting or escaping.

## `env`

```ts
const env: {
  get(name: string, valWhenUndef?: string): string | undefined;
  getAsBool(name: string, valWhenUndef?: unknown): boolean;
  getAsInt(name: string, valWhenUndef?: unknown): number;
};
```

Readers for `process.env`. They read `process.env` on each call and never write to it.

### `env.get(name, valWhenUndef?)`

Returns `process.env[name]`. If it is `undefined`, returns `valWhenUndef`. An empty string is a defined value and is returned as is.

### `env.getAsBool(name, valWhenUndef?)`

- Variable defined: returns `true` when the lower cased value is exactly `"true"`, `"1"`, `"yes"` or `"on"`. Any other value, including `""`, `"0"` and `"false"`, is `false`. There is no trimming.
- Variable undefined: returns `valWhenUndef` if it is a `boolean`, else `false`.

### `env.getAsInt(name, valWhenUndef?)`

- Variable defined: converts with unary `+`, so it accepts anything `Number` accepts. `"0x10"` gives `16`, `"1.5"` gives `1.5` (not truncated), `""` gives `0`, and `" 7 "` gives `7`. If the result is not `NaN`, it is returned.
- Variable undefined or not parseable: returns `valWhenUndef` if it is a `number`, else `NaN`. A `NaN` fallback is itself a number, so it is returned as `NaN` either way.
- Despite the name, the result is not forced to an integer.

## `envPath`

```ts
type EnvContainer = Record<string, string | undefined>;

const envPath: {
  addToFront(p: string | null | undefined, env?: EnvContainer | string): string;
  addToEnd(p?: string | null, env?: EnvContainer | string): string;
  add(p?: string | null, env?: EnvContainer | string): string;
  envKey: string;
  findEnvKey(env: EnvContainer, key?: string): string | undefined;
};
```

Edits a PATH style variable, joined with the platform delimiter (`path.delimiter`: `:` or `;`).

Shared rules for `addToFront`, `addToEnd` and `add`:

- `env` selects the target. With `undefined` (or any falsy value), the target is `process.env` and it is mutated. With an object, that object is mutated. With a string, a temporary object `{ [envKey]: <string> }` is used, the string itself is not changed, and only the return value carries the result.
- The variable edited is the one named by `envKey`, not by looking up a key on the custom `env`. `envKey` is fixed when the module loads.
- All three write the result back to `env[envKey]` and return it, even when nothing changed. When the variable was missing or empty and `p` is empty, they set it to `""` and return `""`.
- If `p` is not a non-empty string (`null`, `undefined`, `""`), the PATH is not rewritten. The current value is returned as is, untrimmed and with its duplicates and empty segments kept.
- Otherwise the current value is trimmed, split on the delimiter, and empty segments are dropped (so the written PATH has no empty segments, including no implicit CWD entry).
- Comparison is exact string equality. There is no path normalization, no case folding on Windows and no trailing slash handling.
- No filesystem checks. `p` does not need to exist.

### `envPath.addToFront(p, env?)`

Removes every existing occurrence of `p`, then puts `p` first. Returns the new PATH string.

### `envPath.addToEnd(p, env?)`

Removes every existing occurrence of `p`, then puts `p` last. Returns the new PATH string.

### `envPath.add(p, env?)`

Appends `p` only if it is not already present. If present, the order is kept and the rewritten PATH has empty segments removed. If `p` is empty, the value is unchanged. Returns the PATH string. The README text "If it already exists, then it is moved" applies to `addToFront` and `addToEnd` only.

```js
envPath.addToFront("/opt/bin");                    // mutates process.env.PATH
envPath.addToEnd("/opt/bin", "/usr/bin:/bin");     // returns "/usr/bin:/bin:/opt/bin"
```

### `envPath.envKey`

`string`. The name of the PATH variable in `process.env`, computed once at module load. It starts as `"Path"` on Windows and `"PATH"` elsewhere. If `process.env` does not have that exact key, the first key that matches `path` case insensitively is used instead. If none is found, the starting name is kept.

### `envPath.findEnvKey(env, key?)`

Returns `key` if `key` is truthy and is an own property of `env`. Otherwise returns the first key of `env` that equals `"path"` case insensitively. If there is no such key, returns `key` as given, which may be `undefined`. It never throws for a normal object.

## `pathCwd`

```ts
const pathCwd: {
  remove(p: string, flags?: string, stripSlash?: boolean): string;
  replace(p: string, str?: string | null | false, flags?: string): string;
};
```

Scrubs the current directory out of a string, such as a stack trace or output line. `process.cwd()` is read on each call. Matching is a literal match (regex metacharacters in the path are escaped). `flags` are `RegExp` flags. Without `"g"`, only the first match is changed.

### `pathCwd.remove(p, flags?, stripSlash?)`

- With `stripSlash` truthy, first removes `<cwd><sep>` (CWD plus the platform separator).
- Then, if `p` still contains CWD, removes CWD.
- Returns `p` as is if CWD is not present.
- The result keeps any following separator unless `stripSlash` removed it. For example `"/a/b/f.js"` with cwd `/a/b` gives `"/f.js"`, and with `stripSlash` gives `"f.js"`.
- When `stripSlash` is used without `"g"`, only the first `<cwd><sep>` is removed.

### `pathCwd.replace(p, str?, flags?)`

Replaces CWD in `p` with `str`. If `str` is not a string (`undefined`, `null`, `false`), `"CWD"` is used. The replacement string is passed to `String.replace`, so `$` patterns in `str` are interpreted.

## `pathCwdNm`

```ts
const pathCwdNm: {
  remove(p: string, flags?: string): string;
  replace(p: string, str?: string | null | false, flags?: string): string;
};
```

Like `pathCwd`, but also handles `<cwd>/node_modules` (`path.resolve("node_modules")`). Matching is literal and uses the same `flags` rules.

### `pathCwdNm.remove(p, flags?)`

Removes `<cwd>/node_modules` from `p`, then calls `pathCwd.remove(p, flags)` (without `stripSlash`) on the result.

### `pathCwdNm.replace(p, str?, flags?)`

1. Replaces `<cwd>/node_modules` with `str`. If `str` is not a string, the replacement is `path.join("CWD", "~")` (`CWD/~`, or `CWD\~` on Windows).
2. Replaces the remaining CWD with `"CWD"` (via `pathCwd.replace(p, null, flags)`).
3. Replaces `path.normalize("/node_modules/")` with `path.normalize("/~/")`, using the same `flags`.

Without `"g"`, each step changes only its first match. A custom `str` applies only to step 1. Steps 2 and 3 always use their fixed replacements.

## `pushd` and `popd`

```ts
function pushd(dir: string): string
function popd(): string
```

A directory stack for `process.chdir`. The stack is module state, shared by the whole process.

- `pushd(dir)` pushes `process.cwd()` and calls `process.chdir(dir)`. It returns the new `process.cwd()`. If `chdir` throws (for example the directory does not exist), the error propagates, and the old directory has already been pushed, so the stack has an extra entry.
- `popd()` pops the most recent saved directory, calls `process.chdir` on it and returns it. If the stack is empty, throws an `AssertionError` with message `xsh.popd: directory stack is empty`.
- The stack is not reset by other `process.chdir` calls.
- `process.chdir` is not available in Node worker threads, where these calls throw.

## README mismatches

The README is context only. In these places the code is the authority.

- Callback `err` is `null` on success, not `undefined`. The README example `xsh.exec("echo hello", (r) => ...)` passes the first callback argument as the result, but it is `err`. The output is the second argument.
- The README documents only `Promise`, `mkCmd`, `exec`, `envPath` and `pushd`/`popd`. `env`, `pathCwd` and `pathCwdNm` are exported but not in the README.
- The README says Node `>= 22.18`. `package.json` `engines` says `^22.22.2 || ^24.15.0 || >=26.0.0`.

<!-- unwrap-npm-cmd v2.1.7: https://fynjs.pages.dev/ref/unwrap-npm-cmd.md -->

# unwrap-npm-cmd reference

`unwrap-npm-cmd` rewrites a command string so that, on Windows, an npm-generated `.cmd` batch shim is replaced by `node.exe` plus the real JS file the shim runs. That lets you spawn the command without a shell and without the batch wrapper. On non-Windows platforms `unwrapNpmCmd` returns its input unchanged. The package has one runtime dependency, `which`. The source is ESM (`"type": "module"`) and a CJS shim is provided.

## Imports

```js
import unwrapNpmCmd, { unwrapNpmCmd, resolveNpmCmd, quote, unquote, relative } from "unwrap-npm-cmd";
import type { UnwrapOptions, ResolveResult, ResolveOptions } from "unwrap-npm-cmd";
```

```js
const unwrapNpmCmd = require("unwrap-npm-cmd");
const { resolveNpmCmd, quote, unquote, relative } = require("unwrap-npm-cmd");
```

There are no subpaths (only `unwrap-npm-cmd/package.json`).

Runtime exports: `default` (same function as `unwrapNpmCmd`), `unwrapNpmCmd`, `resolveNpmCmd`, `quote`, `unquote`, `relative`.

Type-only exports: `UnwrapOptions`, `ResolveResult`, `ResolveOptions`.

CJS: `index.cjs` does `require("./dist/index.js")` and exports `Object.assign(m.default, m)`. So `require("unwrap-npm-cmd")` is the `unwrapNpmCmd` function itself, with `unwrapNpmCmd`, `default`, `resolveNpmCmd`, `quote`, `unquote` and `relative` copied onto it as properties. This mutates the ESM default function object. It relies on `require()` of an ES module, so it needs a Node version that supports that (the `engines` field is `^22.22.2 || ^24.15.0 || >=26.0.0`).

## `unwrapNpmCmd(cmd, options?)`

```ts
interface UnwrapOptions {
  path?: string;
  relative?: boolean;
  cwd?: string;
  jsOnly?: boolean;
}

function unwrapNpmCmd(
  cmd: string,
  options: UnwrapOptions = { path: process.env.PATH }
): string

export default unwrapNpmCmd;
```

Returns a command string. Never throws for a command that cannot be resolved; it returns `cmd` unchanged.

Algorithm:

1. If `process.platform !== "win32"`, return `cmd` unchanged. `options` is ignored.
2. Split `cmd` on the single space character `" "`. The first piece is the executable name. The rest are kept as is.
3. Resolve the executable name with `resolveNpmCmd(name, options)`. If it throws (for example `which` finds nothing), return `cmd` unchanged.
4. If `resolveNpmCmd` returned a string (the found path, quoted), replace the first piece with that string.
5. If it returned `{ jsFile }`:
   - With `options.relative` truthy, `jsFile = relative(jsFile, options.cwd)`.
   - With `options.jsOnly` truthy, the replacement is `quote(jsFile)`.
   - Otherwise the replacement is `quote(process.execPath) + " " + quote(jsFile)`.
6. Join the replacement and the remaining pieces with single spaces and return.

The returned string is `cmd` itself when the replacement equals the first piece. Remaining arguments are never parsed, quoted or changed.

### Options

| option | type | default | behavior |
| --- | --- | --- | --- |
| `path` | `string` | `process.env.PATH`, only when `options` is omitted entirely | Search path passed to `which` in place of `PATH`. If you pass an options object without `path`, `which` falls back to its own default (`process.env.PATH`). Also used as the cache key (see below). |
| `relative` | `boolean` | falsy | Convert the JS file path to a path relative to `cwd` using `relative()`. Applies only when a batch shim was unwrapped. |
| `cwd` | `string` | `process.cwd()` | Base directory for `relative`. Has no effect without `relative`. |
| `jsOnly` | `boolean` | falsy | Return only the quoted JS file path, without `node.exe`. Applies only when a batch shim was unwrapped. |

The whole options object is also passed to `which.sync`, so any `which` option present on it (such as `pathExt`) is honored. Only the four fields above are declared in `UnwrapOptions`.

### Which command strings are unwrapped

Only the first space-separated token is examined, so `"npm test"` looks up `npm` and keeps `test`. Outcomes for that token on Windows:

| the token resolves to | result |
| --- | --- |
| a `.cmd` file (extension compared case-insensitively) with a recognized node launch line | node.exe plus JS file, or the JS file alone with `jsOnly` |
| a `.cmd` file with no recognized launch line | the full path of the `.cmd`, quoted |
| any file without a `.cmd` extension (such as `.exe`) | the full path as found by `which`, quoted. `relative` and `jsOnly` are ignored for this case |
| nothing found, or any other error while resolving | `cmd` unchanged |

Because only a plain space splits the string, a command with a quoted executable path containing spaces, or with tab separators, is not tokenized properly. The first token is then looked up literally and normally fails, so `cmd` comes back unchanged.

### Caching

Results are cached in a module-level object keyed by `options.path || ""` and then by the executable name. A cache hit skips `which` and the batch file read. Details:

- The cache stores the result of `resolveNpmCmd` (string or `{ jsFile }`), before `relative` and `jsOnly` are applied. Different `relative`, `cwd` and `jsOnly` values therefore share an entry.
- Failures are cached too, as the bare name. A command that was not found keeps coming back unchanged for that `path` even if it is installed later.
- There is no invalidation and no exported way to clear the cache.
- `options.path` is the key, not `process.env.PATH`. A call with `options` omitted uses the `PATH` value at that call as the key.

### Examples

```js
unwrapNpmCmd("npm test");
// "C:\...\node.exe" "C:\...\node_modules\npm\bin\npm-cli.js" test
unwrapNpmCmd("npx mocha", { relative: true });
// "C:\...\node.exe" ".\...\npx-cli.js" mocha
unwrapNpmCmd("mocha test", { jsOnly: true });
// "C:\...\node_modules\mocha\bin\mocha" test
unwrapNpmCmd(`find "name" package.json`);
// "C:\WINDOWS\system32\find.EXE" "name" package.json
```

## `resolveNpmCmd(exe, options?)`

```ts
interface ResolveResult {
  jsFile: string;
}

interface ResolveOptions {
  path?: string;
}

function resolveNpmCmd(exe: string, options?: ResolveOptions): string | ResolveResult
```

The lower-level resolver used by `unwrapNpmCmd`. It does no platform check and no caching, and it does not catch errors.

Steps:

1. `which.sync(exe, options)` finds the executable. `options` is passed straight through, so `path` and other `which` options apply. If `which` finds nothing it throws, and `resolveNpmCmd` lets that propagate.
2. If the found path does not end in `.cmd` (case-insensitive), return `quote(foundPath)`. This is a string, not an object.
3. Otherwise read the file and split it on `"\n"`, trimming each line (so `\r` is removed).
4. Pick the line that holds the node launch, by the lower-cased base name of the `.cmd` file:
   - `npm.cmd`: the first line starting with `SET "NPM_CLI_JS=`. The text `NPM_CLI_JS=` is removed from that line.
   - `npx.cmd`: the first line starting with `SET "NPX_CLI_JS=`. The text `NPX_CLI_JS=` is removed.
   - any other `.cmd`: the first line starting with `"%~dp0\node.exe"`, else the first line starting with `"%_prog%"`.
5. If no line matched, return `quote(foundPath)` (the `.cmd` path itself).
6. Take the second space-separated token of the chosen line, with empty tokens ignored. For npm/npx that is the quoted JS path left after removing `SET`. For other shims it is the token after `"%~dp0\node.exe"` or `"%_prog%"`, such as `"%dp0%\node_modules\mocha\bin\mocha"`.
7. In that token, replace the first `%~dp0` and the first `%dp0%` with the directory of the `.cmd` file. Each replacement changes only the first occurrence.
8. Normalize with `Path.normalize`, strip surrounding quotes with `unquote`, then wrap with `quote`, and return `{ jsFile }`. `jsFile` is therefore quoted and normalized. (A code branch for Node older than 18 skips the `unquote` and `quote` steps, but `engines` excludes those versions.)

Failure behavior: throws if `which` finds nothing, if reading the `.cmd` file fails, or if the chosen line has no second token (the `.replace` call runs on `undefined` and throws a `TypeError`). A missing launch line is not a failure; it returns the quoted `.cmd` path.

Limits: the line match is a prefix test on the trimmed line. The second token is found by splitting on spaces, so a JS path that contains a space inside the batch file is cut at the space. Only the first launch line is used. On non-Windows platforms the function still runs. It finds executables with `which` and returns the quoted path, since non-Windows commands rarely have a `.cmd` extension.

## `quote(x)`

```ts
const quote: (x: string) => string
```

Returns `x` unchanged if it already starts with `"`. Otherwise returns `"` + `x` + `"`. Only the start is checked, so `"abc` is returned as is. No escaping is done. An empty string becomes `""`.

## `unquote(x)`

```ts
const unquote: (x: string) => string
```

Trims whitespace, then removes every run of `'` and `"` characters from the start and the end. Single and double quotes are both removed, and mixed runs such as `'"x"'` are fully removed. Inner quotes are kept.

## `relative(x, cwd?)`

```ts
const relative: (x: string, cwd?: string) => string
```

Returns the path of `unquote(x)` relative to `cwd` (default `process.cwd()`), using `path.relative` of the running platform. The result is not quoted. If the relative path does not begin with `.`, the prefix `.` + `path.sep` is added (`.\` on Windows, `./` elsewhere). The check is only on the first character, so a name such as `.bin\x` is left without an extra prefix. When `path.relative` returns an absolute path (different drive on Windows), the prefix is still added, giving a path like `.\D:\x`.

## `UnwrapOptions`, `ResolveResult`, `ResolveOptions`

Type-only exports. Their definitions are shown under `unwrapNpmCmd` and `resolveNpmCmd`. `ResolveOptions` declares only `path`.

## Notes on the README

The README option table matches the code. The README does not mention that the cache ignores `relative`, `cwd` and `jsOnly`, that failures are cached, or the exported `resolveNpmCmd`, `quote`, `unquote` and `relative` helpers.

<!-- aveazul v2.1.8: https://fynjs.pages.dev/ref/aveazul.md -->

# aveazul reference

`aveazul` is a Bluebird-style drop-in layer on top of native `Promise`. `AveAzul<T>` is a class that `extends Promise<T>`, so `then`, `catch`, `finally`, `race`, `allSettled` and the rest are the native implementations, and `await` and interop work unchanged. Runtime dependencies: `xaa` (map, filter, delay, timeout, defer, wrap) and `@jchip/error` (`AggregateError`). The package is ESM (`"type": "module"`) with a CJS shim.

## Imports

```js
// ESM
import AveAzul from "aveazul";
import { AveAzul, Disposer, OperationalError, isOperationalError, isProgrammerError, promisify, promisifyAll } from "aveazul";

// CJS
const AveAzul = require("aveazul");
```

ESM runtime exports: `default` (the `AveAzul` class), `AveAzul`, `Disposer`, `OperationalError`, `isOperationalError`, `isProgrammerError`, `promisify`, `promisifyAll`.

Type-only exports: `MapOptions`, `AsCallbackOptions`, `FromCallbackOptions`, `Deferred`, `AveAzulClass`, `AveAzulInstance`, `PromisifyOptions`, `PromisifyAllOptions`.

CJS entry (`cjs-entry.cjs`, `main` and the `require` condition): `module.exports = Object.assign(m.default, m)` where `m` is the ESM module. `require("aveazul")` is the `AveAzul` class itself, with the named exports above copied on as static properties, plus `AveAzul` (the class), `default` (the class) and `__esModule`. There are no subpaths other than `aveazul/package.json`.

CJS caveat: `Object.assign` overwrites the class statics `promisify` and `promisifyAll` with the standalone functions of the same name. In CJS, and in an ESM process that has also loaded the CJS entry (both share one class object), `AveAzul.promisify` and `AveAzul.promisifyAll` use the global `Promise` instead of `AveAzul`. Results are then native promises without the Bluebird methods. In pure ESM the static versions return `AveAzul`. See `promisify` and `promisifyAll`.

Not exported: the `using` function and `addStaticAny` are internal, and so are the not-implemented helper functions. `Deferred` is a type only.

Behaviors shared by most methods:

- Static `resolve`, `reject`, `all`, `race`, `allSettled` and instance `then`, `catch`, `finally` are native. They construct through `this`, so they return `AveAzul` instances.
- The internal promise check (`isPromise`) is true for `instanceof Promise`, or an object with both `then` and `catch` functions. A thenable with only `then` is treated as a plain value by `each`, `reduce`, `spread`, `some`, `any` and `using`.
- Methods that take a collection are typed `Iterable`, but several only work for arrays at runtime. Details per method.

## `AveAzul` class

```ts
class AveAzul<T> extends Promise<T> {
  constructor(executor: (resolve: (v: T | PromiseLike<T>) => void, reject: (r?: unknown) => void) => void);
}
```

Same as `new Promise`. Instances are `instanceof Promise`.

## Static: native and re-declared

```ts
static resolve<U>(value: U | PromiseLike<U>): AveAzul<U>; static resolve(): AveAzul<void>;
static reject<U = never>(reason?: unknown): AveAzul<U>;
static all<U>(values: Iterable<U | PromiseLike<U>>): AveAzul<Awaited<U>[]>;
```

Inherited from `Promise`. They are re-declared with `declare static` (nothing emitted) so the return type is `AveAzul`. `race`, `allSettled`, `withResolvers` and any other native static in your Node are inherited the same way, with native semantics. `Promise.all` rejects with the first rejection.

## `AveAzul.delay(ms, value?)`

```ts
static delay<U>(ms: number, value?: U): AveAzul<U>
```

Resolves with `value` after `ms` using `xaa.delay`. With `value === undefined` it resolves with `undefined`. A function `value` is handled by xaa as a producer: `delay(1, () => 5)` resolves with `5` (observed).

## `AveAzul.map(items, fn, options?)`

```ts
static map<T, U>(
  value: Iterable<T | PromiseLike<T>>,
  fn: (item: T, index: number, length: number) => U | PromiseLike<U>,
  options?: MapOptions
): AveAzul<U[]>
interface MapOptions { concurrency?: number }
```

Same as `AveAzul.resolve(value).map(fn, options)`, so `value` may itself be a promise of an array.

| option | type | default | behavior |
|---|---|---|---|
| `concurrency` | `number` | `50` | `> 1` runs up to that many `fn` calls at once through xaa. Any other value (`0`, `1`, negative, or an `options` object without `concurrency`) runs one at a time in order. Bluebird's default is unbounded. |

The default applies only when `options` is `undefined`. Passing `{}` is serial.

Rules:

- The input must be an actual array at runtime. Anything else (`Set`, generator, number, `null`) rejects with an `AssertionError` from xaa: `xaa.map expecting an array but got object`.
- Promise items are awaited before `fn` is called. A rejected item rejects the result.
- Result order matches input order.
- The first error rejects the result and gets a `partial` property (array of results so far, possibly with holes). In-flight calls are not cancelled.
- The third `fn` argument is NOT `length` despite the type. It is xaa's context object `{ array, failed, assertNoFailure }`.
- `fn` is called with no `this`.

## `AveAzul.mapSeries(items, fn)`

```ts
static mapSeries<T, U>(value: Iterable<T | PromiseLike<T>>, fn: (item: T, index: number, length: number) => U | PromiseLike<U>): AveAzul<U[]>
```

`AveAzul.map(value, fn, { concurrency: 1 })`. Same array-only rule and third-argument caveat as `map`.

## `AveAzul.try(fn)`

```ts
static try<T>(fn: () => T | PromiseLike<T>): AveAzul<T>
```

Calls `fn` through `xaa.wrap`. A sync throw or rejected return becomes a rejection. A non-function `fn` rejects with `TypeError: func is not a function` (observed), it does not throw synchronously. No extra arguments or `this` are accepted.

## `AveAzul.props(obj)`

```ts
static props<T extends object>(obj: T): AveAzul<{ [K in keyof T]: Awaited<T[K]> }>
```

Resolves every own enumerable string-keyed value (`Object.keys`) with `AveAzul.all` and returns a new plain object with the same keys. A `Map` is not supported: it yields `{}`. `null` or `undefined` throws a `TypeError` synchronously (from `Object.keys`), not a rejection.

## `AveAzul.defer()`

```ts
static defer<T>(): Deferred<T>
interface Deferred<T> { promise: AveAzul<T>; resolve(value: T | PromiseLike<T>): void; reject(reason?: unknown): void }
```

Returns an `xaa` `Defer` built with `AveAzul` as the promise class. At runtime it also has a `done(err, value)` Node-callback property that is not in the type.

## `AveAzul.each(items, fn)`

```ts
static each<T>(items: Iterable<T | PromiseLike<T>>, fn: (item: T, index: number, length: number) => unknown): AveAzul<T[]>
```

`AveAzul.resolve(items).each(fn)`. See instance `each`.

## `AveAzul.reduce(array, fn, initialValue?)`

```ts
static reduce<T, U>(array: Iterable<T | PromiseLike<T>>, fn: (value: U, item: T, index: number, length: number) => U | PromiseLike<U>, initialValue?: U): AveAzul<U>
```

With 3 or more arguments `initialValue` is used even if it is `undefined`. With 2 arguments see instance `reduce`.

## `AveAzul.some(promises, count)`

```ts
static some<T>(promises: Iterable<T | PromiseLike<T>>, count: number): AveAzul<T[]>
```

`AveAzul.resolve(promises).some(count)`. See instance `some`.

## `AveAzul.any(promises)`

```ts
static any<T>(args: Iterable<T | PromiseLike<T>>): AveAzul<T>
```

Replaces native `Promise.any` (overwritten at module load).

- A non-iterable returns a rejected promise with `TypeError: expecting an array or an iterable object but got <x>`. `Set` input works.
- Empty input rejects with `RangeError: Input array must contain at least 1 items but contains only 0 items`.
- Resolves with the first fulfilled value. Non-promise items count as already fulfilled.
- If all reject, rejects with `new AggregateError(errors)` from `@jchip/error`. It has no message (empty string observed). Errors are in rejection order.

## `AveAzul.join(...args)`

```ts
static join(...args: any[]): AveAzul<any>
```

If there is more than one argument and the last is a function, awaits the earlier arguments with `AveAzul.all` and resolves with `handler(...results)`. Otherwise it resolves with `AveAzul.all(args)`. So `join(fn)` with a single function resolves to `[fn]` and `join()` resolves to `[]`.

## `AveAzul.method(fn)`

```ts
static method<T, Args extends any[]>(fn: (...args: Args) => T | PromiseLike<T>): (...args: Args) => AveAzul<T>
```

Returns a function that calls `fn` with the caller's `this` and arguments, giving an `AveAzul`. Sync throws become rejections. A non-function `fn` fails only when the wrapper is called, as a rejection.

## `AveAzul.promisify(fn, options?)`

```ts
static promisify<T = unknown>(fn: (...args: any[]) => void, options?: PromisifyOptions): (...args: any[]) => AveAzul<T>
```

Calls the standalone `promisify` with `Promise` forced to `AveAzul` (overrides `options.Promise`). Options and rules are in the standalone `promisify` section. In the CJS entry this static is replaced by the standalone function (see Imports).

## `AveAzul.promisifyAll(target, options?)`

```ts
static promisifyAll<T extends object>(target: T, options?: PromisifyAllOptions): T
```

Calls the standalone `promisifyAll` with `Promise` forced to `AveAzul`. Same CJS caveat as `promisify`.

## `AveAzul.using(...)`

```ts
static using<R>(resources: any, ...args: any[]): AveAzul<R>
```

The last argument is the handler. Two call forms:

- Variadic: `using(r1, r2, ..., handler)`, handler is called as `handler(...resolvedResources)`.
- Array: `using([r1, r2], handler)`, handler is called as `handler(resolvedArray)`. An array plus more than one trailing argument throws `TypeError: only two arguments are allowed when passing an array of resources`.

Each resource may be a `Disposer` (from `.disposer()`), a promise of a value or of a `Disposer`, or a plain value (no cleanup). Rules:

- No handler argument throws synchronously `TypeError: resrouces and handler function required` (the typo is in the source). A non-function handler throws synchronously `TypeError: handler must be a function`.
- Resources are acquired through `AveAzul.map` (default concurrency 50), so acquisition is concurrent.
- If any acquisition rejects, all successfully acquired resources are disposed, then the first acquisition error rejects the result. The handler is not called.
- After the handler settles (resolve, reject, or sync throw), resources are disposed in input order, one at a time, through `AveAzul.each`. Bluebird disposes in reverse order.
- A dispose function that throws does not reject the result. The errors are collected and thrown as `AggregateError("cleanup resources failed")` on `setTimeout(0)` via `___throwUncaughtError`, which crashes the process unless an `uncaughtException` handler exists.
- A rejected handler result is rethrown after disposal.

## `AveAzul.fromCallback(fn, options?)` and `AveAzul.fromNode`

```ts
static fromCallback<T>(fn: (callback: (err: Error | null, result?: T) => void) => void, options?: FromCallbackOptions): AveAzul<T>
static fromNode: typeof AveAzul.fromCallback // same function
interface FromCallbackOptions { multiArgs?: boolean }
```

Calls `fn` with a Node callback. A truthy `err` rejects. Otherwise it resolves with the first value, or with the array of all values when `options.multiArgs` is truthy. A sync throw from `fn` rejects.

## `AveAzul.isOperationalError`, `AveAzul.isProgrammerError`, `AveAzul.OperationalError`, `AveAzul.Disposer`

Static aliases of the standalone exports of the same names.

## `AveAzul.___throwUncaughtError(error)`

```ts
static ___throwUncaughtError(error: unknown): void
```

Internal. Schedules `setTimeout(() => { throw err }, 0)`. A non-`Error` is wrapped with `new Error(String(error))`. Used by `asCallback` and `using` for errors that must not be swallowed.

## `AveAzul.__notImplementedInstance`, `AveAzul.__notImplementedStatic`

```ts
static __notImplementedInstance?: string[]
static __notImplementedStatic?: string[]
```

Set at load by `setupNotImplemented`. They list the names from a fixed Bluebird list that the class lacked and that were replaced by throwing stubs. Observed values:

- Instance: `bind`, `isFulfilled`, `isRejected`, `isPending`, `isCancelled`, `value`, `reason`, `cancel`, `reflect`, `suppressUnhandledRejections`, `done`.
- Static: `filter`, `coroutine`, `coroutine.addYieldHandler`, `getNewLibraryCopy`, `noConflict`, `setScheduler`.

Calling a stub logs `console.error("<instance|static> <name> Not implemented in aveazul")` and throws an `Error` with the same text. `coroutine.addYieldHandler` is a single property literally named with a dot, not a nested member.

## Instance methods

### `then`, `catch`, `finally`

Native, typed to return `AveAzul`. `catch` takes only a handler. Bluebird's filtered catch `.catch(ErrorClass, handler)` is NOT supported: the class is used as the handler and called as a function. For example `.catch(TypeError, h)` resolves with a new `TypeError` object and never calls `h`.

### `tap(fn)`

```ts
tap(fn: (value: T) => unknown): AveAzul<T>
```

Awaits `fn(value)`, ignores its result and resolves with the original value. A throw or rejection from `fn` rejects the chain.

### `tapCatch(fn)`

```ts
tapCatch(fn: (err: Error) => unknown): AveAzul<T>
```

On rejection awaits `fn(err)` then rethrows the original error. A throw from `fn` replaces it. No filter overloads.

### `return(value)`

```ts
return<U>(value: U): AveAzul<U>
```

`.then(() => value)`.

### `throw(reason)`

```ts
throw(reason: unknown): AveAzul<never>
```

`.then(() => { throw reason })`. Skipped when this promise rejects.

### `catchReturn(value)`, `catchThrow(reason)`

```ts
catchReturn<U>(value: U): AveAzul<T | U>
catchThrow(reason: unknown): AveAzul<T>
```

`.catch(() => value)` and `.catch(() => { throw reason })`. No filter overloads.

### `error(handler)`

```ts
error(handler: (err: Error) => unknown): AveAzul<T>
```

Catches only operational errors (`isOperationalError(err)`: an `OperationalError` instance or an object with `isOperational === true`) and passes them to `handler`. Other errors are rethrown. `AGENTS.md` lists `error` as not implemented, but the code implements it.

### `get(key)`

```ts
get<K extends keyof T>(key: K): AveAzul<T[K]>
```

`.then(v => v[key])`. A `null` or `undefined` value rejects with a `TypeError`. Negative indexes are not special.

### `call(methodName, ...args)`

```ts
call(methodName: string, ...args: any[]): AveAzul<any>
```

Calls `value[methodName](...args)` with `this` set to the value. A missing or non-function member rejects with `TypeError: <name> is not a function`.

### `spread(fn)`

```ts
spread<U>(fn: (...args: any[]) => U | PromiseLike<U>): AveAzul<U>
```

For an array value: awaits promise elements one by one, replacing them in the original array in place, then calls `fn(...array)`. A non-array value calls `fn(value)`. A non-function `fn` returns a rejected promise with `TypeError: expecting a function but got <fn>` (no sync throw).

### `map(fn, options?)` and `mapSeries(fn)`

```ts
map<U>(fn: (item: any, index: number, length: number) => U | PromiseLike<U>, options?: MapOptions): AveAzul<U[]>
mapSeries<U>(fn: (item: any, index: number, length: number) => U | PromiseLike<U>): AveAzul<U[]>
```

The resolved value goes to `xaa.map` with `options`, default `{ concurrency: 50 }`. See `AveAzul.map` for the option table and rules. `mapSeries` is `map(fn, { concurrency: 1 })`. A non-array resolved value rejects with an `AssertionError`.

### `filter(fn)`

```ts
filter(fn: (item: any, index: number, length: number) => any): AveAzul<any[]>
```

Uses `xaa.filter`. Strictly sequential, no options (Bluebird has `concurrency`). It calls `fn(item, index)` only, so the third argument is `undefined`, not `length`. Items are not unwrapped first: `fn` receives the raw element (a promise element is passed as a promise) and the kept value is the raw element. Keeps elements whose awaited result is truthy. A value without `length` (such as a `Set`) resolves to `[]`. The static `AveAzul.filter` is a throwing stub, so use `AveAzul.resolve(arr).filter(fn)`.

### `each(fn)`

```ts
each(fn: (item: any, index: number, length: number) => unknown): AveAzul<any[]>
```

Sequential. For each element: awaits it if it is a promise, then awaits `fn(item, index, arr.length)`. Resolves with a new array of the awaited items. The `fn` results are ignored. Stops at the first rejection. A value without `length` (such as a `Set`) resolves to `[]`.

### `reduce(fn, initialValue?)`

```ts
reduce<U>(fn: (value: U, item: any, index: number, length: number) => U | PromiseLike<U>, initialValue?: U): AveAzul<U>
```

Sequential. Initial value detection is `arguments.length > 1`, so an explicit `undefined` counts as supplied. Without one, the first element is the accumulator and iteration starts at index 1. So an empty array resolves with `undefined` and a one-element array resolves with that element, with `fn` never called. A promise accumulator or element is awaited. A value without `length` (such as a `Set`) resolves to the initial value, or `undefined`.

### `props()`

```ts
props(): AveAzul<any>
```

Same as `AveAzul.props` applied to the resolved value.

### `all()`, `any()`, `some(count)`

```ts
all(): AveAzul<any[]>
any(): AveAzul<any>
some(count: number): AveAzul<any[]>
```

Apply `AveAzul.all`, `AveAzul.any` or the `some` algorithm to the resolved value, which must be an array or iterable (else rejects with `TypeError: expecting an array or an iterable object but got <x>`).

`some(count)` rules:

- `count` must satisfy `(count | 0) === count && count >= 0`, else returns a rejected promise with `TypeError: expecting a non-negative integer`.
- `count === 0` resolves with `[]` without waiting for this promise.
- `count` greater than the input length rejects with `RangeError: Input array must contain at least <count> items but contains only <len> items`.
- Resolves with exactly `count` values in fulfillment order. Non-promise items count as already fulfilled.
- Rejects with `AggregateError` (message `aggregate error`) once fewer than `count` items can still fulfil. Errors are in rejection order.

### `delay(ms)`

```ts
delay(ms: number): AveAzul<T>
```

After fulfillment waits `ms`, then passes the value through. Rejections pass through without the delay.

### `timeout(ms, message?)`

```ts
timeout(ms: number, message?: string): AveAzul<T>   // message defaults to "operation timed out"
```

Races this promise against a timer using `xaa.timeout(ms, message, ...).run(this)`. On timeout it rejects with `OperationalError(message)` (name `OperationalError`, `isOperational === true`). There is no `TimeoutError` class, and `message` is a string only. The timer is cleared when the promise settles. The underlying work is not cancelled.

### `disposer(fn)`

```ts
disposer(fn: (resource: T) => void | Promise<void>): Disposer<T>
```

Returns `new Disposer(fn, this)`, not a promise. Throws synchronously `TypeError: Expected a function` for a non-function `fn`. Use with `AveAzul.using`.

### `asCallback(cb, options?)` and `nodeify(cb, options?)`

```ts
asCallback(cb: ((err: Error | null, value?: T) => void) | ((err: Error | null, ...values: any[]) => void) | undefined | null, options?: AsCallbackOptions): AveAzul<T>
nodeify(cb, options?): AveAzul<T> // calls asCallback
interface AsCallbackOptions { spread?: boolean }
```

| option | type | default | behavior |
|---|---|---|---|
| `spread` | `boolean` | `false` | Only `=== true` counts. An array value is passed as separate arguments `cb(null, ...value)`. A non-array value is passed as `cb(null, value)`. |

- A non-function `cb` is ignored and the same promise is returned.
- On success calls `cb(null, value)`. On rejection calls `cb(reason)`.
- An exception thrown by `cb` is rethrown asynchronously through `___throwUncaughtError`.
- Returns `this`, not a new promise.

## Standalone exports

### `AveAzul` and `default`

The class above. The named and default exports are the same object.

### `promisify(fn, options?)`

```ts
function promisify<T = unknown>(fn: NodeStyleFunction, options?: PromisifyOptions): (...args: unknown[]) => Promise<T>
interface PromisifyOptions { Promise?: PromiseConstructor; multiArgs?: boolean; copyProps?: boolean; suffix?: string; context?: unknown }
```

| option | type | default | behavior |
|---|---|---|---|
| `Promise` | `PromiseConstructor` | `globalThis.Promise` | Class that builds the result. The standalone default returns a native promise, not `AveAzul`. Use `AveAzul.promisify` or pass `{ Promise: AveAzul }`. |
| `multiArgs` | `boolean` | `false` | Truthy resolves with the array of all callback values after `err`. Otherwise only the first value. |
| `copyProps` | `boolean` | `true` | Copies own properties of `fn` onto the wrapper, except `arity`, `length`, `name`, `arguments`, `caller`, `callee`, `prototype`, `__isPromisified__`. |
| `suffix` | `string` | `""` | Appended to the wrapper's `name` only (`fn.name + suffix`). |
| `context` | `unknown` | `undefined` | `this` for `fn` when truthy. Otherwise the wrapper's own `this`. |

Rules:

- A non-function `fn` throws synchronously `TypeError: expecting a function but got [object X]`.
- A function already promisified (`__isPromisified__ === true`) is returned unchanged and the options are ignored.
- The wrapper appends a Node callback as the last argument. A truthy `err` rejects, otherwise it resolves. A sync throw from `fn` rejects, because `fn` runs inside the promise executor.
- The wrapper's `length` is `fn.length` (not reduced by one). Its `name` is `fn.name + suffix`.
- The wrapper is marked with a non-enumerable `__isPromisified__` property.

### `promisifyAll(target, options?)`

```ts
function promisifyAll<T extends object>(target: T, options?: PromisifyAllOptions): T
interface PromisifyAllOptions extends PromisifyOptions { suffix?: string; filter?: FilterFunction; promisifier?: PromisifierFunction }
type FilterFunction = (name: string, value: unknown, target: object, passesDefaultFilter?: boolean) => boolean
type PromisifierFunction = (fn, defaultPromisifier, options: PromisifyAllOptions) => (...args: any[]) => Promise<unknown>
```

Adds `<name><suffix>` promisified siblings in place and returns `target`. Defaults: `suffix: "Async"`, `filter` is the default filter, `promisifier` is the default promisifier, plus the `promisify` defaults (`Promise` global, `multiArgs` false, `copyProps` true, `context` undefined).

- Throws `TypeError: the target of promisifyAll must be an object or a function` when `typeof target` is neither. `null` passes that check and is returned unchanged.
- Throws `RangeError: suffix must be a valid identifier ...` when `suffix` does not match `/^[a-z$_][a-z$_0-9]*$/i`.
- Default filter: valid identifier, not starting with `_`, not `constructor`, not ending with `Sync`. Only data properties (no getters or setters) on the object and its prototype chain are considered, excluding the `Object`, `Array` and `Function` prototypes. Non-functions, already-promisified functions, and names whose `<name><suffix>` is already set are skipped.
- A custom `filter` replaces the default one entirely. It gets `passesDefaultFilter` as the fourth argument.
- Throws `TypeError: Cannot promisify an API that has normal methods with 'Async'-suffix ...` when a candidate method name already ends with the suffix.
- Any property whose value looks like a class gets its `prototype` and its own statics promisified too (keys starting with `_` and `constructor` are skipped). A function is treated as a class if its prototype has more than one own name, or any non-`constructor` member, or its source text matches `this.x =` and it has own properties.
- The default promisifier calls `promisify(fn, { ...options, copyProps: false })`. `context` is not bound to the target, so promisified methods use the call-site `this`.

### `OperationalError`

```ts
class OperationalError extends Error { isOperational: boolean; constructor(message: string) }
```

`name` is `"OperationalError"`, `isOperational` is `true`, and a stack is captured. Thrown by `.timeout()`. There is no `RejectionError`.

### `isOperationalError(error)` and `isProgrammerError(error)`

```ts
function isOperationalError(error: unknown): boolean
function isProgrammerError(error: unknown): boolean
```

`isOperationalError` is false for non-objects and `null`, true for an `OperationalError` instance or any object with `isOperational === true`. `isProgrammerError` is false for non-objects and `null` (a thrown string is NOT a programmer error), otherwise `!isOperationalError(error)`.

### `Disposer`

```ts
class Disposer<T> { _data: (resource: T) => void | Promise<void>; _promise: Promise<T>; constructor(fn, promise) }
```

Marker returned by `.disposer()` and consumed by `AveAzul.using`. `using` also accepts any object with a defined `_promise` and a function `_data`.

## Not implemented from Bluebird

Throwing stubs, instance: `bind`, `isFulfilled`, `isRejected`, `isPending`, `isCancelled`, `value`, `reason`, `cancel`, `reflect`, `suppressUnhandledRejections`, `done`.

Throwing stubs, static: `filter`, `coroutine`, `coroutine.addYieldHandler`, `getNewLibraryCopy`, `noConflict`, `setScheduler`.

Absent (property is `undefined`, no stub), static: `TimeoutError`, `CancellationError`, `AggregateError`, `RejectionError`, `onPossiblyUnhandledRejection`, `onUnhandledRejectionHandled`, `config`, `is`, `fulfilled`, `rejected`, `cast`, `pending`, `longStackTraces`, `hasLongStackTraces`, `spawn`. Absent, instance: `caught`, `lastly`, `thenReturn`, `thenThrow`, `isResolved`, `toJSON`.

Differences from Bluebird behavior: filtered `catch` is unsupported, `timeout` rejects with `OperationalError`, `map` defaults to concurrency 50, `each` resolves with the awaited items (a new array), `using` disposes in input order, `filter` is sequential and its callback gets no `length`, the `map` callback's third argument is a context object, `tapCatch` and `catchReturn` have no filter overloads, `props` takes plain objects only, and native Promise resolution and unhandled-rejection behavior apply.

<!-- xaa v3.1.7: https://fynjs.pages.dev/ref/xaa.md -->

# xaa reference

`xaa` provides small async/await and Promise helpers: delay, deferred promises, timeouts, and sequential or concurrent array iteration. It has no runtime dependencies. ESM only (`"type": "module"`).

## Imports

```js
import { delay, map, timeout } from "xaa";
import * as xaa from "xaa";
```

Everything is a named export from the package root. There is no default export and there are no subpaths (only `xaa/package.json`). Use `import * as xaa` to get an `xaa.` namespace.

Runtime exports: `isPromise`, `Defer`, `makeDefer`, `defer` (alias of `makeDefer`), `TimeoutError`, `delay`, `TimeoutRunner`, `timeout`, `runTimeout`, `mapSeries`, `map`, `each`, `filter`, `tryCatch`, `try` (alias of `tryCatch`), `wrap`.

Type-only exports: `MapError`, `MapOptions`, `MapContext`, `MapFunction`.

Not exported: the types `Task`, `Tasks`, `Runnable`, `TimeoutRunnerOptions`, `Consumer`, `Producer`, `Predicate`, `ValueOrErrorHandler`. `TimeoutRunnerOptions` appears in signatures but cannot be imported by name. There is no `defeer` export (a doc comment in the source mentions it, the code does not define it). `try` is a reserved word, so import it with a rename: `import { try as attempt } from "xaa"`, or use `xaa.try`.

## `isPromise(p)`

```ts
function isPromise<T>(p: any): p is Promise<T>
```

Returns a truthy value when `p` has both `then` and `catch` as functions. A thenable with only `then` is not a promise here.

The return value is not strictly boolean. For a falsy `p` (`null`, `undefined`, `0`, `""`) it returns `p` itself. Other values give `true` or `false`.

`map`, `mapSeries` and `each` use this check to decide whether an array item is awaited. `tryCatch` uses it to tell a promise from a function. A thenable without `catch` is treated as a plain value by these helpers.

## `Defer<T>` and `makeDefer`

```ts
class Defer<T> {
  constructor(ThePromise?: PromiseConstructor); // default global.Promise
  promise: Promise<T>;
  resolve: (result?: T) => void;
  reject: (reason?: any) => void;
  done: (err: Error, ...args: any[]) => void;
}

function makeDefer<T>(ThePromise?: PromiseConstructor): Defer<T>
const defer: typeof makeDefer // same function
```

A promise whose `resolve` and `reject` are exposed as properties. `makeDefer(P)` is `new Defer(P)`. `ThePromise` is used to build `promise`, so a custom constructor (such as Bluebird) can be supplied.

- `resolve` and `reject` are the Promise executor functions. Settling more than once is a no-op.
- `done(err, ...args)` is a Node-style callback. A truthy `err` calls `reject(err)`. Otherwise it calls `resolve(args[0])`. Arguments after the first result are dropped.
- `resolve`, `reject` and `done` are own properties bound at construction, so they can be passed as detached callbacks.
- `done` is not declared with an optional `err`, so call it as `done(null, value)`.
- Nothing is thrown by the constructor or by these methods.

```js
const d = xaa.makeDefer();
emitter.once("event", data => d.resolve(data));
const data = await d.promise;
```

## `TimeoutError`

```ts
class TimeoutError extends Error {
  constructor(msg: string);
}
```

`name` is `"TimeoutError"`. Thrown by `timeout().run()`, `runTimeout()` and `TimeoutRunner.cancel()`.

The constructor calls `assert(msg)` after `super(msg)`. An empty or falsy `msg` throws a Node `AssertionError` instead of creating the error. See `timeout` for the consequence of an empty `rejectMsg`.

## `delay(delayMs, valOrFunc?)`

```ts
function delay(delayMs: number): Promise<void>
function delay<T = void>(delayMs: number, valOrFunc: T): Promise<T>
```

Waits `delayMs` using `setTimeout`, then resolves.

- If `valOrFunc` is a function, it is called after the wait with no arguments, lazily. Its return value is the result, and a returned Promise is awaited.
- Otherwise `valOrFunc` is the result. A Promise passed as a value is adopted by the async return.
- With no second argument, the result is `undefined`.
- If the function throws or rejects, the returned promise rejects with that error.
- `delayMs` follows `setTimeout` rules. Negative, `NaN` and `undefined` behave like the minimum timer delay.
- There is no cancel. The timer is not unref'd, so it keeps the process alive until it fires.
- Declared typing note: the overload types the second argument as `T`, not as a function. TypeScript users passing a function get `Promise<() => X>` from the overload, though the runtime returns the function's result.

```js
await xaa.delay(500);
await xaa.delay(500, "Result");
await xaa.delay(500, () => "Result");
```

## `timeout(maxMs, rejectMsg?, options?)`

```ts
function timeout<T>(
  maxMs: number,
  rejectMsg?: string, // default "xaa TimeoutRunner operation timed out"
  options?: TimeoutRunnerOptions // default { TimeoutError, Promise: global.Promise }
): TimeoutRunner<T>

type TimeoutRunnerOptions = {
  TimeoutError: typeof TimeoutError;
  Promise: PromiseConstructor;
}
```

Creates a `TimeoutRunner` and starts its timer immediately, at creation, not when `run()` is called.

| Parameter | Type | Default | Behavior |
| --- | --- | --- | --- |
| `maxMs` | number | none | Milliseconds until the runner rejects with `TimeoutError`. |
| `rejectMsg` | string | `"xaa TimeoutRunner operation timed out"` | Message of the `TimeoutError`. The default applies only when the argument is `undefined`. |
| `options` | `TimeoutRunnerOptions` | `{ TimeoutError, Promise: global.Promise }` | Both fields are required if `options` is passed. `TimeoutError` is the class constructed on timeout. `Promise` is used for `Promise.all`, `Promise.race` and the internal defer. |

Edge cases:

- Passing `rejectMsg` as `""` skips the default. When the timer fires, `new TimeoutError("")` throws inside the timer callback. That surfaces as an uncaught exception, not a rejection.
- If the timer fires before `run()` is called, the internal rejection is stored. It becomes an unhandled rejection unless `run()` attaches to it. A later `run()` still rejects with the `TimeoutError`, though its tasks are started anyway.
- The timeout does not cancel running tasks. The runner stops waiting. The tasks continue.

```js
await xaa.timeout(1000, "timeout fetching data").run(() => fetch(url));
await xaa.timeout(1000).run([promise1, promise2]);
```

## `TimeoutRunner<T>`

```ts
class TimeoutRunner<T> {
  constructor(maxMs: number, rejectMsg: string, options: TimeoutRunnerOptions);
  run<U extends Runnable<T>>(tasks: U): Promise<T | T[]>;
  cancel(msg?: string): void; // default "xaa TimeoutRunner operation cancelled"
  clear(): void;
  hasError(): boolean;
  hasResult(): boolean;
  isDone(): boolean;
  maxMs: number;
  rejectMsg: string;
  error?: Error;
  result?: T | T[];
  ThePromise: PromiseConstructor;
  TimeoutError: typeof TimeoutError;
}
```

Prefer `timeout()` or `runTimeout()` over constructing this directly. The constructor takes all three arguments with no defaults, and starts the timer at once.

Task type accepted by `run` (not exported): `Task<T> = Promise<T> | (() => Promise<T>)`. An array form is `Task` per element.

### `run(tasks)`

- A non-array `tasks` is one task. An array is a list of tasks. Detection uses `Array.isArray`.
- Each task is processed as: a function is called with no arguments and its result used, anything else is used as is. Despite the type, non-promise values such as `"some value"` pass through as results. Functions are called when `run` is called, all in array order, synchronously before any await.
- A function that throws synchronously becomes a rejection, because the processing step is async.
- An array runs concurrently and resolves like `Promise.all`: results are in task order, not completion order. The first rejection rejects the run.
- The run races the tasks against the timer. If the timer wins, `run` rejects with `TimeoutError(rejectMsg)`.
- On success the timer is cleared, `result` is set, and `result` is returned. On any failure the timer is cleared, `error` is set, and the error is rethrown unchanged (task errors keep their identity).
- Tasks already started are never cancelled. After a timeout or `cancel`, their later results or errors are ignored.
- Calling `run` more than once on one runner is not guarded. The timer is already cleared after the first run, so later runs have no timeout and overwrite `result` or `error`.

### Other members

| Member | Behavior |
| --- | --- |
| `cancel(msg?)` | Clears the timer and rejects the internal promise with `new TimeoutError(msg)`. A pending `run` rejects with it. `msg` defaults to `"xaa TimeoutRunner operation cancelled"`. An empty string throws `AssertionError` from `TimeoutError`. If `run` was never called, the rejection is unhandled until it is. |
| `clear()` | Clears the timer handle only. Does not settle anything. Safe to call repeatedly. |
| `hasError()` | True once `run` has failed. Uses an own-property check on `error`. |
| `hasResult()` | True once `run` has succeeded. Uses an own-property check on `result`. |
| `isDone()` | `hasResult() \|\| hasError()`. |
| `error`, `result` | Set by `run` only. Absent before. A successful run whose result is `undefined` still has `hasResult()` true. |
| `maxMs`, `rejectMsg`, `ThePromise`, `TimeoutError` | The values given at construction. |

## `runTimeout(tasks, maxMs, rejectMsg?, options?)`

```ts
function runTimeout<T>(tasks: Task<T>, maxMs: number, rejectMsg?: string, options?: TimeoutRunnerOptions): Promise<T>
function runTimeout<T extends readonly any[]>(tasks: Tasks<T>, maxMs: number, rejectMsg?: string, options?: TimeoutRunnerOptions): Promise<T[]>
```

Equivalent to `timeout(maxMs, rejectMsg, options).run(tasks)`. Defaults, ordering, errors and no-cancel behavior are the same as `timeout` and `run`. `undefined` for `rejectMsg` or `options` selects the defaults.

## `map(array, func?, options?)`

```ts
function map<T, O>(
  array: readonly T[],
  func?: MapFunction<T, O>,
  options?: MapOptions // default { concurrency: 50 }
): Promise<O[]>

type MapFunction<T, O> = (value: Awaited<T>, index: number, context: MapContext<T>) => O | Promise<O>

type MapOptions = {
  concurrency: number;
  thisArg?: any;
}

type MapContext<T> = {
  failed?: boolean;
  array: readonly T[];
  assertNoFailure: () => void;
}

interface MapError<T> extends Error {
  partial: T[];
}
```

Maps an array with a callback and an in-flight limit. Similar to `bluebird.map`.

### Options

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `concurrency` | number | 50 when `options` is omitted | Maximum callbacks in flight. Greater than 1 uses the concurrent engine. 1, 0, negative, or `undefined` use `mapSeries`. |
| `thisArg` | any | `undefined` | `this` inside `func`. Use a non-arrow function. |

The default of 50 applies only when the whole `options` argument is omitted. `{ thisArg }` alone has no `concurrency`, which means serial.

### Behavior

- `array` must satisfy `Array.isArray`. Otherwise `map` rejects with an `AssertionError` with message `xaa.map expecting an array but got <typeof array>`. The rejection is a promise rejection, not a sync throw.
- Result order matches input order, not completion order. An empty array resolves `[]`.
- Items that pass `isPromise` are awaited and `func` receives the resolved value. A rejected item fails the whole map. A thenable without `catch` is passed to `func` as is.
- Concurrent mode starts up to `concurrency` callbacks synchronously on call, then starts the next item as each completes. A slot is held by an item while its promise is awaited.
- `func` may return a value or a promise. A returned promise is awaited by the slot.
- `func` is called with `(value, index, context)`.
- `func` omitted: the call throws a `TypeError`, which is reported as a failure.

### Failure

- The first failure rejects `map` with the original error object. Its `partial` property is set to the result array so far.
- In concurrent mode, `partial` is the live result array with the full input length. Unfinished slots are holes, and it may keep filling as in-flight callbacks finish. In serial mode it holds only completed results, dense.
- No new items start after a failure. In-flight callbacks are not cancelled. Their later failures are ignored.
- `context.failed` becomes true at failure. `context.assertNoFailure()` throws `new Error("assertNoFailure")` when `failed` is true. A long-running callback can call it to stop early.
- `partial` is assigned on the thrown value. If that value is not an object (for example a thrown string), the assignment throws a `TypeError` in strict mode, which is what the caller then sees.
- Concurrent mode, known gap: a synchronous throw from `func` when the item was a promise is not caught. It becomes an unhandled rejection and the `map` promise never settles. Synchronous throws for non-promise items are handled as normal failures. Return a rejected promise or use an `async` function to avoid this.

```js
const pages = await xaa.map(urls, async url => (await fetch(url)).text(), { concurrency: 2 });
```

## `mapSeries(array, func?, options?)`

```ts
function mapSeries<T, O>(array: readonly T[], func?: MapFunction<T, O>, options?: MapOptions): Promise<O[]>
```

Serial map. Exported, and `map` calls it when `concurrency <= 1`.

- Iterates with `for...of`. It does not check `Array.isArray`, so any iterable works. Non-iterables throw `TypeError` as a rejection.
- Each item: an `isPromise` item is awaited, then `await func.call(options?.thisArg, item, i, context)`. One callback at a time, in order.
- `options` is optional and only `thisArg` is read. `concurrency` is ignored.
- On any error, `context.failed` is set, `error.partial` is set to the completed results (dense array), and the original error is rethrown.
- Same non-object error caveat as `map` for `partial`.

## `each(array, func)`

```ts
function each<T>(array: readonly T[], func: Consumer<T>): Promise<T[]>
// Consumer<T> = (item: T, index?: number) => unknown
```

Async `forEach`. Serial, in order.

- Iterates with `for...of`, so any iterable works. No array check.
- Each item that passes `isPromise` is awaited first. Then `await func(item, index)`.
- Resolves to an array of the resolved items, not of the callback results.
- The first error from an item or the callback rejects with that error. Later items are not processed. There is no `partial`.
- There is no `thisArg` and no context argument.

```js
await xaa.each([1, 2, 3], async val => await xaa.delay(val));
```

## `filter(array, func)`

```ts
function filter<T>(array: readonly T[], func: Predicate<T>): Promise<T[]>
// Predicate<T> = (item: T, index?: number) => boolean | Promise<boolean>
```

Async filter. Concurrency is fixed at 1: each predicate result is awaited before the next call.

- Iterates by index up to `array.length`, so array-likes work.
- Items are not awaited. A promise item is passed to `func` as is, and a kept promise is returned as is.
- Keeps the original item when the awaited result is truthy.
- A predicate error rejects with that error. There is no `partial`.
- Resolves to a new array in input order.

## `tryCatch(funcOrPromise, valOrFunc?)` and `try`

```ts
function tryCatch<T, TAlt>(
  funcOrPromise: Promise<T> | (() => T | Promise<T>),
  valOrFunc?: ValueOrErrorHandler<TAlt>
): Promise<T | TAlt>

// ValueOrErrorHandler<T> = T extends Function ? never : T | Promise<T> | ((err?: Error) => T | Promise<T>)
```

`try` is the same function exported under a second name.

- If `funcOrPromise` passes `isPromise`, it is awaited. Otherwise it is called with no arguments and the result is awaited.
- On success, resolves to that value.
- On any exception or rejection, if `valOrFunc` is a function it is called with the error and its return value is the result. A returned Promise is adopted. Otherwise `valOrFunc` itself is the result, so omitting it gives `undefined`.
- Errors thrown by the `valOrFunc` handler propagate as a rejection.
- If `funcOrPromise` is neither a promise nor a function, calling it throws a `TypeError` that is caught like any other error, so the fallback is returned.
- It never rethrows the original error. Use `valOrFunc` to inspect it.
- A function passed as a plain fallback value is always treated as a handler. Wrap it as `() => fn` to return a function.

## `wrap(func, ...args)`

```ts
function wrap<T, F extends (...args: any[]) => T>(func: F, ...args2: Parameters<F>): Promise<T>
```

Calls `func(...args)` inside an async function and returns its result as a promise. Similar to `bluebird.try`.

- `func` is invoked synchronously during the `wrap` call.
- A synchronous throw becomes a rejection with the same error.
- A returned Promise is adopted. A returned value is wrapped.
- `this` is not bound.

<!-- item-queue v2.1.10: https://fynjs.pages.dev/ref/item-queue.md -->

# item-queue reference

`item-queue` is an async item processing queue. It runs a `processItem` callback over queued items with bounded concurrency, supports pause and resume, emits events per item, and can report items that take too long. ESM only (`"type": "module"`). Runtime dependency: `xflight`.

## Imports

```js
import { ItemQueue } from "item-queue";
```

```ts
import {
  ItemQueue,
  type ItemQueueOptions,
  type ItemQueueHandlers,
  type ItemQueueResult,
  type WatchData,
} from "item-queue";
```

Everything is a named export from the package root. There is no default export and there are no subpaths (only `item-queue/package.json`).

Runtime exports: `ItemQueue`, `Inflight`.

Type-only exports: `ItemQueueData`, `WatchItemInfo`, `WatchData`, `ItemQueueResult`, `ItemQueueHandler`, `ItemQueueHandlers`, `ProcessCb`, `ItemQueueOptions`, `InflightRecord`, `RecordKey`.

Not exported: the internal `InflightData` type and the control symbols used for pause and resume. `Inflight` is `InflightStore` re-exported from `xflight` (not xflight's own `Inflight` class). `InflightRecord` is xflight's `InflightItem`.

## `ItemQueue`

```ts
class ItemQueue<ItemT = unknown> extends EventEmitter {
  constructor(options: ItemQueueOptions<ItemT>);
  static get pauseItem(): symbol;
  wait(): Promise<void>;
  start(): this;
  resume(): this;
  pause(): this;
  unpause(): this;
  addItem(item: ItemT, noStart?: boolean, stopOnError?: boolean): this;
  addItems(items: ItemT[], noStart?: boolean): this;
  setItemQ(itemQ: ItemT[], noStart?: boolean): this;
  deferProcess(): void;
  get isPause(): boolean;
  get isPending(): boolean;
  get count(): number;
}
```

`ItemQueue` extends Node's `EventEmitter`, so `on`, `once`, `off`, `removeListener` and the rest are available. `addItem`, `addItems`, `setItemQ`, `pause`, `unpause`, `start` and `resume` are chainable. Declared return types are inferred, so they are `this`-like instances of the class.

The queue is reusable. After `done` it accepts more items and runs again.

### Constructor and `ItemQueueOptions`

```ts
type ItemQueueOptions<ItemT = unknown> = {
  Promise?: PromiseConstructor;
  itemQ?: ItemT[];
  concurrency?: number;
  processItem: ProcessCb<ItemT>;
  stopOnError?: boolean;
  timeout?: number;
  watchPeriod?: number;
  watchTime?: number;
  handlers?: ItemQueueHandlers<ItemT>;
};
```

| option | type | default | behavior |
| --- | --- | --- | --- |
| `processItem` | `ProcessCb<ItemT>` | none, required | Called once per item. See `ProcessCb`. |
| `itemQ` | `ItemT[]` | none | Initial items. Added with `addItems(itemQ, true)`, so they are copied and processing does not start. Call `start()`, `resume()` or an add method without `noStart`. |
| `concurrency` | `number` | `15` | Max items in flight. Uses `\|\|`, so `0`, `NaN` and `undefined` give `15`. A negative value is truthy and keeps no slot free, so no item ever starts. |
| `stopOnError` | `boolean` | `undefined` (falsy) | When truthy, the first failed item fails the queue. See Error handling. |
| `timeout` | `number` | none | Stored and never used. It has no effect. |
| `watchPeriod` | `number` (ms) | `500` | Interval between overdue checks. Uses `\|\|`, so `0` gives `500`. |
| `watchTime` | `number` (ms) | none | Elapsed time after which an in-flight item is reported by `watch`. Falsy (unset or `0`) disables the watcher entirely. |
| `handlers` | `ItemQueueHandlers<ItemT>` | none | Each own entry with a truthy value is registered with `this.on(name, fn)`. Any key name is registered, not only the known events. |
| `Promise` | `PromiseConstructor` | global `Promise` | Used to create the promises that `wait()` returns and the promises wrapped around `processItem` results. |

Throws `AssertionError` from the constructor:

- `"ItemQueue: must provide options.processItem callback"` when `options` is missing or `processItem` is not a function.
- `"ItemQueue: No Promise implementation available"` when neither `options.Promise` nor a global `Promise` exists.

### `ProcessCb`

```ts
type ProcessCb<ItemT> = (item: ItemT, id?: number) => Promise<unknown> | void;
```

- `item` is the queued item.
- `id` is a number from a counter that starts at `1` and grows by one for each item the queue starts. Internal resume items also take an id, so ids seen by `processItem` can skip numbers.
- A synchronous return value is wrapped with `Promise.resolve`. Any returned value with a `then` property is used as the promise. The resolved value becomes `res` in the `doneItem` data.
- A synchronous throw is caught and treated as a rejection of that item.
- A returned promise that rejects is a failed item. See Error handling.

### `addItem(item, noStart?, stopOnError?)`

Appends one item to the end of the queue. Sets the internal empty flag to `false`, so `empty` can fire again.

- `noStart`: when falsy, calls `deferProcess()`. When `true`, the queue is not started.
- `stopOnError`: stored on that item. Only `false` has an effect. See Error handling.
- Never throws and does not check the item. Returns the queue.
- If `item` is a `symbol`, it is treated as a control item, not data. See Quirks.

### `addItems(items, noStart?)`

Appends each item with `addItem(x, true)`, then calls `deferProcess()` unless `noStart` is truthy. Throws `AssertionError` `"item-queue: Must pass array to addItems"` when `items` is not an array. Items added this way cannot carry a per-item `stopOnError`. Returns the queue.

### `setItemQ(itemQ, noStart?)`

Replaces the not-yet-started items with a copy of `itemQ`. Items already in flight are not affected. Any queued pause or resume control item is discarded too. Sets the empty flag to `itemQ.length === 0`. Calls `deferProcess()` unless `noStart` is truthy. Throws `AssertionError` `"item-queue: Must pass array to setItemQ"` when `itemQ` is not an array. Returns the queue.

### `deferProcess()`

Schedules one processing pass with `process.nextTick`. Calls made before the tick runs collapse into one pass. The pass does not check `isPause` before starting, but a paused queue starts nothing (see `pause`). Returns `undefined`.

### `start()` and `resume()`

`start()` is exactly `resume()`.

`resume()` returns the queue at once and does the work on the next tick:

1. Set `isPause` to `false` (same as `unpause()`).
2. If the item queue is empty, push one internal resume item. It uses a concurrency slot, runs no callback, resolves immediately, and produces no `doneItem`.
3. Run one processing pass.

Consequences:

- Calling `start()` on a queue with no items still emits `empty` (once) and then `done`.
- If a pause control item is still in the queue, step 3 reaches it and pauses again. See Quirks.

### `pause()`

```ts
pause(): this
```

Puts a pause control item at the front of the queue (`unshift`). It does not set `isPause` and does not start any pass.

The pause takes effect when a processing pass reaches that item. A pass runs when an in-flight item settles, or on `start()`, `resume()` or `deferProcess()`. In-flight items always finish. When the pause item is reached:

- `isPause` becomes `true` and no further items start.
- If nothing is in flight, `pause` is emitted on the next tick.
- Otherwise `pause` is emitted when the last in-flight item settles.

Each `pause()` call queues another pause item. Because the item goes to the front, it runs before every item that is already queued.

### `ItemQueue.pauseItem`

```ts
static get pauseItem(): symbol
```

A special value you can pass to `addItem`, `addItems`, `setItemQ` or the `itemQ` option to pause at that position. Items before it start first. Type it with a cast when `ItemT` does not include `symbol`, for example `addItem(ItemQueue.pauseItem as any)`. All callers get the same symbol.

Pausing through it behaves like `pause()` except for its position.

### `unpause()`

Sets `isPause` to `false`. Returns the queue. It does not start processing and does not remove queued pause items.

### `wait()`

```ts
wait(): Promise<void>
```

Returns a promise that settles when the queue finishes. The check happens at call time:

1. If the queue has failed (stopOnError), returns a promise rejected with the stored error.
2. Else if `isPending` is true, returns a promise that resolves on the next `done` event and rejects on the next `fail` event with `data.error`.
3. Else returns a resolved promise at once.

Rules:

- The resolved value is the `done` payload object `{ startTime, endTime, totalTime }`, though the declared type is `void`.
- A `pause` event does not settle the promise. Waiting on a paused queue hangs until it is resumed and finishes.
- `wait()` does not start the queue. If items were added with `noStart`, the promise stays pending until something starts processing.
- If the queue is empty when `wait()` is called, it resolves at once even if `start()` was just called.
- Failed items without `stopOnError` do not reject `wait()`.
- Each call adds its own listeners, and they are removed once it settles.

### Properties

| property | type | behavior |
| --- | --- | --- |
| `isPause` | `boolean` | `true` once a pause item has been reached, until `unpause()` or `resume()` runs. It is `undefined` (not `false`) until the first pause or unpause. |
| `isPending` | `boolean` | `true` when anything is in flight or any item is queued, including control items. |
| `count` | `number` | In-flight count plus queued count. It includes internal pause and resume control items. |

### Events

Events are emitted with `EventEmitter.emit`. Listeners are synchronous. Register them with `on` or `options.handlers`. Names are exact and case sensitive.

```ts
type ItemQueueHandlers<ItemT = unknown> = {
  done?: (data: { startTime: number; endTime: number; totalTime: number }) => void;
  failItem?: ItemQueueHandler<ItemT>;
  fail?: ItemQueueHandler<ItemT>;
  doneItem?: ItemQueueHandler<ItemT>;
  pause?: () => void;
  empty?: () => void;
  watch?: (data: WatchData<ItemT>) => void;
};
type ItemQueueHandler<ItemT = unknown> = (data: ItemQueueResult<ItemT>) => void;
```

| event | payload | fires when |
| --- | --- | --- |
| `doneItem` | `ItemQueueResult` with `id`, `res`, `item` | A real item settled with a truthy-or-no error. `res` is the resolved value of the `processItem` result. |
| `failItem` | `ItemQueueResult` with `id`, `error`, `item` | A real item rejected or threw a truthy error. Emitted before `fail`. |
| `fail` | same data as the `failItem` that caused it | The failing item's `stopOnError` rule matched (see Error handling). Emitted once, right after `failItem`. |
| `empty` | none | The queued list is empty after an item settles and the empty flag is not set. The flag is then set, so it fires once until `addItem`, `addItems` or a non-empty `setItemQ` resets it. Items may still be in flight. Emitted before `done` in the same step. |
| `pause` | none | A pause item has been reached and nothing is in flight. |
| `done` | `{ startTime, endTime, totalTime }` | Nothing queued, nothing in flight, not paused, not failed. Times are ms epoch values and `totalTime = endTime - startTime`. |
| `watch` | `WatchData` | See Watch. |

Order within one item settling: `doneItem` or `failItem` (then `fail`), then `empty`, then either the next processing pass, or `pause` or `done` when nothing is in flight.

Control items (pause, resume and symbol items) never produce `doneItem` or `failItem`.

After the queue has failed, settling items emit nothing at all.

`done` can fire many times if the queue is reused. `startTime` is set once at the first processing pass and never reset, so `totalTime` on later `done` events includes idle time.

### Concurrency and ordering

- Items start in FIFO order. `addItem` appends. `pause()` is the only call that inserts at the front.
- A processing pass starts items while `queued > 0` and `inFlight < concurrency`. Passes run when an item settles (if not paused and items are queued), and from `deferProcess`, `start` and `resume`.
- Completion order is whatever the callbacks produce. The queue does not preserve result order.
- Items already in flight are never cancelled by pause, `setItemQ` or failure.
- `processItem` is called synchronously during a pass. Items added from inside a callback are picked up on a later tick via `deferProcess`.

### Error handling

A rejected promise or a synchronous throw from `processItem` marks the item failed. `failItem` fires with `error` set to the rejection reason.

An item counts as failed only when the reason is truthy. `Promise.reject(undefined)`, `reject(0)` or `reject("")` are reported as `doneItem`.

The queue fails when both are true: `options.stopOnError` is truthy and the item's own `stopOnError` is not `false`.

| queue `stopOnError` | item `stopOnError` | result |
| --- | --- | --- |
| falsy | any | `failItem` only. Queue keeps going. |
| truthy | `undefined` or `true` | `failItem` then `fail`. Queue fails. |
| truthy | `false` | `failItem` only. Queue keeps going. |

On a failed queue:

- `fail` is emitted once, and `done` is never emitted for that run.
- Items still in the queue are not started, and they stay queued, so `isPending` stays `true`.
- Items already in flight finish quietly with no events.
- `wait()` rejects with the error, including for calls made later.
- The failed state is permanent. There is no reset method.
- Without `stopOnError`, the queue always ends with `done` and `wait()` resolves, even if every item failed. Collect errors from `failItem`.

### Watch

Enabled only when `options.watchTime` is truthy. The watcher checks every `watchPeriod` ms, using an unref'd timer, so it does not keep the process alive. It first runs on the tick after the first processing pass, then repeats while items are in flight or a `watch` report is still open. It starts again on the next processing pass.

```ts
type WatchData<ItemT = unknown> = {
  total: number;
  watchTime: number;
  watched: WatchItemInfo<ItemT>[];
  still: WatchItemInfo<ItemT>[];
};
type WatchItemInfo<ItemT = unknown> = {
  item: ItemT;
  promise: Promise<unknown>;
  time: number;
};
```

On each check, every in-flight item with elapsed time `>= watchTime` is reported:

- In `watched` when at least `watchTime` ms passed since the item's last report (or its start). Reporting resets that timer.
- In `still` otherwise.

`total = watched.length + still.length`. `time` is ms since the item started. `promise` is the internal promise the queue tracks for the item, which settles after the queue handled the item, not the promise your callback returned. An item with a `watched` entry is next reported as `watched` only after another `watchTime` ms. If `watchPeriod` is shorter than `watchTime`, the in-between checks list it in `still`.

If a `watch` event was emitted earlier and a later check finds no overdue items, one last `watch` is emitted with `total: 0` and empty arrays. A final check also runs right before `done`.

### Types

```ts
type ItemQueueData<ItemT = unknown> = {
  item: ItemT;
  stopOnError?: boolean;
  promise?: Promise<unknown>;
  _control?: symbol;
};
type ItemQueueResult<ItemT = unknown> = ItemQueueData<ItemT> & {
  id: number;
  res?: ItemT;
  error?: Error;
};
```

- `ItemQueueData` is the wrapper stored for each queued item. `promise` is declared but never set by the code. `_control` is internal and set only for control items.
- `ItemQueueResult` is the payload of `doneItem`, `failItem` and `fail`. Real payloads contain `id`, `item`, `stopOnError` (the per-item value, usually `undefined`), and either `res` or `error`.
- `res` is typed `ItemT` but is really the resolved value of `processItem`. `error` is typed `Error` but is whatever the item rejected with.

### Quirks

- A `symbol` passed as an item is treated as a control item. Its `item` becomes `undefined`. If it is not `ItemQueue.pauseItem`, `processItem` is still called with `undefined`, and no `doneItem` or `failItem` fires for it.
- `pause()` then `resume()` on an idle queue, before any pass has reached the pause item, ends paused. The pass reached by `resume()` consumes the pause item, so `pause` is emitted and no items start. Call `resume()` again.
- After a stopOnError failure, `addItem` without `noStart` starts a pass that still starts items. Their results are silent because the queue is failed.
- The per-item `stopOnError` flag can only turn failure off for one item. `addItem(x, false, true)` does not fail a queue whose own `stopOnError` is falsy.
- `empty` is not emitted if `setItemQ([])` was called while items were in flight. `done` still follows.
- `concurrency` below `0` stalls the queue. Items stay queued.

## `Inflight`

```ts
class Inflight<V = unknown> {
  add(key: RecordKey, value: V, now?: number): V;
  get(key: RecordKey): V | undefined;
  remove(key: RecordKey): void;
  entries(): IterableIterator<[RecordKey, InflightRecord<V>]>;
  get isEmpty(): boolean;
  get count(): number;
  getStartTime(key: RecordKey): number | undefined;
  time(key: RecordKey, now?: number): number;
  elapseTime(key: RecordKey, now?: number): number;
  getCheckTime(key: RecordKey): number | undefined;
  lastCheckTime(key: RecordKey, now?: number): number;
  elapseCheckTime(key: RecordKey, now?: number): number;
  resetCheckTime(key?: RecordKey, now?: number): this;
}
type RecordKey = string | number | symbol;
type InflightRecord<V> = { readonly start: number; lastXTime: number; value: V };
```

This is the keyed time-tracking store that `ItemQueue` uses internally. It is the `InflightStore` class from `xflight`, re-exported under the name `Inflight`. It is separate from `xflight`'s own `Inflight` (promise de-duplication) class.

- `add` throws `AssertionError` `"xflight: item <key> already exist"` for a key already tracked. It stores `start` and `lastXTime` as `now`, or `Date.now()`.
- `remove` throws `AssertionError` `"xflight: removing non-existing item <key>"` when the key is unknown.
- `time` and `lastCheckTime` return elapsed ms since start or last check, or `-1` for an unknown key. `elapseTime` and `elapseCheckTime` are aliases.
- `resetCheckTime(key)` sets `lastXTime` for one key. Without a key it resets all of them. An unknown key is ignored.
- `ItemQueue` does not expose its own instance, so this export is only useful as a standalone helper.

<!-- xflight v3.1.9: https://fynjs.pages.dev/ref/xflight.md -->

# xflight reference

`xflight` dedupes inflight async work by key. `Inflight.promise(key, factory)` runs the factory once per key while its promise is pending and hands every concurrent caller the same promise. It has no runtime dependencies. ESM only (`"type": "module"`).

## Imports

```js
import Inflight from "xflight";
import { Inflight, InflightStore } from "xflight";
```

```ts
import type { Timestamp, RecordKey, PromiseFactory, InflightItem } from "xflight";
```

Runtime exports: `Inflight` (named and default), `InflightStore`.

Type-only exports: `Timestamp`, `RecordKey`, `PromiseFactory`, `InflightItem`.

Not exported: the internal `assert` helper. There are no subpaths (only `xflight/package.json`). The default export is the same class as the named `Inflight` export, so `Inflight` is the only name that matters for deduplication.

## Types

```ts
type Timestamp = number;                       // ms since epoch
type RecordKey = string | number | symbol;     // any Map key of these kinds
type PromiseFactory<T> = () => Promise<T>;

interface InflightItem<V> {
  readonly start: Timestamp;     // when the entry was added
  lastXTime: Timestamp;          // last check time, set to start on add
  readonly value: V;             // the tracked value
}
```

Keys are compared by `Map` identity rules (`SameValueZero`). `1` and `"1"` are different keys.

## `InflightStore<V>`

```ts
class InflightStore<V = unknown> {
  protected readonly _inflights: Map<RecordKey, InflightItem<V>>;
  add(key: RecordKey, value: V, now?: Timestamp): V;
  get(key: RecordKey): V | undefined;
  remove(key: RecordKey): void;
  entries(): IterableIterator<[RecordKey, InflightItem<V>]>;
  get isEmpty(): boolean;
  get count(): number;
  getStartTime(key: RecordKey): Timestamp | undefined;
  time(key: RecordKey, now?: Timestamp): number;
  elapseTime(key: RecordKey, now?: Timestamp): number;
  getCheckTime(key: RecordKey): Timestamp | undefined;
  lastCheckTime(key: RecordKey, now?: Timestamp): number;
  elapseCheckTime(key: RecordKey, now?: Timestamp): number;
  resetCheckTime(key?: RecordKey, now?: Timestamp): this;
}
```

A keyed store of in-progress work with start-time and last-check-time tracking. It stores any value type `V` and knows nothing about promises. It has no constructor arguments. `Inflight` extends it, so every method below also exists on `Inflight`. Use `InflightStore` directly when the tracked value is not a promise, or when keys are numbers.

The store never removes entries on its own. The caller calls `remove`. Nothing here settles, awaits or times out anything.

`now` is a caller-supplied timestamp in ms, used for tests or a shared clock. It is checked with `??`, so `0` is honored. When omitted it is `Date.now()`.

### `add(key, value, now?)`

Tracks `value` under `key` and returns `value`. Sets `start` and `lastXTime` to `now ?? Date.now()`.

Throws `Error("xflight: item <key> already exist")` when the key is present. The key is printed with `String(key)`.

### `get(key)`

Returns the tracked value, or `undefined` when the key is absent. Does not touch timestamps.

### `remove(key)`

Deletes the entry and returns `undefined`. Throws `Error("xflight: removing non-existing item <key>")` when the key is absent. Calling `remove` twice for one key throws on the second call.

### `entries()`

Returns the live `Map` iterator of `[key, record]` pairs, in insertion order. `record` is the `InflightItem`, so `record.value`, `record.start` and `record.lastXTime` are readable. The records are the stored objects, not copies. Because it is a live iterator, adding or removing entries while iterating follows `Map` iteration rules.

### `isEmpty`, `count`

Getters, not methods. `isEmpty` is `true` when there are no entries. `count` is the number of entries.

### Timing methods

| Method | Returns |
| --- | --- |
| `getStartTime(key)` | `start` of the entry, or `undefined` when absent |
| `time(key, now?)` | `(now ?? Date.now()) - start`, or `-1` when absent |
| `elapseTime(key, now?)` | alias of `time` |
| `getCheckTime(key)` | `lastXTime` of the entry, or `undefined` when absent |
| `lastCheckTime(key, now?)` | `(now ?? Date.now()) - lastXTime`, or `-1` when absent |
| `elapseCheckTime(key, now?)` | alias of `lastCheckTime` |

None of these throw. `-1` marks a missing key. A real elapsed value can also be negative if `now` is earlier than the stored time, so `-1` alone is not proof of absence. Use `get` or `getStartTime` to test presence.

`lastXTime` starts equal to `start`. Only `resetCheckTime` changes it. Reading it never updates it.

### `resetCheckTime(key?, now?)`

Sets `lastXTime` to `now ?? Date.now()` and returns `this` for chaining.

- With a key: updates that entry. An absent key is a silent no-op, no throw.
- With no key (or `undefined`): updates every entry to the same timestamp.

`start` is never changed.

## `Inflight<T>`

```ts
class Inflight<T = unknown> extends InflightStore<Promise<T>> {
  readonly Promise: PromiseConstructor;
  constructor(PromiseImpl?: PromiseConstructor);
  promise(key: RecordKey, factory: PromiseFactory<T>): Promise<T>;
}
export default Inflight;
```

All entries hold `Promise<T>` values. One `T` applies to every key of an instance. Inherited methods are documented under `InflightStore<V>` with `V = Promise<T>`.

### Constructor

| Argument | Type | Default | Behavior |
| --- | --- | --- | --- |
| `PromiseImpl` | `PromiseConstructor` | `globalThis.Promise` | Stored as the public readonly property `inflight.Promise`. |

Nothing is thrown. No Promise library is detected or loaded. The custom implementation is used for exactly one thing: building the rejected promise that `promise()` returns when the factory fails (see below). Promises returned by the factory are stored and returned unchanged, whatever their class.

### `promise(key, factory)`

Returns the promise tracked for `key` if one exists. Otherwise calls `factory()` once, tracks the result, and returns it.

Flow:

1. `get(key)` is truthy: return that stored promise. The factory is not called.
2. Call `factory()` with no arguments.
3. If the result is falsy or has no function `then`, fail (see below). Any object with a `then` function is accepted. It need not be a native promise.
4. Store it with `add(key, p)` (start and check time set to now). Attach `then(cleanup, cleanup)` to it.
5. Return `p` itself, not a wrapper.

What callers receive:

- First caller and every concurrent caller get the identical object (`===`) returned by the factory. Success value, rejection reason and any extra methods of a custom promise class are the same for all of them.
- On resolve or reject, all holders of that promise see the same outcome. There is no per-caller copy and no retry.
- The factory runs once per key per inflight period. Arguments, closures and side effects of later callers' factories are discarded because those factories are never called.

When an entry is removed:

- The entry is deleted when the stored promise settles, resolved or rejected. The delete happens in a handler attached when the entry was added, so it runs before handlers attached later by callers.
- Cleanup uses a plain map delete. It does not throw if the entry was already removed manually.
- Cleanup handles the rejection of its own derived promise only. The promise `p` returned to the caller still rejects normally, so callers must handle it.
- After settle, the next `promise(key, ...)` call runs its factory again. A resolved result is not cached.

When no entry is created:

- If `factory()` throws synchronously, the error is caught and `promise()` returns `this.Promise.reject(err)`. No entry exists. The next call for that key calls the factory again. `promise()` itself never throws for factory errors.
- If `factory()` returns a non-thenable (including `undefined`, `null`, `0`, `""`), `promise()` returns a rejected promise with `Error("xflight: promiseFactory for key <key> didn't return a promise")`. No entry exists.
- A factory that returns a promise that is already rejected does add an entry. It is removed after the cleanup handler runs, a microtask later.

Because sync failures come back as rejected promises, `promise()` always returns a thenable and callers need only one error path.

```ts
const inflight = new Inflight<Response>();
const [a, b] = await Promise.all([
  inflight.promise("user:123", () => fetch("/api/user/123")),
  inflight.promise("user:123", () => fetch("/api/user/123")),
]);
// one fetch, a === b
```

### Manual use with inherited methods

`add` on an `Inflight` is typed `add(key, value: Promise<T>, now?)`. It adds no cleanup handler. An entry added with `add` stays until `remove` is called, even after its promise settles. `promise(key, ...)` for such a key returns the stored promise, settled or not.

Other `InflightStore` behaviors carry over: `add` throws on a duplicate key, `remove` throws on an absent key, `get` returns `undefined` when absent.

## Edge cases and caveats

- Manual `remove(key)` then a new `promise(key, f2)` while the first promise `p1` is still pending: when `p1` settles, its cleanup deletes `key` unconditionally. That drops the entry for the newer promise `p2`, even though `p2` is still pending. A third caller then starts a new factory run. Cleanup does not check that the stored value is still `p1`.
- `promise()` checks `get(key)` for truthiness. A falsy value stored with the inherited `add` (possible only by bypassing types) is treated as absent, and the following `add` throws `already exist`. That error is caught, so `promise()` returns a rejected promise.
- Timing data is by `Date.now()`, so it is wall clock, not monotonic.
- Elapsed time is not auto-tracked against a timeout. `Inflight` never cancels or times out a pending factory. Sweep `entries()` with `time` or `lastCheckTime` for overdue detection.
- `Symbol` keys work and are printed in error messages through `String(key)`.

<!-- @fynjs/fetch v1.0.6: https://fynjs.pages.dev/ref/fetch.md -->

# @fynjs/fetch reference

`@fynjs/fetch` is a zero-dependency HTTP client built on Node core `fetch`. It adds retries, timeouts, hooks, URL and body helpers, typed HTTP errors, and socket-safe body draining. Requires Node `^22.22.2 || ^24.15.0 || >=26.0.0`. ESM only (`"type": "module"`).

## Imports

```js
import fynFetch, { createInstance, HttpError, TimeoutError, drain, stream } from "@fynjs/fetch";
// fynFetch is also a named export
import { fynFetch } from "@fynjs/fetch";
```

```ts
import type {
  FynFetchOptions, RetryOptions, FynFetchInstance,
  FynFetchHooks, BeforeRetryContext, SearchParamsInit,
} from "@fynjs/fetch";
```

Runtime exports: `default` (= `fynFetch`), `fynFetch`, `createInstance`, `HttpError`, `TimeoutError`, `drain`, `stream`. Type-only exports: the six types above. The only subpath is `@fynjs/fetch/package.json`. Helpers such as `buildUrl`, `mergeOptions`, `prepareRequest` and `isStream` are internal and not exported.

## `fynFetch`

```ts
const fynFetch: FynFetchInstance; // createInstance({})
fynFetch(url: string | URL, options?: FynFetchOptions): Promise<Response>
```

The default instance with no default options. The call resolves with the `Response` of the final attempt. It does not throw on non-2xx unless `throwOnHttpError` is true. It rejects on network failure, timeout, abort, hook error or option misuse.

Per-call flow:

1. Merge instance defaults with call options (see Merging).
2. Run `hooks.beforeRequest` once, in order. A returned `Response` short-circuits (see Hooks).
3. Build the request: URL, headers, auth, cookies, body (see Request building).
4. Validate `retry` and streaming-body rules.
5. Per attempt: create body (if `bodyFactory`), arm timeout, call global `fetch`, decide on retry, or finalize (`afterResponse` hooks, then `throwOnHttpError`).

All other `RequestInit` fields (`method`, `headers`, `signal`, `redirect`, `dispatcher`, `credentials`, and so on) pass through to `fetch` unchanged.

## `createInstance(defaultOptions?)`

```ts
function createInstance(defaultOptions?: FynFetchOptions): FynFetchInstance
```

Returns a callable instance. `defaultOptions` defaults to `{}`. The object is stored by reference as `instance.defaults`, and is used on every call as the merge base (mutating `instance.defaults` affects later calls on that instance and instances created via `extend` after the mutation).

## `FynFetchInstance`

```ts
interface FynFetchInstance {
  (url: string | URL, options?: FynFetchOptions): Promise<Response>;
  get / post / put / patch / delete / head(url, options?): Promise<Response>;
  json<T = any>(url, options?): Promise<T>;
  text(url, options?): Promise<string>;
  buffer(url, options?): Promise<Buffer>;
  arrayBuffer(url, options?): Promise<ArrayBuffer>;
  blob(url, options?): Promise<Blob>;
  stream(url, destination: string | NodeJS.WritableStream, options?): Promise<Response>;
  drain(res: Response | null | undefined): Promise<void>;
  create(defaultOptions?: FynFetchOptions): FynFetchInstance;
  extend(defaultOptions?: FynFetchOptions): FynFetchInstance;
  defaults: FynFetchOptions;
}
```

### Verb shortcuts

`get`, `post`, `put`, `patch`, `delete`, `head` call the instance with `{ ...options, method: "<VERB>" }`. The verb overrides any `options.method`. They return the `Response` and use the normal `throwOnHttpError` default (`false`).

`head` additionally calls `drain(res)` on the response before returning it, so the socket is released.

### Body shortcuts

`json`, `text`, `buffer`, `arrayBuffer`, `blob` call the instance, then read the body with `res.json()`, `res.text()`, `Buffer.from(await res.arrayBuffer())`, `res.arrayBuffer()`, `res.blob()`.

`throwOnHttpError` for these is `options.throwOnHttpError ?? instance.defaults.throwOnHttpError ?? true`. So the default is `true`, and an explicit `false` (call or instance default) disables it. With `false`, the body of a non-2xx response is read and returned. A body parse failure (for example invalid JSON in `json()`) rejects with the native error. These shortcuts have no extra retry or cleanup logic beyond the core call.

### `instance.stream(url, destination, options?)`

Same as the exported `stream` with instance defaults merged into `options` first. See `stream`.

### `instance.drain`

The exported `drain` function itself.

### `instance.create(opts?)`

Returns `createInstance(opts ?? {})`. Parent defaults are not inherited.

### `instance.extend(opts?)`

Returns `createInstance(mergeOptions(instance.defaults, opts))`. Child inherits parent defaults, merged per the rules below. The merged result is a snapshot at call time.

### Merging

Used for defaults + call options and for `extend`. Result starts as `{ ...base, ...override }` (override wins for scalar options, including `body`, `signal`, `timeout`, `throwOnHttpError`, `prefixUrl`, `json`, `form`, `username`, `password`). Special cases:

| Option | Merge rule |
| --- | --- |
| `headers` | Both normalized to a lowercase-keyed plain object (`Headers`, array of pairs, or record accepted; record values `undefined` or `null` are dropped; others stringified). Override replaces same-named header. |
| `searchParams` | Merged by key. Any key present in override removes all base values of that key, then override values are appended. Repeated keys within one init are kept. Result is a `URLSearchParams`. |
| `hooks` | Concatenated per hook type: base hooks first, then override hooks. Result always has all three arrays. |
| `cookies` | Shallow object merge, override wins. |
| `retry` | If both are objects: shallow merge `{ ...base, ...override }`. If override is a number, it replaces base. If override is an object and base is a number, override object wins (copy). Object values are always cloned so hooks mutating `options.retry` do not write into instance defaults. |

If only one side defines an option it is used as is.

## `FynFetchOptions`

```ts
interface FynFetchOptions extends Omit<RequestInit, "body"> {
  body?: RequestInit["body"] | NodeJS.ReadableStream | null;
  duplex?: "half";
  timeout?: number;
  retry?: number | RetryOptions;
  throwOnHttpError?: boolean;
  bodyFactory?: () => RequestInit["body"] | Promise<RequestInit["body"]>;
  prefixUrl?: string | URL;
  searchParams?: SearchParamsInit;
  json?: any;
  hooks?: FynFetchHooks;
  form?: Record<string, any> | URLSearchParams;
  username?: string;
  password?: string;
  cookies?: Record<string, string>;
}
```

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `body` | `RequestInit["body"] \| NodeJS.ReadableStream \| null` | none | Request body. Readable streams, web streams and async iterables count as streams (one-shot). |
| `duplex` | `"half"` | auto | Set to `"half"` automatically when the body is a stream and `duplex` is unset. |
| `timeout` | `number` (ms) | none (no timeout) | Per-attempt deadline covering headers and body read. Applies only when `> 0`. See Timeouts. |
| `retry` | `number \| RetryOptions` | none (no retry) | A number `n` is `{ retries: n }`. `undefined` or `0` disables retry. See Retry. |
| `throwOnHttpError` | `boolean` | `false` for the core call and verb shortcuts; `true` for body shortcuts; always `true` for `stream` | When true, a non-`ok` final response throws `HttpError`. |
| `bodyFactory` | `() => body \| Promise<body>` | none | Called to produce a fresh body. Required for retrying streaming bodies. See Retry. |
| `prefixUrl` | `string \| URL` | none | Prepended to a relative `url`. Ignored when `url` is a `URL` object or an absolute URL string. |
| `searchParams` | `SearchParamsInit` | none | Query params applied to the final URL. |
| `json` | `any` | none | If `!== undefined`, body becomes `JSON.stringify(json)`. Sets `content-type: application/json` and `accept: application/json` if absent. |
| `form` | `Record<string, any> \| URLSearchParams` | none | Body becomes URL-encoded. Sets `content-type: application/x-www-form-urlencoded` if absent. Record entries with `undefined`/`null` values are skipped; others are `String()`-ed. |
| `username` | `string` | none | If defined and no `authorization` header exists, sets `authorization: Basic base64(username:password)`. |
| `password` | `string` | `""` | Used only with `username`. |
| `cookies` | `Record<string, string>` | none | If no `cookie` header exists, sets `cookie: k=v; k2=v2`. Entries with `undefined`/`null` values are skipped. No cookie header is set when none remain. Values are not encoded. |
| `hooks` | `FynFetchHooks` | none | See Hooks. |

The options `prefixUrl`, `searchParams`, `json`, `form`, `username`, `password`, `cookies`, `timeout`, `retry`, `throwOnHttpError`, `bodyFactory`, `hooks` are stripped before the call to `fetch`; everything else is forwarded.

### Request building

Order: URL, headers, basic auth, cookies, JSON, form, duplex.

- Header names are lowercased. User-supplied `authorization`, `cookie`, `content-type`, `accept` are never overwritten.
- `json` with `body` throws `TypeError("Cannot provide both 'json' and 'body' options")`.
- `form` with `body` or `json` throws `TypeError("Cannot provide 'form' with 'body' or 'json' options")`.
- These `TypeError`s reject the returned promise. They are thrown after `beforeRequest` hooks run.

### URL building

- Input `URL` object: used as `toString()`; `prefixUrl` is ignored.
- Input string is absolute when it matches `^[a-zA-Z][a-zA-Z\d+\-.]*:\/\/`. `localhost:8080/x` is therefore treated as relative.
- Relative string with `prefixUrl`: leading slashes of the relative part are removed, the prefix path's trailing slashes are removed, and the two are joined with one `/`. A query in the relative part is appended to the prefix's own query params. A hash in the relative part replaces the prefix hash. An empty relative part returns the prefix as is. If the prefix is not parseable as a URL, plain string joining is used.
- Relative string without `prefixUrl`: passed unchanged to `fetch`, which will reject it.
- `searchParams` then override: every key present in `searchParams` removes same-named params already in the URL, then the new values are appended. If the URL cannot be parsed, params are appended to the string with `?` or `&`.

### `SearchParamsInit`

```ts
type SearchParamsInit =
  | string
  | URLSearchParams
  | Record<string, string | number | boolean | undefined | null>;
```

Record values `undefined` and `null` are skipped; others are `String()`-ed. A string is parsed with `URLSearchParams`.

## Timeouts

- `timeout` is per attempt, in ms. With retries the worst case is about `(retries + 1) x timeout` plus backoff.
- The timer starts before `fetch` and stays armed after headers arrive, so it also bounds the body read. On firing, the request is aborted with a `TimeoutError` as abort reason. A body read in progress rejects with that same error.
- The timer is `unref`ed and never keeps the process alive.
- It is cleared on network error, retry, and when `finalizeResponse` throws. It is not cleared when a response is returned to the caller; it fires later as a harmless abort of that response's body (if still unread).
- If `fetch` rejects because the timeout fired and the caller's own `signal` has not aborted, the rejection is replaced with a new `TimeoutError`.
- The caller's `signal` and the timeout controller are combined with `AbortSignal.any`. If the caller aborts, the error from `fetch` is thrown as is, and no retry occurs.
- `timeout` of `0`, negative or missing means no timeout.

## Retry

```ts
interface RetryOptions {
  retries?: number;
  minTimeout?: number;
  factor?: number;
  maxTimeout?: number;
  statusCodes?: number[];
  retryOn?: (err: Error | null, res: Response | null) => boolean;
}
```

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `retries` | `number` | `0` | Retry attempts after the first. Must be a non-negative integer, else `TypeError("'retry.retries' must be a non-negative integer, received <v>")`. Max attempts = `retries + 1`. |
| `minTimeout` | `number` (ms) | `500` | Base delay for the first retry. |
| `factor` | `number` | `2` | Delay multiplier per attempt. |
| `maxTimeout` | `number` (ms) | `10000` | Cap on the base delay. |
| `statusCodes` | `number[]` | `[408, 429, 500, 502, 503, 504]` | Statuses that trigger a retry under the default policy. |
| `retryOn` | `(err, res) => boolean` | none | Replaces the entire default policy, both `statusCodes` and the method restriction. Called with `(error, null)` after a thrown `fetch` error, or `(null, response)` after a response. Return `true` to retry. |

Rules:

- `retry` of `undefined` or `0` disables retry. `retry: {}` has `retries: 0`, so one attempt and no retries.
- Default policy: retry only idempotent methods: `GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS`, `TRACE` (method compared uppercased, missing method counts as `GET`). `POST` and `PATCH` are not retried by default. Opt in with `retryOn`.
- Default policy retries a thrown `fetch` error (network failure, per-attempt `TimeoutError`) for idempotent methods, and a response whose status is in `statusCodes` for idempotent methods.
- A caller-aborted `signal` is never retried. The abort error is thrown.
- No retry is attempted on the final attempt. The last response is then returned (and goes through `afterResponse` hooks and `throwOnHttpError`), or the last error is thrown.
- Delay before retry number `attempt` (1-based): `base = min(minTimeout * factor^(attempt-1), maxTimeout)`, then `delay = base + random() * base * 0.25`. So the delay is at most `1.25 x maxTimeout`.
- When a response is available and has a `Retry-After` header, `base = min(retryAfter, maxTimeout)` instead. `Retry-After` is parsed as numeric seconds, else as an HTTP date; unparseable values fall back to the exponential base. Negative results clamp to `0`. Not used after thrown errors.
- The backoff sleep listens to the caller's `signal`. Aborting during sleep rejects with `signal.reason` (or `Error("Aborted")`).
- Before retrying on a response, the response body is drained (`drain`) so the socket is released, then the timeout timer is cleared. `beforeRetry` hooks run after that, then the sleep. For a thrown error, `beforeRetry` runs, then the sleep.
- Streaming bodies: if `retries > 0` and the initial body is a stream (has `pipe`/`getReader`, or is an async iterable) and no `bodyFactory` is set, the call throws `TypeError("Cannot retry a request with a streaming body without 'bodyFactory'. Provide a 'bodyFactory' function or disable retries.")` before any request.
- `bodyFactory` is awaited for attempt 1 only when no `body` is set, and for every later attempt. A stream result gets `duplex: "half"` when unset.
- Options are re-prepared on each retry (`prepareRequest` re-run on the shared `options`), so `beforeRetry` mutations of `options` (for example headers) take effect on the next attempt. `beforeRequest` hooks do not run again.

## Hooks

```ts
interface FynFetchHooks {
  beforeRequest?: ((options: FynFetchOptions, url: string) => void | Response | Promise<void | Response>)[];
  beforeRetry?: ((context: BeforeRetryContext) => void | Promise<void>)[];
  afterResponse?: ((response: Response, options: FynFetchOptions) => Response | void | Promise<Response | void>)[];
}

interface BeforeRetryContext {
  error: Error | null;     // set when the attempt threw
  response: Response | null; // set when the attempt returned a retryable response (already drained)
  attempt: number;         // 1-based number of the attempt that just failed
  options: FynFetchOptions; // the merged options object, mutable
}
```

Each hook type is an array. Hooks run sequentially, awaited, in order (instance defaults first, then call hooks).

- `beforeRequest(options, url)`: runs once per call, before the first attempt. `url` is the fully resolved URL (`prefixUrl` and `searchParams` applied), recomputed per hook. The hook may mutate `options`. Returning a `Response` skips the network, skips remaining `beforeRequest` hooks, and that response goes through `afterResponse` hooks and `throwOnHttpError`. Other return values are ignored. A thrown error rejects the call.
- `beforeRetry(context)`: runs before each retry sleep. Errors thrown reject the call. `context.response` is already drained, so its body cannot be read.
- `afterResponse(response, options)`: runs on the final response (including short-circuit responses), not on retried ones. Returning a `Response` different from the current one drains the current one and replaces it for later hooks and the caller. If a hook throws, the current response is drained (errors ignored) and the error is rethrown.

After the hooks, if `throwOnHttpError` and `!response.ok`, `HttpError.fromResponse` is thrown.

## `HttpError`

```ts
class HttpError extends Error {
  readonly response: Response;
  readonly status: number;
  readonly statusText: string;
  readonly url: string;
  data?: any;
  constructor(response: Response, message?: string, data?: any);
  static fromResponse(response: Response, message?: string): Promise<HttpError>;
}
```

`name` is `"HttpError"`. Default message: `HTTP <status>[ <statusText>] for <url>`. `status`, `statusText`, `url` come from `response`. `data` is the parsed body, if any.

Thrown when `throwOnHttpError` is true and the final response is not `ok`, which includes all body shortcuts by default and `stream`. The constructor does not read the body.

`fromResponse(response, message?)`:

- If `response.bodyUsed` is false, reads `response.text()`. Read failures are swallowed (empty body).
- `data` is `JSON.parse(text)` when the `content-type` contains `application/json` (the raw text if parsing fails), else the raw text. If the body was already used, `data` is `undefined`.
- The error's `response` is a rebuilt `Response` with the same status, statusText and headers, minus `content-encoding` and `content-length`, with `url` defined to the original. Its `text()` returns the buffered text, `json()` returns `data` if it is an object else `JSON.parse(text)`, and `clone()` returns an equivalent rebuilt response. Statuses 204, 205, 304 get a null body.
- If `new Response` rejects the status (outside 200-599), the original response is used with `text`, `json` and `clone` patched.
- The original response body is consumed, so the socket is released.

## `TimeoutError`

```ts
class TimeoutError extends Error {
  readonly timeoutMs: number;
  constructor(timeoutMs: number, message?: string);
}
```

`name` is `"TimeoutError"`. Default message `Request timed out after <ms>ms`. The library throws it with the message `Request to <url> timed out after <ms>ms`. See Timeouts for when. It is retryable under the default policy for idempotent methods.

## `drain`

```ts
function drain(res: Response | null | undefined): Promise<void>
```

Cancels the unread response body so the connection returns to the pool. Rules:

- Resolves with no effect when `res` is nullish, has no body, or the body is already used.
- Throws `TypeError("Cannot drain a locked response body")` when the body stream is locked.
- Cancel errors from closed or aborted streams are suppressed.
- Safe to call more than once.

Call it when you do not read a response body (for example after checking only `status`). The library calls it itself on retried responses, replaced responses, and `head()`.

## `stream`

```ts
function stream(
  url: string | URL,
  destination: string | NodeJS.WritableStream,
  options?: FynFetchOptions
): Promise<Response>
```

Requests via the global `fynFetch` with `throwOnHttpError: true` forced (overrides the option), then pipes the body into `destination` with `stream/promises` `pipeline`. Resolves with the `Response` (body consumed) after the pipeline finishes.

- `destination` string: a file path opened with `fs.createWriteStream`. On a pipeline error the partial file is `unlink`ed (unlink errors ignored) and the error is rethrown.
- `destination` stream: used as is. `pipeline` ends it on completion and destroys it on error. It is not unlinked or otherwise cleaned up.
- No body: throws `Error("Response body is empty for <url>")`. The destination is not created.
- The `timeout` also bounds the body transfer; expiry rejects the pipeline with `TimeoutError`.
- `HttpError` and all other request errors propagate. The module-level `stream` does not apply instance defaults. Use `instance.stream`, which merges them first (hooks from the instance run via the merged options).
- `retry` applies to the request phase only. A failure during piping is not retried.

## Behavior not implemented by this package

There is no proxy, agent, or redirect logic in the source. `redirect`, `dispatcher` and any other `RequestInit` fields are forwarded to Node's global `fetch` unchanged, so their behavior is whatever core `fetch`/undici provides. No `Response` caching, no cookie jar (only the one-shot `cookies` option), and no automatic `Content-Length` handling.

<!-- filter-scan-dir v2.1.10: https://fynjs.pages.dev/ref/filter-scan-dir.md -->

# filter-scan-dir reference

`filter-scan-dir` recursively scans a directory and returns a flat array of matching paths, or a record of arrays when grouping is on. It has a sync and an async form, filter callbacks, ignore rules, and a concurrent async walker. It has no runtime dependencies. The package is ESM (`"type": "module"`) with a CJS shim.

## Imports

```js
// ESM
import { filterScanDir, filterScanDirSync } from "filter-scan-dir";
```

```js
// CJS
const filterScanDir = require("filter-scan-dir");
const { filterScanDirSync } = require("filter-scan-dir");
```

Runtime exports: `filterScanDir`, `filterScanDirSync`. The ESM build has exactly these two named exports. It has no default export and no subpaths (only `filter-scan-dir/package.json`).

The CJS entry (`index.cjs`) loads the ESM build with `require` and returns the `filterScanDir` function itself, with the module's named exports copied onto it. So `require("filter-scan-dir")` is callable, and `.filterScanDir` and `.filterScanDirSync` also exist on it. Node must support `require(esm)` (`engines` is `^22.22.2 || ^24.15.0 || >=26.0.0`).

Type-only exports: `Options`, `GroupingOptions`, `GroupingResult`, `FilterCallback`, `FilterResult`, `FilterInfo`, `ExtrasData`, `GitignoreParser`, `GitignoreMatcher`.

Not exported: the `GitignoreRules` class and the path helpers (internal).

## `filterScanDirSync` and `filterScanDir`

```ts
function filterScanDirSync(options?: string): string[];
function filterScanDirSync(options: GroupingOptions<true>): GroupingResult;
function filterScanDirSync(options: GroupingOptions<false>): GroupingResult;
function filterScanDirSync(options: GroupingOptions): GroupingResult;
function filterScanDirSync(options: Options<true>): string[];
function filterScanDirSync(options: Options<false>): string[];
function filterScanDirSync(options?: Options): string[];

function filterScanDir(options?: string): Promise<string[]>;
function filterScanDir(options: GroupingOptions<true>): Promise<GroupingResult>;
function filterScanDir(options: GroupingOptions<false>): Promise<GroupingResult>;
function filterScanDir(options: GroupingOptions): Promise<GroupingResult>;
function filterScanDir(options: Options<true>): Promise<string[]>;
function filterScanDir(options: Options<false>): Promise<string[]>;
function filterScanDir(options?: Options): Promise<string[]>;
```

Both walk the tree starting at `join(cwd, prefix)` and return the collected paths. The sync form blocks the event loop. The async form returns a promise and can read directories concurrently.

- `options` as a string is shorthand for `{ cwd: options }`.
- No argument means `{}`: scan `process.cwd()`.
- Return type is `GroupingResult` when `grouping: true` is in the options, otherwise `string[]`. At runtime any truthy `grouping` enables grouping; the types only accept `true`.
- The user's options object is not mutated. Options are copied over defaults with `Object.assign`.
- Options set explicitly to `undefined` override the default (see Quirks).
- `filterScanDir` calls option validation before it returns a promise, so an invalid option combination throws synchronously instead of rejecting.

### What gets scanned

- Each directory is read once. Non-directory entries are processed first, then subdirectories one by one, depth first.
- Entries are classified with `lstat` (or `Dirent` when `fullStat: false`). Symlinks are never followed, and a symlink to a directory counts as a non-directory entry.
- Non-directory entries (regular files, symlinks, sockets, and so on) go to `filter`. Directory entries go to `filterDir`. `filter` is never called for a directory and `filterDir` never for a file.
- The scan root itself is never reported or filtered. Only its entries are.
- With default options, symlinks are skipped before `filter` is called (see `includeSymlink`).

### Options

`Options<FullStat>` fields. All are optional.

| option | type | default | behavior |
| --- | --- | --- | --- |
| `cwd` | `string` | `process.cwd()` | Directory to scan. The legacy key `dir` is read as a fallback when `cwd` is falsy (not in the types). Unless `pathSep` is set as an own property, backslashes in `cwd` are replaced with `/`. |
| `prefix` | `string` | `""` | Sub-path scanned below `cwd`. The walk starts at `join(cwd, prefix)`. It appears in the returned paths (`dirFile`, `extras.path`) and in `fullFile`. Entries are not made relative to it. A trailing separator in `prefix` produces a doubled separator in results (`a//y.ts`). |
| `prependCwd` | `boolean` | `false` | Return `extras.fullFile` instead of `extras.dirFile`. The legacy key `includeRoot`, when present as an own property, takes precedence over `prependCwd` (even if `undefined`, which gives `false`). `includeRoot` is not in the types. |
| `sortFiles` | `boolean` | `false` | Sort the entries of each directory by name (plain `<`/`>` string comparison) before processing. Only sorts within one directory. Without it, order is whatever `readdir` returns. |
| `includeDir` | `boolean` | `false` | Add directory entries to the result, when `filterDir` accepts them and does not set `skip: true`. Also makes symlinks reach `filter` (see `includeSymlink`). Directory names have no trailing separator. |
| `includeSymlink` | `boolean` | `false` | A symlink entry (file or directory target) is skipped before `filter` unless `includeSymlink` is truthy or `includeDir` is truthy. Symlinks that pass are handled as non-directory entries and never descended. |
| `maxLevel` | `number` | `Infinity` | Zero-based depth limit for descending. `0` scans only the entries directly in the scan root: subdirectories are still passed to `filterDir` and can be listed with `includeDir`, but are not read. `1` also reads their children, and so on. |
| `fullStat` | `boolean` | `true` | `true`: call `fs.lstat` for each accepted entry, `extras.stat` is `fs.Stats`. `false`: use `readdir` `Dirent` objects as `extras.stat`, with no `lstat` calls. This is much faster, but there is no size, time or mode. |
| `concurrency` | `number` | `50` | Async only, ignored by the sync form. Maximum directories being read (`readdir` plus its `lstat` calls) at the same time. A directory waiting for its children does not hold a slot. Values `<= 1` (including `0`, negatives and `NaN`) walk serially. `Infinity` removes the limit. Also bounds how many child walks are started at once per directory. |
| `rethrowError` | `boolean` | `false` | Throw errors instead of swallowing them. See Errors. |
| `filter` | `FilterCallback` | none (accept all) | Called for each non-directory entry that passed early filtering. See Filter callback. |
| `filterDir` | `FilterCallback` | none (accept all) | Called for each directory entry that passed early filtering. Controls both listing (`includeDir`) and descending. |
| `ignoreDirs` | `string \| string[]` | none | Directory basenames to skip at every depth. Exact name match, not a path or glob. The skipped directory is not stat-ed, not passed to `filterDir`, not listed, and not read. Applies only to entries that `readdir` reports as directories, so a symlink named like an ignored dir is not matched. The scan root is not checked. |
| `gitignore` | `GitignoreParser` | none (disabled) | Parser factory that turns on `.gitignore` handling. See Gitignore. |
| `prefilter` | `(file: string, path: string, entry: Dirent) => boolean` | none | Synchronous check on the `Dirent` before `lstat`. Return a falsy value to drop the entry. Dropping a directory prunes its whole subtree. Called for files and directories. `path` is the same relative directory string as `extras.path`. Throws `TypeError("prefilter requires fullStat: true")` when `fullStat` is `false`. |
| `ignoreExt` | `string \| string[]` | none | Extensions to drop. Applied to non-directory entries only. |
| `filterExt` | `string \| string[]` | none | Keep only these extensions. Applied after `ignoreExt`, non-directory entries only. |
| `pathSep` | `string` | `"/"` (`path.posix.sep`) | Separator used to join `dirFile` and `fullFile`. See Quirks before changing it. An empty string falls back to `"/"`. |

`GroupingOptions<FullStat>` is `Options<FullStat>` plus `grouping: true`.

Type notes:

- `Options<false>` requires `fullStat: false` in the literal and gives callbacks a `Dirent` stat. `Options<true>` and the default `Options` give `Stats` or a union of both (the callback type is distributive over `boolean`).
- `FilterCallback<Stat>` is typed with `Stat` selected by `FullStat`, but the walkers choose the actual stat object at runtime from `fullStat`.

### Extension filters

- `ignoreExt` and `filterExt` accept a string or array. Each value is normalized: `"*.js"` becomes `".js"`, `"js"` becomes `".js"`, `".js"` stays. Empty or falsy values are dropped.
- An entry's extension is the text from the last `.` onward, when that `.` is not at index 0. `a.test.js` has `.js`. `.rc` and `noext` have the extension `""`.
- Comparison is exact and case sensitive.
- `ignoreExt` runs first. If `filterExt` is non-empty, entries whose extension is not listed are dropped. An entry with extension `""` is always dropped by a non-empty `filterExt`, because empty values are removed from the list. You cannot select extensionless or dotfile names with `filterExt`.
- Extension filters run on the `Dirent` name before `lstat`, so a rejected entry never calls `filter` and cannot raise an `lstat` error.

### Early filter order

For each entry, the checks run in this order and the first failing check drops it:

1. `ignoreDirs` (directories only)
2. `gitignore`
3. `prefilter`
4. `ignoreExt` and `filterExt` (non-directories only)
5. `lstat` (when `fullStat` is `true`)
6. symlink skip (non-directories only, see `includeSymlink`)
7. `filter` or `filterDir`

Steps 1 to 4 run only when at least one of `gitignore`, `prefilter`, `ignoreDirs`, `ignoreExt` or `filterExt` is set. In that case `readdir` is called with `withFileTypes: true`. `fullStat: false` also uses `withFileTypes`.

### Filter callback

```ts
type FilterCallback<Stat extends Dirent | Stats = Dirent | Stats> = (
  file: string,
  path: string,
  extras: ExtrasData<Stat>,
) => FilterResult;

type FilterResult = boolean | string | FilterInfo;

type FilterInfo = {
  group?: string;
  skip?: boolean;
  stop?: boolean;
  formatName?: string;
};

type ExtrasData<Stat extends Dirent | Stats = Dirent | Stats> = {
  file: string;
  path: string;
  stat: Stat;
  fullFile: string;
  dirFile: string;
  ext: string;
  noExt: string;
  files: (string | Dirent)[];
};
```

Arguments:

- `file`: entry name.
- `path`: directory that contains the entry, relative to `cwd`, joined with `pathSep`, and starting with `prefix`. It is `""` for entries in the root when `prefix` is empty.

`ExtrasData` fields:

| field | value |
| --- | --- |
| `file` | entry name |
| `path` | same as the second argument |
| `stat` | `fs.Stats` from `lstat` when `fullStat` is `true`, else the `Dirent` |
| `fullFile` | `join(cwd, path)` (normalized by `path.join`) joined with `file` by `pathSep`. It is relative if `cwd` is relative. |
| `dirFile` | `path` joined with `file`. If `path` is `""` or `"."`, it is `file`. |
| `ext` | from the last `.` (kept) when that `.` is not at index 0, else `""` |
| `noExt` | `file` without `ext` |
| `files` | the names in the directory. With `fullStat: false`, these are the `Dirent` objects. With `fullStat: true` they are strings. |

`files` holds all entries in the directory, including ones rejected by early filters. It is sorted when `sortFiles` is set. The callbacks must treat it as read-only because it is shared.

Return values:

| return | effect |
| --- | --- |
| `false`, `undefined`, `null`, `0`, `""` (any falsy) | Skip the entry. A skipped directory is not listed and not descended. |
| `true` | Accept. The entry goes to the `files` group. A directory is also descended. |
| non-empty `string` | With `grouping` on, accept and put the entry in the group with that name. With `grouping` off, accept into the plain result as with `true`. |
| object (`FilterInfo`) | Any object is truthy so it accepts the entry unless `skip === true`. See below. |
| any other truthy value | Accepted like `true`. |

`FilterInfo` fields, read only from object returns:

- `skip`: only the exact value `true` skips. For a file, skip means not added. For a directory, skip means not added and not descended (a directory with `skip: true` is never read). Returning a falsy `skip` or none adds the entry.
- `stop`: when `true`, halts the whole scan. The entry that returned `stop` is still added unless `skip: true` is also set. Sync scans stop at once. Async scans stop starting new work. Reads already in flight finish, but no entry is added after the stop flag is set. Result so far is returned (not an error).
- `group`: group name for the entry. It is honored for objects even when `grouping` is off (see Quirks).
- `formatName`: when not `undefined`, this string is added to the result instead of `dirFile` or `fullFile`. `prependCwd` is ignored for that entry. An empty string is accepted.

Callback rules:

- Callbacks are called synchronously and their return value is not awaited. A function returning a Promise returns a truthy object, so everything is accepted (see Quirks).
- Directories are passed to `filterDir` after all non-directory entries of the same parent were processed. A directory's entries are processed only after `filterDir` returns for it.
- `filter` and `filterDir` return values are not required to be a `FilterInfo`. `boolean` and `string` are enough.

### Result

- Without grouping: `string[]`. Empty array when nothing matches or when an error was swallowed.
- With grouping: `GroupingResult`.

```ts
type GroupingResult = { files: string[] } & Record<string, string[]>;
```

The `files` array is always present, and holds entries with no group (a `true` return, no `group`, or `""`). Other group keys exist only when at least one entry was added to them. A group named `files` merges with the default group. The returned object is a plain object (a copy of the internal null-prototype record).

Each entry is one of: `dirFile` (default), `fullFile` (`prependCwd`), or `formatName`. Directories are added as the same kind of string, without a trailing separator, when `includeDir` is true.

Without grouping, the result is the `files` group only. Any entry placed in another group by a `{ group }` object is dropped from the output.

### Ordering

- Sync scan, and async with `concurrency <= 1`: deterministic for a given `readdir` order. Within a directory, non-directory entries come first, in `readdir` order (name order with `sortFiles`). Then each subdirectory: the directory entry itself (if `includeDir`), followed by everything inside it (depth first), before the next sibling directory.
- `readdir` order is the file system's order. It is not guaranteed to be sorted without `sortFiles`.
- `sortFiles` sorts each directory separately. It does not sort the final array.
- Async with `concurrency > 1`: sibling subdirectories are read concurrently, so entries from different directories can interleave. Order across directories is not deterministic. Sort the result yourself if you need stable output.

### Symlinks

- Never followed. `lstat` or `Dirent` reports a symlink as a symlink, so a link to a directory is not descended even with `includeDir`.
- By default (`includeDir` and `includeSymlink` both falsy), every symlink is skipped before `filter`: links to files as well as links to directories.
- When `includeSymlink` or `includeDir` is true, symlinks are passed to `filter` as ordinary entries. A returned symlink to a directory is reported as a file entry.
- Dangling symlinks are not an error. With `fullStat: true`, `lstat` reads the link itself.

### Gitignore

```ts
type GitignoreMatcher = {
  test(path: string): { ignored: boolean; unignored: boolean };
};
type GitignoreParser = (contents: string) => GitignoreMatcher;
```

The package bundles no parser. `gitignore` is a function that receives the text of one `.gitignore` file and returns a matcher. `matcher.test(p)` gets a POSIX path (`/` separated) relative to the directory of that `.gitignore`, with a trailing `/` for directories. It returns `{ ignored, unignored }`. Both should be `false` when no pattern matches. The result shape matches the object returned by `ignore().add(contents).test(p)` from the `ignore` package, so `gitignore: contents => ignore().add(contents)` works.

Rules:

- Disabled when `gitignore` is not set. Nothing is read.
- At the scan root (`join(cwd, prefix)`, resolved to absolute), the loader walks up looking for a directory that contains `.git` (file or directory, tested with `existsSync`). It loads `.gitignore` from that directory down to the scan root, outermost first. If no `.git` is found up to the filesystem root, only the scan root's own `.gitignore` is loaded.
- Each visited subdirectory then adds its own `.gitignore` after its parent's rules.
- A missing `.gitignore` (`ENOENT`) or a path component that is a file (`ENOTDIR`) is ignored. Any other read error (for example `EISDIR`, `EACCES`) and any error thrown by the parser follow the `rethrowError` rules.
- Rules are applied in order, later ones override earlier ones. A match with `ignored: true` ignores the entry. A match with `unignored: true` re-includes it. If a scan root is itself ignored by an ancestor's rules, the rule set restarts at that root, so the scan can proceed inside an ignored tree.
- Ignored directories are pruned, so their children are never read. A `.gitignore` is not consulted for a pruned directory, so negations cannot re-include a file under an ignored directory (only the matcher rules decide).
- `.git` is not excluded automatically. Use `ignoreDirs: ".git"`.
- Git's index, `.git/info/exclude` and global excludes are not read.
- Works in sync and async scans and with either `fullStat` mode. Each `.gitignore` is read with `readFileSync` or `fs.promises.readFile` to match the scan type.
- Symlinks to directories are tested as non-directories (no trailing `/`), because the `Dirent` is not a directory.

### Errors

Defaults swallow errors. Any error inside one directory's processing (`readdir`, `lstat`, a `.gitignore` read or parse, or a callback throw) aborts the rest of that directory: its remaining entries and subdirectories are not processed. Entries added before the error stay in the result. Other directories continue.

A missing `cwd` or `prefix` returns an empty result.

With `rethrowError: true`:

- Sync: the first error propagates out of `filterScanDirSync` unchanged. Partial results are lost.
- Async: the first error is recorded and the scan stops. In-flight directories finish, then the returned promise rejects with the original error. Later errors are dropped.

Never swallowed, regardless of `rethrowError`:

- `prefilter` with `fullStat: false` throws `TypeError("prefilter requires fullStat: true")` from both functions before any scanning. The async form throws synchronously rather than returning a rejected promise.
- Errors reading options (for example a getter that throws) also throw directly.

`stop: true` is not an error and returns the partial result.

### Quirks

Each of these follows from the code as written.

- **Explicit `undefined` options override defaults.** `Object.assign` copies own keys that are `undefined`.
  - `{ maxLevel: undefined }` never descends: `level < undefined` is false, so only root entries are listed.
  - `{ concurrency: undefined }` walks serially, as `undefined > 1` is false.
  - `{ prefix: undefined }` makes `path.join` throw inside the walk. Without `rethrowError` the error is swallowed and the result is empty. With it, the `TypeError` is thrown.
  - `{ fullStat: undefined }` is safe: it is normalized to `true`.
- **`pathSep` other than the platform separator breaks scanning on POSIX.** `fullFile` is built with `pathSep` and passed to `lstat`, so `pathSep: "|"` with `fullStat: true` makes every `lstat` fail (swallowed, empty result). Nested directory paths are also built with `pathSep` and read again with `path.join`, so with `fullStat: false` recursion stops after depth 1.
- **Object `group` without `grouping`.** `filter: () => ({ group: "g" })` without `grouping: true` returns `[]`: the entries are stored in group `g` and the result only returns `files`.
- **Async callbacks.** `filter: async () => false` accepts every entry, since a Promise is a truthy object with no `skip`.
- **Trailing separator.** `cwd: "t/"` with `prependCwd: true` gives `t//.rc`. `prefix: "a/"` gives `a//y.ts`.
- **`filterExt` cannot select extensionless or dotfile names.** `filterExt: ".rc"` does not match a file named `.rc`.

### Examples

```js
// recursive, sorted, with groups
const r = filterScanDirSync({
  cwd: "src",
  sortFiles: true,
  grouping: true,
  filter: (file, path, { ext }) => (ext === ".ts" ? "ts" : ext === ".js" ? "js" : false),
});
// r = { files: [], ts: [...], js: [...] }
```

```js
// fast scan: Dirent only, skip noisy dirs, async
const files = await filterScanDir({
  cwd: ".",
  fullStat: false,
  ignoreDirs: ["node_modules", ".git"],
  filterExt: [".js", ".ts"],
});
```

```js
// stop at the first match
const found = filterScanDirSync({
  cwd: ".",
  filter: (file) => (file === "package.json" ? { stop: true } : false),
});
```

<!-- munchy v2.0.7: https://fynjs.pages.dev/ref/munchy.md -->

# munchy reference

`munchy` is a producer Node `Readable` stream. You hand it a queue of mixed sources (strings, buffers, streams, iterables, promises) and it emits them as one ordered stream. ESM only (`"type": "module"`), no runtime dependencies. Requires Node `^22.22.2 || ^24.15.0 || >=26.0.0`.

## Imports

```js
import { Munchy } from "munchy";
import Munchy from "munchy"; // default export, same class
```

```ts
import { Munchy, type MunchyOptions, type MunchySource, type StreamErrorResult } from "munchy";
```

Runtime exports: `Munchy` (named) and `default` (the same class).

Type-only exports: `MunchyOptions`, `MunchySource`, `StreamErrorResult`.

Not exported: the helpers `isPlainOptions`, `isStreamLike` and `streamToAsyncIter`. There are no subpaths (only `munchy/package.json`).

## `Munchy`

```ts
class Munchy extends Readable {
  constructor(opts?: MunchyOptions | MunchySource, ...sources: MunchySource[]);
  munch(...sources: MunchySource[]): this;
  destroy(err?: Error): this;
}
```

`Munchy` extends `node:stream` `Readable`. Every inherited `Readable` API works (`pipe`, `on("data")`, `read`, `resume`, `pause`, `for await`, `Readable.prototype.destroy` semantics, `highWaterMark`, `objectMode`, `encoding`). Only the members below are Munchy specific.

### Core model

- Sources are queued in order and processed one at a time, strictly in queue order. A stream source is fully drained before the next source starts. Streams are never read concurrently.
- Nothing is read until the first `_read` call, which happens when a consumer attaches (`pipe`, `on("data")`, `resume`, `read`, `for await`). Constructing and calling `munch()` before that only queues sources.
- The stream does not end by itself. When the queue is empty it parks and waits for more `munch()` calls. Only a `null` source ends it (see `null` below). `pipe(dest)` therefore never calls `dest.end()` unless `null` is munched.
- Backpressure: after each `push`, if `push` returns `false`, the read loop parks until the consumer calls `_read` again. Streams being drained are paused while Munchy is parked (see Node `Readable` sources below). Items from a single sync iterable are pushed one at a time with the same check.
- `autoDestroy` (the Node default) applies: after `end`, Node calls `destroy()`, then `close` is emitted.

### Constructor

```ts
new Munchy(opts?: MunchyOptions | MunchySource, ...sources: MunchySource[])
```

Argument handling, in order:

1. `opts` is `null` or `undefined`: no options. All remaining arguments are sources. `null` here is NOT an end-of-stream source.
2. `opts` is a "plain options" object: it is the options, and `sources` are the sources.
3. Anything else: `opts` is the first source, and the sources are `[opts, ...sources]`.

An object counts as plain options only if it is non-null, `typeof` is `"object"`, it is not a `Uint8Array`, and it has none of: a `pipe` function, a `Symbol.asyncIterator` function, a `Symbol.iterator` function, a `then` function. Consequences:

- Strings, numbers, functions, arrays, `Buffer`, streams, promises and iterables passed first are sources.
- A plain object (such as `{ a: 1 }`) passed first is read as options, not as a source. To use such an object as an `objectMode` source, pass `{}` (or `null`) as the first argument, or `munch()` it later.
- `new Munchy({}, ...)` is the way to pass no options and keep a plain-object source later in the list.

Options are passed whole to the `Readable` constructor, so every `ReadableOptions` field applies. `handleStreamError` is extra and is ignored by `Readable`. If `sources` is non-empty they are queued with `munch()`.

#### `MunchyOptions`

```ts
type MunchyOptions = ReadableOptions & {
  handleStreamError?: (err: any) => StreamErrorResult | void | undefined | null;
};
```

| option | type | default | behavior |
| --- | --- | --- | --- |
| any `ReadableOptions` field | see Node docs | Node defaults | Forwarded to `Readable`. Includes `objectMode`, `highWaterMark`, `encoding`, `signal`, `autoDestroy`. |
| `handleStreamError` | `(err) => StreamErrorResult \| void \| null \| undefined` | `undefined` | Called when a source fails. See Error handling. |

Caveat: a `read` function in the options replaces `_read` on the instance (Node `Readable` behavior). Munchy would then never pull from its sources. Do not pass `read`.

#### `StreamErrorResult`

```ts
type StreamErrorResult = {
  result?: any;
  remit?: boolean;
};
```

| field | type | default | behavior |
| --- | --- | --- | --- |
| `result` | any | none | If truthy, pushed to the output before anything else. A falsy value (`""`, `0`) is not pushed. In non-object mode it must be a string or `Uint8Array`, otherwise `push` itself errors. |
| `remit` | boolean | see below | `false` means swallow the error and keep going. Any other value (including absent) re-emits the error and destroys. |

#### `MunchySource`

```ts
type MunchySource = string | Uint8Array | Readable | AsyncIterable<any> | Iterable<any> | Promise<any> | null | any;
```

Because of the trailing `any`, the type accepts everything. The runtime rules are in the next section.

### Source kinds

Each source is taken from the queue and handled by the first matching rule. A source that is a thenable (`then` is a function) is awaited first, and the resolved value is then matched against the rules. The resolved value is not re-awaited, so a promise resolving to a promise is pushed as is.

| order | source (after awaiting) | behavior |
| --- | --- | --- |
| 0 | `null` (queued directly, not from a promise) | Ends the stream. See `null`. |
| 1 | `string`, `Uint8Array` (so also `Buffer`) | Pushed as one chunk. |
| 2 | has `getReader` function (Web `ReadableStream`) | Converted with `Readable.fromWeb`, then handled as rule 3. |
| 3 | object with `pipe` function, or `Symbol.asyncIterator` function, or `getReader` function | Drained. See below. |
| 4 | has a `Symbol.iterator` function (arrays, `Set`, generators, `Map`) | Each item is pushed in order. |
| 5 | anything else | Pushed as is. |

Notes by kind:

- Strings and buffers: pushed unchanged. In non-object mode `Readable` converts a string to a `Buffer` unless `encoding` or `decodeStrings` says otherwise. An empty string pushes nothing observable and does not end the stream.
- Node `Readable` and other `pipe` sources (rule 3 with `pipe`): Munchy attaches `data`, `error` and `end` listeners and queues chunks. On every chunk it calls `pause()` (if the source has `pause` and `resume`), and calls `resume()` only when its internal queue is empty and it is ready for more. This is how backpressure reaches the source. Listeners are removed when draining stops. The source is switched into flowing mode, so do not read it elsewhere.
- Async iterables without `pipe` (async generators, objects with only `Symbol.asyncIterator`): iterated with `for await`, one value per `push`. Backpressure is natural (the next value is not requested while parked).
- Web `ReadableStream`: converted to a Node `Readable` and drained like one. The `draining` and `drained` payload `stream` is the converted Node `Readable`, not the original web stream. `Readable.fromWeb` throws on a locked stream (see Error handling).
- Sync iterables: iterated with `for...of`. Items are not recursed into, so an array of arrays pushes arrays. A `Uint16Array` or similar is iterable and pushes numbers, which errors in non-object mode (`Uint8Array` is handled earlier as a chunk). Strings never reach this rule.
- Fallback (rule 5): numbers, plain objects, functions and so on are pushed as is. In non-object mode a number or object makes `push` raise a Node `ERR_INVALID_ARG_TYPE` error. In `objectMode` they are emitted as items.
- Promises: awaited at the time the read loop reaches them, not at `munch()` time. A rejection goes through Error handling, with no `draining` or `drained` events.

#### `null`

A `null` source at the head of the queue ends the stream. Munchy calls `push(null)`, discards every source queued after it, resets the queue (emitting `munched`) and stops the read loop. `end` fires once the consumer drains the buffered data, then `close` via `autoDestroy`.

Edge cases:

- `new Munchy(null, ...)` and `new Munchy(undefined, ...)` treat the first argument as "no options", not as a source.
- A promise that resolves to `null` also calls `push(null)` (rule 5), which ends the stream. Unlike a queued `null`, the read loop continues and sources after it are not delivered. Prefer a queued `null`.
- An iterable or async iterable that yields `null` also ends the stream through `push(null)`, with the same loop continuation (see Quirks).
- `undefined` as a source pushes `undefined`. In default non-object mode Node ignores it, so nothing is emitted and the stream continues. It does not end the stream.

### `munch(...sources)`

```ts
munch(...sources: MunchySource[]): this
```

Appends sources to the queue and returns `this` (chainable). Safe to call at any time: before reading starts, while draining, or when parked on an empty queue (which wakes the read loop). `munch()` with no arguments does nothing useful.

If reading has started and there is more to do, a read is scheduled with `process.nextTick`.

Calls after the stream has been destroyed (including after normal end, because of `autoDestroy`) schedule a read that emits `error` with message `munchy _read called after destroy`. If no `error` listener is attached, that is an uncaught exception. Do not `munch()` after `null`/end.

Calling `munch()` while the stream is backpressured releases the park once, so one more chunk may be pushed past `highWaterMark`. Backpressure resumes right after.

### `destroy(err?)`

```ts
destroy(err?: Error): this
```

Overrides `Readable.destroy`. In order: clears the pending queue (emits `munched` if at least one source had already been consumed, see Events), wakes any parked loop so it exits, calls `destroy()` on the source currently being drained (if it has a `destroy` method; exceptions are swallowed), then calls `super.destroy(err)`. Returns `this`. Remaining queued sources are dropped, never processed. It is idempotent in the usual `Readable` way.

When the current source is an event stream and is destroyed without an error, it emits `close` but not `end`, and no `drained` event is emitted for it.

### Events

All `Readable` events (`data`, `end`, `error`, `close`, `readable`, `pause`, `resume`) behave as in Node. Munchy adds three:

| event | payload | when |
| --- | --- | --- |
| `draining` | `{ stream }` | Just before a stream source (Node stream, async iterable, or converted web stream) starts draining. |
| `drained` | `{ stream }` | After that source ends normally, or after its error was recovered by `handleStreamError` (`remit: false`). Not emitted when the error is re-emitted, nor on destroy. |
| `munched` | none | When the queue has been reset after at least one source was consumed. That is when all queued sources are done and Munchy is idle waiting for more (can fire repeatedly), after a `null` ends the stream, and on `destroy()` if queued sources remained. |

`draining` and `drained` fire for stream-like sources only, never for strings, buffers, promises of plain values, or sync iterables. `munched` is emitted synchronously, so a `munch()` called from its handler is picked up.

### Error handling

Failures of two kinds go through `handleStreamError`: a rejected promise source, and an error thrown or emitted by a stream-like source (Node stream `error` event, async iterator throwing, web stream error). If the error value is falsy it is replaced by `new Error("munchy - source stream emitted error")`.

Algorithm:

1. Call `handleStreamError(err)` if set. A falsy return is treated as `{}`.
2. `remit` is `true` when there is no handler, or when `remit !== false`.
3. If `result` is truthy it is pushed. If that push signals backpressure and `remit` is false, Munchy waits for the consumer before continuing.
4. If `remit` is true: emit `error` with the original error, call `destroy()` and stop. Any pushed `result` is still delivered before the error.
5. If `remit` is false: continue with the next source. If the failed source was a stream, `drained` is emitted for it.

So with no handler, or a handler that returns nothing, the first source failure emits `error` and destroys. Only `{ remit: false }` recovers.

```js
const m = new Munchy({
  handleStreamError: err => ({ result: `[failed: ${err.message}]`, remit: false })
});
m.munch(Promise.reject(new Error("x")), "after", null);
// output: "[failed: x]" then "after"
```

Errors that bypass `handleStreamError`:

- An exception thrown by the handler itself.
- An exception thrown while iterating a sync iterable.
- `Readable.fromWeb` failing (such as a locked web stream).
- Errors from `push` itself (such as a number pushed in non-object mode).

For these the read loop rejects, Munchy emits `error` with the exception and calls `destroy()`. Because the read loop is released before the error is emitted, a consumer that keeps reading may start a new loop first and still receive later queued data, even `end`, before `error` arrives. Treat `error` as terminal and ignore data after it.

The `error` event is emitted manually (`emit("error")` then `destroy()`), not through `destroy(err)`. A listener must be attached or Node throws the error as uncaught.

### Quirks

- A stream source that already ended, or was destroyed without an error, before Munchy attaches never emits `end` or `error` to Munchy. Draining then waits forever, and later queued sources are never reached. Pass streams that are still live.
- Promises queued behind a long source are not awaited until reached. A promise that rejects before then triggers Node's `unhandledRejection` even though Munchy would later handle it.
- A queued `null` ends the stream cleanly. A `null` pushed by a promise or iterable ends the stream but leaves the loop running, so later queued sources are pushed after EOF and are dropped.
- `munch()` after end or destroy emits `error` (`munchy _read called after destroy`).
- A plain object as the first constructor argument is options, not a source.
- Public typings expose internal fields `_sources`, `_index`, `_started`, `_reading`, `_canPush`, `_triggered`, `_handleStreamError` and methods `_moreSources`, `_resetSources`, `_triggerRead`, `_read`. They are internals. Do not rely on them.

<!-- @fynjs/reflink v0.1.0: https://fynjs.pages.dev/ref/reflink.md -->

# @fynjs/reflink reference

`@fynjs/reflink` is a native Node addon (Rust, napi-rs) that places files with copy-on-write clones. fyn uses it to replicate packages from its store into `node_modules`. ESM only (`"type": "module"`). Requires Node `^22.22.2 || ^24.15.0 || >=26.0.0` (`engines`).

## Imports

```js
import { cloneFile, cloneFileSync, cloneFiles, cloneFilesSync, cloneDir } from "@fynjs/reflink";
import * as reflink from "@fynjs/reflink";
```

All exports are named exports from the package root. There is no default export. Subpaths: only `@fynjs/reflink/package.json`.

Runtime exports: `cloneFile`, `cloneFileSync`, `cloneFiles`, `cloneFilesSync`, `cloneDir`, `__napiBindingTarget`.

Type-only export: `CloneStats`.

There is no `cloneDirSync`. `__napiBindingTarget` is loader metadata, see "Binary selection".

Importing the package loads the native binding at import time. If no binding can be loaded, the import throws (see "Binary selection").

## Placement algorithm

Used by `cloneFile`, `cloneFileSync`, `cloneFiles` and `cloneFilesSync`. Per file, in order:

1. Remove `dest` (`fs::remove_file`). `NotFound` is ignored. Any other error is returned (for example removing a directory fails).
2. Try a reflink (crate `reflink-copy` 0.1.30, see "Platform mechanisms"). This step is skipped only when copy fallback is on and an earlier reflink in the same call already failed (see below).
3. If hardlink is on, `fs::hard_link(src, dest)`. A hardlink failure is swallowed, and placement continues.
4. If copy fallback is on, `fs::copy(src, dest)`. Otherwise the reflink error is returned.

Step 1 exists because clone and copy write through an existing destination, which would corrupt other paths hardlinked to the same inode. Each placement result is one of cloned, linked or copied.

Per-call "reflink disabled" flag: the first failed reflink in a call clears a shared flag. With copy fallback on, later files in that call skip the reflink attempt and go to hardlink or copy. With copy fallback off, every file still tries the reflink. The flag lives for one call only. It is not shared across calls.

Source symlinks: `reflink-copy` on macOS calls `clonefile` without `CLONE_NOFOLLOW` for files, so a symlink `src` is followed and `dest` becomes a regular file (observed on macOS). The same call falls back to `fs::copy`, which also follows symlinks.

## `cloneFileSync(src, dest)` and `cloneFile(src, dest)`

```ts
function cloneFileSync(src: string, dest: string): boolean
function cloneFile(src: string, dest: string): Promise<boolean>
```

Places one file with hardlink off and copy fallback on. Returns `true` when the file was cloned, `false` when it was copied.

- `dest` is removed first, then replaced.
- The parent directory of `dest` is not created. A missing parent fails with `No such file or directory (os error 2)`.
- `cloneFile` runs on the libuv thread pool (`AsyncTask`). `cloneFileSync` blocks the calling thread.
- Throws or rejects with a `GenericFailure` error on failure (see "Errors").
- Passing a non-string argument throws `StringExpected`.
- When `src` and `dest` are the same path, `dest` (which is `src`) is removed first, then the clone fails, so the source file is deleted. Observed: `cloneFile(p, p)` rejects with ENOENT and `p` no longer exists.
- On macOS a directory `src` is cloned as a tree by `clonefile`, and the call returns `true` (observed). On Linux and Windows a non-regular-file `src` fails the reflink with `InvalidInput` ("the source path is not an existing regular file"), then falls back to `fs::copy`, which also fails.

## `cloneFilesSync(...)` and `cloneFiles(...)`

```ts
function cloneFilesSync(
  srcDir: string,
  destDir: string,
  files: Array<string>,
  hardlink?: boolean | null,
  copyFallback?: boolean | null
): CloneStats

function cloneFiles(
  srcDir: string,
  destDir: string,
  files: Array<string>,
  hardlink?: boolean | null,
  copyFallback?: boolean | null
): Promise<CloneStats>

interface CloneStats {
  cloned: number;  // placed with a copy-on-write clone
  linked: number;  // hardlinked because a clone was not possible
  copied: number;  // fell back to a full copy
}
```

Places each entry of `files` from `srcDir/<file>` to `destDir/<file>`, in parallel.

| argument | type | default | behavior |
| --- | --- | --- | --- |
| `srcDir` | `string` | required | Base directory for sources. |
| `destDir` | `string` | required | Base directory for destinations. |
| `files` | `string[]` | required | Paths relative to both directories, joined with `Path::join`. An empty array returns `{cloned:0, linked:0, copied:0}` and creates nothing. |
| `hardlink` | `boolean \| null \| undefined` | `false` | Hardlink a file that could not be cloned. Positional argument, not an option object. `null` and `undefined` both mean `false`. |
| `copyFallback` | `boolean \| null \| undefined` | `true` | `false` makes a file that cannot be cloned or hardlinked fail with the reflink error instead of copying. `null` and `undefined` both mean `true`. |

Behavior:

- Parent directories of every destination are collected into a set and created with `create_dir_all` before any file is placed. This phase is sequential. If it fails, the error names only the directory (`mkdir <dir>`).
- Placement then runs in parallel on a pool owned by the addon (rayon). Pool size is `min(available_parallelism, 4)`, threads named `reflink-<i>`. The pool is created lazily on first use and lives for the process.
- Fails on the first error. Files already placed before the failure are left in place. The returned error is the first one the parallel reduction surfaces. Which file reports first is not deterministic.
- The three counters sum to `files.length` on success.
- `cloneFilesSync` blocks the calling thread until the pool finishes (`pool.install`). `cloneFiles` returns a promise, uses the same pool (`pool.spawn`) and never occupies a libuv thread.
- Non-array `files` throws `ArrayExpected`. Non-string elements or arguments throw a conversion error such as `StringExpected`.
- Mode: on Linux the crate copies the source permissions to the new file. On macOS `clonefile` keeps the mode (the test suite checks `0o755` survives for `cloneFile` and `cloneDir`).

Path safety: entries are joined without any check. An absolute entry, or one containing `..`, can resolve `dest` outside `destDir`, including onto the source file itself. Step 1 of the placement algorithm then deletes that file. Pass only trusted, normalized relative paths.

Duplicate entries in `files` are placed concurrently onto the same destination. The call can succeed, with an unreliable cloned versus copied split (observed with 8 copies of the same name: `{cloned:1, copied:7}`).

## `cloneDir(src, dest)`

```ts
function cloneDir(src: string, dest: string): Promise<boolean>
```

Clones the directory `src` to `dest` with one `clonefile(2)` call. APFS clones the tree in the kernel, so there are no per-file syscalls. Async only. Runs on the addon pool.

- macOS: calls `clonefile(src, dest, CLONE_NOFOLLOW)` (flag `0x0001`, defined locally). The flag means a symlink passed as `src` is itself cloned, not followed.
- `dest` must not exist and its parent must exist. Nothing is created or removed for you.
- Resolves `true` when cloned.
- Resolves `false` when `clonefile` fails with `ENOTSUP` or `EXDEV` (a filesystem that cannot clone, or `src` and `dest` on different volumes). No fallback is done here. The caller should fall back to `cloneFiles`.
- Any other `clonefile` error rejects. Examples observed: `dest` exists gives `File exists (os error 17)`, missing `src` or missing parent of `dest` gives `No such file or directory (os error 2)`. A `src` that is a regular file is cloned, since `clonefile` accepts files.
- A path containing a NUL byte rejects with `file name contained an unexpected NUL byte`.
- Linux and Windows: the function body is a stub. It always resolves `false` without touching the filesystem and without validating arguments.
- Does not use hardlinks or copy, and returns no `CloneStats`.

```js
if (!(await cloneDir(storeDir, destDir))) {
  await cloneFiles(storeDir, destDir, relativeFiles);
}
```

## `__napiBindingTarget`

```ts
const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
```

Reports which artifact the loader loaded. `'native'` for a native `.node` addon, otherwise the WASI flavor. This package builds no WASI artifact (`napi.targets` has none), so it is `'native'` in normal use.

## Errors

Every failure from the Rust side is a Node `Error` with `code` `GenericFailure`. The message is built as:

```
<io error text>: <target> (<errno or ErrorKind>)
```

- `<target>` is `src -> dest` for placement and `cloneDir`, or `mkdir <dir>` for the parent-creation phase of `cloneFiles` and `cloneFilesSync`.
- `<errno or ErrorKind>` is the raw OS error number when there is one, otherwise the Rust `ErrorKind` name, for example `InvalidInput`.
- Example: `No such file or directory (os error 2): /a/src -> /a/dest (2)`.

Argument type errors have their own codes (`StringExpected`, `ArrayExpected`).

When cloning is unsupported or fails on a file:

| call | result |
| --- | --- |
| `cloneFile`, `cloneFileSync` | Silent copy fallback. Return value `false`. Error only if the copy fails too. |
| `cloneFiles`, `cloneFilesSync`, copy fallback on (default) | Hardlink if `hardlink`, else copy. Counted in `linked` or `copied`. No error. |
| `cloneFiles`, `cloneFilesSync`, `copyFallback: false` | The reflink error is thrown (or the call rejects) for the first file that cannot be cloned or hardlinked. |
| `cloneDir` on macOS | Resolves `false` for `ENOTSUP` or `EXDEV`, rejects otherwise. |
| `cloneDir` off macOS | Always resolves `false`. |

A missing `src` is not reported as a clone failure. It is a copy failure (`ENOENT`) when copy fallback is on, or the reflink `ENOENT` when it is off.

## Platform mechanisms

The file clone is `reflink_copy::reflink` from crate `reflink-copy` 0.1.30 (`Cargo.lock`). The `src` and `dest` filesystem must support block sharing, and both must normally be on the same filesystem.

| OS | Mechanism | Filesystems | Notes |
| --- | --- | --- | --- |
| macOS | `clonefile(2)` with `CLONE_NOOWNERCOPY` | APFS | Directories and symlinks are accepted by `clonefile`. Fails with ENOTSUP on non-APFS volumes. Works as `cloneDir` with `CLONE_NOFOLLOW`. |
| Linux (and Android) | `ioctl(FICLONE)` through `rustix::fs::ioctl_ficlone` | Btrfs, XFS (with reflink), others that implement FICLONE | The crate opens `src`, creates `dest` with `O_EXCL` (`create_new`), clones, then copies the source permissions. On failure `dest` is removed. Not atomic. |
| Windows | `FSCTL_DUPLICATE_EXTENTS_TO_FILE` | ReFS (Windows Server, Dev Drive) | The crate creates `dest` with `create_new`, marks it sparse, and requires the source cluster size to be 4K or 64K. The crate documents this path as untested and possibly buggy. Not atomic. |
| other | not supported (`ErrorKind::Unsupported`) | none | Falls back as described in "Errors". |

On Linux and Windows the crate maps any reflink failure on a non-regular-file `src` to an `InvalidInput` error with the message "the source path is not an existing regular file: ...".

`dest` is created with `O_EXCL` semantics on all three platforms, which is why placement removes `dest` first.

The Rust crate pulls `libc` on unix only, used for `clonefile` in `cloneDir`.

## Binary selection

`index.js` is the napi-rs generated loader. It runs at import time. Order of work:

1. If env `NAPI_RS_FORCE_WASI` is `true` or `error`, or `NAPI_RS_WASI_FLAVOR` is non-empty, the WASI chain is tried (`./reflink.wasi.cjs`, then package `@fynjs/reflink-wasm32-wasi`). `NAPI_RS_WASI_FLAVOR` must be `wasm32-wasi` or the import throws. With `NAPI_RS_FORCE_WASI=error` or a flavor set, a missing WASI binding throws and no native fallback is tried. This package ships no WASI artifact.
2. Otherwise `requireNative()` runs. If env `NAPI_RS_NATIVE_LIBRARY_PATH` is set, only that path is required, and no platform lookup happens.
3. Otherwise the loader picks by `process.platform` and `process.arch`. For each target it first tries a local file `./reflink.<platform>-<arch>[-<abi>].node` next to `index.js`, then the package `@fynjs/reflink-<platform>-<arch>[-<abi>]`.
4. A package version other than the loader's own (`0.1.0`) throws only when env `NAPI_RS_ENFORCE_VERSION_CHECK` is set and not `0`.
5. If nothing loads, the import throws `Cannot find native binding. npm has a bug related to optional dependencies ...`, with `cause` set to a chain of the individual load errors. An unsupported OS or arch adds `Unsupported OS: <platform>, architecture: <arch>` to that chain.

Targets this package builds (`napi.targets`) and the matching platform packages:

| platform / arch | local file and package suffix |
| --- | --- |
| macOS x64 | `darwin-x64` |
| macOS arm64 | `darwin-arm64` |
| Linux x64 glibc | `linux-x64-gnu` |
| Linux arm64 glibc | `linux-arm64-gnu` |
| Linux x64 musl | `linux-x64-musl` |
| Linux arm64 musl | `linux-arm64-musl` |
| Windows x64 | `win32-x64-msvc` |
| Windows arm64 | `win32-arm64-msvc` |

Selection details:

- macOS tries `darwin-universal` first, then the arch specific one.
- Linux picks `-musl` or `-gnu` with `isMusl()`: reads `/usr/bin/ldd` for `musl`, else `process.report` (glibc runtime version or musl shared objects), else runs `ldd --version`.
- Windows x64 picks `win32-x64-gnu` instead of `-msvc` when Node reports `shlib_suffix === 'dll.a'` or `node_target_type === 'shared_library'`. No `-gnu` binary is built by this package.
- The loader also has branches for targets this package does not build (android, freebsd, win32-ia32, linux arm, loong64, riscv64, ppc64, s390x, openharmony). Those would only load if a binary or package of that name existed.
- In the monorepo, `prepare.mjs` builds the addon with `napi build --platform --release --esm` when `cargo` exists, producing `reflink.<platform>-<arch>.node` in the package directory. Without `cargo`, the build is skipped, no binary exists, and importing the package throws. Consumers (fyn) must handle that import failure themselves.
- The `files` list in `package.json` includes `reflink.*.node` for local packing. Under `npm pack` or `npm publish` (detected by `npm_command`), `prepack.mjs` removes the `.node` entries from `files` and adds `optionalDependencies` on `@fynjs/reflink-<platformArchABI>` for every target, at the package version. A published install therefore gets the binary from the matching platform package.

## Native threading

- `cloneFile` uses the libuv thread pool.
- `cloneFiles` and `cloneDir` use the addon's own rayon pool, capped at 4 threads (more threads slow APFS down from directory contention, per the source comment).
- `cloneFilesSync` blocks the JS thread while the same pool works.

<!-- publish-util v3.1.7: https://fynjs.pages.dev/ref/publish-util.md -->

# publish-util reference

`publish-util` prunes `package.json` before `npm pack` and restores it afterwards, so the published manifest drops dev-only and non-standard fields. It ships four bins and a small JS API. ESM only (`"type": "module"`), Node `^22.22.2 || ^24.15.0 || >=26.0.0`.

## Imports

```js
import { prePackObj, prePack, postPack, npmPublish, getPackInfo } from "publish-util";
import * as publishUtil from "publish-util";
```

Everything is a named export of the package root. There is no default export. Subpaths: only `publish-util/package.json`.

Runtime exports: `prePackObj`, `prePack`, `postPack`, `npmPublish`, `getInfo`, `getPackInfo`, `loadInfo`, `writePkgFile`, `metaFileOf`, `extractFromObj`, `removeFromObj`, `renameFromObj`, `keepStandardFields`, `utils`.

Type-only exports: `PrePackConfig`, `NpmPublishOptions`, `PackageInfo`, `SaveMeta`, `ExtractSpec`, `RemoveSpec`, `RenameSpec`.

`utils` is the whole `utils.ts` module as a namespace. It holds every utils export above plus `withPackLock`, which has no named export at the root: use `utils.withPackLock`.

Importing the root has no side effects. `prePack`, `postPack` and `npmPublish` only run when called. The bins call them.

## Bins

| Bin | Runs | Purpose |
| --- | --- | --- |
| `publish-util-prepack` | `prePack()` | save and prune `package.json` |
| `publish-util-prepublishonly` | `prePack()` | identical file body to `publish-util-prepack` |
| `publish-util-postpack` | `postPack()` | restore `package.json` |
| `do-publish` | `npmPublish()` | pack with pruned manifest, then publish the tarball |

Each bin is a shebang stub that imports from `dist/` and calls the function without `await` or `catch`. `publish-util-prepublishonly` does not run any prepublishOnly logic. It performs the prepack prune. The only visible difference is the `process.argv[1]` basename, which prefixes log lines.

### Lifecycle wiring

```json
{
  "scripts": {
    "prepack": "publish-util-prepack",
    "postpack": "publish-util-postpack"
  }
}
```

- npm runs `prepack`, packs the files, then runs `postpack`.
- A `prepack` that does other work can chain it: `"prepack": "npm run build && publish-util-prepack"`.
- The package's own `postinstall` script (`node dist/postinstall.js || true`) adds both scripts to the consumer's package.json at install time. See the postinstall section.
- `npm publish` uploads the packument before `prepack` runs, so the pruned manifest is not what the registry shows. `do-publish` exists for that: it runs `npm pack` first, then publishes the tarball.

### `publish-util-prepack`

Calls `prePack()`. Exits 1 on any error inside its try block, after logging `<bin name> failed` and the error to stderr.

### `publish-util-postpack`

Calls `postPack()`. Exits 1 on any error, after logging `<bin name> failed` and the error to stderr.

### `do-publish`

Calls `npmPublish()` with defaults (`exit: true`, `silent: false`). See `npmPublish` for flags and behavior. Its exit code is the process exit code.

## Which package.json is used

`prePack` and `postPack` find the manifest with `getPackInfo()`. `INIT_CWD` is never used for these. Resolution order:

1. `PUBLISH_UTIL_PKG_DIR` env var: `<resolved dir>/package.json`. Logs `publish-util: using <file> from PUBLISH_UTIL_PKG_DIR`. Skips the name and version checks below.
2. `npm_package_json` env var, if that file exists.
3. `<cwd>/package.json` if it exists, otherwise the nearest `package.json` found upward from cwd.

Checks after loading (not applied with `PUBLISH_UTIL_PKG_DIR`):

- `npm_package_name` set and different from the manifest `name`: throws, refusing to touch the file. The message suggests `PUBLISH_UTIL_PKG_DIR`.
- `npm_package_version` set and different from the manifest `version`: `console.warn` only.

Throws `publish-util: no package.json found for this package (looked in <where>)` when no file is found. `<where>` is the cwd, the resolved override dir, or the text `env npm_package_json`.

## Backup, metadata and lock files

All three live in `os.tmpdir()` and are derived from the package name. In the name, every `@` and `/` is replaced by `_` (a manifest without `name` uses `unknown`).

| File | Path | Content |
| --- | --- | --- |
| backup | `<tmpdir>/package-util-<n>_pkg.json` | byte copy of the original manifest |
| metadata | `<backup>.meta.json` | JSON `SaveMeta` |
| lock | `<backup>.lock` | empty file, existence is the lock |

Example for `@scope/pkg`: `<tmpdir>/package-util-_scope_pkg_pkg.json`, with `.meta.json` and `.lock` appended to that full name.

The prefix is `package-util-`, not `publish-util-`. Names that sanitize to the same string share the same files (`@a/b` and `_a_b`).

### Lock behavior (`withPackLock`)

- Creates the lock with `open(lockFile, "wx")` (exclusive create). On `EEXIST` it waits 10 ms and retries, up to 1000 attempts (about 10 seconds plus I/O time).
- Any error other than `EEXIST` is thrown immediately.
- After 1000 failed attempts it throws `publish-util: timed out waiting for pack lock <lockFile>`.
- The lock is closed and unlinked in a `finally` after the action, so a normal run or a thrown error releases it.
- A process killed while holding the lock (SIGKILL, power loss) leaves the `.lock` file. Every later `prepack` or `postpack` for that package name then fails with the timeout error until the file is deleted. The lock holds no pid and there is no stale detection.
- The lock is held only during the prepack or postpack action. A finished prepack leaves backup and metadata in place for postpack but no lock.

To clear the timeout error after an interrupted prepack, delete the `.lock` file. Then check whether the manifest is still pruned and whether the backup and `.meta.json` still exist. See "Interrupted run states" below.

## `prePack()`

```ts
function prePack(): Promise<void>
```

Steps, in order:

1. `getPackInfo()` finds and reads the manifest. This call is outside the try block: a failure rejects the promise and the bin ends through an unhandled rejection, not through `process.exit(1)` with the `failed` log.
2. Reads `pkg.publishUtil` as the `PrePackConfig` (`{}` when absent). Unless `config.silent`, logs `<bin> saveFile <backup> pkgFile <manifest>`.
3. Inside `withPackLock(backup)`:
   - Reads the metadata file. If it parses, a pack is already active:
     - Throws `publish-util: <meta.pkgFile> is already using backup <backup>` when `meta.pkgFile` differs from the resolved manifest.
     - Otherwise sets `activePacks = (activePacks ?? 1) + 1`, rewrites the metadata, returns. The manifest is not touched and nothing else runs.
   - If the metadata file is missing or unparsable: writes the original bytes to the backup (overwriting any existing backup), then writes metadata `{ pkgFile, name, version, pid, ts, activePacks: 1 }` as 2-space JSON plus newline. Metadata is written after the backup, so metadata present implies backup present.
   - Runs `prePackObj(pkg, config)` on the parsed manifest, then writes it back as `JSON.stringify(pkg, null, 2)` plus a trailing newline.
4. On any error from step 2 or 3: logs `<bin> failed` and the error, then `process.exit(1)`.

The manifest is rewritten through `writePkgFile` (same inode, hardlinks preserved).

## `postPack()`

```ts
function postPack(): Promise<void>
```

1. `getPackInfo()` runs inside the try block, so resolution errors exit 1 with `<bin> failed`.
2. Inside `withPackLock(backup)`: reads the metadata (missing or unparsable gives `undefined`).
   - If metadata exists and `activePacks > 1`: decrements it, rewrites the metadata, returns. The manifest is not restored.
   - Otherwise `target = meta.pkgFile || resolved pkgFile`. The path recorded by prepack wins over the resolved one. When they differ, logs `<bin> restoring <target> as recorded by prepack, not <resolved>`.
   - Logs `<bin> saveFile <backup> pkgFile <target>`. This log is unconditional because postpack does not read `publishUtil.silent`.
   - Reads the backup bytes, writes them to `target`, unlinks the backup, then unlinks the metadata (errors on the metadata unlink are ignored).
3. On any error, including a missing backup (ENOENT): logs `<bin> failed` and the error, `process.exit(1)`.

A backup from an older publish-util has no metadata. Then `activePacks` counts as 1 and the resolved path is the restore target.

Concurrent packs of one package name share one backup. Each prepack increments `activePacks` and only the last postpack restores.

### Interrupted run states

- Killed while the lock is held: stale `.lock`, see Lock behavior.
- Killed after prepack finished but before postpack: backup and metadata remain and the manifest is pruned. The next `prepack` finds the metadata, raises `activePacks` to 2 and leaves the manifest alone. The following `postpack` only decrements to 1, and a second `postpack` restores. Deleting the metadata file instead makes the next prepack back up the already pruned manifest over the old backup. To recover the original, keep the backup and copy it over the manifest by hand, or run `postpack` until it restores.
- `postpack` with no backup present: throws ENOENT, exit 1, manifest untouched.

## `prePackObj(pkg, config?)`

```ts
function prePackObj(pkg: Record<string, unknown>, config?: PrePackConfig): void
```

Mutates `pkg` in place. No file access; only `console.log`. Steps, in order:

1. `renameFromObj(pkg, config.rename)`.
2. If `config.keep`: `keepObj = extractFromObj(pkg, config.keep)`. Taken after rename and before remove.
3. If `config.remove`: `removeFromObj(pkg, config.remove)`.
4. `delete pkg.publishUtil`.
5. Unless `config.removeExtraKeys === false`: deletes every top level key not in `keepStandardFields`. Unless `silent`, logs `removed non-standard fields: <keys>` plus a hint. Nothing is logged when no key was removed.
6. If `scripts.postpack` is falsy and `config.autoPostPack !== false`: sets `scripts.postpack = "publish-util-postpack"`, creating `scripts` if needed. Unless `silent`, logs a notice. `scripts` is read after step 3, so a `remove` that deleted `scripts.postpack` or all of `scripts` triggers the re-add.
7. If `scripts.prepack === "publish-util-prepack"` (exact string): deletes it. `scripts` is the object read in step 6, so this does nothing if `scripts` did not exist then. A `prepack` such as `npm run build && publish-util-prepack` is kept.
8. If `keepObj`: `lodash.merge(pkg, keepObj)`. This runs last, so `keep` restores fields that `remove`, `removeExtraKeys` or step 7 deleted. `merge` skips `undefined`, so keeping a key that does not exist adds nothing.

`workspaces` is not in `keepStandardFields`, so step 5 removes it unless it is kept or `removeExtraKeys` is `false`.

### `PrePackConfig`

```ts
interface PrePackConfig {
  rename?: RenameSpec;
  keep?: ExtractSpec;
  remove?: RemoveSpec;
  removeExtraKeys?: boolean;
  autoPostPack?: boolean;
  silent?: boolean;
}
```

`prePack` reads it from the `publishUtil` field of package.json. `publishUtil` itself is deleted from the output.

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `rename` | `RenameSpec` | none | rename fields before keep and remove |
| `keep` | `ExtractSpec` | none | fields restored after all removal |
| `remove` | `RemoveSpec` | none | fields to delete |
| `removeExtraKeys` | `boolean` | on (any value except `false`) | delete top level non-standard fields |
| `autoPostPack` | `boolean` | on (any value except `false`) | add `scripts.postpack` when missing |
| `silent` | `boolean` | `false` | suppress `prePack` and `prePackObj` logs. `postPack` ignores it |

### `keepStandardFields`

```ts
const keepStandardFields: string[]
```

Top level keys that survive `removeExtraKeys`:

`name`, `version`, `description`, `keywords`, `homepage`, `bugs`, `license`, `author`, `contributors`, `funding`, `files`, `main`, `browser`, `bin`, `man`, `directories`, `repository`, `scripts`, `config`, `dependencies`, `devDependencies`, `peerDependencies`, `peerDependenciesMeta`, `bundledDependencies`, `bundleDependencies`, `optionalDependencies`, `engines`, `os`, `cpu`, `libc`, `private`, `publishConfig`, `module`, `type`, `types`, `typings`, `typesVersions`, `sideEffects`, `exports`, `imports`, `unpkg`, `jsdelivr`.

`devDependencies` is kept by default. Drop it with `remove: ["devDependencies"]`. `workspaces` is deliberately absent.

## Spec types and helpers

```ts
type RenameSpec = Record<string, string | string[]>;
type RemoveSpec = (string | Record<string, RemoveSpec>)[];
type ExtractSpec = (string | Record<string, ExtractSpec>)[];
```

String entries in `RemoveSpec` and `ExtractSpec` are a key name or a regex written `"/<source>/<flags>"`. A string that starts with `/` and splits on `/` into exactly 3 parts is a regex (`new RegExp(parts[1], parts[2])`) tested with `String.match` against the object's own keys. Any other string (including one with more slashes, such as `/a/b/c`) is a literal key. An invalid regex throws `SyntaxError`. Object entries reach into a nested key: `{ "scripts": ["test", "/^pre/"] }`.

### `renameFromObj(obj, rename?)`

```ts
function renameFromObj(obj: Record<string, unknown>, rename?: RenameSpec): void
```

For each key in `rename`: reads `lodash.get(obj, key)` (dot paths allowed). If the value is not `undefined` and the target is truthy, it `unset`s the old path and `set`s the target path (a string or a path array). A missing source or empty target is skipped.

### `removeFromObj(obj, fields)`

```ts
function removeFromObj(obj: Record<string, unknown>, fields: RemoveSpec): void
```

Deletes matching keys. Nested object entries recurse into `obj[key]`. Throws `TypeError` when that nested key does not exist (for example `{ "scripts": ["test"] }` on a manifest with no `scripts`), because the recursion runs on `undefined`. In `prePack` that exits 1.

### `extractFromObj(obj, fields, output?)`

```ts
function extractFromObj(
  obj: Record<string, unknown>,
  fields: ExtractSpec,
  output?: Record<string, unknown>
): Record<string, unknown>
```

Copies matching keys into `output` (default `{}`) and returns it. Leaf values are copied by reference. A nested entry on a missing or falsy value copies that value, on a primitive copies it, and on an object builds a new instance of the same constructor (arrays stay arrays) and recurses. A literal key that does not exist yields `output[key] = undefined`.

## `npmPublish(options?)`

```ts
interface NpmPublishOptions {
  exit?: boolean;
  silent?: boolean;
}

function npmPublish(options?: NpmPublishOptions): Promise<number>
```

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `exit` | `boolean` | `true` | call `process.exit(code)` in `finally`. When `false`, resolves with the code (0 or 1) |
| `silent` | `boolean` | `false` | suppress the `Restoring <file>` and `publishing args:` logs |

`do-publish` runs this. Arguments come from `process.argv.slice(2)`. Steps:

1. Installs a no-op `SIGINT` listener so the parent survives Ctrl-C while children handle it.
2. `getInfo()` finds the manifest from `INIT_CWD` or cwd (it does not use `getPackInfo`).
3. Extracts flags from argv. Only the space-separated form is recognized, so `--tag=x` is passed through untouched:
   - `--dry-run`: boolean, removed from argv, not forwarded.
   - `--tag <tag>`: forwarded as `--tag <tag>`. A missing value fails an assert (`--tag must specify a tag`).
   - `--access <public|restricted>`: forwarded. Any other value, or none, fails an assert naming the allowed values.
   - A failed assert is thrown before the try block. The promise rejects, no restore runs, and the `SIGINT` listener stays.
4. Tarball name: `<name with @ removed and / replaced by ->-<version>.tgz` in the package dir (`unknown` and `0.0.0` as fallbacks).
5. Sets `process.env.BY_PUBLISH_UTIL = "1"` (never unset) and `chdir`s to the package dir.
6. If `scripts.prepublish` exists: warns on stderr that it is deprecated, removes it from the manifest object, marks the manifest changed.
7. If `--dry-run`: deletes `scripts.prepare`, marks changed.
8. If changed: writes the modified manifest as `JSON.stringify(pkg, null, 2)` (no trailing newline).
9. If `scripts.prepublishOnly`: runs `npm run prepublishOnly`.
10. Deletes any existing tarball, then runs `npm pack`. That triggers the package's `prepack` and `postpack`.
11. If `scripts.publish`: runs `npm run publish`.
12. Not dry-run: runs `npm publish [--tag t] [--access a] <tarball> <remaining argv>`. Dry-run: prints `dry-run <tgz> args: [...]` and publishes nothing, though `npm pack` already ran.
13. `finally`: if the manifest was changed in step 6 to 8, writes the original bytes back (errors ignored). Then restores cwd, removes the SIGINT listener, deletes the tarball, and calls `process.exit(code)` when `exit` is true.

Child commands run with `stdio: "inherit"`, through a shell on Windows. A non-zero child exit rejects with `<cmd> <args> exited with code <n>`.

Failure: any error inside the try is logged as `publish failed!` plus the error and the code becomes 1. If the error message contains `SIGINT`, it prints a blank line instead. A signal-killed child gives `exited with code null`, which does not contain `SIGINT`, so that branch is not reached by child failures.

## `getInfo(cwd?)`

```ts
function getInfo(cwd?: string): Promise<PackageInfo>
```

`cwd` defaults to `process.env.INIT_CWD || process.cwd()`. Finds the nearest `package.json` upward with `find-up`, then calls `loadInfo`. Throws `No package.json found starting from directory: <cwd>`. Not safe for pack-time scripts, use `getPackInfo`.

## `getPackInfo(cwd?)`

```ts
function getPackInfo(cwd?: string): Promise<PackageInfo>
```

`cwd` defaults to `process.cwd()`. Resolution and checks are in "Which package.json is used". Used by `prePack` and `postPack`.

## `loadInfo(pkgFile)`

```ts
function loadInfo(pkgFile: string): Promise<PackageInfo>
```

Reads and parses the manifest at the given path. Throws the filesystem error or `SyntaxError` for a missing or invalid file. Computes the backup path from the manifest `name`.

### `PackageInfo`

```ts
interface PackageInfo {
  pkgDir: string;                 // dirname of the manifest
  pkg: Record<string, unknown>;   // parsed manifest
  pkgData: Buffer;                // raw bytes as read
  tmpDir: string;                 // os.tmpdir()
  saveName: string;               // package-util-<n>_pkg.json
  saveFile: string;               // <tmpDir>/<saveName>, the backup
  pkgFile: string;                // manifest path
}
```

### `SaveMeta`

```ts
interface SaveMeta {
  pkgFile: string;
  name?: string;
  version?: string;
  pid: number;
  ts: string;          // ISO timestamp
  activePacks?: number;
}
```

Contents of the `.meta.json` file. Only `pkgFile` and `activePacks` are read back. `pid`, `ts`, `name` and `version` are informational.

### `metaFileOf(saveFile)`

```ts
const metaFileOf: (saveFile: string) => string
```

Returns `${saveFile}.meta.json`.

### `utils.withPackLock(saveFile, action)`

```ts
function withPackLock<T>(saveFile: string, action: () => Promise<T>): Promise<T>
```

Runs `action` while holding `${saveFile}.lock`. Behavior is under Lock behavior. Reachable only through the `utils` namespace.

## `writePkgFile(file, content)`

```ts
function writePkgFile(file: string, content: string | Buffer): Promise<boolean>
```

Returns `true` if it wrote, `false` if the file already had identical bytes.

- File missing or unreadable: plain `writeFile`.
- Otherwise opens `r+` (no truncate), writes the new bytes at offset 0, then truncates to the new length. A shorter replacement is first padded with spaces to the old length in the same write. The inode is kept, so fyn hardlinks into `node_modules` see the change.
- Errors from `open`, `write` or `truncate` propagate.

## postinstall

`dist/postinstall.js` is not exported. The package's own `postinstall` script runs it as `node dist/postinstall.js || true`, so a non-zero exit never fails an install.

- Reads `INIT_CWD`. If unset, logs `publish-util postinstall: no INIT_CWD env - skipping` and returns.
- `getInfo(INIT_CWD)` finds the nearest manifest upward. Failure here is outside the try block and becomes an unhandled rejection, which `|| true` swallows.
- For `prepack` and `postpack`: if `scripts.<name>` is absent, sets it to `publish-util-prepack` or `publish-util-postpack`. If it exists and does not contain that string, warns on stderr and leaves it. An existing script that contains it is kept silently.
- Writes the manifest as `JSON.stringify(pkg, null, 2)` plus newline through `writePkgFile`. Identical bytes mean no write. A manifest with other formatting (not 2-space, or no trailing newline) is reformatted even when no script was added.
- Write errors are logged and swallowed.
- It runs for any install of this package, as a dependency or devDependency.

## Environment variables

| Variable | Read by | Effect |
| --- | --- | --- |
| `PUBLISH_UTIL_PKG_DIR` | `getPackInfo` | directory of the manifest to use. Disables the name and version checks |
| `npm_package_json` | `getPackInfo` | manifest path, used when the file exists |
| `npm_package_name` | `getPackInfo` | must equal the manifest name, else throws |
| `npm_package_version` | `getPackInfo` | mismatch logs a warning only |
| `INIT_CWD` | `getInfo` default, postinstall | start dir for manifest lookup. Never used by prepack or postpack |
| `BY_PUBLISH_UTIL` | set by `npmPublish` to `"1"` | read by the repo's own `check.js` guard, which is not shipped (not in `files`) |

## Mismatches with README

- README says `scripts.prepublishOnly` is removed automatically when it equals `publish-util-prepublishonly`. The code never touches `prepublishOnly`. It deletes `scripts.prepack` when it equals exactly `publish-util-prepack`.
- README shows `"prepack": "npm run build && publish-util-prepack"`. The code only drops a `prepack` that is exactly `publish-util-prepack`, so the chained form stays in the published manifest.
- README says `postpack` cannot be removed. In code it is only re-added when missing and `autoPostPack` is not `false`. With `autoPostPack: false`, a `remove` of it sticks.
- README does not mention the backup, metadata and lock files, `activePacks`, `PUBLISH_UTIL_PKG_DIR`, or the manifest name check.
- README says the standard fields are those in the npm docs plus `module`. The code uses an explicit list (`keepStandardFields`) that also has `libc`, `typings`, `typesVersions`, `sideEffects`, `exports`, `imports`, `unpkg`, `jsdelivr`.

<!-- pkg-preper v0.3.7: https://fynjs.pages.dev/ref/pkg-preper.md -->

# pkg-preper reference

`pkg-preper` builds a pacote `dirPacker` for directories that did not come from the npm registry (for example git dependencies). If the directory's `package.json` has a `prepare` script, it calls your `installDependencies` callback first, then packs the directory into a gzipped tarball using `npm-packlist` and `tar`. ESM only (`"type": "module"`). Runtime dependencies: `cacache`, `npm-packlist`, `tar`.

## Imports

```js
import PkgPreper from "pkg-preper";
import { PkgPreper } from "pkg-preper";
```

```ts
import type { PkgPreperOptions, Manifest, PackageJson, InstallDependenciesCallback } from "pkg-preper";
```

The default export and the named export `PkgPreper` are the same class. There are no subpaths (only `pkg-preper/package.json`).

Runtime exports: `default` (the class), `PkgPreper`.

Type-only exports: `PkgPreperOptions`, `Manifest`, `PackageJson`, `InstallDependenciesCallback`.

Not exported: the internal `readPkgJson` helper. Instance fields `_tmpDir` and `_installDependencies` are TypeScript `private`.

## `PkgPreper`

```ts
class PkgPreper {
  constructor(options: PkgPreperOptions);
  packDirectory(mani: Manifest, dir: string, target: string): Promise<void>;
  depDirPacker(manifest: Manifest, dir: string): PassThrough;
  getDirPackerCb(): (manifest: Manifest, dir: string) => PassThrough;
}
```

The constructor only stores `tmpDir` and `installDependencies`. It validates nothing and touches no files. Missing or wrong-typed options fail later, when a method uses them.

### Types

```ts
interface PkgPreperOptions {
  tmpDir: string;
  installDependencies: InstallDependenciesCallback;
}

type InstallDependenciesCallback = (dir: string, message: string) => Promise<any>;

interface Manifest {
  _resolved?: string;
  [key: string]: any;
}

interface PackageJson {
  name?: string;
  version?: string;
  scripts?: { prepare?: string; [key: string]: string | undefined };
  [key: string]: any;
}
```

| option | type | default | behavior |
| --- | --- | --- | --- |
| `tmpDir` | `string` | none, required | Used as a cacache root. Scratch dirs are created at `<tmpDir>/tmp/<prefix>...` (see side effects). `tmpDir` itself and `<tmpDir>/tmp` are created if missing. |
| `installDependencies` | `(dir, message) => Promise<any>` | none, required | Called by `depDirPacker` only when `package.json` has a truthy `scripts.prepare`. It must install dependencies (with dev) and run the prepare script. The resolved value is ignored. A rejection fails the pack. |

`Manifest` is a pacote manifest. Only `_resolved` is read, and only for the message text. `PackageJson` is the parsed `package.json` of `dir`. It is only used for `scripts.prepare`, `name`, and as the `package` field of the packlist tree stub.

## `packDirectory(mani, dir, target)`

```ts
packDirectory(mani: Manifest, dir: string, target: string): Promise<void>
```

Packs `dir` into a tarball at `target`. It does not run the prepare step. It resolves with `undefined`.

| parameter | type | behavior |
| --- | --- | --- |
| `mani` | `Manifest` | Unused. Accepted for signature compatibility. |
| `dir` | `string` | Package directory. Must contain a parseable `package.json`. Used as tar `cwd`. |
| `target` | `string` | Output tarball path. Its basename names the temp file. Its parent directory must already exist. An existing file is replaced. |

Steps:

1. Reads `<dir>/package.json` and parses it (`JSON.parse` of the trimmed text).
2. Creates a scratch dir `<tmpDir>/tmp/packing<random>` through `cacache.tmp.withTmp`.
3. Builds a minimal stand-in for an arborist node: `{ path: dir, package: <parsed json>, isProjectRoot: true, edgesOut: new Map() }`, and calls `npm-packlist` on it. File selection therefore follows npm rules: the `files` field, `.npmignore`, `.gitignore` fallback, and always-included files such as `package.json`. `edgesOut` is empty, so bundled dependencies are not discovered from the dependency graph.
4. Calls `tar.create` with the file list, each entry prefixed with `./` so node-tar does not treat a leading `@` specially. Tar options: `file` is `<scratch>/<basename(target)>`, `cwd: dir`, `prefix: "package/"`, `portable: true`, `gzip: true`, `mtime` fixed to `1985-10-26T08:15:00.000Z`. Entries land under `package/` in the archive. Output is deterministic for the same file content.
5. Renames the scratch tarball to `target` with `fs.rename`, then removes the scratch dir (`withTmp` cleans up on success and on failure).

Side effects on disk: creates `<tmpDir>`, `<tmpDir>/tmp` and a scratch dir under it (scratch dir removed afterwards, the parent dirs remain), and writes `target`. Reads `dir` files. Nothing inside `dir` is modified.

Errors (all as promise rejections, never sync throws):

- Missing or unreadable `<dir>/package.json`: the `fs` error (`ENOENT` and so on).
- Invalid JSON: `SyntaxError` from `JSON.parse`.
- `npm-packlist`, `tar` or cacache failures: passed through.
- `fs.rename` failure, including `EXDEV` when `tmpDir` and `target` are on different filesystems (no copy fallback), or a missing parent directory of `target`.

## `depDirPacker(manifest, dir)`

```ts
depDirPacker(manifest: Manifest, dir: string): PassThrough
```

The pacote `dirPacker` implementation. It returns a `PassThrough` stream right away and does the work asynchronously. The stream carries the gzipped tarball bytes.

Sequence:

1. Reads `<dir>/package.json`.
2. If `pkg.scripts && pkg.scripts.prepare` is truthy, awaits `installDependencies(dir, message)` where `message` is `` `preparing gitdep package ${pkg.name} from ${manifest._resolved}` ``. With no `name` or `_resolved` the text contains `undefined`. An empty-string `prepare` counts as absent.
3. Emits the custom event `"prepared"` on the stream. This happens whether or not a prepare script existed or `installDependencies` was called.
4. Creates a scratch dir `<tmpDir>/tmp/pacote-packing<random>`, calls `packDirectory(manifest, dir, <scratch>/package.tgz)`, then pipes that file into the stream with `stream/promises.pipeline` (this ends the stream when the file is fully read).
5. Any failure in steps 1 to 4 is caught and reported with `stream.emit("error", err)`.

Events and consumption:

- `"prepared"`: emitted once, after dependencies are installed (if needed) and before packing starts. It carries no arguments. Attach the listener synchronously after the call, as the first await boundary is reading `package.json`.
- `"error"`: emitted for read, parse, install, pack and pipe failures. Attach an `"error"` listener, or Node throws on an unhandled `"error"` event.
- Data and `"end"`: the normal stream events after packing succeeds. No bytes are written before the tarball is fully built, so nothing streams until packing completes.
- The scratch dir is removed when the pipeline finishes or fails.

Side effects on disk: whatever `installDependencies` does in `dir` (typically creates `node_modules` and build output there), plus the scratch dirs described above. Because the install runs before `packDirectory`, files created by the prepare script are packed if packlist selects them.

Quirks:

- The error is emitted with `emit`, not `destroy`. If the failure came from `pipeline`, `pipeline` has already destroyed the stream with that error, so listeners can see the error and the stream can already be closed.
- The `installDependencies` return value is ignored. The callback's own failure is the only signal.
- `"prepared"` is emitted before packing, so a `"prepared"` event does not mean packing succeeded.

## `getDirPackerCb()`

```ts
getDirPackerCb(): (manifest: Manifest, dir: string) => PassThrough
```

Returns `(m, d) => this.depDirPacker(m, d)`. The arrow keeps `this` bound, so the result can be passed detached, for example as the `dirPacker` option of `pacote`. Each call returns a new closure. It has no side effects.

```js
const preper = new PkgPreper({ tmpDir, installDependencies });
await pacote.tarball(spec, { dirPacker: preper.getDirPackerCb() });
```

<!-- check-pkg-new-version v1.1.8: https://fynjs.pages.dev/ref/check-pkg-new-version.md -->

# check-pkg-new-version reference

`check-pkg-new-version` lets a published CLI tell its users when a newer version of itself exists. It wraps `check-pkg-new-version-engine` with a Node `fetch` based registry fetcher, a `semver` comparison, and `.npmrc` loading. ESM only (`"type": "module"`). Engine behavior (throttling, metadata file, notify rules) is documented at https://fynjs.pages.dev/ref/check-pkg-new-version-engine.md.

## Imports

```js
import { checkPkgNewVersion } from "check-pkg-new-version";
import * as cpnv from "check-pkg-new-version";
```

Everything is a named export from the package root. There is no default export and no subpaths (only `check-pkg-new-version/package.json`).

Runtime exports: `checkPkgNewVersion` (defined here) and `checkPkgNewVersionEngine` (re-exported from the engine via `export *`).

Type-only exports (re-exported from the engine): `PkgInfo`, `NpmConfig`, `NotifyData`, `CheckResult`, `CheckNewVersionOptions`.

Not exported: `internalFetchJSON`, `internalCheckIsNewer`, `getNpmRcConfig`. They are reachable only as the defaults inside `checkPkgNewVersion`. The engine's `internalNotify` is also not exported.

## `checkPkgNewVersion(options)`

```ts
function checkPkgNewVersion(options: CheckNewVersionOptions): Promise<any>
```

Checks the registry for a newer version of `options.pkg`, at most once per `checkInterval`, and notifies when one is found. It fills in three defaults and delegates to `checkPkgNewVersionEngine`:

```js
checkPkgNewVersionEngine({
  fetchJSON: internalFetchJSON,       // default
  npmConfig,                          // options.npmConfig || await getNpmRcConfig()
  checkIsNewer: internalCheckIsNewer, // default
  ...options,                         // wins over the defaults above
});
```

Return value (from the engine): resolves `true` when the check ran to completion, including when the cache was fresh and no registry call was made. Resolves `false` in CI (`ci-info` `isCI`) or when anything threw. It never rejects, because the engine catches every error.

A resolved `true` does not mean a notification was shown or that metadata was saved. See Failure behavior.

### Options

`CheckNewVersionOptions`:

| option | type | default | behavior |
| --- | --- | --- | --- |
| `pkg` | `{ name: string; version: string }` | none, required | Package to check and the version currently running. Only `name` and `version` are read. If missing, the engine throws internally and the call resolves `false`. |
| `notifyNewVersion` | `(data: any) => void` | engine's console notifier | Called with `{ name, version, newVersion }` when a newer version is found and not already notified. See Notification. |
| `checkInterval` | `number` (ms) | `86400000` (1 day) | Minimum time between registry fetches. A falsy value (`0`, `undefined`) means 1 day. It cannot force a check on every run. |
| `saveMetaDir` | `string` | `os.tmpdir()` | Parent directory of the cache. Files go under `<saveMetaDir>/check-pkg-new-version/`. |
| `checkTag` | `string` | `"latest"` | Dist-tag to compare against. Falsy means `"latest"`. |
| `npmConfig` | `Record<string, string>` | parsed `.npmrc` files | Config used to find the registry URL and auth token. Replaces `.npmrc` loading when truthy. |
| `fetchJSON` | `(url: string, options?: any) => Promise<any>` | internal `fetch` based fetcher | Fetches the packument JSON. Called as `fetchJSON(url, { headers })`. The engine reads `body["dist-tags"]`. |
| `fetchDistTags` | `(url: string \| URL, authToken: string, pkg?: PkgInfo) => Promise<Record<string, string>>` | none | Alternative to `fetchJSON`. When set, the engine uses it and ignores `fetchJSON`. It receives the registry base URL, not a package URL. |
| `checkIsNewer` | `(pkg: PkgInfo, distTags: Record<string, string>, tag?: string) => CheckResult` | internal semver comparison | Decides whether `distTags[tag]` is newer than `pkg.version`. |

Because `...options` is spread last, a key that is present with the value `undefined` overrides the default. `{ fetchJSON: undefined }`, `{ checkIsNewer: undefined }` or `{ npmConfig: undefined }` makes the call resolve `false` (see Quirks). Omit the key instead.

Types, all re-exported from the engine:

```ts
type PkgInfo = { name: string; version: string };
type NpmConfig = Record<string, string>;
type NotifyData = PkgInfo & { newVersion: string };
type CheckResult = { isNewer: boolean; version?: string };
```

### Where state is stored

One JSON file per package and tag:

```
<saveMetaDir || os.tmpdir()>/check-pkg-new-version/<pkg.name>-<tag>-meta.json
```

Content: `{ name, version, distTags, time, notifiedVersion, notifiedTime }`. The directory is created with `mkdir -p`; a mkdir failure is ignored. A missing or unparseable file is treated as no previous check. The file is written only after a registry fetch.

The default location is the OS temp dir, so the cache can disappear on reboot or temp cleanup and the next call fetches again.

### How often it checks

- The registry is fetched when the cache has no `distTags`, or when `now - meta.time >= checkInterval`.
- Otherwise nothing is fetched, compared or notified. The call resolves `true` after reading the file.
- After a fetch, the compare and notify step runs and the file is rewritten with `time = now`.
- A new version is announced when `checkIsNewer(...).isNewer` is true and either `notifiedVersion !== checked.version` or more than 7 days passed since `notifiedTime`.

The compare runs only on fetch, so a version found newer is announced once per version (or once per 7 days), not on every run.

### Registry and auth resolution

Done by the engine from `npmConfig`:

- Registry: the first config key that ends with `registry` (and, for scoped names like `@scope/pkg`, starts with `@scope`), else `npmConfig.registry`, else `https://registry.npmjs.org/`.
- Auth token: first key ending with `_authToken` and starting with `//<registry host>/`, else `npmConfig._authToken`, else `""`.
- The packument URL is `new URL(encodeURIComponent(pkg.name), registry)`.

With `fetchJSON`, the engine sends only `user-agent: check-pkg-new-version-fetch` and an `accept` header. The auth token is not passed to `fetchJSON`, so the default fetcher never authenticates. Private registries that require a token need a custom `fetchDistTags`, which receives the token as its second argument.

### Default `.npmrc` loading

When `options.npmConfig` is falsy, the config is `{ ...parse(~/.npmrc), ...parse(<process.cwd()>/.npmrc) }`.

- Parsed with the `ini` package. The cwd file overrides the home file key by key.
- A missing or unparsable file contributes `{}`. No error surfaces.
- Not read: global npmrc, parent directories of the cwd, `NPM_CONFIG_*` environment variables, `${VAR}` expansion in values.
- The type is `Record<string, string>`, but `ini.parse` can return other value types (booleans, nested objects for `[section]` headers). Nothing coerces them.
- The files are read on every call, including when the cache is fresh.

### Default fetcher

Internal `internalFetchJSON(url, { headers, timeout })`:

- Uses Node's global `fetch` with `headers` and `AbortSignal.timeout(timeout)`. The default timeout is 10000 ms. The engine passes only `{ headers }`, so the timeout is always 10 s on the default path.
- Returns `resp.json()` when `resp.ok`.
- Returns `{}` for any failure: non-2xx status, network error, abort, invalid JSON, invalid URL. It never throws.

### Default comparison

Internal `internalCheckIsNewer(pkg, distTags, tag)`:

```ts
{ isNewer: semver.gt(distTags[tag], pkg.version), version: distTags[tag] }
```

- Uses `semver.gt`, so prerelease ordering follows semver. `1.0.0-beta` is older than `1.0.0`.
- `version` is returned in all cases, also when `isNewer` is `false`.
- It throws (`TypeError`) when either version is not a valid semver string, when the tag is missing from `distTags`, or when `distTags` is `undefined`. The engine catches it and the call resolves `false`.
- This differs from the engine's own default comparison, which returns `{ isNewer: false }` on invalid input.

### Notification

When `notifyNewVersion` is not given, the engine's console notifier runs. It registers a `process.on("exit")` handler that prints, via `console.log`:

```
(blank line)
    New version '<name>' available <version> -> <newVersion>
    Run 'npm i [-g ]<name>@<newVersion>' to update.
(blank line)
```

`-g ` is included when the package is installed globally (`is-installed-globally`). Nothing is printed until the process exits. A custom `notifyNewVersion` is called synchronously during the check. If it throws, the engine catches it, the call resolves `false` and the meta file is not written.

### Example

```js
import { checkPkgNewVersion } from "check-pkg-new-version";

// fire and forget at CLI startup; never rejects
checkPkgNewVersion({
  pkg: { name: "my-cli", version: "1.2.3" },
  checkInterval: 6 * 60 * 60 * 1000,
  notifyNewVersion: ({ name, version, newVersion }) =>
    console.error(`${name} ${newVersion} is available (you have ${version})`)
});
```

### Failure behavior

- In CI (`ci-info`): resolves `false` immediately, no files read or written, no network.
- Any error in the check is swallowed and the call resolves `false`. Examples: bad `pkg`, bad registry URL in config, invalid versions, throwing callbacks, an unwritable meta directory when saving.
- Fetch failure with the default fetcher: `internalFetchJSON` returns `{}`, the engine reads `{}["dist-tags"]` which is `undefined`, and the default `checkIsNewer` throws on `undefined[tag]`. Result: resolves `false` and the meta file is not written, so the next call fetches again. The check retries on every run until a fetch succeeds, each costing up to 10 s.
- The meta write happens after the notify callback. If the write fails, the notification has already fired and will fire again on the next run.
- A cache read failure only means a fetch happens.

### Quirks

Found by reading the code, not by running it.

- Scoped packages never cache. The meta file name is `<pkg.name>-<tag>-meta.json`, so `@scope/pkg` becomes `.../check-pkg-new-version/@scope/pkg-latest-meta.json`. Only `check-pkg-new-version/` is created, not `@scope/`, so the write fails with `ENOENT`, the call resolves `false`, and each run fetches and notifies again.
- A missing tag in `dist-tags` (for example `checkTag: "beta"` when the package has no `beta`) throws in the default `checkIsNewer` and resolves `false`, with no meta saved, so it refetches every run.
- Present-but-undefined option keys override defaults (see Options).
- `checkInterval: 0` means 1 day, not "always".

### README mismatches

- README says `saveMetaDir` defaults to `os.tmpdir()`. Files actually go in an `os.tmpdir()/check-pkg-new-version/` subdirectory.
- README says `checkInterval` is a wait with no default. The default is 1 day.
- README lists `fetchJSON` as the fetch override and omits `fetchDistTags`, which is also accepted and takes priority.
- README says the package reads the registry URL and auth token from `.npmrc`. The token is only passed to `fetchDistTags`. The default fetcher does not send it.
- README does not say the default `checkIsNewer` throws on a missing tag or invalid version.

<!-- check-pkg-new-version-engine v2.1.7: https://fynjs.pages.dev/ref/check-pkg-new-version-engine.md -->

# check-pkg-new-version-engine reference

`check-pkg-new-version-engine` is a generic engine for npm CLI packages to check whether a newer version of themselves is published. The caller injects the network fetch, the version comparison and the notification. The engine adds throttling, a small on-disk cache, and a repeat-notification rule. ESM only (`"type": "module"`), Node `^22.22.2 || ^24.15.0 || >=26.0.0`. Runtime dependencies: `ci-info`, `is-installed-globally`, `semver`.

## Imports

```js
import { checkPkgNewVersionEngine } from "check-pkg-new-version-engine";
```

```ts
import type {
  CheckNewVersionOptions,
  PkgInfo,
  NpmConfig,
  NotifyData,
  CheckResult,
} from "check-pkg-new-version-engine";
```

The root is the only entry point (plus `check-pkg-new-version-engine/package.json`). There is no default export.

Runtime exports: `checkPkgNewVersionEngine`.

Type-only exports: `PkgInfo`, `NpmConfig`, `NotifyData`, `CheckResult`, `CheckNewVersionOptions`.

Not exported: `internalNotify` (the default notifier) and `internalCheckIsNewer` (a semver-based comparison). The engine never calls `internalCheckIsNewer`. See `checkIsNewer`.

## `checkPkgNewVersionEngine(options)`

```ts
function checkPkgNewVersionEngine(options: CheckNewVersionOptions): Promise<any>
```

Checks the npm registry for a newer version of `options.pkg`, at most once per check interval, and calls a notify hook when one is found. Intended to be called fire-and-forget at CLI startup.

Never rejects. Any error thrown anywhere inside (bad options, hook exceptions, fetch failures that a hook rethrows, file write failures) is swallowed and the promise resolves `false`.

Return value:

| value | when |
| --- | --- |
| `false` | `ci-info` reports a CI environment (checked first, nothing else runs), or any error was thrown |
| `true` | the run completed without throwing, whether or not a fetch happened and whether or not anything was notified |

`true` does not mean a newer version exists or that a notification was sent.

### Flow

1. If `isCI` (from `ci-info`, evaluated at import time): return `false`. No fetch, no file access, no hooks.
2. Copy `options.pkg` to `{ name, version }`. Hooks receive this copy, never the original object.
3. `tag = options.checkTag || "latest"`.
4. `metaDir = path.join(options.saveMetaDir || os.tmpdir(), "check-pkg-new-version")`. Create it recursively. A mkdir failure is ignored.
5. `metaFile = path.join(metaDir, `${pkg.name}-${tag}-meta.json`)`. Read and `JSON.parse` it. Any read or parse failure gives `{ name, version, time: 0, notifiedVersion: "", notifiedTime: 0 }`.
6. `checkInterval = options.checkInterval || 86400000` (1 day).
7. `shouldFetch = now - meta.time >= checkInterval || !meta.distTags`.
8. If `shouldFetch` is false: return `true`. No hook is called and the meta file is not rewritten. The cached `distTags` are not compared again.
9. Otherwise fetch dist tags (see below), call `checkIsNewer(pkg, distTags, tag)`, maybe notify, write the meta file, return `true`.

### Option table

| option | type | default | behavior |
| --- | --- | --- | --- |
| `pkg` | `PkgInfo` | required | Package to check. `name` is used for the registry URL and the cache file name. `version` is the current version passed to `checkIsNewer`. A missing `pkg` throws internally, so the call resolves `false`. |
| `fetchDistTags` | `(url, authToken, pkg?) => Promise<Record<string,string>>` | none | Preferred fetch hook. Takes precedence over `fetchJSON` when both are set. See below for the arguments. |
| `fetchJSON` | `(url: string, options?: any) => Promise<any>` | none | Alternate fetch hook. Used only when `fetchDistTags` is not set. |
| `notifyNewVersion` | `(data: any) => void` | built-in console notifier | Called synchronously, not awaited, with `{ name, version, newVersion }`. |
| `saveMetaDir` | `string` | `os.tmpdir()` | Parent directory for the cache. Files go in `<saveMetaDir>/check-pkg-new-version/`. Empty string counts as unset. |
| `checkInterval` | `number` (ms) | `86400000` | Minimum time between registry fetches. Any falsy value (`0`, `undefined`) gives the default, so `0` cannot mean "always check". |
| `checkTag` | `string` | `"latest"` | Dist-tag to compare against. Also part of the cache file name. Empty string gives `"latest"`. |
| `checkIsNewer` | `(pkg, distTags, tag?) => CheckResult` | none (see note) | Decides whether `distTags[tag]` is newer than `pkg.version`. Typed optional but required in practice. |
| `npmConfig` | `NpmConfig` | none (see note) | Flat npm config used to pick registry and auth token. Typed optional but required in practice. |

Required in practice: if `checkIsNewer` is missing, the call `options.checkIsNewer(...)` throws after the fetch, the meta file is not written, and the result is `false`. If `npmConfig` is missing, `Object.keys(undefined)` throws when the registry is resolved, so nothing is fetched and the result is `false`. Pass `npmConfig: {}` for the npmjs default. The `NpmConfig` doc comment says it defaults to `{ registry: "https://registry.npmjs.org/" }`, but the engine applies no such default to the object. The README comment "without npm config the engine falls back to registry.npmjs.org" holds only for an empty object, not for `undefined`.

Required only when fetching: one of `fetchDistTags` or `fetchJSON` is needed only on a run where `shouldFetch` is true. If neither is set, an internal `Error("must provide one fetch method: fetchDistTags or fetchJSON")` is thrown and swallowed, so the result is `false` and nothing is saved.

## Registry and auth resolution

Done by an internal function, only on runs that fetch.

Scope: if `pkg.name.split("/")` has more than one part, `scope` is the first part (for example `@acme`). Otherwise `scope` is `""`.

Registry: the first key `k` of `npmConfig`, in `Object.keys` order, where `k.endsWith("registry")` and (`scope` is empty or `k.startsWith(scope)`). The value is used if truthy. Otherwise `npmConfig.registry`, otherwise `"https://registry.npmjs.org/"`. The registry string is used as is, and `new URL(registry)` must parse or the run fails (`false`).

- For a scoped package the plain `registry` key does not match the search (it does not start with the scope), so it is reached through the `npmConfig.registry` fallback. Same result.
- For an unscoped package, any key ending in `registry` matches, including `@scope:registry`. See pitfalls.

Auth token: let `regHost = "//" + new URL(registry).host + "/"` (host includes any port). The first key that ends with `_authToken` and starts with `regHost` wins. Otherwise `npmConfig._authToken`, otherwise `""`. The registry path is ignored.

## Fetch hooks

### `fetchDistTags`

```ts
fetchDistTags?(url: string | URL, authToken: string, pkg?: PkgInfo): Promise<Record<string, string>>
```

Called as `fetchDistTags(registry, authToken, { name, version })`. Despite the parameter name `url`, the first argument is the registry base string from the resolution above, not a package URL. The hook must build the package URL itself. It must resolve an object mapping dist-tag to version. A rejection or throw is not caught locally: it propagates, the run resolves `false`, and the meta file is not written (so the next call fetches again).

### `fetchJSON`

```ts
fetchJSON?(url: string, options?: any): Promise<any>
```

Used through the built-in packument fetch:

- URL: `new URL(encodeURIComponent(pkg.name), registry).toString()`. A scoped name becomes `@scope%2Fname`. Relative resolution applies: a registry with a path but no trailing slash (for example `https://host/npm`) loses its last segment.
- Second argument: `{ headers: { "user-agent": "check-pkg-new-version-fetch", accept: "application/vnd.npm.install-v1+json; q=1.0, application/json; q=0.8, */*" } }`.
- The auth token is resolved but not used on this path. No authorization header is sent. Private registries need `fetchDistTags`.
- Result: `body["dist-tags"]`.
- Any error (including a rejection from `fetchJSON` or a null `body`) is caught and `{}` is used as the dist tags. A failed fetch is therefore treated as "no tags": it is cached for the whole interval and `checkIsNewer` runs against `{}`.
- If the body has no `dist-tags`, the value is `undefined`. It is passed to `checkIsNewer` and not saved as truthy, so the next call refetches.

## `checkIsNewer`

```ts
checkIsNewer?(pkg: PkgInfo, distTags: Record<string, string>, tag?: string): CheckResult
```

Called as `checkIsNewer({ name, version }, distTags, tag)` where `tag` is the resolved tag (never undefined). Called synchronously, only on fetch runs. Return `{ isNewer: true, version }` to trigger notification. If `isNewer` is truthy, `version` is used as `newVersion`, as the saved `notifiedVersion` and in the repeat-notification rule. A throw propagates to `false` and the meta file is not written.

The engine has no default comparison. The unexported `internalCheckIsNewer` is not wired in. Its rules, for reference when writing your own with `semver`:

- Uses `semver.valid` on both the current version and `distTags[tag]`. Either one invalid (or missing) gives `{ isNewer: false }`, no throw.
- `semver.gt(newer, current)` true gives `{ isNewer: true, version: newer }`, else `{ isNewer: false }`.
- Comparison is by semver precedence. `1.0.0-beta` is lower than `1.0.0`. An older `latest` never counts as newer.

The README example uses `semver.gt(distTags[tag], pkg.version)` directly. That throws on invalid input and on missing tags (swallowed to `false`, no meta write).

## Notification

After `checkIsNewer` returns, on fetch runs only:

```
notify if checked.isNewer
  && (notifiedVersion !== checked.version || now - notifiedTime > 7 days)
```

`notifiedVersion` and `notifiedTime` come from the meta file (`""` and `0` when absent or of the wrong type). A new version is notified once, and the same version is re-notified when more than 7 days have passed since the last notification. Since fetches happen at most once per `checkInterval`, a `checkInterval` longer than 7 days effectively re-notifies on each fetch.

The notify call is `(options.notifyNewVersion || internalNotify)({ name, version, newVersion })`. It is not awaited. A thrown error propagates, the meta file is not written, and the result is `false`.

When a notification is sent, `notifiedVersion` and `notifiedTime` are updated in the meta file. When not, the previous values are written back.

### Default notifier

Internal, not exported. It registers `process.on("exit", ...)` (one listener per call) that prints with `console.log`:

```
    New version '<name>' available <version> -> <newVersion>
    Run 'npm i [-g ]<name>@<newVersion>' to update.
```

`-g ` is included when `is-installed-globally` is true. The message prints at process exit, so it does not interleave with the host CLI output.

## Meta file

Path: `<saveMetaDir || os.tmpdir()>/check-pkg-new-version/<pkg.name>-<tag>-meta.json`.

Written only on fetch runs, after the notify step, as JSON:

```json
{ "name": "...", "version": "...", "distTags": {}, "time": 1700000000000, "notifiedVersion": "", "notifiedTime": 0 }
```

`time` is the start of the run (`Date.now()` taken before the fetch). `version` is the current package version at write time. It is not compared on read: after the host package upgrades, cached `distTags` stay in force until the interval elapses. The cache key is only name plus tag.

A write failure throws, so the result is `false`. If the notify hook already ran, the notification has been sent but not recorded. Concurrent processes are not coordinated.

## Types

```ts
type PkgInfo = { name: string; version: string };
type NpmConfig = Record<string, string>;
type NotifyData = PkgInfo & { newVersion: string };
type CheckResult = { isNewer: boolean; version?: string };
```

`CheckNewVersionOptions` members, as declared:

```ts
{
  pkg: PkgInfo;
  fetchDistTags?(url: string | URL, authToken: string, pkg?: PkgInfo): Promise<Record<string, string>>;
  fetchJSON?(url: string, options?: any): Promise<any>;
  notifyNewVersion?(data: any): void;
  saveMetaDir?: string;
  checkInterval?: number;
  checkTag?: string;
  checkIsNewer?(pkg: PkgInfo, distTags: Record<string, string>, tag?: string): CheckResult;
  npmConfig?: NpmConfig;
}
```

`NotifyData` is the shape actually passed to `notifyNewVersion`, although that hook is typed `data: any`. `NpmConfig` keys the engine reads: any key ending in `registry` (`registry`, `@scope:registry`), any key ending in `_authToken` (`//host/:_authToken`, `_authToken`).

## Known pitfalls

- Scoped package names break the cache. The meta file name includes `pkg.name`, so `@scope/x` becomes a path in a `@scope` subdirectory that is never created. Reads always miss and the write throws, so every call fetches, notifies again, and resolves `false`.
- An unscoped package can pick up a scoped registry: the first `*registry` key in iteration order wins, even `@other:registry`.
- `fetchJSON` swallows all fetch errors and caches the empty result for the full interval.
- On the `fetchJSON` path the auth token is never sent.

## Example

```js
import { checkPkgNewVersionEngine } from "check-pkg-new-version-engine";
import semver from "semver";

checkPkgNewVersionEngine({
  pkg: { name: "my-cli", version: "1.2.3" },
  npmConfig: {},
  checkInterval: 6 * 60 * 60 * 1000,
  fetchJSON: async (url, options) => (await fetch(url, options)).json(),
  checkIsNewer: (pkg, tags, tag) => {
    const v = tags?.[tag];
    return semver.valid(v) && semver.gt(v, pkg.version)
      ? { isNewer: true, version: v }
      : { isNewer: false };
  },
});
```

<!-- @jchip/error v2.1.7: https://fynjs.pages.dev/ref/error.md -->

# @jchip/error reference

`@jchip/error` has helpers to print readable error stacks and an `AggregateError` subclass whose `stack` includes the stacks of the errors it holds. It has no runtime dependencies. ESM only (`"type": "module"`). Requires Node `^22.22.2 || ^24.15.0 || >=26.0.0`.

## Imports

```js
import { cleanErrorStack, aggregateStack, aggregateErrorStack, AggregateError } from "@jchip/error";
import * as jerr from "@jchip/error";
```

Everything is a named export from the package root. There is no default export and there are no subpaths (only `@jchip/error/package.json`).

Runtime exports: `cleanErrorStack`, `aggregateStack`, `aggregateErrorStack`, `AggregateError`.

There are no exported types besides the class `AggregateError`. The options type `CleanErrorStackOptions` is declared but not exported, so it cannot be imported by name. Use `Parameters<typeof cleanErrorStack>[1]` to get it.

## `cleanErrorStack(error, options?)`

```ts
type CleanErrorStackOptions = {
  replacePath?: false | string;
  ignorePathFilter?: (string | RegExp)[];
};

function cleanErrorStack(
  error: Error,
  options?: CleanErrorStackOptions
): string
```

Returns the text of `error.stack` with noisy stack frames removed and file paths shortened. The error is not modified.

| option | type | default | behavior |
| --- | --- | --- | --- |
| `replacePath` | `false \| string` | `` `${process.cwd()}/` `` (evaluated on each call) | Substring removed from each kept frame path. Ignored when `false`, empty, or exactly 1 character long (so `"/"` does nothing). |
| `ignorePathFilter` | `(string \| RegExp)[]` | `[]` | Extra filters. A frame whose path matches any filter is dropped. Added to the built-in filter. |

Input selection:

- The text cleaned is `error.stack`, or `error.message` when the stack is falsy.
- When neither exists (or `error` is `null`/`undefined`), nothing is cleaned and the return value is `String(error && (error.stack || error.message))`. That gives `"null"` for `null` and `"undefined"` for `undefined`, `{}`, or an object with empty stack and no message.
- A non-string, truthy `stack` (such as a number) throws `TypeError` (`stack.split is not a function`).

Processing, applied to each line of the text split on `"\n"`:

1. A line that does not match `/ {4,}at/` (an `at` preceded by 4 or more spaces anywhere in the line) is kept unchanged. This covers the message line, `Require stack:` lines, and frames indented with fewer than 4 spaces.
2. A frame line is parsed with `/( {4,}at)([^\(]+\()([^\)]+\))(.*)/`. Group 3 is the "path": the text after the first `(` up to and including the first `)`. Groups 2 and 4 are the text before and after it.
3. The frame is dropped when parsing fails. That removes frames without parentheses, such as `    at /abs/file.js:1:1` and `    at node:internal/main/run_main_module:17:47`, and any `at file:///...` frame.
4. The frame is dropped unless the path contains `scheme://` (regex `/[^:]+:\/\//`) or `path.isAbsolute(path)` is true. That removes relative paths and `node:internal/...` frames. `path.isAbsolute` is platform specific, so a Windows path like `C:\a\b.js` is dropped on POSIX.
5. Backslashes in the path are replaced with `/`.
6. The frame is dropped if the path matches the built-in filter or any `ignorePathFilter` entry. A `RegExp` entry uses `path.match(re)`. A string entry uses `path.includes(str)`. Falsy entries (such as `""`) are skipped.
7. Otherwise `replacePath` (when usable) is removed with `String.prototype.replace` (first occurrence only, plain string, not a regex). It can match anywhere in the path, not only at the start.
8. The kept frame is rebuilt as group1 + group2 + new path + group4. Because the path comes from group 3, everything after the first `)` (group 4) is unchanged. A `)` inside a file path ends the path early.
9. After mapping, empty strings are removed and lines are joined with `"\n"`. Blank lines in the original text (including a trailing newline) are therefore removed too.

Built-in filter (always on, checked before `ignorePathFilter`):

```
/\/node_modules.*\/(pirates\/|isomorphic-loader\/lib\/extend-require)/
```

It drops frames from the `pirates` and `isomorphic-loader` require hooks. It matches on the backslash-normalized path.

Not removed: frames from other `node_modules` packages, and any absolute path outside `replacePath`. Only `node:` internals and relative paths go by rule 4.

```js
cleanErrorStack(err);
// Error: boom
//     at run (src/app.js:10:5)
cleanErrorStack(err, { replacePath: false, ignorePathFilter: ["/node_modules/", /vitest/] });
```

## `aggregateStack(stack, errors)`

```ts
function aggregateStack(stack: string, errors: any[]): string
```

Builds a text from a top stack and a list of errors. Output is `stack`, then one entry per error, all joined with `"\n"`. Each error entry is its text with every line indented by 2 spaces (`replace(/^/gm, "  ")`, so blank lines become `"  "`).

The text of one error `e` is `e.stack`, else `e.message`, else `String(e)`. A falsy `e` gives `String(e)`. Examples: `1` gives `"1"`, `null` gives `"null"`, `{ message: "mm" }` gives `"mm"`.

Nested aggregate stacks indent again, so each nesting level adds 2 spaces.

Edge cases on `errors`:

- An array (or any object with a `map` function) is mapped. `[]` returns `stack` alone with no trailing newline.
- A falsy `errors` (`null`, `undefined`, `""`) or a value with no `map` function (such as a string or a plain object without `map`) is treated as no errors, but the result gets a trailing `"\n"`, for example `aggregateStack("t", null) === "t\n"`.
- A truthy `errors.map` that is not a function throws `TypeError`.
- `stack` is not checked. A non-string is joined as is.

## `aggregateErrorStack(error)`

```ts
function aggregateErrorStack(error: AggregateError): string
```

Returns `aggregateStack(error.__stack || error.message || String(error), error.errors)`. The parameter type is this package's `AggregateError` class.

- For an instance of this package's `AggregateError`, the top part is its saved original stack (`__stack`), which is the native stack text, including the header `AggregateError: <message>` and frames.
- For a native `globalThis.AggregateError` (or any object without `__stack`), the top part is `error.message`, falling back to `String(error)` when the message is empty. The native stack frames and the `AggregateError:` header are not used. Example: message `"msg"` yields `"msg\n  Error: e\n      at ..."`.
- The list used is `error.errors`.
- The result is computed each time. It is cached only by the `stack` getter of this package's class.

```js
console.log(aggregateErrorStack(new AggregateError([new Error("error 1")], "test")));
// AggregateError: test
//     at ...
//   Error: error 1
//       at ...
```

## `AggregateError`

```ts
class AggregateError extends globalThis.AggregateError {
  readonly name: string;   // "AggregateError"
  errors: any[];
  stack: string;
  __stack: string;
  constructor(errors?: any[], msg?: string);
}
```

An `AggregateError` whose `stack` also prints the errors it wraps. It is a subclass, not a polyfill. See "Polyfill behavior" below.

Constructor `new AggregateError(errors, msg?)`:

- `errors` must be truthy and have a callable `[Symbol.iterator]`. Otherwise it throws `TypeError` with the message `input errors must be iterable but it's ${typeof errors}`. Falsy values give `undefined`, `object` (for `null`), `number`, and so on. A truthy number (`5`) gives `number`. A string is accepted since strings are iterable.
- `msg` is the message. When omitted the message is `""`. There is no third `options` argument. `{ cause }` passed as a third argument is ignored.
- The parent constructor is called as `super(errors, msg)`.

Instance properties (all defined with `Object.defineProperty`, so `Object.keys(err)` is `[]`):

| property | attributes | value |
| --- | --- | --- |
| `name` | non-enumerable, non-writable, non-configurable own property | `"AggregateError"`. A subclass cannot override it by assignment. |
| `errors` | non-enumerable, writable, configurable | `[].concat(errors)`: a shallow copy when `errors` is an array. |
| `__stack` | non-enumerable, non-writable, non-configurable | `this.stack` read right after `super()`: the native stack text of the error. |
| `stack` | non-enumerable, configurable accessor | Getter returning `aggregateErrorStack(this)`, computed on first read and cached. |

`stack` details:

- The cache means `errors` changes made after the first read of `stack` are not reflected. Changes made before the first read are.
- Only a getter is defined. The existing native setter of the engine remains, so assigning to `err.stack` does not throw and has no effect on the getter result (observed on Node 24).
- `instanceof` works against the native class (`new AggregateError([]) instanceof globalThis.AggregateError` is `true`). A native instance is not an instance of this class.
- `console.log(err)` and `err.stack` in a debugger show the aggregate form. `cleanErrorStack(err)` therefore also cleans the nested error stacks, and the nested lines keep their 2-space indent.

Edge cases from `[].concat(errors)`, which does not iterate:

- A non-array iterable (for example `Set` or a generator) is wrapped as a single element: `new AggregateError(new Set([e])).errors` is `[Set]`, not `[e]`. The native parent receives the original iterable, but the own `errors` property replaces the native one.
- A generator is consumed by `super()` first, so `errors` ends up `[<exhausted generator>]`, and the nested stack lists `String(generator)` (`[object Generator]`).
- A string `"ab"` gives `["ab"]`, where the native class would give `["a", "b"]`.

## Polyfill behavior

- The package does not patch or define any global. Importing it has no side effects (`"sideEffects": false`).
- `AggregateError` here is a different class from `globalThis.AggregateError` (`AggregateError !== globalThis.AggregateError`). Its prototype parent is the global one.
- The module evaluates `class AggregateError extends globalThis.AggregateError` at import time. If the runtime lacks a global `AggregateError`, import throws. All supported Node versions (`engines`) have it, so there is no fallback implementation.
- Code that wants the aggregate-stack behavior must import this class explicitly. Native `AggregateError` instances are unchanged, and `aggregateErrorStack(native)` is the way to format them (see above for how the top line differs).

## README mismatches

- The README calls `AggregateError` a polyfill. In code it is a subclass of the global class and never installs itself.
- The README says Node 15+ has a built-in `AggregateError`. The code requires the global, and `engines` is Node 22 or newer.

<!-- optional-import v1.1.7: https://fynjs.pages.dev/ref/optional-import.md -->

# optional-import reference

`optional-import` loads an optional ESM dependency and tells "not installed" apart from "installed but broken". It resolves the specifier first and imports second, so only a failed resolve counts as "not installed". ESM only (`"type": "module"`), no runtime dependencies, Node `^22.22.2 || ^24.15.0 || >=26.0.0`.

## Imports

```js
import { makeOptionalImport, tryImport, tryResolve, setDefaultLog } from "optional-import";
import * as optionalImport from "optional-import";
```

```ts
import type {
  LogFunction,
  ImportMetaLike,
  NotExportedHandling,
  OptionalImportOpts,
  OptsOrMessage,
  OptionalImportFunction,
} from "optional-import";
```

Everything is a named export from the package root. There is no default export and there are no subpaths (only `optional-import/package.json`).

Runtime exports: `setDefaultLog`, `tryResolve`, `tryImport`, `makeOptionalImport`.

Type-only exports: `LogFunction`, `ImportMetaLike`, `NotExportedHandling`, `OptionalImportOpts`, `OptsOrMessage`, `OptionalImportFunction`.

Not exported: the internal helpers `normalizeOpts`, `checkMeta`, `isPathSpecifier`, `windowsPathToFileUrl`, `pathSpecifierMissing`, `makeNotFoundError`, `isNotFound`, `logNotFound`, `handleResolveError`, `resolveExisting`.

## How "not installed" is decided

Every entry point (`tryImport`, `tryResolve`, and the bound function from `makeOptionalImport`) runs the same steps.

1. `meta` is checked (see `ImportMetaLike`). A bad `meta` throws `TypeError`.
2. The specifier is resolved with `meta.resolve(specifier)`. If it matches `/^[a-zA-Z]:[\\/]/` (a Windows drive path), it is first rewritten to a `file:///` URL, on every OS.
3. If `meta.resolve` threw, that error is classified (below).
4. If it returned and the specifier is a path specifier whose resolved URL starts with `file:`, the file is checked with `existsSync(fileURLToPath(url))`. A missing file produces a synthetic "not found" error. If `fileURLToPath` throws, the specifier is treated as present.
5. Otherwise the resolved URL is used. `tryImport` then runs `import(url)`.

Classification of a resolve error `err`, by `err.code`:

| `err.code` | Result |
| --- | --- |
| `ERR_MODULE_NOT_FOUND` | not installed |
| `ERR_PACKAGE_PATH_NOT_EXPORTED` | not installed when `notExported` is `"notFound"` or unset, else a failure |
| anything else (for example `ERR_INVALID_MODULE_SPECIFIER`, `ERR_PACKAGE_IMPORT_NOT_DEFINED`, `ERR_INVALID_PACKAGE_CONFIG`, or no code) | a failure |

Only `err.code` is read. Message text is never inspected.

What happens in each case:

| Case | Behavior |
| --- | --- |
| not installed | log if `message` is truthy, then return `notFound(err)` if `notFound` is set, else `default` (`undefined` if unset). Nothing is thrown. |
| resolve failure | return `fail(err)` if `fail` is set, else rethrow `err`. No logging. |
| resolved, `import()` throws (`tryImport` only) | return `fail(err)` if `fail` is set, else rethrow. No logging. Covers syntax errors, module-scope throws, and a missing dependency of the module itself. |
| resolved, import succeeds | return the module namespace object. |

Path specifiers are those that start with `/`, `./`, `../`, `.\`, `..\`, or `file:`, or match a drive-letter path `X:\` or `X:/`. Only these get the existence check. Not path specifiers, so never checked: `.`, `..`, bare names (`pkg`, `pkg/sub.js`), `node:` and `#imports` specifiers.

The synthetic not-found error is `new Error("Cannot find module '<specifier>'" + (meta.url ? " imported from <meta.url>" : ""))` with `code` set to `"ERR_MODULE_NOT_FOUND"`. `<specifier>` is the original text, not the rewritten drive URL.

The check is on the literal resolved URL. There is no extension probing and no `index.js` lookup. A path that is a directory exists, so it is not "not installed". Importing it then fails with `ERR_UNSUPPORTED_DIR_IMPORT`, which goes to `fail` or is rethrown.

Known gap: a subpath of an installed bare package with no `exports` map (`"pkg/missing.js"`) resolves without error, so it is not checked. `tryImport` then fails on `import()` with `ERR_MODULE_NOT_FOUND`, which goes to `fail` or is rethrown, not to `notFound`/`default`. `has("pkg/missing.js")` returns `true`.

## Resolution base and caching

Resolution is relative to the module whose `import.meta` was passed. `import.meta.resolve` has no parent argument, so the bound `meta.resolve` function carries the location. `meta.url` is used only in the synthetic not-found message.

An `opts.meta` on a single call overrides the `meta` argument (or the one bound by `makeOptionalImport`) for that call. A falsy `opts.meta` falls back to the bound one.

The package keeps no cache. Each call re-runs resolve, the existence check and `import()`. Module caching is whatever the Node module map does for `import(url)`. The only module-level state is the default log function.

## `setDefaultLog(log)`

```ts
function setDefaultLog(log: LogFunction): void
```

Replaces the module-level default log function. The initial default is `(message) => console.log(message)`; it ignores the `specifier` argument. No validation, returns nothing.

When the default is read:

- `tryResolve` and `tryImport` read it as a default parameter value on each call that omits `log` (or passes `undefined`).
- `makeOptionalImport` reads it once, when called. A function made earlier keeps its previously captured `log` and is not changed by a later `setDefaultLog`.

## `ImportMetaLike`

```ts
type ImportMetaLike = {
  url?: string;
  resolve: (specifier: string) => string;
};
```

The caller's `import.meta` object, not `import.meta.url`. A value is accepted when it is truthy and `typeof meta.resolve === "function"`. Otherwise `TypeError` is thrown with a message starting `optional-import: expecting the caller's \`import.meta\` object (not \`import.meta.url\`)`. `url` is optional and used only in the synthetic not-found message.

When the check throws:

- `makeOptionalImport(meta)`: synchronously.
- `tryResolve`: synchronously.
- `tryImport`: as a rejected promise, since it is `async`.
- the bound function and its `.resolve`: the check runs on `opts.meta || boundMeta` on every call. The bound `meta` was already checked at creation, so only a bad `opts.meta` can throw.

## `OptionalImportOpts`

```ts
type OptionalImportOpts = {
  notFound?: (err: Error) => unknown;
  fail?: (err: Error) => unknown;
  default?: unknown;
  message?: true | string;
  log?: LogFunction;
  meta?: ImportMetaLike;
  notExported?: NotExportedHandling;
};
```

| option | type | default | behavior |
| --- | --- | --- | --- |
| `notFound` | `(err: Error) => unknown` | unset | Called when not installed. Its return value is returned as is. `default` is ignored when this is set. If it throws, the error propagates. |
| `fail` | `(err: Error) => unknown` | unset | Called for a non-not-found resolve error, or for an `import()` error. Its return value is returned. When unset the error is rethrown. Never called for "not installed". |
| `default` | `unknown` | `undefined` | Returned when not installed and `notFound` is unset. |
| `message` | `true \| string` | unset | When truthy and the module is not installed, logs `"<message> optional module not found: <specifier>"`. `true` gives `"optional module not found: <specifier>"` with no prefix. A string is prepended followed by one space. An empty string is falsy and logs nothing. Never logs for failure cases. |
| `log` | `LogFunction` | the function passed to the entry point (default: module default log) | Used instead of that function for this call. Called as `log(text, specifier)`. |
| `meta` | `ImportMetaLike` | the bound `meta` | Overrides the resolution base for this call. |
| `notExported` | `"notFound" \| "fail"` | `"notFound"` | Treatment of `ERR_PACKAGE_PATH_NOT_EXPORTED` from resolve. |

Logging happens before `notFound` or `default` is applied.

## `NotExportedHandling`

```ts
type NotExportedHandling = "notFound" | "fail";
```

An unset value or the exact string `"notFound"` gives not-installed treatment. Any other value (a typo, in JS) is treated as `"fail"`.

- `"notFound"`: the package is installed but its `exports` map does not expose the subpath. Handled as not installed.
- `"fail"`: handled as a failure, so `fail(err)` is returned or `err` is rethrown.

## `OptsOrMessage`

```ts
type OptsOrMessage = OptionalImportOpts | string | true;
```

The third argument of `tryResolve` and `tryImport`, and the second of the bound function and its `.resolve`. `undefined` becomes `{}`. `true` or any string becomes `{ message: <value> }`. An object is used as is. `null` is not handled and throws `TypeError` (a property read on `null`); in `tryImport` that is a rejected promise. `false` is used as is and behaves like no options.

## `LogFunction`

```ts
type LogFunction = (message: string, specifier: string) => void;
```

`message` is the full text to log. `specifier` is the specifier as passed by the caller.

## `tryResolve(meta, specifier, optsOrMsg?, log?)`

```ts
function tryResolve(
  meta: ImportMetaLike,
  specifier: string,
  optsOrMsg?: OptsOrMessage,
  log?: LogFunction // default: current default log, read per call
): any
```

Synchronous. Resolves without evaluating the module, using the steps in "How not installed is decided".

Returns the resolved URL string when found. When not installed, returns `notFound(err)` or `default`. On a failure, returns `fail(err)` or throws.

- A returned URL is not proof the target exists for a bare specifier: `meta.resolve` does no filesystem stat there. Path and `file:` specifiers do get the existence check.
- `undefined` is ambiguous (not installed with no `default`, or a `notFound`/`fail` that returned `undefined`).
- Node built-ins resolve (`tryResolve(import.meta, "node:fs")` returns `"node:fs"`).

## `tryImport(meta, specifier, optsOrMsg?, log?)`

```ts
async function tryImport(
  meta: ImportMetaLike,
  specifier: string,
  optsOrMsg?: OptsOrMessage,
  log?: LogFunction // default: current default log, read per call
): Promise<any>
```

Resolves as `tryResolve` does, then returns `await import(url)` when it resolved.

- The namespace object is returned unmodified. For a CJS dependency, `module.exports` is on `.default`. There is no auto-unwrapping.
- Not installed: resolves to `notFound(err)` or `default`.
- Import errors go to `fail` or reject. A broken installed module never turns into the default.
- All errors surface as promise rejection, including the `TypeError` for a bad `meta`.

## `makeOptionalImport(meta, log?)`

```ts
function makeOptionalImport<T = any>(
  meta: ImportMetaLike,
  log?: LogFunction // default: current default log, read when called
): OptionalImportFunction<T>
```

Validates `meta` immediately (throws `TypeError` if bad) and returns a function bound to it.

```js
const optionalImport = makeOptionalImport(import.meta);
const chalk = await optionalImport("chalk", { default: null });
if (optionalImport.has("chalk")) { /* ... */ }
```

## `OptionalImportFunction<T>`

```ts
type OptionalImportFunction<T = any> = {
  (specifier: string, optsOrMsg?: OptsOrMessage): Promise<T>;
  resolve: (specifier: string, optsOrMsg?: OptsOrMessage) => any;
  has: (specifier: string) => boolean;
  log: LogFunction;
};
```

- Call: `tryImport(meta, specifier, optsOrMsg, optionalImport.log)`. `T` is only a type annotation, nothing is checked at runtime.
- `.resolve(specifier, optsOrMsg?)`: `tryResolve(meta, specifier, optsOrMsg, optionalImport.log)`. Synchronous.
- `.has(specifier)`: `tryResolve(meta, specifier, { default: undefined }) !== undefined`. Synchronous. `true` when the specifier resolves (and, for path specifiers, the file exists), `false` when not installed. It takes no options, uses the bound `meta`, and does not log. A resolve failure that is not "not installed" (an invalid specifier, an undefined `#import`) throws instead of returning `false`.
- `.log`: a plain writable property, initially the `log` argument. It is read on every call, so reassigning it affects later calls on this function. A per-call `opts.log` still wins.

<!-- run-verify v2.1.8: https://fynjs.pages.dev/ref/run-verify.md -->

# run-verify API reference

This reference documents `verify` and its lower-level positional APIs. All of these APIs
are exported from the package root.

## Imports

All supported imports come from the package root:

```js
import { signal, verify } from "run-verify";
```

There is no public subpath for the chain API.

## `verify(config?)`

```ts
verify(config?: ChainConfig): Chain<undefined>
```

Starts an immutable, thenable chain. Adding a step returns a new chain. Awaiting the
chain starts the run. Calling `.then()` or `.catch()` also starts it. There is no
terminal method.

An empty chain resolves `undefined`. Otherwise, the final step supplies the result. A
step or signal failure rejects the run. A missed deadline also rejects it. Errors from
user code keep their original identity.

### Config

```ts
interface ChainConfig<S extends SignalMap = SignalMap> {
  timeout?: number;
  cleanup?: (() => unknown) | (() => unknown)[];
  signals?: S;
}
```

| Option | Behavior |
| --- | --- |
| `timeout` | Whole-run deadline in milliseconds. There is no default. Reaching it fails the run but does not cancel underlying work. |
| `cleanup` | One function or an array of functions run after success or failure. Returned Promises are awaited. |
| `signals` | Named signals registered before the first step. Every registered signal must settle before the run can finish. |

The run invokes multiple cleanup functions in array order. It awaits their returned
Promises together. Put ordered cleanup inside one async function. Use `try`/`finally`
when later cleanup must run after an earlier failure.

### Execution and reuse

Awaiting the same chain more than once starts it once and shares its result. The chain is
immutable, so a prefix can produce independent branches. Each branch is a separate run
with the prefix's setup and cleanup.

A config containing signals is single-use. Its signals represent one occurrence. A
signal-bearing chain cannot be branched or run again. Create the signals and chain
inside each test.

## Step methods

### `.step(fn)`

```ts
chain.step(fn: (input: Current) => Next): Chain<Awaited<Next>>
```

Calls `fn` when the sequence reaches it. The current value is its argument, and the
return value becomes the next value. A returned thenable is awaited. A returned array
passes through unchanged, including an array of promises.

A function that returns nothing changes the value to `undefined`. Use `.keep.step(fn)`
when an assertion or side effect should preserve the input.

### `.step(value)`

```ts
chain.step(value): Chain<Awaited<typeof value>>
```

Replaces the current value with a non-function value. A thenable is adopted. Other
values, including arrays, pass through unchanged.

The value form is eager: a Promise has already started before the chain reaches the
step. Pass a function when work must start only after earlier steps finish.

A function is always treated as work to call. Use a wrapper such as `() => fn` when a
function itself must be the value.

### `.asyncStep(fnOrValue)`

```ts
chain.asyncStep(fnOrValue): Chain<ResolvedValue>
```

Handles one Promise like `.step()`. It resolves an array like `Promise.all` and preserves
tuple positions. The rule applies to a direct value or a function's return value.

The function form receives the current value and starts work when its turn arrives. The
value form is already running.

Use `.step()` instead when an array of promises should remain available for a later
operation such as `Promise.race`.

### `.callbackStep(fn)`

```ts
chain.callbackStep<Result>(fn): Chain<Result>
```

Adds an explicit error-first callback step. Its declared parameter count determines
what it receives:

```js
// One parameter receives only the callback.
.callbackStep(next => load("record-1", next))

// Two parameters receive the current value and callback.
.step(() => "record-1")
.callbackStep((id, next) => load(id, next))
```

The callback signature is `(err?, value?)`. An error fails the step. Otherwise, `value`
becomes the next chain value. The function's return value is ignored, including a
returned Promise.

TypeScript cannot infer the success type from a callback parameter, so the result
defaults to `unknown`. Supply `.callbackStep<Result>()` when a later step needs its
structure. Under strict checking, annotate both parameters in the two-parameter form.
The exported `StepCallback<Result>` type covers the callback.

## Step modifiers

Modifiers affect only the next step method. You can compose them in either order.

### `.keep`

Waits for the next step to finish, then forwards that step's input instead of its
result. A failure still fails the run.

```js
const id = await verify()
  .step(() => ({ id: "a" }))
  .keep.step(record => assert.equal(record.id, "a"))
  .step(record => record.id);
```

### `.expectError`

Requires the next step to fail. A throw, rejection, or callback error satisfies the
requirement. Successful completion fails the run. Returning an `Error` counts as
success, so it does not satisfy the requirement.

The original failure becomes the next value. Without an instance requirement it has
the `unknown` type because JavaScript may throw any value. Adding `.expectError` to an
instance requirement preserves its inferred instance type.

### `.expectErrorMatch(matcher, code?)`

Requires the next step to fail with a matching top-level `message`. A string matcher
checks for a substring; a `RegExp` tests the message. Use anchors for an exact message,
such as `/^invalid input$/`. A failure without a string message does not match.

A supplied `code` must equal the top-level error's `code` with strict equality. Codes
may be strings or numbers. Omitting `code` adds no constraint and preserves any earlier
requirements. The original failure becomes the next value; an existing instance
requirement retains its inferred type.

Repeated calls to either new matching method add requirements. Every requirement must
pass; a later matching call does not replace an earlier message, instance, or code
requirement. Regular expression checks do not change the supplied expression's
`lastIndex`, and repeated checks have the same result for global or sticky expressions.

### `.expectErrorInstanceMatch(ConstructorOrArray, matcher?, code?)`

Requires the next step to fail with a value satisfying `instanceof` the supplied
constructor, including subclasses. Alternatively, supply a nonempty array of
constructors: an instance of any listed constructor satisfies that call's instance
requirement. An optional message matcher and code use the same rules as
`.expectErrorMatch()`. To require just an instance and code, omit the matcher explicitly:

```ts
await verify()
  .expectErrorInstanceMatch(TypeError, undefined, "E_BAD")
  .step(() => parseInput());
```

The original failure becomes the next value, typed as the constructor's instance type
or the union of the array's instance types:

```ts
await verify()
  .expectErrorInstanceMatch([TypeError, RangeError], /invalid/i, "E_BAD")
  .step(() => parseInput())
  .step(error => {
    // error is typed TypeError | RangeError
    expect(error.message).toMatch(/invalid/i);
  });
```

Separate instance-matching calls must all pass and narrow the value accordingly.
Throws, Promise rejections, and callback errors use the same requirements. Successful
completion, even returning an instance, fails the expectation. Both matching methods
apply only to the next step and take precedence over `.keep`.

### `.expectErrorToBe(message, code?)`

Like `.expectError`. The top-level error's `message` must equal `message`. A supplied
`code` must also match with strict equality. Codes may be strings or numbers.

### `.expectErrorHas(text, code?)`

Like `.expectError`. The top-level error's `message` must contain `text`. The optional
`code` check matches `.expectErrorToBe()`.

### `.expectErrorToBe(Constructor, code?)`

Requires the next step to fail with a value that satisfies `instanceof Constructor`,
including subclasses. A supplied `code` must also match with strict equality. The
original failure becomes the next value, typed as the constructor's instance type.
Throws, Promise rejections, and callback errors use the same check. Returning an
instance successfully does not satisfy the expectation.

Constructor and message requirements compose in either order:

```ts
await verify()
  .expectErrorToBe(TypeError)
  .expectErrorHas("invalid input")
  .step(() => parseInput())
  .step(error => {
    // error is typed TypeError
    expect(error.message).toContain("invalid input");
  });
```

Repeating a constructor requirement replaces the previous constructor. Modifiers
apply only to the next step. `.expectError` without a constructor still yields `unknown`.

Use `.expectError` followed by an inspection step for custom predicates, such as
inspecting nested causes. The existing `expectErrorToBe` and `expectErrorHas` methods
retain their current semantics; the new matching methods add requirements rather than
replacing earlier ones.

## Signals

### `signal<T>(timeout?)`

```ts
signal<T>(timeout?: number): Signal<T>
verify.signal<T>(timeout?: number): Signal<T>
```

Both forms are the same function. A signal represents one external occurrence, such as
an event. `timeout` is an optional deadline for that signal alone.

```ts
interface Signal<T> {
  resolve(value: T): void;
  reject(error: Error): void;
  pending(): boolean;
  readonly defer: DeferObject;
}
```

- `resolve(value)` settles the signal successfully.
- `reject(error)` fails the run using the signal.
- `pending()` reports whether it has not settled.
- `defer` exposes the underlying defer used by the positional API.

Declaring a signal in `config.signals` registers it before any step runs. Registration
does not block the sequence. The run cannot finish until every registered signal
settles.

### `.awaiting(signalOrName, ms?)`

Waits at this point for a configured signal. The signal's value replaces the current
value. The signal may already have settled. `ms` sets an optional deadline for this
wait.

The object and name forms have the same behavior:

```js
.awaiting(saved)
.awaiting("saved")
```

The signal must appear in `config.signals`. TypeScript checks named keys and infers the
signal's value type in both forms. The object form avoids string typos in JavaScript.
One signal can be awaited only once in a chain.

## Promise-like methods

### `.then(onfulfilled?, onrejected?)`

Starts the chain. It handles the result like `Promise.then()`.

### `.catch(onrejected?)`

Starts the chain. It handles a rejection like `Promise.catch()`.

## Modern TypeScript exports

| Export | Purpose |
| --- | --- |
| `Chain<Out>` | The immutable, thenable chain. `Out` is its current output type. |
| `ChainConfig<S>` | `verify()` configuration. |
| `Signal<T>` | A typed external signal. |
| `SignalMap` | A string-keyed map of signals. |
| `StepCallback<T>` | Error-first callback type used by `.callbackStep()`. |
| `VerifyFn` | The callable `verify` entry point, including `verify.signal`. |

## Low-level positional API

The positional runner does the work behind `verify`, and its helpers are exported too.
This API is not type-safe between steps. Single-parameter callback detection depends on
the declared parameter name.

### Positional step rules

`runVerify` and `asyncVerify` take positional steps and run them in order. Each ordinary
result becomes the next step's input.

| Step signature | Input | Completion |
| --- | --- | --- |
| `() => value` | None | Returned value or Promise. |
| `value => nextValue` | Previous value | Returned value or Promise, unless the parameter is callback-named. |
| `async value => nextValue` | Previous value | Returned Promise. Native async functions are never callback mode. |
| `(value, next) => {}` | Previous value and callback | `next(err, result)`. |
| `next => {}` | Callback only | `next(err, result)` when the parameter name starts with `next`, `cb`, `callback`, or `done`. |

`withCallback(fn)` selects callback-only mode for a one-parameter function. A callback
step completes only through `next`. A returned Promise is ignored.

A step that returns nothing supplies `undefined` to the next step. Throwing, rejecting,
or calling `next(err)` stops the run unless the step is wrapped with an expected-error
helper.

### `runVerify(...steps, done)`

Runs the positional steps and calls `done(err, result)` once. The run stops on its first
failure. On success, `result` is the last step's result.

### `asyncVerify(...steps)`

Runs the same positional sequence and returns a Promise. The Promise resolves with the
last step's result or rejects on the first failure. Do not pass a final `done` callback.
`asyncVerify` supplies its own.

### `runTimeout(ms)`

Creates a pass-through entry that starts a runner deadline when reached, replacing any
earlier runner deadline. There is no default. This is one deadline for the remaining
run, not a separate timer around each step.

`runTimeout(ms, fn)` is also accepted. It calls `fn` with the timeout error if the
deadline expires. The normal public pattern is the standalone pass-through entry.

### `runFinally(fn)`

Registers cleanup for the end of the run. Cleanup runs after success or failure. The
runner collects cleanup entries before execution, so their positions do not affect
value flow. More than one may be supplied. Returned Promises are awaited.

### `runDefer(timeout?)`

Creates an external signal for the positional runner. Put the defer itself in the
positional list to register it. Registration does not block. Every registered defer must
settle before the run can finish. Put `defer.wait(ms?)` in the list to wait at a specific
point. Its value then passes to the next step.

The returned `DeferObject` provides:

| Member | Behavior |
| --- | --- |
| `resolve(value?)` | Settle successfully. |
| `reject(error)` | Settle with a failure. |
| `pending()` | Return `true` until settlement. |
| `wait(ms?)` | Return a positional wait step. The defer may be waited once. |
| `waitAgain(ms?)` | Return another wait step for intentional reuse. |
| `clear()` | Reset settlement and wait state. Return a function that can reset it again. |
| `onResolve(fn)` | Add a handler for successful settlement. Return the defer. |
| `onReject(fn)` | Add a handler for failed settlement. Return the defer. |

The constructor's `timeout` applies while the registered defer is outstanding. A
timeout passed to `wait()` or `waitAgain()` applies to that wait. `setAwait()` and the
symbol-bearing fields are runner plumbing. Do not call them directly.

### Expected-error helpers

These wrap one positional step:

| Helper | Requirement |
| --- | --- |
| `expectError(fn)` | The step must fail. A throw or rejection counts. A callback error also counts. |
| `expectErrorMatch(fn, matcher, code?)` | Require a top-level message substring or regex match. Optionally require an exact code. |
| `expectErrorInstanceMatch(fn, ConstructorOrArray, matcher?, code?)` | Require an instance of one constructor or any constructor in a nonempty array. Optionally require a message match and exact code. |
| `expectErrorToBe(fn, message, code?)` | Require an exact top-level message. Optionally require an exact code. |
| `expectErrorToBe(fn, Constructor, code?)` | Require an instance of `Constructor`. Optionally require an exact code. Also available on `wrapCheck(fn)`. |
| `expectErrorHas(fn, text, code?)` | Require a top-level message substring. Optionally require an exact code. |

When the requirement passes, the failure value goes to the next positional step.
Returning an `Error` as a value does not satisfy the requirement.
Both matching methods are also available on `wrapCheck(fn)` with the same arguments
after the function. Repeated matching calls on a wrapper retain every requirement,
just as they do on a fluent chain.

### `withCallback(fn)`

Marks a one-parameter function as callback-only without relying on its parameter name.
The function receives `next`, not the previous result. A two-parameter step already
receives `(result, next)` and does not need this wrapper.

### `onFailVerify(fn)`

Creates a positional failure hook. The hook is skipped while the run is passing. It
receives an error from the preceding step. Its return value is ignored. An exception
from the hook replaces the run's error.

### `wrapCheck(fn)` and `wrapFn(fn)`

`wrapCheck` creates the mutable wrapper used by the positional helpers. It exposes the
expected-error modifiers. It also exposes `.withCallback`, `.onFailVerify`, and
`.runTimeout(ms)`.

`wrapFn` creates the undecorated internal wrapper shape. Prefer the named helper that
states the intended behavior.

### `wrapVerify(...steps, done)`

Returns a function that takes one value. Calling it starts `runVerify`. That value is
the first positional result. The supplied steps and `done` follow it.

### `wrapAsyncVerify(...steps)`

This is the Promise form of `wrapVerify`. It returns a function that takes one value.
The result settles like `asyncVerify`.

### Low-level TypeScript exports

| Export | Purpose |
| --- | --- |
| `CheckFunction` | Untyped positional step function. |
| `DoneCallback` | Final callback type. |
| `NextCallback` | Positional error-first callback type. |
| `ErrorCode` | `string | number`. |
| `DeferHandlers` | Handler arrays used by a defer. |
| `DeferObject` | Full positional defer shape. |
| `WrapObject` | Mutable positional wrapper shape. |

### Internal exports

`_asyncVerifyFrom`, `WRAPPED_FN`, `IS_FINALLY`, `DEFER_EVENT`, `DEFER_WAIT`, and
`DEFER_OBJ` are exported from the root module because the implementation shares them.
They are internal plumbing. Do not use them directly.

<!-- string-array v2.1.7: https://fynjs.pages.dev/ref/string-array.md -->

# string-array reference

`string-array` parses a bracketed, comma separated string such as `"[a, b, [c]]"` into a nested array of strings. It has no runtime dependencies. ESM only (`"type": "module"`).

## Imports

```js
import { parse } from "string-array";
import type { ParseResult, StringArray } from "string-array";
```

Everything is a named export from the package root. There is no default export and there are no subpaths (only `string-array/package.json`). The `exports` map has a single `default` condition pointing at an ESM file.

Runtime exports: `parse`.

Type-only exports: `StringArray`, `ParseResult`.

## `StringArray`

```ts
type StringArray = string | StringArray[];
```

An element is either a string or a nested array of elements. Leaves are always strings. Quote characters are never interpreted, and no numbers or booleans are produced.

## `ParseResult`

```ts
interface ParseResult {
  prefix: string;
  array: StringArray[];
  remain: string;
}
```

| Field | Type | Behavior |
| --- | --- | --- |
| `prefix` | `string` | Trimmed text before the first `[`. `""` when there is none, when `noPrefix` is `true`, or when the input is empty. |
| `array` | `StringArray[]` | The outermost parsed array. Its items are strings or nested arrays. `[]` for empty input. |
| `remain` | `string` | Text left after the first complete top-level array, with leading whitespace and one separating `,` removed. The input is trimmed up front, so `remain` has no outer whitespace. `""` when nothing is left. |

## `parse(str, noPrefix?, noExtra?)`

```ts
function parse(str: string, noPrefix?: boolean, noExtra?: boolean): ParseResult
```

Parses one array from the start of `str` (after an optional prefix) and returns it with the prefix and the unparsed rest.

| Parameter | Type | Default | Behavior |
| --- | --- | --- | --- |
| `str` | `string` | none | Input text. Trimmed first. A non-string throws `TypeError`. |
| `noPrefix` | `boolean` | `undefined` | Only the exact value `true` disables prefix detection. Any other value, including truthy ones such as `1`, keeps it enabled. |
| `noExtra` | `boolean` | `undefined` | Only the exact value `true` makes text after the top-level array an error. Any other value allows it and returns it in `remain`. |

### Grammar

Informal, as implemented:

```
input   := ws* [ prefix ] array rest
prefix  := text before the first "[", trimmed; only when that "[" is not at index 0
array   := "[" ws* items "]"
items   := (element | array) separated by ","
element := any characters up to the next "," or "]", trimmed
rest    := ws* [ "," ws* ] remain
```

- Brackets: `[` opens an array and `]` closes it. Consecutive openers such as `[[[a]]]` nest.
- Nesting: unbounded depth. The parser is iterative, with no recursion.
- Separator: `,`. Whitespace around elements, brackets and separators is trimmed (`String.prototype.trim` semantics).
- Elements: raw text, trimmed. Quotes (`'`, `"`, backtick) stay part of the element. There is no escape character and no way to put `,` or `]` inside an element. A `[` in the middle of an element is accepted as plain text (see edge cases).
- The comma after a nested array is optional. If present directly after its `]`, it is consumed.
- Only the first top-level array is parsed. Later text is not parsed, it is returned in `remain`.

### Algorithm

1. `str` is trimmed. If the result is empty, return `{ prefix: "", array: [], remain: "" }`. This happens before any other check, so `noPrefix` and `noExtra` do not matter for empty input.
2. Unless `noPrefix === true`, find the first `[`. If its index is greater than 0, `prefix` is the text before it (trimmed) and parsing starts at that `[`. If the index is 0 or there is no `[`, `prefix` is `""` and the text is parsed as is.
3. The parse loop: if the remaining text starts with `[`, a new array opens (leading whitespace after it is skipped). Otherwise, if no array is open, it throws `array missing [`.
4. In an open array, the next element runs up to the next `,` or `]`. If neither exists it throws `array missing ]`.
5. The element is trimmed. A non-empty element is pushed. An empty element is pushed as `""` only when it ends at `,`. An empty element ending at `]` is dropped.
6. On `]`, the array closes. A single `,` that follows is consumed.
7. When the outermost array closes, the loop stops. If text remains and `noExtra === true`, it throws `extra data at end of array`. Otherwise the text is returned as `remain`.

`array` is the outermost array itself. `"[a, [b]]"` gives `array: ["a", ["b"]]`. Each call returns fresh objects.

### Non-array and unusual input

| Input | Result |
| --- | --- |
| `""` or whitespace only | `{ prefix: "", array: [], remain: "" }`. No error, with any flags. |
| No `[` (`"abc"`) | Throws `array missing [`. |
| Text then `[`, with `noPrefix: true` (`"pre[a]"`) | Throws `array missing [`. |
| `"]"` | Throws `array missing [`. |
| `"[a"`, `"[[a]"` | Throws `array missing ]`. |
| `null`, `undefined`, number, array | Throws `TypeError` from `str.trim`. Not guarded. |

### Errors

All thrown errors are plain `Error` instances (not `AssertionError`) except the `TypeError` for non-string input.

| Message | When |
| --- | --- |
| `array missing [` | Input is non-empty and the parser needs an opening `[` but finds none: no `[` in the input, text before `[` with `noPrefix: true`, or input starting with `]`. |
| `array missing ]` | An array is still open and there is no further `,` or `]`, or the input ends while an array is open. |
| `extra data at end of array` | The top-level array closed, text remains, and `noExtra === true`. |

An unmatched `]` after a complete array is not an error. It lands in `remain`, or throws `extra data at end of array` with `noExtra`.

### Edge cases

| Input | Result |
| --- | --- |
| `"[]"`, `"[ ]"` | `array: []` |
| `"[a,]"` | `["a"]`. A trailing comma adds nothing. |
| `"[,]"` | `[""]` |
| `"[a,,b]"` | `["a", "", "b"]` |
| `"[a,,]"` | `["a", ""]` |
| `"[[a],]"` | `[["a"]]` |
| `"[[a] b]"` | `[["a"], "b"]`. The comma after a nested array is optional. |
| `"[[],[]]"`, `"[a,[]]"` | `[[], []]`, `["a", []]` |
| `"[ 'x,y' ]"` | `["'x", "y'"]`. Quotes do not protect the comma. |
| `"[a [b]]"` | `array: ["a [b"]`, `remain: "]"`. The inner `[` is plain text, so the first `]` closes the outer array. |
| `"pre [a] post"` | `prefix: "pre"`, `array: ["a"]`, `remain: "post"` |
| `"x]y[a]"` | `prefix: "x]y"`, `array: ["a"]` |
| `"[a], x"` | `remain: "x"`. The comma after `]` is consumed. |
| `"[a] x [b]"` | `remain: "x [b]"`. The second array is not parsed. |
| `"[a]]"` | `remain: "]"` |
| `"[a]["` | `remain: "["` |
| `"[a],"`, `"[a]  ,  "` | `remain: ""`, even with `noExtra: true`. The comma is consumed and nothing is left. |
| `"[a] ,x"` with `noExtra` | Throws `extra data at end of array`. |
| `"pre[a]"` with `noExtra` | Fine. A prefix is not extra data. |

```js
parse("tag[ hello, world, [ 1, [2] ] ] rest");
// { prefix: "tag", array: ["hello", "world", ["1", ["2"]]], remain: "rest" }

parse("[a, b] more", false, true); // throws Error("extra data at end of array")
```

<!-- @fynjs/ts-resolve v1.0.3: https://fynjs.pages.dev/ref/ts-resolve.md -->

# @fynjs/ts-resolve reference

`@fynjs/ts-resolve` lets plain `node` run TypeScript sources that import each other with `.js`-style or extensionless specifiers. It only resolves specifiers to `.ts`-family files. Node's own type stripping then compiles them. There is no `load` hook, no transpiler and no runtime dependency. ESM only (`"type": "module"`).

## Imports

```js
// Register side effect (CLI): node --import @fynjs/ts-resolve/register app.ts
import "@fynjs/ts-resolve/register";

// Programmatic
import { install, createTsMapper, createResolveHook } from "@fynjs/ts-resolve";
import type { MapperOptions, FileCheck } from "@fynjs/ts-resolve";
```

Package `exports`: `.` (`dist/index.js`), `./register` (`dist/register.js`), `./package.json`. `sideEffects` lists only `dist/register.js`. `./register` has no exports; importing it runs `install()` with no options. There is no `./register.ts` subpath and no CJS entry. From CommonJS use dynamic `import()`.

Runtime exports of `.`: `install`, `createResolveHook`, `createResolveFilename`, `createTsMapper`, `defaultIsFile`.

Type-only exports of `.`: `MapperOptions`, `FileCheck`.

Not exported: the types `ResolveContext`, `ResolveResult`, `NextResolve`, `MapTs`, `CjsParent`, `ResolveFilename`. They appear in the signatures below and cannot be imported by name. Derive them with `ReturnType` or `Parameters` if needed. The constants `TS_EXTENSIONS`, `JS_TO_TS`, `DEFAULT_SKIP` are internal.

Engines: `^22.22.2 || ^24.15.0 || >=26.0.0`. The code needs `module.registerHooks` (a synchronous in-thread hook API) and node's built-in type stripping.

## Registering

Two ways, same effect.

```sh
node --import @fynjs/ts-resolve/register src/entry.ts
```

```js
import { install } from "@fynjs/ts-resolve";
install();
```

`install()` does two things: it registers an ESM/`require` resolve hook with `module.registerHooks`, and it wraps `Module._resolveFilename` for CommonJS. See `install`. It does not use `module.register` (no async loader thread) and has no CJS `-r` entry.

The entry file itself is not remapped. The specifier passed to the resolve hook for the main entry is not relative, so `node entry.js` does not find `entry.ts`. Pass the real `.ts` path.

## Mapping rules

These rules are implemented by `createTsMapper` and applied by both hooks. Input is a resolved `file:` URL.

Only relative specifiers are considered by the hooks: those starting with `"."`, and only when a parent is known (`context.parentURL` for ESM, `parent.filename` for CJS). Bare specifiers (`pkg`), absolute paths, `file:` URLs, `node:` builtins and `#imports` are always passed to the next resolver.

For each URL, `mapTs` runs this lookup. First match wins:

1. If the URL matches the `skip` regex (default `/\/(node_modules|\.fynpo)\//`), return `null`. This is tested against the whole URL, so it also skips everything when the project itself lives under a directory named `node_modules` or `.fynpo`.
2. If the URL ends with `.js`, `.mjs` or `.cjs` (case-sensitive regex `/\.[mc]?js$/`):
   - If a real file exists at the URL, return `null`. An existing JS file is never shadowed.
   - Otherwise try these candidates with the extension swapped, in order, and return the first that is a file:

   | specifier ends with | candidates, in order |
   | --- | --- |
   | `.js` | `.ts`, `.tsx` |
   | `.mjs` | `.mts`, `.ts` |
   | `.cjs` | `.cts`, `.ts` |

   - If none exists, return `null`.
3. Else, if the URL does not end with an extension (regex `/\.[a-z0-9]+$/i` does not match), try in order:
   - `url + ".ts"`, `".tsx"`, `".mts"`, `".cts"`
   - `url + "/index.ts"`, `"/index.tsx"`, `"/index.mts"`, `"/index.cts"`

   Return the first that is a file. All extension candidates are tried before any `index` candidate.
4. Otherwise return `null`.

Consequences:

- A specifier that already ends in `.ts`, `.mts`, `.cts`, `.tsx`, `.json` or any other extension is never mapped. It goes to the next resolver unchanged.
- Extensionless names that contain a dot, such as `./foo.config`, count as having an extension and are not mapped.
- Uppercase `.JS` is not treated as a JS extension (the JS regex is case-sensitive) but does count as having an extension, so it is not mapped.
- A directory specifier with a trailing slash, such as `./sub/`, does map to the index file, but the URL gets a double slash (`.../sub//index.ts`). The path still stats correctly on POSIX.
- A query string or hash on the specifier (`./a.js?x=1`) makes the URL not end in `.js`, so it is not mapped.
- `.tsx` is mapped, but node cannot strip JSX, so such a file will fail to load at runtime.
- The candidate must be a regular file (`statSync(...).isFile()`). A directory named `foo.ts` is not matched.

What is passed through: every URL for which `mapTs` returns `null` goes to the next resolver untouched. That includes all of `node_modules` (by default), existing `.js` files, bare specifiers and unmatched paths. When nothing maps, errors such as `ERR_MODULE_NOT_FOUND` or `MODULE_NOT_FOUND` come from node, not from this package.

## `install(options?)`

```ts
function install(options?: MapperOptions): void
```

Registers the ESM/synchronous resolve hook and patches the CJS resolver. `options` defaults to `{}`.

Steps, in order:

1. `registerHooks({ resolve: createResolveHook(options) })` from `node:module`.
2. Replaces `Module._resolveFilename` with `createResolveFilename(createTsMapper(options), previous)`, where `previous` is the function in place at call time.

Rules:

- Each call adds another hook and wraps the CJS resolver again. Call it once per process. `./register` already calls it once.
- The two steps use two separate mappers, so they have separate caches. They share the same `options`.
- Why the CJS patch exists (from source comments): below node 26.2, a CommonJS entry file's `require` goes straight to `Module._resolveFilename` and skips `registerHooks`. Without the patch `require("./lib.js")` fails with `MODULE_NOT_FOUND`. From 26.2 both agree. The patch is installed unconditionally and no version check is done.
- Type stripping for `.ts` files handed to the CJS loader is done by node, not by this package.
- Throws whatever `registerHooks` throws, for example when `module.registerHooks` does not exist on an unsupported node. This package adds no checks of its own.
- Returns `undefined`. There is no uninstall.

## `createResolveHook(options?)`

```ts
function createResolveHook(options?: MapperOptions): (
  specifier: string,
  context: { parentURL?: string },
  nextResolve: (specifier: string, context: { parentURL?: string }) => { url: string; shortCircuit?: boolean }
) => { url: string; shortCircuit?: boolean }
```

Builds the resolve hook without registering it. The return value has the shape `registerHooks({ resolve })` expects. Each call creates its own mapper and cache.

Behavior of the returned `resolve(specifier, context, nextResolve)`:

- If `specifier` starts with `"."` and `context.parentURL` is truthy: compute `new URL(specifier, context.parentURL).href` and pass it to the mapper. If the mapper returns a URL, return `{ url: mapped, shortCircuit: true }`.
- Otherwise, return `nextResolve(specifier, context)`, passing both arguments through unchanged.
- The result has no `format` on purpose. Node infers `module-typescript` or `commonjs-typescript` from the `.ts` extension and strips types. Setting `format` would suppress that and the file would load unstripped.
- Missing `parentURL` (for example the main entry) means the specifier is never mapped.
- `new URL(...)` throws a `TypeError` if `parentURL` is not a valid absolute URL. A valid non-`file:` parent such as `data:` does not throw: the mapper's default stat check catches the error from `fileURLToPath` and treats the URL as not a file.
- The hook is synchronous and does not return a promise.

```js
const resolve = createResolveHook({ isFile: url => files.has(url) });
resolve("./a.js", { parentURL: "file:///p/x.ts" }, next); // { url: "file:///p/a.ts", shortCircuit: true } when files has it
```

## `createResolveFilename(mapTs, next)`

```ts
function createResolveFilename(
  mapTs: (url: string) => string | null,
  next: (request: string, parent: { filename?: string | null } | null | undefined, isMain: boolean, options?: unknown) => string
): (request: string, parent: { filename?: string | null } | null | undefined, isMain: boolean, options?: unknown) => string
```

Builds a `Module._resolveFilename` replacement without patching the process. `mapTs` is typically the result of `createTsMapper`. `next` is the resolver to fall back to.

Behavior of the returned function (it uses `this` and forwards it):

- If `request` starts with `"."` and `parent?.filename` is truthy: compute `new URL(request, pathToFileURL(parent.filename)).href`, call `mapTs`, and if it returns a URL, return `fileURLToPath(mapped)` (a path, not a URL).
- Otherwise call `next.call(this, request, parent, isMain, options)` and return its result.
- A `parent` of `null`, `undefined` or one without `filename` always falls through to `next`.
- `mapTs` returning a non-`file:` URL would make `fileURLToPath` throw. The default mapper only returns URLs derived from its input plus an extension.

## `createTsMapper(options?)`

```ts
function createTsMapper(options?: MapperOptions): (url: string) => string | null
```

Builds the mapper from a resolved `file:` URL string to the URL of its TypeScript source, or `null` to leave the URL alone. The mapping rules are in "Mapping rules". The returned function is `mapTs(url)`.

- Input and output are URL strings (`file:///...`), not paths.
- Results are memoized in a `Map` per mapper, keyed by the exact input URL, for the life of the mapper. `null` results are cached too. There is no invalidation, so a file created or deleted after the first lookup of that URL is not noticed.
- Defaults: `isFile` is `defaultIsFile`, `skip` is `/\/(node_modules|\.fynpo)\//`. Each is applied with `??`, so `undefined` selects the default.
- `skip` is applied with `RegExp.prototype.test`. A regex with the `g` or `y` flag keeps `lastIndex` between calls, which can make results inconsistent. Use a regex without those flags.
- Does not throw by itself. Errors thrown by a custom `isFile` propagate.
- The mapper does not check the scheme of the URL. With the default `isFile`, a non-`file:` URL simply is never a file.

## `defaultIsFile`

```ts
const defaultIsFile: (url: string) => boolean
```

The default `FileCheck`. Returns `statSync(fileURLToPath(url)).isFile()`. Any error (missing file, permission, a non-`file:` URL that makes `fileURLToPath` throw) is swallowed and gives `false`. Synchronous. Symlinks are followed by `statSync`.

## `MapperOptions`

```ts
type MapperOptions = {
  isFile?: FileCheck;
  skip?: RegExp;
};
```

| option | type | default | behavior |
| --- | --- | --- | --- |
| `isFile` | `FileCheck` | `defaultIsFile` | Decides whether a candidate URL exists. Called with `file:` URL strings. Also used for the "real `.js` file wins" check. Source comment says it exists to be overridden in tests. |
| `skip` | `RegExp` | `/\/(node_modules\|\.fynpo)\//` | URLs that match are never remapped. Replacing it replaces the default, so to keep skipping `node_modules` your regex must include it. |

## `FileCheck`

```ts
type FileCheck = (url: string) => boolean;
```

Predicate that tests whether a `file:` URL points at a real file. Must be synchronous: the hooks are synchronous and a returned promise would be truthy.

## Interaction with `node_modules`

By default no URL containing `/node_modules/` or `/.fynpo/` is remapped, in either the ESM or the CJS path. Installed packages are expected to ship built JS. The test is on the resolved URL, which for a relative specifier is built from the parent's location. So relative imports between files inside an installed package are skipped, and a relative import that climbs out of `node_modules` into source is not skipped. Pass `skip: /$^/` (matches nothing) to disable skipping.

Specifiers that go through the resolver as bare names (`import "pkg"`) are never examined by this package, so a workspace package whose `exports` point at `.ts` files is resolved by node alone.

## Limits stated in source

- Resolution only. Module syntax is not converted: a `.ts` file with `import`/`export` in a package without `"type": "module"` fails in node (README: `Unexpected token 'export'`).
- No `load` hook, no source maps (node strips types by whitespace replacement so positions stay valid; README claim, not implemented here).

<!-- xenv-config v2.1.7: https://fynjs.pages.dev/ref/xenv-config.md -->

# xenv-config reference

`xenv-config` builds a config object from a spec. Each key is resolved from an env var, a user config object, or a default, and every resolved key gets a trace record that says where it came from. No runtime dependencies. ESM only (`"type": "module"`).

## Imports

```js
import xenvConfig from "xenv-config";
```

```ts
import xenvConfig, {
  type XenvConfigTrace,
  type XenvConfigSpecOption,
  type XenvConfigSpec,
  type XenvConfigEnv,
  type XenvConfigUserConfig,
  type XenvConfigMergeFn,
  type XenvConfigOptions,
  type XenvConfigResult
} from "xenv-config";
```

The only runtime export is the default export, the function `xenvConfig`. There are no named runtime exports and no subpaths (only `xenv-config/package.json`). The package has no CommonJS build, so `require("xenv-config")` as shown in the README does not apply to this version; use `import`.

Type-only exports: `XenvConfigTrace`, `XenvConfigSpecOption`, `XenvConfigSpec`, `XenvConfigEnv`, `XenvConfigUserConfig`, `XenvConfigMergeFn`, `XenvConfigOptions`, `XenvConfigResult`.

Not exported: the internal `typeGetters` table, `getEnvName` and `FoundValue`.

## `xenvConfig(spec, userConfig?, options?)`

```ts
const xenvConfig: <T = Record<string, unknown>>(
  spec: XenvConfigSpec,
  userConfig?: XenvConfigUserConfig,
  options?: XenvConfigOptions
) => XenvConfigResult<T>;
```

Resolves every key of `spec` and returns a new plain object. It is synchronous. `T` is only a type cast of the result; nothing is checked against it.

| Parameter | Type | Default | Behavior |
| --- | --- | --- | --- |
| `spec` | `XenvConfigSpec` | required | Keys are iterated with `Object.keys(spec)`. Each value is a `XenvConfigSpecOption`. `undefined` or `null` `spec` throws a `TypeError`. |
| `userConfig` | `XenvConfigUserConfig` | `{}` | Values supplied by the caller. A falsy value is replaced with `{}`. |
| `options` | `XenvConfigOptions` | none | See `XenvConfigOptions`. |

For each spec key the function:

1. Finds a value by walking the sources (see Source order).
2. If nothing is found, the key is skipped. It is absent from the result and from `__$trace__`. `post` is not called.
3. Otherwise records the trace, runs `post` if the spec has one, and stores the result.

### Source order

Three sources exist, each named by a string:

| Source name | Looks in | Found when | Trace |
| --- | --- | --- | --- |
| `"env"` | env object (`options._env` or `process.env`) | the spec has an own `env` property that names a variable that is an own property of the env object | `{ src: "env", name }` |
| `"option"` | `userConfig` | `userConfig` has the key as an own property | `{ src: "option" }` |
| `"default"` | spec | the spec has an own `default` property | `{ src: "default" }` |

The default order is `["env", "option"]`, and `"default"` is appended last. For non-json types the first source that finds a value wins and the rest are not consulted.

Reorder with `options.sources`. Example: `sources: ["option", "env"]` makes user config beat env. A source left out of the list is never consulted, except `"default"`, which is always appended. Rules:

- Presence is tested with `Object.prototype.hasOwnProperty`. A present key whose value is `undefined`, `null`, `""` or `false` still counts as found. An empty string env var is found.
- Inherited properties are not seen, on `spec` entries, `userConfig` and the env object.
- `options.sources` is mutated. The function calls `push("default")` on the array you pass in. See Quirks.
- A source name other than `"env"`, `"option"` or `"default"` throws a `TypeError` (`getters[s] is not a function`) when that key is resolved.
- The `"default"` entry: if `default` is a function it is called with no arguments and its return value is used. A function is never type-coerced.

### Env lookup

The env var name is chosen from `spec[key].env`, which is read only when `env` is an own property of the spec option.

| `env` value | Name used |
| --- | --- |
| absent, `false`, `""` | none, the env source finds nothing |
| `true` | the spec key itself |
| `string` | that exact name |
| `string[]` | the first name in the list that is an own property of the env object |

If the chosen name is not an own property of the env object, the env source finds nothing. For an array, the match requires own presence, so a present empty string wins over a later name. An empty array finds nothing.

When a name is found, the raw value is `env[name]`, then:

1. If `envMap` is set and has the raw value as an own key, the mapped value is used as is. No type coercion is applied to it (`post` still runs). The raw value is used as a property key, so a non-string raw value is converted to a string for the lookup.
2. Otherwise the raw value is coerced by the key's type (see Types).

## `XenvConfigSpecOption`

```ts
interface XenvConfigSpecOption {
  env?: string | string[] | boolean;
  envMap?: Record<string, unknown>;
  type?: string;
  default?: unknown;
  post?: (value: unknown, trace: XenvConfigTrace) => unknown;
  [extra: string]: unknown;
}
```

All fields are optional. A spec option with none of them resolves only from `userConfig`. Extra properties are allowed by the type and ignored by the code.

| Field | Type | Default | Behavior |
| --- | --- | --- | --- |
| `env` | `string \| string[] \| boolean` | none | Which env var to read. See Env lookup. |
| `envMap` | `Record<string, unknown>` | none | Maps raw env strings to final values. Only applies to the env source. Checked before type coercion. A hit skips coercion. |
| `type` | `string` | inferred | How to coerce an env string. See Types. Applies only to env values, not to `userConfig` values or defaults, except that `json` also changes how all sources combine. |
| `default` | `unknown` | none | Fallback value, or a function that returns it. Presence is tested as an own property, so `default: undefined` counts as a default and yields `undefined`. A function default is called each time `xenvConfig` runs. Not coerced. |
| `post` | `(value, trace) => unknown` | none | Runs on the resolved value after a source is found. Its return value is stored in the result. Receives the same trace object that is stored in `__$trace__`, so mutating it changes the stored trace. Not called when the key is not found. Runs for every source, including `option` and `default`. |

## Types

The type for a key is decided by `type` first, then inference:

1. `opt.type` if truthy.
2. Else `typeof opt.default` when `default` is an own property and its `typeof` is not `"function"`.
3. Else `"string"`.

Then `"object"` is rewritten to `"json"`. A type name not listed below falls back to the `string` converter. Only `"json"` (after the rewrite) triggers merge behavior.

| Type | Converter for an env value `x` | Notes |
| --- | --- | --- |
| `string` | `` `${x}` `` | Also the fallback for any unknown type name. |
| `number` | `parseInt(x, 10)` | Integer. A non-numeric string gives `NaN` (JSON serializes it as `null`). `"1.9"` gives `1`. |
| `float` | `parseFloat(x)` | |
| `boolean` | lower-cased `x` is `"true"`, `"yes"`, `"1"` or `"on"` | Case-insensitive. Any other string gives `false`. A non-string raw value throws (see Errors). |
| `truthy` | `!!x` | An empty string gives `false`. Any non-empty string, including `"false"` and `"0"`, gives `true`. |
| `json` | `JSON.parse(x)` | Needs strict JSON. `{b:90}` is invalid. See json merging. |

Inference from `default`:

| `typeof default` | Inferred type |
| --- | --- |
| `"string"` | `string` |
| `"number"` | `number` (integer, `parseInt`) |
| `"boolean"` | `boolean` |
| `"object"` | `json` (this includes `null` and arrays) |
| `"undefined"` (own property set to `undefined`) | no converter of that name, so `string` conversion |
| `"function"`, or no `default` | `string` |

An explicit `type` always overrides inference. `type: "object"` is accepted as an alias of `json`.

### json merging

When the resolved type is `json`, sources are not first-wins. Every source in `sources` (plus `"default"`) is consulted. All found values are merged.

- The env value is parsed with `JSON.parse`, or taken from `envMap` when a mapping hits.
- Merge call: `merge({}, ...values)` where values are ordered lowest priority first. With the default order the call is `merge({}, defaultValue, optionValue, envValue)`, so env wins, then option, then default. With a custom `sources`, the earlier a source is in the list, the higher its priority.
- `merge` is `options.merge` or `Object.assign` (shallow). Pass a deep merge such as lodash `merge` for nested objects.
- The result is always a new object, so defaults and user config are not mutated by the merge.
- If no source finds a value, the key is skipped.
- Values are merged as given. With `Object.assign`, a string merges as indexed characters, an array as indexed keys, and `null` or `undefined` is ignored.
- The trace is `{ src: "<names joined by comma>" }`, in `sources` order, only for the sources that found a value, for example `"env,option,default"` or `"option,default"`. It has no `name` field, even when env contributed.

## `XenvConfigOptions`

```ts
interface XenvConfigOptions {
  _env?: XenvConfigEnv;
  merge?: XenvConfigMergeFn;
  sources?: string[];
}
```

| Option | Type | Default | Behavior |
| --- | --- | --- | --- |
| `_env` | `XenvConfigEnv` (`Record<string, unknown>`) | `process.env` | Env-like object to read. Used when truthy. Values need not be strings, but `boolean` rejects non-strings. |
| `merge` | `XenvConfigMergeFn` | `Object.assign` | Called as `merge.apply(null, [{}, ...values])` for json keys. Must return the merged object. Its return value is used as the key's value. |
| `sources` | `string[]` | `["env", "option"]` | Ordered source names to consult. `"default"` is always appended, after your list. The array is mutated. |

## Result

```ts
type XenvConfigResult<T = Record<string, unknown>> = T & {
  readonly __$trace__: Record<string, XenvConfigTrace>;
};

interface XenvConfigTrace {
  src: string;
  name?: string;
}
```

The result is a plain `{}` with one property per resolved spec key, in spec key order.

- `__$trace__` is defined with `Object.defineProperty`: `enumerable: false`, `writable: false`, `configurable: false`. It is skipped by `Object.keys`, spread, `JSON.stringify` and deep-equal checks, but is read as `config.__$trace__`. Copying the object with spread or `Object.assign` drops it.
- `__$trace__[key]` exists exactly when `key` is in the result.
- `trace.src` is `"env"`, `"option"`, `"default"`, or for json keys a comma-joined list of those.
- `trace.name` is set only for non-json keys resolved from env. It holds the env var name actually used, which is useful with an `env` array.
- Values from `userConfig` and `default` are stored by reference, not cloned (non-json keys).

```js
const config = xenvConfig(
  {
    port: { env: ["APP_PORT", "PORT"], type: "number", default: 8080 },
    debug: { env: true, type: "boolean" },
    opts: { env: "OPTS", type: "json", default: { a: 1 } }
  },
  { opts: { b: 2 } },
  { _env: { PORT: "9000", OPTS: '{"c":3}' } }
);
// config: { port: 9000, opts: { a: 1, b: 2, c: 3 } }  (debug is absent)
// config.__$trace__:
//   port: { src: "env", name: "PORT" }
//   opts: { src: "env,option,default" }
```

## Errors

Nothing is caught or wrapped. All errors are thrown synchronously from `xenvConfig`.

| Condition | Error |
| --- | --- |
| `boolean` type and the env value (or `_env` value) is not a string | `AssertionError` from `node:assert`, message `xenv-config: [<key>] trying to convert non-string env value <value> to boolean.` |
| `json` type and the env string is not valid JSON | `SyntaxError` from `JSON.parse` |
| `sources` contains an unknown name | `TypeError` (`getters[s] is not a function`) |
| `spec` is `undefined` or `null` | `TypeError` from `Object.keys` |
| A function `default`, `post`, or `merge` throws | the error propagates unchanged |
| `type: "json"` where `x` is not a string, such as a non-string `_env` value | `JSON.parse` coerces it to a string first, so it may parse or throw `SyntaxError` |

Absence of a value is not an error. Missing keys are left out of the result.

## Quirks

- `options.sources` is mutated by `push("default")`. Reusing the same array in a later call adds another `"default"`. For json keys this repeats the default in the merge and in the trace (`"option,default,default"`). Pass a fresh array each call.
- `type: "json"` needs strict JSON in env. The README example `JSON_OPTION = "{b:90}"` throws `SyntaxError`; use `'{"b":90}'`.
- `default: null` or an array default infers type `json`, so the key resolves to a new merged object (`{}` for `null`, `{0: ...}` for an array), not to `null` or the array.
- `number` env values that are not integers give `NaN` rather than an error. Empty env strings give `NaN`.
- `envMap` hits are returned as is, with no coercion by `type`.
- `userConfig` values and defaults are never coerced, only env values are.
- A key present in the env object with value `undefined` counts as found. For `string` type it yields the string `"undefined"`.
- The README says the order is env, option, default. The code matches this by default, but only `"default"` is forced last. The README does not document `options.sources`.
- The README says `boolean` is `x === "true" || ...`. The code lower-cases first, so `"TRUE"` is `true`.