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

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

@@ -0,0 +1,145 @@
+/**
+ * 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.
+ */
+import type { CompressionConfig } from '../codec/compression.js';
+import { type S3OffloadConfig } from '../codec/s3/config.js';
+import type { RetryPolicy } from '../dynamodb/retry.js';
+import type { BaseAdapterOptions, CodecOptions } from '../options.js';
+/**
+ * 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.
+ */
+export declare const MAX_PAYLOAD_BUFFER_BYTES: number;
+/** Largest `retry.maxAttempts` an adapter accepts; beyond it a retry loop is a hang, not a policy. */
+export declare const 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.
+ */
+export declare const MAX_RETRY_DELAY_MS = 60000;
+/**
+ * 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.
+ */
+export declare const MAX_READ_CONCURRENCY = 128;
+/**
+ * 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`.
+ */
+export declare function assertTableName(tableName: string): void;
+/**
+ * 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.
+ */
+export declare function assertClientChoice(options: Pick<BaseAdapterOptions, 'client' | 'clientConfig' | 'createClient'>): void;
+/**
+ * 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`.
+ */
+export declare function assertRetryBounds(policy: Pick<RetryPolicy, 'maxAttempts' | 'baseDelayMs' | 'maxDelayMs'>): void;
+/**
+ * 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>`.
+ */
+export declare function assertRetryPolicy(policy: RetryPolicy): void;
+/**
+ * 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.
+ */
+export declare function assertBaseAdapterOptions(options: BaseAdapterOptions & CodecOptions): void;
+/**
+ * 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`.
+ */
+export declare function assertCompression(config: CompressionConfig): void;
+/**
+ * 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`.
+ */
+export declare function assertS3(config: S3OffloadConfig): void;

package/dist/esm/shared/validation/options.js

@@ -0,0 +1,156 @@
+import { MAX_INLINE_PAYLOAD_BYTES } from '../codec/codec.js';
+import { assertScopedKeyPrefix } from '../codec/s3/config.js';
+import { DEFAULT_MAX_S3_DOWNLOAD_BYTES, DEFAULT_S3_THRESHOLD_BYTES, } from '../codec/s3/offloader.js';
+import { MAX_INDEX_SHARDS } from '../dynamodb/recency-index.js';
+import { validationError } from '../errors/errors.js';
+import { allKeysOf, assertObjectShape, assertShape } from './option-shape.js';
+import { assertInteger, assertNonEmptyString } from './primitives.js';
+import { resolveTtlSeconds } from './ttl.js';
+const TABLE_NAME_PATTERN = /^[A-Za-z0-9_.-]{3,255}$/;
+export const MAX_PAYLOAD_BUFFER_BYTES = 512 * 1024 * 1024;
+export const MAX_RETRY_ATTEMPTS = 100;
+export const MAX_RETRY_DELAY_MS = 60_000;
+export const MAX_READ_CONCURRENCY = 128;
+const RETRY_KEYS = allKeysOf({
+    maxAttempts: 'maxAttempts',
+    baseDelayMs: 'baseDelayMs',
+    maxDelayMs: 'maxDelayMs',
+});
+export function assertTableName(tableName) {
+    if (typeof tableName !== 'string' || !TABLE_NAME_PATTERN.test(tableName)) {
+        throw validationError('tableName must be 3-255 characters from [A-Za-z0-9_.-], as DynamoDB requires', 'tableName');
+    }
+}
+export function assertClientChoice(options) {
+    if (options.client &&
+        (options.clientConfig !== undefined || options.createClient !== undefined)) {
+        throw validationError('provide either `client` or `clientConfig`/`createClient`, not both: an injected client ' +
+            'is used as-is and the configuration would be silently ignored', 'client');
+    }
+    if (options.clientConfig !== undefined)
+        assertObjectShape(options.clientConfig, 'clientConfig');
+}
+export function assertRetryBounds(policy) {
+    if (policy.maxAttempts !== undefined) {
+        assertInteger(policy.maxAttempts, 'retry.maxAttempts', { min: 1, max: MAX_RETRY_ATTEMPTS });
+    }
+    if (policy.baseDelayMs !== undefined) {
+        assertInteger(policy.baseDelayMs, 'retry.baseDelayMs', { min: 1, max: MAX_RETRY_DELAY_MS });
+    }
+    if (policy.maxDelayMs !== undefined) {
+        assertInteger(policy.maxDelayMs, 'retry.maxDelayMs', {
+            min: policy.baseDelayMs ?? 1,
+            max: MAX_RETRY_DELAY_MS,
+        });
+    }
+}
+export function assertRetryPolicy(policy) {
+    assertShape(policy, RETRY_KEYS, 'retry');
+    assertRetryBounds(policy);
+}
+function assertRecencyIndex(options) {
+    if (options.indexShards !== undefined) {
+        assertInteger(options.indexShards, 'indexShards', { min: 1, max: MAX_INDEX_SHARDS });
+    }
+    if (options.indexName !== undefined)
+        assertNonEmptyString(options.indexName, 'indexName');
+}
+export function assertBaseAdapterOptions(options) {
+    if (typeof options !== 'object' || options === null) {
+        throw validationError('options must be an object naming at least a tableName', 'options');
+    }
+    assertTableName(options.tableName);
+    assertClientChoice(options);
+    if (options.ttl !== undefined)
+        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) {
+        assertInteger(options.readConcurrency, 'readConcurrency', {
+            min: 1,
+            max: MAX_READ_CONCURRENCY,
+        });
+    }
+    assertRecencyIndex(options);
+}
+const SSE_ALGORITHMS = ['AES256', 'aws:kms', 'aws:kms:dsse'];
+const COMPRESSION_KEYS = allKeysOf({
+    enabled: 'enabled',
+    level: 'level',
+    minSizeBytes: 'minSizeBytes',
+    maxDecompressedBytes: 'maxDecompressedBytes',
+});
+const S3_KEYS = allKeysOf({
+    bucketName: 'bucketName',
+    keyPrefix: 'keyPrefix',
+    thresholdBytes: 'thresholdBytes',
+    serverSideEncryption: 'serverSideEncryption',
+    sseKmsKeyId: 'sseKmsKeyId',
+    maxDownloadBytes: 'maxDownloadBytes',
+    clientConfig: 'clientConfig',
+    createS3Client: 'createS3Client',
+});
+export function assertCompression(config) {
+    assertShape(config, COMPRESSION_KEYS, 'compression');
+    if (typeof config.enabled !== 'boolean') {
+        throw validationError('compression.enabled must be a boolean', 'compression.enabled');
+    }
+    if (config.level !== undefined) {
+        assertInteger(config.level, 'compression.level', { min: 0, max: 9 });
+    }
+    if (config.minSizeBytes !== undefined) {
+        assertInteger(config.minSizeBytes, 'compression.minSizeBytes', {
+            min: 0,
+            max: MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+    if (config.maxDecompressedBytes !== undefined) {
+        assertInteger(config.maxDecompressedBytes, 'compression.maxDecompressedBytes', {
+            min: 1,
+            max: MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+}
+function assertS3Encryption(config) {
+    if (config.serverSideEncryption !== undefined &&
+        !SSE_ALGORITHMS.includes(config.serverSideEncryption)) {
+        throw validationError(`s3.serverSideEncryption must be one of ${SSE_ALGORITHMS.join(', ')}`, 's3.serverSideEncryption');
+    }
+    if (config.sseKmsKeyId !== undefined) {
+        assertNonEmptyString(config.sseKmsKeyId, 's3.sseKmsKeyId');
+    }
+}
+export function assertS3(config) {
+    assertShape(config, S3_KEYS, 's3');
+    assertNonEmptyString(config.bucketName, 's3.bucketName');
+    if (config.clientConfig !== undefined)
+        assertObjectShape(config.clientConfig, 's3.clientConfig');
+    if (config.thresholdBytes !== undefined) {
+        assertInteger(config.thresholdBytes, 's3.thresholdBytes', {
+            min: 1,
+            max: MAX_INLINE_PAYLOAD_BYTES,
+        });
+    }
+    if (config.keyPrefix !== undefined)
+        assertScopedKeyPrefix(config.keyPrefix);
+    if (config.maxDownloadBytes !== undefined) {
+        assertInteger(config.maxDownloadBytes, 's3.maxDownloadBytes', {
+            min: 1,
+            max: MAX_PAYLOAD_BUFFER_BYTES,
+        });
+    }
+    const threshold = config.thresholdBytes ?? DEFAULT_S3_THRESHOLD_BYTES;
+    const downloadable = config.maxDownloadBytes ?? DEFAULT_MAX_S3_DOWNLOAD_BYTES;
+    if (downloadable < threshold) {
+        throw validationError(`s3.maxDownloadBytes (${downloadable}) must be at least s3.thresholdBytes (${threshold}): ` +
+            'every offloaded payload is at least the threshold, so none could be read back', 's3.maxDownloadBytes');
+    }
+    assertS3Encryption(config);
+    if (config.createS3Client !== undefined && typeof config.createS3Client !== 'function') {
+        throw validationError('s3.createS3Client must be a function', 's3.createS3Client');
+    }
+}

package/dist/{shared/validation/primitives.js → esm/shared/validation/primitives.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides the rules every caller-supplied primitive must pass.
  *
@@ -10,20 +9,6 @@
  * 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.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.assertWellFormed = assertWellFormed;
-exports.parseKeySegment = parseKeySegment;
-exports.parseIdentifier = parseIdentifier;
-const errors_1 = require("../errors/errors");
 /**
  * Largest `limit` any read accepts, on every method that takes one.
  *
@@ -54,7 +39,18 @@ const errors_1 = require("../errors/errors");
  * `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;
+export declare const MAX_PAGE_LIMIT = 10000;
+declare const pageLimitBrand: unique symbol;
+/**
+ * A page size checked against the package-wide page rule: an integer from the
+ * call site's floor to {@link MAX_PAGE_LIMIT}. {@link parseLimit} is the only
+ * way to obtain one, so a reader that asks for a `PageLimit` cannot be handed a
+ * size nobody checked, and does not check it again. The brand is phantom: at
+ * run time it is the caller's own number.
+ */
+export type PageLimit = number & {
+    readonly [pageLimitBrand]: true;
+};
 /**
  * The value as a string, or a refusal.
  *
@@ -66,29 +62,7 @@ exports.MAX_PAGE_LIMIT = 10_000;
  *
  * 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;
-}
-/**
- * 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;
-}
+export declare function parseString(value: unknown, field: string): string;
 /**
  * Throw `VALIDATION` unless `value` is a string holding at least one
  * non-whitespace character.
@@ -103,17 +77,7 @@ function parseNonBlankString(value, field) {
  *
  * 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);
-    }
-}
+export declare function assertNonEmptyString(value: string, field: string): void;
 /**
  * The value as an integer inside `bounds`.
  *
@@ -126,18 +90,10 @@ function assertMaxBytes(value, field, maxBytes) {
  * 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 (0, errors_1.validationError)(`${field} must be an integer`, field);
-    }
-    if (bounds.min !== undefined && value < bounds.min) {
-        throw (0, errors_1.validationError)(`${field} must be >= ${bounds.min}`, field);
-    }
-    if (bounds.max !== undefined && value > bounds.max) {
-        throw (0, errors_1.validationError)(`${field} must be <= ${bounds.max}`, field);
-    }
-    return value;
-}
+export declare function parseInteger(value: unknown, field: string, bounds?: {
+    min?: number;
+    max?: number;
+}): number;
 /**
  * Throw `VALIDATION` unless `value` is an integer inside `bounds`.
  *
@@ -153,9 +109,10 @@ function parseInteger(value, field, bounds = {}) {
  * Throws: `VALIDATION` naming `field`; the integer rule is reported before
  * either bound.
  */
-function assertInteger(value, field, bounds = {}) {
-    parseInteger(value, field, bounds);
-}
+export declare function assertInteger(value: number, field: string, bounds?: {
+    min?: number;
+    max?: number;
+}): void;
 /**
  * The value as a page size this package will serve: an integer from `min` to
  * {@link MAX_PAGE_LIMIT}.
@@ -191,9 +148,7 @@ function assertInteger(value, field, bounds = {}) {
  * 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 });
-}
+export declare function parseLimit(value: unknown, min: 0 | 1): PageLimit;
 /**
  * The value as an array of strings, copied.
  *
@@ -210,20 +165,7 @@ function parseLimit(value, min) {
  * 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;
-}
+export declare function parseStringArray(value: unknown, field: string): string[];
 /**
  * Throw `VALIDATION` unless `value` is an array of strings.
  *
@@ -237,18 +179,7 @@ function parseStringArray(value, field) {
  *
  * 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 && code <= 0x9f))
-            return true;
-    }
-    return false;
-}
+export declare function assertStringArray(value: readonly string[], field: string): void;
 /**
  * Throw `VALIDATION` unless `value` is free of control characters.
  *
@@ -270,12 +201,7 @@ function hasControlChar(value) {
  * 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 (0, errors_1.validationError)(`${field} must not contain control characters`, field);
-    }
-}
+export declare function assertNoControlChars(value: string, field: string): void;
 /**
  * Throw `VALIDATION` unless every surrogate in `value` is part of a
  * pair.
@@ -296,20 +222,7 @@ function assertNoControlChars(value, field) {
  * 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 `VALIDATION` if `value` contains `separator`. */
-function assertNoSeparator(value, separator, field) {
-    parseString(value, field);
-    if (value.includes(separator)) {
-        throw (0, errors_1.validationError)(`${field} must not contain the reserved "${separator}" separator`, field);
-    }
-}
+export declare function assertWellFormed(value: string, field: string): void;
 /**
  * One segment of a key, which may be empty: every rule of
  * {@link parseIdentifier} except non-blank. The checkpoint namespace is the one
@@ -326,14 +239,7 @@ function assertNoSeparator(value, separator, field) {
  * `maxBytes` of UTF-8, free of `separator`, free of control characters,
  * well-formed UTF-16.
  */
-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;
-}
+export declare function parseKeySegment(value: unknown, separator: string, field: string, maxBytes: number): string;
 /**
  * The value as a caller-supplied identifier that reaches a DynamoDB key or an
  * S3 object key, checked.
@@ -382,6 +288,5 @@ function parseKeySegment(value, separator, field, maxBytes) {
  * 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);
-}
+export declare function parseIdentifier(value: unknown, separator: string, field: string, maxBytes: number): string;
+export {};

package/dist/esm/shared/validation/primitives.js

@@ -0,0 +1,100 @@
+import { validationError } from '../errors/errors.js';
+export const MAX_PAGE_LIMIT = 10_000;
+export function parseString(value, field) {
+    if (typeof value !== 'string') {
+        throw validationError(`${field} must be a string`, field);
+    }
+    return value;
+}
+function parseNonBlankString(value, field) {
+    const text = parseString(value, field);
+    if (text.trim().length === 0) {
+        throw validationError(`${field} must be a non-empty string (whitespace-only counts as empty)`, field);
+    }
+    return text;
+}
+export function assertNonEmptyString(value, field) {
+    parseNonBlankString(value, field);
+}
+function assertMaxBytes(value, field, maxBytes) {
+    parseString(value, field);
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes > maxBytes) {
+        throw validationError(`${field} must be at most ${maxBytes} bytes of UTF-8 (received ${bytes})`, field);
+    }
+}
+export function parseInteger(value, field, bounds = {}) {
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+        throw validationError(`${field} must be an integer`, field);
+    }
+    if (bounds.min !== undefined && value < bounds.min) {
+        throw validationError(`${field} must be >= ${bounds.min}`, field);
+    }
+    if (bounds.max !== undefined && value > bounds.max) {
+        throw validationError(`${field} must be <= ${bounds.max}`, field);
+    }
+    return value;
+}
+export function assertInteger(value, field, bounds = {}) {
+    parseInteger(value, field, bounds);
+}
+export function parseLimit(value, min) {
+    return parseInteger(value, 'limit', { min, max: MAX_PAGE_LIMIT });
+}
+function parseStringElement(item, field, index) {
+    if (typeof item !== 'string') {
+        throw validationError(`${field}[${index}] must be a string`, field);
+    }
+    return item;
+}
+export function parseStringArray(value, field) {
+    if (!Array.isArray(value)) {
+        throw validationError(`${field} must be an array of strings`, field);
+    }
+    const result = [];
+    for (let index = 0; index < value.length; index += 1) {
+        result.push(parseStringElement(value[index], field, index));
+    }
+    return result;
+}
+export function assertStringArray(value, field) {
+    parseStringArray(value, field);
+}
+function hasControlChar(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}
+export function assertNoControlChars(value, field) {
+    parseString(value, field);
+    if (hasControlChar(value)) {
+        throw validationError(`${field} must not contain control characters`, field);
+    }
+}
+export function assertWellFormed(value, field) {
+    parseString(value, field);
+    if (!value.isWellFormed()) {
+        throw validationError(`${field} must be well-formed UTF-16 (it contains an unpaired surrogate, which does not ` +
+            'survive encoding to UTF-8)', field);
+    }
+}
+function assertNoSeparator(value, separator, field) {
+    parseString(value, field);
+    if (value.includes(separator)) {
+        throw validationError(`${field} must not contain the reserved "${separator}" separator`, field);
+    }
+}
+export 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;
+}
+export function parseIdentifier(value, separator, field, maxBytes) {
+    return parseKeySegment(parseNonBlankString(value, field), separator, field, maxBytes);
+}