@farukada/aws-langgraph-dynamodb-ts 1.0.0-rc.1 → 1.0.0

package/dist/esm/shared/options.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Hides which options every adapter shares.
+ *
+ * The table, the client, the ttl, the logger, the retry policy, the recency
+ * index, the read concurrency, the codec options and per-call cancellation are
+ * declared once here, so the checkpointer, the store and the history accept
+ * the same keys with the same meaning, and an adapter-wide option is added in
+ * one place. This module holds their types only; checking them is elsewhere.
+ */
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import type { CompressionConfig } from './codec/compression.js';
+import type { S3OffloadConfig } from './codec/s3/config.js';
+import type { DynamoDBDocumentLike } from './dynamodb/client.js';
+import type { RetryPolicy } from './dynamodb/retry.js';
+import type { Logger } from './logging/logger.js';
+import type { TtlOption } from './validation/ttl.js';
+/**
+ * Options common to every adapter (the unified options shape). An adapter
+ * either reuses an injected `client` or builds one from `clientConfig`.
+ */
+export interface BaseAdapterOptions {
+    /** DynamoDB table name. */
+    tableName: string;
+    /** Pre-built DocumentClient to reuse; when set, the adapter does not own it. */
+    client?: DynamoDBDocumentLike;
+    /** The config a client is built from when `client` is not provided. */
+    clientConfig?: DynamoDBClientConfig;
+    /** Optional time-to-live applied to written items. */
+    ttl?: TtlOption;
+    /** Optional per-instance logger (defaults to a silent logger). */
+    logger?: Logger;
+    /** Retry budget and backoff for every DynamoDB call (see the README "Retries and backoff"). */
+    retry?: RetryPolicy;
+    /**
+     * Index partitions per adapter in the recency index (GSI1), default 8.
+     *
+     * Checkpoint and session rows carry the index attributes whether or not the
+     * table defines the index, so enabling it later needs only a backfill of the
+     * rows written before. The value is fixed for the table's life. Every row
+     * keeps the shard it was written with, and `backfillRecencyIndex` writes
+     * keys only to rows that have none, so it cannot move a row. Raising the
+     * count is safe: the old shards stay among the ones a listing queries.
+     * Lowering it hides every row on a dropped shard from the listings. The
+     * store takes no `indexShards`.
+     *
+     * A single index partition per adapter would concentrate every listing on
+     * one partition, which is worse than the table scan it replaces.
+     */
+    indexShards?: number;
+    /**
+     * Name of the recency index (a GSI on `gsi1pk`/`gsi1sk`) on this table.
+     *
+     * Opt-in on purpose: whether the table carries the index is deployment
+     * configuration the operator knows, and probing for it would spend a failed
+     * request per process to find out. Naming it switches two listings that
+     * would otherwise scan the whole table onto a read of the index, newest
+     * first: `history.listSessions`, which pages it by cursor, and a
+     * `saver.list` without a `thread_id`, which streams it and takes no cursor.
+     * Leaving it unset keeps both on the table scan, so the index can be created
+     * and backfilled before any adapter reads it.
+     *
+     * The store takes no `indexName`: its rootless search and its namespace
+     * listing stay table scans.
+     */
+    indexName?: string;
+    /**
+     * How many payloads a single call decodes at once, default 8.
+     *
+     * It is the multiplier on this package's memory ceiling, which is
+     * `readConcurrency × (s3.maxDownloadBytes + compression.maxDecompressedBytes)`
+     * — a downloaded object and its decompressed form are both resident while a
+     * payload is decoded, and that much can be in flight for each concurrent
+     * decode. Lower it on a small container; raising it trades memory for
+     * latency on reads that fetch many offloaded payloads.
+     *
+     * It also bounds how many recency-index shards one listing queries at once.
+     */
+    readConcurrency?: number;
+}
+/** Options enabling payload compression and/or S3 offloading. */
+export interface CodecOptions {
+    /** Gzip compression configuration. */
+    compression?: CompressionConfig;
+    /** S3 offload configuration for payloads over DynamoDB's item limit. */
+    s3?: S3OffloadConfig;
+}
+/** Per-call cancellation for the long-running adapter methods. */
+export interface CancelOptions {
+    /**
+     * Aborting it rejects the call with an `ABORTED` error — carrying the abort
+     * reason as `cause` — whether the signal was already aborted (nothing is
+     * sent), aborts while the call waits between requests, or aborts while a
+     * request is in flight: the signal reaches the AWS SDK on every DynamoDB
+     * request and S3 transfer the call makes for you, so the request itself
+     * ends. The verification reads and the cleanup that follow a failure run to
+     * completion regardless. A value that is not `AbortSignal`-shaped is refused
+     * with `VALIDATION` naming `signal` before anything is sent.
+     */
+    signal?: AbortSignal;
+}

package/dist/esm/shared/options.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/shared/ulid.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Hides how a sortable, unique id is made from the clock and random bytes.
+ *
+ * A caller gets ids whose byte order is their creation order, and a prefix
+ * that bounds every id from a given millisecond, without knowing the alphabet,
+ * the width of the time field or where the randomness comes from. One
+ * generator's ids strictly increase whatever the clock does, and
+ * `ulidTimePrefix` refuses a millisecond the encoding cannot hold rather than
+ * wrapping it, so a caller building a bound from a raw millisecond cannot be
+ * handed a silently wrong one.
+ */
+/**
+ * One past the last millisecond ten base-32 characters can hold: `32^10`,
+ * which is `2^50`, and lands in the year 37648. Derived rather than written
+ * down, so widening {@link TIME_CHARS} moves the rule with it.
+ */
+export declare const ULID_TIME_RANGE_MS: number;
+/**
+ * A CSPRNG-backed `rng` seam.
+ *
+ * Accepts: nothing. Each returned generator owns its own pool.
+ *
+ * Returns: a function yielding uniform values in `[0, 1)`, one byte per call,
+ * refilling from `crypto.randomBytes` every {@link RNG_POOL_BYTES} — so a burst
+ * of ids costs one syscall per 256 digits rather than one per digit.
+ *
+ * Throws: whatever `crypto.randomBytes` throws when the platform has no entropy.
+ *
+ * Guarantees: a digit drawn as `floor(rng() * 32)` is uniform over 0..31 —
+ * 256 is a whole multiple of 32, so there is no modulo bias. `Math.random`
+ * would order and disambiguate just as well but is not a cryptographically
+ * secure source, which the ULID spec asks for in identifier generation.
+ */
+export declare function secureRng(): () => number;
+/**
+ * The 10 time characters every ULID generated at `timeMs` starts with.
+ *
+ * Accepts: `timeMs` — epoch milliseconds inside `[0, {@link
+ * ULID_TIME_RANGE_MS})`, which is every instant the ten characters can encode.
+ *
+ * Returns: the prefix, usable as a sort-key bound — every id from that
+ * millisecond onward sorts at or after it, every earlier id before it.
+ *
+ * Throws: `VALIDATION` for a millisecond outside the range, naming no field:
+ * no caller-supplied option is at fault here, and the rule a caller meets is
+ * `parseMessageWindow`'s, which names `before`. This guard is the invariant
+ * underneath it, so no second caller can rebuild the bound that broke.
+ *
+ * Guarantees: exactly ten characters, all of them from the ULID alphabet.
+ * Neither held before. A negative millisecond took a negative remainder into
+ * the alphabet and yielded `undefined` per character, so the bound read
+ * `undefinedundefined…` — which sorts *above* every real id, since `u` and `d`
+ * are both above `Z` — and a window asking for messages before 1969 matched
+ * the whole conversation instead of none of it. A millisecond at or past the
+ * range wrapped to `0000000000` and matched nothing at all. Both are garbage
+ * indistinguishable from a real answer, so both are refused rather than
+ * clamped: clamping would hand back the same wrong page under a different
+ * name.
+ */
+export declare function ulidTimePrefix(timeMs: number): string;
+/**
+ * A monotonic ULID generator.
+ *
+ * Accepts: `now` — epoch milliseconds, default `Date.now`. `rng` — values in
+ * `[0, 1)`, default {@link secureRng}. Both are seams for deterministic tests.
+ *
+ * Returns: a function yielding lexicographically sortable 26-character ids
+ * whose first 10 characters encode the millisecond.
+ *
+ * Throws: whatever `rng` throws.
+ *
+ * Guarantees: ids from **one** generator strictly increase, whatever the clock
+ * does. A clock that advances starts a fresh random component; a clock that
+ * stalls or regresses reuses the last timestamp and increments that component;
+ * an increment that exhausts all 16 digits carries into the timestamp and draws
+ * fresh digits. Two generators — two processes, or two adapter instances —
+ * order only by their wall clocks at millisecond precision, so a lagging clock
+ * can sort a later id before an earlier one.
+ */
+export declare function createUlidFactory(now?: () => number, rng?: () => number): () => string;

package/dist/esm/shared/ulid.js

@@ -0,0 +1,77 @@
+import { randomBytes } from 'node:crypto';
+import { validationError } from './errors/errors.js';
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const ENCODING_LEN = 32;
+const TIME_CHARS = 10;
+const RANDOM_CHARS = 16;
+export const ULID_TIME_RANGE_MS = ENCODING_LEN ** TIME_CHARS;
+const RNG_POOL_BYTES = 256;
+export function secureRng() {
+    let pool = Buffer.alloc(0);
+    let offset = 0;
+    return () => {
+        if (offset >= pool.length) {
+            pool = randomBytes(RNG_POOL_BYTES);
+            offset = 0;
+        }
+        const byte = pool[offset];
+        offset += 1;
+        return byte / 256;
+    };
+}
+function encodeTime(timeMs) {
+    let remaining = Math.floor(timeMs);
+    let out = '';
+    for (let i = 0; i < TIME_CHARS; i++) {
+        out = ENCODING[remaining % ENCODING_LEN] + out;
+        remaining = Math.floor(remaining / ENCODING_LEN);
+    }
+    return out;
+}
+export function ulidTimePrefix(timeMs) {
+    if (!(timeMs >= 0 && timeMs < ULID_TIME_RANGE_MS)) {
+        throw validationError(`a ULID time prefix covers epoch milliseconds 0 to ${ULID_TIME_RANGE_MS - 1} (the year ` +
+            `37648); ${timeMs} is outside it and has no ten-character encoding`);
+    }
+    return encodeTime(timeMs);
+}
+function randomDigits(rng) {
+    const digits = [];
+    for (let i = 0; i < RANDOM_CHARS; i++) {
+        digits.push(Math.floor(rng() * ENCODING_LEN));
+    }
+    return digits;
+}
+function incrementDigits(digits) {
+    const next = [...digits];
+    for (let i = RANDOM_CHARS - 1; i >= 0; i--) {
+        if (next[i] < ENCODING_LEN - 1) {
+            next[i] += 1;
+            return { digits: next, overflowed: false };
+        }
+        next[i] = 0;
+    }
+    return { digits: next, overflowed: true };
+}
+export function createUlidFactory(now = Date.now, rng = secureRng()) {
+    let lastTime = -1;
+    let lastRandom = [];
+    return () => {
+        const time = now();
+        if (time > lastTime) {
+            lastTime = time;
+            lastRandom = randomDigits(rng);
+        }
+        else {
+            const result = incrementDigits(lastRandom);
+            if (result.overflowed) {
+                lastTime += 1;
+                lastRandom = randomDigits(rng);
+            }
+            else {
+                lastRandom = result.digits;
+            }
+        }
+        return encodeTime(lastTime) + lastRandom.map((digit) => ENCODING[digit]).join('');
+    };
+}

package/dist/esm/shared/validation/collaborators.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Hides what a collaborator a caller hands in must offer.
+ *
+ * An injected client, logger, serde, embeddings model or vector backend is
+ * checked by the members this package calls on it, and a cancellation signal
+ * — at construction or on a single call's options — by the members an
+ * `AbortSignal` has, so a wrong object fails where it was passed and not at the
+ * first call deep inside an operation.
+ */
+import type { CancelOptions } from '../options.js';
+/** The `DynamoDBDocument` methods this package calls on an injected `client`. */
+export declare const CLIENT_MEMBERS: readonly string[];
+/** The `Logger` methods every adapter calls. */
+export declare const LOGGER_MEMBERS: readonly string[];
+/** The `SerializerProtocol` methods this package calls on `serde`. */
+export declare const SERDE_MEMBERS: readonly string[];
+/** The `Embeddings` methods this package calls on `index.embeddings`. */
+export declare const EMBEDDINGS_MEMBERS: readonly string[];
+/**
+ * The `VectorBackend` methods this package calls. `listKeys` is deliberately
+ * excluded: it is optional on the interface (`store/vector-backend.ts`), and
+ * `reconcileVectorIndex` already branches on its absence and logs instead of
+ * requiring it — requiring it here would refuse a backend shape this package
+ * documents and supports.
+ */
+export declare const VECTOR_BACKEND_MEMBERS: readonly string[];
+/**
+ * Every `AbortSignal` member this package uses on a caller's `signal`, with
+ * the `typeof` each must have: `aborted` is read before a request and between
+ * pages, and the wait between retries attaches an abort listener and removes
+ * it again from inside its timer. `reason` is only read, which is safe on any
+ * object, so it is not required.
+ */
+export declare const ABORT_SIGNAL_MEMBERS: Readonly<Record<string, 'boolean' | 'function'>>;
+/**
+ * Refuse a collaborator missing a method this package calls.
+ *
+ * Checked by shape, never `instanceof`: the rule is banned repo-wide, and a
+ * duck-typed check also survives two copies of a dependency in one tree, which
+ * is exactly the situation an injected client comes from.
+ *
+ * Accepts: `value` — the collaborator as the caller gave it. `members` — every
+ * method this package calls on it. `field` — what the error names.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field` for a non-object, `null` or an array,
+ * and `field.member` for the first missing method — naming which member is
+ * missing is what turns a first-request crash into a startup error a caller
+ * can act on. An array is refused as a whole rather than reported as missing
+ * its first method, which would point the caller at a method instead of at
+ * the value.
+ */
+export declare function assertMembers(value: object, members: readonly string[], field: string): void;
+/**
+ * Refuse an injected client whose document translation changes what this
+ * package writes or reads back.
+ *
+ * Accepts: `client` — the injected document client, or any object standing in
+ * for one; one without `config.translateConfig` translates the default way.
+ *
+ * Returns: nothing: the client is kept under its declared type, and this checks it.
+ *
+ * Throws: `VALIDATION` naming `client` when its `unmarshallOptions.wrapNumbers`
+ * is set — every number this package reads back (a row's format version, a
+ * `ttl`, a message count) would arrive wrapped, so a newer row would read as
+ * version 0 and a session as malformed — or when its
+ * `marshallOptions.convertEmptyValues` is on, which stores the root checkpoint
+ * namespace, the empty string, as NULL.
+ */
+export declare function assertClientTranslation(client: object): void;
+/**
+ * Validate the collaborators every adapter shares: `client`, `logger` and
+ * `serde`. Pulled out of each `setUp*` as one call rather than three inline
+ * checks, so the three adapters check them the same way.
+ *
+ * Accepts: `options` — the adapter options, narrowed to the three shared
+ * collaborator fields. Every field here is typed as `object`, which a real
+ * `DynamoDBDocument`, `Logger` or `SerializerProtocol` all satisfy, so any
+ * adapter's options type is assignable without a cast.
+ *
+ * Returns: nothing: each collaborator given is kept under its declared type,
+ * and this checks it. A collaborator the caller did not supply is left
+ * untouched, so it still reaches its default.
+ *
+ * Throws: see {@link assertMembers} for a collaborator missing a method, and
+ * {@link assertClientTranslation} for a `client` whose translation would
+ * change how a row reads back.
+ */
+export declare function assertBaseCollaborators(options: {
+    client?: object;
+    logger?: object;
+    serde?: object;
+}): void;
+/**
+ * A value usable as an `AbortSignal`, checked by shape.
+ *
+ * `signal` is not a method bag like the collaborators above, so this returns
+ * a boolean rather than throwing: it never needs to be paired with the
+ * caller's own decision about what an absent signal means.
+ *
+ * Accepts: `value` — the caller's `signal`, or `undefined`.
+ *
+ * Returns: `true` when `value` is a non-null object whose every member in
+ * {@link ABORT_SIGNAL_MEMBERS} has the type listed there — `false` otherwise,
+ * including for `undefined`.
+ *
+ * Throws: nothing.
+ */
+export declare function isAbortSignalLike(value: AbortSignal | undefined): boolean;
+/**
+ * Throw `VALIDATION` naming `field` unless `value` is absent or
+ * {@link isAbortSignalLike}.
+ *
+ * Accepts: `value` — a caller's signal, or `undefined`. `field` — what the
+ * error names; `signal` by default, and the full path for a signal nested in
+ * another option (`retry.signal`), so a caller whose top-level `signal` is
+ * valid is not pointed at it.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`. Left unchecked, a value that is not
+ * an `AbortSignal` reaches whatever this package hands it to — an
+ * `addEventListener` call, a retry loop reading `.aborted`, a
+ * `removeEventListener` call from inside a timer, where nothing can catch it —
+ * and fails there with a raw, unrelated error instead of naming the option
+ * that caused it.
+ */
+export declare function assertSignalLike(value: AbortSignal | undefined, field?: string): void;
+/**
+ * The keys of a cancellation-only option bag, exhaustive in both directions.
+ *
+ * Every feature's own option-bag lists live in that feature's `internal/`
+ * directory, beside the types they are checked against;
+ * `shared/` knows no feature. This one stays here because `CancelOptions` is
+ * shared by all three. `allKeysOf<T>` keeps the list from drifting from the
+ * type it guards: an exhaustive list compiles, omitting or inventing a key
+ * does not.
+ */
+export declare const CANCEL_KEYS: readonly string[];
+/**
+ * Reject a `{ signal }` bag carrying a key this package does not read.
+ *
+ * Pulled out as one call because several methods across three classes take
+ * only cancellation (`addMessages`, `addMessage`, `clear`,
+ * `reconcileMessageCount`, `deleteThread`, `reconcileVectorIndex`) — one
+ * shared check keeps their wording and their key list from drifting apart.
+ *
+ * Accepts: `options` — as the caller passed it; absent is left alone, since
+ * there is nothing to check.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `options.<key>` for the first key this
+ * package does not read, or `signal` for a value that is not AbortSignal-like.
+ */
+export declare function assertCancelOptions(options: CancelOptions | undefined): void;

package/dist/esm/shared/validation/collaborators.js

@@ -0,0 +1,70 @@
+import { validationError } from '../errors/errors.js';
+import { allKeysOf, assertShape, isObjectShape } from './option-shape.js';
+export const CLIENT_MEMBERS = [
+    'get',
+    'put',
+    'delete',
+    'update',
+    'query',
+    'scan',
+    'batchWrite',
+    'transactWrite',
+];
+export const LOGGER_MEMBERS = ['debug', 'info', 'warn', 'error'];
+export const SERDE_MEMBERS = ['dumpsTyped', 'loadsTyped'];
+export const EMBEDDINGS_MEMBERS = ['embedQuery', 'embedDocuments'];
+export const VECTOR_BACKEND_MEMBERS = ['upsert', 'query', 'delete'];
+export const ABORT_SIGNAL_MEMBERS = {
+    aborted: 'boolean',
+    addEventListener: 'function',
+    removeEventListener: 'function',
+};
+export function assertMembers(value, members, field) {
+    if (!isObjectShape(value)) {
+        throw validationError(`${field} must be an object`, field);
+    }
+    for (const member of members) {
+        if (typeof Reflect.get(value, member) !== 'function') {
+            throw validationError(`${field}.${member} must be a function`, `${field}.${member}`);
+        }
+    }
+}
+export function assertClientTranslation(client) {
+    const translate = client.config?.translateConfig;
+    if (translate?.unmarshallOptions?.wrapNumbers) {
+        throw validationError('client reads numbers back wrapped (unmarshallOptions.wrapNumbers), where this package ' +
+            'reads a row version, a ttl and a count as numbers; inject a DynamoDBDocument built ' +
+            'without it', 'client');
+    }
+    if (translate?.marshallOptions?.convertEmptyValues === true) {
+        throw validationError('client stores an empty string as NULL (marshallOptions.convertEmptyValues), which erases ' +
+            'the root checkpoint namespace; inject a DynamoDBDocument built without it', 'client');
+    }
+}
+export function assertBaseCollaborators(options) {
+    if (options.client !== undefined) {
+        assertMembers(options.client, CLIENT_MEMBERS, 'client');
+        assertClientTranslation(options.client);
+    }
+    if (options.logger !== undefined)
+        assertMembers(options.logger, LOGGER_MEMBERS, 'logger');
+    if (options.serde !== undefined)
+        assertMembers(options.serde, SERDE_MEMBERS, 'serde');
+}
+export function isAbortSignalLike(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return Object.entries(ABORT_SIGNAL_MEMBERS).every(([member, type]) => typeof Reflect.get(value, member) === type);
+}
+export function assertSignalLike(value, field = 'signal') {
+    if (value !== undefined && !isAbortSignalLike(value)) {
+        throw validationError(`${field} must be an AbortSignal`, field);
+    }
+}
+export const CANCEL_KEYS = allKeysOf({ signal: 'signal' });
+export function assertCancelOptions(options) {
+    if (options === undefined)
+        return;
+    assertShape(options, CANCEL_KEYS, 'options');
+    assertSignalLike(options.signal);
+}

package/dist/esm/shared/validation/option-shape.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Hides how an option object is told apart from a misspelt one.
+ *
+ * An option type this package defines lists its keys once, checked by the
+ * compiler against the type, and an object carrying any other key is refused
+ * naming that key. An option object LangGraph defines is only held to being an
+ * object, since a key a later LangGraph adds must not refuse a call LangGraph
+ * makes (decision record 28). No caller writes the plain-object test or the
+ * unknown-key walk itself, so the message and the field a refusal names are the
+ * same for every option object this package reads.
+ */
+/**
+ * Every key of `T`, listed once.
+ *
+ * Accepts: an object naming every key of `T` as its own value. The parameter's
+ * type makes the list exhaustive in both directions: omitting a key the type
+ * declares, or naming one it does not, fails to compile — so the list cannot
+ * drift from the option type it guards, which matters because the list is what
+ * decides that a key is *unknown*.
+ *
+ * Returns: the keys.
+ *
+ * Throws: nothing.
+ */
+export declare function allKeysOf<T extends object>(keys: {
+    [K in keyof Required<T>]: K;
+}): readonly string[];
+/**
+ * Whether a value is a plain object: an object at all, not `null`, and not an
+ * array.
+ *
+ * Accepts: `value` — as the caller gave it, `undefined` included.
+ *
+ * Returns: true exactly when {@link assertObjectShape} would accept `value`.
+ * For code that must decide what to do with a malformed value rather than
+ * refuse it on the spot.
+ *
+ * Throws: nothing.
+ */
+export declare function isObjectShape(value: object | undefined): value is object;
+/**
+ * Reject a value that is not a plain object: not an object at all, `null`, or
+ * an array.
+ *
+ * Accepts: `value` — as the caller gave it. `field` — what the error names.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ */
+export declare function assertObjectShape(value: object, field: string): void;
+/**
+ * Reject an option object that is not an object, or that carries a key this
+ * package does not read.
+ *
+ * Accepts: `value` — the option object as the caller gave it. `allowed` — the
+ * key list from {@link allKeysOf}. `field` — what the error names.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field` for a value that is not an object, and
+ * `field.key` for an unknown key. A misspelt key is otherwise accepted and
+ * ignored, and the caller runs on a default they believe they overrode.
+ *
+ * `field.key` is **deliberately not cut**, where the rule that bounds an
+ * unchecked string before a message quotes it would otherwise reach it. The
+ * same string is the message *and* `context.field`, and `context.field` is the
+ * compatibility surface a caller branches on, so cutting one and not the other
+ * would make an error disagree with itself about which option it refused.
+ * Cutting both would bound a field callers match on, which this package does
+ * not do. The value is also the caller's own key off the caller's own options
+ * object — neither row-sourced nor third-party — so the only person who can
+ * make it enormous is the person reading the error.
+ */
+export declare function assertShape(value: object, allowed: readonly string[], field: string): void;
+/**
+ * {@link assertShape}, returning `value` instead of nothing.
+ *
+ * Accepts: the same arguments as {@link assertShape}.
+ *
+ * Returns: `value`, unchanged. This returning form exists because a subclass
+ * constructor cannot run a statement before `super(...)`, so validating an
+ * argument bound for `super(...)` has to happen inside that expression —
+ * `super(parseShape(options, ALLOWED, 'options').thing)` — where a `void`
+ * function would not compile.
+ *
+ * Throws: the same as {@link assertShape}.
+ */
+export declare function parseShape<T extends object>(value: T, allowed: readonly string[], field: string): T;

package/dist/esm/shared/validation/option-shape.js

@@ -0,0 +1,24 @@
+import { validationError } from '../errors/errors.js';
+export function allKeysOf(keys) {
+    return Object.keys(keys);
+}
+export function isObjectShape(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function assertObjectShape(value, field) {
+    if (!isObjectShape(value)) {
+        throw validationError(`${field} must be an object`, field);
+    }
+}
+export function assertShape(value, allowed, field) {
+    assertObjectShape(value, field);
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            throw validationError(`${field}.${key} is not an option this package reads; expected one of ${allowed.join(', ')}`, `${field}.${key}`);
+        }
+    }
+}
+export function parseShape(value, allowed, field) {
+    assertShape(value, allowed, field);
+    return value;
+}