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

package/dist/store/internal/filter.js

@@ -1,137 +0,0 @@
-"use strict";
-/**
- * Hides the store's filter grammar.
- *
- * Which operators a search filter accepts, how each compares a stored field —
- * ordered comparisons only between like-typed values, an absent field matching
- * nothing — and whether an item passes a search's optional filter are decided
- * here, the same way whichever search path runs.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchesStoreFilter = matchesStoreFilter;
-exports.passesFilter = passesFilter;
-const node_util_1 = require("node:util");
-/**
- * Three-way order for a like-typed pair, or `undefined` when the pair is
- * *unordered*. `NaN` compares `false` against everything including itself, so a
- * bare `===`/`>` ternary silently reports it as "less than" — which let a
- * stored `NaN` satisfy `$lt`/`$lte` against any number, contradicting
- * {@link compareOrdered}'s own contract.
- */
-function orderOf(actual, expected) {
-    if (actual < expected)
-        return -1;
-    if (actual > expected)
-        return 1;
-    return actual === expected ? 0 : undefined;
-}
-/** Apply `test` to a resolved order; an unordered pair never matches. */
-function testOrder(order, test) {
-    return order !== undefined && test(order);
-}
-/**
- * Ordered comparison over like-typed values only: numbers compare numerically,
- * strings lexicographically, and a mismatched or unordered pair never matches.
- *
- * Deliberately stricter than both native comparison and what upstream does.
- * Native `>` coerces, so a stored `'10'` would satisfy `{ $gt: 5 }` — inclusion
- * decided by JS coercion rather than by the stored type. Upstream instead
- * reduces both sides with `Number()`, which makes two ISO-8601 date strings
- * `NaN` and every comparison between them false. Comparing like types
- * directly is well-defined in both cases.
- */
-function compareOrdered(actual, expected, test) {
-    if (typeof actual === 'number' && typeof expected === 'number') {
-        return testOrder(orderOf(actual, expected), test);
-    }
-    if (typeof actual === 'string' && typeof expected === 'string') {
-        return testOrder(orderOf(actual, expected), test);
-    }
-    return false;
-}
-const COMPARATORS = {
-    $eq: (actual, expected) => (0, node_util_1.isDeepStrictEqual)(actual, expected),
-    $ne: (actual, expected) => !(0, node_util_1.isDeepStrictEqual)(actual, expected),
-    $gt: (actual, expected) => compareOrdered(actual, expected, (order) => order > 0),
-    $gte: (actual, expected) => compareOrdered(actual, expected, (order) => order >= 0),
-    $lt: (actual, expected) => compareOrdered(actual, expected, (order) => order < 0),
-    $lte: (actual, expected) => compareOrdered(actual, expected, (order) => order <= 0),
-    $in: (actual, expected) => Array.isArray(expected)
-        ? expected.some((candidate) => (0, node_util_1.isDeepStrictEqual)(actual, candidate))
-        : false,
-    $nin: (actual, expected) => Array.isArray(expected)
-        ? !expected.some((candidate) => (0, node_util_1.isDeepStrictEqual)(actual, candidate))
-        : true,
-};
-/**
- * True when every key is one of the exact known operator names, which matches
- * the reference store's own detection (`@langchain/langgraph-checkpoint@1.1.5`
- * `dist/store/utils.js:61`): a stored value that merely has `$`-prefixed keys —
- * a JSON Schema document, say — is compared as a literal instead of misread as
- * a filter.
- *
- * An empty condition qualifies, and therefore imposes no constraint: `every`
- * over no operators is true, exactly as it is upstream, so `{ field: {} }`
- * matches every item — including one that does not hold the field at all, for
- * which there is likewise no operator to fail. Requiring at least one key
- * inverted that answer and made the same filter match nothing.
- *
- * Arrays are excluded where the reference does not. Upstream an empty array
- * reaches `Object.keys([]).every(...)` and is likewise vacuously true, so `[]`
- * as a condition matches everything there; treating a stored array as a literal
- * to compare is the answer a caller means, and the difference is recorded
- * rather than copied.
- */
-function isOperatorObject(condition) {
-    return (typeof condition === 'object' &&
-        condition !== null &&
-        !Array.isArray(condition) &&
-        Object.keys(condition).every((key) => Object.prototype.hasOwnProperty.call(COMPARATORS, key)));
-}
-function matchesCondition(actual, condition) {
-    if (!isOperatorObject(condition))
-        return (0, node_util_1.isDeepStrictEqual)(actual, condition);
-    return Object.entries(condition).every(([operator, expected]) => COMPARATORS[operator](actual, expected));
-}
-/** The value `item` holds at `field`, or undefined when it holds no such own property. */
-function ownField(item, field) {
-    if (item === null || typeof item !== 'object')
-        return undefined;
-    return Object.hasOwn(item, field) ? item[field] : undefined;
-}
-/**
- * Whether `value` satisfies every field condition in `filter`.
- *
- * Accepts: `value` — a stored item's decoded value. Declared as a record, but a
- * row holds whatever its writer stored, including `null` and a scalar; such a
- * value has no own properties and so satisfies no condition. `filter` — a plain
- * value per field is exact match, an operator object (`{ $gt: 4 }`) applies
- * comparisons, and `{}` constrains nothing.
- *
- * Returns: whether every condition holds.
- *
- * Throws: nothing. `search` walks every candidate row, so one row whose value
- * is not an object must not fail the search.
- *
- * Guarantees: own properties only — `value['toString']` would otherwise resolve
- * up the prototype chain and be compared as if it were stored data.
- */
-function matchesStoreFilter(value, filter) {
-    return Object.entries(filter).every(([field, condition]) => matchesCondition(ownField(value, field), condition));
-}
-/**
- * Whether `item` satisfies a search's optional metadata filter.
- *
- * Accepts: `filter` — a parsed search's filter; absent passes every item.
- * `item.value` — whatever the item's writer stored; a value that is not
- * an object satisfies no condition (see `matchesStoreFilter`).
- *
- * Returns: whether the item belongs in the result.
- *
- * Throws: nothing, so one unusual row cannot fail a search over many.
- */
-function passesFilter(item, filter) {
-    if (!filter)
-        return true;
-    return matchesStoreFilter(item.value, filter);
-}

package/dist/store/internal/get-item.d.ts

@@ -1,45 +0,0 @@
-/**
- * Hides what a single read counts as absent, and how it outlives an overwrite.
- *
- * A get reads its row strongly consistently and answers `null` alike for a
- * missing row, an expired one and a row this adapter does not own. When the
- * object an offloaded row names is deleted between the row read and the
- * download, one re-read settles whether the item was replaced, removed or
- * truly lost. A caller gets an item or `null` and never sees the race.
- */
-import type { Item } from '@langchain/langgraph-checkpoint';
-import type { StoreAddress } from './parse';
-import type { StoreContext } from './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). A row the overwrite left with no
- * descriptor at all is a replacement like any other: it is decoded, and refused
- * by its own coded error. Any other download failure propagates.
- *
- * Accepts: `address` — parsed; no check is repeated here. `signal` — aborts
- * the reads.
- *
- * Returns: the item, or `null` for one that does not exist, has expired, or
- * whose key holds a row this adapter does not own — which includes a row whose
- * `createdAt` or `updatedAt` is not the string this package writes there, since
- * an item is reported with both. The answers are one on purpose: a caller
- * cannot act on the difference, and reporting a foreign row would leak that a
- * shared table holds one.
- *
- * Throws: `VALIDATION` naming — for a row whose descriptor is not one —
- * `descriptor`; `FORMAT_UNSUPPORTED` for
- * a row, or a payload, written by a newer version, which is *not* reported as
- * absent — hiding an item that exists is worse than failing; `PAYLOAD_CORRUPT`
- * or the download's own error for a payload that cannot be read; `ABORTED`
- * when the signal fires.
- *
- * Guarantees: strongly consistent — an item just written is always seen, and
- * the ttl is honoured here rather than waited for.
- */
-export declare function getItem(context: StoreContext, address: StoreAddress, signal?: AbortSignal): Promise<Item | null>;

package/dist/store/internal/get-item.js

@@ -1,115 +0,0 @@
-"use strict";
-/**
- * Hides what a single read counts as absent, and how it outlives an overwrite.
- *
- * A get reads its row strongly consistently and answers `null` alike for a
- * missing row, an expired one and a row this adapter does not own. When the
- * object an offloaded row names is deleted between the row read and the
- * download, one re-read settles whether the item was replaced, removed or
- * truly lost. A caller gets an item or `null` and never sees the race.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getItem = getItem;
-const clock_1 = require("../../shared/clock");
-const codec_1 = require("../../shared/codec/codec");
-const retry_1 = require("../../shared/dynamodb/retry");
-const table_schema_1 = require("../../shared/dynamodb/table-schema");
-const rows_1 = require("./rows");
-/**
- * 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. The narrow is the whole-row one, so a row with no `createdAt` or
- * `updatedAt` is refused here rather than decoded into an item whose
- * timestamps are `Invalid Date`.
- */
-async function readRow(context, namespace, key, signal) {
-    const result = await (0, retry_1.withDynamoDBRetry)((request) => context.client.get({
-        TableName: context.tableName,
-        Key: (0, rows_1.itemRowKey)({ namespace, key }),
-        ConsistentRead: true,
-    }, request), (0, retry_1.retryFor)(context, signal));
-    if (!result.Item)
-        return undefined;
-    const record = (0, rows_1.parseWholeStoreRow)(result.Item);
-    if (!record) {
-        context.logger.warn('store.get: ignored a row that is not a store item', {
-            partitionKey: (0, rows_1.partitionKey)(namespace),
-            sortKey: (0, rows_1.sortKey)(namespace, key),
-        });
-        return undefined;
-    }
-    // A row past its ttl is absent to every reader, however long DynamoDB's sweep lags.
-    return (0, table_schema_1.isExpiredRow)(record, (0, clock_1.nowSeconds)()) ? undefined : record;
-}
-/**
- * True when both records point at the same offloaded object.
- *
- * Only `read` is known to hold a descriptor: it is the row whose download just
- * failed. `reread` is whatever the overwrite this recovery exists for left
- * behind, which can be a `null` where the descriptor belongs, so it is tested
- * for presence first. A row pointing at nothing is not pointing at the object
- * this read lost, so it is decoded like any other replacement and answered with
- * the coded error that names the descriptor — not with a property read that
- * would replace the download's own failure with a bare `TypeError`.
- */
-function sameObject(read, reread) {
-    const fresh = reread.value;
-    if (!fresh)
-        return false;
-    return (read.value.location === codec_1.PayloadLocation.S3 &&
-        fresh.location === codec_1.PayloadLocation.S3 &&
-        read.value.s3Key === fresh.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). A row the overwrite left with no
- * descriptor at all is a replacement like any other: it is decoded, and refused
- * by its own coded error. Any other download failure propagates.
- *
- * Accepts: `address` — parsed; no check is repeated here. `signal` — aborts
- * the reads.
- *
- * Returns: the item, or `null` for one that does not exist, has expired, or
- * whose key holds a row this adapter does not own — which includes a row whose
- * `createdAt` or `updatedAt` is not the string this package writes there, since
- * an item is reported with both. The answers are one on purpose: a caller
- * cannot act on the difference, and reporting a foreign row would leak that a
- * shared table holds one.
- *
- * Throws: `VALIDATION` naming — for a row whose descriptor is not one —
- * `descriptor`; `FORMAT_UNSUPPORTED` for
- * a row, or a payload, written by a newer version, which is *not* reported as
- * absent — hiding an item that exists is worse than failing; `PAYLOAD_CORRUPT`
- * or the download's own error for a payload that cannot be read; `ABORTED`
- * when the signal fires.
- *
- * Guarantees: strongly consistent — an item just written is always seen, and
- * the ttl is honoured here rather than waited for.
- */
-async function getItem(context, address, signal) {
-    const { namespace, key } = address;
-    const record = await readRow(context, namespace, key, signal);
-    if (!record)
-        return null;
-    try {
-        return await (0, rows_1.readStoreItem)(context, record, signal);
-    }
-    catch (error) {
-        if (!(0, codec_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, rows_1.readStoreItem)(context, fresh, signal);
-    }
-}