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

package/dist/index.d.ts

@@ -1,22 +1,53 @@
+/**
+ * AWS DynamoDB implementation of LangGraph's checkpoint saver, memory store
+ * and chat message history, in TypeScript.
+ *
+ * Hides where anything lives.
+ *
+ * This module re-exports and declares nothing of its own, so which module
+ * holds an adapter, the factory, the error class, the serializer or a
+ * collaborator type is free to change without moving anything a caller
+ * imports. What appears here is the whole supported surface; the package's
+ * exports map admits no deep import, so nothing else is reachable.
+ *
+ * @packageDocumentation
+ */
 export { DynamoDBSaver } from './checkpointer/saver';
-export type { DynamoDBSaverOptions } from './checkpointer/types';
+export type { DeltaChannelHistoryOptions, DynamoDBSaverOptions } from './checkpointer/types';
 export { DynamoDBStore } from './store/store';
-export type { DynamoDBStoreOptions } from './store/types';
-export type { VectorReconcileResult } from './store/actions/reconcile-vector-index';
-export type { VectorBackend, VectorMatch, VectorRef } from './store/vector-backend';
+export type { DynamoDBStoreOptions, ListNamespacesOptions, SearchOptions, VectorReconcileResult, } from './store/types';
+export type { VectorBackend, VectorMatch, VectorRef, VectorScoreDirection, } from './store/vector-backend';
 export { DynamoDBChatMessageHistory } from './history/chat-message-history';
 export { DynamoDBSessionChatMessageHistory } from './history/session-adapter';
-export type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions, SessionMetadata, } from './history/types';
+export type { AdapterWindow, MultiSessionHistory, SessionBackend } from './history/session-adapter';
+export type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions, GetMessagesOptions, ListSessionsOptions, SessionPage, MessageWindow, SessionMetadata, } from './history/types';
+/**
+ * Operator tool: give rows written before the recency index their index keys.
+ * Run it before setting `indexName` on any adapter — see its own documentation
+ * for why enabling the index first hides pre-existing rows from the listings.
+ */
+export { backfillRecencyIndex } from './backfill/backfill';
+export type { BackfillOptions, BackfillResult } from './backfill/backfill';
 export { DynamoDBFactory } from './factory/factory';
-export type { CreateAllOptions, CreatedAdapters, FactoryBaseOptions } from './factory/factory';
-export { DynamoDbLangGraphError } from './shared/errors/base-error';
-export type { ErrorContext } from './shared/errors/base-error';
+export type { AdapterSection, CreateAllOptions, CreatedAdapters, FactoryBaseOptions, } from './factory/types';
+/**
+ * The plain JSON serializer the store and chat-history adapters use by
+ * default, exported so a checkpointer can be given it in place of LangGraph's
+ * `JsonPlusSerializer`, whose read path instantiates the class a stored
+ * `{"lc": …}` record names. See the README's *Trust boundary* note and
+ * `SECURITY.md`.
+ */
+export { JSON_SERDE } from './shared/codec/json-serde';
+export { DynamoDBLangGraphError, isDynamoDBLangGraphError } from './shared/errors/base-error';
+export type { AnyDynamoDBLangGraphError, BatchDrainDetails, BatchPassDetails, BatchWriteIncompleteDetails, CompensationFailedDetails, ErrorContext, ErrorDetailsByCode, ErrorDetailsFor, } from './shared/errors/base-error';
 export { ErrorCode } from './shared/errors/error-code';
-export { AbortError, BatchWriteAllIncompleteError, BatchWriteIncompleteError, CompensationFailedError, ConflictError, ResultTruncatedError, RetryExhaustedError, ValidationError, } from './shared/errors/errors';
 export type { Logger, LogArgument } from './shared/logging/logger';
 export { redactLogger, redactSecrets } from './shared/logging/redaction';
-export type { BaseAdapterOptions, CodecOptions } from './shared/options';
+export type { Redactable, RedactLoggerOptions } from './shared/logging/redaction';
+export type { CancelOptions, BaseAdapterOptions, CodecOptions } from './shared/options';
+export type { DynamoDBDocumentLike } from './shared/dynamodb/client';
+export type { RetryAttemptInfo, RetryOptions, RetryPolicy } from './shared/dynamodb/retry';
 export type { TtlOption } from './shared/validation/ttl';
 export type { CompressionConfig } from './shared/codec/compression';
 export type { S3OffloadConfig } from './shared/codec/s3/config';
-//# sourceMappingURL=index.d.ts.map
+export type { S3ClientConfigLike, S3ClientLike, S3ClientOption, S3ClientOptions, S3CommandLike, S3RegionLike, } from './shared/codec/s3/client-types';

package/dist/index.js

@@ -1,6 +1,20 @@
 "use strict";
+/**
+ * AWS DynamoDB implementation of LangGraph's checkpoint saver, memory store
+ * and chat message history, in TypeScript.
+ *
+ * Hides where anything lives.
+ *
+ * This module re-exports and declares nothing of its own, so which module
+ * holds an adapter, the factory, the error class, the serializer or a
+ * collaborator type is free to change without moving anything a caller
+ * imports. What appears here is the whole supported surface; the package's
+ * exports map admits no deep import, so nothing else is reachable.
+ *
+ * @packageDocumentation
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.redactSecrets = exports.redactLogger = exports.ValidationError = exports.RetryExhaustedError = exports.ResultTruncatedError = exports.ConflictError = exports.CompensationFailedError = exports.BatchWriteIncompleteError = exports.BatchWriteAllIncompleteError = exports.AbortError = exports.ErrorCode = exports.DynamoDbLangGraphError = exports.DynamoDBFactory = exports.DynamoDBSessionChatMessageHistory = exports.DynamoDBChatMessageHistory = exports.DynamoDBStore = exports.DynamoDBSaver = void 0;
+exports.redactSecrets = exports.redactLogger = exports.ErrorCode = exports.isDynamoDBLangGraphError = exports.DynamoDBLangGraphError = exports.JSON_SERDE = exports.DynamoDBFactory = exports.backfillRecencyIndex = exports.DynamoDBSessionChatMessageHistory = exports.DynamoDBChatMessageHistory = exports.DynamoDBStore = exports.DynamoDBSaver = void 0;
 var saver_1 = require("./checkpointer/saver");
 Object.defineProperty(exports, "DynamoDBSaver", { enumerable: true, get: function () { return saver_1.DynamoDBSaver; } });
 var store_1 = require("./store/store");
@@ -9,22 +23,29 @@ var chat_message_history_1 = require("./history/chat-message-history");
 Object.defineProperty(exports, "DynamoDBChatMessageHistory", { enumerable: true, get: function () { return chat_message_history_1.DynamoDBChatMessageHistory; } });
 var session_adapter_1 = require("./history/session-adapter");
 Object.defineProperty(exports, "DynamoDBSessionChatMessageHistory", { enumerable: true, get: function () { return session_adapter_1.DynamoDBSessionChatMessageHistory; } });
+/**
+ * Operator tool: give rows written before the recency index their index keys.
+ * Run it before setting `indexName` on any adapter — see its own documentation
+ * for why enabling the index first hides pre-existing rows from the listings.
+ */
+var backfill_1 = require("./backfill/backfill");
+Object.defineProperty(exports, "backfillRecencyIndex", { enumerable: true, get: function () { return backfill_1.backfillRecencyIndex; } });
 var factory_1 = require("./factory/factory");
 Object.defineProperty(exports, "DynamoDBFactory", { enumerable: true, get: function () { return factory_1.DynamoDBFactory; } });
+/**
+ * The plain JSON serializer the store and chat-history adapters use by
+ * default, exported so a checkpointer can be given it in place of LangGraph's
+ * `JsonPlusSerializer`, whose read path instantiates the class a stored
+ * `{"lc": …}` record names. See the README's *Trust boundary* note and
+ * `SECURITY.md`.
+ */
+var json_serde_1 = require("./shared/codec/json-serde");
+Object.defineProperty(exports, "JSON_SERDE", { enumerable: true, get: function () { return json_serde_1.JSON_SERDE; } });
 var base_error_1 = require("./shared/errors/base-error");
-Object.defineProperty(exports, "DynamoDbLangGraphError", { enumerable: true, get: function () { return base_error_1.DynamoDbLangGraphError; } });
+Object.defineProperty(exports, "DynamoDBLangGraphError", { enumerable: true, get: function () { return base_error_1.DynamoDBLangGraphError; } });
+Object.defineProperty(exports, "isDynamoDBLangGraphError", { enumerable: true, get: function () { return base_error_1.isDynamoDBLangGraphError; } });
 var error_code_1 = require("./shared/errors/error-code");
 Object.defineProperty(exports, "ErrorCode", { enumerable: true, get: function () { return error_code_1.ErrorCode; } });
-var errors_1 = require("./shared/errors/errors");
-Object.defineProperty(exports, "AbortError", { enumerable: true, get: function () { return errors_1.AbortError; } });
-Object.defineProperty(exports, "BatchWriteAllIncompleteError", { enumerable: true, get: function () { return errors_1.BatchWriteAllIncompleteError; } });
-Object.defineProperty(exports, "BatchWriteIncompleteError", { enumerable: true, get: function () { return errors_1.BatchWriteIncompleteError; } });
-Object.defineProperty(exports, "CompensationFailedError", { enumerable: true, get: function () { return errors_1.CompensationFailedError; } });
-Object.defineProperty(exports, "ConflictError", { enumerable: true, get: function () { return errors_1.ConflictError; } });
-Object.defineProperty(exports, "ResultTruncatedError", { enumerable: true, get: function () { return errors_1.ResultTruncatedError; } });
-Object.defineProperty(exports, "RetryExhaustedError", { enumerable: true, get: function () { return errors_1.RetryExhaustedError; } });
-Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_1.ValidationError; } });
 var redaction_1 = require("./shared/logging/redaction");
 Object.defineProperty(exports, "redactLogger", { enumerable: true, get: function () { return redaction_1.redactLogger; } });
 Object.defineProperty(exports, "redactSecrets", { enumerable: true, get: function () { return redaction_1.redactSecrets; } });
-//# sourceMappingURL=index.js.map

package/dist/shared/adapter.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Hides what an adapter owns for its lifetime, and how it lets go of it.
+ *
+ * Every adapter resolves the same things from its options — a DynamoDB client
+ * it either built, and so must destroy, or was handed, and so must not; an S3
+ * offloader when it offloads; a logger; a retry policy; the recency index's
+ * settings — releases them the same way, and provisions the same lifecycle
+ * rule from its ttl. Whether an adapter owns its client is decided in
+ * `dynamodb/client.ts`; this module only reads that decision, to release a
+ * client it built and leave an injected one alone.
+ */
+import type { CompressionConfig } from './codec/compression';
+import { type AdapterName } from './codec/s3/config';
+import { S3Offloader } from './codec/s3/offloader';
+import { type DynamoDBDocumentLike } from './dynamodb/client';
+import { type RetryOptions } from './dynamodb/retry';
+import { type Logger } from './logging/logger';
+import type { BaseAdapterOptions, CodecOptions } from './options';
+import { type TtlOption } from './validation/ttl';
+/** Anything an adapter holds open and must hand back when it is torn down. */
+export interface Releasable {
+    destroy(): void;
+}
+/**
+ * Release every resource, whatever any one of them does.
+ *
+ * The hazard is the one `DynamoDBFactory`'s own `release` names: a teardown
+ * written as a sequence of statements stops at the first throw, so everything
+ * after it is stranded with no reference left to reach it by. Each adapter's
+ * `destroy` was exactly that sequence — the S3 offloader, then the DynamoDB
+ * client it built — and an S3 client whose sockets are already gone throws from
+ * its own `destroy`, so the DynamoDB client leaked for the life of the process.
+ *
+ * Accepts: `resources` — in the order they should be released; an absent one
+ * (an adapter with no offloader, a client the caller injected and therefore
+ * owns) is skipped rather than guarded at each call site.
+ *
+ * Returns: nothing.
+ *
+ * Throws: the **first** failure, and only after every resource has been
+ * offered its release, so nothing is stranded behind it. Raised rather than
+ * logged because the default logger discards everything: a caller who never
+ * configured one would otherwise be told nowhere at all that a client of theirs
+ * is still holding sockets. A later failure is dropped, because a caller can
+ * act on one report and the first one names the resource that actually broke.
+ * A `throw` that produced something other than an `Error` is normalised, so a
+ * caller's `catch` is handed the same shape whatever a client raised.
+ */
+export declare function releaseOwned(resources: readonly (Releasable | undefined)[]): void;
+/** What every adapter resolves from its options and every operation reads. */
+export interface AdapterCore {
+    client: DynamoDBDocumentLike;
+    tableName: string;
+    compression?: CompressionConfig;
+    offloader?: S3Offloader;
+    ttl?: TtlOption;
+    logger: Logger;
+    /** Retry budget and backoff for every DynamoDB call, with the retry debug log attached. */
+    retry?: RetryOptions;
+    /**
+     * Index partitions per adapter for the recency index; see `indexKeys`.
+     * Absent means the default, which is where it is resolved.
+     */
+    indexShards?: number;
+    /** Payloads decoded at once by one call; the memory ceiling’s multiplier. */
+    readConcurrency?: number;
+    /** Name of the recency index, when the table carries one; see `BaseAdapterOptions.indexName`. */
+    indexName?: string;
+}
+/** An adapter's hold on what it owns. */
+export interface AdapterShell {
+    readonly core: AdapterCore;
+    /** Provision the S3 lifecycle rule for the configured ttl; see {@link ensureLifecycleFor}. */
+    ensureLifecycleRule(): Promise<void>;
+    /** Release the offloader, and the DynamoDB client when the adapter built it; see {@link releaseOwned}. */
+    release(): void;
+}
+/** The checks an adapter adds to the shared ones, and where they run. */
+export interface AdapterChecks {
+    /** Runs after the shared option checks and before the collaborator checks. */
+    options?: () => void;
+    /** Runs after the shared collaborator checks, before anything is built. */
+    collaborators?: () => void;
+    /** The fewest attempts the adapter's own writes need; see `resolveRetryPolicy`. */
+    attemptFloor?: number;
+}
+/** The options every adapter takes, with the serializer each may add. */
+export type AdapterOptions = BaseAdapterOptions & CodecOptions & {
+    serde?: object;
+};
+/**
+ * Provision the S3 lifecycle rule that expires what an adapter offloads, on its
+ * ttl, so an offloaded payload does not outlive the DynamoDB item that points
+ * at it.
+ *
+ * The rule is expressed in whole days because that is the only granularity S3
+ * lifecycle expiration accepts, while the DynamoDB TTL is in seconds; see
+ * `lifecycleExpirationDays` for the rounding, which is always up.
+ *
+ * Accepts: `core` — the adapter's offloader, ttl and logger.
+ *
+ * Returns: nothing. Without an offloader there is nothing to rule over, and
+ * without a ttl no item expires, so any rule would delete a payload a live row
+ * still needs: either absence does nothing. Installing a rule that is already
+ * there is a no-op too, so calling this on every deploy is safe.
+ *
+ * Throws: whatever reading or writing the bucket's lifecycle configuration
+ * throws, and `VALIDATION` naming `s3.keyPrefix` when the rule id this
+ * prefix would take is already held by a different prefix.
+ *
+ * Guarantees: needs the bucket-level `s3:GetLifecycleConfiguration` /
+ * `s3:PutLifecycleConfiguration` permissions, which are broader than the
+ * object-level CRUD the rest of offload uses — so this is a provisioning call,
+ * not a per-request one.
+ */
+export declare function ensureLifecycleFor(core: Pick<AdapterCore, 'offloader' | 'ttl' | 'logger'>): Promise<void>;
+/**
+ * Check an adapter's options and resolve what it will own.
+ *
+ * Accepts: `options` — the adapter's, already held to its own key list, and
+ * checked first, so no half-built adapter exists when one is wrong.
+ * `adapter` — which adapter, which names its default S3 key prefix. `checks` —
+ * the adapter's own option and collaborator checks, and its retry floor.
+ *
+ * Returns: the shell: the core every operation reads, with every shared
+ * default filled in here and nowhere else, and the adapter's two lifetime
+ * operations. A client the caller passed in is never destroyed by `release`.
+ *
+ * Throws: `VALIDATION` for an option or a collaborator that fails a shared
+ * check or one of `checks`, in that order.
+ *
+ * Guarantees: no I/O. The stacked-retry check is deliberately not awaited: it
+ * is a warning about a caller-supplied client, not a precondition.
+ */
+export declare function openAdapter(options: AdapterOptions, adapter: AdapterName, checks?: AdapterChecks): AdapterShell;

package/dist/shared/adapter.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Hides what an adapter owns for its lifetime, and how it lets go of it.
+ *
+ * Every adapter resolves the same things from its options — a DynamoDB client
+ * it either built, and so must destroy, or was handed, and so must not; an S3
+ * offloader when it offloads; a logger; a retry policy; the recency index's
+ * settings — releases them the same way, and provisions the same lifecycle
+ * rule from its ttl. Whether an adapter owns its client is decided in
+ * `dynamodb/client.ts`; this module only reads that decision, to release a
+ * client it built and leave an injected one alone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.releaseOwned = releaseOwned;
+exports.ensureLifecycleFor = ensureLifecycleFor;
+exports.openAdapter = openAdapter;
+const config_1 = require("./codec/s3/config");
+const offloader_1 = require("./codec/s3/offloader");
+const concurrency_1 = require("./concurrency");
+const client_1 = require("./dynamodb/client");
+const recency_index_1 = require("./dynamodb/recency-index");
+const retry_1 = require("./dynamodb/retry");
+const base_error_1 = require("./errors/base-error");
+const logger_1 = require("./logging/logger");
+const collaborators_1 = require("./validation/collaborators");
+const options_1 = require("./validation/options");
+const ttl_1 = require("./validation/ttl");
+/**
+ * Release every resource, whatever any one of them does.
+ *
+ * The hazard is the one `DynamoDBFactory`'s own `release` names: a teardown
+ * written as a sequence of statements stops at the first throw, so everything
+ * after it is stranded with no reference left to reach it by. Each adapter's
+ * `destroy` was exactly that sequence — the S3 offloader, then the DynamoDB
+ * client it built — and an S3 client whose sockets are already gone throws from
+ * its own `destroy`, so the DynamoDB client leaked for the life of the process.
+ *
+ * Accepts: `resources` — in the order they should be released; an absent one
+ * (an adapter with no offloader, a client the caller injected and therefore
+ * owns) is skipped rather than guarded at each call site.
+ *
+ * Returns: nothing.
+ *
+ * Throws: the **first** failure, and only after every resource has been
+ * offered its release, so nothing is stranded behind it. Raised rather than
+ * logged because the default logger discards everything: a caller who never
+ * configured one would otherwise be told nowhere at all that a client of theirs
+ * is still holding sockets. A later failure is dropped, because a caller can
+ * act on one report and the first one names the resource that actually broke.
+ * A `throw` that produced something other than an `Error` is normalised, so a
+ * caller's `catch` is handed the same shape whatever a client raised.
+ */
+function releaseOwned(resources) {
+    let first;
+    for (const resource of resources) {
+        try {
+            resource?.destroy();
+        }
+        catch (error) {
+            first ??= (0, base_error_1.toError)(error);
+        }
+    }
+    if (first !== undefined)
+        throw first;
+}
+/**
+ * Provision the S3 lifecycle rule that expires what an adapter offloads, on its
+ * ttl, so an offloaded payload does not outlive the DynamoDB item that points
+ * at it.
+ *
+ * The rule is expressed in whole days because that is the only granularity S3
+ * lifecycle expiration accepts, while the DynamoDB TTL is in seconds; see
+ * `lifecycleExpirationDays` for the rounding, which is always up.
+ *
+ * Accepts: `core` — the adapter's offloader, ttl and logger.
+ *
+ * Returns: nothing. Without an offloader there is nothing to rule over, and
+ * without a ttl no item expires, so any rule would delete a payload a live row
+ * still needs: either absence does nothing. Installing a rule that is already
+ * there is a no-op too, so calling this on every deploy is safe.
+ *
+ * Throws: whatever reading or writing the bucket's lifecycle configuration
+ * throws, and `VALIDATION` naming `s3.keyPrefix` when the rule id this
+ * prefix would take is already held by a different prefix.
+ *
+ * Guarantees: needs the bucket-level `s3:GetLifecycleConfiguration` /
+ * `s3:PutLifecycleConfiguration` permissions, which are broader than the
+ * object-level CRUD the rest of offload uses — so this is a provisioning call,
+ * not a per-request one.
+ */
+async function ensureLifecycleFor(core) {
+    if (!core.offloader || !core.ttl)
+        return;
+    await core.offloader.ensureLifecycleRule((0, ttl_1.lifecycleExpirationDays)(core.ttl), core.logger);
+}
+/**
+ * Check an adapter's options and resolve what it will own.
+ *
+ * Accepts: `options` — the adapter's, already held to its own key list, and
+ * checked first, so no half-built adapter exists when one is wrong.
+ * `adapter` — which adapter, which names its default S3 key prefix. `checks` —
+ * the adapter's own option and collaborator checks, and its retry floor.
+ *
+ * Returns: the shell: the core every operation reads, with every shared
+ * default filled in here and nowhere else, and the adapter's two lifetime
+ * operations. A client the caller passed in is never destroyed by `release`.
+ *
+ * Throws: `VALIDATION` for an option or a collaborator that fails a shared
+ * check or one of `checks`, in that order.
+ *
+ * Guarantees: no I/O. The stacked-retry check is deliberately not awaited: it
+ * is a warning about a caller-supplied client, not a precondition.
+ */
+function openAdapter(options, adapter, checks = {}) {
+    (0, options_1.assertBaseAdapterOptions)(options);
+    checks.options?.();
+    (0, collaborators_1.assertBaseCollaborators)(options);
+    checks.collaborators?.();
+    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);
+    const offloader = options.s3
+        ? new offloader_1.S3Offloader((0, config_1.offloaderConfigFor)(options.s3, adapter, options.clientConfig))
+        : undefined;
+    const core = {
+        client: resolved.client,
+        tableName: options.tableName,
+        compression: options.compression,
+        offloader,
+        ttl: options.ttl,
+        logger,
+        retry: (0, retry_1.resolveRetryPolicy)(options.retry, logger, checks.attemptFloor),
+        indexShards: options.indexShards ?? recency_index_1.DEFAULT_INDEX_SHARDS,
+        readConcurrency: options.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY,
+        indexName: options.indexName,
+    };
+    return {
+        core,
+        ensureLifecycleRule: () => ensureLifecycleFor(core),
+        release: () => releaseOwned([offloader, resolved.ownsClient ? resolved.ddbClient : undefined]),
+    };
+}

package/dist/shared/clock.d.ts

@@ -1,3 +1,52 @@
-/** Current time as an ISO-8601 string, derived from the (test-freezable) clock. */
+/**
+ * Hides where the current time comes from, and in which unit each reader
+ * takes it.
+ *
+ * Every timestamp, deadline and expiry this package computes through
+ * `nowIso`, `nowMs` or `nowSeconds` reads `Date.now` through here, so a test
+ * that freezes it freezes all of them at once, and under a skewed clock they
+ * agree with each other rather than disagreeing by a second. Two call sites
+ * take their own default instead of this seam — `calculateTtlTimestamp`'s
+ * `now` parameter and `createUlidFactory`'s `now` parameter, both defaulting
+ * to `Date.now` directly — so freezing this module's clock alone does not
+ * freeze them. That the ISO form sorts chronologically and that the TTL unit
+ * is floored seconds are settled here; a caller asks for the unit it needs.
+ */
+/**
+ * The current time as an ISO-8601 string.
+ *
+ * Accepts: nothing; it reads `Date.now`, which the test setup freezes.
+ *
+ * Returns: UTC, millisecond precision, `Z`-suffixed — the form whose byte order
+ * is its chronological order, which is why it can lead a sort key unparsed.
+ *
+ * Throws: nothing.
+ */
 export declare function nowIso(): string;
-//# sourceMappingURL=clock.d.ts.map
+/**
+ * The current time as epoch milliseconds.
+ *
+ * Accepts: nothing; it reads `Date.now`, which the test setup freezes.
+ *
+ * Returns: the millisecond, unrounded — the unit a whole-operation deadline is
+ * measured in, since a retry budget is bounded far below a second's
+ * granularity of error.
+ *
+ * Throws: nothing.
+ */
+export declare function nowMs(): number;
+/**
+ * The current time as whole epoch seconds, the unit DynamoDB's TTL uses.
+ *
+ * Accepts: nothing; it reads `Date.now`, which the test setup freezes.
+ *
+ * Returns: the second, floored — never a fraction, which DynamoDB would reject
+ * on the `ttl` attribute.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: every expiry stamp, expiry filter and ttl-anchor comparison in
+ * this package reads this one seam, so they agree with each other under a
+ * frozen or skewed clock rather than disagreeing by a second.
+ */
+export declare function nowSeconds(): number;

package/dist/shared/clock.js

@@ -1,8 +1,63 @@
 "use strict";
+/**
+ * Hides where the current time comes from, and in which unit each reader
+ * takes it.
+ *
+ * Every timestamp, deadline and expiry this package computes through
+ * `nowIso`, `nowMs` or `nowSeconds` reads `Date.now` through here, so a test
+ * that freezes it freezes all of them at once, and under a skewed clock they
+ * agree with each other rather than disagreeing by a second. Two call sites
+ * take their own default instead of this seam — `calculateTtlTimestamp`'s
+ * `now` parameter and `createUlidFactory`'s `now` parameter, both defaulting
+ * to `Date.now` directly — so freezing this module's clock alone does not
+ * freeze them. That the ISO form sorts chronologically and that the TTL unit
+ * is floored seconds are settled here; a caller asks for the unit it needs.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nowIso = nowIso;
-/** Current time as an ISO-8601 string, derived from the (test-freezable) clock. */
+exports.nowMs = nowMs;
+exports.nowSeconds = nowSeconds;
+/**
+ * The current time as an ISO-8601 string.
+ *
+ * Accepts: nothing; it reads `Date.now`, which the test setup freezes.
+ *
+ * Returns: UTC, millisecond precision, `Z`-suffixed — the form whose byte order
+ * is its chronological order, which is why it can lead a sort key unparsed.
+ *
+ * Throws: nothing.
+ */
 function nowIso() {
     return new Date(Date.now()).toISOString();
 }
-//# sourceMappingURL=clock.js.map
+/**
+ * The current time as epoch milliseconds.
+ *
+ * Accepts: nothing; it reads `Date.now`, which the test setup freezes.
+ *
+ * Returns: the millisecond, unrounded — the unit a whole-operation deadline is
+ * measured in, since a retry budget is bounded far below a second's
+ * granularity of error.
+ *
+ * Throws: nothing.
+ */
+function nowMs() {
+    return Date.now();
+}
+/**
+ * The current time as whole epoch seconds, the unit DynamoDB's TTL uses.
+ *
+ * Accepts: nothing; it reads `Date.now`, which the test setup freezes.
+ *
+ * Returns: the second, floored — never a fraction, which DynamoDB would reject
+ * on the `ttl` attribute.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: every expiry stamp, expiry filter and ttl-anchor comparison in
+ * this package reads this one seam, so they agree with each other under a
+ * frozen or skewed clock rather than disagreeing by a second.
+ */
+function nowSeconds() {
+    return Math.floor(Date.now() / 1000);
+}