@lafken/dynamo 0.12.12 → 0.12.13

package/lib/service/query-builder/base/base.js

@@ -19,6 +19,9 @@ class QueryBuilderBase {
         sort && this.validateGlobalKey(Object.keys(sort), isGlobalIndex);
         const partitionFilters = [];
         for (const key in partition) {
+            if (partition[key] === undefined) {
+                continue;
+            }
             partitionFilters.push(this.resolveFilter({
                 expressionName: key,
                 value: partition[key],
@@ -50,6 +53,9 @@ class QueryBuilderBase {
             }
         }
         for (const key in sortValues) {
+            if (sortValues[key] === undefined) {
+                continue;
+            }
             let filterExpressionKey = 'equal';
             let sortValue = sort[key];
             if (typeof sortValue === 'object') {

package/lib/service/query-builder/dynamo-index/dynamo-index.js

@@ -41,12 +41,14 @@ class DynamoIndexes {
             }
             return index;
         }
-        const partitionKeys = Object.keys(partition);
-        const sortKeys = Object.keys(sort || {});
+        const partitionKeys = Object.keys(partition).filter((key) => partition[key] !== undefined);
+        const sortKeys = Object.keys(sort || {}).filter((key) => sort?.[key] !== undefined);
         if (partitionKeys.length > 1 || sortKeys.length > 1) {
             return this.getGlobalIndex(new Set(partitionKeys), new Set(sortKeys));
         }
-        if (this.partitionKey === partitionKeys[0] && this.sortKey !== sortKeys[0]) {
+        if (this.partitionKey === partitionKeys[0] &&
+            this.sortKey !== sortKeys[0] &&
+            sortKeys[0] !== undefined) {
             const index = this.getLocalIndex(sortKeys[0]);
             if (index) {
                 return index;

package/lib/service/query-builder/find/find.js

@@ -42,12 +42,6 @@ class FindBuilder extends base_1.QueryBuilderBase {
         const command = new client_dynamodb_1.QueryCommand(input);
         const { Items = [], LastEvaluatedKey } = await this.queryOptions.client.send(command);
         const resultData = Items.map((item) => (0, util_dynamodb_1.unmarshall)(item));
-        if (input.Limit === 1) {
-            return {
-                data: [resultData[0]],
-                cursor: LastEvaluatedKey ? (0, util_dynamodb_1.unmarshall)(LastEvaluatedKey) : undefined,
-            };
-        }
         const items = data.concat(resultData);
         if (LastEvaluatedKey && (!input.Limit || items.length < input.Limit)) {
             return this.runQuery({

package/lib/service/query-builder/find-all/find-all.js

@@ -7,7 +7,6 @@ class FindAllBuilder extends find_1.FindBuilder {
     constructor(queryOptions) {
         super(queryOptions);
         this.queryOptions = queryOptions;
-        this.find();
     }
     then(resolve, reject) {
         return this.exec().then(resolve, reject);

package/lib/service/query-builder/find-one/find-one.js

@@ -7,7 +7,6 @@ class FindOneBuilder extends find_1.FindBuilder {
     constructor(queryOptions) {
         super(queryOptions);
         this.queryOptions = queryOptions;
-        this.find();
     }
     then(resolve, reject) {
         return this.exec().then(resolve, reject);

package/lib/service/repository/repository.types.d.ts

@@ -16,19 +16,156 @@ import type { ScanBuilder } from '../query-builder/scan/scan';
 import type { UpdateBuilder } from '../query-builder/update/update';
 import type { UpsertBuilder } from '../query-builder/upsert/upsert';
 export type RepositoryReturn<E extends ClassResource> = {
+    /**
+     * Queries a single item using `QueryCommand`.
+     *
+     * Builds a `KeyConditionExpression` from `keyCondition` and automatically resolves the
+     * secondary index (GSI/LSI) to use when applicable. Optionally applies a `FilterExpression`
+     * on the results and enforces `Limit: 1`. If `cacheTtl` is provided, the result is stored
+     * in the in-memory cache keyed by table name and `inputProps`.
+     *
+     * @param inputProps - Query conditions: `keyCondition`, `filter`, `projection`, `cursor`, `limit`, `sortDirection`.
+     * @param cacheTtl - In-memory cache TTL in seconds. If omitted, no caching is applied.
+     * @returns Thenable builder that resolves with the first matching item or `undefined`.
+     */
     findOne(inputProps: QueryOneProps<E>, cacheTtl?: number): FindOneBuilder<E>;
+    /**
+     * Queries multiple items using `QueryCommand`.
+     *
+     * Builds a `KeyConditionExpression` from `keyCondition` and automatically resolves the
+     * secondary index (GSI/LSI) to use when applicable. Optionally applies a `FilterExpression`,
+     * pagination via `ExclusiveStartKey` (cursor), `Limit`, `ProjectionExpression`, and sort
+     * direction. Automatically paginates until all results are retrieved. If `cacheTtl` is
+     * provided, the result is stored in the in-memory cache.
+     *
+     * @param inputProps - Query conditions: `keyCondition`, `filter`, `projection`, `cursor`, `limit`, `sortDirection`.
+     * @param cacheTtl - In-memory cache TTL in seconds. If omitted, no caching is applied.
+     * @returns Thenable builder that resolves with `{ data, cursor }`.
+     */
     findAll(inputProps: QueryProps<E>, cacheTtl?: number): FindAllBuilder<E>;
+    /**
+     * Scans the entire table using `ScanCommand`.
+     *
+     * Unlike `findAll`, does not require a `keyCondition` and reads every item in the table.
+     * Optionally applies a `FilterExpression`, pagination via `ExclusiveStartKey` (cursor),
+     * `Limit`, and `ProjectionExpression`. Automatically paginates until the requested limit is
+     * reached. **Avoid on large tables due to high read capacity consumption.**
+     *
+     * @param inputProps - Optional parameters: `filter`, `projection`, `cursor`, `limit`.
+     * @returns Thenable builder that resolves with `{ data, cursor }`.
+     */
     scan(inputProps?: FindProps<E>): ScanBuilder<E>;
+    /**
+     * Creates or replaces an item using `PutItemCommand`.
+     *
+     * If an item with the same primary key already exists, it is fully overwritten.
+     * Optionally accepts a `ConditionExpression` via `inputProps.condition` to guard the write
+     * (e.g. verify an attribute has a specific value before writing).
+     *
+     * @param item - The full item to write to the table.
+     * @param inputProps - Optional parameters: `condition` for `ConditionExpression`.
+     * @returns Thenable builder that resolves with the written item.
+     */
     upsert(item: Item<E>, inputProps?: UpsertProps<E>): UpsertBuilder<E>;
+    /**
+     * Creates a new item using `PutItemCommand`, ensuring it does not already exist.
+     *
+     * Internally adds an automatic `ConditionExpression` using `attribute_not_exists` on the
+     * partition key (and sort key if present), causing the operation to fail if the item already
+     * exists. Does not accept additional conditions.
+     *
+     * @param item - The item to create. Throws a DynamoDB error if the item already exists.
+     * @returns Thenable builder that resolves with the created item.
+     */
     create(item: Item<E>): CreateBuilder<E>;
+    /**
+     * Updates attributes of an existing item using `UpdateItemCommand`.
+     *
+     * Builds an `UpdateExpression` with `SET` clauses (for `setValues` and `replaceValues`) and
+     * `REMOVE` clauses (for `removeValues`). The difference between `setValues` and `replaceValues`
+     * is that `setValues` performs a deep merge on nested objects, while `replaceValues` overwrites
+     * the attribute entirely. Optionally applies a `ConditionExpression` via `condition` and returns
+     * previous or new attributes when `returnValue` is specified.
+     *
+     * @param inputProps - `keyCondition` (primary key of the item to update), `setValues`,
+     *   `replaceValues`, `removeValues`, `condition` for `ConditionExpression`, and `returnValue`
+     *   (`'all_old'` | `'all_new'` | `'updated_old'` | `'updated_new'`).
+     * @returns Thenable builder that resolves with the updated item if `returnValue` was specified, or `undefined`.
+     */
     update<R extends ReturnValueOption | undefined = undefined>(inputProps: Omit<UpdateProps<E>, 'returnValue'> & {
         returnValue?: R;
     }): UpdateBuilder<E, R>;
+    /**
+     * Fetches a single item by its exact primary key using `GetItemCommand`.
+     *
+     * Unlike `findOne`, uses `GetItemCommand` instead of `QueryCommand`, making it more efficient
+     * for exact-key lookups. Supports `ConsistentRead` for strongly consistent reads and
+     * `ProjectionExpression` to return only specific attributes. If `cacheTtl` is provided,
+     * the result is stored in the in-memory cache.
+     *
+     * @param key - Primary key of the item (partition key and sort key if applicable).
+     * @param options - Options: `consistentRead`, `projection`, `cacheTtl` for in-memory caching.
+     * @returns Thenable builder that resolves with the found item or `undefined`.
+     */
     getItem(key: TablePartition<Item<E>>, options?: GetItemOptions<E>): GetItemBuilder<E>;
+    /**
+     * Deletes an item by its primary key using `DeleteItemCommand`.
+     *
+     * Does not apply any `ConditionExpression`. If the item does not exist, the operation
+     * completes without error.
+     *
+     * @param key - Primary key of the item to delete (partition key and sort key if applicable).
+     * @returns Thenable builder that resolves with `true` on completion.
+     */
     delete(key: TablePartition<Item<E>>): DeleteBuilder<E>;
+    /**
+     * Fetches multiple items by their primary keys using `BatchGetItemCommand`.
+     *
+     * Automatically splits keys into batches of up to 100 items (DynamoDB limit) and executes
+     * all batches in parallel. Automatically retries `UnprocessedKeys` up to `maxAttempt` times
+     * (default 5). Supports `ConsistentRead` and `ProjectionExpression`.
+     *
+     * @param keys - List of primary keys to retrieve.
+     * @param options - Options: `consistentRead`, `projection`, `maxAttempt` (default: 5).
+     * @returns Thenable builder that resolves with the array of found items.
+     */
     batchGet(keys: TablePartition<Item<E>>[], options?: BatchGetOptions<E>): BatchGetBuilder<E>;
+    /**
+     * Creates multiple items using `BatchWriteItemCommand` with `PutRequest`.
+     *
+     * Automatically splits items into batches of up to 25 (DynamoDB limit) and sends them in
+     * parallel. Automatically retries `UnprocessedItems` up to `maxAttempt` times (default 5).
+     * Does not apply a `ConditionExpression`; if an item already exists, it is overwritten.
+     *
+     * @param items - List of items to write to the table.
+     * @returns Thenable builder that resolves when all writes are complete.
+     */
     bulkCreate(items: Item<E>[]): BulkCreateBuilder<E>;
+    /**
+     * Deletes multiple items using `BatchWriteItemCommand` with `DeleteRequest`.
+     *
+     * Automatically splits keys into batches of up to 25 (DynamoDB limit) and sends them in
+     * parallel. Automatically retries `UnprocessedItems` up to `maxAttempt` times (default 5).
+     * If a key does not exist, the operation completes without error.
+     *
+     * @param keys - List of primary keys of the items to delete.
+     * @returns Thenable builder that resolves when all deletions are complete.
+     */
     bulkDelete(keys: TablePartition<Item<E>>[]): BulkDeleteBuilder<E>;
+    /**
+     * Sends an arbitrary command directly to the DynamoDB client.
+     *
+     * Allows executing SDK commands not covered by the repository methods.
+     *
+     * @param command - Any DynamoDB SDK command (`@aws-sdk/client-dynamodb`).
+     * @returns Promise that resolves with the typed command response.
+     */
     sendRawCommand<T = unknown>(command: Parameters<DynamoDBClient['send']>[0]): Promise<T>;
+    /**
+     * Clears the in-memory cache shared by `findOne`, `findAll`, and `getItem`.
+     *
+     * All cached results are invalidated immediately. Useful after write operations that may
+     * leave stale data in the cache.
+     */
     clearCache(): void;
 };

package/lib/service/transaction/transaction.d.ts

@@ -1,4 +1,30 @@
 import { type TransactWriteItem } from '@aws-sdk/client-dynamodb';
 import type { QueryTransactions } from './transaction.types';
+/**
+ * Resolves the `TransactWriteItem` operation type for a given query builder.
+ *
+ * Maps builder instances to their corresponding DynamoDB transactional operation key:
+ * - `CreateBuilder` / `UpsertBuilder` → `'Put'`
+ * - `UpdateBuilder` → `'Update'`
+ * - `DeleteBuilder` → `'Delete'`
+ *
+ * @param builder - A query builder instance representing one transactional operation.
+ * @throws If the builder type is not supported within a transaction.
+ * @returns The `TransactWriteItem` key (`'Put'` | `'Update'` | `'Delete'`).
+ */
 export declare const getTransactionType: (builder: QueryTransactions) => keyof TransactWriteItem;
+/**
+ * Executes multiple write operations atomically using `TransactWriteItemsCommand`.
+ *
+ * Accepts an array of query builders (`CreateBuilder`, `UpsertBuilder`, `UpdateBuilder`, or
+ * `DeleteBuilder`) and groups them into a single transactional request. DynamoDB guarantees
+ * all operations either succeed or fail together. Supports up to 100 items per transaction
+ * (DynamoDB limit). Does not apply any `ConditionExpression` beyond what each builder already
+ * carries; each builder's command is extracted via `getCommand()` and mapped to the appropriate
+ * `TransactWriteItem` operation type.
+ *
+ * @param queryBuilders - Array of write builders to include in the transaction.
+ * @throws If any builder type is unsupported or if the transaction is rejected by DynamoDB
+ *   (e.g. a condition check fails in one of the items).
+ */
 export declare const transaction: (queryBuilders: QueryTransactions[]) => Promise<void>;

package/lib/service/transaction/transaction.js

@@ -7,6 +7,18 @@ const create_1 = require("../query-builder/create/create");
 const delete_1 = require("../query-builder/delete/delete");
 const update_1 = require("../query-builder/update/update");
 const upsert_1 = require("../query-builder/upsert/upsert");
+/**
+ * Resolves the `TransactWriteItem` operation type for a given query builder.
+ *
+ * Maps builder instances to their corresponding DynamoDB transactional operation key:
+ * - `CreateBuilder` / `UpsertBuilder` → `'Put'`
+ * - `UpdateBuilder` → `'Update'`
+ * - `DeleteBuilder` → `'Delete'`
+ *
+ * @param builder - A query builder instance representing one transactional operation.
+ * @throws If the builder type is not supported within a transaction.
+ * @returns The `TransactWriteItem` key (`'Put'` | `'Update'` | `'Delete'`).
+ */
 const getTransactionType = (builder) => {
     let type;
     if (builder instanceof create_1.CreateBuilder || builder instanceof upsert_1.UpsertBuilder) {
@@ -24,6 +36,20 @@ const getTransactionType = (builder) => {
     return type;
 };
 exports.getTransactionType = getTransactionType;
+/**
+ * Executes multiple write operations atomically using `TransactWriteItemsCommand`.
+ *
+ * Accepts an array of query builders (`CreateBuilder`, `UpsertBuilder`, `UpdateBuilder`, or
+ * `DeleteBuilder`) and groups them into a single transactional request. DynamoDB guarantees
+ * all operations either succeed or fail together. Supports up to 100 items per transaction
+ * (DynamoDB limit). Does not apply any `ConditionExpression` beyond what each builder already
+ * carries; each builder's command is extracted via `getCommand()` and mapped to the appropriate
+ * `TransactWriteItem` operation type.
+ *
+ * @param queryBuilders - Array of write builders to include in the transaction.
+ * @throws If any builder type is unsupported or if the transaction is rejected by DynamoDB
+ *   (e.g. a condition check fails in one of the items).
+ */
 const transaction = async (queryBuilders) => {
     const transactionCommands = queryBuilders.map((builder) => {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lafken/dynamo",
-  "version": "0.12.12",
+  "version": "0.12.13",
   "private": false,
   "description": "Define DynamoDB tables using TypeScript decorators - type-safe, declarative infrastructure with Lafken",
   "keywords": [
@@ -56,31 +56,31 @@
     "lib"
   ],
   "dependencies": {
-    "@aws-sdk/client-dynamodb": "^3.1056.0",
+    "@aws-sdk/client-dynamodb": "^3.1062.0",
     "@aws-sdk/util-dynamodb": "^3.996.2",
     "aws-xray-sdk": "^3.12.0",
     "reflect-metadata": "^0.2.2",
-    "@lafken/resolver": "0.12.12"
+    "@lafken/resolver": "0.12.13"
   },
   "devDependencies": {
-    "@cdktn/provider-aws": "^24.3.0",
+    "@cdktn/provider-aws": "^24.4.0",
     "@swc/core": "^1.15.40",
     "@swc/helpers": "^0.5.23",
-    "@vitest/runner": "^4.1.7",
+    "@vitest/runner": "^4.1.8",
     "aws-sdk-client-mock": "^4.1.0",
     "cdktn": "^0.23.2",
     "cdktn-vitest": "^1.0.0",
     "constructs": "^10.6.0",
     "typescript": "6.0.3",
     "unplugin-swc": "^1.5.9",
-    "vitest": "^4.1.7",
-    "@lafken/common": "0.12.12"
+    "vitest": "^4.1.8",
+    "@lafken/common": "0.12.13"
   },
   "peerDependencies": {
     "@cdktn/provider-aws": ">=23.0.0",
     "cdktn": ">=0.22.0",
     "constructs": "^10.4.5",
-    "@lafken/common": "0.12.12"
+    "@lafken/common": "0.12.13"
   },
   "engines": {
     "node": ">=20.19"