ts-prorm-orm 1.1.0 → 1.2.0

package/dist/nosql/dynamodb/index.d.ts

@@ -0,0 +1,643 @@
+/**
+ * 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.
+ */
+import { DynamoDBClient, type DynamoDBClientConfig, type UpdateTableCommandInput, type CreateTableCommandInput, type StreamViewType, type TimeToLiveStatus, type TableDescription, type GlobalSecondaryIndexUpdate, type BillingMode, type ProvisionedThroughput, type PointInTimeRecoveryStatus, type BackupSummary, type BackupDescription, type Tag } from '@aws-sdk/client-dynamodb';
+import { DynamoDBDocumentClient, type PutCommandInput, type UpdateCommandInput, type DeleteCommandInput, type TransactGetCommandInput, type TransactWriteCommandInput, type TranslateConfig } from '@aws-sdk/lib-dynamodb';
+import { DatabaseError } from '../../errors';
+import type { NoSqlStore } from '../store';
+/** Plain JS object representing a DynamoDB item/key (no raw AttributeValues). */
+export type DynamoDbItem = Record<string, unknown>;
+/**
+ * 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.
+ */
+export declare enum DynamoReturnValues {
+    None = "NONE",
+    AllOld = "ALL_OLD",
+    AllNew = "ALL_NEW",
+    UpdatedOld = "UPDATED_OLD",
+    UpdatedNew = "UPDATED_NEW"
+}
+/**
+ * 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.
+ */
+export declare enum DynamoStreamViewType {
+    NewImage = "NEW_IMAGE",
+    OldImage = "OLD_IMAGE",
+    NewAndOldImages = "NEW_AND_OLD_IMAGES",
+    KeysOnly = "KEYS_ONLY"
+}
+export interface DynamoDbStoreOptions {
+    /** AWS region, e.g. 'us-east-1'. Required unless using a local endpoint that ignores it. */
+    region?: string;
+    /** Static credentials. Omit to fall back to the default AWS credential provider chain. */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    /**
+     * Override the service endpoint, e.g. 'http://localhost:8000' for
+     * DynamoDB Local / dynamodb-local test containers. When set, region and
+     * credentials can be dummy values since DynamoDB Local doesn't validate them.
+     */
+    endpoint?: string;
+    /** Passed straight through to the underlying `DynamoDBClient` constructor for anything not covered above. */
+    clientConfig?: DynamoDBClientConfig;
+    /** Marshalling options for the document client (e.g. `{ removeUndefinedValues: true }`). */
+    translateConfig?: TranslateConfig;
+}
+export interface PutItemOptions {
+    /** Conditional write, e.g. 'attribute_not_exists(pk)' to emulate an insert-only put. */
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    /**
+     * PutItem only supports `'NONE'` (default) or `'ALL_OLD'` (returns the
+     * item's previous value if one existed, or nothing if it didn't) —
+     * unlike UpdateItem, there is no `ALL_NEW`/`UPDATED_*` variant since a Put
+     * always writes the whole item.
+     */
+    returnValues?: PutCommandInput['ReturnValues'] | DynamoReturnValues;
+}
+export interface UpdateItemOptions {
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    returnValues?: UpdateCommandInput['ReturnValues'] | DynamoReturnValues;
+}
+export interface DeleteItemOptions {
+    conditionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    /**
+     * Defaults to `'ALL_OLD'` (returns the deleted item) for backwards
+     * compatibility. Pass `'NONE'` to skip returning the deleted item when
+     * the caller doesn't need it (saves a small amount of response payload).
+     */
+    returnValues?: DeleteCommandInput['ReturnValues'] | DynamoReturnValues;
+}
+/** Options controlling the retry/backoff behavior of `batchGetItem`/`batchWriteItem`. */
+export interface BatchRetryOptions {
+    /**
+     * Maximum number of attempts per chunk (the initial request plus
+     * retries) when DynamoDB returns `UnprocessedKeys`/`UnprocessedItems`
+     * (typically due to throttling). Defaults to 5.
+     */
+    maxAttempts?: number;
+    /** Base delay in ms for exponential backoff between retries. Defaults to 50ms. */
+    baseDelayMs?: number;
+    /** Cap on the backoff delay in ms, before jitter is applied. Defaults to 2000ms. */
+    maxDelayMs?: number;
+}
+export interface QueryParams {
+    /** Name of a Global or Local Secondary Index to query instead of the base table. */
+    indexName?: string;
+    /** e.g. 'pk = :pk' */
+    keyConditionExpression: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    /** Applied after the key condition, does not reduce RCU consumption. */
+    filterExpression?: string;
+    /**
+     * Restricts which attributes are returned, e.g. `'#n, total'`. Use
+     * `expressionAttributeNames` for any reserved-word-safe `#alias` tokens
+     * referenced here, same as `keyConditionExpression`/`filterExpression`.
+     */
+    projectionExpression?: string;
+    limit?: number;
+    scanIndexForward?: boolean;
+    /** Pagination cursor from a previous page's `lastEvaluatedKey`. */
+    exclusiveStartKey?: DynamoDbItem;
+    consistentRead?: boolean;
+}
+export interface QueryResult<T extends DynamoDbItem = DynamoDbItem> {
+    items: T[];
+    /** Present when there are more pages; pass back in as `exclusiveStartKey` to continue. */
+    lastEvaluatedKey?: DynamoDbItem;
+    count: number;
+    scannedCount: number;
+}
+export interface ScanParams {
+    indexName?: string;
+    filterExpression?: string;
+    /**
+     * Restricts which attributes are returned. Use `expressionAttributeNames`
+     * for any `#alias` tokens referenced here (same rules as `getItem()`).
+     */
+    projectionExpression?: string;
+    expressionAttributeNames?: Record<string, string>;
+    expressionAttributeValues?: Record<string, unknown>;
+    limit?: number;
+    exclusiveStartKey?: DynamoDbItem;
+    consistentRead?: boolean;
+    /** For parallel scans: this segment's index (0-based). */
+    segment?: number;
+    /** For parallel scans: total number of segments. */
+    totalSegments?: number;
+}
+export type ScanResult<T extends DynamoDbItem = DynamoDbItem> = QueryResult<T>;
+/**
+ * Describes a single item update for `updateItem()`'s convenience API. Each
+ * entry SETs `attributeName` to `value`. For anything beyond a flat SET
+ * (REMOVE, ADD, DELETE, nested paths), build an `UpdateExpression` by hand
+ * and call the document client returned by `getClient()` directly, or pass
+ * a raw `UpdateCommandInput` via `updateItemRaw()`.
+ */
+export type UpdateAttributes = Record<string, unknown>;
+/**
+ * One entry of a `TransactionCanceledException.CancellationReasons` list —
+ * DynamoDB's per-item explanation of why a `TransactWriteItems`/
+ * `TransactGetItems` call was cancelled (e.g. a `ConditionCheck` failing on
+ * one specific item). `item` is the raw (still-marshalled, `{ S: 'foo' }`
+ * style) `AttributeValue` map DynamoDB includes for the failing item, if
+ * any — this store doesn't depend on `@aws-sdk/util-dynamodb` to unmarshal
+ * it, so callers that want a plain object should unmarshal it themselves.
+ */
+export interface DynamoDbCancellationReason {
+    /** Status code for why this item's part of the transaction was cancelled, e.g. 'ConditionalCheckFailed', 'None'. */
+    code?: string;
+    /** Human-readable description of the cancellation reason. */
+    message?: string;
+    /** Raw (marshalled) AttributeValue map of the item that caused the cancellation, if DynamoDB returned one. */
+    item?: Record<string, unknown>;
+}
+/**
+ * `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`.
+ */
+export declare class DynamoDbError extends DatabaseError {
+    /**
+     * Per-item cancellation reasons from a `TransactionCanceledException`,
+     * in the same order as the `transactItems` request. Undefined for any
+     * other kind of error.
+     */
+    readonly cancellationReasons?: DynamoDbCancellationReason[];
+    constructor(message: string, options?: {
+        code?: import('../../errors').ErrorCode;
+        parent?: Error;
+        sql?: string;
+        original?: string;
+        cancellationReasons?: DynamoDbCancellationReason[];
+    });
+}
+/** Result of `listTables()`. */
+export interface ListTablesResult {
+    tableNames: string[];
+    /** Present when there are more pages; pass back in as `exclusiveStartTableName` to continue. */
+    lastEvaluatedTableName?: string;
+}
+/** Result of `describePITR()`. */
+export interface PitrDescription {
+    status: PointInTimeRecoveryStatus | undefined;
+    recoveryPeriodInDays?: number;
+    earliestRestorableDateTime?: Date;
+    latestRestorableDateTime?: Date;
+}
+/**
+ * Describes a table's (or index's) key attributes so the ORM layer can pick
+ * `Query` vs `Scan` and extract item keys for update/delete. Supply this to
+ * {@link DynamoDbStore.findAll} et al. via the `key` option (or per-index via
+ * `indexes`).
+ */
+export interface DynamoKeySchema {
+    /** Partition (HASH) key attribute name. */
+    partitionKey: string;
+    /** Optional sort (RANGE) key attribute name. */
+    sortKey?: string;
+    /** Key schemas for named GSIs/LSIs, so a query can target an index. */
+    indexes?: Record<string, {
+        partitionKey: string;
+        sortKey?: string;
+    }>;
+}
+/** Options for {@link DynamoDbStore.findAll}/{@link DynamoDbStore.findOne}. */
+export interface DynamoFindOptions {
+    /** ORM `where` clause (plain equality and/or `Op`-keyed conditions). */
+    where?: Record<string, any>;
+    /** Key schema; enables `Query` (vs `Scan`) and key extraction. */
+    key?: DynamoKeySchema;
+    /** Query a named GSI/LSI (its schema must be in `key.indexes`). */
+    indexName?: string;
+    /** Restrict returned attributes (compiled to a ProjectionExpression). */
+    attributes?: string[];
+    /** Sort-key ordering for `Query` results: `'ASC'` (default) or `'DESC'`. */
+    order?: 'ASC' | 'DESC';
+    /** Per-page item cap. */
+    limit?: number;
+    /** Pagination cursor from a previous page's `lastEvaluatedKey`. */
+    exclusiveStartKey?: DynamoDbItem;
+    /** Strongly-consistent read (base table only; not valid on a GSI). */
+    consistentRead?: boolean;
+}
+/**
+ * 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.
+ */
+export declare class DynamoDbStore implements NoSqlStore {
+    readonly name = "dynamodb";
+    readonly library = "@aws-sdk/client-dynamodb";
+    private readonly options;
+    private client;
+    private docClient;
+    private connected;
+    constructor(options?: DynamoDbStoreOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    /** Returns the `DynamoDBDocumentClient` (plain-object marshalling), not the raw `DynamoDBClient`. */
+    getClient(): DynamoDBDocumentClient;
+    /** Access to the low-level `DynamoDBClient` (raw `AttributeValue` shapes), for anything the document client doesn't cover. */
+    getRawClient(): DynamoDBClient;
+    private requireClient;
+    /**
+     * 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.
+     */
+    private wrapError;
+    getItem<T extends DynamoDbItem = DynamoDbItem>(tableName: string, key: DynamoDbItem, options?: {
+        consistentRead?: boolean;
+        projectionExpression?: string;
+    }): Promise<T | undefined>;
+    /**
+     * `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).
+     */
+    putItem<T extends DynamoDbItem = DynamoDbItem>(tableName: string, item: T, options?: PutItemOptions): Promise<T | undefined>;
+    /**
+     * 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()`.
+     */
+    updateItem<T extends DynamoDbItem = DynamoDbItem>(tableName: string, key: DynamoDbItem, updates: UpdateAttributes, options?: UpdateItemOptions): Promise<T | undefined>;
+    /** Escape hatch for update expressions beyond the flat-SET convenience wrapper above (REMOVE/ADD/DELETE, nested paths, etc). */
+    updateItemRaw<T extends DynamoDbItem = DynamoDbItem>(tableName: string, input: UpdateCommandInput): Promise<T | undefined>;
+    /** `options.returnValues` defaults to `'ALL_OLD'` (returns the deleted item); pass `'NONE'` to skip returning it. */
+    deleteItem<T extends DynamoDbItem = DynamoDbItem>(tableName: string, key: DynamoDbItem, options?: DeleteItemOptions): Promise<T | undefined>;
+    /**
+     * 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.
+     */
+    query<T extends DynamoDbItem = DynamoDbItem>(tableName: string, params: QueryParams): Promise<QueryResult<T>>;
+    /**
+     * 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.
+     */
+    scan<T extends DynamoDbItem = DynamoDbItem>(tableName: string, params?: ScanParams): Promise<ScanResult<T>>;
+    /**
+     * 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()`.
+     */
+    queryAll<T extends DynamoDbItem = DynamoDbItem>(tableName: string, params: QueryParams): Promise<T[]>;
+    /**
+     * 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.
+     */
+    queryPages<T extends DynamoDbItem = DynamoDbItem>(tableName: string, params: QueryParams): AsyncGenerator<T[], void, void>;
+    /**
+     * 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.
+     */
+    scanAll<T extends DynamoDbItem = DynamoDbItem>(tableName: string, params?: ScanParams): Promise<T[]>;
+    /** Async-generator form of `scanAll()`; yields each page as it arrives. */
+    scanPages<T extends DynamoDbItem = DynamoDbItem>(tableName: string, params?: ScanParams): AsyncGenerator<T[], void, void>;
+    /** Sleeps for `ms` milliseconds. */
+    private delay;
+    /**
+     * 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).
+     */
+    private backoffDelayMs;
+    /**
+     * 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.
+     */
+    batchGetItem<T extends DynamoDbItem = DynamoDbItem>(tableName: string, keys: DynamoDbItem[], options?: {
+        consistentRead?: boolean;
+        chunkSize?: number;
+    } & BatchRetryOptions): Promise<{
+        items: T[];
+        unprocessedKeys: DynamoDbItem[];
+    }>;
+    /**
+     * 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.
+     */
+    batchWriteItem<T extends DynamoDbItem = DynamoDbItem>(tableName: string, requests: Array<{
+        put?: T;
+    } | {
+        delete: DynamoDbItem;
+    }>, options?: {
+        chunkSize?: number;
+    } & BatchRetryOptions): Promise<{
+        unprocessedCount: number;
+    }>;
+    /**
+     * 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).
+     */
+    transactWriteItems(input: Omit<TransactWriteCommandInput, 'TransactItems'> & {
+        transactItems: TransactWriteCommandInput['TransactItems'];
+    }): Promise<void>;
+    /** Passthrough to DynamoDB's TransactGetItems — up to 100 Get actions, read as a single consistent snapshot. */
+    transactGetItems<T extends DynamoDbItem = DynamoDbItem>(input: Omit<TransactGetCommandInput, 'TransactItems'> & {
+        transactItems: TransactGetCommandInput['TransactItems'];
+    }): Promise<Array<T | undefined>>;
+    /**
+     * 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.
+     */
+    enableStreams(tableName: string, streamViewType: StreamViewType | DynamoStreamViewType): Promise<string | undefined>;
+    /** Disables DynamoDB Streams on a table via `UpdateTableCommand`. */
+    disableStreams(tableName: string): Promise<void>;
+    /**
+     * 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.
+     */
+    getStreamArn(tableName: string): Promise<string | undefined>;
+    /**
+     * 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.
+     */
+    enableTTL(tableName: string, attributeName: string): Promise<void>;
+    /**
+     * 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.
+     */
+    disableTTL(tableName: string): Promise<void>;
+    /** Reads back a table's TTL configuration via `DescribeTimeToLiveCommand`. */
+    describeTTL(tableName: string): Promise<{
+        status: TimeToLiveStatus | undefined;
+        attributeName: string | undefined;
+    }>;
+    /**
+     * 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.
+     */
+    createTable(params: CreateTableCommandInput): Promise<TableDescription | undefined>;
+    /**
+     * 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.
+     */
+    deleteTable(tableName: string): Promise<TableDescription | undefined>;
+    /**
+     * 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.
+     */
+    listTables(params?: {
+        exclusiveStartTableName?: string;
+        limit?: number;
+    }): Promise<ListTablesResult>;
+    /**
+     * 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.
+     */
+    describeTable(tableName: string): Promise<TableDescription | undefined>;
+    /**
+     * 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).
+     */
+    updateTableIndexes(tableName: string, gsiUpdates: GlobalSecondaryIndexUpdate[], attributeDefinitions?: UpdateTableCommandInput['AttributeDefinitions']): Promise<TableDescription | undefined>;
+    /**
+     * 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`.
+     */
+    updateBillingMode(tableName: string, mode: BillingMode | 'PAY_PER_REQUEST' | 'PROVISIONED', throughput?: ProvisionedThroughput): Promise<TableDescription | undefined>;
+    /**
+     * 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).
+     */
+    enablePITR(tableName: string): Promise<void>;
+    /** Disables Point-in-Time Recovery on a table via `UpdateContinuousBackupsCommand`. */
+    disablePITR(tableName: string): Promise<void>;
+    /** Reads back a table's PITR configuration via `DescribeContinuousBackupsCommand`. */
+    describePITR(tableName: string): Promise<PitrDescription>;
+    /** Creates an on-demand backup of a table via `CreateBackupCommand`. */
+    createBackup(tableName: string, backupName: string): Promise<BackupDescription['BackupDetails']>;
+    /** Reads back a backup's full description via `DescribeBackupCommand`. */
+    describeBackup(backupArn: string): Promise<BackupDescription | undefined>;
+    /**
+     * 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()`.
+     */
+    listBackups(tableName?: string, options?: {
+        limit?: number;
+        exclusiveStartBackupArn?: string;
+    }): Promise<BackupSummary[]>;
+    /**
+     * 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.
+     */
+    restoreTableFromBackup(backupArn: string, newTableName: string): Promise<TableDescription | undefined>;
+    /** Adds (or updates, if the key already exists) tags on a table/backup resource via `TagResourceCommand`. */
+    tagResource(resourceArn: string, tags: Record<string, string> | Tag[]): Promise<void>;
+    /** Removes tags (by key) from a table/backup resource via `UntagResourceCommand`. */
+    untagResource(resourceArn: string, tagKeys: string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    listTags(resourceArn: string, options?: {
+        nextToken?: string;
+    }): Promise<{
+        tags: Tag[];
+        nextToken?: string;
+    }>;
+    /**
+     * Compile an ORM `where` clause + read options into either a `QueryParams`
+     * (when the partition key is pinned by equality, so DynamoDB can Query) or a
+     * `ScanParams` (otherwise). Shared by {@link findAll}/{@link findAllPaged}/
+     * {@link count}.
+     */
+    private compileRead;
+    /**
+     * Fetch items matching the ORM `where` clause. When `options.key` pins the
+     * partition key by equality this issues an efficient `Query`; otherwise it
+     * falls back to a `Scan` (see the warning on {@link scan}). Returns a single
+     * page plus the `lastEvaluatedKey` cursor (pass it back as
+     * `exclusiveStartKey` for the next page, or use {@link findAll} to
+     * auto-paginate).
+     */
+    findAllPaged<T extends DynamoDbItem = DynamoDbItem>(tableName: string, options?: DynamoFindOptions): Promise<QueryResult<T>>;
+    /**
+     * Auto-paginating {@link findAllPaged}: follows `lastEvaluatedKey` and
+     * returns every matching item. `options.limit` still applies per page (as
+     * DynamoDB defines it); to cap total results, slice the return value.
+     */
+    findAll<T extends DynamoDbItem = DynamoDbItem>(tableName: string, options?: DynamoFindOptions): Promise<T[]>;
+    /** Fetch the first item matching `where` (page-limited to 1), or `undefined`. */
+    findOne<T extends DynamoDbItem = DynamoDbItem>(tableName: string, options?: DynamoFindOptions): Promise<T | undefined>;
+    /**
+     * Count items matching `where` using `Select: 'COUNT'` (server-side count;
+     * items are not returned). Follows pagination automatically and sums each
+     * page's count.
+     */
+    count(tableName: string, options?: DynamoFindOptions): Promise<number>;
+    /**
+     * Insert an item (`PutItem`). By default overwrites any existing item with
+     * the same key (native Put semantics); pass `options.key` with
+     * `options.insertOnly` to add an `attribute_not_exists(<pk>)` condition so a
+     * duplicate primary key fails instead (SQL `INSERT` semantics).
+     */
+    create<T extends DynamoDbItem = DynamoDbItem>(tableName: string, item: T, options?: {
+        key?: DynamoKeySchema;
+        insertOnly?: boolean;
+    }): Promise<T>;
+    /** Insert many items via chunked/retried `BatchWriteItem` puts. */
+    bulkCreate<T extends DynamoDbItem = DynamoDbItem>(tableName: string, items: T[], options?: BatchRetryOptions & {
+        chunkSize?: number;
+    }): Promise<{
+        inserted: number;
+        unprocessedCount: number;
+    }>;
+    /**
+     * Insert-or-replace an item (`PutItem`) — DynamoDB's native Put already has
+     * upsert semantics (it creates the item or overwrites it wholesale).
+     */
+    upsert<T extends DynamoDbItem = DynamoDbItem>(tableName: string, item: T): Promise<T>;
+    /** Extract a full primary key `{pk, sk?}` from top-level eq leaves, or null. */
+    private extractFullKey;
+    /**
+     * Update every item matching `where`, SETting each key in `values`. When
+     * `where` pins the full primary key (and nothing else), this is a single
+     * `UpdateItem`; otherwise it finds matching items (Query/Scan via `key`),
+     * then issues one `UpdateItem` per item. Requires `options.key`. Returns the
+     * number of items updated.
+     */
+    update(tableName: string, values: UpdateAttributes, where: Record<string, any>, options?: {
+        key: DynamoKeySchema;
+        indexName?: string;
+    }): Promise<number>;
+    /**
+     * Delete every item matching `where`. When `where` pins the full primary key
+     * this is a single `DeleteItem`; otherwise it finds matching items and
+     * deletes them via chunked `BatchWriteItem`. Requires `options.key`. Returns
+     * the number of items deleted.
+     */
+    destroy(tableName: string, where: Record<string, any>, options?: {
+        key: DynamoKeySchema;
+        indexName?: string;
+    }): Promise<number>;
+    /** Project an item down to just its key attributes for the given schema. */
+    private itemKey;
+}