dyno-table 0.1.8 → 0.2.0-0

package/dist/table-BEhBPy2G.d.cts

@@ -0,0 +1,364 @@
+import { DynamoItem, TableConfig, Index } from './types.cjs';
+import { P as PrimaryKeyWithoutExpression, a as PrimaryKey } from './conditions-ChhQWd6z.cjs';
+import { F as FilterBuilder, a as FilterOptions, Q as QueryBuilder } from './query-builder-D2FM9rsu.cjs';
+import { PutBuilder } from './builders/put-builder.cjs';
+import { DeleteBuilder } from './builders/delete-builder.cjs';
+import { UpdateBuilder } from './builders/update-builder.cjs';
+import { TransactionBuilder, TransactionOptions } from './builders/transaction-builder.cjs';
+import { ConditionCheckBuilder } from './builders/condition-check-builder.cjs';
+import { S as ScanBuilderInterface } from './builder-types-DtwbqMeF.cjs';
+
+type BatchWriteOperation<T extends Record<string, unknown>> = {
+    type: "put";
+    item: T;
+} | {
+    type: "delete";
+    key: PrimaryKeyWithoutExpression;
+};
+
+/**
+ * Parameters for the DynamoDB get command.
+ */
+interface GetCommandParams {
+    /** The name of the DynamoDB table */
+    tableName: string;
+    /** The primary key of the item to get */
+    key: PrimaryKeyWithoutExpression;
+    /** Comma-separated list of attributes to return */
+    projectionExpression?: string;
+    /** Map of expression attribute name placeholders to actual names */
+    expressionAttributeNames?: Record<string, string>;
+    /** Whether to use strongly consistent reads */
+    consistentRead?: boolean;
+}
+/**
+ * Function type for executing DynamoDB get operations.
+ * @typeParam T - The type of item being retrieved
+ */
+type GetExecutor<T extends DynamoItem> = (params: GetCommandParams) => Promise<{
+    item: T | undefined;
+}>;
+/**
+ * Builder for creating DynamoDB get operations.
+ * Use this builder when you need to:
+ * - Retrieve a single dinosaur by its primary key
+ * - Project specific dinosaur attributes
+ * - Use consistent reads for critical dinosaur data
+ *
+ * @example
+ * ```typescript
+ * // Simple get
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .execute();
+ *
+ * // Get with projection and consistent read
+ * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+ *   .select(['species', 'name', 'diet'])
+ *   .consistentRead()
+ *   .execute();
+ * ```
+ *
+ * @typeParam T - The type of item being retrieved
+ */
+declare class GetBuilder<T extends DynamoItem> {
+    private readonly executor;
+    private readonly params;
+    private options;
+    private selectedFields;
+    /**
+     * Creates a new GetBuilder instance.
+     *
+     * @param executor - Function that executes the get operation
+     * @param key - Primary key of the item to retrieve
+     * @param tableName - Name of the DynamoDB table
+     */
+    constructor(executor: GetExecutor<T>, key: PrimaryKeyWithoutExpression, tableName: string);
+    /**
+     * Specifies which attributes to return in the get results.
+     * Use this method when you need to:
+     * - Reduce data transfer by selecting specific dinosaur attributes
+     * - Optimize response size for dinosaur records
+     * - Focus on relevant dinosaur characteristics only
+     *
+     * @example
+     * ```typescript
+     * // Select single attribute
+     * builder.select('species')
+     *
+     * // Select multiple attributes
+     * builder.select(['id', 'species', 'diet'])
+     *
+     * // Chain multiple select calls
+     * builder
+     *   .select('id')
+     *   .select(['species', 'diet'])
+     * ```
+     *
+     * @param fields - A single field name or an array of field names to return
+     * @returns The builder instance for method chaining
+     */
+    select(fields: string | string[]): GetBuilder<T>;
+    /**
+     * Sets whether to use strongly consistent reads for the get operation.
+     * Use this method when you need:
+     * - The most up-to-date dinosaur data
+     * - To ensure you're reading the latest dinosaur status
+     * - Critical safety information about dangerous species
+     *
+     * Note: Consistent reads consume twice the throughput
+     *
+     * @example
+     * ```typescript
+     * // Get the latest T-Rex data
+     * const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *   .consistentRead()
+     *   .execute();
+     * ```
+     *
+     * @param consistentRead - Whether to use consistent reads (defaults to true)
+     * @returns The builder instance for method chaining
+     */
+    consistentRead(consistentRead?: boolean): GetBuilder<T>;
+    /**
+     * Executes the get operation against DynamoDB.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const result = await new GetBuilder(executor, { pk: 'dinosaur#123', sk: 'profile' })
+     *     .select(['species', 'name', 'diet'])
+     *     .consistentRead()
+     *     .execute();
+     *
+     *   if (result.item) {
+     *     console.log('Dinosaur found:', result.item);
+     *   } else {
+     *     console.log('Dinosaur not found');
+     *   }
+     * } catch (error) {
+     *   console.error('Error getting dinosaur:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing:
+     *          - item: The retrieved dinosaur or undefined if not found
+     */
+    execute(): Promise<{
+        item: T | undefined;
+    }>;
+}
+
+/**
+ * Configuration options for DynamoDB scan operations.
+ * Extends the base FilterOptions.
+ */
+type ScanOptions = FilterOptions;
+/**
+ * Function type for executing DynamoDB filter operations.
+ * @typeParam T - The type of items being filtered
+ */
+type ScanExecutor<T extends DynamoItem> = (options: ScanOptions) => Promise<{
+    items: T[];
+    lastEvaluatedKey?: DynamoItem;
+}>;
+/**
+ * Builder for creating DynamoDB scan operations.
+ * Use this builder when you need to:
+ * - Scan all items in a table
+ * - Filter results based on non-key attributes
+ * - Scan items on a Secondary Index (GSI)
+ * - Implement pagination
+ * - Project specific attributes
+ *
+ * The builder supports:
+ * - Type-safe GSI selection
+ * - Complex filter conditions
+ * - Automatic pagination handling
+ * - Consistent reads
+ * - Attribute projection
+ *
+ * @example
+ * ```typescript
+ * // Simple scan with filtering
+ * const result = await new ScanBuilder(executor)
+ *   .filter(op => op.eq('status', 'ACTIVE'))
+ *   .execute();
+ *
+ * // Scan with GSI and filtering
+ * const result = await new ScanBuilder(executor)
+ *   .useIndex('status-index')
+ *   .filter(op => op.gt('securityLevel', 8))
+ *   .select(['id', 'capacity', 'currentOccupants'])
+ *   .limit(10)
+ *   .execute();
+ *
+ * // Scan with pagination
+ * const paginator = new ScanBuilder(executor)
+ *   .filter(op => op.eq('type', 'INCIDENT'))
+ *   .paginate(25);
+ *
+ * while (paginator.hasNextPage()) {
+ *   const page = await paginator.getNextPage();
+ *   // Process page.items
+ * }
+ * ```
+ *
+ * @typeParam T - The type of items being scanned
+ * @typeParam TConfig - The table configuration type for type-safe GSI selection
+ */
+declare class ScanBuilder<T extends DynamoItem, TConfig extends TableConfig = TableConfig> extends FilterBuilder<T, TConfig> implements ScanBuilderInterface<T, TConfig> {
+    protected readonly executor: ScanExecutor<T>;
+    constructor(executor: ScanExecutor<T>);
+    /**
+     * Creates a deep clone of this ScanBuilder instance.
+     * Use this method when you need to:
+     * - Create scan templates
+     * - Run multiple variations of a scan
+     * - Implement pagination (used internally by paginate())
+     *
+     * @returns A new ScanBuilder instance with the same configuration
+     */
+    clone(): ScanBuilder<T, TConfig>;
+    /**
+     * Executes the scan against DynamoDB.
+     * Use this method when you need to:
+     * - Search across the entire table
+     * - Find items matching specific criteria
+     * - Perform full table analysis
+     * - Generate reports across all data
+     *
+     * The method returns both the matched items and, if there are more results,
+     * a lastEvaluatedKey that can be used with startFrom() to continue the scan.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Find all dinosaurs with high aggression levels
+     *   const result = await new ScanBuilder(executor)
+     *     .filter(op =>
+     *       op.and([
+     *         op.eq('status', 'ACTIVE'),
+     *         op.gt('aggressionLevel', 7)
+     *       ])
+     *     )
+     *     .limit(20)
+     *     .execute();
+     *
+     *   console.log(`Found ${result.items.length} potentially dangerous dinosaurs`);
+     *
+     *   if (result.lastEvaluatedKey) {
+     *     console.log('More results available');
+     *   }
+     * } catch (error) {
+     *   console.error('Security scan failed:', error);
+     * }
+     * ```
+     *
+     * @returns A promise that resolves to an object containing:
+     *          - items: Array of items matching the scan criteria
+     *          - lastEvaluatedKey: Token for continuing the scan, if more items exist
+     */
+    execute(): Promise<{
+        items: T[];
+        lastEvaluatedKey?: Record<string, unknown>;
+    }>;
+}
+
+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
+     *
+     * @param item The item to create
+     * @returns A PutBuilder instance for chaining conditions and executing the put operation
+     */
+    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;
+    /**
+     * 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<T>(callback: (tx: TransactionBuilder) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * 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 { GetBuilder as G, ScanBuilder as S, Table as T };