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

package/dist/shared/validation/options.js

@@ -1,90 +1,328 @@
 "use strict";
+/**
+ * Hides which adapter-wide construction options are accepted.
+ *
+ * The table name, the client choice, the ttl, the retry policy, the recency
+ * index, the read concurrency, compression and S3 offload are checked here with
+ * their bounds, before an adapter builds anything, so a misconfiguration
+ * surfaces at construction rather than on the first call.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateBaseAdapterOptions = validateBaseAdapterOptions;
+exports.MAX_READ_CONCURRENCY = exports.MAX_RETRY_DELAY_MS = exports.MAX_RETRY_ATTEMPTS = exports.MAX_PAYLOAD_BUFFER_BYTES = void 0;
+exports.assertTableName = assertTableName;
+exports.assertClientChoice = assertClientChoice;
+exports.assertRetryBounds = assertRetryBounds;
+exports.assertRetryPolicy = assertRetryPolicy;
+exports.assertBaseAdapterOptions = assertBaseAdapterOptions;
+exports.assertCompression = assertCompression;
+exports.assertS3 = assertS3;
+const codec_1 = require("../codec/codec");
 const config_1 = require("../codec/s3/config");
-const constants_1 = require("../constants");
+const recency_index_1 = require("../dynamodb/recency-index");
 const errors_1 = require("../errors/errors");
+const option_shape_1 = require("./option-shape");
 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) {
+/**
+ * Largest `s3.maxDownloadBytes`/`compression.maxDecompressedBytes` an adapter
+ * accepts (512 MiB): both hold one buffer fully resident while it is read or
+ * inflated, and `BaseAdapterOptions.readConcurrency`'s doc multiplies the two
+ * together into the package's memory ceiling, so an unbounded value here is an
+ * unbounded process, not just an unbounded object.
+ */
+exports.MAX_PAYLOAD_BUFFER_BYTES = 512 * 1024 * 1024;
+/** Largest `retry.maxAttempts` an adapter accepts; beyond it a retry loop is a hang, not a policy. */
+exports.MAX_RETRY_ATTEMPTS = 100;
+/**
+ * Largest `retry.baseDelayMs`/`retry.maxDelayMs` an adapter accepts (one
+ * minute): combined with {@link MAX_RETRY_ATTEMPTS}, an unbounded per-attempt
+ * delay turns a bounded attempt count back into an effectively unbounded wait.
+ */
+exports.MAX_RETRY_DELAY_MS = 60_000;
+/**
+ * Largest `readConcurrency` an adapter accepts: it is a multiplier on the
+ * memory-ceiling formula (see the option's own doc) and on requests fired at
+ * once, so an unbounded value turns a typo into an out-of-memory crash or a
+ * request storm against the table/bucket.
+ */
+exports.MAX_READ_CONCURRENCY = 128;
+const RETRY_KEYS = (0, option_shape_1.allKeysOf)({
+    maxAttempts: 'maxAttempts',
+    baseDelayMs: 'baseDelayMs',
+    maxDelayMs: 'maxDelayMs',
+});
+/**
+ * Validate a table name against DynamoDB's own naming rule.
+ *
+ * Accepts: `tableName` — as the caller gave it.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `tableName`.
+ */
+function assertTableName(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');
+        throw (0, 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.
+ * Reject a client choice that names two ways of getting one, or a
+ * `clientConfig` that is not an object.
+ *
+ * Accepts: the three client options, from an adapter or from the factory that
+ * defaults them. 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. `clientConfig`, when given, must
+ * be an object that is neither `null` nor an array; what it holds is the AWS
+ * SDK's to judge.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `client` for both ways at once, then
+ * `clientConfig` for one that is not an object.
  */
-function validateClientChoice(options) {
+function assertClientChoice(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 ' +
+        throw (0, 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');
     }
+    // The shape only, never the keys, and on purpose: they are the AWS SDK's
+    // `DynamoDBClientConfig`, which gains keys between SDK releases, and an
+    // application may install a newer SDK than the one this package was
+    // compiled against, so a key list compiled in here would refuse valid
+    // configuration. The SDK reads each key itself.
+    if (options.clientConfig !== undefined)
+        (0, option_shape_1.assertObjectShape)(options.clientConfig, 'clientConfig');
 }
-function validateRetryPolicy(policy) {
+/**
+ * The three numeric bounds every retry policy shares, regardless of which
+ * other keys the caller's own type allows beyond them. Split out so a caller
+ * with a wider surface than {@link RetryPolicy} (`backfillRecencyIndex`'s
+ * `RetryOptions`, which also exposes `onRetry`, `isRetryable` and friends)
+ * can reuse the identical bounds without going through {@link
+ * assertRetryPolicy}'s narrower `assertShape`, which would refuse those
+ * extra keys outright.
+ *
+ * Accepts: `policy` — its `maxAttempts`, `baseDelayMs` and `maxDelayMs`, each
+ * optional.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `retry.maxAttempts`, `retry.baseDelayMs` or
+ * `retry.maxDelayMs`.
+ */
+function assertRetryBounds(policy) {
     if (policy.maxAttempts !== undefined) {
-        (0, primitives_1.validateInteger)(policy.maxAttempts, 'retry.maxAttempts', { min: 1, max: constants_1.MAX_RETRY_ATTEMPTS });
+        (0, primitives_1.assertInteger)(policy.maxAttempts, 'retry.maxAttempts', { min: 1, max: exports.MAX_RETRY_ATTEMPTS });
     }
     if (policy.baseDelayMs !== undefined) {
-        (0, primitives_1.validateInteger)(policy.baseDelayMs, 'retry.baseDelayMs', { min: 1 });
+        (0, primitives_1.assertInteger)(policy.baseDelayMs, 'retry.baseDelayMs', { min: 1, max: exports.MAX_RETRY_DELAY_MS });
     }
     if (policy.maxDelayMs !== undefined) {
-        (0, primitives_1.validateInteger)(policy.maxDelayMs, 'retry.maxDelayMs', { min: policy.baseDelayMs ?? 1 });
+        (0, primitives_1.assertInteger)(policy.maxDelayMs, 'retry.maxDelayMs', {
+            min: policy.baseDelayMs ?? 1,
+            max: exports.MAX_RETRY_DELAY_MS,
+        });
+    }
+}
+/**
+ * Validate a retry policy: shape, then each bound.
+ *
+ * Accepts: `policy` — must be an object naming only `maxAttempts`,
+ * `baseDelayMs` and `maxDelayMs`; each, if given, is a bounded integer.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `retry` or `retry.<key>`.
+ */
+function assertRetryPolicy(policy) {
+    (0, option_shape_1.assertShape)(policy, RETRY_KEYS, 'retry');
+    assertRetryBounds(policy);
+}
+/** The recency index: a named GSI, and the partition count rows are sharded across. */
+function assertRecencyIndex(options) {
+    if (options.indexShards !== undefined) {
+        (0, primitives_1.assertInteger)(options.indexShards, 'indexShards', { min: 1, max: recency_index_1.MAX_INDEX_SHARDS });
+    }
+    if (options.indexName !== undefined)
+        (0, primitives_1.assertNonEmptyString)(options.indexName, 'indexName');
+}
+/**
+ * Validate the options every adapter shares, at construction.
+ *
+ * Accepts: `options` — must be an object. `tableName` is required; every other
+ * option is optional, and `undefined` means "not configured" for each. A
+ * nested `ttl`, `retry`, `compression` or `s3` must be an object whose keys
+ * this package reads: a misspelt key is rejected rather than ignored, because
+ * the caller would otherwise run on a default they believe they overrode.
+ * `clientConfig` and `s3.clientConfig` must be objects, but their keys belong
+ * to the AWS SDK and are not checked. Keys of `options` itself are not checked
+ * here — the adapter types differ and this validator sees only the shared ones.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` whose `context.field` names the offending option,
+ * dotted for a nested one (`s3.bucketName`). The order is `tableName`, client
+ * choice, `ttl`, `retry`, `compression`, `s3`, `readConcurrency`, then the
+ * index options.
+ *
+ * Guarantees: a misconfiguration surfaces at construction, naming the option,
+ * rather than as a raw AWS error on the first request.
+ */
+function assertBaseAdapterOptions(options) {
+    if (typeof options !== 'object' || options === null) {
+        throw (0, errors_1.validationError)('options must be an object naming at least a tableName', 'options');
+    }
+    assertTableName(options.tableName);
+    assertClientChoice(options);
+    if (options.ttl !== undefined)
+        (0, ttl_1.resolveTtlSeconds)(options.ttl);
+    if (options.retry !== undefined)
+        assertRetryPolicy(options.retry);
+    if (options.compression !== undefined)
+        assertCompression(options.compression);
+    if (options.s3 !== undefined)
+        assertS3(options.s3);
+    if (options.readConcurrency !== undefined) {
+        (0, primitives_1.assertInteger)(options.readConcurrency, 'readConcurrency', {
+            min: 1,
+            max: exports.MAX_READ_CONCURRENCY,
+        });
     }
+    assertRecencyIndex(options);
 }
-function validateCompression(config) {
+/** Server-side encryption algorithms S3 accepts for `PutObject`. */
+const SSE_ALGORITHMS = ['AES256', 'aws:kms', 'aws:kms:dsse'];
+const COMPRESSION_KEYS = (0, option_shape_1.allKeysOf)({
+    enabled: 'enabled',
+    level: 'level',
+    minSizeBytes: 'minSizeBytes',
+    maxDecompressedBytes: 'maxDecompressedBytes',
+});
+const S3_KEYS = (0, option_shape_1.allKeysOf)({
+    bucketName: 'bucketName',
+    keyPrefix: 'keyPrefix',
+    thresholdBytes: 'thresholdBytes',
+    serverSideEncryption: 'serverSideEncryption',
+    sseKmsKeyId: 'sseKmsKeyId',
+    maxDownloadBytes: 'maxDownloadBytes',
+    clientConfig: 'clientConfig',
+    createS3Client: 'createS3Client',
+});
+/**
+ * Validate a `compression` config, honoring its allowed key set.
+ *
+ * Accepts: `config` — an object naming only {@link CompressionConfig}'s keys.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming the offending field, dotted under
+ * `compression`.
+ */
+function assertCompression(config) {
+    (0, option_shape_1.assertShape)(config, COMPRESSION_KEYS, 'compression');
     if (typeof config.enabled !== 'boolean') {
-        throw new errors_1.ValidationError('compression.enabled must be a boolean', 'compression.enabled');
+        throw (0, 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 });
+        (0, primitives_1.assertInteger)(config.level, 'compression.level', { min: 0, max: 9 });
     }
     if (config.minSizeBytes !== undefined) {
-        (0, primitives_1.validateInteger)(config.minSizeBytes, 'compression.minSizeBytes', { min: 0 });
+        // Bounded by MAX_PAYLOAD_BUFFER_BYTES, not by MAX_INLINE_PAYLOAD_BYTES as
+        // `s3.thresholdBytes` is, because the two differ in kind. `encodePayload`
+        // compresses first and only then decides inline versus offload, on the
+        // compressed size — so `minSizeBytes` above the inline limit, paired with
+        // `s3`, is a meaningful configuration: compress only what will be offloaded
+        // anyway. A `thresholdBytes` above the inline limit is not: a payload
+        // between the two is too large to store inline and too small to offload,
+        // so its write fails. `minSizeBytes` only decides whether gzip runs; the
+        // only value it can never act on is one larger than any payload this
+        // package can read back.
+        (0, primitives_1.assertInteger)(config.minSizeBytes, 'compression.minSizeBytes', {
+            min: 0,
+            max: exports.MAX_PAYLOAD_BUFFER_BYTES,
+        });
     }
     if (config.maxDecompressedBytes !== undefined) {
-        (0, primitives_1.validateInteger)(config.maxDecompressedBytes, 'compression.maxDecompressedBytes', { min: 1 });
+        (0, primitives_1.assertInteger)(config.maxDecompressedBytes, 'compression.maxDecompressedBytes', {
+            min: 1,
+            max: exports.MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+}
+/**
+ * Validate the two `s3` options `PutObject` receives as they were given.
+ *
+ * Accepts: `config.serverSideEncryption` — absent, or an algorithm S3 accepts.
+ * `config.sseKmsKeyId` — absent, or a non-empty string. Only its type is
+ * checked; whether it names a real key, by id or by ARN, is for S3 to answer.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `s3.serverSideEncryption` or
+ * `s3.sseKmsKeyId`. Unchecked, a truthy key id that is not a string was
+ * handed to `PutObject` at the first offload, and a falsy one (`''`, `null`,
+ * `0`) was dropped, uploading without the key the caller named.
+ */
+function assertS3Encryption(config) {
+    if (config.serverSideEncryption !== undefined &&
+        !SSE_ALGORITHMS.includes(config.serverSideEncryption)) {
+        throw (0, errors_1.validationError)(`s3.serverSideEncryption must be one of ${SSE_ALGORITHMS.join(', ')}`, 's3.serverSideEncryption');
+    }
+    if (config.sseKmsKeyId !== undefined) {
+        (0, primitives_1.assertNonEmptyString)(config.sseKmsKeyId, 's3.sseKmsKeyId');
     }
 }
-function validateS3(config) {
-    (0, primitives_1.validateNonEmptyString)(config.bucketName, 's3.bucketName');
+/**
+ * Validate an `s3` offload config, honoring its allowed key set.
+ *
+ * Accepts: `config` — an object naming only {@link S3OffloadConfig}'s keys.
+ * `config.clientConfig`, when given, must be an object that is neither `null`
+ * nor an array; its own keys are not checked. `config.createS3Client`, when
+ * given, must be a function.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming the offending field, dotted under `s3`.
+ */
+function assertS3(config) {
+    (0, option_shape_1.assertShape)(config, S3_KEYS, 's3');
+    (0, primitives_1.assertNonEmptyString)(config.bucketName, 's3.bucketName');
+    // The shape only, never the keys: they are the AWS SDK's `S3ClientConfig`,
+    // which gains keys between SDK releases, and an application may install a
+    // newer SDK than the one this package was compiled against, so a key list
+    // compiled in here would refuse valid configuration.
+    if (config.clientConfig !== undefined)
+        (0, option_shape_1.assertObjectShape)(config.clientConfig, 's3.clientConfig');
     if (config.thresholdBytes !== undefined) {
-        (0, primitives_1.validateInteger)(config.thresholdBytes, 's3.thresholdBytes', {
+        (0, primitives_1.assertInteger)(config.thresholdBytes, 's3.thresholdBytes', {
             min: 1,
-            max: constants_1.MAX_INLINE_PAYLOAD_BYTES,
+            max: codec_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 });
+        (0, primitives_1.assertInteger)(config.maxDownloadBytes, 's3.maxDownloadBytes', {
+            min: 1,
+            max: exports.MAX_PAYLOAD_BUFFER_BYTES,
+        });
     }
-    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');
+    assertS3Encryption(config);
+    // Called to build the S3 client at the first offload, where a value that is
+    // not a function threw a bare `TypeError`.
+    if (config.createS3Client !== undefined && typeof config.createS3Client !== 'function') {
+        throw (0, errors_1.validationError)('s3.createS3Client must be a function', 's3.createS3Client');
     }
 }
-/**
- * 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);
-}