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

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+The notable changes of `@octoii-works/octoii-std`, newest first.
+
+## [Unreleased]
+
+## [0.0.1] - 2026-10-31
+
+- 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/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @octoii-works/octoii-std
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The base every Octoii package stands on: JSON values and their changes, text encodings, hashes, ids, TypeBox
+validation, time and cancellation, a portable SQLite connection, Server-Sent Events, JSON-RPC 2.0, addresses and text
+diffs. It knows no agent, model or tool, and the same code runs on Bun, Node, browsers, workerd and the Hermes of
+React Native.
+
+Contents: [Where it sits](#where-it-sits) · [The subpaths](#the-subpaths) · [Everything from the caller](#everything-from-the-caller) ·
+[SQLite](#sqlite) · [Constants](#constants) · [Testing](#testing).
+
+## Where it sits
+
+```sh
+bun add @octoii-works/octoii-std
+```
+
+- **At the bottom.** std depends on TypeBox alone, and every other Octoii package depends on it.
+- **No root entry.** Every import names its subpath, so a program loads only what it uses:
+
+  ```ts
+  import { parseJson, type JsonValue } from "@octoii-works/octoii-std/json";
+  import { matches } from "@octoii-works/octoii-std/schema";
+  ```
+
+## The subpaths
+
+| Subpath | What it gives |
+| --- | --- |
+| `/json` | The JSON value model every package shares, `JsonValue` and `JsonObject`, with checks, `jsonEqual`, `copyJson` and a `parseJson` whose keys are own data only |
+| `/delta` | How a JSON value changed, as operations: `diffJson` and `applyOps` |
+| `/encoding` | UTF-8, base64, base64url and hex, strict when asked, so a value read back is the value written |
+| `/hash` | SHA-256 in plain JavaScript, synchronous on every platform, and HMAC, PKCE and the check of an RSA signature on it |
+| `/id` | UUIDs of versions 4 and 7, from the randomness and the time the caller passes |
+| `/schema` | TypeBox validators compiled once per schema, `matches`, `parsed` and `validationProblems`, with the same results where code cannot be generated |
+| `/async` | Clocks, `sleep`, timeouts (`withinLimit`), cancellation (`abortable`, `linkedSignal`) and backoff |
+| `/errors` | `errorMessage` for an unknown error, and `unreachable` |
+| `/sqlite` | A synchronous SQLite connection, `SqlDriver`, and consecutive schema migrations; its adapters are `/sqlite/bun`, `/sqlite/node` and `/sqlite/worker` |
+| `/sse` | An incremental Server-Sent Events decoder that does no I/O |
+| `/json-rpc` | JSON-RPC 2.0 messages, their checks, and the error codes as `JSON_RPC_ERRORS` |
+| `/url` | Absolute addresses parsed and normalized without a platform URL parser, and their queries |
+| `/text` | Text as editing tools read it: sizes and line counts, line endings, line diffs and the unified diff, and an edit's tiers |
+| `/testing` | `portabilityProblems`, the scan of platform-neutral sources against what Hermes lacks |
+
+## Everything from the caller
+
+std reads no clock, timer, randomness or environment of its own: a function that needs one takes it.
+
+```ts
+import { systemClock, withinLimit } from "@octoii-works/octoii-std/async";
+import { uuidv7 } from "@octoii-works/octoii-std/id";
+
+const random = (length: number) => crypto.getRandomValues(new Uint8Array(length));
+const id = uuidv7(systemClock.now(), random);
+const answer = await withinLimit(fetch("https://example.com"), 5_000, systemClock);
+if ("timedOut" in answer) console.log("gave up after 5 s");
+```
+
+So a test passes a fake clock and fixed bytes, and gets the same results every run.
+
+## SQLite
+
+```ts
+import { bunSqlite } from "@octoii-works/octoii-std/sqlite/bun";
+import { migrate } from "@octoii-works/octoii-std/sqlite";
+
+const db = bunSqlite("app.db", { durability: "full" });
+migrate(db, [
+	"CREATE TABLE notes (id TEXT PRIMARY KEY, text TEXT NOT NULL)",
+	"ALTER TABLE notes ADD COLUMN at INTEGER",
+]);
+```
+
+- **One interface, three platforms.** `bunSqlite` on Bun, `nodeSqlite` on Node, `durableObjectSql` in a Durable Object;
+  code written against `SqlDriver` runs on all three.
+- **Synchronous.** Every statement returns its rows, so a transaction never waits in the middle.
+- **Migrations count on.** `migrate` runs the statements past the schema's version, each once, in order.
+
+## Constants
+
+std's codes and limits are in one module, and each subpath gives those of its own, such as `JSON_RPC_ERRORS` from
+`/json-rpc`, `DIFF_CONTEXT_LINES` from `/text` and `PKCE_VERIFIER_BYTES` from `/hash`.
+
+## Testing
+
+Each module's tests run on Bun and on Node. `portabilityProblems` from `/testing` is what every Octoii package's tests
+use to keep platform-neutral code within what Hermes runs.

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>;