ts-prorm-orm 1.1.0

package/dist/nosql/dynamodb/index.js

@@ -0,0 +1,937 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDbStore = exports.DynamoDbError = exports.DynamoStreamViewType = exports.DynamoReturnValues = void 0;
+/**
+ * Amazon DynamoDB store.
+ *
+ * DynamoDB is a partition-key-based key-value/document store, not a SQL
+ * database — it has no arbitrary WHERE-clause queries, no joins, and no
+ * ad hoc filtering without first reading data (`FilterExpression` runs
+ * *after* items are read/consumed against RCU, it does not reduce the
+ * amount of data scanned). Access patterns must be designed up front
+ * around the table's partition key (and optional sort key), plus any
+ * Global/Local Secondary Indexes. Because none of that fits the SQL-shaped
+ * `Dialect` interface (`src/dialects/dialect.ts`), this store instead
+ * implements the minimal `NoSqlStore` marker interface
+ * (`src/nosql/store.ts`) and exposes DynamoDB's own item-level operations
+ * directly.
+ *
+ * Built on AWS SDK v3: `DynamoDBClient` (`@aws-sdk/client-dynamodb`) is the
+ * low-level client that speaks the DynamoDB wire protocol in terms of
+ * `AttributeValue` maps (`{ S: 'foo' }`, `{ N: '1' }`, ...). This store
+ * wraps it in a `DynamoDBDocumentClient` (`@aws-sdk/lib-dynamodb`), which
+ * marshals/unmarshals plain JavaScript objects to/from that wire format
+ * automatically, so callers of this class work with ordinary objects.
+ */
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
+const errors_1 = require("../../errors");
+/**
+ * Companion enum for DynamoDB's `ReturnValues` parameter (PutItem, UpdateItem,
+ * DeleteItem). Provided for callers who prefer enum members over raw string
+ * literals; the underlying option fields still accept the original
+ * `'NONE' | 'ALL_OLD' | 'ALL_NEW' | 'UPDATED_OLD' | 'UPDATED_NEW'` string
+ * literals too; this is purely additive and does not narrow what's accepted.
+ */
+var DynamoReturnValues;
+(function (DynamoReturnValues) {
+    DynamoReturnValues["None"] = "NONE";
+    DynamoReturnValues["AllOld"] = "ALL_OLD";
+    DynamoReturnValues["AllNew"] = "ALL_NEW";
+    DynamoReturnValues["UpdatedOld"] = "UPDATED_OLD";
+    DynamoReturnValues["UpdatedNew"] = "UPDATED_NEW";
+})(DynamoReturnValues || (exports.DynamoReturnValues = DynamoReturnValues = {}));
+/**
+ * Companion enum for DynamoDB's `StreamViewType` (used by `enableStreams`).
+ * Provided for callers who prefer enum members over raw string literals; the
+ * `enableStreams` parameter still accepts the original
+ * `'NEW_IMAGE' | 'OLD_IMAGE' | 'NEW_AND_OLD_IMAGES' | 'KEYS_ONLY'` string
+ * literals too; this is purely additive and does not narrow what's accepted.
+ */
+var DynamoStreamViewType;
+(function (DynamoStreamViewType) {
+    DynamoStreamViewType["NewImage"] = "NEW_IMAGE";
+    DynamoStreamViewType["OldImage"] = "OLD_IMAGE";
+    DynamoStreamViewType["NewAndOldImages"] = "NEW_AND_OLD_IMAGES";
+    DynamoStreamViewType["KeysOnly"] = "KEYS_ONLY";
+})(DynamoStreamViewType || (exports.DynamoStreamViewType = DynamoStreamViewType = {}));
+const MAX_BATCH_GET_ITEMS = 100;
+const MAX_BATCH_WRITE_ITEMS = 25;
+const DEFAULT_MAX_ATTEMPTS = 5;
+const DEFAULT_BASE_DELAY_MS = 50;
+const DEFAULT_MAX_DELAY_MS = 2000;
+/**
+ * `DatabaseError` subclass used for all DynamoDB failures wrapped by this
+ * store. Adds `cancellationReasons`, populated whenever the underlying AWS
+ * error is a `TransactionCanceledException` (thrown by
+ * `transactWriteItems()`/`transactGetItems()`), so callers can inspect which
+ * item(s) caused the transaction to be cancelled and why without digging
+ * into `.parent`/`.original`.
+ */
+class DynamoDbError extends errors_1.DatabaseError {
+    constructor(message, options = {}) {
+        const { cancellationReasons, ...rest } = options;
+        super(message, rest);
+        this.cancellationReasons = cancellationReasons;
+        this.name = 'DynamoDbError';
+    }
+}
+exports.DynamoDbError = DynamoDbError;
+/**
+ * Amazon DynamoDB store, implementing the minimal `NoSqlStore` marker
+ * interface. Unlike the SQL dialects, there is no `query(sql)` — DynamoDB's
+ * operations are item/key-shaped (Get/Put/Update/Delete/Query/Scan/Batch/Transact),
+ * and that shape is preserved here rather than forced into a SQL string.
+ */
+class DynamoDbStore {
+    constructor(options = {}) {
+        this.name = 'dynamodb';
+        this.library = '@aws-sdk/client-dynamodb';
+        this.client = null;
+        this.docClient = null;
+        this.connected = false;
+        this.options = options;
+    }
+    // ---------------------------------------------------------------------
+    // NoSqlStore lifecycle
+    // ---------------------------------------------------------------------
+    async connect() {
+        try {
+            const config = {
+                ...this.options.clientConfig,
+                region: this.options.region ?? this.options.clientConfig?.region,
+                endpoint: this.options.endpoint ?? this.options.clientConfig?.endpoint,
+                credentials: this.options.credentials ?? this.options.clientConfig?.credentials,
+            };
+            this.client = new client_dynamodb_1.DynamoDBClient(config);
+            this.docClient = lib_dynamodb_1.DynamoDBDocumentClient.from(this.client, this.options.translateConfig);
+            this.connected = true;
+        }
+        catch (err) {
+            this.connected = false;
+            throw new errors_1.ConnectionError(`Failed to connect to DynamoDB: ${err instanceof Error ? err.message : String(err)}`, { parent: err instanceof Error ? err : undefined });
+        }
+    }
+    async disconnect() {
+        try {
+            this.docClient?.destroy();
+            this.client?.destroy();
+        }
+        finally {
+            this.client = null;
+            this.docClient = null;
+            this.connected = false;
+        }
+    }
+    isConnected() {
+        return this.connected;
+    }
+    /** Returns the `DynamoDBDocumentClient` (plain-object marshalling), not the raw `DynamoDBClient`. */
+    getClient() {
+        return this.requireClient();
+    }
+    /** Access to the low-level `DynamoDBClient` (raw `AttributeValue` shapes), for anything the document client doesn't cover. */
+    getRawClient() {
+        if (!this.client) {
+            throw new errors_1.ConnectionError('DynamoDB client is not connected. Call connect() first.');
+        }
+        return this.client;
+    }
+    requireClient() {
+        if (!this.docClient || !this.connected) {
+            throw new errors_1.ConnectionError('DynamoDB client is not connected. Call connect() first.');
+        }
+        return this.docClient;
+    }
+    /**
+     * Wraps an AWS SDK failure in a `DynamoDbError` (a `DatabaseError`
+     * subclass) while preserving the original error (incl. `.name` like
+     * `ConditionalCheckFailedException`) on `.parent`/`.original`. When the
+     * underlying error is a `TransactionCanceledException`, its
+     * `CancellationReasons` (per-item cancellation detail from
+     * `transactWriteItems()`/`transactGetItems()`) are also surfaced directly
+     * on `.cancellationReasons`, so callers don't have to dig into `.parent`
+     * to find out which item caused a transaction to be cancelled.
+     */
+    wrapError(action, err) {
+        const parent = err instanceof Error ? err : undefined;
+        const name = parent?.name ? ` (${parent.name})` : '';
+        const rawReasons = err?.CancellationReasons;
+        const cancellationReasons = Array.isArray(rawReasons)
+            ? rawReasons.map((r) => ({ code: r.Code, message: r.Message, item: r.Item }))
+            : undefined;
+        return new DynamoDbError(`DynamoDB ${action} failed${name}: ${parent?.message ?? String(err)}`, {
+            parent,
+            original: parent?.message,
+            cancellationReasons,
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Single-item CRUD
+    // ---------------------------------------------------------------------
+    async getItem(tableName, key, options = {}) {
+        const client = this.requireClient();
+        const input = {
+            TableName: tableName,
+            Key: key,
+            ConsistentRead: options.consistentRead,
+            ProjectionExpression: options.projectionExpression,
+        };
+        try {
+            const result = await client.send(new lib_dynamodb_1.GetCommand(input));
+            return result.Item;
+        }
+        catch (err) {
+            throw this.wrapError(`GetItem on '${tableName}'`, err);
+        }
+    }
+    /**
+     * `options.returnValues` defaults to `'NONE'` (matching real PutItem
+     * default behavior). Pass `'ALL_OLD'` to get the item's previous value
+     * back (`undefined` if there wasn't one).
+     */
+    async putItem(tableName, item, options = {}) {
+        const client = this.requireClient();
+        const input = {
+            TableName: tableName,
+            Item: item,
+            ConditionExpression: options.conditionExpression,
+            ExpressionAttributeNames: options.expressionAttributeNames,
+            ExpressionAttributeValues: options.expressionAttributeValues,
+            ReturnValues: options.returnValues,
+        };
+        try {
+            const result = await client.send(new lib_dynamodb_1.PutCommand(input));
+            return result.Attributes;
+        }
+        catch (err) {
+            throw this.wrapError(`PutItem on '${tableName}'`, err);
+        }
+    }
+    /**
+     * Convenience update: SETs each key in `updates` to its value. Builds a
+     * simple `UpdateExpression`/`ExpressionAttributeValues` internally, using
+     * `#k0`, `#k1`, ... as attribute name placeholders (so reserved words like
+     * `status` are always safe) merged with any `options.expressionAttributeNames`.
+     * For REMOVE/ADD/DELETE or nested-path updates, use `updateItemRaw()`.
+     */
+    async updateItem(tableName, key, updates, options = {}) {
+        const entries = Object.entries(updates);
+        if (entries.length === 0) {
+            throw new errors_1.DatabaseError('updateItem() requires at least one attribute to update', {
+                original: 'empty updates object',
+            });
+        }
+        const names = { ...options.expressionAttributeNames };
+        const values = {};
+        const sets = [];
+        entries.forEach(([attr, value], i) => {
+            const nameKey = `#k${i}`;
+            const valueKey = `:v${i}`;
+            names[nameKey] = attr;
+            values[valueKey] = value;
+            sets.push(`${nameKey} = ${valueKey}`);
+        });
+        return this.updateItemRaw(tableName, {
+            TableName: tableName,
+            Key: key,
+            UpdateExpression: `SET ${sets.join(', ')}`,
+            ExpressionAttributeNames: names,
+            ExpressionAttributeValues: values,
+            ConditionExpression: options.conditionExpression,
+            ReturnValues: (options.returnValues ?? 'ALL_NEW'),
+        });
+    }
+    /** Escape hatch for update expressions beyond the flat-SET convenience wrapper above (REMOVE/ADD/DELETE, nested paths, etc). */
+    async updateItemRaw(tableName, input) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(new lib_dynamodb_1.UpdateCommand({ ...input, TableName: tableName }));
+            return result.Attributes;
+        }
+        catch (err) {
+            throw this.wrapError(`UpdateItem on '${tableName}'`, err);
+        }
+    }
+    /** `options.returnValues` defaults to `'ALL_OLD'` (returns the deleted item); pass `'NONE'` to skip returning it. */
+    async deleteItem(tableName, key, options = {}) {
+        const client = this.requireClient();
+        const input = {
+            TableName: tableName,
+            Key: key,
+            ConditionExpression: options.conditionExpression,
+            ExpressionAttributeNames: options.expressionAttributeNames,
+            ExpressionAttributeValues: options.expressionAttributeValues,
+            ReturnValues: (options.returnValues ?? 'ALL_OLD'),
+        };
+        try {
+            const result = await client.send(new lib_dynamodb_1.DeleteCommand(input));
+            return result.Attributes;
+        }
+        catch (err) {
+            throw this.wrapError(`DeleteItem on '${tableName}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Query / Scan
+    // ---------------------------------------------------------------------
+    /**
+     * Query by partition key equality (plus an optional sort-key condition)
+     * against the base table or a named GSI/LSI. This is the primary way to
+     * read more than one item efficiently from DynamoDB — unlike Scan, it
+     * only reads the partition(s) that match, not the whole table.
+     */
+    async query(tableName, params) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(new lib_dynamodb_1.QueryCommand({
+                TableName: tableName,
+                IndexName: params.indexName,
+                KeyConditionExpression: params.keyConditionExpression,
+                ExpressionAttributeNames: params.expressionAttributeNames,
+                ExpressionAttributeValues: params.expressionAttributeValues,
+                FilterExpression: params.filterExpression,
+                ProjectionExpression: params.projectionExpression,
+                Limit: params.limit,
+                ScanIndexForward: params.scanIndexForward,
+                ExclusiveStartKey: params.exclusiveStartKey,
+                ConsistentRead: params.consistentRead,
+            }));
+            return {
+                items: (result.Items ?? []),
+                lastEvaluatedKey: result.LastEvaluatedKey,
+                count: result.Count ?? 0,
+                scannedCount: result.ScannedCount ?? 0,
+            };
+        }
+        catch (err) {
+            throw this.wrapError(`Query on '${tableName}'`, err);
+        }
+    }
+    /**
+     * Full table (or index) scan. This reads every item in the table — cost
+     * and latency scale with table size, not with how many items you actually
+     * want, and `filterExpression` is applied *after* the read (it does not
+     * reduce RCU consumption or the amount of data scanned). Prefer `query()`
+     * with a well-designed partition/sort key or GSI. Only reach for `scan()`
+     * for admin/maintenance/export tasks, small tables, or as a last resort
+     * when no query-friendly access pattern exists.
+     */
+    async scan(tableName, params = {}) {
+        const client = this.requireClient();
+        try {
+            const result = await client.send(new lib_dynamodb_1.ScanCommand({
+                TableName: tableName,
+                IndexName: params.indexName,
+                FilterExpression: params.filterExpression,
+                ProjectionExpression: params.projectionExpression,
+                ExpressionAttributeNames: params.expressionAttributeNames,
+                ExpressionAttributeValues: params.expressionAttributeValues,
+                Limit: params.limit,
+                ExclusiveStartKey: params.exclusiveStartKey,
+                ConsistentRead: params.consistentRead,
+                Segment: params.segment,
+                TotalSegments: params.totalSegments,
+            }));
+            return {
+                items: (result.Items ?? []),
+                lastEvaluatedKey: result.LastEvaluatedKey,
+                count: result.Count ?? 0,
+                scannedCount: result.ScannedCount ?? 0,
+            };
+        }
+        catch (err) {
+            throw this.wrapError(`Scan on '${tableName}'`, err);
+        }
+    }
+    /**
+     * Auto-paginating `query()`: DynamoDB caps each `Query` response at 1MB of
+     * data, so a query over more items than that fits in a single page and
+     * returns a `lastEvaluatedKey` that the caller must pass back in as
+     * `exclusiveStartKey` to fetch the next page. Forgetting to loop on that
+     * silently truncates results. `queryAll()` follows `lastEvaluatedKey`
+     * automatically and returns every matching item across all pages.
+     *
+     * `params.limit`, if set, still applies per-page (as DynamoDB defines
+     * it) — it does not cap the total number of items returned here. To
+     * consume pages one at a time instead of buffering everything in memory,
+     * use `queryPages()`.
+     */
+    async queryAll(tableName, params) {
+        const items = [];
+        for await (const page of this.queryPages(tableName, params)) {
+            items.push(...page);
+        }
+        return items;
+    }
+    /**
+     * Async-generator form of `queryAll()`: yields each page of items as it
+     * arrives instead of buffering the entire result set in memory, while
+     * still following `lastEvaluatedKey` automatically.
+     */
+    async *queryPages(tableName, params) {
+        let exclusiveStartKey = params.exclusiveStartKey;
+        do {
+            const result = await this.query(tableName, { ...params, exclusiveStartKey });
+            yield result.items;
+            exclusiveStartKey = result.lastEvaluatedKey;
+        } while (exclusiveStartKey !== undefined);
+    }
+    /**
+     * Auto-paginating `scan()` — see `queryAll()` above for why this matters
+     * (the same 1MB-per-page cap applies to Scan). Reminder: `scan()` is
+     * already O(table size) per the warning on `scan()` itself; `scanAll()`
+     * makes that even more explicit by reading literally the whole table (or
+     * index) into memory across as many pages as it takes.
+     */
+    async scanAll(tableName, params = {}) {
+        const items = [];
+        for await (const page of this.scanPages(tableName, params)) {
+            items.push(...page);
+        }
+        return items;
+    }
+    /** Async-generator form of `scanAll()`; yields each page as it arrives. */
+    async *scanPages(tableName, params = {}) {
+        let exclusiveStartKey = params.exclusiveStartKey;
+        do {
+            const result = await this.scan(tableName, { ...params, exclusiveStartKey });
+            yield result.items;
+            exclusiveStartKey = result.lastEvaluatedKey;
+        } while (exclusiveStartKey !== undefined);
+    }
+    // ---------------------------------------------------------------------
+    // Batch operations
+    // ---------------------------------------------------------------------
+    /** Sleeps for `ms` milliseconds. */
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Exponential backoff with full jitter (AWS's recommended strategy):
+     * a random delay between 0 and `min(maxDelayMs, baseDelayMs * 2^attempt)`.
+     * `attempt` is 0-based (the delay before the *first* retry, i.e. after
+     * the initial attempt has already failed/returned unprocessed items).
+     */
+    backoffDelayMs(attempt, baseDelayMs, maxDelayMs) {
+        const cap = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+        return Math.random() * cap;
+    }
+    /**
+     * BatchGetItem across one or more tables. DynamoDB caps a single
+     * BatchGetItem call at 100 items total; this method chunks `keys`
+     * internally (25-at-a-time chunks well under the limit, sent
+     * sequentially) so callers can pass an arbitrarily large key list without
+     * worrying about the limit themselves. Also retries any
+     * `UnprocessedKeys` DynamoDB returns for a chunk (throttling) with
+     * exponential backoff and jitter between attempts, up to
+     * `options.maxAttempts` (default 5) attempts per chunk, before giving up
+     * and returning whatever's still unprocessed to the caller.
+     */
+    async batchGetItem(tableName, keys, options = {}) {
+        const client = this.requireClient();
+        const chunkSize = Math.min(options.chunkSize ?? MAX_BATCH_GET_ITEMS, MAX_BATCH_GET_ITEMS);
+        const maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+        const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+        const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+        const items = [];
+        const unprocessedKeys = [];
+        for (let i = 0; i < keys.length; i += chunkSize) {
+            const chunk = keys.slice(i, i + chunkSize);
+            try {
+                let requestKeys = chunk;
+                let attempts = 0;
+                while (requestKeys.length > 0 && attempts < maxAttempts) {
+                    if (attempts > 0) {
+                        await this.delay(this.backoffDelayMs(attempts - 1, baseDelayMs, maxDelayMs));
+                    }
+                    const result = await client.send(new lib_dynamodb_1.BatchGetCommand({
+                        RequestItems: {
+                            [tableName]: { Keys: requestKeys, ConsistentRead: options.consistentRead },
+                        },
+                    }));
+                    const fetched = (result.Responses?.[tableName] ?? []);
+                    items.push(...fetched);
+                    const unprocessed = result.UnprocessedKeys?.[tableName]?.Keys;
+                    requestKeys = unprocessed ?? [];
+                    attempts += 1;
+                }
+                if (requestKeys.length > 0) {
+                    unprocessedKeys.push(...requestKeys);
+                }
+            }
+            catch (err) {
+                throw this.wrapError(`BatchGetItem on '${tableName}'`, err);
+            }
+        }
+        return { items, unprocessedKeys };
+    }
+    /**
+     * BatchWriteItem (put and/or delete) against a single table. DynamoDB
+     * caps a single BatchWriteItem call at 25 write requests; this method
+     * chunks `requests` internally so callers can pass an arbitrarily large
+     * batch. Also retries `UnprocessedItems` with exponential backoff and
+     * jitter, up to `options.maxAttempts` (default 5) attempts per chunk,
+     * before returning whatever's left to the caller.
+     */
+    async batchWriteItem(tableName, requests, options = {}) {
+        const client = this.requireClient();
+        const chunkSize = Math.min(options.chunkSize ?? MAX_BATCH_WRITE_ITEMS, MAX_BATCH_WRITE_ITEMS);
+        const maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+        const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+        const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+        let unprocessedCount = 0;
+        const toWriteRequest = (r) => 'put' in r && r.put !== undefined
+            ? { PutRequest: { Item: r.put } }
+            : { DeleteRequest: { Key: r.delete } };
+        for (let i = 0; i < requests.length; i += chunkSize) {
+            const chunk = requests.slice(i, i + chunkSize).map(toWriteRequest);
+            try {
+                let pending = chunk;
+                let attempts = 0;
+                while (pending.length > 0 && attempts < maxAttempts) {
+                    if (attempts > 0) {
+                        await this.delay(this.backoffDelayMs(attempts - 1, baseDelayMs, maxDelayMs));
+                    }
+                    const result = await client.send(new lib_dynamodb_1.BatchWriteCommand({ RequestItems: { [tableName]: pending } }));
+                    const unprocessed = result.UnprocessedItems?.[tableName];
+                    pending = unprocessed ?? [];
+                    attempts += 1;
+                }
+                unprocessedCount += pending.length;
+            }
+            catch (err) {
+                throw this.wrapError(`BatchWriteItem on '${tableName}'`, err);
+            }
+        }
+        return { unprocessedCount };
+    }
+    // ---------------------------------------------------------------------
+    // Transactions (multi-item ACID, up to 100 items across tables)
+    // ---------------------------------------------------------------------
+    /**
+     * Passthrough to DynamoDB's TransactWriteItems — up to 100 Put/Update/
+     * Delete/ConditionCheck actions, atomically, potentially across multiple
+     * tables. Not chunked: DynamoDB rejects the whole transaction if it
+     * exceeds the limit, so it's on the caller to stay under it (unlike the
+     * batch methods above, there's no safe way to silently split a
+     * transaction into several without breaking its atomicity guarantee).
+     */
+    async transactWriteItems(input) {
+        const client = this.requireClient();
+        try {
+            const { transactItems, ...rest } = input;
+            await client.send(new lib_dynamodb_1.TransactWriteCommand({ ...rest, TransactItems: transactItems }));
+        }
+        catch (err) {
+            throw this.wrapError('TransactWriteItems', err);
+        }
+    }
+    /** Passthrough to DynamoDB's TransactGetItems — up to 100 Get actions, read as a single consistent snapshot. */
+    async transactGetItems(input) {
+        const client = this.requireClient();
+        try {
+            const { transactItems, ...rest } = input;
+            const result = await client.send(new lib_dynamodb_1.TransactGetCommand({ ...rest, TransactItems: transactItems }));
+            return (result.Responses ?? []).map((r) => r.Item);
+        }
+        catch (err) {
+            throw this.wrapError('TransactGetItems', err);
+        }
+    }
+    /**
+     * Enables DynamoDB Streams on a table via `UpdateTableCommand`'s
+     * `StreamSpecification`, choosing what a stream record captures:
+     * `KEYS_ONLY` (just the key attributes of the modified item), `NEW_IMAGE`
+     * (the entire item as it appears after modification), `OLD_IMAGE` (as it
+     * appeared before), or `NEW_AND_OLD_IMAGES` (both). This only flips the
+     * table-level setting and returns the ARN DynamoDB assigns the new
+     * stream — it does not read from the stream itself; see "Known
+     * limitations" in the README for why a stream *consumer* is out of scope
+     * for this store.
+     */
+    async enableStreams(tableName, streamViewType) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.UpdateTableCommand({
+                TableName: tableName,
+                StreamSpecification: {
+                    StreamEnabled: true,
+                    StreamViewType: streamViewType,
+                },
+            }));
+            return result.TableDescription?.LatestStreamArn;
+        }
+        catch (err) {
+            throw this.wrapError(`UpdateTable (enableStreams) on '${tableName}'`, err);
+        }
+    }
+    /** Disables DynamoDB Streams on a table via `UpdateTableCommand`. */
+    async disableStreams(tableName) {
+        const client = this.getRawClient();
+        try {
+            await client.send(new client_dynamodb_1.UpdateTableCommand({
+                TableName: tableName,
+                StreamSpecification: { StreamEnabled: false },
+            }));
+        }
+        catch (err) {
+            throw this.wrapError(`UpdateTable (disableStreams) on '${tableName}'`, err);
+        }
+    }
+    /**
+     * Reads back the table's current stream ARN (`undefined` if streams
+     * aren't enabled) via `DescribeTableCommand`. Consuming the stream itself
+     * (shard iterators / record polling) requires the separate
+     * `@aws-sdk/client-dynamodb-streams` package or a Lambda event source
+     * mapping — out of scope here, see the README.
+     */
+    async getStreamArn(tableName) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.DescribeTableCommand({ TableName: tableName }));
+            return result.Table?.LatestStreamArn;
+        }
+        catch (err) {
+            throw this.wrapError(`DescribeTable (getStreamArn) on '${tableName}'`, err);
+        }
+    }
+    /**
+     * Enables TTL on a table via `UpdateTimeToLiveCommand`: DynamoDB
+     * periodically (usually within 48 hours, not immediately) deletes items
+     * whose `attributeName` holds a Unix epoch-seconds number in the past.
+     * A table may only have one TTL attribute at a time.
+     */
+    async enableTTL(tableName, attributeName) {
+        const client = this.getRawClient();
+        try {
+            await client.send(new client_dynamodb_1.UpdateTimeToLiveCommand({
+                TableName: tableName,
+                TimeToLiveSpecification: { Enabled: true, AttributeName: attributeName },
+            }));
+        }
+        catch (err) {
+            throw this.wrapError(`UpdateTimeToLive (enableTTL) on '${tableName}'`, err);
+        }
+    }
+    /**
+     * Disables TTL on a table. DynamoDB requires the currently-enabled
+     * `AttributeName` to be repeated on the disabling call, so this first
+     * reads it back via `describeTTL()` and is a no-op if TTL isn't
+     * currently enabled on the table.
+     */
+    async disableTTL(tableName) {
+        const client = this.getRawClient();
+        const current = await this.describeTTL(tableName);
+        const attributeName = current.attributeName;
+        if (!attributeName)
+            return;
+        try {
+            await client.send(new client_dynamodb_1.UpdateTimeToLiveCommand({
+                TableName: tableName,
+                TimeToLiveSpecification: { Enabled: false, AttributeName: attributeName },
+            }));
+        }
+        catch (err) {
+            throw this.wrapError(`UpdateTimeToLive (disableTTL) on '${tableName}'`, err);
+        }
+    }
+    /** Reads back a table's TTL configuration via `DescribeTimeToLiveCommand`. */
+    async describeTTL(tableName) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.DescribeTimeToLiveCommand({ TableName: tableName }));
+            return {
+                status: result.TimeToLiveDescription?.TimeToLiveStatus,
+                attributeName: result.TimeToLiveDescription?.AttributeName,
+            };
+        }
+        catch (err) {
+            throw this.wrapError(`DescribeTimeToLive on '${tableName}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Table lifecycle
+    // ---------------------------------------------------------------------
+    /**
+     * Creates a table via `CreateTableCommand`. Thin passthrough to the raw
+     * SDK input shape: `params.TableName`, `params.KeySchema`, and
+     * `params.AttributeDefinitions` are required (as real CreateTable
+     * requires), plus either `params.BillingMode: 'PAY_PER_REQUEST'` or
+     * `params.ProvisionedThroughput` (real CreateTable requires one or the
+     * other), and optionally `params.GlobalSecondaryIndexes`/
+     * `params.LocalSecondaryIndexes`. Table creation is asynchronous on AWS's
+     * side (the table starts in `CREATING` status) — this call returns as
+     * soon as DynamoDB accepts the request, it does not wait for the table to
+     * become `ACTIVE`; poll `describeTable()` if you need to wait.
+     */
+    async createTable(params) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.CreateTableCommand(params));
+            return result.TableDescription;
+        }
+        catch (err) {
+            throw this.wrapError(`CreateTable on '${params.TableName}'`, err);
+        }
+    }
+    /**
+     * Deletes a table via `DeleteTableCommand`. Like `createTable()`, this is
+     * asynchronous on AWS's side (the table moves to `DELETING` status); this
+     * call returns as soon as DynamoDB accepts the request.
+     */
+    async deleteTable(tableName) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.DeleteTableCommand({ TableName: tableName }));
+            return result.TableDescription;
+        }
+        catch (err) {
+            throw this.wrapError(`DeleteTable on '${tableName}'`, err);
+        }
+    }
+    /**
+     * Lists table names in the current account/region via `ListTablesCommand`.
+     * A single call returns at most 100 table names (or `params.limit` if
+     * lower); pass `params.exclusiveStartTableName` (from a previous call's
+     * `lastEvaluatedTableName`) to page through the rest.
+     */
+    async listTables(params = {}) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.ListTablesCommand({
+                ExclusiveStartTableName: params.exclusiveStartTableName,
+                Limit: params.limit,
+            }));
+            return {
+                tableNames: result.TableNames ?? [],
+                lastEvaluatedTableName: result.LastEvaluatedTableName,
+            };
+        }
+        catch (err) {
+            throw this.wrapError('ListTables', err);
+        }
+    }
+    /**
+     * Reads back a table's full description (status, key schema, billing
+     * mode, indexes, stream ARN, item count, etc.) via `DescribeTableCommand`.
+     * `getStreamArn()` above is a narrow convenience wrapper around this same
+     * command for just the stream ARN.
+     */
+    async describeTable(tableName) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.DescribeTableCommand({ TableName: tableName }));
+            return result.Table;
+        }
+        catch (err) {
+            throw this.wrapError(`DescribeTable on '${tableName}'`, err);
+        }
+    }
+    /**
+     * Adds or removes a Global Secondary Index on an existing table via
+     * `UpdateTableCommand`'s `GlobalSecondaryIndexUpdates`. DynamoDB only
+     * allows one GSI create/delete/update action per `UpdateTable` call, so
+     * `gsiUpdates` must contain exactly one `GlobalSecondaryIndexUpdate`
+     * entry (`{ Create: {...} }`, `{ Update: {...} }`, or `{ Delete: {...} }`).
+     * When creating a new GSI, `attributeDefinitions` must include the key
+     * attribute(s) of the new index (DynamoDB validates this).
+     */
+    async updateTableIndexes(tableName, gsiUpdates, attributeDefinitions) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.UpdateTableCommand({
+                TableName: tableName,
+                GlobalSecondaryIndexUpdates: gsiUpdates,
+                AttributeDefinitions: attributeDefinitions,
+            }));
+            return result.TableDescription;
+        }
+        catch (err) {
+            throw this.wrapError(`UpdateTable (updateTableIndexes) on '${tableName}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Billing/capacity mode
+    // ---------------------------------------------------------------------
+    /**
+     * Switches a table between on-demand (`PAY_PER_REQUEST`) and provisioned
+     * (`PROVISIONED`) capacity via `UpdateTableCommand`. When switching to
+     * `PROVISIONED`, `throughput` (`ReadCapacityUnits`/`WriteCapacityUnits`)
+     * is required (real DynamoDB rejects the call without it); it's ignored
+     * when switching to `PAY_PER_REQUEST`.
+     */
+    async updateBillingMode(tableName, mode, throughput) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.UpdateTableCommand({
+                TableName: tableName,
+                BillingMode: mode,
+                ProvisionedThroughput: mode === 'PROVISIONED' ? throughput : undefined,
+            }));
+            return result.TableDescription;
+        }
+        catch (err) {
+            throw this.wrapError(`UpdateTable (updateBillingMode) on '${tableName}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Point-in-Time Recovery (PITR)
+    // ---------------------------------------------------------------------
+    /**
+     * Enables Point-in-Time Recovery on a table via
+     * `UpdateContinuousBackupsCommand`, allowing restore to any second within
+     * the retention window (35 days by default; DynamoDB currently ignores
+     * a custom `recoveryPeriodInDays` on enable and defaults to 35).
+     */
+    async enablePITR(tableName) {
+        const client = this.getRawClient();
+        try {
+            await client.send(new client_dynamodb_1.UpdateContinuousBackupsCommand({
+                TableName: tableName,
+                PointInTimeRecoverySpecification: { PointInTimeRecoveryEnabled: true },
+            }));
+        }
+        catch (err) {
+            throw this.wrapError(`UpdateContinuousBackups (enablePITR) on '${tableName}'`, err);
+        }
+    }
+    /** Disables Point-in-Time Recovery on a table via `UpdateContinuousBackupsCommand`. */
+    async disablePITR(tableName) {
+        const client = this.getRawClient();
+        try {
+            await client.send(new client_dynamodb_1.UpdateContinuousBackupsCommand({
+                TableName: tableName,
+                PointInTimeRecoverySpecification: { PointInTimeRecoveryEnabled: false },
+            }));
+        }
+        catch (err) {
+            throw this.wrapError(`UpdateContinuousBackups (disablePITR) on '${tableName}'`, err);
+        }
+    }
+    /** Reads back a table's PITR configuration via `DescribeContinuousBackupsCommand`. */
+    async describePITR(tableName) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.DescribeContinuousBackupsCommand({ TableName: tableName }));
+            const pitr = result.ContinuousBackupsDescription?.PointInTimeRecoveryDescription;
+            return {
+                status: pitr?.PointInTimeRecoveryStatus,
+                recoveryPeriodInDays: pitr?.RecoveryPeriodInDays,
+                earliestRestorableDateTime: pitr?.EarliestRestorableDateTime,
+                latestRestorableDateTime: pitr?.LatestRestorableDateTime,
+            };
+        }
+        catch (err) {
+            throw this.wrapError(`DescribeContinuousBackups on '${tableName}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // On-demand backup/restore
+    // ---------------------------------------------------------------------
+    //
+    // Distinct from PITR above: these are named, on-demand snapshots (created
+    // explicitly, kept until deleted) rather than the continuous, rolling
+    // 35-day recovery window PITR provides.
+    /** Creates an on-demand backup of a table via `CreateBackupCommand`. */
+    async createBackup(tableName, backupName) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.CreateBackupCommand({ TableName: tableName, BackupName: backupName }));
+            return result.BackupDetails;
+        }
+        catch (err) {
+            throw this.wrapError(`CreateBackup on '${tableName}'`, err);
+        }
+    }
+    /** Reads back a backup's full description via `DescribeBackupCommand`. */
+    async describeBackup(backupArn) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.DescribeBackupCommand({ BackupArn: backupArn }));
+            return result.BackupDescription;
+        }
+        catch (err) {
+            throw this.wrapError(`DescribeBackup on '${backupArn}'`, err);
+        }
+    }
+    /**
+     * Lists backups via `ListBackupsCommand`, optionally scoped to a single
+     * table. Does not auto-paginate — pass the last item's `BackupArn` back
+     * in as `exclusiveStartBackupArn` to fetch the next page, same pattern as
+     * `listTables()`.
+     */
+    async listBackups(tableName, options = {}) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.ListBackupsCommand({
+                TableName: tableName,
+                Limit: options.limit,
+                ExclusiveStartBackupArn: options.exclusiveStartBackupArn,
+            }));
+            return result.BackupSummaries ?? [];
+        }
+        catch (err) {
+            throw this.wrapError('ListBackups', err);
+        }
+    }
+    /**
+     * Restores a backup into a new table via `RestoreTableFromBackupCommand`.
+     * DynamoDB always restores into a *new* table (`newTableName` must not
+     * already exist) — it does not overwrite the original table the backup
+     * was taken from. Like `createTable()`, this is asynchronous: the new
+     * table starts in `CREATING` status.
+     */
+    async restoreTableFromBackup(backupArn, newTableName) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.RestoreTableFromBackupCommand({ BackupArn: backupArn, TargetTableName: newTableName }));
+            return result.TableDescription;
+        }
+        catch (err) {
+            throw this.wrapError(`RestoreTableFromBackup to '${newTableName}'`, err);
+        }
+    }
+    // ---------------------------------------------------------------------
+    // Tagging
+    // ---------------------------------------------------------------------
+    /** Adds (or updates, if the key already exists) tags on a table/backup resource via `TagResourceCommand`. */
+    async tagResource(resourceArn, tags) {
+        const client = this.getRawClient();
+        const Tags = Array.isArray(tags)
+            ? tags
+            : Object.entries(tags).map(([Key, Value]) => ({ Key, Value }));
+        try {
+            await client.send(new client_dynamodb_1.TagResourceCommand({ ResourceArn: resourceArn, Tags }));
+        }
+        catch (err) {
+            throw this.wrapError(`TagResource on '${resourceArn}'`, err);
+        }
+    }
+    /** Removes tags (by key) from a table/backup resource via `UntagResourceCommand`. */
+    async untagResource(resourceArn, tagKeys) {
+        const client = this.getRawClient();
+        try {
+            await client.send(new client_dynamodb_1.UntagResourceCommand({ ResourceArn: resourceArn, TagKeys: tagKeys }));
+        }
+        catch (err) {
+            throw this.wrapError(`UntagResource on '${resourceArn}'`, err);
+        }
+    }
+    /**
+     * Lists tags on a table/backup resource via `ListTagsOfResourceCommand`.
+     * Does not auto-paginate — pass a returned `nextToken` back in as
+     * `options.nextToken` to fetch the next page.
+     */
+    async listTags(resourceArn, options = {}) {
+        const client = this.getRawClient();
+        try {
+            const result = await client.send(new client_dynamodb_1.ListTagsOfResourceCommand({ ResourceArn: resourceArn, NextToken: options.nextToken }));
+            return { tags: result.Tags ?? [], nextToken: result.NextToken };
+        }
+        catch (err) {
+            throw this.wrapError(`ListTagsOfResource on '${resourceArn}'`, err);
+        }
+    }
+}
+exports.DynamoDbStore = DynamoDbStore;