@ix-xs/node-comfort 2.0.0 → 2.1.0

package/types/src/Cli.d.ts

@@ -300,9 +300,13 @@ export type FlagSpec = {
      */
     required?: boolean | undefined;
     /**
-     * Allowed values, for string flags.
+     * Allowed values.
      */
-    choices?: readonly string[] | undefined;
+    choices?: readonly string[] | readonly number[] | undefined;
+    /**
+     * An environment variable to read when the flag isn't given, like `"PORT"`. The command line wins, then the variable, then `default`.
+     */
+    env?: string | undefined;
     /**
      * Shown in `--help`.
      */
@@ -311,9 +315,9 @@ export type FlagSpec = {
 /**
  * The type of a flag's value.
  */
-export type FlagValue<F extends FlagSpec> = F["type"] extends "number" ? number : F["type"] extends "boolean" ? boolean : F extends {
+export type FlagValue<F extends FlagSpec> = F["type"] extends "boolean" ? boolean : F extends {
     choices: readonly (infer C)[];
-} ? C : string;
+} ? C : F["type"] extends "number" ? number : string;
 /**
  * The parsed flags, typed from the schema.
  */
@@ -346,6 +350,14 @@ export type ArgsOptions = {
      * A usage line, like `"<file> [options]"`.
      */
     usage?: string | undefined;
+    /**
+     * Subcommands and what they do, like `{ build: "Build the project" }`. The first argument, when there is one, must be one of them and comes back as `command`. They share the flags of the program.
+     */
+    commands?: Record<string, string> | undefined;
+    /**
+     * Command lines shown at the end of the help.
+     */
+    examples?: string[] | undefined;
     /**
      * Answer `--help` and `-h` by printing the help and exiting. Defaults to `true`.
      */
@@ -358,6 +370,10 @@ export type ArgsOptions = {
      * Reject unknown flags, with a suggestion. Defaults to `true`.
      */
     strict?: boolean | undefined;
+    /**
+     * Where `env` flags are read from. Defaults to `process.env`.
+     */
+    env?: Record<string, string | undefined> | undefined;
 };
 /**
  * What `args()` returns.
@@ -368,17 +384,37 @@ export type ParsedArgs<S extends Record<string, FlagSpec>> = {
      * Arguments that aren't flags.
      */
     positionals: string[];
+    /**
+     * The subcommand, when `commands` was given.
+     */
+    command: string | undefined;
     /**
      * The generated help text.
      */
     help: () => string;
 };
+/**
+ * Options for `spin()`: the spinner's, plus what to say at the end.
+ */
+export type SpinOptions<T> = SpinnerOptions & {
+    success?: string | ((result: T) => string);
+    fail?: string | ((error: unknown) => string);
+};
+/**
+ * Options for `tree()`.
+ */
+export type TreeOptions = {
+    /**
+     * Draw with `|`, `+` and `-` instead of box characters.
+     */
+    ascii?: boolean | undefined;
+};
 /**
  * One line reader per input stream, shared by every prompt, so piped lines
  * that arrive early are queued instead of lost.
  */
-export type LineReader = {
-    rl: readline.Interface;
+export type _LineReader = {
+    rl: import("node:readline").Interface;
     lines: string[];
     waiting: Array<{
         resolve: (line: string) => void;
@@ -412,16 +448,38 @@ export function table(rows: Array<Record<string, unknown>> | unknown[][], option
  *
  * @example
  * console.log(cli.box("Server ready\nhttp://localhost:3000", { title: "my-app", borderColor: "green" }));
- * // ╭─ my-app ──────────────────╮
- * // │  Server ready             │
- * // │  http://localhost:3000    │
- * // ╰───────────────────────────╯
+ * // ╭─ my-app ────────────────╮
+ * // │  Server ready           │
+ * // │  http://localhost:3000  │
+ * // ╰─────────────────────────╯
  *
  * @param {string} text
  * @param {BoxOptions} [options]
  * @returns {string}
  */
 export function box(text: string, options?: BoxOptions): string;
+/**
+ * Draws nested data as a tree, like the `tree` command does for folders.
+ * Keys are branches. A value that is an object or an array opens a level,
+ * `null` or `true` makes a plain leaf, anything else is shown after the key.
+ *
+ * @example
+ * console.log(cli.tree({
+ *   src: { "index.js": null, lib: ["a.js", "b.js"] },
+ *   "package.json": "1.2 kB",
+ * }));
+ * // ├── src
+ * // │   ├── index.js
+ * // │   └── lib
+ * // │       ├── a.js
+ * // │       └── b.js
+ * // └── package.json: 1.2 kB
+ *
+ * @param {Record<string, unknown> | unknown[]} data
+ * @param {TreeOptions} [options]
+ * @returns {string}
+ */
+export function tree(data: Record<string, unknown> | unknown[], options?: TreeOptions): string;
 /**
  * A spinner for work in progress. Call `.start()`, then finish with
  * `.succeed()`, `.fail()`, `.warn()`, `.info()` or `.stop()`.
@@ -440,6 +498,24 @@ export function box(text: string, options?: BoxOptions): string;
  * @returns {Spinner} Not started yet.
  */
 export function spinner(text?: string, options?: SpinnerOptions): Spinner;
+/**
+ * Shows a spinner while some work runs, then `✔` or `✖` depending on how it
+ * ended. Resolves with the result of the work, or rejects with its error.
+ *
+ * @example
+ * const users = await cli.spin("Loading users", () => db.getAll("users"));
+ * await cli.spin("Deploying", deploy(), {
+ *   success: (url) => `Deployed to ${url}`,
+ *   fail: (error) => `Deploy failed: ${error.message}`,
+ * });
+ *
+ * @template T
+ * @param {string} text
+ * @param {Promise<T> | ((spinner: Spinner) => T | Promise<T>)} task A promise, or a function that gets the spinner so it can update the text.
+ * @param {SpinOptions<T>} [options]
+ * @returns {Promise<T>}
+ */
+export function spin<T>(text: string, task: Promise<T> | ((spinner: Spinner) => T | Promise<T>), options?: SpinOptions<T>): Promise<T>;
 /**
  * A progress bar with percentage, ETA and speed. It redraws at most every
  * 50 ms, so calling `tick()` in a tight loop is fine.
@@ -533,24 +609,31 @@ export function multiselect<V = string>(question: string, choices: Array<Choice<
 /**
  * Parses command-line arguments from a schema, and types the result:
  * `flags.port` is a `number`. Handles short aliases, defaults, required
- * flags, allowed values, repeated flags and `--no-flag`, and generates
- * `--help`. A typo gets a "Did you mean...?" suggestion.
+ * flags, allowed values, repeated flags, `--no-flag`, environment variables
+ * as a fallback and subcommands, and generates `--help`. A typo gets a
+ * "Did you mean...?" suggestion.
  *
  * @example
  * // node server.js --port 8080 -v --tag api --tag web public/
  * const { flags, positionals } = cli.args({
- *   port: { type: "number", short: "p", default: 3000, description: "Port to listen on" },
+ *   port: { type: "number", short: "p", default: 3000, env: "PORT", description: "Port to listen on" },
  *   verbose: { type: "boolean", short: "v" },
  *   tag: { type: "string", multiple: true },
  *   env: { type: "string", choices: ["dev", "prod"], default: "dev" },
  * }, { description: "Start the web server", version: "1.0.0" });
  * // flags: { port: 8080, verbose: true, tag: ["api", "web"], env: "dev" }
  *
+ * // node tool.js build --watch
+ * const { command, flags: buildFlags } = cli.args({ watch: { type: "boolean" } }, {
+ *   commands: { build: "Build the project", serve: "Start the dev server" },
+ * });
+ * // command: "build"
+ *
  * @template {Record<string, FlagSpec>} S
  * @param {S} schema
  * @param {ArgsOptions} [options]
  * @returns {ParsedArgs<S>}
- * @throws {TypeError} For unknown flags, bad numbers, missing required flags or values not in `choices`. The message is ready to show.
+ * @throws {TypeError} For unknown flags or commands, bad numbers, missing required flags or values not in `choices`. The message is ready to show.
  */
 export function args<S extends Record<string, FlagSpec>>(schema: S, options?: ArgsOptions): ParsedArgs<S>;
 /**
@@ -578,5 +661,4 @@ export function size(): {
  * @returns {void}
  */
 export function clear(): void;
-import readline = require("node:readline");
 //# sourceMappingURL=Cli.d.ts.map

package/types/src/Cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cli.d.ts","sourceRoot":"","sources":["../../src/Cli.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Cli.d.ts","sourceRoot":"","sources":["../../src/Cli.js"],"names":[],"mappings":"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"}

package/types/src/Color.d.ts

@@ -244,7 +244,7 @@ type ColorModule = ColorStyles & ColorMethods & ColorHelpers;
  */
 type ColorHelpers = {
     /**
-     * The current color level. Set it to force one; `0` turns colors off.
+     * The current color level. Set it to force one: `0` turns colors off, `undefined` goes back to what the terminal supports.
      */
     level: ColorLevel;
     /**
@@ -269,6 +269,12 @@ type ColorHelpers = {
      * How many columns the text takes, ignoring colors and counting emoji and CJK as 2.
      */
     width: (text: string) => number;
+    /**
+     * Cuts text to a number of columns and adds `…`. Colors are kept and still closed properly.
+     */
+    truncate: (text: string, columns: number, options?: {
+        ellipsis?: string;
+    }) => string;
     /**
      * A clickable link in terminals that support it, `"text (url)"` elsewhere.
      */

package/types/src/Color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Color.d.ts","sourceRoot":"","sources":["../../src/Color.js"],"names":[],"mappings":";AA0ZA,0BAA0B;AAC1B,qBADW,WAAW,CACiB;;;;;;;iBA3Y1B,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,eAAe,GAC7G,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAC9F,aAAa,GAAG,WAAW,GAAG,aAAa,GAAG,cAAc,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,GAAG,aAAa,GAC5H,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAClH,eAAe,GAAG,aAAa,GAAG,eAAe,GAAG,gBAAgB,GAAG,cAAc,GAAG,iBAAiB,GAAG,cAAc,GAAG,eAAe;;;;kBAKtI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;;;;;;;;;WAOZ,UAAU;;;;UACV,UAAU;;;;SACV,UAAU;;;;YACV,UAAU;;;;eACV,UAAU;;;;cACV,UAAU;;;;aACV,UAAU;;;;YACV,UAAU;;;;mBACV,UAAU;;;;WACV,UAAU;;;;SACV,UAAU;;;;WACV,UAAU;;;;YACV,UAAU;;;;UACV,UAAU;;;;aACV,UAAU;;;;UACV,UAAU;;;;WACV,UAAU;;;;UACV,UAAU;;;;UACV,UAAU;;;;iBACV,UAAU;;;;eACV,UAAU;;;;iBACV,UAAU;;;;kBACV,UAAU;;;;gBACV,UAAU;;;;mBACV,UAAU;;;;gBACV,UAAU;;;;iBACV,UAAU;;;;aACV,UAAU;;;;WACV,UAAU;;;;aACV,UAAU;;;;cACV,UAAU;;;;YACV,UAAU;;;;eACV,UAAU;;;;YACV,UAAU;;;;aACV,UAAU;;;;YACV,UAAU;;;;YACV,UAAU;;;;mBACV,UAAU;;;;iBACV,UAAU;;;;mBACV,UAAU;;;;oBACV,UAAU;;;;kBACV,UAAU;;;;qBACV,UAAU;;;;kBACV,UAAU;;;;mBACV,UAAU;;;;;mBAKX,QAAQ,CAAC,eAAe,CAAC;;;;kBAMzB,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC,GAAG,WAAW,GAAG,YAAY;;;;;;;;SAM5D,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,UAAU;;;;WAC/C,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,UAAU;;;;SAC/C,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU;;;;WAC3B,CAAC,GAAG,EAAE,MAAM,KAAK,UAAU;;;;aAC3B,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU;;;;eAC5B,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU;;;;;mBAM7B,WAAW,GAAG,YAAY,GAAG,YAAY;;;;;;;;WAMxC,UAAU;;;;aACV,OAAO;;;;YACP,CAAC,KAAK,CAAC,EAAE,UAAU,KAAK,WAAW;;;;YACnC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,GAAG;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,UAAU;;;;WACjE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM;;;;WACxB,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM;;;;UACxB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM;;;;cACrC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,MAAM;;;;;kBAiB3C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAA;CAAE"}
+{"version":3,"file":"Color.d.ts","sourceRoot":"","sources":["../../src/Color.js"],"names":[],"mappings":"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"}

package/types/src/Crypto.d.ts

@@ -62,6 +62,25 @@ export type DecryptOptions = {
      */
     output?: "utf8" | "buffer" | undefined;
 };
+/**
+ * A key for `signJWT()` and `verifyJWT()`. For the HS algorithms it's a
+ * shared secret. For the others it's a key pair: a PEM string, a
+ * `KeyObject` or a JWK, private to sign and public to verify.
+ */
+export type JWTKey = string | Buffer | Uint8Array | import("node:crypto").KeyObject | import("node:crypto").JsonWebKey;
+/**
+ * A pair of keys in PEM, as made by `generateKeyPair()`.
+ */
+export type KeyPair = {
+    /**
+     * Give this one away: it only checks signatures.
+     */
+    publicKey: string;
+    /**
+     * Keep this one secret: it signs.
+     */
+    privateKey: string;
+};
 /**
  * Standard JWT claims.
  */
@@ -96,15 +115,17 @@ export type JWTClaims = {
     jti?: string | undefined;
 };
 /**
- * Supported JWT algorithms.
+ * Supported JWT algorithms. HS signs and verifies with one shared secret.
+ * RS, PS, ES and EdDSA sign with a private key and verify with the public
+ * one, so services that only check tokens never hold the signing key.
  */
-export type JWTAlgorithm = "HS256" | "HS384" | "HS512";
+export type JWTAlgorithm = "HS256" | "HS384" | "HS512" | "RS256" | "RS384" | "RS512" | "PS256" | "PS384" | "PS512" | "ES256" | "ES384" | "ES512" | "EdDSA";
 /**
  * Options for `signJWT()`.
  */
 export type SignJWTOptions = {
     /**
-     * Defaults to `"HS256"`.
+     * Defaults to what fits the key: `"HS256"` for a secret, `"RS256"` for an RSA key, `"ES256"` for a P-256 key, `"EdDSA"` for an Ed25519 key.
      */
     algorithm?: JWTAlgorithm | undefined;
     /**
@@ -145,7 +166,7 @@ export type SignJWTOptions = {
  */
 export type VerifyJWTOptions = {
     /**
-     * Accepted algorithms. Defaults to all three HMAC ones.
+     * Accepted algorithms. Defaults to the ones that fit the key, so a token can't pick a weaker one.
      */
     algorithms?: JWTAlgorithm[] | undefined;
     /**
@@ -173,7 +194,7 @@ export type VerifyJWTOptions = {
      */
     ignoreExpiration?: boolean | undefined;
     /**
-     * What time it is. Defaults to now.
+     * What time it is. Defaults to now. Handy in tests.
      */
     now?: number | Date | undefined;
 };
@@ -245,6 +266,18 @@ export type TOTPURIOptions = {
      */
     algorithm?: "SHA1" | "SHA256" | "SHA512" | undefined;
 };
+/**
+ * A key, ready to use, with the algorithms it may be used with.
+ */
+export type _ResolvedKey = {
+    secret: Buffer;
+    key?: undefined;
+    algorithms: readonly JWTAlgorithm[];
+} | {
+    secret?: undefined;
+    key: import("node:crypto").KeyObject;
+    algorithms: readonly JWTAlgorithm[];
+};
 /**
  * Hashes data, SHA-256 in hex by default.
  *
@@ -271,10 +304,28 @@ export function hash(data: string | Buffer | Uint8Array, options?: HashOptions):
  * @returns {string}
  */
 export function hmac(data: string | Buffer | Uint8Array, secret: string | Buffer | Uint8Array, options?: HashOptions): string;
+/**
+ * Checks an HMAC signature you received, in constant time. A leading
+ * `sha256=`, as GitHub and others send, is ignored.
+ *
+ * @example
+ * // an Express webhook route: sign the raw body, not the parsed JSON
+ * if (!crypto.verifyHmac(req.rawBody, req.headers["x-hub-signature-256"], process.env.WEBHOOK_SECRET)) {
+ *   return res.status(401).end();
+ * }
+ *
+ * @param {string | Buffer | Uint8Array} data
+ * @param {unknown} signature What the sender computed. Anything but a matching string gives `false`.
+ * @param {string | Buffer | Uint8Array} secret
+ * @param {HashOptions} [options] Must match what the sender used.
+ * @returns {boolean}
+ */
+export function verifyHmac(data: string | Buffer | Uint8Array, signature: unknown, secret: string | Buffer | Uint8Array, options?: HashOptions): boolean;
 /**
  * Compares two secrets in constant time, so the comparison can't leak
- * anything through timing. Use it instead of `===` for tokens, signatures
- * and API keys.
+ * anything through timing, not even their lengths. Use it instead of `===`
+ * for tokens, signatures and API keys. A missing value (`undefined`, `null`)
+ * never equals anything.
  *
  * @example
  * if (!crypto.safeEqual(providedKey, process.env.API_KEY)) throw new Error("Forbidden");
@@ -296,6 +347,7 @@ export function safeEqual(a: string | Buffer | Uint8Array, b: string | Buffer |
  * @param {string} password
  * @param {HashPasswordOptions} [options]
  * @returns {Promise<string>}
+ * @throws {RangeError} If the settings are out of bounds, like a cost that needs more than 1 GiB of memory.
  */
 export function hashPassword(password: string, options?: HashPasswordOptions): Promise<string>;
 /**
@@ -350,8 +402,8 @@ export function generateKey(): string;
  */
 export function encrypt(data: string | Buffer | Uint8Array, secret: string | Buffer | Uint8Array, options?: EncryptOptions): string;
 /**
- * Decrypts what `encrypt()` produced. Throws if the secret is wrong or the
- * data was changed.
+ * Decrypts what `encrypt()` produced. Throws an error with code
+ * `ERR_DECRYPT` if the secret is wrong or the data was changed.
  *
  * @example
  * const text = crypto.decrypt(box, SECRET);
@@ -379,18 +431,28 @@ export function decrypt(payload: string, secret: string | Buffer | Uint8Array, o
 /**
  * Creates a signed JSON Web Token. `iat` is added for you.
  *
+ * With a secret, the token is signed with HMAC. With a private key, it's
+ * signed with that key, and anyone holding the public key can verify it
+ * without being able to issue tokens.
+ *
  * @example
  * const token = crypto.signJWT({ sub: String(user.id), role: user.role }, process.env.JWT_SECRET, {
  *   expiresIn: "15m",
  *   issuer: "api.example.com",
  * });
  *
+ * // key pair: the auth service signs, every other service verifies
+ * const { publicKey, privateKey } = await crypto.generateKeyPair("ES256");
+ * const signed = crypto.signJWT({ sub: "42" }, privateKey, { expiresIn: "15m" });
+ * crypto.verifyJWT(signed, publicKey);
+ *
  * @param {Record<string, unknown>} payload
- * @param {string | Buffer} secret At least 32 random bytes.
+ * @param {JWTKey} secret For HS algorithms, at least 32 random bytes. Otherwise a private key.
  * @param {SignJWTOptions} [options]
  * @returns {string}
+ * @throws {TypeError} If the key can't be used, or doesn't fit the algorithm.
  */
-export function signJWT(payload: Record<string, unknown>, secret: string | Buffer, options?: SignJWTOptions): string;
+export function signJWT(payload: Record<string, unknown>, secret: JWTKey, options?: SignJWTOptions): string;
 /**
  * Reads a JWT without checking it. Fine for display; call `verifyJWT()`
  * before trusting anything in it.
@@ -409,6 +471,9 @@ export function decodeJWT<P = Record<string, unknown>>(token: string): DecodedJW
  * require. Returns the payload, or throws a `JWTError` whose `code` says
  * what's wrong.
  *
+ * The accepted algorithms follow from the key you pass, so a token signed
+ * with HMAC is never accepted where a public key is expected.
+ *
  * @example
  * try {
  *   const { sub } = crypto.verifyJWT(token, process.env.JWT_SECRET, { issuer: "api.example.com" });
@@ -418,12 +483,33 @@ export function decodeJWT<P = Record<string, unknown>>(token: string): DecodedJW
  *
  * @template [P=Record<string, unknown>]
  * @param {string} token
- * @param {string | Buffer} secret
+ * @param {JWTKey} secret The shared secret, or the public key for RS, PS, ES and EdDSA tokens.
  * @param {VerifyJWTOptions} [options]
  * @returns {P & JWTClaims}
  * @throws {JWTError}
  */
-export function verifyJWT<P = Record<string, unknown>>(token: string, secret: string | Buffer, options?: VerifyJWTOptions): P & JWTClaims;
+export function verifyJWT<P = Record<string, unknown>>(token: string, secret: JWTKey, options?: VerifyJWTOptions): P & JWTClaims;
+/**
+ * Makes a pair of keys for signing JWTs: the private one signs, the public
+ * one verifies. Both come as PEM text, ready for an environment variable or
+ * a file.
+ *
+ * `"EdDSA"` (Ed25519) is the fastest with the shortest keys and signatures.
+ * `"ES256"` is the most widely supported after RSA. Pick `"RS256"` when the
+ * other side asks for it.
+ *
+ * @example
+ * const { publicKey, privateKey } = await crypto.generateKeyPair();
+ * const token = crypto.signJWT({ sub: "42" }, privateKey);
+ * crypto.verifyJWT(token, publicKey);
+ *
+ * @param {Exclude<JWTAlgorithm, "HS256" | "HS384" | "HS512">} [algorithm="EdDSA"] The JWT algorithm the keys are for.
+ * @param {{ modulusLength?: number }} [options] RSA key size in bits. Defaults to `2048`.
+ * @returns {Promise<KeyPair>}
+ */
+export function generateKeyPair(algorithm?: Exclude<JWTAlgorithm, "HS256" | "HS384" | "HS512">, options?: {
+    modulusLength?: number;
+}): Promise<KeyPair>;
 /**
  * A new two-factor secret, in the Base32 format authenticator apps expect.
  * Store it encrypted.

package/types/src/Crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Crypto.d.ts","sourceRoot":"","sources":["../../src/Crypto.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"Crypto.d.ts","sourceRoot":"","sources":["../../src/Crypto.js"],"names":[],"mappings":"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"}

package/types/src/Emitter.d.ts

@@ -1,17 +1,4 @@
 export = Emitter;
-/**
- * Event names mapped to their arguments, like
- * `{ ready: [], data: [chunk: Buffer], error: [error: Error] }`.
- * @typedef {Record<string, any[]>} EventMap
- */
-/**
- * Options for `waitFor()`.
- * @template {any[]} A
- * @typedef {object} WaitForOptions
- * @property {number | string} [timeout] Reject with a `TimeoutError` after this long.
- * @property {AbortSignal} [signal] Reject with an `AbortError` when aborted.
- * @property {(...args: A) => boolean} [filter] Only resolve for events that pass this test.
- */
 /**
  * A typed event emitter. In JavaScript, give the variable a JSDoc type such
  * as `import("@ix-xs/node-comfort").Emitter<{ ready: [port: number] }>`.
@@ -26,21 +13,28 @@ declare class Emitter<Events extends EventMap = EventMap> {
      * const off = emitter.on("data", (chunk) => chunks.push(chunk));
      * off(); // stop listening
      *
+     * const controller = new AbortController();
+     * emitter.on("data", onData, { signal: controller.signal });
+     * emitter.on("end", onEnd, { signal: controller.signal });
+     * controller.abort(); // removes both
+     *
      * @template {keyof Events & string} K
      * @param {K} event
      * @param {(...args: Events[K]) => unknown} listener
+     * @param {ListenOptions} [options]
      * @returns {() => void} Removes the listener.
      */
-    on<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => unknown): () => void;
+    on<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => unknown, options?: ListenOptions): () => void;
     /**
      * Listens to an event once.
      *
      * @template {keyof Events & string} K
      * @param {K} event
      * @param {(...args: Events[K]) => unknown} listener
+     * @param {ListenOptions} [options]
      * @returns {() => void} Removes the listener if it hasn't run yet.
      */
-    once<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => unknown): () => void;
+    once<K extends keyof Events & string>(event: K, listener: (...args: Events[K]) => unknown, options?: ListenOptions): () => void;
     /**
      * Listens to every event; the listener gets the event name first. Handy for
      * logging.
@@ -57,7 +51,7 @@ declare class Emitter<Events extends EventMap = EventMap> {
      *
      * @template {keyof Events & string} K
      * @param {K} event
-     * @param {(...args: Events[K]) => unknown} [listener]
+     * @param {(...args: Events[K]) => unknown} [listener] The function given to `on()` or `once()`.
      * @returns {this}
      */
     off<K extends keyof Events & string>(event: K, listener?: (...args: Events[K]) => unknown): this;
@@ -127,6 +121,15 @@ declare class Emitter<Events extends EventMap = EventMap> {
      * @returns {number}
      */
     listenerCount(event?: keyof Events & string): number;
+    /**
+     * The listeners of an event, in the order they run. For `once()`, you get
+     * the function you passed, not its wrapper.
+     *
+     * @template {keyof Events & string} K
+     * @param {K} event
+     * @returns {Array<(...args: Events[K]) => unknown>}
+     */
+    listeners<K extends keyof Events & string>(event: K): Array<(...args: Events[K]) => unknown>;
     /**
      * The events that have listeners.
      *
@@ -143,13 +146,22 @@ declare class Emitter<Events extends EventMap = EventMap> {
     #private;
 }
 declare namespace Emitter {
-    export { EventMap, WaitForOptions };
+    export { EventMap, ListenOptions, WaitForOptions, _StoredListener };
 }
 /**
  * Event names mapped to their arguments, like
  * `{ ready: [], data: [chunk: Buffer], error: [error: Error] }`.
  */
 type EventMap = Record<string, any[]>;
+/**
+ * Options for `on()` and `once()`.
+ */
+type ListenOptions = {
+    /**
+     * Removes the listener when aborted. One signal can clean up many listeners at once.
+     */
+    signal?: AbortSignal | undefined;
+};
 /**
  * Options for `waitFor()`.
  */
@@ -167,4 +179,11 @@ type WaitForOptions<A extends any[]> = {
      */
     filter?: ((...args: A) => boolean) | undefined;
 };
+/**
+ * A listener as stored: `once()` wraps the function it was given and keeps
+ * it as `listener`, so `off()` can find it.
+ */
+type _StoredListener = ((...args: any[]) => unknown) & {
+    listener?: Function;
+};
 //# sourceMappingURL=Emitter.d.ts.map

package/types/src/Emitter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Emitter.d.ts","sourceRoot":"","sources":["../../src/Emitter.js"],"names":[],"mappings":";AAkBA;;;;GAIG;AAEH;;;;;;;GAOG;AAEH;;;;;GAKG;AACH,sBAFyB,MAAM,SAAjB,QAAS;IAQrB;;;;;;;;;;;OAWG;IACH,GALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,YACD,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,OAAO,GAC7B,MAAM,IAAI,CAOtB;IAED;;;;;;;OAOG;IACH,KALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,YACD,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,OAAO,GAC7B,MAAM,IAAI,CAUtB;IAED;;;;;;;;;OASG;IACH,gBAHW,CAAC,KAAK,EAAE,MAAM,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,GACvD,MAAM,IAAI,CAKtB;IAED;;;;;;;OAOG;IACH,IALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,aACD,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,OAAO,GAC7B,IAAI,CAUhB;IAED;;;;;;;;;;;OAWG;IACH,KALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,WACD,MAAM,CAAC,CAAC,CAAC,GACP,OAAO,CAOnB;IAED;;;;;;;;;;;OAWG;IACH,UALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,WACD,MAAM,CAAC,CAAC,CAAC,GACP,OAAO,CAAC,OAAO,EAAE,CAAC,CAO9B;IAED;;;;;;;;;;;;;OAaG;IACH,QAPqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,YACD,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAgC9B;IAED;;;;;;;;;;;;;OAaG;IACH,QALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,YACD;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACtB,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAsC5C;IAED;;;;;;OAMG;IACH,sBAHW,MAAM,MAAM,GAAG,MAAM,GACnB,MAAM,CAOlB;IAED;;;;OAIG;IACH,cAFa,KAAK,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,CAIxC;IAED;;;;;OAKG;IACH,cAHW,MAAM,MAAM,GAAG,MAAM,GACnB,IAAI,CAShB;;CACF;;;;;;;;gBAzQY,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;;;;oBAKb,CAAC,SAAR,GAAG,EAAG;;;;;;;;;;;;wBAII,CAAC,KAAK,OAAO"}
+{"version":3,"file":"Emitter.d.ts","sourceRoot":"","sources":["../../src/Emitter.js"],"names":[],"mappings":";AAiDA;;;;;GAKG;AACH,sBAFyB,MAAM,SAAjB,QAAS;IA0CrB;;;;;;;;;;;;;;;;;OAiBG;IACH,GANqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,YACD,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,OAAO,YAC/B,aAAa,GACX,MAAM,IAAI,CAItB;IAED;;;;;;;;OAQG;IACH,KANqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,YACD,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,OAAO,YAC/B,aAAa,GACX,MAAM,IAAI,CAWtB;IAED;;;;;;;;;OASG;IACH,gBAHW,CAAC,KAAK,EAAE,MAAM,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,GACvD,MAAM,IAAI,CAOtB;IAED;;;;;;;OAOG;IACH,IALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,aACD,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,OAAO,GAC7B,IAAI,CAMhB;IAED;;;;;;;;;;;OAWG;IACH,KALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,WACD,MAAM,CAAC,CAAC,CAAC,GACP,OAAO,CAQnB;IAED;;;;;;;;;;;OAWG;IACH,UALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,WACD,MAAM,CAAC,CAAC,CAAC,GACP,OAAO,CAAC,OAAO,EAAE,CAAC,CAQ9B;IAED;;;;;;;;;;;;;OAaG;IACH,QAPqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,YACD,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAgC9B;IAED;;;;;;;;;;;;;OAaG;IACH,QALqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,YACD;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACtB,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAsC5C;IAED;;;;;;OAMG;IACH,sBAHW,MAAM,MAAM,GAAG,MAAM,GACnB,MAAM,CAOlB;IAED;;;;;;;OAOG;IACH,UAJqC,CAAC,SAAxB,MAAM,MAAM,GAAG,MAAO,SACzB,CAAC,GACC,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAIlD;IAED;;;;OAIG;IACH,cAFa,KAAK,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,CAIxC;IAED;;;;;OAKG;IACH,cAHW,MAAM,MAAM,GAAG,MAAM,GACnB,IAAI,CAShB;;CACF;;;;;;;;gBA3UY,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;;;;;;;;;;;;;oBAWb,CAAC,SAAR,GAAG,EAAG;;;;;;;;;;;;wBAII,CAAC,KAAK,OAAO;;;;;;uBAMxB,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG;IAAE,QAAQ,CAAC,WAAU;CAAE"}