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

package/dist/store/internal/query.d.ts

@@ -1,11 +0,0 @@
-import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
-/** Query input for a scoped prefix (PK = prefix[0], optional SK begins_with). */
-export declare function scopedQuery(tableName: string, prefix: string[]): QueryCommandInput;
-/** Scan input for the rootless case, filtered to store items only. */
-export declare function storeScan(tableName: string): ScanCommandInput;
-/**
- * Restrict a Query/Scan to the attributes `narrowStoreRecord` needs, leaving the
- * payload behind: a namespace listing never reads a value. RCU is billed on
- * the stored size regardless, so the saving is transfer and unmarshalling.
- */
-export declare function projectKeys<T extends QueryCommandInput | ScanCommandInput>(params: T): T;

package/dist/store/internal/query.js

@@ -1,48 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.scopedQuery = scopedQuery;
-exports.storeScan = storeScan;
-exports.projectKeys = projectKeys;
-const keys_1 = require("./keys");
-/** Query input for a scoped prefix (PK = prefix[0], optional SK begins_with). */
-function scopedQuery(tableName, prefix) {
-    const skPrefix = (0, keys_1.sortKeyPrefix)(prefix);
-    if (skPrefix.length === 0) {
-        return {
-            TableName: tableName,
-            KeyConditionExpression: '#pk = :pk',
-            ExpressionAttributeNames: { '#pk': 'PK' },
-            ExpressionAttributeValues: { ':pk': (0, keys_1.partitionKey)(prefix) },
-        };
-    }
-    return {
-        TableName: tableName,
-        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
-        ExpressionAttributeNames: { '#pk': 'PK', '#sk': 'SK' },
-        ExpressionAttributeValues: { ':pk': (0, keys_1.partitionKey)(prefix), ':skp': skPrefix },
-    };
-}
-/** Scan input for the rootless case, filtered to store items only. */
-function storeScan(tableName) {
-    return {
-        TableName: tableName,
-        FilterExpression: 'attribute_exists(#ns)',
-        ExpressionAttributeNames: { '#ns': 'namespace' },
-    };
-}
-/**
- * Restrict a Query/Scan to the attributes `narrowStoreRecord` needs, leaving the
- * payload behind: a namespace listing never reads a value. RCU is billed on
- * the stored size regardless, so the saving is transfer and unmarshalling.
- */
-function projectKeys(params) {
-    return {
-        ...params,
-        ProjectionExpression: 'PK, SK, #ns, #key',
-        ExpressionAttributeNames: {
-            ...params.ExpressionAttributeNames,
-            '#ns': 'namespace',
-            '#key': 'key',
-        },
-    };
-}

package/dist/store/internal/ranker.d.ts

@@ -1,18 +0,0 @@
-import type { Item, SearchItem } from '@langchain/langgraph-checkpoint';
-/** A decoded item plus its stored embedding, awaiting ranking. */
-export interface RankCandidate {
-    item: Item;
-    embedding?: number[];
-}
-/**
- * Rank candidates by cosine similarity to `queryVector`, descending. Throws a
- * {@link ValidationError} when the candidate count exceeds `maxCandidates`
- * (steer large corpora to an external VectorBackend).
- *
- * A stored embedding whose length differs from the query vector's cannot be
- * scored — it was written by a different embeddings model — and is ranked
- * last with an undefined score. `onDimensionMismatch` is invoked once with
- * how many candidates that affected, so the caller can say so instead of
- * silently returning a ranking that quietly omits them.
- */
-export declare function rankInMemory(candidates: RankCandidate[], queryVector: number[], maxCandidates: number, onDimensionMismatch?: (count: number) => void): SearchItem[];

package/dist/store/internal/ranker.js

@@ -1,39 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.rankInMemory = rankInMemory;
-const errors_1 = require("../../shared/errors/errors");
-const semantic_search_1 = require("./semantic-search");
-/** Sort weight for an item without an embedding; below the −1 cosine minimum. */
-const UNSCORED_RANK = -2;
-/**
- * Rank candidates by cosine similarity to `queryVector`, descending. Throws a
- * {@link ValidationError} when the candidate count exceeds `maxCandidates`
- * (steer large corpora to an external VectorBackend).
- *
- * A stored embedding whose length differs from the query vector's cannot be
- * scored — it was written by a different embeddings model — and is ranked
- * last with an undefined score. `onDimensionMismatch` is invoked once with
- * how many candidates that affected, so the caller can say so instead of
- * silently returning a ranking that quietly omits them.
- */
-function rankInMemory(candidates, queryVector, maxCandidates, onDimensionMismatch) {
-    if (candidates.length > maxCandidates) {
-        throw new errors_1.ValidationError(`Semantic search candidate set (${candidates.length}) exceeds maxSearchCandidates ` +
-            `(${maxCandidates}); use a dedicated VectorBackend for large corpora`, 'maxSearchCandidates');
-    }
-    const mismatched = candidates.filter(({ embedding }) => embedding !== undefined && embedding.length !== queryVector.length).length;
-    if (mismatched > 0)
-        onDimensionMismatch?.(mismatched);
-    return candidates
-        .map(({ item, embedding }) => ({
-        ...item,
-        score: embedding && embedding.length === queryVector.length
-            ? (0, semantic_search_1.cosineSimilarity)(queryVector, embedding)
-            : undefined,
-    }))
-        .sort((a, b) => rankValue(b) - rankValue(a));
-}
-/** Sort weight: real cosine score, or a value below the cosine minimum for unscored items. */
-function rankValue(item) {
-    return item.score ?? UNSCORED_RANK;
-}

package/dist/store/internal/read-existing.d.ts

@@ -1,23 +0,0 @@
-import type { DescriptorRef } from '../../shared/codec/descriptor-keys';
-import type { DocItem } from '../../shared/dynamodb/types';
-import type { StoreContext } from './setup';
-/** The previous row's createdAt, payload descriptor and revision. */
-export interface ExistingRecordMeta {
-    exists: boolean;
-    createdAt?: string;
-    value?: DescriptorRef;
-    revision?: string;
-}
-/**
- * Read the fields a put needs from the row it is about to replace, in one
- * strongly-consistent projection: `createdAt` to preserve, the descriptor's
- * location and S3 key to clean up afterwards (never its inline bytes, which
- * can be hundreds of kilobytes the write would only discard), and the
- * revision the compare-and-swap pins.
- *
- * Lives apart from `actions/put.ts` so `persist.ts` can re-read on a lost swap
- * without importing its own caller.
- */
-export declare function readExisting(context: StoreContext, pk: string, sk: string): Promise<ExistingRecordMeta>;
-/** Project a raw row (a read result, or the row a rejection carried) onto {@link ExistingRecordMeta}. */
-export declare function existingFrom(item: DocItem | undefined): ExistingRecordMeta;

package/dist/store/internal/read-existing.js

@@ -1,41 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.readExisting = readExisting;
-exports.existingFrom = existingFrom;
-const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
-const retry_1 = require("../../shared/dynamodb/retry");
-/**
- * Read the fields a put needs from the row it is about to replace, in one
- * strongly-consistent projection: `createdAt` to preserve, the descriptor's
- * location and S3 key to clean up afterwards (never its inline bytes, which
- * can be hundreds of kilobytes the write would only discard), and the
- * revision the compare-and-swap pins.
- *
- * Lives apart from `actions/put.ts` so `persist.ts` can re-read on a lost swap
- * without importing its own caller.
- */
-async function readExisting(context, pk, sk) {
-    const existing = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-        TableName: context.tableName,
-        Key: { PK: pk, SK: sk },
-        ConsistentRead: true,
-        ProjectionExpression: '#c, #r, #v.#loc, #v.#s3k',
-        ExpressionAttributeNames: {
-            '#c': 'createdAt',
-            '#r': conditional_put_1.REVISION_ATTRIBUTE,
-            '#v': 'value',
-            '#loc': 'location',
-            '#s3k': 's3Key',
-        },
-    }), context.retry);
-    return existingFrom(existing.Item);
-}
-/** Project a raw row (a read result, or the row a rejection carried) onto {@link ExistingRecordMeta}. */
-function existingFrom(item) {
-    return {
-        exists: item !== undefined,
-        createdAt: item?.createdAt,
-        value: item?.value,
-        revision: item?.[conditional_put_1.REVISION_ATTRIBUTE],
-    };
-}

package/dist/store/internal/score-direction.d.ts

@@ -1,31 +0,0 @@
-import type { VectorMatch } from '../vector-backend';
-/** Which direction a {@link VectorBackend} reports its score in. */
-export type VectorScoreDirection = 'relevance' | 'distance';
-/** Every direction {@link toRelevanceScores} recognises, for validating input. */
-export declare const VECTOR_SCORE_DIRECTIONS: readonly VectorScoreDirection[];
-/**
- * Normalise a backend's matches to the relevance direction upstream
- * `SearchItem.score` documents — "higher scores indicate better matches",
- * typically a cosine similarity between -1 and 1.
- *
- * A distance is converted by **negation** rather than `1 / (1 + d)`: negation
- * is monotone over the whole real line, needs no non-negativity precondition,
- * and is exactly invertible, so the original distance is simply `-score`. A
- * reciprocal would silently imply a different `(0, 1]` scale and is undefined
- * at `d === -1`. Negative scores are already in range for this contract, so
- * nothing is lost by producing them.
- *
- * Results are re-sorted after conversion so a backend that returns its matches
- * in some other order still ranks correctly. Anything that is not `'distance'`
- * is returned untouched — its own order stays authoritative, exactly as before.
- *
- * The test is for `'distance'` rather than against `'relevance'` on purpose:
- * converting is the destructive branch, so only the exact value that asks for
- * it may reach it. Testing the other way round made every unrecognised
- * string — `'Distance'`, a typo, a value read from a config file — reverse the
- * ranking silently, with no error and no warning (the ascending-score warning
- * lives downstream of this conversion, so it could never fire). `setUpStore`
- * rejects such a value outright; this keeps the failure harmless for any
- * caller that reaches the function some other way.
- */
-export declare function toRelevanceScores(matches: VectorMatch[], direction: VectorScoreDirection): VectorMatch[];

package/dist/store/internal/score-direction.js

@@ -1,38 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.VECTOR_SCORE_DIRECTIONS = void 0;
-exports.toRelevanceScores = toRelevanceScores;
-/** Every direction {@link toRelevanceScores} recognises, for validating input. */
-exports.VECTOR_SCORE_DIRECTIONS = ['relevance', 'distance'];
-/**
- * Normalise a backend's matches to the relevance direction upstream
- * `SearchItem.score` documents — "higher scores indicate better matches",
- * typically a cosine similarity between -1 and 1.
- *
- * A distance is converted by **negation** rather than `1 / (1 + d)`: negation
- * is monotone over the whole real line, needs no non-negativity precondition,
- * and is exactly invertible, so the original distance is simply `-score`. A
- * reciprocal would silently imply a different `(0, 1]` scale and is undefined
- * at `d === -1`. Negative scores are already in range for this contract, so
- * nothing is lost by producing them.
- *
- * Results are re-sorted after conversion so a backend that returns its matches
- * in some other order still ranks correctly. Anything that is not `'distance'`
- * is returned untouched — its own order stays authoritative, exactly as before.
- *
- * The test is for `'distance'` rather than against `'relevance'` on purpose:
- * converting is the destructive branch, so only the exact value that asks for
- * it may reach it. Testing the other way round made every unrecognised
- * string — `'Distance'`, a typo, a value read from a config file — reverse the
- * ranking silently, with no error and no warning (the ascending-score warning
- * lives downstream of this conversion, so it could never fire). `setUpStore`
- * rejects such a value outright; this keeps the failure harmless for any
- * caller that reaches the function some other way.
- */
-function toRelevanceScores(matches, direction) {
-    if (direction !== 'distance')
-        return matches;
-    return matches
-        .map((match) => ({ ...match, score: -match.score }))
-        .sort((left, right) => right.score - left.score);
-}

package/dist/store/internal/search-filter.d.ts

@@ -1,3 +0,0 @@
-import type { Item, SearchOperation } from '@langchain/langgraph-checkpoint';
-/** True when `item` satisfies the search operation's optional metadata filter. */
-export declare function passesFilter(item: Item, op: SearchOperation): boolean;

package/dist/store/internal/search-filter.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.passesFilter = passesFilter;
-const filter_1 = require("./filter");
-/** True when `item` satisfies the search operation's optional metadata filter. */
-function passesFilter(item, op) {
-    if (!op.filter)
-        return true;
-    return (0, filter_1.matchesStoreFilter)(item.value, op.filter);
-}

package/dist/store/internal/semantic-search.d.ts

@@ -1,34 +0,0 @@
-import type { IndexConfig } from '@langchain/langgraph-checkpoint';
-import type { JsonValue } from './filter';
-import type { StoreContext } from './setup';
-/** Cosine similarity of two equal-length vectors; 0 for zero/mismatched vectors. */
-export declare function cosineSimilarity(a: number[], b: number[]): number;
-/**
- * Extract and join the indexable text of a value for the configured fields,
- * byte-for-byte as LangGraph's `InMemoryStore` does (see `text-path.ts`), so
- * the two stores embed identical text for identical documents.
- */
-export declare function extractText(value: Record<string, JsonValue>, fields: string[]): string;
-/**
- * Reject a vector whose length disagrees with the configured `index.dims`. A
- * mismatch means the embeddings model does not match the configuration, so
- * every stored vector would be incomparable with every query; failing here
- * surfaces that at the first put or search instead of ranking silently. The
- * check is skipped when `dims` is not a positive integer, since nothing else
- * in this package reads it.
- */
-export declare function assertVectorDims(index: IndexConfig, vector: number[], what: string): void;
-/**
- * Embed several values for indexing with `embedDocuments` — the document-side
- * method; providers such as Titan and Cohere embed documents and queries with
- * different task types, so embedding a document with `embedQuery` degrades
- * retrieval — batched and order-preserving. A value with no indexable text
- * yields `undefined`; without an index every value does.
- */
-export declare function embedValues(context: StoreContext, values: Record<string, JsonValue>[], fieldsOverride?: string[]): Promise<(number[] | undefined)[]>;
-/**
- * Embed one value for indexing, or undefined when indexing is off or the text
- * is empty. `fieldsOverride` (from a put's `index` option) takes precedence
- * over the store's configured fields. See {@link embedValues}.
- */
-export declare function embedValue(context: StoreContext, value: Record<string, JsonValue>, fieldsOverride?: string[]): Promise<number[] | undefined>;

package/dist/store/internal/semantic-search.js

@@ -1,87 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.cosineSimilarity = cosineSimilarity;
-exports.extractText = extractText;
-exports.assertVectorDims = assertVectorDims;
-exports.embedValues = embedValues;
-exports.embedValue = embedValue;
-const errors_1 = require("../../shared/errors/errors");
-const text_path_1 = require("./text-path");
-/** Texts per `embedDocuments` call; keeps provider request sizes bounded. */
-const EMBED_BATCH_SIZE = 100;
-/** Cosine similarity of two equal-length vectors; 0 for zero/mismatched vectors. */
-function cosineSimilarity(a, b) {
-    if (a.length !== b.length)
-        return 0;
-    let dot = 0;
-    let normA = 0;
-    let normB = 0;
-    for (let i = 0; i < a.length; i++) {
-        dot += a[i] * b[i];
-        normA += a[i] * a[i];
-        normB += b[i] * b[i];
-    }
-    if (normA === 0 || normB === 0)
-        return 0;
-    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
-}
-/**
- * Extract and join the indexable text of a value for the configured fields,
- * byte-for-byte as LangGraph's `InMemoryStore` does (see `text-path.ts`), so
- * the two stores embed identical text for identical documents.
- */
-function extractText(value, fields) {
-    return fields.flatMap((field) => (0, text_path_1.getTextAtPath)(value, field)).join(' ');
-}
-/**
- * Reject a vector whose length disagrees with the configured `index.dims`. A
- * mismatch means the embeddings model does not match the configuration, so
- * every stored vector would be incomparable with every query; failing here
- * surfaces that at the first put or search instead of ranking silently. The
- * check is skipped when `dims` is not a positive integer, since nothing else
- * in this package reads it.
- */
-function assertVectorDims(index, vector, what) {
-    const dims = index.dims;
-    if (!Number.isInteger(dims) || dims <= 0 || vector.length === dims)
-        return;
-    throw new errors_1.ValidationError(`index.embeddings returned a ${vector.length}-dimensional ${what} vector but index.dims ` +
-        `is ${dims}; the embeddings model does not match the configured index`, 'index.dims');
-}
-/**
- * Embed several values for indexing with `embedDocuments` — the document-side
- * method; providers such as Titan and Cohere embed documents and queries with
- * different task types, so embedding a document with `embedQuery` degrades
- * retrieval — batched and order-preserving. A value with no indexable text
- * yields `undefined`; without an index every value does.
- */
-async function embedValues(context, values, fieldsOverride) {
-    const index = context.index;
-    if (!index)
-        return values.map(() => undefined);
-    const fields = fieldsOverride ?? index.fields ?? ['$'];
-    const pending = [];
-    values.forEach((value, position) => {
-        const text = extractText(value, fields);
-        if (text.length > 0)
-            pending.push({ text, position });
-    });
-    const vectors = values.map(() => undefined);
-    for (let start = 0; start < pending.length; start += EMBED_BATCH_SIZE) {
-        const batch = pending.slice(start, start + EMBED_BATCH_SIZE);
-        const embedded = await index.embeddings.embedDocuments(batch.map((entry) => entry.text));
-        batch.forEach((entry, i) => {
-            assertVectorDims(index, embedded[i], 'document');
-            vectors[entry.position] = embedded[i];
-        });
-    }
-    return vectors;
-}
-/**
- * Embed one value for indexing, or undefined when indexing is off or the text
- * is empty. `fieldsOverride` (from a put's `index` option) takes precedence
- * over the store's configured fields. See {@link embedValues}.
- */
-async function embedValue(context, value, fieldsOverride) {
-    return (await embedValues(context, [value], fieldsOverride))[0];
-}

package/dist/store/internal/setup.d.ts

@@ -1,36 +0,0 @@
-import type { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
-import type { IndexConfig, SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { CompressionConfig } from '../../shared/codec/compression';
-import { S3Offloader } from '../../shared/codec/s3/offloader';
-import type { RetryOptions } from '../../shared/dynamodb/retry';
-import { type Logger } from '../../shared/logging/logger';
-import type { TtlOption } from '../../shared/validation/ttl';
-import type { DynamoDBStoreOptions } from '../types';
-import type { VectorBackend } from '../vector-backend';
-import type { VectorScoreDirection } from './score-direction';
-/** Resolved collaborators shared by every store action. */
-export interface StoreContext {
-    client: DynamoDBDocument;
-    tableName: string;
-    serde: SerializerProtocol;
-    compression?: CompressionConfig;
-    offloader?: S3Offloader;
-    ttl?: TtlOption;
-    logger: Logger;
-    index?: IndexConfig;
-    vectorBackend?: VectorBackend;
-    vectorScoreDirection: VectorScoreDirection;
-    maxSearchCandidates: number;
-    maxScanItems: number;
-    /** Retry budget and backoff for every DynamoDB call, with the retry debug log attached. */
-    retry?: RetryOptions;
-}
-/** Result of wiring up a store from its options. */
-export interface StoreSetup {
-    context: StoreContext;
-    ddbClient: DynamoDBClient | undefined;
-    ownsClient: boolean;
-}
-/** Validate the options, then resolve the client, offloader, serializer, and index. */
-export declare function setUpStore(options: DynamoDBStoreOptions): StoreSetup;

package/dist/store/internal/setup.js

@@ -1,40 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.setUpStore = setUpStore;
-const json_serde_1 = require("../../shared/codec/json-serde");
-const adapter_config_1 = require("../../shared/codec/s3/adapter-config");
-const offloader_1 = require("../../shared/codec/s3/offloader");
-const constants_1 = require("../../shared/constants");
-const client_1 = require("../../shared/dynamodb/client");
-const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
-const logger_1 = require("../../shared/logging/logger");
-const option_validation_1 = require("./option-validation");
-/** Validate the options, then resolve the client, offloader, serializer, and index. */
-function setUpStore(options) {
-    (0, option_validation_1.validateStoreOptions)(options);
-    const logger = (0, logger_1.resolveLogger)(options.logger);
-    const resolved = (0, client_1.resolveDynamoDBClient)(options);
-    if (!resolved.ownsClient)
-        void (0, client_1.warnOnStackedRetries)(resolved.client, logger);
-    return {
-        context: {
-            client: resolved.client,
-            tableName: options.tableName,
-            serde: options.serde ?? json_serde_1.JSON_SERDE,
-            compression: options.compression,
-            offloader: options.s3
-                ? new offloader_1.S3Offloader((0, adapter_config_1.offloaderConfigFor)(options.s3, 'store', options.clientConfig))
-                : undefined,
-            ttl: options.ttl,
-            logger,
-            retry: (0, retry_policy_1.resolveRetryPolicy)(options.retry, logger),
-            index: options.index,
-            vectorBackend: options.vectorBackend,
-            vectorScoreDirection: options.vectorScoreDirection ?? 'relevance',
-            maxSearchCandidates: options.maxSearchCandidates ?? constants_1.DEFAULT_MAX_SEARCH_CANDIDATES,
-            maxScanItems: options.maxScanItems ?? constants_1.MAX_TOTAL_ITEMS_IN_MEMORY,
-        },
-        ddbClient: resolved.ddbClient,
-        ownsClient: resolved.ownsClient,
-    };
-}

package/dist/store/internal/text-path.d.ts

@@ -1,17 +0,0 @@
-import type { JsonValue } from './filter';
-/**
- * Split a JSON path into tokens the way LangGraph's `InMemoryStore` does: dots
- * separate plain segments, while a `[…]` index and a `{…}` field group each
- * become a token of their own (`tags[0]` → `['tags', '[0]']`).
- */
-export declare function tokenizePath(path: string): string[];
-/**
- * Extract the indexable text of `value` at `path`, byte-for-byte as LangGraph's
- * `InMemoryStore` does (`store/utils`), so an embedding computed here matches
- * one computed by the reference store for the same document. Supports plain
- * paths, `[n]`/`[-n]`/`[*]` indexing, a bare `*` wildcard, `{a,b.c}` field
- * groups and `$` for the whole document. The package root's `getTextAtPath` is
- * a string-only variant that returns nothing for numbers, booleans, objects
- * and arrays and throws on a `null` intermediate; it must not be used here.
- */
-export declare function getTextAtPath(value: JsonValue, path: string): string[];

package/dist/store/internal/validation.d.ts

@@ -1,18 +0,0 @@
-/** Validate search/listNamespaces paging is non-negative integers. */
-export declare function validatePaging(offset: number, limit: number): void;
-/** Validate the namespace is non-empty and each element is a valid, ≤256-byte identifier. */
-export declare function validateNamespace(namespace: string[]): void;
-/** Validate an item key is a non-blank, separator- and control-char-free, ≤256-byte string. */
-export declare function validateKey(key: string): void;
-/**
- * Validate a namespace/key pair as the item address it becomes: each segment
- * on its own, then the sort key they compose, which DynamoDB caps at 1024
- * bytes regardless of how short the individual segments are.
- */
-export declare function validateStoreKey(namespace: string[], key: string): void;
-/**
- * Validate an optional namespace depth cap. Left unchecked, a negative value
- * silently inverted truncation via `Array.prototype.slice(0, -n)`, which drops
- * the *last* n elements rather than erroring.
- */
-export declare function validateMaxDepth(maxDepth?: number): void;

package/dist/store/internal/validation.js

@@ -1,51 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validatePaging = validatePaging;
-exports.validateNamespace = validateNamespace;
-exports.validateKey = validateKey;
-exports.validateStoreKey = validateStoreKey;
-exports.validateMaxDepth = validateMaxDepth;
-const constants_1 = require("../../shared/constants");
-const errors_1 = require("../../shared/errors/errors");
-const primitives_1 = require("../../shared/validation/primitives");
-const keys_1 = require("./keys");
-/** Validate search/listNamespaces paging is non-negative integers. */
-function validatePaging(offset, limit) {
-    (0, primitives_1.validateInteger)(offset, 'offset', { min: 0 });
-    (0, primitives_1.validateInteger)(limit, 'limit', { min: 0 });
-}
-/** Validate the namespace is non-empty and each element is a valid, ≤256-byte identifier. */
-function validateNamespace(namespace) {
-    (0, primitives_1.validateNonEmptyArray)(namespace, 'namespace');
-    for (const element of namespace) {
-        (0, primitives_1.validateIdentifier)(element, keys_1.NAMESPACE_SEPARATOR, 'namespace element', constants_1.MAX_KEY_SEGMENT_BYTES);
-    }
-}
-/** Validate an item key is a non-blank, separator- and control-char-free, ≤256-byte string. */
-function validateKey(key) {
-    (0, primitives_1.validateIdentifier)(key, keys_1.NAMESPACE_SEPARATOR, 'key', constants_1.MAX_KEY_SEGMENT_BYTES);
-}
-/**
- * Validate a namespace/key pair as the item address it becomes: each segment
- * on its own, then the sort key they compose, which DynamoDB caps at 1024
- * bytes regardless of how short the individual segments are.
- */
-function validateStoreKey(namespace, key) {
-    validateNamespace(namespace);
-    validateKey(key);
-    const bytes = Buffer.byteLength((0, keys_1.sortKey)(namespace, key), 'utf8');
-    if (bytes > constants_1.MAX_SORT_KEY_BYTES) {
-        throw new errors_1.ValidationError(`namespace and key compose a ${bytes}-byte sort key; DynamoDB caps sort keys at ` +
-            `${constants_1.MAX_SORT_KEY_BYTES} bytes`, 'sortKey');
-    }
-}
-/**
- * Validate an optional namespace depth cap. Left unchecked, a negative value
- * silently inverted truncation via `Array.prototype.slice(0, -n)`, which drops
- * the *last* n elements rather than erroring.
- */
-function validateMaxDepth(maxDepth) {
-    if (maxDepth === undefined)
-        return;
-    (0, primitives_1.validateInteger)(maxDepth, 'maxDepth', { min: 1 });
-}

package/dist/store/internal/write-verify.d.ts

@@ -1,42 +0,0 @@
-import type { StoreContext } from './setup';
-/** True when `error` is a {@link RetryExhaustedError} — by name, not `instanceof` (banned repo-wide). */
-export declare function isRetryExhausted(error: Error): boolean;
-/**
- * True when the row is confirmed absent — used to resolve an ambiguous
- * retry-exhausted *delete*, where the delete may well have landed server-side
- * and only its acknowledgement was lost. Only the partition key is projected:
- * existence is the whole question. A failure reading this is not treated as
- * confirmation, which is fail-safe here: the caller only rethrows, and nothing
- * is deleted on the strength of a `false`.
- */
-export declare function rowIsAbsent(context: StoreContext, key: {
-    PK: string;
-    SK: string;
-}): Promise<boolean>;
-/** What a post-failure verification read could establish about a write. */
-export type WriteVerdict = 'landed' | 'not-landed' | 'unverified';
-/**
- * Read `record`'s row back to establish what an ambiguous write actually did,
- * comparing the row's revision with the one this write carried. Every put
- * stamps a fresh per-call `rev`, so the comparison works for inline and
- * offloaded records alike.
- *
- * - `'landed'`: the row holds this write's `rev`, so it committed server-side
- *   and only its acknowledgement was lost.
- * - `'not-landed'`: the row was read and holds something else, or nothing —
- *   or the record carries no `rev` to compare — so this call's own upload, if
- *   any, is dead and safe to delete.
- * - `'unverified'`: the read itself failed, so nothing is established.
- *
- * The third answer used to be folded into the second as a plain `false`, which
- * made a partition that blocked both the put and this read delete the object a
- * possibly-live row points at — permanently breaking every later read of that
- * item. Only a *confirmed* non-commit may delete the new upload: leaking one
- * object (reclaimed by `ensureS3LifecycleRule`) is recoverable, stranding a
- * live row is not.
- */
-export declare function verifyWriteLanded(context: StoreContext, record: {
-    PK: string;
-    SK: string;
-    rev?: string;
-}): Promise<WriteVerdict>;