@naturalcycles/nodejs-lib 15.113.0 → 15.115.0

package/dist/bin/generate-build-info.js

@@ -1,11 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { _parseArgs } from '../cli/parseArgs.js';
 import { appendToBashEnv, appendToGithubEnv, appendToGithubOutput } from '../fs/json2env.js';
 import { runScript } from '../script/runScript.js';
 import { generateBuildInfo } from '../util/buildInfo.util.js';
-import { _yargs } from '../yargs/yargs.util.js';
 runScript(async () => {
-    const { dir, overrideTimestamp } = _yargs().options({
+    const { dir, overrideTimestamp } = _parseArgs({
         dir: {
             type: 'string',
             desc: 'Output directory',
@@ -14,7 +14,7 @@ runScript(async () => {
             type: 'number',
             desc: 'This unix timestamp will be used instead of "current time"',
         },
-    }).argv;
+    });
     const buildInfo = generateBuildInfo({
         overrideTimestamp: overrideTimestamp,
     });

package/dist/bin/json2env.js

@@ -1,10 +1,8 @@
+import { _parseArgs } from '../cli/parseArgs.js';
 import { json2env } from '../fs/json2env.js';
 import { runScript } from '../script/runScript.js';
-import { _yargs } from '../yargs/yargs.util.js';
 runScript(() => {
-    const { argv } = _yargs()
-        .demandCommand(1)
-        .options({
+    const argv = _parseArgs({
         prefix: {
             type: 'string',
         },
@@ -34,6 +32,8 @@ runScript(() => {
         silent: {
             type: 'boolean',
         },
+    }, {
+        minPositionals: 1,
     });
     const { _: args, prefix, saveEnvFile, bashEnv, githubEnv, fail, debug, silent } = argv;
     if (debug)

package/dist/bin/kpy.js

@@ -1,10 +1,8 @@
+import { _parseArgs } from '../cli/parseArgs.js';
 import { kpySync } from '../fs/kpy.js';
 import { runScript } from '../script/runScript.js';
-import { _yargs } from '../yargs/yargs.util.js';
 runScript(() => {
-    const { _: [baseDir, ...inputPatterns], ...opt } = _yargs()
-        .demandCommand(2)
-        .options({
+    const { _: [baseDir, ...inputPatterns], ...opt } = _parseArgs({
         silent: {
             type: 'boolean',
             desc: 'Suppress all text output',
@@ -28,9 +26,9 @@ runScript(() => {
         },
         move: {
             type: 'boolean',
-            descr: 'Move files instead of copy',
+            desc: 'Move files instead of copy',
         },
-    }).argv;
+    }, { minPositionals: 2 });
     const outputDir = inputPatterns.pop();
     /*
     console.log({
@@ -43,7 +41,7 @@ runScript(() => {
     })*/
     const kpyOpt = {
         baseDir: baseDir,
-        inputPatterns: inputPatterns,
+        inputPatterns,
         outputDir,
         ...opt,
         noOverwrite: !opt.overwrite,

package/dist/bin/secrets-decrypt.js

@@ -1,15 +1,16 @@
+import { _parseArgs } from '../cli/parseArgs.js';
 import { dimGrey } from '../colors/colors.js';
 import { runScript } from '../script/runScript.js';
 import { secretsDecrypt } from '../secret/secrets-decrypt.util.js';
-import { _yargs } from '../yargs/yargs.util.js';
 runScript(() => {
     const { dir, file, encKeyBuffer, del, jsonMode } = getDecryptCLIOptions();
     secretsDecrypt(dir, file, encKeyBuffer, del, jsonMode);
 });
 function getDecryptCLIOptions() {
-    let { dir, file, encKey, encKeyVar, del, jsonMode } = _yargs().options({
+    let { dir, file, encKey, encKeyVar, del, jsonMode } = _parseArgs({
         dir: {
-            type: 'array',
+            type: 'string',
+            array: true,
             desc: 'Directory with secrets. Can be many',
             // demandOption: true,
             default: './secret',
@@ -42,7 +43,7 @@ function getDecryptCLIOptions() {
             desc: 'JSON mode. Encrypts only json values, not the whole file',
             default: false,
         },
-    }).argv;
+    });
     if (!encKey) {
         encKey = process.env[encKeyVar];
         if (encKey) {
@@ -53,6 +54,5 @@ function getDecryptCLIOptions() {
         }
     }
     const encKeyBuffer = Buffer.from(encKey, 'base64');
-    // `as any` because @types/yargs can't handle string[] type properly
-    return { dir: dir, file, encKeyBuffer, del, jsonMode };
+    return { dir, file, encKeyBuffer, del, jsonMode };
 }

package/dist/bin/secrets-encrypt.js

@@ -1,13 +1,13 @@
+import { _parseArgs } from '../cli/parseArgs.js';
 import { dimGrey } from '../colors/colors.js';
 import { runScript } from '../script/runScript.js';
 import { secretsEncrypt } from '../secret/secrets-encrypt.util.js';
-import { _yargs } from '../yargs/yargs.util.js';
 runScript(() => {
     const { pattern, file, encKeyBuffer, del, jsonMode } = getEncryptCLIOptions();
     secretsEncrypt(pattern, file, encKeyBuffer, del, jsonMode);
 });
 function getEncryptCLIOptions() {
-    let { pattern, file, encKey, encKeyVar, del, jsonMode } = _yargs().options({
+    let { pattern, file, encKey, encKeyVar, del, jsonMode } = _parseArgs({
         pattern: {
             type: 'string',
             array: true,
@@ -44,7 +44,7 @@ function getEncryptCLIOptions() {
             desc: 'JSON mode. Encrypts only json values, not the whole file',
             default: false,
         },
-    }).argv;
+    });
     if (!encKey) {
         encKey = process.env[encKeyVar];
         if (encKey) {
@@ -55,6 +55,5 @@ function getEncryptCLIOptions() {
         }
     }
     const encKeyBuffer = Buffer.from(encKey, 'base64');
-    // `as any` because @types/yargs can't handle string[] type properly
-    return { pattern: pattern, file, encKeyBuffer, del, jsonMode };
+    return { pattern, file, encKeyBuffer, del, jsonMode };
 }

package/dist/bin/secrets-gen-key.js

@@ -1,12 +1,14 @@
 import { randomBytes } from 'node:crypto';
+import { _parseArgs } from '../cli/parseArgs.js';
 import { dimGrey } from '../colors/colors.js';
 import { runScript } from '../script/runScript.js';
-import { _yargs } from '../yargs/yargs.util.js';
 runScript(() => {
-    const { sizeBytes } = _yargs().option('sizeBytes', {
-        type: 'number',
-        default: 256,
-    }).argv;
+    const { sizeBytes } = _parseArgs({
+        sizeBytes: {
+            type: 'number',
+            default: 256,
+        },
+    });
     const key = randomBytes(sizeBytes).toString('base64');
     console.log(dimGrey('\nSECRET_ENCRYPTION_KEY:\n'));
     console.log(key, '\n');

package/dist/bin/slack-this.js

@@ -1,8 +1,8 @@
+import { _parseArgs } from '../cli/parseArgs.js';
 import { runScript } from '../script/runScript.js';
 import { SlackService } from '../slack/index.js';
-import { _yargs } from '../yargs/yargs.util.js';
 runScript(async () => {
-    const { channel, msg, username, emoji, webhook: webhookUrl, } = _yargs().options({
+    const { channel, msg, username, emoji, webhook: webhookUrl, } = _parseArgs({
         channel: {
             type: 'string',
             demandOption: true,
@@ -23,7 +23,7 @@ runScript(async () => {
             type: 'string',
             default: process.env.SLACK_WEBHOOK_URL,
         },
-    }).argv;
+    });
     if (!webhookUrl) {
         console.log(`Slack webhook is required, either via env.SLACK_WEBHOOK_URL or --webhook`);
         process.exit(1);

package/dist/cli/parseArgs.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Allowed CLI option value types.
+ */
+export type CliOptionType = 'string' | 'number' | 'boolean';
+/**
+ * Declarative definition of a single CLI option, modeled after the subset of
+ * yargs `.options()` that we actually use.
+ */
+export interface CliOption {
+    /**
+     * Value type. Defaults to `'string'` when omitted.
+     */
+    type?: CliOptionType;
+    /**
+     * Accept the flag multiple times, collecting values into an array.
+     * `--id a --id b` => `['a', 'b']`. Replaces yargs `type: 'array'`.
+     */
+    array?: boolean;
+    /**
+     * Default value, applied when the flag is not provided.
+     * Providing a non-`undefined` default makes the output field non-optional.
+     */
+    default?: string | number | boolean | readonly (string | number)[];
+    /**
+     * Mark the option as required. Throws/exits if not provided.
+     * Makes the output field non-optional.
+     */
+    demandOption?: boolean;
+    /**
+     * Restrict the value to a set of allowed values. With a `const` call (the
+     * default here) the output type is narrowed to the union of the literals.
+     */
+    choices?: readonly (string | number)[];
+    /**
+     * Help text, shown in `--help` output.
+     */
+    desc?: string;
+    /**
+     * Single-character alias, e.g. `short: 'v'` enables `-v`.
+     */
+    short?: string;
+    /**
+     * Transform the raw string value into the final value. The output type is
+     * inferred from the function's return type, so this is the way to produce
+     * branded types (e.g. `IsoDate`) or richer values (parsed numbers, JSON, ...).
+     *
+     * Applied per-element for `array` options. Receives the raw string token, so
+     * it fully owns conversion - built-in `number` coercion is not applied on top.
+     * NOT applied to `default` values: a `default` is taken to be in final form.
+     *
+     * @example transform: s => s as IsoDate
+     */
+    transform?: (value: string) => unknown;
+}
+export type CliOptions = Record<string, CliOption>;
+/**
+ * Element value type of a single option, derived from `transform` (if present,
+ * its return type wins), then `choices`, then `type`. Defaults to `string` when
+ * none narrow it (so `type` is optional).
+ */
+type ElemType<O extends CliOption> = O extends {
+    transform: (...args: any[]) => infer R;
+} ? R : O extends {
+    choices: readonly (infer C)[];
+} ? C : O extends {
+    type: 'number';
+} ? number : O extends {
+    type: 'boolean';
+} ? boolean : string;
+/**
+ * Full value type of a single option, applying `array` on top of the element
+ * type.
+ */
+type ValueType<O extends CliOption> = O extends {
+    array: true;
+} ? ElemType<O>[] : ElemType<O>;
+/**
+ * An option is "required" (non-optional in the output) when it is `demandOption`
+ * or has a non-`undefined` `default`. `NonNullable<unknown>` matches any
+ * non-null/undefined value, so `default: false | 0 | ''` correctly counts as
+ * present, while `default: process.env.X` (which may be `undefined`) stays optional.
+ */
+type IsRequired<O extends CliOption> = O extends {
+    demandOption: true;
+} ? true : O extends {
+    default: NonNullable<unknown>;
+} ? true : false;
+/**
+ * Flattens an intersection into a single object type for nicer hovers.
+ */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Output type inferred from the options config - the clean `@types/yargs@16`
+ * shape: exactly the declared keys with correct optionality, plus `_` for
+ * positionals. No `[x: string]: unknown` index signature, no camelCase/kebab
+ * key duplication (the `@types/yargs@17` noise).
+ */
+export type InferCliArgs<O extends CliOptions> = Simplify<{
+    [K in keyof O as IsRequired<O[K]> extends true ? K : never]: ValueType<O[K]>;
+} & {
+    [K in keyof O as IsRequired<O[K]> extends true ? never : K]?: ValueType<O[K]>;
+} & {
+    /** Positional arguments (yargs `_`). */
+    _: string[];
+}>;
+export interface ParseArgsOptions {
+    /**
+     * Args to parse. Defaults to `process.argv.slice(2)` (no `hideBin` needed).
+     */
+    args?: string[];
+    /**
+     * Require at least this many positional args. Replaces yargs `.demandCommand`.
+     */
+    minPositionals?: number;
+    /**
+     * Usage line shown at the top of `--help`.
+     */
+    usage?: string;
+    /**
+     * When `true`, unknown options throw a {@link ParseArgsError}.
+     * When `false` (default), unknown options are silently ignored - matching
+     * yargs' default lenient behavior. Important when several parsers read the
+     * same `process.argv` and each only knows about its own subset of options.
+     */
+    strict?: boolean;
+}
+/**
+ * Thrown by {@link _parseArgs} on invalid input (missing/invalid option,
+ * too few positionals). Unknown options are ignored, not rejected.
+ */
+export declare class ParseArgsError extends Error {
+    name: string;
+}
+/**
+ * In-house, type-inferred replacement for `yargs().options(...).argv`, built on
+ * top of node's `util.parseArgs`.
+ *
+ * @example
+ * const { dir, limit, date } = _parseArgs({
+ *   dir: { desc: 'Output directory' }, // type defaults to 'string'
+ *   limit: { type: 'number', default: 100 },
+ *   date: { transform: s => s as IsoDate }, // inferred + converted via transform
+ * })
+ * // dir?: string   limit: number   date?: IsoDate   _: string[]
+ */
+export declare function _parseArgs<const O extends CliOptions>(options: O, opt?: ParseArgsOptions): InferCliArgs<O>;
+export {};

package/dist/cli/parseArgs.js

@@ -0,0 +1,130 @@
+import { parseArgs } from 'node:util';
+/**
+ * Thrown by {@link _parseArgs} on invalid input (missing/invalid option,
+ * too few positionals). Unknown options are ignored, not rejected.
+ */
+export class ParseArgsError extends Error {
+    name = 'ParseArgsError';
+}
+/**
+ * In-house, type-inferred replacement for `yargs().options(...).argv`, built on
+ * top of node's `util.parseArgs`.
+ *
+ * @example
+ * const { dir, limit, date } = _parseArgs({
+ *   dir: { desc: 'Output directory' }, // type defaults to 'string'
+ *   limit: { type: 'number', default: 100 },
+ *   date: { transform: s => s as IsoDate }, // inferred + converted via transform
+ * })
+ * // dir?: string   limit: number   date?: IsoDate   _: string[]
+ */
+export function _parseArgs(options, opt = {}) {
+    const { args, minPositionals = 0, usage, strict = false } = opt;
+    // node's parseArgs only supports string|boolean, so `number` is parsed as a
+    // string and coerced afterwards. We also never forward `default` (parseArgs
+    // rejects e.g. a numeric default on a string-typed option) - defaults are
+    // applied by us below.
+    const nodeOptions = options['help'] ? {} : { help: { type: 'boolean', short: 'h' } };
+    for (const [name, def] of Object.entries(options)) {
+        // parseArgs rejects `undefined` for `short`/`multiple`, so only set when present
+        const nodeOption = {
+            type: def.type === 'boolean' ? 'boolean' : 'string',
+        };
+        if (def.array)
+            nodeOption.multiple = true;
+        if (def.short)
+            nodeOption.short = def.short;
+        nodeOptions[name] = nodeOption;
+    }
+    const parsed = (() => {
+        try {
+            return parseArgs({
+                args,
+                options: nodeOptions,
+                allowPositionals: true,
+                allowNegative: true, // native `--no-flag` support for booleans
+                // In non-strict mode, unknown options are collected into `values` but
+                // ignored below, since we only read declared options. See `strict` docs.
+                strict,
+            });
+        }
+        catch (err) {
+            throw new ParseArgsError(err.message);
+        }
+    })();
+    const values = parsed.values;
+    if (!options['help'] && values['help']) {
+        process.stdout.write(buildHelp(options, usage));
+        process.exit(0);
+    }
+    const result = { _: parsed.positionals };
+    for (const [name, def] of Object.entries(options)) {
+        let v = values[name];
+        // `transform` is only applied to arg-sourced values; a `default` is taken
+        // to be in final form (see CliOption.transform docs).
+        const fromArgs = v !== undefined;
+        if (v === undefined) {
+            if (def.default !== undefined) {
+                v = def.default;
+            }
+            else if (def.demandOption) {
+                throw new ParseArgsError(`Missing required option: --${name}`);
+            }
+            else {
+                continue; // leave absent
+            }
+        }
+        // normalize to array (e.g. a scalar default on an `array` option)
+        if (def.array) {
+            v = Array.isArray(v) ? v : [v];
+        }
+        // `transform` owns conversion, so built-in number coercion is skipped for it
+        if (def.type === 'number' && !def.transform) {
+            v = Array.isArray(v) ? v.map(x => toNumber(x, name)) : toNumber(v, name);
+        }
+        if (def.choices) {
+            const list = Array.isArray(v) ? v : [v];
+            for (const x of list) {
+                if (!def.choices.includes(x)) {
+                    throw new ParseArgsError(`Invalid value for --${name}: "${x}". Choices: ${def.choices.join(', ')}`);
+                }
+            }
+        }
+        if (def.transform && fromArgs) {
+            const { transform } = def;
+            v = Array.isArray(v) ? v.map(x => transform(x)) : transform(v);
+        }
+        result[name] = v;
+    }
+    if (parsed.positionals.length < minPositionals) {
+        throw new ParseArgsError(`Expected at least ${minPositionals} positional argument(s), got ${parsed.positionals.length}`);
+    }
+    return result;
+}
+function toNumber(raw, name) {
+    const n = Number(raw);
+    if (Number.isNaN(n)) {
+        throw new ParseArgsError(`Invalid number for --${name}: "${raw}"`);
+    }
+    return n;
+}
+function buildHelp(options, usage) {
+    const lines = [];
+    if (usage)
+        lines.push(usage, '');
+    lines.push('Options:');
+    for (const [name, def] of Object.entries(options)) {
+        const flag = def.short ? `-${def.short}, --${name}` : `--${name}`;
+        const type = def.type ?? 'string';
+        const meta = [`[${def.array ? `${type}[]` : type}]`];
+        if (def.demandOption)
+            meta.push('[required]');
+        if (def.default !== undefined)
+            meta.push(`[default: ${JSON.stringify(def.default)}]`);
+        if (def.choices)
+            meta.push(`[choices: ${def.choices.join(', ')}]`);
+        lines.push(`  ${flag}  ${meta.join(' ')}${def.desc ? `  ${def.desc}` : ''}`);
+    }
+    lines.push('  -h, --help  Show help');
+    return `${lines.join('\n')}\n`;
+}

package/dist/validation/ajv/jSchema.d.ts

@@ -64,7 +64,7 @@ export declare const j: {
     };
     array<OUT, Opt>(itemSchema: JSchema<OUT, Opt>): JArray<OUT, Opt>;
     tuple<const S extends JSchema<any, any>[]>(items: S): JTuple<S>;
-    set<OUT_1, Opt_1>(itemSchema: JSchema<OUT_1, Opt_1>): JSet2Builder<OUT_1, Opt_1>;
+    set<OUT, Opt>(itemSchema: JSchema<OUT, Opt>): JSet2Builder<OUT, Opt>;
     buffer(): JBuilder<Buffer, false>;
     enum<const T extends readonly (string | number | boolean | null)[] | StringEnum | NumberEnum>(input: T, opt?: JsonBuilderRuleOpt): JEnum<T extends readonly (infer U)[] ? U : T extends StringEnum ? T[keyof T] : T extends NumberEnum ? T[keyof T] : never>;
     /**
@@ -90,7 +90,7 @@ export declare const j: {
      * Use `anyOf` when schemas may overlap (e.g., AccountId | PartnerId with same format).
      * Use `oneOf` when schemas are mutually exclusive.
      */
-    anyOf<B_1 extends readonly JSchema<any, boolean>[]>(items: [...B_1]): JBuilder<BuilderOutUnion<B_1>, false>;
+    anyOf<B extends readonly JSchema<any, boolean>[]>(items: [...B]): JBuilder<BuilderOutUnion<B>, false>;
     /**
      * Pick validation schema for an object based on the value of a specific property.
      *
@@ -112,7 +112,7 @@ export declare const j: {
      * const schema = j.anyOfThese([successSchema, errorSchema])
      * ```
      */
-    anyOfThese<B_2 extends readonly JSchema<any, boolean>[]>(items: [...B_2]): JBuilder<BuilderOutUnion<B_2>, false>;
+    anyOfThese<B extends readonly JSchema<any, boolean>[]>(items: [...B]): JBuilder<BuilderOutUnion<B>, false>;
     and(): {
         silentBob: () => never;
     };
@@ -123,10 +123,10 @@ export declare const j: {
      *
      * Optionally accepts a custom Ajv instance and/or inputName for error messages.
      */
-    fromSchema<OUT_2>(schema: JsonSchema<OUT_2>, cfg?: {
+    fromSchema<OUT>(schema: JsonSchema<OUT>, cfg?: {
         ajv?: Ajv;
         inputName?: string;
-    }): JSchema<OUT_2, false>;
+    }): JSchema<OUT, false>;
 };
 export declare const HIDDEN_AJV_SCHEMA: unique symbol;
 export type WithCachedAjvSchema<Base, OUT> = Base & {

package/dist/zip/zipReader.d.ts

@@ -77,6 +77,11 @@ export declare class ZipReader implements AsyncDisposable {
      */
     [Symbol.asyncDispose](): Promise<void>;
     private assertReadable;
+    /**
+     * Read the local file header to locate the start of the entry's data.
+     * The local header's name/extra-field lengths can differ from the central
+     * directory's, so this must be read per entry.
+     */
     private findFileDataStart;
 }
 /**

package/dist/zip/zipWriter.d.ts

@@ -98,9 +98,16 @@ export declare class ZipWriter implements AsyncDisposable {
     private assertWritable;
     /** Build the in-memory representation of an entry from its name and options. */
     private createEntry;
+    /** Write an entry whose CRC and sizes are already known: header, name, data, no descriptor. */
     private writeKnownEntry;
+    /** Write a streamed entry: header with bit 3 set, streamed data, then a data descriptor. */
     private pumpEntry;
+    /**
+     * Pipe `source` to the output, computing the CRC-32 and uncompressed size on
+     * the way in, optionally deflating, and counting the compressed bytes written.
+     */
     private pumpData;
+    /** Write a buffer to the output, tracking the byte offset and respecting backpressure. */
     private write;
     private waitDrain;
     private finishStream;

package/package.json

@@ -1,27 +1,26 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.113.0",
+  "version": "15.115.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@standard-schema/spec": "^1",
     "@types/jsonwebtoken": "^9",
-    "@types/yargs": "^16",
     "ajv": "^8",
     "ansis": "^4",
     "jsonwebtoken": "^9",
     "lru-cache": "^11",
     "tinyglobby": "^0.2",
     "tslib": "^2",
-    "yaml": "^2",
-    "yargs": "^18"
+    "yaml": "^2"
   },
   "devDependencies": {
-    "@typescript/native-preview": "beta",
+    "typescript": "rc",
     "@naturalcycles/dev-lib": "18.4.2"
   },
   "exports": {
     ".": "./dist/index.js",
+    "./args": "./dist/cli/parseArgs.js",
     "./lruMemoCache": "./dist/cache/lruMemoCache.js",
     "./colors": "./dist/colors/colors.js",
     "./csv": "./dist/csv/index.js",
@@ -36,7 +35,6 @@
     "./slack": "./dist/slack/index.js",
     "./stream": "./dist/stream/index.js",
     "./stream/*.js": "./dist/stream/*.js",
-    "./yargs": "./dist/yargs/yargs.util.js",
     "./ajv": "./dist/validation/ajv/index.js",
     "./zip": "./dist/zip/index.js"
   },

package/src/bin/generate-build-info.ts

@@ -1,13 +1,13 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import type { UnixTimestamp } from '@naturalcycles/js-lib/types'
+import { _parseArgs } from '../cli/parseArgs.js'
 import { appendToBashEnv, appendToGithubEnv, appendToGithubOutput } from '../fs/json2env.js'
 import { runScript } from '../script/runScript.js'
 import { generateBuildInfo } from '../util/buildInfo.util.js'
-import { _yargs } from '../yargs/yargs.util.js'
 
 runScript(async () => {
-  const { dir, overrideTimestamp } = _yargs().options({
+  const { dir, overrideTimestamp } = _parseArgs({
     dir: {
       type: 'string',
       desc: 'Output directory',
@@ -16,7 +16,7 @@ runScript(async () => {
       type: 'number',
       desc: 'This unix timestamp will be used instead of "current time"',
     },
-  }).argv
+  })
 
   const buildInfo = generateBuildInfo({
     overrideTimestamp: overrideTimestamp as UnixTimestamp,

package/src/bin/json2env.ts

@@ -1,11 +1,10 @@
+import { _parseArgs } from '../cli/parseArgs.js'
 import { json2env } from '../fs/json2env.js'
 import { runScript } from '../script/runScript.js'
-import { _yargs } from '../yargs/yargs.util.js'
 
 runScript(() => {
-  const { argv } = _yargs()
-    .demandCommand(1)
-    .options({
+  const argv = _parseArgs(
+    {
       prefix: {
         type: 'string',
       },
@@ -35,12 +34,16 @@ runScript(() => {
       silent: {
         type: 'boolean',
       },
-    })
+    },
+    {
+      minPositionals: 1,
+    },
+  )
 
   const { _: args, prefix, saveEnvFile, bashEnv, githubEnv, fail, debug, silent } = argv
   if (debug) console.log({ argv })
 
-  const jsonPath = args[0] as string
+  const jsonPath = args[0]!
 
   json2env({
     jsonPath,

package/src/bin/kpy.ts

@@ -1,14 +1,13 @@
+import { _parseArgs } from '../cli/parseArgs.js'
 import { kpySync } from '../fs/kpy.js'
 import { runScript } from '../script/runScript.js'
-import { _yargs } from '../yargs/yargs.util.js'
 
 runScript(() => {
   const {
     _: [baseDir, ...inputPatterns],
     ...opt
-  } = _yargs()
-    .demandCommand(2)
-    .options({
+  } = _parseArgs(
+    {
       silent: {
         type: 'boolean',
         desc: 'Suppress all text output',
@@ -32,11 +31,13 @@ runScript(() => {
       },
       move: {
         type: 'boolean',
-        descr: 'Move files instead of copy',
+        desc: 'Move files instead of copy',
       },
-    }).argv
+    },
+    { minPositionals: 2 },
+  )
 
-  const outputDir = inputPatterns.pop() as string
+  const outputDir = inputPatterns.pop()!
 
   /*
   console.log({
@@ -49,8 +50,8 @@ runScript(() => {
   })*/
 
   const kpyOpt = {
-    baseDir: baseDir as string,
-    inputPatterns: inputPatterns as string[],
+    baseDir: baseDir!,
+    inputPatterns,
     outputDir,
     ...opt,
     noOverwrite: !opt.overwrite,

package/src/bin/secrets-decrypt.ts

@@ -1,8 +1,8 @@
+import { _parseArgs } from '../cli/parseArgs.js'
 import { dimGrey } from '../colors/colors.js'
 import { runScript } from '../script/runScript.js'
 import type { DecryptCLIOptions } from '../secret/secrets-decrypt.util.js'
 import { secretsDecrypt } from '../secret/secrets-decrypt.util.js'
-import { _yargs } from '../yargs/yargs.util.js'
 
 runScript(() => {
   const { dir, file, encKeyBuffer, del, jsonMode } = getDecryptCLIOptions()
@@ -11,9 +11,10 @@ runScript(() => {
 })
 
 function getDecryptCLIOptions(): DecryptCLIOptions {
-  let { dir, file, encKey, encKeyVar, del, jsonMode } = _yargs().options({
+  let { dir, file, encKey, encKeyVar, del, jsonMode } = _parseArgs({
     dir: {
-      type: 'array',
+      type: 'string',
+      array: true,
       desc: 'Directory with secrets. Can be many',
       // demandOption: true,
       default: './secret',
@@ -46,7 +47,7 @@ function getDecryptCLIOptions(): DecryptCLIOptions {
       desc: 'JSON mode. Encrypts only json values, not the whole file',
       default: false,
     },
-  }).argv
+  })
 
   if (!encKey) {
     encKey = process.env[encKeyVar]
@@ -62,6 +63,5 @@ function getDecryptCLIOptions(): DecryptCLIOptions {
 
   const encKeyBuffer = Buffer.from(encKey, 'base64')
 
-  // `as any` because @types/yargs can't handle string[] type properly
-  return { dir: dir as any, file, encKeyBuffer, del, jsonMode }
+  return { dir, file, encKeyBuffer, del, jsonMode }
 }

package/src/bin/secrets-encrypt.ts

@@ -1,8 +1,8 @@
+import { _parseArgs } from '../cli/parseArgs.js'
 import { dimGrey } from '../colors/colors.js'
 import { runScript } from '../script/runScript.js'
 import type { EncryptCLIOptions } from '../secret/secrets-encrypt.util.js'
 import { secretsEncrypt } from '../secret/secrets-encrypt.util.js'
-import { _yargs } from '../yargs/yargs.util.js'
 
 runScript(() => {
   const { pattern, file, encKeyBuffer, del, jsonMode } = getEncryptCLIOptions()
@@ -11,7 +11,7 @@ runScript(() => {
 })
 
 function getEncryptCLIOptions(): EncryptCLIOptions {
-  let { pattern, file, encKey, encKeyVar, del, jsonMode } = _yargs().options({
+  let { pattern, file, encKey, encKeyVar, del, jsonMode } = _parseArgs({
     pattern: {
       type: 'string',
       array: true,
@@ -48,7 +48,7 @@ function getEncryptCLIOptions(): EncryptCLIOptions {
       desc: 'JSON mode. Encrypts only json values, not the whole file',
       default: false,
     },
-  }).argv
+  })
 
   if (!encKey) {
     encKey = process.env[encKeyVar]
@@ -64,6 +64,5 @@ function getEncryptCLIOptions(): EncryptCLIOptions {
 
   const encKeyBuffer = Buffer.from(encKey, 'base64')
 
-  // `as any` because @types/yargs can't handle string[] type properly
-  return { pattern: pattern as any, file, encKeyBuffer, del, jsonMode }
+  return { pattern, file, encKeyBuffer, del, jsonMode }
 }

package/src/bin/secrets-gen-key.ts

@@ -1,13 +1,15 @@
 import { randomBytes } from 'node:crypto'
+import { _parseArgs } from '../cli/parseArgs.js'
 import { dimGrey } from '../colors/colors.js'
 import { runScript } from '../script/runScript.js'
-import { _yargs } from '../yargs/yargs.util.js'
 
 runScript(() => {
-  const { sizeBytes } = _yargs().option('sizeBytes', {
-    type: 'number',
-    default: 256,
-  }).argv
+  const { sizeBytes } = _parseArgs({
+    sizeBytes: {
+      type: 'number',
+      default: 256,
+    },
+  })
 
   const key = randomBytes(sizeBytes).toString('base64')
 

package/src/bin/slack-this.ts

@@ -1,6 +1,6 @@
+import { _parseArgs } from '../cli/parseArgs.js'
 import { runScript } from '../script/runScript.js'
 import { SlackService } from '../slack/index.js'
-import { _yargs } from '../yargs/yargs.util.js'
 
 runScript(async () => {
   const {
@@ -9,7 +9,7 @@ runScript(async () => {
     username,
     emoji,
     webhook: webhookUrl,
-  } = _yargs().options({
+  } = _parseArgs({
     channel: {
       type: 'string',
       demandOption: true,
@@ -30,7 +30,7 @@ runScript(async () => {
       type: 'string',
       default: process.env.SLACK_WEBHOOK_URL,
     },
-  }).argv
+  })
 
   if (!webhookUrl) {
     console.log(`Slack webhook is required, either via env.SLACK_WEBHOOK_URL or --webhook`)

package/src/cli/parseArgs.ts

@@ -0,0 +1,284 @@
+import { parseArgs } from 'node:util'
+
+/**
+ * Allowed CLI option value types.
+ */
+export type CliOptionType = 'string' | 'number' | 'boolean'
+
+/**
+ * Declarative definition of a single CLI option, modeled after the subset of
+ * yargs `.options()` that we actually use.
+ */
+export interface CliOption {
+  /**
+   * Value type. Defaults to `'string'` when omitted.
+   */
+  type?: CliOptionType
+  /**
+   * Accept the flag multiple times, collecting values into an array.
+   * `--id a --id b` => `['a', 'b']`. Replaces yargs `type: 'array'`.
+   */
+  array?: boolean
+  /**
+   * Default value, applied when the flag is not provided.
+   * Providing a non-`undefined` default makes the output field non-optional.
+   */
+  default?: string | number | boolean | readonly (string | number)[]
+  /**
+   * Mark the option as required. Throws/exits if not provided.
+   * Makes the output field non-optional.
+   */
+  demandOption?: boolean
+  /**
+   * Restrict the value to a set of allowed values. With a `const` call (the
+   * default here) the output type is narrowed to the union of the literals.
+   */
+  choices?: readonly (string | number)[]
+  /**
+   * Help text, shown in `--help` output.
+   */
+  desc?: string
+  /**
+   * Single-character alias, e.g. `short: 'v'` enables `-v`.
+   */
+  short?: string
+  /**
+   * Transform the raw string value into the final value. The output type is
+   * inferred from the function's return type, so this is the way to produce
+   * branded types (e.g. `IsoDate`) or richer values (parsed numbers, JSON, ...).
+   *
+   * Applied per-element for `array` options. Receives the raw string token, so
+   * it fully owns conversion - built-in `number` coercion is not applied on top.
+   * NOT applied to `default` values: a `default` is taken to be in final form.
+   *
+   * @example transform: s => s as IsoDate
+   */
+  transform?: (value: string) => unknown
+}
+
+export type CliOptions = Record<string, CliOption>
+
+/**
+ * Element value type of a single option, derived from `transform` (if present,
+ * its return type wins), then `choices`, then `type`. Defaults to `string` when
+ * none narrow it (so `type` is optional).
+ */
+type ElemType<O extends CliOption> = O extends { transform: (...args: any[]) => infer R }
+  ? R
+  : O extends { choices: readonly (infer C)[] }
+    ? C
+    : O extends { type: 'number' }
+      ? number
+      : O extends { type: 'boolean' }
+        ? boolean
+        : string
+
+/**
+ * Full value type of a single option, applying `array` on top of the element
+ * type.
+ */
+type ValueType<O extends CliOption> = O extends { array: true } ? ElemType<O>[] : ElemType<O>
+
+/**
+ * An option is "required" (non-optional in the output) when it is `demandOption`
+ * or has a non-`undefined` `default`. `NonNullable<unknown>` matches any
+ * non-null/undefined value, so `default: false | 0 | ''` correctly counts as
+ * present, while `default: process.env.X` (which may be `undefined`) stays optional.
+ */
+type IsRequired<O extends CliOption> = O extends { demandOption: true }
+  ? true
+  : O extends { default: NonNullable<unknown> }
+    ? true
+    : false
+
+/**
+ * Flattens an intersection into a single object type for nicer hovers.
+ */
+type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+/**
+ * Output type inferred from the options config - the clean `@types/yargs@16`
+ * shape: exactly the declared keys with correct optionality, plus `_` for
+ * positionals. No `[x: string]: unknown` index signature, no camelCase/kebab
+ * key duplication (the `@types/yargs@17` noise).
+ */
+export type InferCliArgs<O extends CliOptions> = Simplify<
+  {
+    [K in keyof O as IsRequired<O[K]> extends true ? K : never]: ValueType<O[K]>
+  } & {
+    [K in keyof O as IsRequired<O[K]> extends true ? never : K]?: ValueType<O[K]>
+  } & {
+    /** Positional arguments (yargs `_`). */
+    _: string[]
+  }
+>
+
+export interface ParseArgsOptions {
+  /**
+   * Args to parse. Defaults to `process.argv.slice(2)` (no `hideBin` needed).
+   */
+  args?: string[]
+  /**
+   * Require at least this many positional args. Replaces yargs `.demandCommand`.
+   */
+  minPositionals?: number
+  /**
+   * Usage line shown at the top of `--help`.
+   */
+  usage?: string
+  /**
+   * When `true`, unknown options throw a {@link ParseArgsError}.
+   * When `false` (default), unknown options are silently ignored - matching
+   * yargs' default lenient behavior. Important when several parsers read the
+   * same `process.argv` and each only knows about its own subset of options.
+   */
+  strict?: boolean
+}
+
+/**
+ * Thrown by {@link _parseArgs} on invalid input (missing/invalid option,
+ * too few positionals). Unknown options are ignored, not rejected.
+ */
+export class ParseArgsError extends Error {
+  override name = 'ParseArgsError'
+}
+
+/**
+ * In-house, type-inferred replacement for `yargs().options(...).argv`, built on
+ * top of node's `util.parseArgs`.
+ *
+ * @example
+ * const { dir, limit, date } = _parseArgs({
+ *   dir: { desc: 'Output directory' }, // type defaults to 'string'
+ *   limit: { type: 'number', default: 100 },
+ *   date: { transform: s => s as IsoDate }, // inferred + converted via transform
+ * })
+ * // dir?: string   limit: number   date?: IsoDate   _: string[]
+ */
+export function _parseArgs<const O extends CliOptions>(
+  options: O,
+  opt: ParseArgsOptions = {},
+): InferCliArgs<O> {
+  const { args, minPositionals = 0, usage, strict = false } = opt
+
+  // node's parseArgs only supports string|boolean, so `number` is parsed as a
+  // string and coerced afterwards. We also never forward `default` (parseArgs
+  // rejects e.g. a numeric default on a string-typed option) - defaults are
+  // applied by us below.
+  const nodeOptions: Record<
+    string,
+    { type: 'string' | 'boolean'; multiple?: boolean; short?: string }
+  > = options['help'] ? {} : { help: { type: 'boolean', short: 'h' } }
+  for (const [name, def] of Object.entries(options)) {
+    // parseArgs rejects `undefined` for `short`/`multiple`, so only set when present
+    const nodeOption: { type: 'string' | 'boolean'; multiple?: boolean; short?: string } = {
+      type: def.type === 'boolean' ? 'boolean' : 'string',
+    }
+    if (def.array) nodeOption.multiple = true
+    if (def.short) nodeOption.short = def.short
+    nodeOptions[name] = nodeOption
+  }
+
+  const parsed = (() => {
+    try {
+      return parseArgs({
+        args,
+        options: nodeOptions,
+        allowPositionals: true,
+        allowNegative: true, // native `--no-flag` support for booleans
+        // In non-strict mode, unknown options are collected into `values` but
+        // ignored below, since we only read declared options. See `strict` docs.
+        strict,
+      })
+    } catch (err) {
+      throw new ParseArgsError((err as Error).message)
+    }
+  })()
+
+  const values = parsed.values as Record<string, unknown>
+
+  if (!options['help'] && values['help']) {
+    process.stdout.write(buildHelp(options, usage))
+    process.exit(0)
+  }
+
+  const result: Record<string, unknown> = { _: parsed.positionals }
+
+  for (const [name, def] of Object.entries(options)) {
+    let v = values[name]
+    // `transform` is only applied to arg-sourced values; a `default` is taken
+    // to be in final form (see CliOption.transform docs).
+    const fromArgs = v !== undefined
+
+    if (v === undefined) {
+      if (def.default !== undefined) {
+        v = def.default
+      } else if (def.demandOption) {
+        throw new ParseArgsError(`Missing required option: --${name}`)
+      } else {
+        continue // leave absent
+      }
+    }
+
+    // normalize to array (e.g. a scalar default on an `array` option)
+    if (def.array) {
+      v = Array.isArray(v) ? v : [v]
+    }
+
+    // `transform` owns conversion, so built-in number coercion is skipped for it
+    if (def.type === 'number' && !def.transform) {
+      v = Array.isArray(v) ? v.map(x => toNumber(x, name)) : toNumber(v, name)
+    }
+
+    if (def.choices) {
+      const list = Array.isArray(v) ? v : [v]
+      for (const x of list) {
+        if (!def.choices.includes(x as string | number)) {
+          throw new ParseArgsError(
+            `Invalid value for --${name}: "${x}". Choices: ${def.choices.join(', ')}`,
+          )
+        }
+      }
+    }
+
+    if (def.transform && fromArgs) {
+      const { transform } = def
+      v = Array.isArray(v) ? v.map(x => transform(x as string)) : transform(v as string)
+    }
+
+    result[name] = v
+  }
+
+  if (parsed.positionals.length < minPositionals) {
+    throw new ParseArgsError(
+      `Expected at least ${minPositionals} positional argument(s), got ${parsed.positionals.length}`,
+    )
+  }
+
+  return result as InferCliArgs<O>
+}
+
+function toNumber(raw: unknown, name: string): number {
+  const n = Number(raw)
+  if (Number.isNaN(n)) {
+    throw new ParseArgsError(`Invalid number for --${name}: "${raw}"`)
+  }
+  return n
+}
+
+function buildHelp(options: CliOptions, usage?: string): string {
+  const lines: string[] = []
+  if (usage) lines.push(usage, '')
+  lines.push('Options:')
+  for (const [name, def] of Object.entries(options)) {
+    const flag = def.short ? `-${def.short}, --${name}` : `--${name}`
+    const type = def.type ?? 'string'
+    const meta = [`[${def.array ? `${type}[]` : type}]`]
+    if (def.demandOption) meta.push('[required]')
+    if (def.default !== undefined) meta.push(`[default: ${JSON.stringify(def.default)}]`)
+    if (def.choices) meta.push(`[choices: ${def.choices.join(', ')}]`)
+    lines.push(`  ${flag}  ${meta.join(' ')}${def.desc ? `  ${def.desc}` : ''}`)
+  }
+  lines.push('  -h, --help  Show help')
+  return `${lines.join('\n')}\n`
+}

package/src/stream/pipeline.ts

@@ -341,7 +341,7 @@ export class Pipeline<T = unknown> {
       }),
     )
     this.objectMode = false
-    return this as any
+    return this
   }
 
   gunzip(this: Pipeline<Uint8Array>, opt?: ZlibOptions): Pipeline<Uint8Array> {
@@ -352,7 +352,7 @@ export class Pipeline<T = unknown> {
       }),
     )
     this.objectMode = false
-    return this as any
+    return this
   }
 
   zstdCompress(
@@ -362,7 +362,7 @@ export class Pipeline<T = unknown> {
   ): Pipeline<Uint8Array> {
     this.transforms.push(createZstdCompress(zip2.zstdLevelToOptions(level, opt)))
     this.objectMode = false
-    return this as any
+    return this
   }
 
   zstdDecompress(this: Pipeline<Uint8Array>, opt?: ZstdOptions): Pipeline<Uint8Array> {
@@ -373,7 +373,7 @@ export class Pipeline<T = unknown> {
       }),
     )
     this.objectMode = false
-    return this as any
+    return this
   }
 
   async toArray(opt?: TransformOptions): Promise<T[]> {

package/src/validation/ajv/from-data/generateJsonSchemaFromData.ts

@@ -14,7 +14,7 @@ type Type = PrimitiveType | 'array' | 'object'
 export function generateJsonSchemaFromData<T extends AnyObject = AnyObject>(
   rows: AnyObject[],
 ): JsonSchema<T> {
-  return objectToJsonSchema<T>(rows as any)
+  return objectToJsonSchema<T>(rows)
 }
 
 function objectToJsonSchema<T extends AnyObject>(rows: AnyObject[]): JsonSchema<T> {
@@ -68,25 +68,25 @@ function mergeTypes(types: Type[], samples: any[]): JsonSchema | undefined {
   if (type === 'null') {
     return {
       type: 'null',
-    } as JsonSchema
+    }
   }
 
   if (type === 'boolean') {
     return {
       type: 'boolean',
-    } as JsonSchema
+    }
   }
 
   if (type === 'string') {
     return {
       type: 'string',
-    } as JsonSchema
+    }
   }
 
   if (type === 'number') {
     return {
       type: 'number',
-    } as JsonSchema
+    }
   }
 
   if (type === 'object') {
@@ -102,7 +102,7 @@ function mergeTypes(types: Type[], samples: any[]): JsonSchema | undefined {
     return {
       type: 'array',
       items: mergeTypes(itemTypes, items),
-    } as JsonSchema
+    }
   }
 }
 

package/dist/yargs/yargs.util.d.ts

@@ -1,6 +0,0 @@
-import yargs from 'yargs';
-/**
- * Quick yargs helper to make it work in esm.
- * It also allows to not have yargs and `@types/yargs` to be declared as dependencies.
- */
-export declare function _yargs(): yargs.Argv<{}>;

package/dist/yargs/yargs.util.js

@@ -1,11 +0,0 @@
-import yargs from 'yargs';
-// @ts-expect-error yargs types disagree with runtime
-import { hideBin } from 'yargs/helpers';
-/**
- * Quick yargs helper to make it work in esm.
- * It also allows to not have yargs and `@types/yargs` to be declared as dependencies.
- */
-// oxlint-disable-next-line @typescript-eslint/explicit-function-return-type
-export function _yargs() {
-    return yargs(hideBin(process.argv));
-}

package/src/yargs/yargs.util.ts

@@ -1,12 +0,0 @@
-import yargs from 'yargs'
-// @ts-expect-error yargs types disagree with runtime
-import { hideBin } from 'yargs/helpers'
-
-/**
- * Quick yargs helper to make it work in esm.
- * It also allows to not have yargs and `@types/yargs` to be declared as dependencies.
- */
-// oxlint-disable-next-line @typescript-eslint/explicit-function-return-type
-export function _yargs() {
-  return yargs(hideBin(process.argv))
-}