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

package/dist/history/chat-message-history.js

@@ -1,7 +1,20 @@
 "use strict";
+/**
+ * Hides that chat history is a set of actions behind one error boundary.
+ *
+ * The public class holds only what it resolved from its options and routes
+ * each read and write to the action that implements it, through
+ * `guardPublic`. Each asynchronous method is the error boundary, so no error
+ * but the library's own reaches a caller (record 13); the synchronous
+ * `destroy` and `forSession` are the exceptions — the latter is also the
+ * one route from it to LangChain's single-session history. Where an action
+ * lives, how it reads or writes, and which client or offloader it uses can
+ * change without touching this surface.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DynamoDBChatMessageHistory = void 0;
-const ttl_1 = require("../shared/validation/ttl");
+const boundary_1 = require("../shared/errors/boundary");
+const collaborators_1 = require("../shared/validation/collaborators");
 const add_messages_1 = require("./actions/add-messages");
 const clear_1 = require("./actions/clear");
 const get_messages_1 = require("./actions/get-messages");
@@ -10,72 +23,256 @@ const reconcile_count_1 = require("./actions/reconcile-count");
 const setup_1 = require("./internal/setup");
 const session_adapter_1 = require("./session-adapter");
 /**
- * DynamoDB-backed multi-session chat history. Each message is its own item
- * (ordered by a monotonic ULID, compressed / S3-offloaded as needed) alongside a
- * per-session metadata item; every message in a session shares one uniform TTL.
- * Appends are O(1) and lock-free. Use {@link forSession} to get a single-session
- * LangChain adapter.
+ * DynamoDB-backed multi-session chat history. Each message is its own row,
+ * ordered by when it was appended, beside one metadata row per session, and
+ * every message in a session shares one TTL. An append costs the same however
+ * long the session is and takes no lock. Use {@link forSession} to get a
+ * single-session LangChain adapter. Every public method rejects only with this
+ * library's error.
  */
 class DynamoDBChatMessageHistory {
     context;
-    ownsClient;
-    ddbClient;
+    shell;
+    /**
+     * Accepts: `options` — validated here, so a misconfiguration surfaces at
+     * construction rather than on the first request.
+     *
+     * Returns: an adapter that owns the client it built, or borrows the one it
+     * was given.
+     *
+     * Throws: `VALIDATION` naming the offending option.
+     *
+     * Guarantees: no I/O. Constructing the adapter issues no request.
+     */
     constructor(options) {
         const setup = (0, setup_1.setUpHistory)(options);
         this.context = setup.context;
-        this.ownsClient = setup.ownsClient;
-        this.ddbClient = setup.ddbClient;
+        this.shell = setup.shell;
     }
-    /** Get a session's messages in order. */
-    getMessages(sessionId) {
-        return (0, get_messages_1.getMessages)(this.context, sessionId);
+    /**
+     * Get a session's messages in chronological order.
+     *
+     * Accepts: `sessionId` — validated. `options.limit` — an integer from 1 to
+     * `MAX_PAGE_LIMIT` (10,000); only the newest that many messages. `0` is
+     * refused rather than answered with an empty conversation, which is the one
+     * place this package refuses a `limit` of zero. `options.before` — a valid
+     * `Date`; only messages appended before that instant. Neither given reads
+     * the whole session. `options.signal` — aborts the reads.
+     *
+     * Returns: the messages, oldest first. A session that does not exist and one
+     * whose messages have all expired both return nothing.
+     *
+     * Throws: `VALIDATION` for a malformed session id or window, an invalid
+     * `signal`, or naming `options.<key>` for a key this package does not read;
+     * `VALIDATION` naming `s3Key` for a row addressing an object outside the
+     * session's own path, and naming `message` for a row in this session's
+     * message key space that this adapter did not write, both whatever the
+     * corruption policy;
+     * `FORMAT_UNSUPPORTED` for a row, or a payload, a newer release wrote;
+     * a classified AWS failure;
+     * `ABORTED`; and, under `onCorruptMessage: 'throw'`, the decode error of a
+     * corrupt row.
+     *
+     * Guarantees: strongly consistent, so the turn just appended is visible.
+     * Expired messages are filtered on read, so the history is never stale.
+     * @remarks One query page plus one S3 download per offloaded message.
+     */
+    getMessages(sessionId, options) {
+        return (0, boundary_1.guardPublic)('history.getMessages', () => (0, get_messages_1.getMessages)(this.context, sessionId, options));
     }
-    /** Append messages to a session. */
-    addMessages(sessionId, messages) {
-        return (0, add_messages_1.addMessages)(this.context, sessionId, messages);
+    /**
+     * Append messages to a session.
+     *
+     * Accepts: `sessionId` — validated. `messages` — LangChain messages; an empty
+     * list writes nothing and is not an error. `options.signal` — aborts between
+     * chunks.
+     *
+     * Returns: nothing, and only once every message has landed.
+     *
+     * Throws: `VALIDATION` naming `messages`, for a value that is not itself
+     * an array, or, with the offending index, for an element that is not a
+     * message or one that could never be read back; or naming `signal` or
+     * `options.<key>` for a key this package does not read;
+     * `COMPENSATION_FAILED` when a later chunk fails and the rollback fails
+     * too; `RETRY_EXHAUSTED` after 18 contended attempts; a classified AWS failure;
+     * `ABORTED`.
+     *
+     * Guarantees: a caller observes all messages or none. One transaction per
+     * chunk of up to 99 keeps `messageCount` exact. Lock-free and safe under
+     * concurrent appends to one session; every message shares the session's TTL
+     * when one is configured.
+     */
+    addMessages(sessionId, messages, options) {
+        return (0, boundary_1.guardPublic)('history.addMessages', () => {
+            (0, collaborators_1.assertCancelOptions)(options);
+            return (0, add_messages_1.addMessages)(this.context, sessionId, messages, options?.signal);
+        });
     }
-    /** Append a single message to a session. */
-    addMessage(sessionId, message) {
-        return (0, add_messages_1.addMessages)(this.context, sessionId, [message]);
+    /**
+     * Append one message.
+     *
+     * Accepts: as {@link addMessages}, for a single message.
+     *
+     * Returns: nothing.
+     *
+     * Throws: as {@link addMessages}.
+     */
+    addMessage(sessionId, message, options) {
+        return (0, boundary_1.guardPublic)('history.addMessage', () => {
+            (0, collaborators_1.assertCancelOptions)(options);
+            return (0, add_messages_1.addMessages)(this.context, sessionId, [message], options?.signal);
+        });
     }
-    /** Delete a session and any offloaded payload. */
-    clear(sessionId) {
-        return (0, clear_1.clearSession)(this.context, sessionId);
+    /**
+     * Delete a session's messages, metadata and offloaded objects.
+     *
+     * Accepts: `sessionId` — validated. `options.signal` — aborts between pages.
+     *
+     * Returns: nothing. Clearing a session that does not exist is not an error.
+     *
+     * Throws: `VALIDATION` for a malformed session id, an invalid `signal`,
+     * or an `options.<key>` this package does not read;
+     * `BATCH_WRITE_INCOMPLETE` when a row's delete fails, counting rows
+     * rather than batches; a classified AWS failure; `ABORTED` when the signal fires,
+     * which is what a cancel surfaces as rather than an incomplete delete, even
+     * when it fires part-way through the pass. A row refused because it
+     * was rewritten after the partition read raises nothing: it is left in place,
+     * reported at `warn`, and counted as skipped.
+     *
+     * Guarantees: a row this adapter did not write is left in place and logged,
+     * and neither is a row rewritten since the read — an append landing during
+     * the call moves the session row's own write id, so that row survives with
+     * the session it belongs to instead of being removed under a live
+     * conversation. Single pass: call it when the session is quiescent, since a
+     * message appended while it runs may survive it, and the surviving session
+     * row then over-counts until `reconcileMessageCount` repairs it.
+     */
+    clear(sessionId, options) {
+        return (0, boundary_1.guardPublic)('history.clear', () => {
+            (0, collaborators_1.assertCancelOptions)(options);
+            return (0, clear_1.clearSession)(this.context, sessionId, options);
+        });
     }
-    /** List all sessions as metadata summaries. */
+    /**
+     * List every session as a metadata summary, most recently updated first.
+     * With a configured `indexName` this reads each index shard newest-first,
+     * merges the shards and pages by the opaque `nextCursor`. Without one it
+     * falls back to a filtered table scan — cross-tenant by construction,
+     * bounded by `maxItems` / `maxIterations`, and returning the newest `limit`
+     * sessions, or every session when no limit is given, with no cursor.
+     *
+     * Accepts: `options.limit` — an integer from 0 to `MAX_PAGE_LIMIT` (10,000);
+     * the page size with the index, the newest N without it, and `0` an empty
+     * page read from neither. `options.cursor` — from a previous page,
+     * and only with a configured `indexName`. `options.maxItems` /
+     * `maxIterations` — caps on the scan path. `options.signal` — aborts the
+     * reads.
+     *
+     * Returns: the page and, while rows may remain, a `nextCursor`. A page may
+     * come back shorter than `limit` while more rows remain: expired and foreign
+     * rows are dropped after the read. A cursor does not promise more rows:
+     * DynamoDB can end a shard's page at its last row and still return a key to
+     * continue from, and the page after such a cursor can come back empty. Stop
+     * when `nextCursor` is absent, never when a page looks short.
+     *
+     * Throws: `VALIDATION` naming `limit`, `cursor`, `maxItems`,
+     * `maxIterations`, `signal`, or `options.<key>` for a key this package does
+     * not read; `RESULT_TRUNCATED` past either cap on the scan path, or for an
+     * index shard whose pages do not end; `FORMAT_UNSUPPORTED` for a session row
+     * a newer release wrote; a classified AWS failure; `ABORTED`.
+     *
+     * Guarantees: with a configured `indexName` each shard is read one DynamoDB
+     * page at a time, and its next page whenever it has no row buffered and the
+     * page still needs one, so a shard can cost a query whose rows the page never
+     * takes; at most `readConcurrency` shards are queried at once. Memory is the
+     * page being built, up to `limit` rows and so bounded by
+     * `MAX_PAGE_LIMIT` (10,000), plus at most one DynamoDB page per shard,
+     * whatever the table holds.
+     */
     listSessions(options) {
-        return (0, list_sessions_1.listSessions)(this.context, options);
+        return (0, boundary_1.guardPublic)('history.listSessions', () => (0, list_sessions_1.listSessions)(this.context, options));
     }
     /**
      * Recompute and repair a session's `messageCount` from the stored messages.
      * A maintenance tool for external corruption; run it when the session is idle.
+     *
+     * Accepts: `sessionId` — validated, and an existing session.
+     * `options.signal` — aborts the reads.
+     *
+     * Returns: the count now stored, which is the number of messages a reader
+     * would see.
+     *
+     * Throws: `VALIDATION` for a malformed session id, an invalid `signal`,
+     * or an `options.<key>` this package does not read; `CONDITION_CONFLICT` when the
+     * session does not exist or stayed busy through every attempt;
+     * `FORMAT_UNSUPPORTED` for a message row a newer release wrote, and
+     * `VALIDATION` naming `message` for a row in the session's message key
+     * space that this adapter did not write, both of which `getMessages` refuses
+     * too — a count is a repair only while it agrees with the read;
+     * a classified AWS failure; `ABORTED`.
+     *
+     * Guarantees: safe on a live session — the write is pinned to the value the
+     * row held when the count was computed, so a concurrent append makes it
+     * recount instead of clobbering the increment.
      */
-    reconcileMessageCount(sessionId) {
-        return (0, reconcile_count_1.reconcileMessageCount)(this.context, sessionId);
+    reconcileMessageCount(sessionId, options) {
+        return (0, boundary_1.guardPublic)('history.reconcileMessageCount', () => {
+            (0, collaborators_1.assertCancelOptions)(options);
+            return (0, reconcile_count_1.reconcileMessageCount)(this.context, sessionId, options?.signal);
+        });
     }
-    /** Get a single-session LangChain adapter for `sessionId`. */
-    forSession(sessionId) {
-        return new session_adapter_1.DynamoDBSessionChatMessageHistory(this, sessionId);
+    /**
+     * Get a single-session LangChain adapter for `sessionId`.
+     *
+     * Accepts: `sessionId` — validated by the adapter's own constructor, the
+     * same rule every other method applies. `window.limit` — bounds what the
+     * adapter feeds the chain to the newest that many messages; validated the
+     * same way.
+     *
+     * Returns: an adapter implementing `BaseListChatMessageHistory`, which is
+     * what `RunnableWithMessageHistory` takes.
+     *
+     * Throws: `VALIDATION` naming `sessionId`, `window` for a window that is
+     * not an object, `window.<key>` for a key the adapter does not declare, or
+     * `limit` — raised by the constructed adapter, so a bad id or window fails
+     * here rather than on first use.
+     */
+    forSession(sessionId, window) {
+        return new session_adapter_1.DynamoDBSessionChatMessageHistory(this, sessionId, window);
     }
-    /** Release owned resources (the underlying client and any S3 client). */
+    /**
+     * Release owned resources.
+     *
+     * Accepts: nothing.
+     *
+     * Returns: nothing. Idempotent, and a no-op for a client the caller injected
+     * — that one is theirs to close.
+     *
+     * Throws: whatever a resource's own `destroy` raises — but only after every
+     * other one has been released, so a client that fails to close never strands
+     * the one behind it.
+     */
     destroy() {
-        this.context.offloader?.destroy();
-        if (this.ownsClient)
-            this.ddbClient?.destroy();
+        this.shell.release();
     }
     /**
-     * Best-effort provision an S3 lifecycle expiration rule matching the
-     * configured TTL, so offloaded objects don't outlive their DynamoDB item
-     * forever. No-ops when S3 offload or TTL isn't configured. Requires the
-     * `s3:GetLifecycleConfiguration`/`s3:PutLifecycleConfiguration` bucket-level
-     * permissions (broader than the object-level CRUD the rest of S3 offload
-     * needs) — call this once during deployment/provisioning, not per-request.
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded objects don't outlive their DynamoDB item forever.
+     *
+     * Accepts: nothing; the rule follows the configured `s3` and `ttl`. A no-op
+     * without both.
+     *
+     * Returns: nothing. Installing a rule that is already there is a no-op too.
+     *
+     * Throws: `VALIDATION` naming `s3.keyPrefix` on a rule-id collision;
+     * a classified AWS failure when the bucket's lifecycle cannot be read or written.
+     * @remarks Requires the bucket-level `s3:GetLifecycleConfiguration` /
+     * `s3:PutLifecycleConfiguration` permissions, broader than the object-level
+     * CRUD the rest of S3 offload needs — call it once during provisioning, not
+     * per request.
      */
     async ensureS3LifecycleRule() {
-        if (!this.context.offloader || !this.context.ttl)
-            return;
-        await this.context.offloader.ensureLifecycleRule((0, ttl_1.resolveTtlDaysCeil)(this.context.ttl));
+        return (0, boundary_1.guardPublic)('history.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule());
     }
 }
 exports.DynamoDBChatMessageHistory = DynamoDBChatMessageHistory;
-//# sourceMappingURL=chat-message-history.js.map

package/dist/history/internal/append.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Hides how an append of any size commits all-or-nothing, as its caller sees it.
+ *
+ * One `TransactWriteItems` carries at most a hundred items and four megabytes,
+ * so a large append is several transactions, each writing its messages and the
+ * SESSION row's update together. When one of them fails the append is rolled
+ * back: committed chunks are deleted and their effect on the SESSION row
+ * reverted, and each S3 object is released only once no row can name it. An
+ * ambiguous failure is read back before anything is undone. This is also the
+ * one module that writes a message row, which is what lets a delete pin a
+ * message row to the SESSION row's `writeId`.
+ */
+import { type RowKey } from '../../shared/dynamodb/table-schema';
+import type { SessionId, StorableMessages } from './parse';
+import { type MessageRow } from './rows';
+import { type SessionUpdateFields, type TtlAnchorResult } from './session';
+import { type HistoryContext } from './setup';
+/** One append, parsed: the session, its messages in stored form, and the session's ttl anchor. */
+export interface AppendRequest {
+    readonly sessionId: SessionId;
+    readonly messages: StorableMessages;
+    /** The session's creation-anchored ttl, when the adapter has a ttl. */
+    readonly anchor: TtlAnchorResult | undefined;
+    readonly signal?: AbortSignal;
+}
+/** Shared per-append metadata applied to every chunk's session update. */
+interface AppendFields {
+    now: string;
+    title?: string;
+    ttlTimestamp?: number;
+    forceTtlRefresh?: boolean;
+}
+/** An append cut into chunks, with the fields every chunk's SESSION update stamps. */
+export interface ChunkedAppend {
+    readonly sessionId: SessionId;
+    readonly chunks: MessageRow[][];
+    readonly fields: AppendFields;
+    readonly signal?: AbortSignal;
+}
+/** A chunk that committed, retained so it can be rolled back on a later failure. */
+interface CommittedChunk {
+    keys: RowKey[];
+    count: number;
+}
+/** How far a failed append got, which decides what its rollback undoes. */
+export interface FailedAppend {
+    readonly committed: CommittedChunk[];
+    readonly trigger: Error;
+    /** True when the failing chunk's own outcome could not be read back. */
+    readonly uncertain: boolean;
+}
+/**
+ * Append messages to a session: encode them, cut them into transactions, and
+ * commit them all or undo what committed.
+ *
+ * Accepts: `request` — the parsed session and messages, the ttl anchor, and
+ * the caller's signal.
+ *
+ * Returns: nothing, once every chunk has committed.
+ *
+ * Throws: the first chunk's failure after the append is rolled back;
+ * `COMPENSATION_FAILED` when the rollback itself fails; whatever encoding a
+ * message throws, after this call's own uploads are released.
+ */
+export declare function appendMessages(context: HistoryContext, request: AppendRequest): Promise<void>;
+/**
+ * Undo a failed batch. Always throws. S3 cleanup is split by commit status so
+ * no live row is ever left pointing at a deleted object: the never-committed
+ * suffix is cleaned immediately, the committed prefix only after its rows are
+ * confirmed deleted. If the rollback itself fails, the committed chunks' S3
+ * objects are deliberately left in place (their rows may survive) and it
+ * raises `COMPENSATION_FAILED` carrying both the trigger and the
+ * rollback error; otherwise it rethrows the trigger.
+ *
+ * `failure.uncertain` marks the failed chunk
+ * (`append.chunks[failure.committed.length]`) as one whose outcome could not be
+ * verified: its rows may be live, so its objects are leaked rather than
+ * deleted, while the never-attempted chunks after it are still cleaned.
+ *
+ * Accepts: `append` — the append that failed: its `sessionId`, its `chunks` in
+ * order, and the `fields.now` and `fields.title` its first chunk stamped on
+ * the session row. `failure.committed` — the chunks known to have landed, in
+ * order; empty means the very first chunk failed, and then the only thing to
+ * undo is the session row this call may have created. `failure.trigger` — the
+ * failure that started this. `failure.uncertain` — see above.
+ *
+ * Returns: never; the declared `Promise<never>` is the contract.
+ *
+ * Throws: `failure.trigger` when the rollback succeeded, `COMPENSATION_FAILED`
+ * when it did not.
+ *
+ * Guarantees: an object is deleted only once no row can reference it — the
+ * never-committed suffix immediately, the committed prefix only after its rows
+ * are confirmed gone, and an unverified chunk never. Storage is leaked in
+ * preference to leaving a live row pointing at a deleted object.
+ *
+ * Neither of its two log lines can stop it: both go through
+ * {@link reportStep}. Otherwise a throw from the first would skip the S3
+ * cleanup, the rollback, the count revert and the rethrow all at once, leaving
+ * every committed chunk in the table with `messageCount` still counting it,
+ * and handing the caller the logger's own error in place of the failure that
+ * started this. Announcing the rollback is not the rollback.
+ */
+export declare function compensate(context: HistoryContext, append: ChunkedAppend, failure: FailedAppend): Promise<never>;
+/**
+ * Append message chunks with caller-observed atomicity. Each chunk commits its
+ * messages and count in one transaction; if a later chunk fails, every
+ * already-committed chunk is deleted and its count reverted, and the batch's
+ * S3 objects are cleaned once their rows are gone, restoring the pre-call
+ * state before the error is rethrown. Except on a failed rollback, which
+ * surfaces as `COMPENSATION_FAILED` and deliberately leaves the
+ * committed chunks' S3 objects behind, since their rows may survive.
+ *
+ * A `RETRY_EXHAUSTED` error is ambiguous — the transaction may have committed
+ * and lost its response — so the chunk is read back first: present means it
+ * committed (continue), absent means it did not (compensate), and a failed
+ * read compensates but leaks that chunk's objects rather than delete objects
+ * its possibly-live rows reference.
+ *
+ * Accepts: `append.sessionId` — the session every chunk writes to.
+ * `append.chunks` — in order, each already within the transaction's limits;
+ * no chunks is no work and no write. `append.fields` — the session update every
+ * chunk carries. `append.signal` — aborts between chunks.
+ *
+ * Returns: nothing, and only when every chunk is known to have committed.
+ *
+ * Throws: the first chunk's failure, after the rollback has restored the
+ * pre-call state; or `COMPENSATION_FAILED` carrying both that failure
+ * and the rollback's own, when the rollback could not finish.
+ *
+ * Guarantees: each message's S3 key carries its own ULID, so no two rows of any
+ * call can address the same object and the rollback's cleanup can never delete
+ * an object a surviving row still points at. What a caller observes is
+ * all-or-nothing; what the table holds is all-or-nothing only until a rollback
+ * fails, which is why that case is a distinct error and not a rethrow.
+ */
+export declare function appendChunks(context: HistoryContext, append: ChunkedAppend): Promise<void>;
+/** Per-call retry seams (injected in tests to keep backoff instant). */
+export interface ChunkRetryOptions {
+    rng?: () => number;
+    signal?: AbortSignal;
+}
+/**
+ * Atomically write a chunk of message items together with the session-metadata
+ * count update in one {@link https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html | TransactWriteItems}
+ * call, so `messageCount` can never disagree with the messages that landed. A
+ * single `ClientRequestToken` is used per attempt so a re-sent commit (e.g.
+ * after a lost response) is idempotent and never double-applies the count
+ * `ADD`. When `fields.forceTtlRefresh` is set, the session update carries a
+ * monotonic ConditionExpression (see session.ts); if — and only if —
+ * that specific condition loses a race against a concurrent caller who just
+ * healed the same anchor, this retries the identical chunk once with
+ * `forceTtlRefresh: false` (safe: `if_not_exists` then converges to whatever
+ * already won) rather than losing the message writes to a benign ttl race. A
+ * cancellation caused by any other item (a genuine message-row conflict) is
+ * not retried here — it propagates for the normal transient-conflict retry
+ * budget inside `withDynamoDBRetry` to handle, or to the caller otherwise.
+ *
+ * Accepts: `items` — one chunk, already within the transaction's limits.
+ * `fields` — the session-metadata update accompanying it; its `indexShards` and
+ * its `writeId` are taken from the adapter's context, never from the caller.
+ * `retry.signal` — aborts between attempts.
+ *
+ * Returns: nothing. The chunk and the count are committed together or not at
+ * all.
+ *
+ * Throws: whatever the transaction throws — including a
+ * `TransactionCanceledException` for a genuine conflict, after the retry budget
+ * is spent. The caller compensates; this function never partially succeeds.
+ *
+ * Guarantees: `messageCount` can never disagree with the messages that landed,
+ * because they land in one transaction. At most one extra attempt is spent on
+ * the benign ttl race, and it carries its own request token, so a retry can
+ * never double-apply the count — and its own deadline of
+ * `MAX_WRITE_LIFETIME_MS`, so the retrying stops while that token is
+ * still deduplicating rather than after it has expired. The SESSION row's
+ * `writeId` moves if and only if a message row was added: the update travels in
+ * the same transaction as the rows, and nothing else writes it.
+ */
+export declare function writeMessageChunk(context: HistoryContext, items: MessageRow[], fields: Omit<SessionUpdateFields, 'writeId'>, retry?: ChunkRetryOptions): Promise<void>;
+/**
+ * Conservatively estimate a message row's stored size.
+ *
+ * Accepts: any message row, inline or offloaded — an offloaded one measures
+ * its S3 key, since that is what the row actually carries.
+ *
+ * Returns: an estimate at or above the real marshalled size. Erring high is the
+ * whole point: an underestimate builds a transaction DynamoDB refuses, and the
+ * cost of erring high is one extra transaction.
+ *
+ * Throws: nothing.
+ */
+export declare function estimateRowBytes(item: MessageRow): number;
+/**
+ * Split message items into transaction-sized chunks.
+ *
+ * Accepts: `items` — in order; empty yields no chunks, so an append of nothing
+ * issues no write. `maxItems` and `maxBytes` — the transaction's two limits,
+ * both binding.
+ *
+ * Returns: the chunks, in order, each within both limits — except that a single
+ * item larger than `maxBytes` is placed alone rather than dropped: refusing it
+ * here would lose a message that DynamoDB might still accept, and if it does
+ * not, the transaction says so.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: order is preserved across chunks, so messages keep the order the
+ * caller wrote them in, which is the order their ULIDs already encode.
+ */
+export declare function chunkBySize(items: MessageRow[], maxItems: number, maxBytes: number): MessageRow[][];
+export {};