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

package/dist/shared/logging/secret-patterns.d.ts

@@ -1,22 +1,74 @@
 /** Marker substituted for anything recognised as secret. */
 export declare const REDACTED = "[REDACTED]";
-/** Key names (matched case-insensitively as substrings) whose value is a secret. */
+/**
+ * Key names whose value is a secret. Each entry is a *normalised* name — see
+ * {@link normaliseKey} — and matches a key whose normalised form equals it or
+ * ends with it. Suffix matching is what catches `secretAccessKey`, `x-api-key`,
+ * `client_secret` and `AUTH_TOKEN`; requiring the pattern to be a suffix, not a
+ * substring, is what spares `maxTokens`, `total_tokens`, `tokenizer` and
+ * `secretary`, which the old substring rule redacted.
+ */
 export declare const DEFAULT_SECRET_KEY_PATTERNS: readonly string[];
+/**
+ * Canonical form of a key name for matching: lower-case with every character
+ * that is not a letter or digit removed, so `api_key`, `x-api-key`, `ApiKey`
+ * and `API KEY` all become `apikey`.
+ */
+export declare function normaliseKey(key: string): string;
 /**
  * Secret shapes recognisable in free text, where key-name matching cannot
  * reach: an error's `message`/`stack`, or any other string value. Deliberately
  * high-confidence — each pattern describes a credential *format* rather than a
  * word that merely sounds sensitive — so ordinary operational text survives
  * redaction unchanged.
+ *
+ * The credential-pair pattern (last) tolerates a **closing quote after the
+ * keyword**, because that is what `JSON.stringify` produces
+ * (`{"password":"…"}`) and requiring the separator to follow the bare keyword
+ * matched nothing at all there — a silent, complete bypass on the single most
+ * common shape a downstream HTTP error arrives in. Its group 1 is the keyword
+ * and separator, preserved by {@link redactText}.
+ *
+ * Its value side tries three shapes, and their order is load-bearing:
+ * 1. a fully-quoted span that consumes escapes, so `{"password":"a\"b"}` is
+ *    redacted whole. Ending the span at the escaped quote stopped the
+ *    redaction short and printed the rest of the secret verbatim.
+ * 2. an unquoted JSON scalar — number, `true`, `false`, `null` — required to
+ *    end at a real delimiter — `,`, `}`, `]` or end of input, optionally
+ *    preceded by whitespace. Without this alternative,
+ *    `{"apiKey":123,"region":"us-east-1"}` fell through to the fallback below,
+ *    which then destroyed every sibling field after the secret. The lookahead
+ *    is what stops the alternative truncating a value it does not fully
+ *    describe, such as `token=123abc`, and leaking the tail it left behind.
+ *    Whitespace alone does not end a scalar: treating a space as a delimiter
+ *    made `api_key: 5 items` redact to `api_key: [REDACTED] items`, which
+ *    reads as a partial redaction of a value the pattern never described.
+ * 3. the rest of the line, so a multi-word secret is redacted whole instead of
+ *    up to its first space. Trying the two precise shapes first is what keeps
+ *    this fallback from over-redacting sibling JSON fields.
  */
 export declare const DEFAULT_SECRET_VALUE_PATTERNS: readonly RegExp[];
-/** True when `key` matches any secret-key pattern. */
+/** True when `key`'s normalised form equals or ends with any (normalised) pattern. */
 export declare function isSecretKey(key: string, patterns: readonly string[]): boolean;
+/**
+ * An error's message with recognised credential shapes redacted, for embedding
+ * in another error's message: a wrapper that quotes its cause must not leak a
+ * `password=` or token the cause happened to carry.
+ */
+export declare function redactedMessage(error: Error): string;
 /**
  * Replace every recognised secret shape inside `value` with {@link REDACTED},
  * leaving the surrounding text intact so a redacted message stays readable.
  * Each pattern is rebuilt per call so a `g` flag's `lastIndex` never leaks
  * between invocations.
+ *
+ * A pattern may capture a leading group it wants **preserved**: only the rest
+ * of the match is replaced, which is what keeps `apiKey=[REDACTED]` saying
+ * which field was redacted instead of collapsing to a bare marker. A pattern
+ * with no group is replaced whole, as before. `String.prototype.replace`
+ * passes the match *offset* — a number — as the second callback argument when
+ * the pattern has no group, hence the `typeof` test rather than an
+ * `undefined` check.
  */
 export declare function redactText(value: string, patterns: readonly RegExp[]): string;
 /**
@@ -38,4 +90,3 @@ export interface RedactedErrorText {
  * rebuilding it so the secret cannot escape.
  */
 export declare function redactErrorText(error: Error, patterns: readonly RegExp[]): RedactedErrorText;
-//# sourceMappingURL=secret-patterns.d.ts.map

package/dist/shared/logging/secret-patterns.js

@@ -1,52 +1,112 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_SECRET_VALUE_PATTERNS = exports.DEFAULT_SECRET_KEY_PATTERNS = exports.REDACTED = void 0;
+exports.normaliseKey = normaliseKey;
 exports.isSecretKey = isSecretKey;
+exports.redactedMessage = redactedMessage;
 exports.redactText = redactText;
 exports.binaryLabel = binaryLabel;
 exports.redactErrorText = redactErrorText;
 /** Marker substituted for anything recognised as secret. */
 exports.REDACTED = '[REDACTED]';
-/** Key names (matched case-insensitively as substrings) whose value is a secret. */
+/**
+ * Key names whose value is a secret. Each entry is a *normalised* name — see
+ * {@link normaliseKey} — and matches a key whose normalised form equals it or
+ * ends with it. Suffix matching is what catches `secretAccessKey`, `x-api-key`,
+ * `client_secret` and `AUTH_TOKEN`; requiring the pattern to be a suffix, not a
+ * substring, is what spares `maxTokens`, `total_tokens`, `tokenizer` and
+ * `secretary`, which the old substring rule redacted.
+ */
 exports.DEFAULT_SECRET_KEY_PATTERNS = [
     'accesskey',
-    'secretkey',
+    'accesskeyid',
     'secret',
     'sessiontoken',
     'securitytoken',
     'authorization',
     'password',
+    'passwd',
+    'passphrase',
     'apikey',
     'bearer',
     'token',
     'privatekey',
 ];
+/**
+ * Canonical form of a key name for matching: lower-case with every character
+ * that is not a letter or digit removed, so `api_key`, `x-api-key`, `ApiKey`
+ * and `API KEY` all become `apikey`.
+ */
+function normaliseKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
 /**
  * Secret shapes recognisable in free text, where key-name matching cannot
  * reach: an error's `message`/`stack`, or any other string value. Deliberately
  * high-confidence — each pattern describes a credential *format* rather than a
  * word that merely sounds sensitive — so ordinary operational text survives
  * redaction unchanged.
+ *
+ * The credential-pair pattern (last) tolerates a **closing quote after the
+ * keyword**, because that is what `JSON.stringify` produces
+ * (`{"password":"…"}`) and requiring the separator to follow the bare keyword
+ * matched nothing at all there — a silent, complete bypass on the single most
+ * common shape a downstream HTTP error arrives in. Its group 1 is the keyword
+ * and separator, preserved by {@link redactText}.
+ *
+ * Its value side tries three shapes, and their order is load-bearing:
+ * 1. a fully-quoted span that consumes escapes, so `{"password":"a\"b"}` is
+ *    redacted whole. Ending the span at the escaped quote stopped the
+ *    redaction short and printed the rest of the secret verbatim.
+ * 2. an unquoted JSON scalar — number, `true`, `false`, `null` — required to
+ *    end at a real delimiter — `,`, `}`, `]` or end of input, optionally
+ *    preceded by whitespace. Without this alternative,
+ *    `{"apiKey":123,"region":"us-east-1"}` fell through to the fallback below,
+ *    which then destroyed every sibling field after the secret. The lookahead
+ *    is what stops the alternative truncating a value it does not fully
+ *    describe, such as `token=123abc`, and leaking the tail it left behind.
+ *    Whitespace alone does not end a scalar: treating a space as a delimiter
+ *    made `api_key: 5 items` redact to `api_key: [REDACTED] items`, which
+ *    reads as a partial redaction of a value the pattern never described.
+ * 3. the rest of the line, so a multi-word secret is redacted whole instead of
+ *    up to its first space. Trying the two precise shapes first is what keeps
+ *    this fallback from over-redacting sibling JSON fields.
  */
 exports.DEFAULT_SECRET_VALUE_PATTERNS = [
     /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
     /\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi,
     /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
-    /(?:aws_)?(?:secret_access_key|secretaccesskey|password|passwd|api_?key|token)\s*[=:]\s*\S+/gi,
+    /((?:aws_)?(?:secret_access_key|secretaccesskey|password|passwd|api_?key|token)["']?\s*[=:]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|(?:-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)(?=\s*[,}\]]|\s*$)|[^\r\n]+)/gi,
 ];
-/** True when `key` matches any secret-key pattern. */
+/** True when `key`'s normalised form equals or ends with any (normalised) pattern. */
 function isSecretKey(key, patterns) {
-    const lower = key.toLowerCase();
-    return patterns.some((pattern) => lower.includes(pattern));
+    const normalised = normaliseKey(key);
+    return patterns.some((pattern) => normalised === pattern || normalised.endsWith(pattern));
+}
+/**
+ * An error's message with recognised credential shapes redacted, for embedding
+ * in another error's message: a wrapper that quotes its cause must not leak a
+ * `password=` or token the cause happened to carry.
+ */
+function redactedMessage(error) {
+    return redactText(error.message, exports.DEFAULT_SECRET_VALUE_PATTERNS);
 }
 /**
  * Replace every recognised secret shape inside `value` with {@link REDACTED},
  * leaving the surrounding text intact so a redacted message stays readable.
  * Each pattern is rebuilt per call so a `g` flag's `lastIndex` never leaks
  * between invocations.
+ *
+ * A pattern may capture a leading group it wants **preserved**: only the rest
+ * of the match is replaced, which is what keeps `apiKey=[REDACTED]` saying
+ * which field was redacted instead of collapsing to a bare marker. A pattern
+ * with no group is replaced whole, as before. `String.prototype.replace`
+ * passes the match *offset* — a number — as the second callback argument when
+ * the pattern has no group, hence the `typeof` test rather than an
+ * `undefined` check.
  */
 function redactText(value, patterns) {
-    return patterns.reduce((text, pattern) => text.replace(new RegExp(pattern.source, pattern.flags), exports.REDACTED), value);
+    return patterns.reduce((text, pattern) => text.replace(new RegExp(pattern.source, pattern.flags), (_match, prefix) => typeof prefix === 'string' ? `${prefix}${exports.REDACTED}` : exports.REDACTED), value);
 }
 /**
  * A short label for a binary view. Recursing one would explode it into a
@@ -71,4 +131,3 @@ function redactErrorText(error, patterns) {
         changed: message !== error.message || stack !== error.stack,
     };
 }
-//# sourceMappingURL=secret-patterns.js.map

package/dist/shared/options.d.ts

@@ -1,7 +1,8 @@
-import type { DynamoDBClient, DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
 import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import type { CompressionConfig } from './codec/compression';
 import type { S3OffloadConfig } from './codec/s3/config';
+import type { RetryPolicy } from './dynamodb/retry-policy';
 import type { Logger } from './logging/logger';
 import type { TtlOption } from './validation/ttl';
 /**
@@ -15,12 +16,12 @@ export interface BaseAdapterOptions {
     client?: DynamoDBDocument;
     /** Config used to build a client when `client` is not provided. */
     clientConfig?: DynamoDBClientConfig;
-    /** Factory seam for constructing the underlying client (testing). */
-    createClient?: (config: DynamoDBClientConfig) => DynamoDBClient;
     /** Optional time-to-live applied to written items. */
     ttl?: TtlOption;
     /** Optional per-instance logger (defaults to a silent logger). */
     logger?: Logger;
+    /** Retry budget and backoff for every DynamoDB call (see the README "Retries and backoff"). */
+    retry?: RetryPolicy;
 }
 /** Options enabling payload compression and/or S3 offloading. */
 export interface CodecOptions {
@@ -29,4 +30,8 @@ export interface CodecOptions {
     /** S3 offload configuration for payloads over DynamoDB's item limit. */
     s3?: S3OffloadConfig;
 }
-//# sourceMappingURL=options.d.ts.map
+/** Per-call cancellation for the long-running adapter methods. */
+export interface CancelOptions {
+    /** Aborting it rejects the call with `AbortError` (`ABORTED`) at the next wait. */
+    signal?: AbortSignal;
+}

package/dist/shared/options.js

@@ -1,3 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=options.js.map

package/dist/shared/ulid.d.ts

@@ -1,10 +1,23 @@
+/**
+ * A CSPRNG-backed `rng` seam: uniform values in `[0, 1)` from `crypto.randomBytes`,
+ * drawn from a refilled pool so a burst of ids costs one syscall per 256
+ * digits rather than one per digit. `Math.random` is fine for uniqueness and
+ * ordering but is not a cryptographically secure source, which security
+ * baselines flag in identifier generation; the ULID spec recommends a CSPRNG.
+ */
+export declare function secureRng(): () => number;
+/**
+ * The 10 time characters every ULID generated at `timeMs` starts with. Used
+ * as a sort-key bound: every id from that millisecond onwards sorts at or
+ * after it, every earlier id before it.
+ */
+export declare function ulidTimePrefix(timeMs: number): string;
 /**
  * Build a monotonic ULID generator: lexicographically sortable 26-char ids
  * whose first 10 chars encode the millisecond timestamp. Ids strictly increase
  * even when the clock regresses or the same-millisecond random space overflows:
  * any non-advancing clock reuses the last timestamp and increments the random
  * component, carrying into the timestamp on overflow. `now`/`rng` are seams for
- * deterministic tests.
+ * deterministic tests; the default `rng` is {@link secureRng}.
  */
 export declare function createUlidFactory(now?: () => number, rng?: () => number): () => string;
-//# sourceMappingURL=ulid.d.ts.map

package/dist/shared/ulid.js

@@ -1,10 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.secureRng = secureRng;
+exports.ulidTimePrefix = ulidTimePrefix;
 exports.createUlidFactory = createUlidFactory;
+const node_crypto_1 = require("node:crypto");
 const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
 const ENCODING_LEN = 32;
 const TIME_CHARS = 10;
 const RANDOM_CHARS = 16;
+/** Bytes drawn per refill of the {@link secureRng} pool: 16 ids per syscall. */
+const RNG_POOL_BYTES = 256;
+/**
+ * A CSPRNG-backed `rng` seam: uniform values in `[0, 1)` from `crypto.randomBytes`,
+ * drawn from a refilled pool so a burst of ids costs one syscall per 256
+ * digits rather than one per digit. `Math.random` is fine for uniqueness and
+ * ordering but is not a cryptographically secure source, which security
+ * baselines flag in identifier generation; the ULID spec recommends a CSPRNG.
+ */
+function secureRng() {
+    let pool = Buffer.alloc(0);
+    let offset = 0;
+    return () => {
+        if (offset >= pool.length) {
+            pool = (0, node_crypto_1.randomBytes)(RNG_POOL_BYTES);
+            offset = 0;
+        }
+        const byte = pool[offset];
+        offset += 1;
+        return byte / 256;
+    };
+}
 function encodeTime(timeMs) {
     let remaining = Math.floor(timeMs);
     let out = '';
@@ -14,6 +39,14 @@ function encodeTime(timeMs) {
     }
     return out;
 }
+/**
+ * The 10 time characters every ULID generated at `timeMs` starts with. Used
+ * as a sort-key bound: every id from that millisecond onwards sorts at or
+ * after it, every earlier id before it.
+ */
+function ulidTimePrefix(timeMs) {
+    return encodeTime(timeMs);
+}
 function randomDigits(rng) {
     const digits = [];
     for (let i = 0; i < RANDOM_CHARS; i++) {
@@ -38,9 +71,9 @@ function incrementDigits(digits) {
  * even when the clock regresses or the same-millisecond random space overflows:
  * any non-advancing clock reuses the last timestamp and increments the random
  * component, carrying into the timestamp on overflow. `now`/`rng` are seams for
- * deterministic tests.
+ * deterministic tests; the default `rng` is {@link secureRng}.
  */
-function createUlidFactory(now = Date.now, rng = Math.random) {
+function createUlidFactory(now = Date.now, rng = secureRng()) {
     let lastTime = -1;
     let lastRandom = [];
     return () => {
@@ -62,4 +95,3 @@ function createUlidFactory(now = Date.now, rng = Math.random) {
         return encodeTime(lastTime) + lastRandom.map((digit) => ENCODING[digit]).join('');
     };
 }
-//# sourceMappingURL=ulid.js.map

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

@@ -0,0 +1,8 @@
+import type { BaseAdapterOptions, CodecOptions } from '../options';
+/**
+ * Validate the options every adapter shares, at construction. Each failure is
+ * a {@link ValidationError} whose `context.field` names the offending option,
+ * so a misconfiguration surfaces where it was written instead of as a raw AWS
+ * error on the first request.
+ */
+export declare function validateBaseAdapterOptions(options: BaseAdapterOptions & CodecOptions): void;

package/dist/shared/validation/options.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateBaseAdapterOptions = validateBaseAdapterOptions;
+const config_1 = require("../codec/s3/config");
+const constants_1 = require("../constants");
+const errors_1 = require("../errors/errors");
+const primitives_1 = require("./primitives");
+const ttl_1 = require("./ttl");
+/** DynamoDB's table-name rule: 3–255 characters from `[A-Za-z0-9_.-]`. */
+const TABLE_NAME_PATTERN = /^[A-Za-z0-9_.-]{3,255}$/;
+/** Server-side encryption algorithms S3 accepts for `PutObject`. */
+const SSE_ALGORITHMS = ['AES256', 'aws:kms', 'aws:kms:dsse'];
+function validateTableName(tableName) {
+    if (typeof tableName !== 'string' || !TABLE_NAME_PATTERN.test(tableName)) {
+        throw new errors_1.ValidationError('tableName must be 3-255 characters from [A-Za-z0-9_.-], as DynamoDB requires', 'tableName');
+    }
+}
+/**
+ * An injected `client` is used as-is, so a `clientConfig` or `createClient`
+ * given alongside it would be silently ignored — including a `region` the
+ * caller believes is in effect. Reject the combination instead.
+ */
+function validateClientChoice(options) {
+    if (options.client &&
+        (options.clientConfig !== undefined || options.createClient !== undefined)) {
+        throw new errors_1.ValidationError('provide either `client` or `clientConfig`/`createClient`, not both: an injected client ' +
+            'is used as-is and the configuration would be silently ignored', 'client');
+    }
+}
+function validateRetryPolicy(policy) {
+    if (policy.maxAttempts !== undefined) {
+        (0, primitives_1.validateInteger)(policy.maxAttempts, 'retry.maxAttempts', { min: 1, max: constants_1.MAX_RETRY_ATTEMPTS });
+    }
+    if (policy.baseDelayMs !== undefined) {
+        (0, primitives_1.validateInteger)(policy.baseDelayMs, 'retry.baseDelayMs', { min: 1 });
+    }
+    if (policy.maxDelayMs !== undefined) {
+        (0, primitives_1.validateInteger)(policy.maxDelayMs, 'retry.maxDelayMs', { min: policy.baseDelayMs ?? 1 });
+    }
+}
+function validateCompression(config) {
+    if (typeof config.enabled !== 'boolean') {
+        throw new errors_1.ValidationError('compression.enabled must be a boolean', 'compression.enabled');
+    }
+    if (config.level !== undefined) {
+        (0, primitives_1.validateInteger)(config.level, 'compression.level', { min: 0, max: 9 });
+    }
+    if (config.minSizeBytes !== undefined) {
+        (0, primitives_1.validateInteger)(config.minSizeBytes, 'compression.minSizeBytes', { min: 0 });
+    }
+    if (config.maxDecompressedBytes !== undefined) {
+        (0, primitives_1.validateInteger)(config.maxDecompressedBytes, 'compression.maxDecompressedBytes', { min: 1 });
+    }
+}
+function validateS3(config) {
+    (0, primitives_1.validateNonEmptyString)(config.bucketName, 's3.bucketName');
+    if (config.thresholdBytes !== undefined) {
+        (0, primitives_1.validateInteger)(config.thresholdBytes, 's3.thresholdBytes', {
+            min: 1,
+            max: constants_1.MAX_INLINE_PAYLOAD_BYTES,
+        });
+    }
+    if (config.keyPrefix !== undefined)
+        (0, config_1.assertScopedKeyPrefix)(config.keyPrefix);
+    if (config.maxDownloadBytes !== undefined) {
+        (0, primitives_1.validateInteger)(config.maxDownloadBytes, 's3.maxDownloadBytes', { min: 1 });
+    }
+    if (config.serverSideEncryption !== undefined &&
+        !SSE_ALGORITHMS.includes(config.serverSideEncryption)) {
+        throw new errors_1.ValidationError(`s3.serverSideEncryption must be one of ${SSE_ALGORITHMS.join(', ')}`, 's3.serverSideEncryption');
+    }
+}
+/**
+ * Validate the options every adapter shares, at construction. Each failure is
+ * a {@link ValidationError} whose `context.field` names the offending option,
+ * so a misconfiguration surfaces where it was written instead of as a raw AWS
+ * error on the first request.
+ */
+function validateBaseAdapterOptions(options) {
+    validateTableName(options.tableName);
+    validateClientChoice(options);
+    if (options.ttl !== undefined)
+        (0, ttl_1.resolveTtlSeconds)(options.ttl);
+    if (options.retry !== undefined)
+        validateRetryPolicy(options.retry);
+    if (options.compression !== undefined)
+        validateCompression(options.compression);
+    if (options.s3 !== undefined)
+        validateS3(options.s3);
+}

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

@@ -1,6 +1,11 @@
-import type { Redactable } from '../logging/redaction-walk';
-/** Throw {@link ValidationError} unless `value` is a non-empty string. */
+/**
+ * Throw {@link ValidationError} unless `value` is a string with at least one
+ * non-whitespace character: a blank identifier is never intended and would
+ * otherwise become an invisible, un-greppable DynamoDB key.
+ */
 export declare function validateNonEmptyString(value: string, field: string): void;
+/** Throw {@link ValidationError} if `value` exceeds `maxBytes` when encoded as UTF-8. */
+export declare function assertMaxBytes(value: string, field: string, maxBytes: number): void;
 /** Throw {@link ValidationError} unless `value` is an integer within bounds. */
 export declare function validateInteger(value: number, field: string, bounds?: {
     min?: number;
@@ -14,12 +19,11 @@ export declare function assertNoControlChars(value: string, field: string): void
 export declare function assertNoSeparator(value: string, separator: string, field: string): void;
 /**
  * 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.
+ * at most `maxBytes` of UTF-8, 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. The length check runs before the character scans so
+ * an oversized value is rejected without being walked.
  */
-export declare function validateIdentifier(value: string, separator: string, field: string): void;
-/** Throw {@link ValidationError} if nested-array depth exceeds `maxDepth`. */
-export declare function validateArrayMaxDepth(value: Redactable[], field: string, maxDepth: number): void;
-//# sourceMappingURL=primitives.d.ts.map
+export declare function validateIdentifier(value: string, separator: string, field: string, maxBytes: number): void;

package/dist/shared/validation/primitives.js

@@ -1,17 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateNonEmptyString = validateNonEmptyString;
+exports.assertMaxBytes = assertMaxBytes;
 exports.validateInteger = validateInteger;
 exports.validateNonEmptyArray = validateNonEmptyArray;
 exports.assertNoControlChars = assertNoControlChars;
 exports.assertNoSeparator = assertNoSeparator;
 exports.validateIdentifier = validateIdentifier;
-exports.validateArrayMaxDepth = validateArrayMaxDepth;
 const errors_1 = require("../errors/errors");
-/** Throw {@link ValidationError} unless `value` is a non-empty string. */
+/**
+ * Throw {@link ValidationError} unless `value` is a string with at least one
+ * non-whitespace character: a blank identifier is never intended and would
+ * otherwise become an invisible, un-greppable DynamoDB key.
+ */
 function validateNonEmptyString(value, field) {
-    if (typeof value !== 'string' || value.length === 0) {
-        throw new errors_1.ValidationError(`${field} must be a non-empty string`, field);
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new errors_1.ValidationError(`${field} must be a non-empty string (whitespace-only counts as empty)`, field);
+    }
+}
+/** Throw {@link ValidationError} if `value` exceeds `maxBytes` when encoded as UTF-8. */
+function assertMaxBytes(value, field, maxBytes) {
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes > maxBytes) {
+        throw new errors_1.ValidationError(`${field} must be at most ${maxBytes} bytes of UTF-8 (received ${bytes})`, field);
     }
 }
 /** Throw {@link ValidationError} unless `value` is an integer within bounds. */
@@ -56,29 +67,16 @@ function assertNoSeparator(value, 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.
+ * at most `maxBytes` of UTF-8, 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. The length check runs before the character scans so
+ * an oversized value is rejected without being walked.
  */
-function validateIdentifier(value, separator, field) {
+function validateIdentifier(value, separator, field, maxBytes) {
     validateNonEmptyString(value, field);
+    assertMaxBytes(value, field, maxBytes);
     assertNoSeparator(value, separator, field);
     assertNoControlChars(value, field);
 }
-/** 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);
-    }
-}
-//# sourceMappingURL=primitives.js.map

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

@@ -4,7 +4,11 @@ export type TtlOption = {
 } | {
     seconds: number;
 };
-/** Validate a {@link TtlOption} and resolve it to a positive number of seconds. */
+/**
+ * Validate a {@link TtlOption} and resolve it to a positive number of seconds.
+ * Both forms share the same five-year cap, and an object carrying both keys is
+ * rejected instead of being resolved by whichever key happens to be checked first.
+ */
 export declare function resolveTtlSeconds(ttl: TtlOption): number;
 /**
  * Resolve a {@link TtlOption} into a DynamoDB TTL attribute value: the Unix
@@ -13,9 +17,12 @@ export declare function resolveTtlSeconds(ttl: TtlOption): number;
  * @param now - Clock seam returning epoch milliseconds. Defaults to `Date.now`.
  */
 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
+/**
+ * Days for the S3 lifecycle rule that backs a TTL: the TTL rounded up to whole
+ * days plus {@link S3_LIFECYCLE_SWEEP_MARGIN_DAYS}. S3 expires an object at the
+ * first midnight UTC at least that many days after creation, while DynamoDB
+ * can keep the row up to ~48 h past its `ttl`; without the margin an
+ * `{ days: N }` TTL expired the object on day N exactly, stranding a live row
+ * that pointed at a deleted payload until the sweep caught up.
+ */
+export declare function lifecycleExpirationDays(ttl: TtlOption): number;

package/dist/shared/validation/ttl.js

@@ -2,17 +2,32 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveTtlSeconds = resolveTtlSeconds;
 exports.calculateTtlTimestamp = calculateTtlTimestamp;
-exports.resolveTtlDaysCeil = resolveTtlDaysCeil;
+exports.lifecycleExpirationDays = lifecycleExpirationDays;
 const constants_1 = require("../constants");
+const errors_1 = require("../errors/errors");
 const primitives_1 = require("./primitives");
 const SECONDS_PER_DAY = 24 * 60 * 60;
-/** Validate a {@link TtlOption} and resolve it to a positive number of seconds. */
+/** Positive integer no greater than `max`, with a message that names what the cap means. */
+function validateWithinCap(value, field, max) {
+    (0, primitives_1.validateInteger)(value, field, { min: 1 });
+    if (value > max) {
+        throw new errors_1.ValidationError(`${field} must be <= ${max} (five years)`, field);
+    }
+}
+/**
+ * Validate a {@link TtlOption} and resolve it to a positive number of seconds.
+ * Both forms share the same five-year cap, and an object carrying both keys is
+ * rejected instead of being resolved by whichever key happens to be checked first.
+ */
 function resolveTtlSeconds(ttl) {
+    if ('days' in ttl && 'seconds' in ttl) {
+        throw new errors_1.ValidationError('ttl must specify either ttl.days or ttl.seconds, not both', 'ttl');
+    }
     if ('days' in ttl) {
-        (0, primitives_1.validateInteger)(ttl.days, 'ttl.days', { min: 1, max: constants_1.MAX_TTL_DAYS });
+        validateWithinCap(ttl.days, 'ttl.days', constants_1.MAX_TTL_DAYS);
         return ttl.days * SECONDS_PER_DAY;
     }
-    (0, primitives_1.validateInteger)(ttl.seconds, 'ttl.seconds', { min: 1, max: constants_1.MAX_TTL_SECONDS });
+    validateWithinCap(ttl.seconds, 'ttl.seconds', constants_1.MAX_TTL_SECONDS);
     return ttl.seconds;
 }
 /**
@@ -24,11 +39,14 @@ function resolveTtlSeconds(ttl) {
 function calculateTtlTimestamp(ttl, now = Date.now) {
     return Math.floor(now() / 1000) + resolveTtlSeconds(ttl);
 }
-/** 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. */
-function resolveTtlDaysCeil(ttl) {
-    return Math.ceil(resolveTtlSeconds(ttl) / SECONDS_PER_DAY);
+/**
+ * Days for the S3 lifecycle rule that backs a TTL: the TTL rounded up to whole
+ * days plus {@link S3_LIFECYCLE_SWEEP_MARGIN_DAYS}. S3 expires an object at the
+ * first midnight UTC at least that many days after creation, while DynamoDB
+ * can keep the row up to ~48 h past its `ttl`; without the margin an
+ * `{ days: N }` TTL expired the object on day N exactly, stranding a live row
+ * that pointed at a deleted payload until the sweep caught up.
+ */
+function lifecycleExpirationDays(ttl) {
+    return Math.ceil(resolveTtlSeconds(ttl) / SECONDS_PER_DAY) + constants_1.S3_LIFECYCLE_SWEEP_MARGIN_DAYS;
 }
-//# sourceMappingURL=ttl.js.map