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

package/dist/shared/dynamodb/retry-classifier.d.ts

@@ -1,17 +0,0 @@
-/**
- * Default retryable transient signals. TransactionCanceledException is
- * intentionally absent (its reasons include permanent failures);
- * TransactionConflictException (transient row contention) IS retryable.
- */
-export declare const DEFAULT_RETRYABLE_ERRORS: readonly string[];
-/**
- * True when `error` (or any cause in its chain) is transient: a transaction
- * cancellation whose every reason is transient (that verdict takes precedence,
- * because a permanent reason arrives with the same statuses as a transient
- * one), an HTTP status in {@link TRANSIENT_HTTP_STATUSES}, the SDK's
- * `$retryable` trait, or an exact match of a `name`/`code`/`errno`/`syscall`
- * token against `retryableErrors`. Exact, not substring: the fields are
- * whole tokens, and a substring rule would let an unrelated name that merely
- * contains one ride along.
- */
-export declare function isRetryableError(error: Error, retryableErrors: readonly string[]): boolean;

package/dist/shared/dynamodb/retry-classifier.js

@@ -1,118 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_RETRYABLE_ERRORS = void 0;
-exports.isRetryableError = isRetryableError;
-const cancellation_1 = require("./cancellation");
-const MAX_CAUSE_DEPTH = 32;
-/**
- * Default retryable transient signals. TransactionCanceledException is
- * intentionally absent (its reasons include permanent failures);
- * TransactionConflictException (transient row contention) IS retryable.
- */
-exports.DEFAULT_RETRYABLE_ERRORS = [
-    'ProvisionedThroughputExceededException',
-    'ThrottlingException',
-    'RequestLimitExceeded',
-    'InternalServerError',
-    'ServiceUnavailable',
-    'TransactionConflictException',
-    'TransactionInProgressException',
-    'RequestTimeout',
-    'RequestTimeoutException',
-    'ECONNRESET',
-    'ECONNREFUSED',
-    'ETIMEDOUT',
-    'EPIPE',
-    'EAI_AGAIN',
-    'NetworkingError',
-    'TimeoutError',
-    'EHOSTUNREACH',
-    'ENETUNREACH',
-    'ENOTFOUND',
-];
-/**
- * HTTP statuses the AWS SDK retries regardless of the error name: throttling
- * (429) and the transient server statuses. They matter most for an error the
- * SDK could not map to a modeled exception (an intermediary's HTML 503, a
- * truncated body), which arrives as `name: 'Unknown'` with only its status.
- */
-const TRANSIENT_HTTP_STATUSES = [429, 500, 502, 503, 504];
-/**
- * Cancellation reason codes (from a `TransactionCanceledException`'s
- * `CancellationReasons`) that are transient and safe to retry. `None` marks an
- * item that was not the cause and is ignored.
- */
-const TRANSIENT_CANCELLATION_REASONS = [
-    'None',
-    'TransactionConflict',
-    'ThrottlingError',
-    'ProvisionedThroughputExceeded',
-];
-/**
- * When `error` is a transaction cancellation carrying reasons, return whether
- * every reason is transient; otherwise undefined so normal signal matching
- * applies. A bare cancellation with no reasons is treated as non-retryable.
- */
-function transactionCancellationRetryable(error) {
-    const reasons = (0, cancellation_1.getCancellationReasons)(error);
-    if (!reasons)
-        return undefined;
-    /**
-     * `length > 0` is load-bearing: `.every()` is vacuously true on an empty
-     * array, which would make a reason-less cancellation retryable — the exact
-     * opposite of what this function documents. AWS populates one reason per
-     * `TransactItems` entry, so an empty array should not occur; if it ever
-     * does, the conservative answer is not to retry.
-     */
-    return (reasons.length > 0 &&
-        reasons.every((reason) => reason.Code === undefined || TRANSIENT_CANCELLATION_REASONS.includes(reason.Code)));
-}
-/** Add one node's signal tokens, HTTP status and retryable trait to `evidence`. */
-function recordNode(fields, evidence) {
-    for (const value of [fields.name, fields.code, fields.errno, fields.syscall]) {
-        if (typeof value === 'string')
-            evidence.signals.push(value);
-    }
-    if (typeof fields.$metadata?.httpStatusCode === 'number') {
-        evidence.statuses.push(fields.$metadata.httpStatusCode);
-    }
-    if (fields.$retryable !== undefined && fields.$retryable !== null)
-        evidence.retryableByTrait = true;
-}
-function collectEvidence(error) {
-    const seen = new WeakSet();
-    const evidence = { signals: [], statuses: [], retryableByTrait: false };
-    const walk = (node, depth) => {
-        if (depth > MAX_CAUSE_DEPTH || node === null || typeof node !== 'object' || seen.has(node)) {
-            return;
-        }
-        seen.add(node);
-        const fields = node;
-        recordNode(fields, evidence);
-        if (fields.cause)
-            walk(fields.cause, depth + 1);
-    };
-    walk(error, 0);
-    return evidence;
-}
-/**
- * True when `error` (or any cause in its chain) is transient: a transaction
- * cancellation whose every reason is transient (that verdict takes precedence,
- * because a permanent reason arrives with the same statuses as a transient
- * one), an HTTP status in {@link TRANSIENT_HTTP_STATUSES}, the SDK's
- * `$retryable` trait, or an exact match of a `name`/`code`/`errno`/`syscall`
- * token against `retryableErrors`. Exact, not substring: the fields are
- * whole tokens, and a substring rule would let an unrelated name that merely
- * contains one ride along.
- */
-function isRetryableError(error, retryableErrors) {
-    const cancellation = transactionCancellationRetryable(error);
-    if (cancellation !== undefined)
-        return cancellation;
-    const evidence = collectEvidence(error);
-    if (evidence.retryableByTrait)
-        return true;
-    if (evidence.statuses.some((status) => TRANSIENT_HTTP_STATUSES.includes(status)))
-        return true;
-    return evidence.signals.some((signal) => retryableErrors.includes(signal));
-}

package/dist/shared/dynamodb/retry-policy.d.ts

@@ -1,26 +0,0 @@
-import type { Logger } from '../logging/logger';
-import type { RetryOptions } from './retry';
-/**
- * Caller-facing retry tunables for every DynamoDB call an adapter makes. The
- * schedule is full-jitter exponential backoff: `baseDelayMs` doubling per
- * attempt, capped at `maxDelayMs`, for `maxAttempts` attempts. The
- * message-append path never goes below its own contention floor.
- */
-export interface RetryPolicy {
-    /** Attempts per call before `RetryExhaustedError` (default 5). */
-    maxAttempts?: number;
-    /** First backoff delay in milliseconds (default 100). */
-    baseDelayMs?: number;
-    /** Cap on a single backoff delay in milliseconds (default 5000). */
-    maxDelayMs?: number;
-}
-/**
- * Resolve an adapter's retry policy once, attaching the context logger so
- * every retry is visible at `debug` (attempt, the delay about to be slept, the
- * error name) instead of only surfacing once the budget is exhausted.
- */
-export declare function resolveRetryPolicy(policy: RetryPolicy | undefined, logger: Logger): RetryOptions;
-/** The context's retry options plus a per-call cancellation signal, when one is given. */
-export declare function retryFor(context: {
-    retry?: RetryOptions;
-}, signal?: AbortSignal): RetryOptions | undefined;

package/dist/shared/dynamodb/retry-policy.js

@@ -1,22 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveRetryPolicy = resolveRetryPolicy;
-exports.retryFor = retryFor;
-const constants_1 = require("../constants");
-/**
- * Resolve an adapter's retry policy once, attaching the context logger so
- * every retry is visible at `debug` (attempt, the delay about to be slept, the
- * error name) instead of only surfacing once the budget is exhausted.
- */
-function resolveRetryPolicy(policy, logger) {
-    return {
-        maxAttempts: policy?.maxAttempts ?? constants_1.DEFAULT_RETRY_MAX_ATTEMPTS,
-        baseDelayMs: policy?.baseDelayMs ?? constants_1.INITIAL_BACKOFF_DELAY_MS,
-        maxDelayMs: policy?.maxDelayMs ?? constants_1.MAX_BACKOFF_DELAY_MS,
-        onRetry: ({ attempt, delayMs, error }) => logger.debug('retrying after a transient error', { attempt, delayMs, error: error.name }),
-    };
-}
-/** The context's retry options plus a per-call cancellation signal, when one is given. */
-function retryFor(context, signal) {
-    return signal === undefined ? context.retry : { ...context.retry, signal };
-}

package/dist/shared/dynamodb/scan.d.ts

@@ -1,14 +0,0 @@
-import type { DynamoDBDocument, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
-import { type PaginateCoreOptions } from './paginate-core';
-import type { DocItem } from './types';
-/** Options for {@link paginateScan}. */
-export interface ScanOptions extends PaginateCoreOptions {
-    client: DynamoDBDocument;
-    params: ScanCommandInput;
-}
-/**
- * Drive a DynamoDB Scan across all pages, yielding each item. Shares the
- * pagination core with {@link paginateQuery}: abort handling, retry per page,
- * and runaway guards.
- */
-export declare function paginateScan(options: ScanOptions): AsyncGenerator<DocItem>;

package/dist/shared/dynamodb/scan.js

@@ -1,19 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.paginateScan = paginateScan;
-const paginate_core_1 = require("./paginate-core");
-const retry_1 = require("./retry");
-/**
- * Drive a DynamoDB Scan across all pages, yielding each item. Shares the
- * pagination core with {@link paginateQuery}: abort handling, retry per page,
- * and runaway guards.
- */
-function paginateScan(options) {
-    return (0, paginate_core_1.paginatePages)(async (startKey) => {
-        const page = await (0, retry_1.withDynamoDBRetry)(() => options.client.scan({ ...options.params, ExclusiveStartKey: startKey }), { ...options.retry, signal: options.signal });
-        return {
-            items: page.Items ?? [],
-            lastKey: page.LastEvaluatedKey,
-        };
-    }, options);
-}

package/dist/shared/dynamodb/types.d.ts

@@ -1,23 +0,0 @@
-import type { NativeAttributeValue } from '@aws-sdk/lib-dynamodb';
-/**
- * A DynamoDB item as returned/accepted by the DocumentClient. Reads that we
- * wrote ourselves are narrowed with a single structural `as` at the mapper
- * boundary (never `as any`/`as unknown`); untrusted shared-table scans go
- * through `narrowStoreRecord`.
- */
-export type DocItem = Record<string, NativeAttributeValue>;
-/** A BatchWriteItem PutRequest. */
-interface PutWriteRequest {
-    PutRequest: {
-        Item: DocItem;
-    };
-}
-/** A BatchWriteItem DeleteRequest. */
-interface DeleteWriteRequest {
-    DeleteRequest: {
-        Key: DocItem;
-    };
-}
-/** A single BatchWriteItem write request. */
-export type WriteRequest = PutWriteRequest | DeleteWriteRequest;
-export {};

package/dist/shared/dynamodb/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });

package/dist/shared/errors/upstream-error.d.ts

@@ -1,16 +0,0 @@
-import { DynamoDBLangGraphError } from './base-error';
-/**
- * A failure that originated below this library — the AWS SDK, the transport,
- * a third-party `VectorBackend` or `Embeddings` — and surfaced through one of
- * its public methods. Wrapping it keeps the promise that every rejection a
- * caller sees is a {@link DynamoDBLangGraphError} with a branchable `code`,
- * while losing nothing a support ticket needs: the SDK's own error name, the
- * request id and HTTP status when present, and the original as `cause`.
- */
-export declare class UpstreamError extends DynamoDBLangGraphError {
-    readonly upstreamName: string;
-    /** Declared, not emitted: absent metadata leaves no `undefined`-valued own property behind. */
-    readonly requestId?: string;
-    readonly httpStatusCode?: number;
-    constructor(cause: Error, operation: string);
-}

package/dist/shared/errors/upstream-error.js

@@ -1,27 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.UpstreamError = void 0;
-const base_error_1 = require("./base-error");
-const error_code_1 = require("./error-code");
-/**
- * A failure that originated below this library — the AWS SDK, the transport,
- * a third-party `VectorBackend` or `Embeddings` — and surfaced through one of
- * its public methods. Wrapping it keeps the promise that every rejection a
- * caller sees is a {@link DynamoDBLangGraphError} with a branchable `code`,
- * while losing nothing a support ticket needs: the SDK's own error name, the
- * request id and HTTP status when present, and the original as `cause`.
- */
-class UpstreamError extends base_error_1.DynamoDBLangGraphError {
-    upstreamName;
-    constructor(cause, operation) {
-        super(`${operation}: ${cause.name}: ${cause.message}`, error_code_1.ErrorCode.UPSTREAM, { operation }, cause);
-        this.name = 'UpstreamError';
-        this.upstreamName = cause.name;
-        const metadata = cause.$metadata;
-        if (metadata?.requestId !== undefined)
-            this.requestId = metadata.requestId;
-        if (metadata?.httpStatusCode !== undefined)
-            this.httpStatusCode = metadata.httpStatusCode;
-    }
-}
-exports.UpstreamError = UpstreamError;

package/dist/shared/errors/wrap-error.d.ts

@@ -1,7 +0,0 @@
-/**
- * Normalize a caught value (TypeScript types catch clauses as the implicit
- * unknown) into an `Error`. Error-shaped values pass through; anything else is
- * stringified into a fresh `Error`. This is the boundary where caught values
- * are narrowed — callers do `toError(error as Error)`.
- */
-export declare function toError(value: Error): Error;

package/dist/shared/errors/wrap-error.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.toError = toError;
-/**
- * Normalize a caught value (TypeScript types catch clauses as the implicit
- * unknown) into an `Error`. Error-shaped values pass through; anything else is
- * stringified into a fresh `Error`. This is the boundary where caught values
- * are narrowed — callers do `toError(error as Error)`.
- */
-function toError(value) {
-    if (value !== null && typeof value === 'object' && typeof value.message === 'string') {
-        return value;
-    }
-    return new Error(typeof value === 'string' ? value : JSON.stringify(value));
-}

package/dist/shared/logging/redaction-walk.d.ts

@@ -1,23 +0,0 @@
-/** A value that {@link redactSecrets} can recurse through. */
-export type Redactable = string | number | boolean | null | undefined | Redactable[] | {
-    [key: string]: Redactable;
-};
-/** Any `Redactable` that is a non-null object — what the walk dispatches on. */
-export type RedactableObject = Redactable[] | {
-    [key: string]: Redactable;
-};
-/** One step of the recursive walk, threaded into the entry helpers. */
-type Walk = (value: Redactable) => Redactable;
-/** Collaborators threaded through the recursive walk. */
-export interface WalkDeps {
-    keyPatterns: readonly string[];
-    valuePatterns: readonly RegExp[];
-    walk: Walk;
-}
-/**
- * Dispatch one non-null object by its shape: arrays and plain objects recurse,
- * binary views collapse to a label, `Date`/`RegExp` pass through by reference,
- * `Set`/`Map` render as their contents, and an Error takes the path above.
- */
-export declare function walkObject(current: RedactableObject, deps: WalkDeps): Redactable;
-export {};

package/dist/shared/logging/redaction-walk.js

@@ -1,112 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.walkObject = walkObject;
-const secret_patterns_1 = require("./secret-patterns");
-/** True when `value` is a Set, tested by tag so a cross-realm Set still matches. */
-function isSetValue(value) {
-    return Object.prototype.toString.call(value) === '[object Set]';
-}
-/** True when `value` is a Map, tested by tag so a cross-realm Map still matches. */
-function isMapValue(value) {
-    return Object.prototype.toString.call(value) === '[object Map]';
-}
-/**
- * True when `value` is an Error (or subclass) or a `DOMException` — which has
- * its own tag yet carries the same `name`/`message`/`stack` — tested by tag,
- * not `instanceof`, so a cross-realm error still matches.
- */
-function isErrorValue(value) {
-    const tag = Object.prototype.toString.call(value);
-    return tag === '[object Error]' || tag === '[object DOMException]';
-}
-/**
- * True for a value whose identity matters more than its own properties.
- * `Date` and `RegExp` have none, so recursing either would yield a bare `{}`.
- */
-function isOpaqueValue(value) {
-    const tag = Object.prototype.toString.call(value);
-    return tag === '[object Date]' || tag === '[object RegExp]';
-}
-/**
- * Rebuild entries into a plain object, redacting values at secret-looking
- * keys. Properties are defined, not assigned: `out['__proto__'] = …` would
- * replace the result's prototype (and drop the entry) instead of recording the
- * key as data.
- */
-function redactEntries(entries, keyPatterns, walk) {
-    const out = {};
-    for (const [key, value] of entries) {
-        Object.defineProperty(out, key, {
-            value: (0, secret_patterns_1.isSecretKey)(key, keyPatterns) ? secret_patterns_1.REDACTED : walk(value),
-            enumerable: true,
-            writable: true,
-            configurable: true,
-        });
-    }
-    return out;
-}
-/**
- * A Map's entries as an object. Keys are stringified so a non-string key is
- * still reported rather than dropped, and each is checked against the
- * secret-key patterns exactly as a plain object's own keys are.
- */
-function redactMap(value, deps) {
-    const entries = [...value].map(([key, entry]) => [String(key), entry]);
-    return redactEntries(entries, deps.keyPatterns, deps.walk);
-}
-/**
- * Rebuild an Error as a plain object carrying its redacted text alongside its
- * redacted own properties. The one exception is an Error with no own
- * enumerable data, no `cause`, no aggregated `errors`, and no secret in its
- * text: it is returned by reference so its identity and stack trace survive,
- * which is what keeps a caught error useful in a log.
- *
- * `cause` and `AggregateError.errors` are copied explicitly because both are
- * defined *non-enumerable* per spec, so `Object.entries` never sees them.
- * Without this the whole chain vanished on every rebuild — and the rebuild
- * always fires for this library's own error types, since each attaches an
- * enumerable `code`/`context`. A redacted `RetryExhaustedError` would then no
- * longer say whether the underlying failure was a throttle, a validation error
- * or a network fault, which is the entire reason it carries a cause. A bare
- * Error *with* a cause is rebuilt for the same reason: passing it by reference
- * would hand the caller whatever secret the cause carries. Recursing through
- * `walk` redacts the chain too, and the cycle guard handles a cause that
- * points back at its own wrapper.
- */
-function redactError(current, entries, deps) {
-    const text = (0, secret_patterns_1.redactErrorText)(current, deps.valuePatterns);
-    const aggregated = current.errors;
-    const bare = entries.length === 0 && current.cause === undefined && aggregated === undefined;
-    if (bare && !text.changed)
-        return current;
-    const out = redactEntries(entries, deps.keyPatterns, deps.walk);
-    out.name = text.name;
-    out.message = text.message;
-    out.stack = text.stack;
-    if (current.cause !== undefined)
-        out.cause = deps.walk(current.cause);
-    if (Array.isArray(aggregated))
-        out.errors = deps.walk(aggregated);
-    return out;
-}
-/**
- * Dispatch one non-null object by its shape: arrays and plain objects recurse,
- * binary views collapse to a label, `Date`/`RegExp` pass through by reference,
- * `Set`/`Map` render as their contents, and an Error takes the path above.
- */
-function walkObject(current, deps) {
-    if (Array.isArray(current))
-        return current.map(deps.walk);
-    if (ArrayBuffer.isView(current))
-        return (0, secret_patterns_1.binaryLabel)(current);
-    if (isOpaqueValue(current))
-        return current;
-    if (isSetValue(current))
-        return [...current].map(deps.walk);
-    if (isMapValue(current))
-        return redactMap(current, deps);
-    const entries = Object.entries(current);
-    if (isErrorValue(current))
-        return redactError(current, entries, deps);
-    return redactEntries(entries, deps.keyPatterns, deps.walk);
-}

package/dist/store/actions/get.d.ts

@@ -1,13 +0,0 @@
-import type { Item } from '@langchain/langgraph-checkpoint';
-import type { StoreContext } from '../internal/setup';
-/**
- * Retrieve a single item by namespace and key (strongly consistent), or null.
- *
- * An offloaded item can lose a race with a concurrent overwrite: between the
- * row read and the S3 download the writer commits a new descriptor and deletes
- * the object this read was about to fetch. That surfaces as `NoSuchKey`, and
- * one strongly-consistent re-read settles it — the row now points at the new
- * object (return that), is gone (null), or still points at the same missing
- * object (a genuine loss, rethrown). Any other download failure propagates.
- */
-export declare function getItem(context: StoreContext, namespace: string[], key: string, signal?: AbortSignal): Promise<Item | null>;

package/dist/store/actions/get.js

@@ -1,73 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getItem = getItem;
-const clock_1 = require("../../shared/clock");
-const codec_1 = require("../../shared/codec/codec");
-const payload_loss_1 = require("../../shared/codec/payload-loss");
-const expiry_1 = require("../../shared/dynamodb/expiry");
-const retry_1 = require("../../shared/dynamodb/retry");
-const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
-const item_mapper_1 = require("../internal/item-mapper");
-const keys_1 = require("../internal/keys");
-const validation_1 = require("../internal/validation");
-/**
- * Read the row strongly consistently and narrow it rather than cast. A
- * foreign row sharing this key has no `namespace`, and one carrying a `value`
- * PayloadDescriptor in the same shape a store item uses (a checkpointer WRITE
- * row) would otherwise decode cleanly and be handed back as the caller's own
- * value.
- */
-async function readRow(context, namespace, key, signal) {
-    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-        TableName: context.tableName,
-        Key: { PK: (0, keys_1.partitionKey)(namespace), SK: (0, keys_1.sortKey)(namespace, key) },
-        ConsistentRead: true,
-    }), (0, retry_policy_1.retryFor)(context, signal));
-    if (!result.Item)
-        return undefined;
-    const record = (0, item_mapper_1.narrowStoreRecord)(result.Item);
-    if (!record) {
-        context.logger.warn('store.get: ignored a row that is not a store item', {
-            partitionKey: (0, keys_1.partitionKey)(namespace),
-            sortKey: (0, keys_1.sortKey)(namespace, key),
-        });
-        return undefined;
-    }
-    /** A row past its ttl is absent to every reader, however long DynamoDB's sweep lags. */
-    return (0, expiry_1.isExpiredRow)(record, (0, clock_1.nowSeconds)()) ? undefined : record;
-}
-/** True when both records point at the same offloaded object. */
-function sameObject(a, b) {
-    return (a.value.location === codec_1.PayloadLocation.S3 &&
-        b.value.location === codec_1.PayloadLocation.S3 &&
-        a.value.s3Key === b.value.s3Key);
-}
-/**
- * Retrieve a single item by namespace and key (strongly consistent), or null.
- *
- * An offloaded item can lose a race with a concurrent overwrite: between the
- * row read and the S3 download the writer commits a new descriptor and deletes
- * the object this read was about to fetch. That surfaces as `NoSuchKey`, and
- * one strongly-consistent re-read settles it — the row now points at the new
- * object (return that), is gone (null), or still points at the same missing
- * object (a genuine loss, rethrown). Any other download failure propagates.
- */
-async function getItem(context, namespace, key, signal) {
-    (0, validation_1.validateStoreKey)(namespace, key);
-    const record = await readRow(context, namespace, key, signal);
-    if (!record)
-        return null;
-    try {
-        return await (0, item_mapper_1.readStoreItem)(context, record);
-    }
-    catch (error) {
-        if (!(0, payload_loss_1.isMissingObjectError)(error))
-            throw error;
-        const fresh = await readRow(context, namespace, key, signal);
-        if (!fresh)
-            return null;
-        if (sameObject(record, fresh))
-            throw error;
-        return (0, item_mapper_1.readStoreItem)(context, fresh);
-    }
-}

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

@@ -1,4 +0,0 @@
-import type { IndexConfig, SearchItem, SearchOperation } from '@langchain/langgraph-checkpoint';
-import type { VectorBackend } from '../vector-backend';
-import type { StoreContext } from './setup';
-export declare function searchViaBackend(context: StoreContext, backend: VectorBackend, index: IndexConfig, op: SearchOperation, offset: number, limit: number, signal?: AbortSignal): Promise<SearchItem[]>;

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

@@ -1,74 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.searchViaBackend = searchViaBackend;
-const errors_1 = require("../../shared/errors/errors");
-const get_1 = require("../actions/get");
-const keys_1 = require("./keys");
-const score_direction_1 = require("./score-direction");
-const search_filter_1 = require("./search-filter");
-const semantic_search_1 = require("./semantic-search");
-/**
- * Warn when a backend's own ordering disagrees with its scores. A backend
- * returning a raw distance still hands back nearest-first, so the order looks
- * right while every score means the opposite of what {@link VectorMatch.score}
- * promises — ascending scores are that exact signature. Results are never
- * reordered on this basis: a correctly-scored backend's order is authoritative.
- */
-function warnOnNonDescendingScores(context, matches, namespacePrefix) {
-    const descending = matches.every((match, position) => position === 0 || matches[position - 1].score >= match.score);
-    if (descending)
-        return;
-    context.logger.warn('search: vectorBackend returned ascending scores; VectorMatch.score must be a relevance ' +
-        '(higher is better), not a distance — results are forwarded in the order the backend gave', { namespacePrefix });
-}
-/**
- * Read the canonical item a backend match points at, or `undefined` when the
- * match is unusable. `getItem` validates, so a backend returning a namespace
- * element containing the reserved separator would otherwise turn the whole
- * search into a ValidationError instead of dropping the one bad match.
- */
-async function fetchMatch(context, match, signal) {
-    try {
-        return await (0, get_1.getItem)(context, match.namespace, match.key, signal);
-    }
-    catch (error) {
-        context.logger.warn('search: skipped an unusable vectorBackend match', {
-            namespace: match.namespace,
-            key: match.key,
-            reason: error.name,
-        });
-        return null;
-    }
-}
-async function searchViaBackend(context, backend, index, op, offset, limit, signal) {
-    const queryVector = await index.embeddings.embedQuery(op.query);
-    (0, semantic_search_1.assertVectorDims)(index, queryVector, 'query');
-    const need = offset + limit;
-    if (need > context.maxSearchCandidates) {
-        throw new errors_1.ValidationError(`Requested page (offset ${offset} + limit ${limit} = ${need}) exceeds maxSearchCandidates ` +
-            `(${context.maxSearchCandidates}); narrow the page or raise maxSearchCandidates`, 'maxSearchCandidates');
-    }
-    let topK = Math.min(need, context.maxSearchCandidates);
-    let results;
-    for (;;) {
-        const matches = (0, score_direction_1.toRelevanceScores)(await backend.query(op.namespacePrefix, queryVector, topK), context.vectorScoreDirection);
-        warnOnNonDescendingScores(context, matches, op.namespacePrefix);
-        results = [];
-        for (const match of matches) {
-            if (!(0, keys_1.namespaceMatchesPrefix)(match.namespace, op.namespacePrefix))
-                continue;
-            const item = await fetchMatch(context, match, signal);
-            if (item && (0, search_filter_1.passesFilter)(item, op))
-                results.push({ ...item, score: match.score });
-        }
-        if (results.length >= need || matches.length < topK)
-            break;
-        if (topK >= context.maxSearchCandidates) {
-            /** The backend still holds matches, but the filter left the page short at the cap: the same answer the in-DB ranker gives, not a silently short page. */
-            throw new errors_1.ValidationError(`Semantic search collected ${results.length} of ${need} matches within maxSearchCandidates ` +
-                `(${context.maxSearchCandidates}); narrow the filter or raise maxSearchCandidates`, 'maxSearchCandidates');
-        }
-        topK = Math.min(topK * 2, context.maxSearchCandidates);
-    }
-    return results;
-}

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

@@ -1,23 +0,0 @@
-import type { SearchOperation } from '@langchain/langgraph-checkpoint';
-import type { RankCandidate } from './ranker';
-import type { StoreContext } from './setup';
-/**
- * How far a collection must go. A plain page is complete once `need`
- * (`offset + limit`) matching items are in hand, so rows past it are never
- * read or decoded; a semantic ranking needs every candidate but is refused as
- * soon as more than `cap` rows exist, before a single decode or embedding.
- */
-export type CollectBound = {
-    kind: 'page';
-    need: number;
-} | {
-    kind: 'semantic';
-    cap: number;
-};
-/**
- * Collect the live rows under the prefix and decode them within `bound`. A
- * page decodes rows in batches of {@link DEFAULT_READ_CONCURRENCY} and closes
- * the paginator as soon as the page is full, so a namespace far larger than the
- * page costs neither a full decode nor a truncation error.
- */
-export declare function collectCandidates(context: StoreContext, op: SearchOperation, bound: CollectBound, signal?: AbortSignal): Promise<RankCandidate[]>;