dyno-table 2.2.0 → 2.3.0

package/dist/table.d.cts

@@ -1,13 +1,164 @@
-import './batch-builder-BPoHyN_Q.cjs';
-import './builders/condition-check-builder.cjs';
-import './builders/delete-builder.cjs';
-import './builders/put-builder.cjs';
-import './query-builder-DoZzZz_c.cjs';
-export { T as Table } from './table-f-3wsT7K.cjs';
-import './builders/transaction-builder.cjs';
-import './builders/update-builder.cjs';
-import './conditions-CC3NDfUU.cjs';
-import './types.cjs';
-import './builder-types-BTVhQSHI.cjs';
+import { P as PutBuilder, G as GetBuilder, Q as QueryBuilder, S as ScanBuilder, D as DeleteBuilder, U as UpdateBuilder, T as TransactionBuilder, B as BatchBuilder, f as TransactionOptions, C as ConditionCheckBuilder, h as BatchWriteOperation } from './index-DlN8G9hd.cjs';
+import { c as PrimaryKeyWithoutExpression, P as PrimaryKey } from './conditions-CcZL0sR2.cjs';
+import { TableConfig, Index, DynamoItem } from './types.cjs';
 import '@aws-sdk/lib-dynamodb';
-import './builders/paginator.cjs';
+
+declare class Table<TConfig extends TableConfig = TableConfig> {
+    private readonly dynamoClient;
+    readonly tableName: string;
+    /**
+     * The column name of the partitionKey for the Table
+     */
+    readonly partitionKey: string;
+    /**
+     * The column name of the sortKey for the Table
+     */
+    readonly sortKey?: string;
+    /**
+     * The Global Secondary Indexes that are configured on this table
+     */
+    readonly gsis: Record<string, Index>;
+    constructor(config: TConfig);
+    protected createKeyForPrimaryIndex(keyCondition: PrimaryKeyWithoutExpression): Record<string, unknown>;
+    /**
+     * Creates a new item in the table, it will fail if the item already exists.
+     *
+     * By default, this method returns the input values passed to the create operation
+     * upon successful creation.
+     *
+     * You can customise the return behaviour by chaining the `.returnValues()` method:
+     *
+     * @param item The item to create
+     * @returns A PutBuilder instance for chaining additional conditions and executing the create operation
+     *
+     * @example
+     * ```ts
+     * // Create with default behavior (returns input values)
+     * const result = await table.create({
+     *   id: 'user-123',
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * }).execute();
+     * console.log(result); // Returns the input object
+     *
+     * // Create with no return value for better performance
+     * await table.create(userData).returnValues('NONE').execute();
+     *
+     * // Create and get fresh data from dynamodb using a strongly consistent read
+     * const freshData = await table.create(userData).returnValues('CONSISTENT').execute();
+     *
+     * // Create and get previous values (if the item was overwritten)
+     * const oldData = await table.create(userData).returnValues('ALL_OLD').execute();
+     * ```
+     */
+    create<T extends DynamoItem>(item: T): PutBuilder<T>;
+    get<T extends DynamoItem>(keyCondition: PrimaryKeyWithoutExpression): GetBuilder<T>;
+    /**
+     * Updates an item in the table
+     *
+     * @param item The item to update
+     * @returns A PutBuilder instance for chaining conditions and executing the put operation
+     */
+    put<T extends DynamoItem>(item: T): PutBuilder<T>;
+    /**
+     * Creates a query builder for complex queries
+     * If useIndex is called on the returned QueryBuilder, it will use the GSI configuration
+     */
+    query<T extends DynamoItem>(keyCondition: PrimaryKey): QueryBuilder<T, TConfig>;
+    /**
+     * Creates a scan builder for scanning the entire table
+     * Use this when you need to:
+     * - Process all items in a table
+     * - Apply filters to a large dataset
+     * - Use a GSI for scanning
+     *
+     * @returns A ScanBuilder instance for chaining operations
+     */
+    scan<T extends DynamoItem>(): ScanBuilder<T, TConfig>;
+    delete(keyCondition: PrimaryKeyWithoutExpression): DeleteBuilder;
+    /**
+     * Updates an item in the table
+     *
+     * @param keyCondition The primary key of the item to update
+     * @returns An UpdateBuilder instance for chaining update operations and conditions
+     */
+    update<T extends DynamoItem>(keyCondition: PrimaryKeyWithoutExpression): UpdateBuilder<T>;
+    /**
+     * Creates a transaction builder for performing multiple operations atomically
+     */
+    transactionBuilder(): TransactionBuilder;
+    /**
+     * Creates a batch builder for performing multiple operations efficiently with optional type inference
+     *
+     * @example Basic Usage
+     * ```typescript
+     * const batch = table.batchBuilder();
+     *
+     * // Add operations
+     * userRepo.create(newUser).withBatch(batch);
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch);
+     *
+     * // Execute operations
+     * const result = await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```typescript
+     * // Define entity types for the batch
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     *   Product: ProductEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.create(newUser).withBatch(batch, 'User');
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch, 'Order');
+     * productRepo.delete({ id: 'old-product' }).withBatch(batch, 'Product');
+     *
+     * // Execute and get typed results
+     * const result = await batch.execute();
+     * const users: UserEntity[] = result.reads.itemsByType.User;
+     * const orders: OrderEntity[] = result.reads.itemsByType.Order;
+     * ```
+     */
+    batchBuilder<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>>(): BatchBuilder<TEntities>;
+    /**
+     * Executes a transaction using a callback function
+     *
+     * @param callback A function that receives a transaction context and performs operations on it
+     * @param options Optional transaction options
+     * @returns A promise that resolves when the transaction is complete
+     */
+    transaction(callback: (tx: TransactionBuilder) => Promise<void> | void, options?: TransactionOptions): Promise<void>;
+    /**
+     * Creates a condition check operation for use in transactions
+     *
+     * This is useful for when you require a transaction to succeed only when a specific condition is met on a
+     * a record within the database that you are not directly updating.
+     *
+     * For example, you are updating a record and you want to ensure that another record exists and/or has a specific value before proceeding.
+     */
+    conditionCheck(keyCondition: PrimaryKeyWithoutExpression): ConditionCheckBuilder;
+    /**
+     * Performs a batch get operation to retrieve multiple items at once
+     *
+     * @param keys Array of primary keys to retrieve
+     * @returns A promise that resolves to the retrieved items
+     */
+    batchGet<T extends DynamoItem>(keys: Array<PrimaryKeyWithoutExpression>): Promise<{
+        items: T[];
+        unprocessedKeys: PrimaryKeyWithoutExpression[];
+    }>;
+    /**
+     * Performs a batch write operation to put or delete multiple items at once
+     *
+     * @param operations Array of put or delete operations
+     * @returns A promise that resolves to any unprocessed operations
+     */
+    batchWrite<T extends DynamoItem>(operations: Array<BatchWriteOperation<T>>): Promise<{
+        unprocessedItems: Array<BatchWriteOperation<T>>;
+    }>;
+}
+
+export { Table };

package/dist/table.d.ts

@@ -1,13 +1,164 @@
-import './batch-builder-Cdo49C2r.js';
-import './builders/condition-check-builder.js';
-import './builders/delete-builder.js';
-import './builders/put-builder.js';
-import './query-builder-CUWdavZw.js';
-export { T as Table } from './table-CZBMkW2Z.js';
-import './builders/transaction-builder.js';
-import './builders/update-builder.js';
-import './conditions-DD0bvyHm.js';
-import './types.js';
-import './builder-types-CzuLR4Th.js';
+import { P as PutBuilder, G as GetBuilder, Q as QueryBuilder, S as ScanBuilder, D as DeleteBuilder, U as UpdateBuilder, T as TransactionBuilder, B as BatchBuilder, f as TransactionOptions, C as ConditionCheckBuilder, h as BatchWriteOperation } from './index-2cbm07Bi.js';
+import { c as PrimaryKeyWithoutExpression, P as PrimaryKey } from './conditions-D_w7vVYG.js';
+import { TableConfig, Index, DynamoItem } from './types.js';
 import '@aws-sdk/lib-dynamodb';
-import './builders/paginator.js';
+
+declare class Table<TConfig extends TableConfig = TableConfig> {
+    private readonly dynamoClient;
+    readonly tableName: string;
+    /**
+     * The column name of the partitionKey for the Table
+     */
+    readonly partitionKey: string;
+    /**
+     * The column name of the sortKey for the Table
+     */
+    readonly sortKey?: string;
+    /**
+     * The Global Secondary Indexes that are configured on this table
+     */
+    readonly gsis: Record<string, Index>;
+    constructor(config: TConfig);
+    protected createKeyForPrimaryIndex(keyCondition: PrimaryKeyWithoutExpression): Record<string, unknown>;
+    /**
+     * Creates a new item in the table, it will fail if the item already exists.
+     *
+     * By default, this method returns the input values passed to the create operation
+     * upon successful creation.
+     *
+     * You can customise the return behaviour by chaining the `.returnValues()` method:
+     *
+     * @param item The item to create
+     * @returns A PutBuilder instance for chaining additional conditions and executing the create operation
+     *
+     * @example
+     * ```ts
+     * // Create with default behavior (returns input values)
+     * const result = await table.create({
+     *   id: 'user-123',
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * }).execute();
+     * console.log(result); // Returns the input object
+     *
+     * // Create with no return value for better performance
+     * await table.create(userData).returnValues('NONE').execute();
+     *
+     * // Create and get fresh data from dynamodb using a strongly consistent read
+     * const freshData = await table.create(userData).returnValues('CONSISTENT').execute();
+     *
+     * // Create and get previous values (if the item was overwritten)
+     * const oldData = await table.create(userData).returnValues('ALL_OLD').execute();
+     * ```
+     */
+    create<T extends DynamoItem>(item: T): PutBuilder<T>;
+    get<T extends DynamoItem>(keyCondition: PrimaryKeyWithoutExpression): GetBuilder<T>;
+    /**
+     * Updates an item in the table
+     *
+     * @param item The item to update
+     * @returns A PutBuilder instance for chaining conditions and executing the put operation
+     */
+    put<T extends DynamoItem>(item: T): PutBuilder<T>;
+    /**
+     * Creates a query builder for complex queries
+     * If useIndex is called on the returned QueryBuilder, it will use the GSI configuration
+     */
+    query<T extends DynamoItem>(keyCondition: PrimaryKey): QueryBuilder<T, TConfig>;
+    /**
+     * Creates a scan builder for scanning the entire table
+     * Use this when you need to:
+     * - Process all items in a table
+     * - Apply filters to a large dataset
+     * - Use a GSI for scanning
+     *
+     * @returns A ScanBuilder instance for chaining operations
+     */
+    scan<T extends DynamoItem>(): ScanBuilder<T, TConfig>;
+    delete(keyCondition: PrimaryKeyWithoutExpression): DeleteBuilder;
+    /**
+     * Updates an item in the table
+     *
+     * @param keyCondition The primary key of the item to update
+     * @returns An UpdateBuilder instance for chaining update operations and conditions
+     */
+    update<T extends DynamoItem>(keyCondition: PrimaryKeyWithoutExpression): UpdateBuilder<T>;
+    /**
+     * Creates a transaction builder for performing multiple operations atomically
+     */
+    transactionBuilder(): TransactionBuilder;
+    /**
+     * Creates a batch builder for performing multiple operations efficiently with optional type inference
+     *
+     * @example Basic Usage
+     * ```typescript
+     * const batch = table.batchBuilder();
+     *
+     * // Add operations
+     * userRepo.create(newUser).withBatch(batch);
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch);
+     *
+     * // Execute operations
+     * const result = await batch.execute();
+     * ```
+     *
+     * @example Typed Usage
+     * ```typescript
+     * // Define entity types for the batch
+     * const batch = table.batchBuilder<{
+     *   User: UserEntity;
+     *   Order: OrderEntity;
+     *   Product: ProductEntity;
+     * }>();
+     *
+     * // Add operations with type information
+     * userRepo.create(newUser).withBatch(batch, 'User');
+     * orderRepo.get({ id: 'order-1' }).withBatch(batch, 'Order');
+     * productRepo.delete({ id: 'old-product' }).withBatch(batch, 'Product');
+     *
+     * // Execute and get typed results
+     * const result = await batch.execute();
+     * const users: UserEntity[] = result.reads.itemsByType.User;
+     * const orders: OrderEntity[] = result.reads.itemsByType.Order;
+     * ```
+     */
+    batchBuilder<TEntities extends Record<string, DynamoItem> = Record<string, DynamoItem>>(): BatchBuilder<TEntities>;
+    /**
+     * Executes a transaction using a callback function
+     *
+     * @param callback A function that receives a transaction context and performs operations on it
+     * @param options Optional transaction options
+     * @returns A promise that resolves when the transaction is complete
+     */
+    transaction(callback: (tx: TransactionBuilder) => Promise<void> | void, options?: TransactionOptions): Promise<void>;
+    /**
+     * Creates a condition check operation for use in transactions
+     *
+     * This is useful for when you require a transaction to succeed only when a specific condition is met on a
+     * a record within the database that you are not directly updating.
+     *
+     * For example, you are updating a record and you want to ensure that another record exists and/or has a specific value before proceeding.
+     */
+    conditionCheck(keyCondition: PrimaryKeyWithoutExpression): ConditionCheckBuilder;
+    /**
+     * Performs a batch get operation to retrieve multiple items at once
+     *
+     * @param keys Array of primary keys to retrieve
+     * @returns A promise that resolves to the retrieved items
+     */
+    batchGet<T extends DynamoItem>(keys: Array<PrimaryKeyWithoutExpression>): Promise<{
+        items: T[];
+        unprocessedKeys: PrimaryKeyWithoutExpression[];
+    }>;
+    /**
+     * Performs a batch write operation to put or delete multiple items at once
+     *
+     * @param operations Array of put or delete operations
+     * @returns A promise that resolves to any unprocessed operations
+     */
+    batchWrite<T extends DynamoItem>(operations: Array<BatchWriteOperation<T>>): Promise<{
+        unprocessedItems: Array<BatchWriteOperation<T>>;
+    }>;
+}
+
+export { Table };