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

package/dist/{shared/ulid.js → esm/shared/ulid.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides how a sortable, unique id is made from the clock and random bytes.
  *
@@ -10,25 +9,12 @@
  * wrapping it, so a caller building a bound from a raw millisecond cannot be
  * handed a silently wrong one.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ULID_TIME_RANGE_MS = void 0;
-exports.secureRng = secureRng;
-exports.ulidTimePrefix = ulidTimePrefix;
-exports.createUlidFactory = createUlidFactory;
-const node_crypto_1 = require("node:crypto");
-const errors_1 = require("./errors/errors");
-const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
-const ENCODING_LEN = 32;
-const TIME_CHARS = 10;
-const RANDOM_CHARS = 16;
 /**
  * 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.
  */
-exports.ULID_TIME_RANGE_MS = ENCODING_LEN ** TIME_CHARS;
-/** Bytes drawn per refill of the {@link secureRng} pool: 16 ids per syscall. */
-const RNG_POOL_BYTES = 256;
+export declare const ULID_TIME_RANGE_MS: number;
 /**
  * A CSPRNG-backed `rng` seam.
  *
@@ -45,28 +31,7 @@ const RNG_POOL_BYTES = 256;
  * would order and disambiguate just as well but is not a cryptographically
  * secure source, which the ULID spec asks for in identifier generation.
  */
-function secureRng() {
-    let pool = Buffer.alloc(0);
-    let offset = 0;
-    return () => {
-        if (offset >= pool.length) {
-            pool = (0, node_crypto_1.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 declare function secureRng(): () => number;
 /**
  * The 10 time characters every ULID generated at `timeMs` starts with.
  *
@@ -92,31 +57,7 @@ function encodeTime(timeMs) {
  * clamped: clamping would hand back the same wrong page under a different
  * name.
  */
-function ulidTimePrefix(timeMs) {
-    if (!(timeMs >= 0 && timeMs < exports.ULID_TIME_RANGE_MS)) {
-        throw (0, errors_1.validationError)(`a ULID time prefix covers epoch milliseconds 0 to ${exports.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 declare function ulidTimePrefix(timeMs: number): string;
 /**
  * A monotonic ULID generator.
  *
@@ -136,25 +77,4 @@ function incrementDigits(digits) {
  * order only by their wall clocks at millisecond precision, so a lagging clock
  * can sort a later id before an earlier one.
  */
-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('');
-    };
-}
+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/{shared/validation/collaborators.js → esm/shared/validation/collaborators.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides what a collaborator a caller hands in must offer.
  *
@@ -8,32 +7,15 @@
  * `AbortSignal` has, so a wrong object fails where it was passed and not at the
  * first call deep inside an operation.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CANCEL_KEYS = exports.ABORT_SIGNAL_MEMBERS = exports.VECTOR_BACKEND_MEMBERS = exports.EMBEDDINGS_MEMBERS = exports.SERDE_MEMBERS = exports.LOGGER_MEMBERS = exports.CLIENT_MEMBERS = void 0;
-exports.assertMembers = assertMembers;
-exports.assertBaseCollaborators = assertBaseCollaborators;
-exports.isAbortSignalLike = isAbortSignalLike;
-exports.assertSignalLike = assertSignalLike;
-exports.assertCancelOptions = assertCancelOptions;
-const errors_1 = require("../errors/errors");
-const option_shape_1 = require("./option-shape");
+import type { CancelOptions } from '../options.js';
 /** The `DynamoDBDocument` methods this package calls on an injected `client`. */
-exports.CLIENT_MEMBERS = [
-    'get',
-    'put',
-    'delete',
-    'update',
-    'query',
-    'scan',
-    'batchWrite',
-    'transactWrite',
-];
+export declare const CLIENT_MEMBERS: readonly string[];
 /** The `Logger` methods every adapter calls. */
-exports.LOGGER_MEMBERS = ['debug', 'info', 'warn', 'error'];
+export declare const LOGGER_MEMBERS: readonly string[];
 /** The `SerializerProtocol` methods this package calls on `serde`. */
-exports.SERDE_MEMBERS = ['dumpsTyped', 'loadsTyped'];
+export declare const SERDE_MEMBERS: readonly string[];
 /** The `Embeddings` methods this package calls on `index.embeddings`. */
-exports.EMBEDDINGS_MEMBERS = ['embedQuery', 'embedDocuments'];
+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
@@ -41,7 +23,7 @@ exports.EMBEDDINGS_MEMBERS = ['embedQuery', 'embedDocuments'];
  * requiring it — requiring it here would refuse a backend shape this package
  * documents and supports.
  */
-exports.VECTOR_BACKEND_MEMBERS = ['upsert', 'query', 'delete'];
+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
@@ -49,11 +31,7 @@ exports.VECTOR_BACKEND_MEMBERS = ['upsert', 'query', 'delete'];
  * it again from inside its timer. `reason` is only read, which is safe on any
  * object, so it is not required.
  */
-exports.ABORT_SIGNAL_MEMBERS = {
-    aborted: 'boolean',
-    addEventListener: 'function',
-    removeEventListener: 'function',
-};
+export declare const ABORT_SIGNAL_MEMBERS: Readonly<Record<string, 'boolean' | 'function'>>;
 /**
  * Refuse a collaborator missing a method this package calls.
  *
@@ -74,16 +52,24 @@ exports.ABORT_SIGNAL_MEMBERS = {
  * its first method, which would point the caller at a method instead of at
  * the value.
  */
-function assertMembers(value, members, field) {
-    if (!(0, option_shape_1.isObjectShape)(value)) {
-        throw (0, errors_1.validationError)(`${field} must be an object`, field);
-    }
-    for (const member of members) {
-        if (typeof Reflect.get(value, member) !== 'function') {
-            throw (0, errors_1.validationError)(`${field}.${member} must be a function`, `${field}.${member}`);
-        }
-    }
-}
+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
@@ -98,16 +84,15 @@ function assertMembers(value, members, field) {
  * and this checks it. A collaborator the caller did not supply is left
  * untouched, so it still reaches its default.
  *
- * Throws: see {@link assertMembers}.
+ * 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.
  */
-function assertBaseCollaborators(options) {
-    if (options.client !== undefined)
-        assertMembers(options.client, exports.CLIENT_MEMBERS, 'client');
-    if (options.logger !== undefined)
-        assertMembers(options.logger, exports.LOGGER_MEMBERS, 'logger');
-    if (options.serde !== undefined)
-        assertMembers(options.serde, exports.SERDE_MEMBERS, 'serde');
-}
+export declare function assertBaseCollaborators(options: {
+    client?: object;
+    logger?: object;
+    serde?: object;
+}): void;
 /**
  * A value usable as an `AbortSignal`, checked by shape.
  *
@@ -123,11 +108,7 @@ function assertBaseCollaborators(options) {
  *
  * Throws: nothing.
  */
-function isAbortSignalLike(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
-    return Object.entries(exports.ABORT_SIGNAL_MEMBERS).every(([member, type]) => typeof Reflect.get(value, member) === type);
-}
+export declare function isAbortSignalLike(value: AbortSignal | undefined): boolean;
 /**
  * Throw `VALIDATION` naming `field` unless `value` is absent or
  * {@link isAbortSignalLike}.
@@ -147,11 +128,7 @@ function isAbortSignalLike(value) {
  * and fails there with a raw, unrelated error instead of naming the option
  * that caused it.
  */
-function assertSignalLike(value, field = 'signal') {
-    if (value !== undefined && !isAbortSignalLike(value)) {
-        throw (0, errors_1.validationError)(`${field} must be an AbortSignal`, field);
-    }
-}
+export declare function assertSignalLike(value: AbortSignal | undefined, field?: string): void;
 /**
  * The keys of a cancellation-only option bag, exhaustive in both directions.
  *
@@ -162,7 +139,7 @@ function assertSignalLike(value, field = 'signal') {
  * type it guards: an exhaustive list compiles, omitting or inventing a key
  * does not.
  */
-exports.CANCEL_KEYS = (0, option_shape_1.allKeysOf)({ signal: 'signal' });
+export declare const CANCEL_KEYS: readonly string[];
 /**
  * Reject a `{ signal }` bag carrying a key this package does not read.
  *
@@ -180,9 +157,4 @@ exports.CANCEL_KEYS = (0, option_shape_1.allKeysOf)({ signal: 'signal' });
  * Throws: `VALIDATION` naming `options.<key>` for the first key this
  * package does not read, or `signal` for a value that is not AbortSignal-like.
  */
-function assertCancelOptions(options) {
-    if (options === undefined)
-        return;
-    (0, option_shape_1.assertShape)(options, exports.CANCEL_KEYS, 'options');
-    assertSignalLike(options.signal);
-}
+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/{shared/validation/option-shape.js → esm/shared/validation/option-shape.d.ts}

@@ -1,20 +1,14 @@
-"use strict";
 /**
  * Hides how an option object is told apart from a misspelt one.
  *
- * An option type lists its keys once, checked by the compiler against the
- * type, and an object carrying any other key is refused naming that key. 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.
+ * 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.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.allKeysOf = allKeysOf;
-exports.isObjectShape = isObjectShape;
-exports.assertObjectShape = assertObjectShape;
-exports.assertShape = assertShape;
-exports.parseShape = parseShape;
-const errors_1 = require("../errors/errors");
 /**
  * Every key of `T`, listed once.
  *
@@ -28,9 +22,9 @@ const errors_1 = require("../errors/errors");
  *
  * Throws: nothing.
  */
-function allKeysOf(keys) {
-    return Object.values(keys);
-}
+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.
@@ -43,9 +37,7 @@ function allKeysOf(keys) {
  *
  * Throws: nothing.
  */
-function isObjectShape(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
+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.
@@ -57,11 +49,7 @@ function isObjectShape(value) {
  *
  * Throws: `VALIDATION` naming `field`.
  */
-function assertObjectShape(value, field) {
-    if (!isObjectShape(value)) {
-        throw (0, errors_1.validationError)(`${field} must be an object`, 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.
@@ -86,14 +74,7 @@ function assertObjectShape(value, field) {
  * object — neither row-sourced nor third-party — so the only person who can
  * make it enormous is the person reading the error.
  */
-function assertShape(value, allowed, field) {
-    assertObjectShape(value, field);
-    for (const key of Object.keys(value)) {
-        if (!allowed.includes(key)) {
-            throw (0, errors_1.validationError)(`${field}.${key} is not an option this package reads; expected one of ${allowed.join(', ')}`, `${field}.${key}`);
-        }
-    }
-}
+export declare function assertShape(value: object, allowed: readonly string[], field: string): void;
 /**
  * {@link assertShape}, returning `value` instead of nothing.
  *
@@ -107,7 +88,4 @@ function assertShape(value, allowed, field) {
  *
  * Throws: the same as {@link assertShape}.
  */
-function parseShape(value, allowed, field) {
-    assertShape(value, allowed, field);
-    return value;
-}
+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;
+}