hanzio 3.2.0 → 3.3.0

package/README.md

@@ -9,7 +9,7 @@ logging.
 
 ```bash
 bun add hanzio
-# only needed for hanzio/zod, hanzio/api-wrapper, hanzio/secrets and hanzio/cli
+# only needed for hanzio/zod, hanzio/api-wrapper, hanzio/secrets and hanzio/cli commands with an input
 bun add zod
 ```
 
@@ -50,6 +50,7 @@ subpath export:
 | `hanzio/format` | Cached `Intl` formatters: numbers, currency, bytes, durations, dates, relative time ([docs](src/format/README.md)) |
 | `hanzio/format/phone` | Phone numbers as people read them; needs `libphonenumber-js` ([docs](src/format/README.md#phone-numbers)) |
 | `hanzio/crypto` | Web Crypto helpers: constant-time compare, HMAC/webhook verification, sealing, tokens ([docs](src/crypto/README.md)) |
+| `hanzio/crypto/node` | Synchronous sealing on `node:crypto`, same envelope as `hanzio/crypto` ([docs](src/crypto/README.md#synchronous-sealing-hanziocryptonode)) |
 | `hanzio/storage` | Typed localStorage/AsyncStorage items that never throw ([docs](src/storage/README.md)) |
 | `hanzio/i18n` | Typed `{placeholder}` interpolation, translators, `TypedTranslate` and locale registries ([docs](src/i18n/README.md)) |
 | `hanzio/i18n/vue` | vue-i18n setup with locale persistence and a typed composer ([docs](src/i18n/README.md#vue-i18n)) |

package/dist/cli/fields.d.ts

@@ -1,6 +1,8 @@
-import { z } from 'zod';
-/** Thrown for bad argv. The CLI prints it with a `--help` hint and exits 2. */
+import type { z } from 'zod';
+/** Thrown for bad argv; `cli.run()` turns it into a `CliUsageError`. */
 export declare class UsageError extends Error {
+    readonly kind: 'missing-command' | 'unknown-command' | 'invalid-arguments';
+    constructor(message: string, kind?: 'missing-command' | 'unknown-command' | 'invalid-arguments');
 }
 /** One key of an input or globals object, read as a flag or a positional. */
 export type Field = {
@@ -13,17 +15,25 @@ export type Field = {
     hasDefault: boolean;
     defaultValue: unknown;
     description?: string;
+    /** One-letter short flag. */
     alias?: string;
-    env?: string;
+    /** Extra long flag names, from multi-character aliases. */
+    aliases: string[];
+    env: string[];
+    /** `--name` alone is `true`, `--name=value` is the value. */
+    optionalValue: boolean;
     choices?: string[];
 };
+/** The `parseArgs` option name. A `noX` key is its own flag, never `--x` negated. */
+export declare const optionName: (field: Field) => string;
 export declare function fieldsOf(schema: z.ZodObject | undefined): Field[];
 /**
  * Builds the raw object Zod validates: flag values and positionals by key,
- * numbers coerced, `.meta({ env })` as fallback, and a missing required
- * boolean or array read as `false` or `[]`.
+ * numbers coerced, `.meta({ env })` as fallback (blank variables count as
+ * unset), and a missing required boolean or array read as `false` or `[]`.
+ * Extra positionals are a usage error unless `strict` is false.
  */
-export declare function readFields(fields: Field[], values: Record<string, string | boolean | (string | boolean)[] | undefined>, positionals: string[], env: Record<string, string | undefined>): Record<string, unknown>;
+export declare function readFields(fields: Field[], values: Record<string, string | boolean | (string | boolean)[] | undefined>, positionals: string[], env: Record<string, string | undefined>, strict?: boolean): Record<string, unknown>;
 export declare function fieldLabel(field: Field): string;
 export declare function fieldHelp(field: Field): string;
 /** Closest candidate within a few edits, for "Did you mean ...?" hints. */

package/dist/cli/index.d.ts

@@ -3,10 +3,16 @@ declare module 'zod' {
     interface GlobalMeta {
         /** hanzio/cli: read this key from positional arguments, in key order. */
         positional?: boolean;
-        /** hanzio/cli: one-letter short flag, e.g. `'r'` for `-r`. */
-        alias?: string;
-        /** hanzio/cli: environment variable read when the flag is missing. */
-        env?: string;
+        /**
+         * hanzio/cli: other names for the flag: one letter for `-r`, longer for
+         * `--region-name`.
+         */
+        alias?: string | readonly string[];
+        /**
+         * hanzio/cli: environment variables read in order when the flag is
+         * missing. Blank values count as unset.
+         */
+        env?: string | readonly string[];
     }
 }
 declare const commandKey: unique symbol;
@@ -30,6 +36,25 @@ export type CliIO = {
     stderr?: CliWriter;
     env?: Record<string, string | undefined>;
 };
+/**
+ * Bad arguments, passed to `defineCli({ onError })`. `help` is the help of
+ * the group or command the arguments were for, ending in a newline.
+ */
+export declare class CliUsageError extends CliError {
+    readonly kind: 'missing-command' | 'unknown-command' | 'invalid-arguments';
+    readonly path: readonly string[];
+    readonly help: string;
+    constructor(message: string, details: Pick<CliUsageError, 'kind' | 'path' | 'help'>);
+}
+/** What `defineCli({ onError })` gets besides the error. */
+export type CliErrorIO = {
+    readonly stdout: CliWriter;
+    readonly stderr: CliWriter;
+    readonly env: Record<string, string | undefined>;
+    readonly json: boolean;
+    /** Prints the error the default way and returns its exit code. */
+    print(): number;
+};
 export type CommandContext<C = unknown> = {
     /** What `defineCli({ context })` returned. */
     readonly context: C;
@@ -52,8 +77,11 @@ export type CommandContext<C = unknown> = {
 export type Command<C = unknown> = {
     readonly [commandKey]: true;
     readonly description?: string;
+    readonly usage?: string;
+    readonly examples?: readonly string[];
     readonly input?: AnyObject;
     readonly raw?: boolean;
+    readonly strict?: boolean;
     readonly run?: (input: never, ctx: CommandContext<C>) => unknown;
     readonly output?: (result: never, ctx: CommandContext<C>) => unknown;
     readonly load?: LazyCommand<C>;
@@ -88,6 +116,22 @@ export type CliConfig<G extends AnyObject, C> = {
     }) => unknown;
     /** A command (single-command CLI) or nested groups of commands. */
     commands: CommandNode<C>;
+    /**
+     * The root command to run when no command name is given, or when the first
+     * argument is a flag that isn't a global. A function reads it from `env`.
+     */
+    defaultCommand?: string | ((env: Record<string, string | undefined>) => string | undefined);
+    /** Resolves a command name the group doesn't have, e.g. from config. */
+    unknownCommand?: (name: string, path: readonly string[]) => CommandNode<C> | undefined | Promise<CommandNode<C> | undefined>;
+    /** Rewrites a help screen; `path` is `[]` for the root. */
+    help?: (text: string, info: {
+        path: readonly string[];
+    }) => string | Promise<string>;
+    /**
+     * Handles every error, usage errors included (`CliUsageError`). Return the
+     * exit code, or `undefined` for `io.print()`.
+     */
+    onError?: (error: unknown, io: CliErrorIO) => number | undefined | Promise<number | undefined>;
 } & (undefined extends C ? {
     context?: ContextFunction<G, C>;
 } : {
@@ -101,14 +145,22 @@ type ContextFunction<G extends AnyObject, C> = (globals: z.output<G>) => C | Pro
  * printed by `output` (default: strings as-is, anything else as JSON).
  */
 export declare function defineCommand<S extends AnyObject = EmptyObject, R = unknown, C = unknown>(definition: {
+    /** The first line is the summary in command lists; help shows it all. */
     description?: string;
+    /** Replaces the generated arguments in usage lines, e.g. `'[name...] [--all]'`. */
+    usage?: string;
+    /** Command lines shown under "Examples:" in the command's help. */
+    examples?: readonly string[];
     input?: S;
+    /** `false` ignores unknown flags and extra positionals. */
+    strict?: boolean;
     run: (input: z.output<S>, ctx: CommandContext<C>) => R;
     output?: (result: Awaited<R>, ctx: CommandContext<C>) => unknown;
 }): Command<C>;
 /** A command that skips parsing: everything after its name is in `ctx.argv`. */
 export declare function defineCommand<R = unknown, C = unknown>(definition: {
     description?: string;
+    usage?: string;
     raw: true;
     run: (input: Record<string, never>, ctx: CommandContext<C>) => R;
     output?: (result: Awaited<R>, ctx: CommandContext<C>) => unknown;
@@ -116,6 +168,7 @@ export declare function defineCommand<R = unknown, C = unknown>(definition: {
 /** A lazy command whose description shows in help before it loads. */
 export declare function defineCommand<C = unknown>(definition: {
     description?: string;
+    usage?: string;
     load: LazyCommand<C>;
 }): Command<C>;
 export declare function defineCli<G extends AnyObject = EmptyObject, C = undefined>(config: CliConfig<G, C>): Cli;

package/dist/crypto/node.d.ts

@@ -0,0 +1,17 @@
+import { type SealerOptions } from './sealer';
+export { SealerError, type SealerErrorCode, type SealerOptions } from './sealer';
+export type SealerSync = {
+    seal(plaintext: string): string;
+    open(sealed: string): string;
+    sealJson(value: unknown): string;
+    openJson<T = unknown>(sealed: unknown): T;
+};
+/**
+ * AES-256-GCM sealing with a random 96-bit IV per value, synchronously.
+ *
+ * @example
+ * const secrets = createSealerSync({ secret: process.env.APP_SECRET!, info: 'app.credentials.v1' })
+ * const stored = secrets.sealJson({ accessToken })
+ * const { accessToken } = secrets.openJson<{ accessToken: string }>(stored)
+ */
+export declare function createSealerSync(options: SealerOptions): SealerSync;

package/dist/crypto/sealer.d.ts

@@ -6,20 +6,52 @@ export type SealerOptions = {
     salt?: string;
     /** HKDF info; use a distinct value per purpose. Default: `'hanzio.sealer.aes-256-gcm.v1'` */
     info?: string;
+    /**
+     * Older `{ salt, info }` pairs that `open` also tries, so values sealed before
+     * a rename stay readable. `seal` always uses `salt` and `info`.
+     */
+    fallbacks?: readonly {
+        salt?: string;
+        info?: string;
+    }[];
+    /**
+     * `open` and `openJson` return a value that was never sealed unchanged
+     * (`{}`, a legacy plaintext) instead of throwing. Malformed envelopes and
+     * other envelope versions still throw.
+     */
+    passthroughUnsealed?: boolean;
 };
 export type Sealer = {
     seal(plaintext: string): Promise<string>;
     open(sealed: string): Promise<string>;
     sealJson(value: unknown): Promise<string>;
-    openJson<T = unknown>(sealed: string): Promise<T>;
+    openJson<T = unknown>(sealed: unknown): Promise<T>;
 };
 export type SealerErrorCode = 'malformed' | 'unsupported_version' | 'decrypt_failed';
 export declare class SealerError extends Error {
     readonly code: SealerErrorCode;
     constructor(code: SealerErrorCode);
 }
+/** The secret's bytes and every HKDF context `open` tries, primary first. */
+export declare function sealerKeyInputs(options: SealerOptions): {
+    secret: Uint8Array<ArrayBuffer>;
+    contexts: {
+        salt: string;
+        info: string;
+    }[];
+};
+export declare function formatEnvelope(iv: Uint8Array, tag: Uint8Array, ciphertext: Uint8Array): string;
+export type Envelope = {
+    iv: Uint8Array<ArrayBuffer>;
+    tag: Uint8Array<ArrayBuffer>;
+    ciphertext: Uint8Array<ArrayBuffer>;
+};
+/** `null` means `sealed` was never sealed and `passthroughUnsealed` allows it. */
+export declare function parseEnvelope(sealed: unknown, passthroughUnsealed?: boolean): Envelope | null;
+export declare function jsonToSeal(value: unknown): string;
 /**
  * AES-256-GCM sealing with a random 96-bit IV per value. Envelope:
- * `enc:v1:<b64url(iv)>.<b64url(tag)>.<b64url(ciphertext)>`.
+ * `enc:v1:<b64url(iv)>.<b64url(tag)>.<b64url(ciphertext)>`. Async, on Web
+ * Crypto; `hanzio/crypto/node` has a synchronous twin with the same envelope.
  */
 export declare function createSealer(options: SealerOptions): Sealer;