@octoii-works/octoii-std 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+The notable changes of `@octoii-works/octoii-std`, newest first.
+
+## [Unreleased]
+
+- First release: The general-purpose base library of Octoii: JSON, deltas, encodings, ids, schemas, async helpers, bounded text, SQLite, SSE and JSON-RPC.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 octoii
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,27 @@
+@octoii-works/octoii-std includes code adapted from the following project.
+
+--------------------------------------------------------------------------------
+pi (https://github.com/earendil-works/pi)
+Adapted in: src/text/truncate.ts (truncation by lines and bytes)
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/async/backoff.d.ts

@@ -0,0 +1,13 @@
+export type BackoffOptions = {
+    /** The delay before the second attempt, which doubles with each attempt after it. */
+    readonly baseDelayMs: number;
+    /** The longest the doubling delay grows. */
+    readonly maxDelayMs: number;
+    /** How far a delay strays, from 0 to 1: 0.2 places it within ±20%. */
+    readonly jitter: number;
+};
+/**
+ * The delay before the attempt after attempt `attempt` (from 1), in whole ms: doubling from `baseDelayMs` up to
+ * `maxDelayMs`, strayed by `random()` in [0, 1); never below `floorMs`, such as a server's Retry-After.
+ */
+export declare function backoffDelay(attempt: number, options: BackoffOptions, random: () => number, floorMs?: number): number;

package/dist/async/backoff.js

@@ -0,0 +1,9 @@
+/**
+ * The delay before the attempt after attempt `attempt` (from 1), in whole ms: doubling from `baseDelayMs` up to
+ * `maxDelayMs`, strayed by `random()` in [0, 1); never below `floorMs`, such as a server's Retry-After.
+ */
+export function backoffDelay(attempt, options, random, floorMs = 0) {
+    const doubled = Math.min(options.baseDelayMs * 2 ** (attempt - 1), options.maxDelayMs);
+    const strayed = doubled * (1 - options.jitter + 2 * options.jitter * random());
+    return Math.ceil(Math.max(strayed, floorMs));
+}

package/dist/async/clock.d.ts

@@ -0,0 +1,14 @@
+/** Time and timers, injected: the host's clock in production, a simulated one in tests. */
+export type Clock = {
+    /** The time, in ms since the epoch. */
+    now(): number;
+    /** Runs `callback` after `delayMs`, never synchronously, and returns a function that cancels it. */
+    setTimer(callback: () => void, delayMs: number): () => void;
+};
+/**
+ * `Date.now` and `setTimeout`: the one object in `std` that reads the platform's clock and timers, for a program's edge,
+ * such as a host, to pass in. No function falls back to it.
+ */
+export declare const systemClock: Clock;
+/** Resolves after `ms` on `clock`'s timer; rejects with the signal's reason once `signal` aborts, cancelling the timer. */
+export declare function sleep(clock: Clock, ms: number, signal?: AbortSignal): Promise<void>;

package/dist/async/clock.js

@@ -0,0 +1,29 @@
+/**
+ * `Date.now` and `setTimeout`: the one object in `std` that reads the platform's clock and timers, for a program's edge,
+ * such as a host, to pass in. No function falls back to it.
+ */
+export const systemClock = {
+    now: () => Date.now(),
+    setTimer: (callback, delayMs) => {
+        const timer = setTimeout(callback, delayMs);
+        return () => clearTimeout(timer);
+    },
+};
+/** Resolves after `ms` on `clock`'s timer; rejects with the signal's reason once `signal` aborts, cancelling the timer. */
+export function sleep(clock, ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            cancel();
+            reject(signal?.reason);
+        };
+        const cancel = clock.setTimer(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/async/index.d.ts

@@ -0,0 +1,4 @@
+/** Time, waits, cancellation and backoff, on the clock and signals a caller passes. */
+export { type BackoffOptions, backoffDelay } from "./backoff.js";
+export { type Clock, sleep, systemClock } from "./clock.js";
+export { abortable, linkedSignal, withinLimit } from "./signals.js";

package/dist/async/index.js

@@ -0,0 +1,4 @@
+/** Time, waits, cancellation and backoff, on the clock and signals a caller passes. */
+export { backoffDelay } from "./backoff.js";
+export { sleep, systemClock } from "./clock.js";
+export { abortable, linkedSignal, withinLimit } from "./signals.js";

package/dist/async/signals.d.ts

@@ -0,0 +1,23 @@
+import { type Clock } from "./clock.js";
+/**
+ * A signal that aborts as soon as any of `signals` does, with its reason; `release` stops listening to them once the
+ * work is done. Written out because `AbortSignal.any` is not everywhere.
+ */
+export declare function linkedSignal(signals: readonly (AbortSignal | undefined)[]): {
+    readonly signal: AbortSignal;
+    release(): void;
+};
+/**
+ * Waits for `promise` until it settles or `signal` aborts. Aborting rejects only this wait with the signal's reason; it
+ * does not cancel the work behind the promise.
+ */
+export declare function abortable<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+/**
+ * Waits for `promise` at most `ms` by `clock`: its value, or `timedOut` once the time is up, while the work goes on
+ * unobserved. A promise that rejects in time rejects the wait.
+ */
+export declare function withinLimit<T>(promise: Promise<T>, ms: number, clock: Clock): Promise<{
+    readonly value: T;
+} | {
+    readonly timedOut: true;
+}>;

package/dist/async/signals.js

@@ -0,0 +1,58 @@
+import { sleep } from "./clock.js";
+/**
+ * A signal that aborts as soon as any of `signals` does, with its reason; `release` stops listening to them once the
+ * work is done. Written out because `AbortSignal.any` is not everywhere.
+ */
+export function linkedSignal(signals) {
+    const controller = new AbortController();
+    const present = signals.filter((signal) => signal !== undefined);
+    const aborted = present.find((signal) => signal.aborted);
+    if (aborted !== undefined) {
+        controller.abort(aborted.reason);
+        return { signal: controller.signal, release: () => undefined };
+    }
+    const listeners = present.map((signal) => {
+        const onAbort = () => controller.abort(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        return () => signal.removeEventListener("abort", onAbort);
+    });
+    return { signal: controller.signal, release: () => listeners.forEach((stop) => stop()) };
+}
+/**
+ * Waits for `promise` until it settles or `signal` aborts. Aborting rejects only this wait with the signal's reason; it
+ * does not cancel the work behind the promise.
+ */
+export function abortable(promise, signal) {
+    if (signal === undefined)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Waits for `promise` at most `ms` by `clock`: its value, or `timedOut` once the time is up, while the work goes on
+ * unobserved. A promise that rejects in time rejects the wait.
+ */
+export async function withinLimit(promise, ms, clock) {
+    const timer = new AbortController();
+    const timeout = sleep(clock, ms, timer.signal).then(() => ({ timedOut: true }), 
+    // The sleep is aborted once the promise settles; the race is decided by then.
+    () => ({ timedOut: true }));
+    try {
+        return await Promise.race([promise.then((value) => ({ value })), timeout]);
+    }
+    finally {
+        timer.abort();
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * std's constants, all of them: the codes and names its modules give, and their limits. Each subpath gives those of its
+ * own module.
+ */
+/** JSON-RPC 2.0's error codes. */
+export declare const JSON_RPC_ERRORS: {
+    readonly parseError: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internalError: -32603;
+};
+/**
+ * The key a SQLite worker keeps a database's schema version under, in the object's key-value storage, since the SQL API
+ * takes no `PRAGMA user_version`.
+ */
+export declare const SQLITE_SCHEMA_VERSION_KEY = "std.sqlite.schema-version";
+/** The unchanged lines around each change of a diff. */
+export declare const DIFF_CONTEXT_LINES = 3;
+/**
+ * The most edits Myers' search tries before it takes the changed middle as removed and added whole: it bounds the time
+ * a diff of two very different files takes, at the cost of a longer diff.
+ */
+export declare const DIFF_MAX_EDITS = 1000;
+/** How long a statement waits for another connection's lock before it fails, in ms. */
+export declare const BUSY_TIMEOUT_MS = 5000;
+/** The random bytes of a PKCE verifier: 32, which base64url writes as 43 characters, the fewest RFC 7636 allows. */
+export declare const PKCE_VERIFIER_BYTES = 32;

package/dist/constants.js

@@ -0,0 +1,30 @@
+/**
+ * std's constants, all of them: the codes and names its modules give, and their limits. Each subpath gives those of its
+ * own module.
+ */
+// Codes and names.
+/** JSON-RPC 2.0's error codes. */
+export const JSON_RPC_ERRORS = {
+    parseError: -32700,
+    invalidRequest: -32600,
+    methodNotFound: -32601,
+    invalidParams: -32602,
+    internalError: -32603,
+};
+/**
+ * The key a SQLite worker keeps a database's schema version under, in the object's key-value storage, since the SQL API
+ * takes no `PRAGMA user_version`.
+ */
+export const SQLITE_SCHEMA_VERSION_KEY = "std.sqlite.schema-version";
+// Numbers.
+/** The unchanged lines around each change of a diff. */
+export const DIFF_CONTEXT_LINES = 3;
+/**
+ * The most edits Myers' search tries before it takes the changed middle as removed and added whole: it bounds the time
+ * a diff of two very different files takes, at the cost of a longer diff.
+ */
+export const DIFF_MAX_EDITS = 1_000;
+/** How long a statement waits for another connection's lock before it fails, in ms. */
+export const BUSY_TIMEOUT_MS = 5000;
+/** The random bytes of a PKCE verifier: 32, which base64url writes as 43 characters, the fewest RFC 7636 allows. */
+export const PKCE_VERIFIER_BYTES = 32;

package/dist/delta.d.ts

@@ -0,0 +1,19 @@
+/** How a JSON value changed, as a list of operations, and the value those operations give. */
+import { type JsonValue } from "./json.js";
+/** Where in a JSON value: object keys and array indexes from the root. */
+export type Path = readonly (string | number)[];
+/**
+ * A change to a JSON value; small and plain, so it can be stored and sent too.
+ * - `set`: the value at the path, which may be a new key or the index just past an array's end; the empty path
+ *   replaces the whole value.
+ * - `delete`: removes an object key.
+ * - `append`: appends text to the string at the path.
+ */
+export type Op = readonly ["set", Path, JsonValue] | readonly ["delete", Path] | readonly ["append", Path, string];
+/**
+ * The operations that turn `before` into `after`: nothing when they are equal; a string that only grew becomes an
+ * `append`; objects and growing arrays are compared member by member; anything else is a `set`.
+ */
+export declare function diffJson(before: JsonValue, after: JsonValue): Op[];
+/** `value` with `ops` applied; the input is not changed, and unchanged parts are shared. */
+export declare function applyOps(value: JsonValue | undefined, ops: readonly Op[]): JsonValue;

package/dist/delta.js

@@ -0,0 +1,116 @@
+/** How a JSON value changed, as a list of operations, and the value those operations give. */
+import { isObject, jsonEntries, jsonEqual } from "./json.js";
+/**
+ * The operations that turn `before` into `after`: nothing when they are equal; a string that only grew becomes an
+ * `append`; objects and growing arrays are compared member by member; anything else is a `set`.
+ */
+export function diffJson(before, after) {
+    const ops = [];
+    diffInto(before, after, [], ops);
+    return ops;
+}
+/** `value` with `ops` applied; the input is not changed, and unchanged parts are shared. */
+export function applyOps(value, ops) {
+    let result = value;
+    for (const op of ops)
+        result = applyOp(result, op);
+    if (result === undefined)
+        throw new Error("The ops leave no value");
+    return result;
+}
+function diffInto(before, after, path, ops) {
+    if (jsonEqual(before, after))
+        return;
+    if (typeof before === "string" && typeof after === "string" && before.length > 0 && after.startsWith(before)) {
+        ops.push(["append", path, after.slice(before.length)]);
+        return;
+    }
+    if (Array.isArray(before) && Array.isArray(after) && after.length >= before.length) {
+        before.forEach((item, index) => diffInto(item, after[index] ?? null, [...path, index], ops));
+        for (let index = before.length; index < after.length; index++)
+            ops.push(["set", [...path, index], after[index] ?? null]);
+        return;
+    }
+    if (isObject(before) && isObject(after)) {
+        for (const [key] of jsonEntries(before))
+            if (ownMember(after, key) === undefined)
+                ops.push(["delete", [...path, key]]);
+        for (const [key, value] of jsonEntries(after)) {
+            const previous = ownMember(before, key);
+            if (previous === undefined)
+                ops.push(["set", [...path, key], value]);
+            else
+                diffInto(previous, value, [...path, key], ops);
+        }
+        return;
+    }
+    ops.push(["set", path, after]);
+}
+function applyOp(value, op) {
+    const path = op[1];
+    if (path.length === 0) {
+        if (op[0] === "set")
+            return op[2];
+        if (op[0] === "append" && typeof value === "string")
+            return value + op[2];
+        throw new Error(`Cannot ${op[0]} the whole value`);
+    }
+    if (value === undefined)
+        throw new Error(`No value at ${JSON.stringify(path)}`);
+    return updateAt(value, path, (current) => {
+        switch (op[0]) {
+            case "set":
+                return op[2];
+            case "delete":
+                return undefined;
+            case "append":
+                if (typeof current !== "string")
+                    throw new Error(`No string to append to at ${JSON.stringify(path)}`);
+                return current + op[2];
+        }
+    });
+}
+/** The object's own member under `key`; undefined for a key it inherits, such as `constructor` or `__proto__`. */
+function ownMember(object, key) {
+    return Object.hasOwn(object, key) ? object[key] : undefined;
+}
+/** Sets the object's own member under `key`, also for `__proto__`, which an assignment would take as its prototype. */
+function setOwn(object, key, value) {
+    Object.defineProperty(object, key, { value, writable: true, enumerable: true, configurable: true });
+}
+/** A copy of `value` with the member at `path` replaced by `update`'s result; undefined removes an object key. */
+function updateAt(value, path, update) {
+    const [segment, ...rest] = path;
+    if (segment === undefined)
+        throw new Error("An update needs a path");
+    const child = (current) => {
+        if (rest.length === 0)
+            return update(current);
+        if (current === undefined)
+            throw new Error(`No value at ${JSON.stringify(path)}`);
+        return updateAt(current, rest, update);
+    };
+    if (Array.isArray(value)) {
+        if (typeof segment !== "number" || !Number.isInteger(segment) || segment < 0 || segment > value.length) {
+            throw new Error(`Index ${String(segment)} is outside an array of ${value.length}`);
+        }
+        const next = child(value[segment]);
+        if (next === undefined)
+            throw new Error("Array items cannot be deleted; set the array instead");
+        const copy = [...value];
+        copy[segment] = next;
+        return copy;
+    }
+    if (isObject(value)) {
+        if (typeof segment !== "string")
+            throw new Error(`Index ${segment} used on an object`);
+        const next = child(ownMember(value, segment));
+        const copy = { ...value };
+        if (next === undefined)
+            delete copy[segment];
+        else
+            setOwn(copy, segment, next);
+        return copy;
+    }
+    throw new Error(`No object or array at ${JSON.stringify(path)}`);
+}

package/dist/encoding.d.ts

@@ -0,0 +1,35 @@
+/**
+ * UTF-8 and base64, the same on every platform. Decoding is strict when asked: invalid bytes throw rather than becoming
+ * U+FFFD, so a value read back is the value written.
+ */
+/** How decoding treats bytes that are no UTF-8: as U+FFFD, or, with `fatal`, as a `TypeError`. */
+export type Utf8Options = {
+    readonly fatal?: boolean;
+};
+/** Decodes UTF-8 a chunk at a time: a character whose bytes are split between chunks is decoded once all have arrived. */
+export interface Utf8Decoder {
+    /** The text of `bytes` after what earlier chunks left unfinished; `final` decodes everything that is left. */
+    decode(bytes: Uint8Array, final: boolean): string;
+}
+/** `text` as UTF-8; a lone surrogate becomes U+FFFD. */
+export declare function utf8Encode(text: string): Uint8Array;
+/** UTF-8 `bytes` as text; with `fatal`, bytes that are no UTF-8 throw a `TypeError`. */
+export declare function utf8Decode(bytes: Uint8Array, options?: Utf8Options): string;
+/** A streaming decoder: bytes may split a character across chunks. */
+export declare function utf8Decoder(options?: Utf8Options): Utf8Decoder;
+/** The UTF-8 length of `text`, without encoding it; a lone surrogate counts as the three bytes of U+FFFD. */
+export declare function utf8ByteLength(text: string): number;
+/** Whether `text` has no lone surrogates, so it encodes to UTF-8 and back unchanged. */
+export declare function isWellFormed(text: string): boolean;
+/** `text` with each lone surrogate replaced by U+FFFD. */
+export declare function toWellFormed(text: string): string;
+/** `bytes` as base64 with padding. */
+export declare function toBase64(bytes: Uint8Array): string;
+/** The bytes padded base64 `text` stands for; anything else throws a `SyntaxError`. */
+export declare function fromBase64(text: string): Uint8Array;
+/** `bytes` as lowercase hex, two digits a byte. */
+export declare function toHex(bytes: Uint8Array): string;
+/** `bytes` as base64url, without padding, as URLs and PKCE take it. */
+export declare function toBase64Url(bytes: Uint8Array): string;
+/** The bytes base64url `text` stands for, padded or not; anything else throws a `SyntaxError`. */
+export declare function fromBase64Url(text: string): Uint8Array<ArrayBuffer>;

package/dist/encoding.js

@@ -0,0 +1,140 @@
+/**
+ * UTF-8 and base64, the same on every platform. Decoding is strict when asked: invalid bytes throw rather than becoming
+ * U+FFFD, so a value read back is the value written.
+ */
+const ENCODER = new TextEncoder();
+/** `text` as UTF-8; a lone surrogate becomes U+FFFD. */
+export function utf8Encode(text) {
+    return ENCODER.encode(text);
+}
+/** UTF-8 `bytes` as text; with `fatal`, bytes that are no UTF-8 throw a `TypeError`. */
+export function utf8Decode(bytes, options = {}) {
+    // `ignoreBOM: false` is the default, named because the Workers types require every option.
+    return new TextDecoder("utf-8", { fatal: options.fatal === true, ignoreBOM: false }).decode(bytes);
+}
+/** A streaming decoder: bytes may split a character across chunks. */
+export function utf8Decoder(options = {}) {
+    const decoder = new TextDecoder("utf-8", { fatal: options.fatal === true, ignoreBOM: false });
+    return { decode: (bytes, final) => decoder.decode(bytes, { stream: !final }) };
+}
+/** The UTF-8 length of `text`, without encoding it; a lone surrogate counts as the three bytes of U+FFFD. */
+export function utf8ByteLength(text) {
+    let bytes = 0;
+    for (let index = 0; index < text.length; index++) {
+        const code = text.charCodeAt(index);
+        if (code <= 0x7f)
+            bytes += 1;
+        else if (code <= 0x7ff)
+            bytes += 2;
+        else if (isHighSurrogate(code) && index + 1 < text.length && isLowSurrogate(text.charCodeAt(index + 1))) {
+            bytes += 4;
+            index++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+/** Whether `text` has no lone surrogates, so it encodes to UTF-8 and back unchanged. */
+export function isWellFormed(text) {
+    for (let index = 0; index < text.length; index++) {
+        const code = text.charCodeAt(index);
+        if (isHighSurrogate(code) && index + 1 < text.length && isLowSurrogate(text.charCodeAt(index + 1)))
+            index++;
+        else if (isHighSurrogate(code) || isLowSurrogate(code))
+            return false;
+    }
+    return true;
+}
+/** `text` with each lone surrogate replaced by U+FFFD. */
+export function toWellFormed(text) {
+    if (isWellFormed(text))
+        return text;
+    let result = "";
+    for (let index = 0; index < text.length; index++) {
+        const code = text.charCodeAt(index);
+        if (isHighSurrogate(code) && index + 1 < text.length && isLowSurrogate(text.charCodeAt(index + 1))) {
+            result += text.slice(index, index + 2);
+            index++;
+        }
+        else
+            result += isHighSurrogate(code) || isLowSurrogate(code) ? "�" : text.charAt(index);
+    }
+    return result;
+}
+/** Base64 written out here, since not every platform has `btoa`, `atob`, `Buffer` or `Uint8Array`'s base64 methods. */
+const ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const SEXTETS = new Map(Array.from(ALPHABET, (character, index) => [character, index]));
+/** How long a piece of the text grows before it is set aside: one string grown a character at a time is slow for megabytes. */
+const PIECE_LENGTH = 8192;
+/** `bytes` as base64 with padding. */
+export function toBase64(bytes) {
+    const pieces = [];
+    let piece = "";
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index] ?? 0;
+        const second = bytes[index + 1];
+        const third = bytes[index + 2];
+        const group = (first << 16) | ((second ?? 0) << 8) | (third ?? 0);
+        piece += ALPHABET.charAt(group >> 18) + ALPHABET.charAt((group >> 12) & 63);
+        piece += second === undefined ? "=" : ALPHABET.charAt((group >> 6) & 63);
+        piece += third === undefined ? "=" : ALPHABET.charAt(group & 63);
+        if (piece.length >= PIECE_LENGTH) {
+            pieces.push(piece);
+            piece = "";
+        }
+    }
+    pieces.push(piece);
+    return pieces.join("");
+}
+/** The bytes padded base64 `text` stands for; anything else throws a `SyntaxError`. */
+export function fromBase64(text) {
+    if (text.length % 4 !== 0)
+        throw notBase64();
+    const padding = text.endsWith("==") ? 2 : text.endsWith("=") ? 1 : 0;
+    const bytes = new Uint8Array((text.length / 4) * 3 - padding);
+    let written = 0;
+    for (let index = 0; index < text.length; index += 4) {
+        let group = 0;
+        for (let offset = 0; offset < 4; offset++) {
+            const character = text.charAt(index + offset);
+            const isPadding = character === "=" && index + offset >= text.length - padding;
+            const sextet = isPadding ? 0 : SEXTETS.get(character);
+            if (sextet === undefined)
+                throw notBase64();
+            group = (group << 6) | sextet;
+        }
+        for (const shift of [16, 8, 0]) {
+            if (written < bytes.length)
+                bytes[written++] = (group >> shift) & 255;
+        }
+    }
+    return bytes;
+}
+/** `bytes` as lowercase hex, two digits a byte. */
+export function toHex(bytes) {
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** `bytes` as base64url, without padding, as URLs and PKCE take it. */
+export function toBase64Url(bytes) {
+    return toBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/** The bytes base64url `text` stands for, padded or not; anything else throws a `SyntaxError`. */
+export function fromBase64Url(text) {
+    if (/[+/]/.test(text))
+        throw new SyntaxError("The text is not base64url");
+    const standard = text.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = standard.endsWith("=") ? standard : standard + "=".repeat((4 - (standard.length % 4)) % 4);
+    return new Uint8Array(fromBase64(padded));
+}
+function notBase64() {
+    return new SyntaxError("The text is not padded base64");
+}
+/** Whether a UTF-16 code unit is the first half of a surrogate pair. */
+function isHighSurrogate(code) {
+    return code >= 0xd800 && code <= 0xdbff;
+}
+/** Whether a UTF-16 code unit is the second half of a surrogate pair. */
+function isLowSurrogate(code) {
+    return code >= 0xdc00 && code <= 0xdfff;
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * What every package needs to report an unknown error. Each package defines its own error classes and codes.
+ */
+/** A readable message for anything thrown: an `Error`'s message, a string, or the value as JSON. */
+export declare function errorMessage(error: unknown): string;
+/**
+ * Throws for a value the type checker proved cannot exist, such as the case a `switch` over a discriminated union does
+ * not name: placed at the end of the `switch`, it makes a missing case a type error.
+ */
+export declare function unreachable(value: never): never;

package/dist/errors.js

@@ -0,0 +1,27 @@
+/**
+ * What every package needs to report an unknown error. Each package defines its own error classes and codes.
+ */
+/** A readable message for anything thrown: an `Error`'s message, a string, or the value as JSON. */
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    return asJson(error) ?? String(error);
+}
+/**
+ * Throws for a value the type checker proved cannot exist, such as the case a `switch` over a discriminated union does
+ * not name: placed at the end of the `switch`, it makes a missing case a type error.
+ */
+export function unreachable(value) {
+    throw new Error(`Unreachable: ${errorMessage(value)}`);
+}
+/** The JSON text of `value`, or undefined for a value JSON cannot hold, such as undefined, a cycle or a bigint. */
+function asJson(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return undefined;
+    }
+}