@lafken/dynamo 0.14.4 → 0.15.0

package/README.md

@@ -459,14 +459,32 @@ const result = await orderRepository
 
 If `indexName` is omitted, the repository automatically selects the best matching index based on the key condition attributes.
 
+#### Custom Client
+
+By default every repository shares a `DynamoDBClient` built from the ambient AWS SDK configuration (the region, credentials and endpoint the SDK resolves from the environment). Pass a `client` to reach a table on a different region, account or endpoint, such as a local DynamoDB instance during development:
+
+```typescript
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import { createRepository } from '@lafken/dynamo/service';
+
+const client = new DynamoDBClient({
+  endpoint: 'http://localhost:8000',
+  region: 'us-east-1',
+});
+
+export const contactRepository = createRepository(Contact, { client });
+```
+
+Reuse the same instance across your models instead of creating one per repository, so they share a single connection pool.
+
 ### Transactions
 
-Group multiple write operations (create, update, upsert, delete) into an atomic transaction. All operations succeed or fail together:
+`transactionWrite` groups multiple write operations (create, update, upsert, delete) into an atomic transaction. All operations succeed or fail together:
 
 ```typescript
-import { transaction } from '@lafken/dynamo/service';
+import { transactionWrite } from '@lafken/dynamo/service';
 
-await transaction([
+await transactionWrite([
   contactRepository.create({
     email: 'new@example.com',
     company: 'Acme',
@@ -485,7 +503,29 @@ await transaction([
 ```
 
 > [!NOTE]
-> Transaction builders are passed without calling `.exec()` — the `transaction` function handles execution internally.
+> Transaction builders are passed without calling `.exec()` — the `transactionWrite` function handles execution internally.
+
+The transaction is sent with the client of the repositories that created the builders, so every repository taking part in it must share the same client instance. A transaction is a single request and cannot be split across connections: mixing clients throws before anything is sent.
+
+#### Transactional Reads
+
+`transactionGet` reads several items atomically, from any number of tables, so all of them come from the same consistent snapshot. It accepts **only `getItem` queries** — any other builder throws — and resolves the items in the same order they were requested, typed by position:
+
+```typescript
+import { transactionGet } from '@lafken/dynamo/service';
+
+const [contact, order] = await transactionGet([
+  contactRepository.getItem({ email: 'jane@example.com', company: 'Acme' }),
+  orderRepository.getItem({ customerId: 'cust-1', orderId: 'ord-1' }),
+]);
+```
+
+`contact` is `Contact | undefined` and `order` is `Order | undefined`: an item that does not exist resolves as `undefined` in its position.
+
+Unlike `batchGet`, which splits its keys into several requests over a single table, this is one request and cannot be chunked — DynamoDB limits it to 100 items.
+
+> [!NOTE]
+> `consistentRead` and `cacheTtl` do not apply to the queries of a read transaction: it is already strongly consistent, and the in-memory cache is never read nor populated.
 
 ### Extending the Table
 

package/lib/service/query-builder/base/base.d.ts

@@ -1,3 +1,4 @@
+import type { DynamoDBClient } from '@aws-sdk/client-dynamodb';
 import type { ClassResource } from '@lafken/common';
 import type { LocalIndex } from '../../../main';
 import type { GlobalIndexProperty } from '../dynamo-index/dynamo-index.types';
@@ -9,6 +10,14 @@ export declare class QueryBuilderBase<E extends ClassResource> {
     protected attributeNames: Record<string, string>;
     protected attributeValues: Record<string, any>;
     protected expressionGroupCounter: number;
+    /**
+     * Returns the DynamoDB client used to execute this query.
+     *
+     * It is the client injected into the repository that created the builder, and it allows
+     * operations grouping several builders, like the transactions, to send their command through
+     * the same connection the builders would have used on their own.
+     */
+    getClient(): DynamoDBClient;
     protected getKeyConditionExpression(expression: KeyCondition<E>, index?: LocalIndex<E> | GlobalIndexProperty): string;
     protected getFilterExpression<T>(filter: Filter<T> | OrFilter<T> | AndFilter<T>, names?: string[], union?: 'or' | 'and', counter?: number): string;
     protected getProjectionExpression(projection?: (string | number | symbol)[] | 'ALL'): string | undefined;

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

@@ -5,13 +5,22 @@ const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
 const base_utils_1 = require("./base.utils");
 class QueryBuilderBase {
     options;
-    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: ''
     constructor(options) {
         this.options = options;
     }
     attributeNames = {};
     attributeValues = {};
     expressionGroupCounter = 0;
+    /**
+     * Returns the DynamoDB client used to execute this query.
+     *
+     * It is the client injected into the repository that created the builder, and it allows
+     * operations grouping several builders, like the transactions, to send their command through
+     * the same connection the builders would have used on their own.
+     */
+    getClient() {
+        return this.options.client;
+    }
     getKeyConditionExpression(expression, index) {
         const { partition, sort } = expression;
         const isGlobalIndex = index?.type === 'global';

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

@@ -1,3 +1,3 @@
 import type { ClassResource } from '@lafken/common';
-import type { RepositoryReturn } from './repository.types';
-export declare const createRepository: <E extends ClassResource>(model: E) => RepositoryReturn<E>;
+import type { RepositoryOptions, RepositoryReturn } from './repository.types';
+export declare const createRepository: <E extends ClassResource>(model: E, options?: RepositoryOptions) => RepositoryReturn<E>;

package/lib/service/repository/repository.js

@@ -16,10 +16,10 @@ const scan_1 = require("../query-builder/scan/scan");
 const update_1 = require("../query-builder/update/update");
 const upsert_1 = require("../query-builder/upsert/upsert");
 const repository_utils_1 = require("./repository.utils");
-const createRepository = (model) => {
+const createRepository = (model, options = {}) => {
     const { modelProps, partitionKey, sortKey, fields } = (0, repository_utils_1.getModelInformation)(model);
     const queryBuilderProps = {
-        client: client_1.client,
+        client: options.client ?? client_1.client,
         fields,
         modelProps,
         partitionKey,

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

@@ -15,6 +15,18 @@ import type { GetItemOptions } from '../query-builder/get-item/get-item.types';
 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 interface RepositoryOptions {
+    /**
+     * DynamoDB client used by every query of the repository.
+     *
+     * Injecting a client is the way to reach a table on a different region, account or endpoint,
+     * for example a local DynamoDB instance during development. Repositories taking part in the
+     * same transaction must share the same client instance.
+     *
+     * @default The shared client built from the ambient AWS SDK configuration.
+     */
+    client?: DynamoDBClient;
+}
 export type RepositoryReturn<E extends ClassResource> = {
     /**
      * Queries a single item using `QueryCommand`.

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

@@ -1,2 +1,2 @@
-export * from './transaction';
-export * from './transaction.types';
+export * from './transaction-get';
+export * from './transaction-write';

package/lib/service/transaction/index.js

@@ -14,5 +14,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./transaction"), exports);
-__exportStar(require("./transaction.types"), exports);
+__exportStar(require("./transaction-get"), exports);
+__exportStar(require("./transaction-write"), exports);

package/lib/service/transaction/transaction-get/index.d.ts

@@ -0,0 +1,2 @@
+export * from './transaction-get';
+export * from './transaction-get.types';

package/lib/service/transaction/transaction-get/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./transaction-get"), exports);
+__exportStar(require("./transaction-get.types"), exports);

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

@@ -0,0 +1,22 @@
+import type { QueryGetTransactions, TransactionGetResult } from './transaction-get.types';
+/**
+ * Reads several items atomically using `TransactGetItemsCommand`.
+ *
+ * Accepts only `getItem` builders, from any number of tables, and resolves their items in the
+ * same order they were requested, with `undefined` for the ones that do not exist. Every item
+ * is read from the same consistent snapshot, unlike `batchGet`, which splits the keys into
+ * several requests over a single table. Supports up to 100 items per transaction (DynamoDB
+ * limit).
+ *
+ * The request is sent with the client of the repositories that created the builders, so every
+ * builder must share the same client instance: a transaction is a single request and cannot be
+ * split across connections. An empty array is a no-op.
+ *
+ * `consistentRead` and `cacheTtl` do not apply here: a transactional read is already strongly
+ * consistent, and the in-memory cache is never read nor populated.
+ *
+ * @param queryBuilders - Array of `getItem` builders to include in the transaction.
+ * @throws If any query is not a `getItem`, if the builders do not share the same client, or if
+ *   the transaction is rejected by DynamoDB.
+ */
+export declare const transactionGet: <T extends readonly QueryGetTransactions[]>(queryBuilders: [...T]) => Promise<TransactionGetResult<T>>;

package/lib/service/transaction/transaction-get/transaction-get.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transactionGet = void 0;
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
+const get_item_1 = require("../../query-builder/get-item/get-item");
+const transaction_utils_1 = require("../transaction.utils");
+/**
+ * Reads several items atomically using `TransactGetItemsCommand`.
+ *
+ * Accepts only `getItem` builders, from any number of tables, and resolves their items in the
+ * same order they were requested, with `undefined` for the ones that do not exist. Every item
+ * is read from the same consistent snapshot, unlike `batchGet`, which splits the keys into
+ * several requests over a single table. Supports up to 100 items per transaction (DynamoDB
+ * limit).
+ *
+ * The request is sent with the client of the repositories that created the builders, so every
+ * builder must share the same client instance: a transaction is a single request and cannot be
+ * split across connections. An empty array is a no-op.
+ *
+ * `consistentRead` and `cacheTtl` do not apply here: a transactional read is already strongly
+ * consistent, and the in-memory cache is never read nor populated.
+ *
+ * @param queryBuilders - Array of `getItem` builders to include in the transaction.
+ * @throws If any query is not a `getItem`, if the builders do not share the same client, or if
+ *   the transaction is rejected by DynamoDB.
+ */
+const transactionGet = async (queryBuilders) => {
+    if (queryBuilders.length === 0) {
+        return [];
+    }
+    if (queryBuilders.some((builder) => !(builder instanceof get_item_1.GetItemBuilder))) {
+        throw new Error('The transaction includes a query that is not a getItem');
+    }
+    const client = (0, transaction_utils_1.getTransactionClient)(queryBuilders);
+    const command = new client_dynamodb_1.TransactGetItemsCommand({
+        TransactItems: queryBuilders.map((builder) => {
+            const { TableName, Key, ProjectionExpression, ExpressionAttributeNames } = builder.getCommand();
+            return {
+                Get: { TableName, Key, ProjectionExpression, ExpressionAttributeNames },
+            };
+        }),
+    });
+    const { Responses = [] } = await client.send(command);
+    return queryBuilders.map((_, index) => {
+        const item = Responses[index]?.Item;
+        return item ? (0, util_dynamodb_1.unmarshall)(item) : undefined;
+    });
+};
+exports.transactionGet = transactionGet;

package/lib/service/transaction/transaction-get/transaction-get.types.d.ts

@@ -0,0 +1,13 @@
+import type { ClassResource } from '@lafken/common';
+import type { GetItemBuilder } from '../../query-builder/get-item/get-item';
+export type QueryGetTransactions = GetItemBuilder<any>;
+/**
+ * Maps a tuple of `getItem` builders to the tuple of items they resolve.
+ *
+ * Keeps the result typed by position, so builders from different models do not collapse into
+ * a single union: `[userRepository.getItem(...), orderRepository.getItem(...)]` resolves as
+ * `[User | undefined, Order | undefined]`.
+ */
+export type TransactionGetResult<T extends readonly QueryGetTransactions[]> = {
+    [K in keyof T]: T[K] extends GetItemBuilder<infer E extends ClassResource> ? InstanceType<E> | undefined : never;
+};

package/lib/service/transaction/transaction-write/index.d.ts

@@ -0,0 +1,2 @@
+export * from './transaction-write';
+export * from './transaction-write.types';

package/lib/service/transaction/transaction-write/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./transaction-write"), exports);
+__exportStar(require("./transaction-write.types"), exports);

package/lib/service/transaction/{transaction.d.ts → transaction-write/transaction-write.d.ts}

@@ -1,5 +1,5 @@
 import { type TransactWriteItem } from '@aws-sdk/client-dynamodb';
-import type { QueryTransactions } from './transaction.types';
+import type { QueryTransactions } from './transaction-write.types';
 /**
  * Resolves the `TransactWriteItem` operation type for a given query builder.
  *
@@ -23,8 +23,13 @@ export declare const getTransactionType: (builder: QueryTransactions) => keyof T
  * carries; each builder's command is extracted via `getCommand()` and mapped to the appropriate
  * `TransactWriteItem` operation type.
  *
+ * The request is sent with the client of the repositories that created the builders, so every
+ * builder must share the same client instance: a transaction is a single request and cannot be
+ * split across connections. An empty array is a no-op.
+ *
  * @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).
+ * @throws If any builder type is unsupported, if the builders do not share the same client, 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>;
+export declare const transactionWrite: (queryBuilders: QueryTransactions[]) => Promise<void>;

package/lib/service/transaction/{transaction.js → transaction-write/transaction-write.js}

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.transaction = exports.getTransactionType = void 0;
+exports.transactionWrite = exports.getTransactionType = void 0;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
-const client_1 = require("../client/client");
-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");
+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");
+const transaction_utils_1 = require("../transaction.utils");
 /**
  * Resolves the `TransactWriteItem` operation type for a given query builder.
  *
@@ -46,11 +46,20 @@ exports.getTransactionType = getTransactionType;
  * carries; each builder's command is extracted via `getCommand()` and mapped to the appropriate
  * `TransactWriteItem` operation type.
  *
+ * The request is sent with the client of the repositories that created the builders, so every
+ * builder must share the same client instance: a transaction is a single request and cannot be
+ * split across connections. An empty array is a no-op.
+ *
  * @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).
+ * @throws If any builder type is unsupported, if the builders do not share the same client, or
+ *   if the transaction is rejected by DynamoDB (e.g. a condition check fails in one of the
+ *   items).
  */
-const transaction = async (queryBuilders) => {
+const transactionWrite = async (queryBuilders) => {
+    if (queryBuilders.length === 0) {
+        return;
+    }
+    const client = (0, transaction_utils_1.getTransactionClient)(queryBuilders);
     const transactionCommands = queryBuilders.map((builder) => {
         return {
             [(0, exports.getTransactionType)(builder)]: builder.getCommand(),
@@ -59,6 +68,6 @@ const transaction = async (queryBuilders) => {
     const command = new client_dynamodb_1.TransactWriteItemsCommand({
         TransactItems: transactionCommands,
     });
-    await client_1.client.send(command);
+    await client.send(command);
 };
-exports.transaction = transaction;
+exports.transactionWrite = transactionWrite;

package/lib/service/transaction/transaction-write/transaction-write.types.d.ts

@@ -0,0 +1,5 @@
+import type { CreateBuilder } from '../../query-builder/create/create';
+import type { DeleteBuilder } from '../../query-builder/delete/delete';
+import type { UpdateBuilder } from '../../query-builder/update/update';
+import type { UpsertBuilder } from '../../query-builder/upsert/upsert';
+export type QueryTransactions = CreateBuilder<any> | UpsertBuilder<any> | UpdateBuilder<any, any> | DeleteBuilder<any>;

package/lib/service/transaction/transaction-write/transaction-write.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,13 @@
+import type { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import type { QueryBuilderBase } from '../query-builder/base/base';
+/**
+ * Resolves the client shared by the queries of a transaction.
+ *
+ * A transaction is sent as a single request, so it cannot be split across connections: every
+ * builder must come from repositories using the same client instance.
+ *
+ * @param queryBuilders - Non empty list of builders taking part in the transaction.
+ * @throws If the builders do not share the same client.
+ * @returns The client used to send the transaction.
+ */
+export declare const getTransactionClient: (queryBuilders: readonly QueryBuilderBase<any>[]) => DynamoDBClient;

package/lib/service/transaction/transaction.utils.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTransactionClient = void 0;
+/**
+ * Resolves the client shared by the queries of a transaction.
+ *
+ * A transaction is sent as a single request, so it cannot be split across connections: every
+ * builder must come from repositories using the same client instance.
+ *
+ * @param queryBuilders - Non empty list of builders taking part in the transaction.
+ * @throws If the builders do not share the same client.
+ * @returns The client used to send the transaction.
+ */
+const getTransactionClient = (queryBuilders) => {
+    const client = queryBuilders[0].getClient();
+    if (queryBuilders.some((builder) => builder.getClient() !== client)) {
+        throw new Error('All queries in a transaction must share the same client');
+    }
+    return client;
+};
+exports.getTransactionClient = getTransactionClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lafken/dynamo",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "private": false,
   "description": "Define DynamoDB tables using TypeScript decorators - type-safe, declarative infrastructure with Lafken",
   "keywords": [
@@ -59,7 +59,7 @@
     "@aws-sdk/client-dynamodb": "^3.1106.0",
     "@aws-sdk/util-dynamodb": "^3.996.7",
     "reflect-metadata": "^0.2.2",
-    "@lafken/resolver": "0.14.4"
+    "@lafken/resolver": "0.15.0"
   },
   "devDependencies": {
     "@cdktn/provider-aws": "^25.0.0",
@@ -73,16 +73,16 @@
     "typescript": "7.0.2",
     "unplugin-swc": "^1.5.10",
     "vitest": "^4.1.10",
-    "@lafken/common": "0.14.4"
+    "@lafken/common": "0.15.0"
   },
   "peerDependencies": {
     "@cdktn/provider-aws": ">=23.0.0",
     "cdktn": ">=0.22.0",
     "constructs": ">=10.7.0",
-    "@lafken/common": "0.14.4"
+    "@lafken/common": "0.15.0"
   },
   "engines": {
-    "node": ">=20.19"
+    "node": ">=22.13"
   },
   "publishConfig": {
     "access": "public"

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

@@ -1,5 +0,0 @@
-import type { CreateBuilder } from '../query-builder/create/create';
-import type { DeleteBuilder } from '../query-builder/delete/delete';
-import type { UpdateBuilder } from '../query-builder/update/update';
-import type { UpsertBuilder } from '../query-builder/upsert/upsert';
-export type QueryTransactions = CreateBuilder<any> | UpsertBuilder<any> | UpdateBuilder<any, any> | DeleteBuilder<any>;