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

package/dist/shared/validation/primitives.js

@@ -1,84 +1,387 @@
 "use strict";
+/**
+ * Hides the rules every caller-supplied primitive must pass.
+ *
+ * What makes a string an identifier safe inside a key, an integer a page size
+ * this package serves, and an array a copy holding only strings is decided
+ * once here. Only `parseLimit` returns a branded type of its own —
+ * `PageLimit`, which only it can build (record 21); every other rule's
+ * `parse*` form returns the plain checked value, and a feature parser brands
+ * it into its own type. Feature parsers compose these rules rather than
+ * restate them, so tightening one changes every method at once.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateNonEmptyString = validateNonEmptyString;
-exports.validateInteger = validateInteger;
-exports.validateNonEmptyArray = validateNonEmptyArray;
+exports.MAX_PAGE_LIMIT = void 0;
+exports.parseString = parseString;
+exports.assertNonEmptyString = assertNonEmptyString;
+exports.parseInteger = parseInteger;
+exports.assertInteger = assertInteger;
+exports.parseLimit = parseLimit;
+exports.parseStringArray = parseStringArray;
+exports.assertStringArray = assertStringArray;
 exports.assertNoControlChars = assertNoControlChars;
-exports.assertNoSeparator = assertNoSeparator;
-exports.validateIdentifier = validateIdentifier;
-exports.validateArrayMaxDepth = validateArrayMaxDepth;
+exports.assertWellFormed = assertWellFormed;
+exports.parseKeySegment = parseKeySegment;
+exports.parseIdentifier = parseIdentifier;
 const errors_1 = require("../errors/errors");
-/** Throw {@link ValidationError} unless `value` is a non-empty string. */
-function validateNonEmptyString(value, field) {
-    if (typeof value !== 'string' || value.length === 0) {
-        throw new errors_1.ValidationError(`${field} must be a non-empty string`, field);
+/**
+ * Largest `limit` any read accepts, on every method that takes one.
+ *
+ * Chosen from what a page costs, which is linear in `limit` and amortised
+ * nowhere: every row of a page is held decoded and resident until the whole
+ * page is handed back, and an offloaded row is an S3 GET and a decompression
+ * of its own, `readConcurrency` at a time. A page of N rows is therefore N
+ * objects held at once and, in the worst case, N round trips before the caller
+ * sees the first of them.
+ *
+ * Ten thousand is where this package already says a read has stopped being one
+ * and become an export: `MAX_TOTAL_ROWS_IN_MEMORY`
+ * (`src/shared/dynamodb/paginate.ts`) refuses to collect more than that across
+ * a whole paginated query, and `LIST_SCAN_WARN_THRESHOLD`
+ * (`src/shared/dynamodb/paginate.ts`) tells an operator about a listing that
+ * walks that far. A single page allowed past either would hold more than every
+ * other path in the package may. Its own literal at the same value rather than
+ * an alias of them, for the reason `LIST_SCAN_WARN_THRESHOLD`
+ * (`src/shared/dynamodb/paginate.ts`) records.
+ *
+ * What it does *not* do is promise a memory figure: rows are the caller's own
+ * data, so ten thousand session summaries are a few megabytes while a hundred
+ * items at `MAX_INLINE_PAYLOAD_BYTES` (`src/shared/codec/codec.ts`) are forty.
+ * It bounds a typo — a `1e12` that would otherwise resolve — not a working set.
+ *
+ * What a caller loses at the ceiling is one large page, never the rows: every
+ * bounded read has a way to continue — `listSessions` a cursor, `search` an
+ * `offset`, `getMessages` a `before`, and `saver.list` streams and never
+ * accumulates — so an answer larger than this is paid for as pages.
+ */
+exports.MAX_PAGE_LIMIT = 10_000;
+/**
+ * The value as a string, or a refusal.
+ *
+ * Accepts: `value` — anything. A JavaScript caller, or a TypeScript caller
+ * whose input came from JSON, can pass any type where a string is declared, and
+ * every rule after this one reaches a string method.
+ *
+ * Returns: `value`, typed as the string it was checked to be.
+ *
+ * Throws: `VALIDATION` naming `field`, for anything that is not a string.
+ */
+function parseString(value, field) {
+    if (typeof value !== 'string') {
+        throw (0, errors_1.validationError)(`${field} must be a string`, field);
     }
+    return value;
 }
-/** Throw {@link ValidationError} unless `value` is an integer within bounds. */
-function validateInteger(value, field, bounds = {}) {
+/**
+ * The value as a string holding at least one non-whitespace character.
+ *
+ * Accepts: `value` — anything; `''` and whitespace-only are refused alongside
+ * non-strings.
+ *
+ * Returns: `value`, typed as a string.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ */
+function parseNonBlankString(value, field) {
+    const text = parseString(value, field);
+    if (text.trim().length === 0) {
+        throw (0, errors_1.validationError)(`${field} must be a non-empty string (whitespace-only counts as empty)`, field);
+    }
+    return text;
+}
+/**
+ * Throw `VALIDATION` unless `value` is a string holding at least one
+ * non-whitespace character.
+ *
+ * Accepts: `value` — any type; `''` and whitespace-only are rejected alongside
+ * non-strings. `field` — the option or identifier name carried on the error.
+ * The rule is {@link parseNonBlankString}'s; this form is for a value the
+ * caller keeps under its declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ */
+function assertNonEmptyString(value, field) {
+    parseNonBlankString(value, field);
+}
+/** Throw `VALIDATION` unless `value` encodes to at most `maxBytes` of UTF-8. */
+function assertMaxBytes(value, field, maxBytes) {
+    parseString(value, field);
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes > maxBytes) {
+        throw (0, errors_1.validationError)(`${field} must be at most ${maxBytes} bytes of UTF-8 (received ${bytes})`, field);
+    }
+}
+/**
+ * The value as an integer inside `bounds`.
+ *
+ * Accepts: `value` — anything; a non-number, a fraction, `NaN` and `Infinity`
+ * are all refused by the integer rule. `bounds` — omitted or `{}` bounds
+ * nothing; `min` and `max` are inclusive.
+ *
+ * Returns: `value`, typed as a number.
+ *
+ * Throws: `VALIDATION` naming `field`; the integer rule is reported before
+ * either bound.
+ */
+function parseInteger(value, field, bounds = {}) {
     if (typeof value !== 'number' || !Number.isInteger(value)) {
-        throw new errors_1.ValidationError(`${field} must be an integer`, field);
+        throw (0, errors_1.validationError)(`${field} must be an integer`, field);
     }
     if (bounds.min !== undefined && value < bounds.min) {
-        throw new errors_1.ValidationError(`${field} must be >= ${bounds.min}`, field);
+        throw (0, errors_1.validationError)(`${field} must be >= ${bounds.min}`, field);
     }
     if (bounds.max !== undefined && value > bounds.max) {
-        throw new errors_1.ValidationError(`${field} must be <= ${bounds.max}`, field);
+        throw (0, errors_1.validationError)(`${field} must be <= ${bounds.max}`, field);
     }
+    return value;
+}
+/**
+ * Throw `VALIDATION` unless `value` is an integer inside `bounds`.
+ *
+ * Accepts: `value` — any type; a non-number, a fraction, `NaN` and `Infinity`
+ * are all rejected by the integer rule. `bounds` — omitted or `{}` bounds
+ * nothing, `min` and `max` are inclusive and may be given together or alone.
+ * The rule is {@link parseInteger}'s; this form is for a value the caller
+ * keeps under its declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`; the integer rule is reported before
+ * either bound.
+ */
+function assertInteger(value, field, bounds = {}) {
+    parseInteger(value, field, bounds);
+}
+/**
+ * The value as a page size this package will serve: an integer from `min` to
+ * {@link MAX_PAGE_LIMIT}.
+ *
+ * One rule for every `limit` a public method takes. Without it they would
+ * disagree three ways — no minimum on `saver.list`, so `limit: -1` would
+ * resolve; `0` refused by the history reads and accepted by the store — and
+ * none would have a ceiling, so `limit: 1e12` would resolve on five methods.
+ * The same mistake would be answered differently depending on which method a
+ * caller happened to reach for.
+ *
+ * What survives that unification is one message shape, one ceiling and two
+ * floors, because zero does not ask for the same thing on every method. A zero
+ * *page* is answered: the caller asked a listing for nothing, holds the empty
+ * array it returned, and can see that is what it got. A zero *conversation
+ * window* is refused: it feeds a model rather than a caller, an empty
+ * conversation is indistinguishable from one that never happened, and the
+ * answer the model gives is persisted as the transcript. So every call site
+ * passes its floor and says why; `1` is passed from exactly one place,
+ * `parseMessageWindow` in `src/history/internal/parse.ts`, which is the
+ * check behind `history.getMessages` and `history.forSession` alike.
+ *
+ * Accepts: `value` — any type; a non-number, a fraction, `NaN` and `Infinity`
+ * are all rejected by the integer rule. `min` — `0` where an empty result is a
+ * request the call site answers without issuing a read, `1` where an empty
+ * result would be mistaken for an empty conversation. A negative value is
+ * refused at either floor rather than read as zero: it is a page size that was
+ * computed, and the computation went wrong.
+ *
+ * Returns: `value` as a {@link PageLimit}.
+ *
+ * Throws: `VALIDATION` naming `limit`, quoting the bound broken — the floor
+ * or {@link MAX_PAGE_LIMIT} — so the caller is told what the rule is rather
+ * than only that it has one.
+ */
+function parseLimit(value, min) {
+    return parseInteger(value, 'limit', { min, max: exports.MAX_PAGE_LIMIT });
 }
-/** Throw {@link ValidationError} unless `value` is a non-empty array. */
-function validateNonEmptyArray(value, field) {
-    if (!Array.isArray(value) || value.length === 0) {
-        throw new errors_1.ValidationError(`${field} must be a non-empty array`, field);
+/**
+ * The value as an array of strings, copied.
+ *
+ * Accepts: `value` — anything; a non-array is refused, as is an array holding
+ * anything but a string. An empty array is valid.
+ *
+ * Returns: a copy of `value`, so a caller changing its own array afterwards
+ * changes nothing this package acts on.
+ *
+ * Throws: `VALIDATION` naming `field`, its message identifying the offending
+ * index. Walked by position rather than `Array.prototype.some`, which skips a
+ * hole in a sparse array instead of visiting it, and copied by position rather
+ * than `Array.prototype.slice`, which carries a hole forward instead of
+ * filling it: unchecked, a hole passed as a string and reached a caller who
+ * declared `string[]`.
+ */
+function parseStringArray(value, field) {
+    if (!Array.isArray(value)) {
+        throw (0, errors_1.validationError)(`${field} must be an array of strings`, field);
+    }
+    const result = [];
+    for (let index = 0; index < value.length; index += 1) {
+        const item = value[index];
+        if (typeof item !== 'string') {
+            throw (0, errors_1.validationError)(`${field}[${index}] must be a string`, field);
+        }
+        result.push(item);
     }
+    return result;
 }
-/** Return `true` if `value` contains any ASCII control character. */
+/**
+ * Throw `VALIDATION` unless `value` is an array of strings.
+ *
+ * Accepts: `value` — declared `readonly string[]` for a caller whose types
+ * hold; a non-array is rejected, as is an array holding anything but a
+ * string. An empty array is valid. The rule is {@link parseStringArray}'s;
+ * this form is for a value the caller keeps under its declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ */
+function assertStringArray(value, field) {
+    parseStringArray(value, field);
+}
+/** True when `value` holds a C0 control character, DEL, or a C1 control character. */
 function hasControlChar(value) {
     for (let i = 0; i < value.length; i++) {
         const code = value.charCodeAt(i);
-        if (code <= 0x1f || code === 0x7f) {
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
             return true;
-        }
     }
     return false;
 }
-/** Throw {@link ValidationError} if `value` contains an ASCII control character. */
+/**
+ * Throw `VALIDATION` unless `value` is free of control characters.
+ *
+ * Accepts: `value` — any type, non-strings rejected first by
+ * {@link parseString}. Rejected code points are C0 (`U+0000`–`U+001F`), DEL
+ * (`U+007F`) and C1 (`U+0080`–`U+009F`). The rule is this function's own:
+ * {@link parseKeySegment} applies it to every key segment and identifier by
+ * calling this one, and this form serves a value the caller keeps under its
+ * declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ *
+ * Guarantees: an accepted value cannot terminate a log line or open a terminal
+ * escape sequence — neither `ESC` (`U+001B`) nor the single-byte `CSI`
+ * (`U+009B`) survives this rule. Identifiers are written into log lines by this
+ * package, and unneutralised output is CWE-117
+ * (https://cwe.mitre.org/data/definitions/117.html).
+ */
 function assertNoControlChars(value, field) {
+    parseString(value, field);
     if (hasControlChar(value)) {
-        throw new errors_1.ValidationError(`${field} must not contain control characters`, field);
+        throw (0, errors_1.validationError)(`${field} must not contain control characters`, field);
+    }
+}
+/**
+ * Throw `VALIDATION` unless every surrogate in `value` is part of a
+ * pair.
+ *
+ * Accepts: `value` — any type, non-strings rejected first by
+ * {@link parseString}. The rule is this function's own:
+ * {@link parseKeySegment} applies it to every key segment and identifier by
+ * calling this one, and this form serves a value the caller keeps under its
+ * declared type.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ *
+ * Guarantees: the mapping from an accepted value to its UTF-8 encoding is
+ * injective. `Buffer.from(value, 'utf8')` replaces a lone surrogate with
+ * U+FFFD, so two values differing only there would encode identically and,
+ * where that encoding is a storage key, address one object.
+ */
+function assertWellFormed(value, field) {
+    parseString(value, field);
+    if (!value.isWellFormed()) {
+        throw (0, errors_1.validationError)(`${field} must be well-formed UTF-16 (it contains an unpaired surrogate, which does not ` +
+            'survive encoding to UTF-8)', field);
     }
 }
-/** Throw {@link ValidationError} if `value` contains the reserved `separator`. */
+/** Throw `VALIDATION` if `value` contains `separator`. */
 function assertNoSeparator(value, separator, field) {
+    parseString(value, field);
     if (value.includes(separator)) {
-        throw new errors_1.ValidationError(`${field} must not contain the reserved "${separator}" separator`, field);
+        throw (0, errors_1.validationError)(`${field} must not contain the reserved "${separator}" separator`, field);
     }
 }
 /**
- * Validate a caller-supplied identifier that reaches a DynamoDB key: non-empty,
- * free of the reserved `separator`, and free of control characters. The last
- * rule matters even though DynamoDB itself accepts control characters — an
- * identifier is echoed into logs, so an unvalidated ANSI escape is a
- * log/terminal-injection surface for any app that writes these values out.
+ * One segment of a key, which may be empty: every rule of
+ * {@link parseIdentifier} except non-blank. The checkpoint namespace is the one
+ * such value — `''` *is* the root namespace — and it is still a segment of both
+ * the sort key and the offloaded object's key, so a lone surrogate or a control
+ * character in it is as damaging as in any other.
+ *
+ * Accepts: `value` — anything. `separator`, `field`, `maxBytes` — as
+ * {@link parseIdentifier}.
+ *
+ * Returns: `value`, typed as a string.
+ *
+ * Throws: `VALIDATION` naming `field`, in this order: string, at most
+ * `maxBytes` of UTF-8, free of `separator`, free of control characters,
+ * well-formed UTF-16.
  */
-function validateIdentifier(value, separator, field) {
-    validateNonEmptyString(value, field);
-    assertNoSeparator(value, separator, field);
-    assertNoControlChars(value, field);
+function parseKeySegment(value, separator, field, maxBytes) {
+    const text = parseString(value, field);
+    assertMaxBytes(text, field, maxBytes);
+    assertNoSeparator(text, separator, field);
+    assertNoControlChars(text, field);
+    assertWellFormed(text, field);
+    return text;
 }
-/** Throw {@link ValidationError} if nested-array depth exceeds `maxDepth`. */
-function validateArrayMaxDepth(value, field, maxDepth) {
-    const depthOf = (node, depth) => {
-        if (!Array.isArray(node)) {
-            return depth;
-        }
-        if (depth > maxDepth) {
-            return depth;
-        }
-        return node.reduce((max, child) => Math.max(max, depthOf(child, depth + 1)), depth);
-    };
-    if (depthOf(value, 0) > maxDepth) {
-        throw new errors_1.ValidationError(`${field} exceeds maximum array depth of ${maxDepth}`, field);
-    }
+/**
+ * The value as a caller-supplied identifier that reaches a DynamoDB key or an
+ * S3 object key, checked.
+ *
+ * Accepts: `value` — any type. `separator`, `field`, `maxBytes` — as the rules
+ * below.
+ *
+ * Returns: `value`, typed as a string. The caller's parser brands it.
+ *
+ * Throws: `VALIDATION` naming `field`. The rules apply in this order, and
+ * the order is part of the contract because a caller branches on which one
+ * failed: string, non-blank, at most `maxBytes` of UTF-8, free of `separator`,
+ * free of control characters, well-formed UTF-16.
+ *
+ * Guarantees: every guarantee of {@link assertNoControlChars} and
+ * {@link assertWellFormed} holds for an accepted value, and it composes into a
+ * key segment without escaping.
+ *
+ * Not guaranteed, and deliberately so: an accepted identifier is **not**
+ * normalised, and Unicode format characters (`Cf` — `U+200B` ZERO WIDTH SPACE,
+ * `U+200C`/`U+200D` the zero-width non-joiner and joiner, `U+FEFF`, `U+202E`
+ * RIGHT-TO-LEFT OVERRIDE) and the separators `U+2028`/`U+2029` are all
+ * accepted. Two facts make that safe, and one makes it necessary.
+ *
+ * It is safe because none of them can produce a collision. DynamoDB orders and
+ * compares strings by their UTF-8 bytes, and {@link assertWellFormed} has
+ * already made the mapping from an accepted identifier to those bytes
+ * injective — so two identifiers differing anywhere address two different
+ * rows. An identifier that reaches an S3 key is base64url-encoded on the way
+ * (`encodeKeyPart`), so none of these characters appears in a key at all. What
+ * one actually costs is a log line, a terminal or a console that renders two
+ * distinct identifiers alike: confusion for a reader, not a row either of them
+ * can reach. Terminal escapes and line breaks, which *are* an injection rather
+ * than a rendering, are refused by {@link assertNoControlChars}.
+ *
+ * It is necessary because refusing `Cf` would refuse ordinary text rather than
+ * hostile text. `U+200C` and `U+200D` carry meaning in Persian, Hindi and the
+ * Indic scripts — the Persian for "goes" is spelled with a `U+200C` — and
+ * `U+200D` is what joins the code points of every multi-person emoji. A rule
+ * against `Cf` would reject a `thread_id` or a store `key` taken from ordinary
+ * user text, in a package whose identifiers are the caller's own.
+ *
+ * Normalising would be worse than breaking: `NFC` folds `e` + `U+0301` onto
+ * `U+00E9`, so a row written under one form would afterwards be addressed
+ * under the other and the caller's data would stop being found. That is silent
+ * loss on upgrade, bought with a rendering nicety. A caller who wants either
+ * rule can apply it to its own identifiers before passing them.
+ */
+function parseIdentifier(value, separator, field, maxBytes) {
+    return parseKeySegment(parseNonBlankString(value, field), separator, field, maxBytes);
 }
-//# sourceMappingURL=primitives.js.map

package/dist/shared/validation/ttl.d.ts

@@ -1,21 +1,77 @@
+/**
+ * Hides how a `ttl` option becomes an expiry.
+ *
+ * A caller gives days or seconds. The one-unit rule, the five-year cap, the
+ * epoch second DynamoDB's TTL attribute takes, and the S3 lifecycle days that
+ * keep an offloaded object alive past its row's sweep lag are all derived
+ * here, so the two spellings of the `ttl` option are accepted or rejected
+ * alike and no reader re-derives one unit from the other itself. A stored
+ * row's own epoch-second `ttl` is converted to milliseconds for `Date` where
+ * that row is read, not here.
+ */
+/** Maximum TTL expressed in days (5 years). */
+export declare const MAX_TTL_DAYS: number;
+/** Maximum TTL expressed in seconds: the same five years as {@link MAX_TTL_DAYS}. */
+export declare const MAX_TTL_SECONDS: number;
+/**
+ * Extra days an S3 lifecycle rule adds over the TTL it backs. DynamoDB's TTL
+ * sweep can lag up to ~48 h past the `ttl` timestamp; the offloaded object
+ * must outlive its row, never the other way round.
+ */
+export declare const S3_LIFECYCLE_SWEEP_MARGIN_DAYS = 2;
 /** Time-to-live expressed in whole days or whole seconds. */
 export type TtlOption = {
     days: number;
 } | {
     seconds: number;
 };
-/** Validate a {@link TtlOption} and resolve it to a positive number of seconds. */
+/**
+ * A {@link TtlOption} resolved to a positive number of seconds.
+ *
+ * Accepts: `ttl` — declared as the two-shape union; a JavaScript caller, or a
+ * config built from JSON, can also reach `undefined`, a non-object, `{}`, an
+ * object carrying both keys and one carrying any other key, and each is
+ * rejected. Within a shape the value must be an integer of at least 1.
+ *
+ * Returns: whole seconds, `days × 86400` for the days form.
+ *
+ * Throws: `VALIDATION`, in this order, naming `ttl` for a value that is not
+ * an object, `ttl.<key>` for a key other than `days` or `seconds`, `ttl` for
+ * an object naming neither unit or both, and `ttl.days` or `ttl.seconds` for a
+ * value outside 1..five years. Both forms share that cap, so the two spellings
+ * of one duration are accepted or rejected alike.
+ */
 export declare function resolveTtlSeconds(ttl: TtlOption): number;
 /**
- * Resolve a {@link TtlOption} into a DynamoDB TTL attribute value: the Unix
- * epoch (seconds) at which the item expires.
+ * The value DynamoDB's TTL attribute takes for an item written now: the Unix
+ * epoch second at which it expires.
+ *
+ * Accepts: `ttl` — as {@link resolveTtlSeconds}. `now` — a clock returning
+ * epoch **milliseconds**, defaulting to `Date.now`; supplied by tests and by
+ * the adapters' clock seam.
+ *
+ * Returns: `floor(now() / 1000) + resolveTtlSeconds(ttl)`. Whole seconds,
+ * because DynamoDB reads the attribute as an epoch-second Number
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/time-to-live-ttl-before-you-start.html).
  *
- * @param now - Clock seam returning epoch milliseconds. Defaults to `Date.now`.
+ * Throws: whatever {@link resolveTtlSeconds} throws.
  */
 export declare function calculateTtlTimestamp(ttl: TtlOption, now?: () => number): number;
-/** Resolve a {@link TtlOption} to whole days, rounded up so the S3 lifecycle
- * expiration never fires before DynamoDB's own TTL sweep (which can lag up
- * to ~48h past the TTL timestamp) — expiring the S3 object first would leave
- * a live DynamoDB item pointing at a deleted payload. */
-export declare function resolveTtlDaysCeil(ttl: TtlOption): number;
-//# sourceMappingURL=ttl.d.ts.map
+/**
+ * The `Days` of the S3 lifecycle expiration rule that backs a TTL.
+ *
+ * Accepts: `ttl` — as {@link resolveTtlSeconds}.
+ *
+ * Returns: the TTL rounded **up** to whole days plus
+ * {@link S3_LIFECYCLE_SWEEP_MARGIN_DAYS}, so always at least
+ * `1 + margin`.
+ *
+ * Throws: whatever {@link resolveTtlSeconds} throws.
+ *
+ * Guarantees: the object outlives the row that points at it. S3 expires an
+ * object at the first midnight UTC at least `Days` after creation, while
+ * DynamoDB may keep an expired item for up to 48 hours past its `ttl`
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/howitworks-ttl.html);
+ * the margin covers that lag, which a bare `{ days: N }` did not.
+ */
+export declare function lifecycleExpirationDays(ttl: TtlOption): number;