captify 0.1.18 → 1.1.0

package/dist/shared/services/dynamodb/dynamodb.query-builder.js

@@ -0,0 +1,117 @@
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function attributeNamePlaceholder(name) {
+    // Keep placeholders stable and human-readable
+    return `#${name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+}
+function valuePlaceholder(name) {
+    return `:${name.replace(/[^a-zA-Z0-9_]/g, "_")}`;
+}
+function normalizePartitionCondition(value) {
+    if (typeof value === "string")
+        return { op: "eq", value };
+    if (isObject(value) && typeof value.eq === "string")
+        return { op: "eq", value: value.eq };
+    throw new Error("Invalid partition key condition");
+}
+function normalizeSortCondition(value) {
+    if (typeof value === "string")
+        return value;
+    if (!isObject(value))
+        throw new Error("Invalid sort key condition");
+    // Narrow to supported operators
+    if (typeof value.eq === "string")
+        return { eq: value.eq };
+    if (typeof value.beginsWith === "string")
+        return { beginsWith: value.beginsWith };
+    if (Array.isArray(value.between) && value.between.length === 2) {
+        return { between: [String(value.between[0]), String(value.between[1])] };
+    }
+    if (typeof value.gt === "string")
+        return { gt: value.gt };
+    if (typeof value.gte === "string")
+        return { gte: value.gte };
+    if (typeof value.lt === "string")
+        return { lt: value.lt };
+    if (typeof value.lte === "string")
+        return { lte: value.lte };
+    throw new Error("Invalid sort key condition operator");
+}
+/**
+ * Build a DynamoDB `KeyConditionExpression` from a typed keyCondition object.
+ *
+ * Example:
+ * `{ PK: "x", SK: { beginsWith: "META#" } }`
+ * => `PK = :PK AND begins_with(SK, :SK)`
+ */
+export function buildKeyConditionExpression(keyCondition) {
+    const ExpressionAttributeNames = {};
+    const ExpressionAttributeValues = {};
+    const parts = [];
+    for (const [field, rawValue] of Object.entries(keyCondition)) {
+        const nameKey = attributeNamePlaceholder(field);
+        ExpressionAttributeNames[nameKey] = field;
+        // Partition key (string or {eq})
+        if (!isObject(rawValue) || typeof rawValue === "string" || "eq" in rawValue) {
+            const normalized = normalizePartitionCondition(rawValue);
+            const valKey = valuePlaceholder(field);
+            ExpressionAttributeValues[valKey] = normalized.value;
+            parts.push(`${nameKey} = ${valKey}`);
+            continue;
+        }
+        // Sort key operator object
+        const normalizedSort = normalizeSortCondition(rawValue);
+        const baseValKey = valuePlaceholder(field);
+        if (typeof normalizedSort === "string") {
+            ExpressionAttributeValues[baseValKey] = normalizedSort;
+            parts.push(`${nameKey} = ${baseValKey}`);
+            continue;
+        }
+        if ("eq" in normalizedSort) {
+            ExpressionAttributeValues[baseValKey] = normalizedSort.eq;
+            parts.push(`${nameKey} = ${baseValKey}`);
+            continue;
+        }
+        if ("beginsWith" in normalizedSort) {
+            ExpressionAttributeValues[baseValKey] = normalizedSort.beginsWith;
+            parts.push(`begins_with(${nameKey}, ${baseValKey})`);
+            continue;
+        }
+        if ("between" in normalizedSort) {
+            const [a, b] = normalizedSort.between;
+            const aKey = `${baseValKey}_a`;
+            const bKey = `${baseValKey}_b`;
+            ExpressionAttributeValues[aKey] = a;
+            ExpressionAttributeValues[bKey] = b;
+            parts.push(`${nameKey} BETWEEN ${aKey} AND ${bKey}`);
+            continue;
+        }
+        if ("gt" in normalizedSort) {
+            ExpressionAttributeValues[baseValKey] = normalizedSort.gt;
+            parts.push(`${nameKey} > ${baseValKey}`);
+            continue;
+        }
+        if ("gte" in normalizedSort) {
+            ExpressionAttributeValues[baseValKey] = normalizedSort.gte;
+            parts.push(`${nameKey} >= ${baseValKey}`);
+            continue;
+        }
+        if ("lt" in normalizedSort) {
+            ExpressionAttributeValues[baseValKey] = normalizedSort.lt;
+            parts.push(`${nameKey} < ${baseValKey}`);
+            continue;
+        }
+        if ("lte" in normalizedSort) {
+            ExpressionAttributeValues[baseValKey] = normalizedSort.lte;
+            parts.push(`${nameKey} <= ${baseValKey}`);
+            continue;
+        }
+    }
+    return {
+        KeyConditionExpression: parts.join(" AND "),
+        ExpressionAttributeNames,
+        ExpressionAttributeValues,
+    };
+}
+//# sourceMappingURL=dynamodb.query-builder.js.map

package/dist/shared/services/dynamodb/dynamodb.query-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamodb.query-builder.js","sourceRoot":"","sources":["../../../../lib/shared/services/dynamodb/dynamodb.query-builder.ts"],"names":[],"mappings":"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"}

package/dist/shared/services/dynamodb/dynamodb.service.d.ts

@@ -1,8 +1,24 @@
-import type { DynamoDbBaseOptions, DynamoDbBatchGetParams, DynamoDbBatchGetResult, DynamoDbConfig, DynamoDbQueryResult, DynamoDbScanResult, DynamoDbTransactGetItem, DynamoDbTransactionAction } from "./dynamodb.interfaces";
+import type { DynamoDbBaseOptions, DynamoDbBatchGetParams, DynamoDbBatchGetResult, DynamoDbConfig, DynamoDbQueryResult, DynamoDbScanResult, DynamoDbTransactGetItem, DynamoDbTransactionAction, DynamoDbUpdateOptions } from "./dynamodb.interfaces";
+import type { IndexNames, TableItem, TableKey, TableSchema } from "./types";
 import type { BaseAwsError } from "../services.errors";
 import type { Logger } from "../logger";
 import { BaseAwsService } from "../base-aws-service";
-import { type BatchWriteCommandOutput, DynamoDBDocumentClient, type QueryCommandInput, type ScanCommandInput } from "@aws-sdk/lib-dynamodb";
+import { type BatchWriteCommandOutput, type DeleteCommandOutput, DynamoDBDocumentClient, type GetCommandOutput, type PutCommandOutput, type QueryCommandInput, type QueryCommandOutput, type ScanCommandInput, type ScanCommandOutput, type UpdateCommandOutput } from "@aws-sdk/lib-dynamodb";
+import { TypedUpdateExpressionBuilder } from "./typed-update-expression-builder";
+import type { QueryParams, QueryResult } from "./types";
+type AnyTableSchema = TableSchema<Record<string, any>>;
+type TypedGetOutput<TItem> = Omit<GetCommandOutput, "Item"> & {
+    Item?: TItem;
+};
+type TypedUpdateOutput<TItem> = Omit<UpdateCommandOutput, "Attributes"> & {
+    Attributes?: TItem;
+};
+type TypedQueryOutput<TItem> = Omit<QueryCommandOutput, "Items"> & {
+    Items?: Array<TItem>;
+};
+type TypedScanOutput<TItem> = Omit<ScanCommandOutput, "Items"> & {
+    Items?: Array<TItem>;
+};
 /**
  * Generic DynamoDB service that provides type-safe operations for any DynamoDB table.
  *
@@ -65,7 +81,7 @@ import { type BatchWriteCommandOutput, DynamoDBDocumentClient, type QueryCommand
  * ]);
  * ```
  */
-export declare class DynamoDbService extends BaseAwsService {
+export declare class DynamoDbService<TSchema extends TableSchema<any> = AnyTableSchema> extends BaseAwsService {
     private readonly client;
     private readonly defaultTableName?;
     private constructor();
@@ -121,23 +137,23 @@ export declare class DynamoDbService extends BaseAwsService {
      * });
      * ```
      */
-    static create(config: Partial<DynamoDbConfig>, logger?: Logger): DynamoDbService;
+    static create<TSchema extends TableSchema<any> = AnyTableSchema>(config: Partial<DynamoDbConfig>, logger?: Logger): DynamoDbService<TSchema>;
     static loadEnvConfig(): Partial<DynamoDbConfig>;
-    static createWithClient(client: DynamoDBDocumentClient, tableName: string, logger?: Logger): DynamoDbService;
+    static createWithClient<TSchema extends TableSchema<any> = AnyTableSchema>(client: DynamoDBDocumentClient, tableName: string, logger?: Logger): DynamoDbService<TSchema>;
     /**
      * Inserts or replaces an item in the DynamoDB table.
      * @param item The item to be created or updated.
      * @param options Optional parameters including table name override and user credentials
      * @returns The result of the Put operation.
      */
-    putItem<T extends Record<string, unknown>>(item: T, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").PutCommandOutput>;
+    putItem(item: TableItem<TSchema>, options?: DynamoDbBaseOptions): Promise<PutCommandOutput>;
     /**
      * Retrieves an item from the DynamoDB table by its primary key.
      * @param key The primary key of the item to retrieve.
      * @param options Optional parameters including table name override and user credentials
      * @returns The result of the Get operation, containing the item if found.
      */
-    getItem<T extends Record<string, unknown>>(key: T, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").GetCommandOutput>;
+    getItem(key: TableKey<TSchema>, options?: DynamoDbBaseOptions): Promise<TypedGetOutput<TableItem<TSchema>>>;
     /**
      * Updates an existing item in the DynamoDB table.
      * @param key The primary key of the item to update.
@@ -147,14 +163,14 @@ export declare class DynamoDbService extends BaseAwsService {
      * @param options Optional parameters including table name override and user credentials
      * @returns The result of the Update operation.
      */
-    updateItem<T extends Record<string, unknown>, U extends Record<string, string>>(key: T, updateExpression: string, expressionAttributeNames?: U, expressionAttributeValues?: T, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").UpdateCommandOutput>;
+    updateItem(key: TableKey<TSchema>, updateExpression: string, expressionAttributeNames?: Record<string, string>, expressionAttributeValues?: Record<string, unknown>, options?: DynamoDbUpdateOptions): Promise<TypedUpdateOutput<TableItem<TSchema>>>;
     /**
      * Deletes an item from the DynamoDB table by its primary key.
      * @param key The primary key of the item to delete.
      * @param options Optional parameters including table name override and user credentials
      * @returns The result of the Delete operation.
      */
-    deleteItem<T extends Record<string, unknown>>(key: T, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").DeleteCommandOutput>;
+    deleteItem(key: TableKey<TSchema>, options?: DynamoDbBaseOptions): Promise<DeleteCommandOutput>;
     /**
      * Queries items from the table based on a key condition.
      * Supports pagination via the `ExclusiveStartKey` parameter.
@@ -162,15 +178,43 @@ export declare class DynamoDbService extends BaseAwsService {
      * @param options Optional parameters including table name override and user credentials
      * @returns The result of the Query operation, containing the matching items.
      */
-    queryItems(params: Omit<QueryCommandInput, "TableName">, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").QueryCommandOutput>;
+    queryItems<IndexName extends IndexNames<TSchema> | undefined = undefined>(params: Omit<QueryCommandInput, "TableName" | "IndexName"> & (IndexName extends IndexNames<TSchema> ? {
+        IndexName: IndexName;
+    } : {
+        IndexName?: IndexNames<TSchema> | string;
+    }), options?: DynamoDbBaseOptions): Promise<TypedQueryOutput<TableItem<TSchema>>>;
+    queryItems(params: Omit<QueryCommandInput, "TableName">, options?: DynamoDbBaseOptions): Promise<QueryCommandOutput>;
     /**
-     * Scans all items in the table.
+     * Create a typed update builder for this table schema.
+     *
+     * This follows the dev guide's principle: keep runtime behavior stable and layer
+     * compile-time safety via types.
+     */
+    createUpdateBuilder(): TypedUpdateExpressionBuilder<TSchema["attributes"]>;
+    /**
+     * Type-safe query builder wrapper.
+     *
+     * This is the preferred API for new code because it:
+     * - Validates index names at compile time
+     * - Avoids brittle KeyConditionExpression strings
+     * - Returns typed items
+     *
+     * Runtime behavior is equivalent to calling `queryItems()` with the built params.
+     */
+    queryTyped<IndexName extends IndexNames<TSchema> | "primary" = "primary">(params: QueryParams<TSchema, IndexName>, options?: DynamoDbBaseOptions): Promise<QueryResult<TSchema>>;
+    /**
+     * Async generator that paginates through all results using the typed query API.
+     * This mirrors `queryAllPages()` but avoids stringly-typed key expressions.
+     */
+    queryAllPagesTyped<IndexName extends IndexNames<TSchema> | "primary" = "primary">(params: Omit<QueryParams<TSchema, IndexName>, "exclusiveStartKey">, options?: DynamoDbBaseOptions): AsyncGenerator<QueryResult<TSchema>, void, undefined>;
+    /**
+     * Scans all items in the table with type-safe return type.
      * Supports pagination via the `ExclusiveStartKey` parameter.
      * @param params The parameters for the Scan operation, including optional filters.
      * @param options Optional parameters including table name override and user credentials
-     * @returns The result of the Scan operation, containing the scanned items.
+     * @returns The result of the Scan operation with typed Items array.
      */
-    scanItems(params: Omit<ScanCommandInput, "TableName">, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").ScanCommandOutput>;
+    scanItems(params: Omit<ScanCommandInput, "TableName">, options?: DynamoDbBaseOptions): Promise<TypedScanOutput<TableItem<TSchema>>>;
     /**
      * Async generator that automatically handles pagination for query operations.
      * Yields items one page at a time until all results are retrieved.
@@ -185,7 +229,7 @@ export declare class DynamoDbService extends BaseAwsService {
      * }
      * ```
      */
-    queryAllPages<T extends Record<string, unknown>>(params: Omit<QueryCommandInput, "TableName" | "ExclusiveStartKey">, options?: DynamoDbBaseOptions): AsyncGenerator<DynamoDbQueryResult<T>, void, undefined>;
+    queryAllPages<TItem extends Record<string, unknown> = TableItem<TSchema>>(params: Omit<QueryCommandInput, "TableName" | "ExclusiveStartKey">, options?: DynamoDbBaseOptions): AsyncGenerator<DynamoDbQueryResult<TItem>, void, undefined>;
     /**
      * Async generator that automatically handles pagination for scan operations.
      * Yields items one page at a time until all results are retrieved.
@@ -200,7 +244,7 @@ export declare class DynamoDbService extends BaseAwsService {
      * }
      * ```
      */
-    scanAllPages<T extends Record<string, unknown>>(params: Omit<ScanCommandInput, "TableName" | "ExclusiveStartKey">, options?: DynamoDbBaseOptions): AsyncGenerator<DynamoDbScanResult<T>, void, undefined>;
+    scanAllPages<TItem extends Record<string, unknown> = TableItem<TSchema>>(params: Omit<ScanCommandInput, "TableName" | "ExclusiveStartKey">, options?: DynamoDbBaseOptions): AsyncGenerator<DynamoDbScanResult<TItem>, void, undefined>;
     /**
      * Performs a batch write operation (put or delete) on multiple items.
      * @param items An array of items to be put or deleted.
@@ -210,7 +254,9 @@ export declare class DynamoDbService extends BaseAwsService {
      * @throws `Error` if the items array is empty.
      * @throws `Error` if retry attempts are exhausted.
      */
-    batchWrite<T extends Record<string, unknown>>(items: T[], operation?: "put" | "delete", options?: DynamoDbBaseOptions): Promise<BatchWriteCommandOutput>;
+    batchWrite(items: Array<TableItem<TSchema>>, operation?: "put", options?: DynamoDbBaseOptions): Promise<BatchWriteCommandOutput>;
+    batchWrite(items: Array<TableKey<TSchema>>, operation: "delete", options?: DynamoDbBaseOptions): Promise<BatchWriteCommandOutput>;
+    batchWrite<T extends Record<string, unknown>>(items: T[], operation: "put" | "delete", options?: DynamoDbBaseOptions): Promise<BatchWriteCommandOutput>;
     /**
      * Performs a transactional write operation (up to 100 actions)
      * All actions succeed or all fail atomically
@@ -234,6 +280,9 @@ export declare class DynamoDbService extends BaseAwsService {
      * @param options Optional parameters including table name override and user credentials
      * @returns The result containing retrieved items and any unprocessed keys
      */
+    batchGet(params: Omit<DynamoDbBatchGetParams, "keys"> & {
+        keys: Array<TableKey<TSchema>>;
+    }, options?: DynamoDbBaseOptions): Promise<DynamoDbBatchGetResult<TableItem<TSchema>>>;
     batchGet<T extends Record<string, unknown>>(params: DynamoDbBatchGetParams, options?: DynamoDbBaseOptions): Promise<DynamoDbBatchGetResult<T>>;
     /**
      * Conditional put operation - only puts the item if it doesn't already exist.
@@ -251,7 +300,8 @@ export declare class DynamoDbService extends BaseAwsService {
      * );
      * ```
      */
-    putIfNotExists<T extends Record<string, unknown>>(item: T, partitionKeyName: string, options?: DynamoDbBaseOptions): Promise<import("@aws-sdk/lib-dynamodb").PutCommandOutput>;
+    putIfNotExists(item: TableItem<TSchema>, partitionKeyName: TSchema["primaryKey"]["partition"], options?: DynamoDbBaseOptions): Promise<unknown>;
+    putIfNotExists<T extends Record<string, unknown>>(item: T, partitionKeyName: string, options?: DynamoDbBaseOptions): Promise<unknown>;
     /**
      * Conditional update operation - only updates the item if it exists.
      * Uses attribute_exists() condition on the partition key.
@@ -274,13 +324,20 @@ export declare class DynamoDbService extends BaseAwsService {
      * );
      * ```
      */
+    updateIfExists(key: TableKey<TSchema>, updateExpression: string, partitionKeyName: TSchema["primaryKey"]["partition"], options?: {
+        tableName?: string;
+        expressionAttributeNames?: Record<string, string>;
+        expressionAttributeValues?: Record<string, unknown>;
+        additionalCondition?: string;
+        userCredentials?: import("..").UserAwsCredentials;
+    }): Promise<unknown>;
     updateIfExists(key: Record<string, unknown>, updateExpression: string, partitionKeyName: string, options?: {
         tableName?: string;
         expressionAttributeNames?: Record<string, string>;
         expressionAttributeValues?: Record<string, unknown>;
         additionalCondition?: string;
         userCredentials?: import("..").UserAwsCredentials;
-    }): Promise<import("@aws-sdk/lib-dynamodb").UpdateCommandOutput>;
+    }): Promise<unknown>;
     protected onMetric(name: string, dims: Record<string, unknown>): void;
     getDefaultTableName(): string | undefined;
     /**
@@ -289,4 +346,5 @@ export declare class DynamoDbService extends BaseAwsService {
      */
     destroy(): Promise<void>;
 }
+export {};
 //# sourceMappingURL=dynamodb.service.d.ts.map

package/dist/shared/services/dynamodb/dynamodb.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dynamodb.service.d.ts","sourceRoot":"","sources":["../../../../lib/shared/services/dynamodb/dynamodb.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAElB,uBAAuB,EACvB,yBAAyB,EAC1B,MAAM,oDAAoD,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AAC1E,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAGxE,OAAO,EAGL,KAAK,uBAAuB,EAE5B,sBAAsB,EAItB,KAAK,iBAAiB,EAEtB,KAAK,gBAAgB,EAItB,MAAM,uBAAuB,CAAC;AAY/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,qBAAa,eAAgB,SAAQ,cAAc;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAE3C,OAAO;IAMP,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY;IAInD,OAAO,CAAC,gBAAgB;IASxB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAoB7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM;IA0B9D,MAAM,CAAC,aAAa,IAAI,OAAO,CAAC,cAAc,CAAC;IAS/C,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAS1F;;;;;OAKG;IACG,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB;IA2BvF;;;;;OAKG;IACG,OAAO,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB;IA2BtF;;;;;;;;OAQG;IACG,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClF,GAAG,EAAE,CAAC,EACN,gBAAgB,EAAE,MAAM,EACxB,wBAAwB,CAAC,EAAE,CAAC,EAC5B,yBAAyB,CAAC,EAAE,CAAC,EAC7B,OAAO,CAAC,EAAE,mBAAmB;IAgC/B;;;;;OAKG;IACG,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB;IA2BzF;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB;IA0B5F;;;;;;OAMG;IACG,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,EAAE,mBAAmB;IA0B1F;;;;;;;;;;;;;OAaG;IACI,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpD,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,mBAAmB,CAAC,EAClE,OAAO,CAAC,EAAE,mBAAmB,GAC5B,cAAc,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;IAyB1D;;;;;;;;;;;;;OAaG;IACI,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnD,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,GAAG,mBAAmB,CAAC,EACjE,OAAO,CAAC,EAAE,mBAAmB,GAC5B,cAAc,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC;IAyBzD;;;;;;;;OAQG;IACG,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,GAAE,KAAK,GAAG,QAAgB,EACnC,OAAO,CAAC,EAAE,mBAAmB;IAuG/B;;;;;;OAMG;IACG,aAAa,CACjB,OAAO,EAAE,yBAAyB,EAAE,EACpC,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC;IAkGlD;;;;;;OAMG;IACG,WAAW,CACf,KAAK,EAAE,uBAAuB,EAAE,EAChC,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC;IA8ClD;;;;;;OAMG;IACG,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,MAAM,EAAE,sBAAsB,EAC9B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAoFrC;;;;;;;;;;;;;;;OAeG;IACG,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpD,IAAI,EAAE,CAAC,EACP,gBAAgB,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE,mBAAmB;IA6B/B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,cAAc,CAClB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAClD,yBAAyB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpD,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,eAAe,CAAC,EAAE,OAAO,uBAAuB,EAAE,kBAAkB,CAAC;KACtE;IAsCH,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIrE,mBAAmB,IAAI,MAAM,GAAG,SAAS;IAIzC;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAa/B"}
+{"version":3,"file":"dynamodb.service.d.ts","sourceRoot":"","sources":["../../../../lib/shared/services/dynamodb/dynamodb.service.ts"],"names":[],"mappings":"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"}

package/dist/shared/services/dynamodb/dynamodb.service.js

@@ -18,6 +18,8 @@ import { BatchGetCommand, BatchWriteCommand, DeleteCommand, DynamoDBDocumentClie
 import { DYNAMODB_BATCH_WRITE_CHUNK_SIZE, DYNAMODB_ERROR_MESSAGES, } from "./dynamodb.constants";
 import { classifyDynamoDbError } from "./dynamodb.errors";
 import { validateItemSize, validateKey, validateTableName, } from "./dynamodb.utilities";
+import { TypedUpdateExpressionBuilder } from "./typed-update-expression-builder";
+import { buildKeyConditionExpression } from "./dynamodb.query-builder";
 /**
  * Generic DynamoDB service that provides type-safe operations for any DynamoDB table.
  *
@@ -195,12 +197,6 @@ export class DynamoDbService extends BaseAwsService {
         };
         return new DynamoDbService(deps);
     }
-    /**
-     * Inserts or replaces an item in the DynamoDB table.
-     * @param item The item to be created or updated.
-     * @param options Optional parameters including table name override and user credentials
-     * @returns The result of the Put operation.
-     */
     async putItem(item, options) {
         return this.executeWithRetry(async () => {
             const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
@@ -221,12 +217,6 @@ export class DynamoDbService extends BaseAwsService {
             return result;
         });
     }
-    /**
-     * Retrieves an item from the DynamoDB table by its primary key.
-     * @param key The primary key of the item to retrieve.
-     * @param options Optional parameters including table name override and user credentials
-     * @returns The result of the Get operation, containing the item if found.
-     */
     async getItem(key, options) {
         return this.executeWithRetry(async () => {
             const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
@@ -247,15 +237,6 @@ export class DynamoDbService extends BaseAwsService {
             return result;
         });
     }
-    /**
-     * Updates an existing item in the DynamoDB table.
-     * @param key The primary key of the item to update.
-     * @param updateExpression A string that defines the attributes to be updated.
-     * @param expressionAttributeNames Attribute name placeholders
-     * @param expressionAttributeValues A map of values to substitute in the expression.
-     * @param options Optional parameters including table name override and user credentials
-     * @returns The result of the Update operation.
-     */
     async updateItem(key, updateExpression, expressionAttributeNames, expressionAttributeValues, options) {
         return this.executeWithRetry(async () => {
             const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
@@ -264,14 +245,9 @@ export class DynamoDbService extends BaseAwsService {
             this.logger.info(`Updating item in ${tableName}`, {
                 userCredentials: usingUserCredentials,
             });
-            const command = new UpdateCommand({
-                TableName: tableName,
-                Key: key,
-                UpdateExpression: updateExpression,
-                ExpressionAttributeNames: expressionAttributeNames,
-                ExpressionAttributeValues: expressionAttributeValues,
-                ReturnValues: "ALL_NEW",
-            });
+            const command = new UpdateCommand(Object.assign({ TableName: tableName, Key: key, UpdateExpression: updateExpression, ExpressionAttributeNames: expressionAttributeNames, ExpressionAttributeValues: expressionAttributeValues, ReturnValues: "ALL_NEW" }, ((options === null || options === void 0 ? void 0 : options.conditionExpression) && {
+                ConditionExpression: options.conditionExpression,
+            })));
             const client = this.getClientForOperation(options === null || options === void 0 ? void 0 : options.userCredentials);
             const result = await client.send(command);
             this.logger.info(`Successfully updated item in ${tableName}`, {
@@ -280,12 +256,6 @@ export class DynamoDbService extends BaseAwsService {
             return result;
         });
     }
-    /**
-     * Deletes an item from the DynamoDB table by its primary key.
-     * @param key The primary key of the item to delete.
-     * @param options Optional parameters including table name override and user credentials
-     * @returns The result of the Delete operation.
-     */
     async deleteItem(key, options) {
         return this.executeWithRetry(async () => {
             const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
@@ -306,13 +276,6 @@ export class DynamoDbService extends BaseAwsService {
             return result;
         });
     }
-    /**
-     * Queries items from the table based on a key condition.
-     * Supports pagination via the `ExclusiveStartKey` parameter.
-     * @param params The parameters for the Query operation, including the key condition and optional filters.
-     * @param options Optional parameters including table name override and user credentials
-     * @returns The result of the Query operation, containing the matching items.
-     */
     async queryItems(params, options) {
         return this.executeWithRetry(async () => {
             const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
@@ -330,12 +293,53 @@ export class DynamoDbService extends BaseAwsService {
         });
     }
     /**
-     * Scans all items in the table.
-     * Supports pagination via the `ExclusiveStartKey` parameter.
-     * @param params The parameters for the Scan operation, including optional filters.
-     * @param options Optional parameters including table name override and user credentials
-     * @returns The result of the Scan operation, containing the scanned items.
+     * Create a typed update builder for this table schema.
+     *
+     * This follows the dev guide's principle: keep runtime behavior stable and layer
+     * compile-time safety via types.
+     */
+    createUpdateBuilder() {
+        return new TypedUpdateExpressionBuilder();
+    }
+    /**
+     * Type-safe query builder wrapper.
+     *
+     * This is the preferred API for new code because it:
+     * - Validates index names at compile time
+     * - Avoids brittle KeyConditionExpression strings
+     * - Returns typed items
+     *
+     * Runtime behavior is equivalent to calling `queryItems()` with the built params.
      */
+    async queryTyped(params, options) {
+        var _a, _b;
+        const built = buildKeyConditionExpression(params.keyCondition);
+        const ExpressionAttributeNames = Object.assign(Object.assign({}, built.ExpressionAttributeNames), ((_a = params.expressionAttributeNames) !== null && _a !== void 0 ? _a : {}));
+        const ExpressionAttributeValues = Object.assign(Object.assign({}, built.ExpressionAttributeValues), ((_b = params.expressionAttributeValues) !== null && _b !== void 0 ? _b : {}));
+        const result = await this.queryItems(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (params.index ? { IndexName: params.index } : {})), { KeyConditionExpression: built.KeyConditionExpression, ExpressionAttributeNames,
+            ExpressionAttributeValues }), (params.filterExpression ? { FilterExpression: params.filterExpression } : {})), (params.select ? { Select: params.select } : {})), (params.scanIndexForward !== undefined
+            ? { ScanIndexForward: params.scanIndexForward }
+            : {})), (params.limit !== undefined ? { Limit: params.limit } : {})), (params.exclusiveStartKey ? { ExclusiveStartKey: params.exclusiveStartKey } : {})), options);
+        return {
+            items: (result.Items || []),
+            count: result.Count || 0,
+            lastEvaluatedKey: result.LastEvaluatedKey,
+        };
+    }
+    /**
+     * Async generator that paginates through all results using the typed query API.
+     * This mirrors `queryAllPages()` but avoids stringly-typed key expressions.
+     */
+    queryAllPagesTyped(params, options) {
+        return __asyncGenerator(this, arguments, function* queryAllPagesTyped_1() {
+            let exclusiveStartKey;
+            do {
+                const page = yield __await(this.queryTyped(Object.assign(Object.assign({}, params), { exclusiveStartKey }), options));
+                yield yield __await(page);
+                exclusiveStartKey = page.lastEvaluatedKey;
+            } while (exclusiveStartKey);
+        });
+    }
     async scanItems(params, options) {
         return this.executeWithRetry(async () => {
             const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
@@ -400,31 +404,22 @@ export class DynamoDbService extends BaseAwsService {
      */
     scanAllPages(params, options) {
         return __asyncGenerator(this, arguments, function* scanAllPages_1() {
-            var _a;
+            var _a, _b;
             const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
             let lastEvaluatedKey;
             do {
                 const result = yield __await(this.scanItems(Object.assign(Object.assign({}, params), { ExclusiveStartKey: lastEvaluatedKey }), { tableName, userCredentials: options === null || options === void 0 ? void 0 : options.userCredentials }));
                 yield yield __await({
-                    items: (result.Items || []),
+                    items: ((_a = result.Items) !== null && _a !== void 0 ? _a : []),
                     count: result.Count || 0,
                     scannedCount: result.ScannedCount,
                     lastEvaluatedKey: result.LastEvaluatedKey,
-                    consumed: (_a = result.ConsumedCapacity) === null || _a === void 0 ? void 0 : _a.CapacityUnits,
+                    consumed: (_b = result.ConsumedCapacity) === null || _b === void 0 ? void 0 : _b.CapacityUnits,
                 });
                 lastEvaluatedKey = result.LastEvaluatedKey;
             } while (lastEvaluatedKey);
         });
     }
-    /**
-     * Performs a batch write operation (put or delete) on multiple items.
-     * @param items An array of items to be put or deleted.
-     * @param operation The operation to perform on the items: "put" or "delete" (default: "put").
-     * @param options Optional parameters including table name override and user credentials
-     * @returns The final result of the BatchWrite operation after all retries.
-     * @throws `Error` if the items array is empty.
-     * @throws `Error` if retry attempts are exhausted.
-     */
     async batchWrite(items, operation = "put", options) {
         invariant(items.length > 0, "Items must be provided");
         return this.executeWithRetry(async () => {
@@ -469,7 +464,12 @@ export class DynamoDbService extends BaseAwsService {
                         break;
                     }
                     // Extract unprocessed items for retry
-                    currentChunk = unprocessed.map((req) => { var _a, _b; return operation === "put" ? (_a = req.PutRequest) === null || _a === void 0 ? void 0 : _a.Item : (_b = req.DeleteRequest) === null || _b === void 0 ? void 0 : _b.Key; });
+                    currentChunk = unprocessed.map((req) => {
+                        var _a, _b;
+                        return operation === "put"
+                            ? (_a = req.PutRequest) === null || _a === void 0 ? void 0 : _a.Item
+                            : (_b = req.DeleteRequest) === null || _b === void 0 ? void 0 : _b.Key;
+                    });
                     retries++;
                     if (retries < maxChunkRetries) {
                         // Exponential backoff before retry
@@ -634,13 +634,6 @@ export class DynamoDbService extends BaseAwsService {
             return result;
         });
     }
-    /**
-     * Retrieves multiple items in a single batch request (up to 100 items)
-     * More efficient than individual get operations
-     * @param params Batch get parameters
-     * @param options Optional parameters including table name override and user credentials
-     * @returns The result containing retrieved items and any unprocessed keys
-     */
     async batchGet(params, options) {
         if (params.keys.length === 0) {
             throw new Error("At least one key must be provided for batch get");
@@ -701,22 +694,6 @@ export class DynamoDbService extends BaseAwsService {
             return { items, unprocessedKeys };
         });
     }
-    /**
-     * Conditional put operation - only puts the item if it doesn't already exist.
-     * Uses attribute_not_exists() condition on the partition key.
-     * @param item The item to put
-     * @param partitionKeyName The name of the partition key attribute
-     * @param options Optional parameters including table name override and user credentials
-     * @returns The result of the put operation
-     * @throws Error if the item already exists (ConditionalCheckFailedException)
-     * @example
-     * ```typescript
-     * await service.putIfNotExists(
-     *   { id: '123', name: 'John' },
-     *   'id'
-     * );
-     * ```
-     */
     async putIfNotExists(item, partitionKeyName, options) {
         return this.executeWithRetry(async () => {
             const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);
@@ -738,28 +715,6 @@ export class DynamoDbService extends BaseAwsService {
             return result;
         });
     }
-    /**
-     * Conditional update operation - only updates the item if it exists.
-     * Uses attribute_exists() condition on the partition key.
-     * @param key The key of the item to update
-     * @param updateExpression The update expression
-     * @param partitionKeyName The name of the partition key attribute
-     * @param options Optional parameters including table name override, expression attribute names/values, additional conditions, and user credentials
-     * @returns The result of the update operation
-     * @throws Error if the item doesn't exist (ConditionalCheckFailedException)
-     * @example
-     * ```typescript
-     * await service.updateIfExists(
-     *   { id: '123' },
-     *   'SET #name = :name',
-     *   'id',
-     *   {
-     *     expressionAttributeNames: { '#name': 'name' },
-     *     expressionAttributeValues: { ':name': 'Jane' }
-     *   }
-     * );
-     * ```
-     */
     async updateIfExists(key, updateExpression, partitionKeyName, options) {
         return this.executeWithRetry(async () => {
             const tableName = this.resolveTableName(options === null || options === void 0 ? void 0 : options.tableName);