dinah 0.11.0 → 0.12.0

package/README.md

@@ -99,16 +99,34 @@ const UserTable = new Table(
 
 ### Using the Repository Class
 
-`Repository` is the recommended way to interact with DynamoDB. Created from a `Table`, it provides full type inference for keys, items, queries, and projections:
+`Repo` is the recommended way to interact with DynamoDB. Use `db.makeRepo` to create a repo inline, with or without configuration:
 
 ```typescript
-const userRepo = db.createRepo(UserTable);
+const userRepo = db.makeRepo(UserTable);
+
+const userRepo = db.makeRepo(UserTable, {
+  defaultPutData: () => ({ createdAt: Date.now() }),
+  defaultUpdateData: () => ({ updatedAt: Date.now() }),
+});
+```
+
+To create a named, reusable repo class, use the standalone `makeRepo` (see [Repository Configuration](#repository-configuration)):
+
+```typescript
+import { makeRepo } from "dinah";
+
+class UserRepo extends makeRepo(UserTable, {
+  defaultPutData: () => ({ createdAt: Date.now() }),
+  defaultUpdateData: () => ({ updatedAt: Date.now() }),
+}) {}
+
+const userRepo = new UserRepo(db);
 ```
 
 #### CRUD
 
 ```typescript
-// Create (conditional put - fails if item already exists)
+// Create (conditional put — fails if item already exists)
 const user = await userRepo.create({
   userId: "u1",
   email: "alice@example.com",
@@ -126,14 +144,47 @@ const partial = await userRepo.get({ userId: "u1" }, { projection: ["name", "ema
 // getOrThrow (throws if item not found)
 const aliceOrThrow = await userRepo.getOrThrow({ userId: "u1" });
 
-// Update
+// Put (upsert)
+await userRepo.put({
+  userId: "u1",
+  email: "alice@example.com",
+  name: "Alice",
+  role: "admin",
+  createdAt: Date.now(),
+});
+
+// Update (throws if item does not exist)
 const updated = await userRepo.update(
   { userId: "u1" },
   { name: "Alice Smith", updatedAt: Date.now() },
 );
 
-// Delete
-await userRepo.delete({ userId: "u1" });
+// Delete (returns old item or undefined)
+const deleted = await userRepo.delete({ userId: "u1" });
+
+// deleteOrThrow (throws if item not found)
+const item = await userRepo.deleteOrThrow({ userId: "u1" });
+```
+
+#### Update Expressions
+
+The update argument supports MongoDB-style operators:
+
+```typescript
+await userRepo.update(
+  { userId: "u1" },
+  {
+    name: "Alice", // set
+    age: undefined, // remove
+    score: { $plus: 10 }, // increment
+    score: { $minus: 5 }, // decrement
+    score: { $ifNotExists: 0 }, // set only if missing
+    tags: { $append: "vip" }, // list_append to end
+    tags: { $prepend: "featured" }, // list_append to front
+    followers: { $setAdd: "user-99" }, // ADD to DynamoDB set
+    followers: { $setDel: "user-99" }, // DELETE from DynamoDB set
+  },
+);
 ```
 
 #### Querying
@@ -142,7 +193,10 @@ Queries use a MongoDB-like syntax with operators like `$gt`, `$between`, `$prefi
 
 ```typescript
 // Query by partition key
-const admins = await userRepo.query({ userId: "u1" });
+const posts = await postRepo.query({ authorId: "u1" });
+
+// Query with sort key condition
+const recent = await postRepo.query({ authorId: "u1" }, { postId: { $gte: "2024-" } });
 
 // Query a GSI
 const adminsByDate = await userRepo.queryGsi("byRole", {
@@ -150,82 +204,153 @@ const adminsByDate = await userRepo.queryGsi("byRole", {
   createdAt: { $gt: 1700000000000 },
 });
 
+// Paginated query (async generator, one page at a time)
+for await (const page of postRepo.queryPaged({ authorId: "u1" }, { limit: 20 })) {
+  console.log(page);
+}
+
+// Paginated GSI query
+for await (const page of userRepo.queryGsiPaged("byRole", { role: "admin" })) {
+  console.log(page);
+}
+
 // Scan with filters
 const recentUsers = await userRepo.scan({
   filter: { createdAt: { $gte: 1700000000000 } },
 });
 
-// Paginated query with async iteration
-for await (const page of userRepo.queryGsiPaged("byRole", { role: "admin" })) {
-  console.log(page); // each page is an array of items
-}
+// Scan a GSI
+const allByStatus = await postRepo.scanGsi("byStatus");
+
+// Check existence (uses query or scan, no data returned)
+const hasAdmins = await userRepo.existsGsi("byRole", { query: { role: "admin" } });
+const exists = await postRepo.exists({ query: { authorId: "u1" } });
 ```
 
+Filter operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between`, `$in`, `$nin`, `$prefix`, `$includes`, `$exists`, `$size`, `$type`.
+
 #### Batch Operations
 
 ```typescript
 // Batch get
-const { items, unprocessed } = await userRepo.batchGet([
-  { userId: "u1" },
-  { userId: "u2" },
-  { userId: "u3" },
-]);
+const { items, unprocessed } = await userRepo.batchGet([{ userId: "u1" }, { userId: "u2" }]);
 
-// Batch write (puts and deletes)
+// Batch get (throws on missing or unprocessed)
+const items = await userRepo.batchGetOrThrow([{ userId: "u1" }, { userId: "u2" }]);
+
+// Batch write (puts and deletes mixed)
 await userRepo.batchWrite([
+  {
+    type: "PUT",
+    item: { userId: "u3", email: "c@d.com", name: "Carol", role: "user", createdAt: Date.now() },
+  },
+  { type: "DELETE", key: { userId: "u2" } },
+]);
+
+// Batch update (same update applied to multiple keys via PartiQL)
+await userRepo.batchUpdate([{ userId: "u1" }, { userId: "u3" }], { role: "admin" });
+```
+
+#### Transactions
+
+`trxWrite` accepts plain request objects and executes them as a single DynamoDB transaction:
+
+```typescript
+await userRepo.trxWrite(
   {
     type: "PUT",
     item: {
-      userId: "u4",
-      email: "bob@example.com",
-      name: "Bob",
+      userId: "u5",
+      email: "eve@example.com",
+      name: "Eve",
       role: "user",
       createdAt: Date.now(),
     },
   },
-  { type: "DELETE", key: { userId: "u3" } },
-]);
+  { type: "UPDATE", key: { userId: "u1" }, update: { role: "superadmin" } },
+  { type: "DELETE", key: { userId: "u2" } },
+  { type: "CONDITION", key: { userId: "u3" }, condition: { role: "admin" } },
+);
 ```
 
-#### Transactions
+Convenience methods operate on multiple keys/items atomically:
 
 ```typescript
-await userRepo.trxWrite(
-  userRepo.trxPut({
-    userId: "u5",
-    email: "eve@example.com",
-    name: "Eve",
-    role: "user",
-    createdAt: Date.now(),
-  }),
-  userRepo.trxUpdate({ userId: "u1" }, { role: "superadmin" }),
-  userRepo.trxDelete({ userId: "u2" }),
+// Transactional get
+const [u1, u2] = await userRepo.trxGet([{ userId: "u1" }, { userId: "u2" }]);
+const items = await userRepo.trxGetOrThrow([{ userId: "u1" }, { userId: "u2" }]);
+
+// Transactional writes
+await userRepo.trxPut([item1, item2]);
+await userRepo.trxUpdate([{ userId: "u1" }, { userId: "u2" }], { role: "admin" });
+await userRepo.trxDelete([{ userId: "u1" }, { userId: "u2" }]);
+await userRepo.trxCreate([item1, item2]); // fails if any item already exists
+```
+
+To build cross-repo transactions, use the `*Request` methods to produce request objects and pass them to `db.trxWrite`:
+
+```typescript
+await db.trxWrite(
+  userRepo.trxPutRequest(userItem),
+  postRepo.trxDeleteRequest({ authorId: "u1", postId: "p1" }),
 );
 ```
 
-### Default Values
+## Repository Configuration
 
-To attach defaults like timestamps to every write, subclass `AbstractRepo` and override `defaultPutData` and/or `defaultUpdateData`:
+`makeRepo` accepts a config object that controls defaults, transforms, and attribute rules. Extend the result to create a named repo class:
 
 ```typescript
-import { AbstractRepo } from "dinah";
+class UserRepo extends makeRepo(UserTable, {
+  defaultPutData: () => ({ createdAt: Date.now() }),
+  defaultUpdateData: () => ({ updatedAt: Date.now() }),
+}) {}
+```
 
-class UserRepo extends AbstractRepo<typeof UserTable> {
-  readonly table = UserTable;
+`defaultPutData` is merged under every `put` / `create` / `batchWrite` put / `trxPut` / `trxCreate`. `defaultUpdateData` is merged under every `update` / `batchUpdate` / `trxUpdate`. Caller-provided values always win.
 
-  override get defaultPutData() {
-    return { createdAt: Date.now() };
-  }
+### transformInput / transformOutput
 
-  override get defaultUpdateData() {
-    return { updatedAt: Date.now() };
-  }
-}
+`transformInput` runs on every write (after defaults are merged) and receives a partial of the schema. `transformOutput` runs on every read and maps the stored shape to your desired return type:
 
-const userRepo = new UserRepo(db);
+```typescript
+class UserRepo extends makeRepo(UserTable, {
+  transformInput: (item) => ({
+    ...item,
+    email: item.email?.toLowerCase(),
+  }),
+  transformOutput: (item): UserWithDisplayName => ({
+    ...item,
+    displayName: `${item.name} <${item.email}>`,
+  }),
+}) {}
+```
+
+Transforms are skipped when a `projection` option is provided, since only a subset of fields is available.
+
+### derivedAttributes / immutableAttributes
+
+`derivedAttributes` lists fields that are computed by `transformInput` and should never be written directly by the caller. They are stripped from put and update inputs:
+
+```typescript
+class UserRepo extends makeRepo(UserTable, {
+  transformInput: (item) => ({
+    ...item,
+    emailDomain: item.email ? item.email.split("@")[1] : undefined,
+  }),
+  derivedAttributes: ["emailDomain"],
+}) {}
+```
+
+`immutableAttributes` lists fields that may be set on create but must not be changed by updates:
+
+```typescript
+class UserRepo extends makeRepo(UserTable, {
+  immutableAttributes: ["createdAt"],
+}) {}
 ```
 
-`defaultPutData` is merged under every `put` / `create` / `batchWrite` put / `trxPut` / `trxCreate`. `defaultUpdateData` is merged under every `update` / `trxUpdate`. Caller-provided values always win on conflict.
+Both arrays are inferred as literal types — no `as const` needed.
 
 ## License
 

package/dist/index.cjs

@@ -3,6 +3,25 @@ const require_util = require("./util-D88GS6Gt.cjs");
 let _aws_sdk_client_dynamodb = require("@aws-sdk/client-dynamodb");
 let _aws_sdk_lib_dynamodb = require("@aws-sdk/lib-dynamodb");
 _aws_sdk_lib_dynamodb = require_util.__toESM(_aws_sdk_lib_dynamodb, 1);
+//#region src/error.ts
+function dinahErrorMessage(details) {
+	switch (details.type) {
+		case "NOT_FOUND": return `${details.resource ?? "Item"} not found: ${JSON.stringify(details.key)}`;
+		case "CONDITIONAL_CHECK_FAILED": return details.key ? `${details.resource ?? "Item"} condition check failed: ${JSON.stringify(details.key)}` : `${details.resource ?? "Item"} condition check failed`;
+		case "VALIDATION": return `Validation error: ${details.message}`;
+		case "TRANSACTION_CANCELED": return `Transaction canceled: ${details.reasons.map((r) => r.type).join(", ")}`;
+	}
+}
+var DinahError = class extends Error {
+	details;
+	constructor(details, options) {
+		super(dinahErrorMessage(details), options);
+		this.name = "DinahError";
+		this.details = details;
+	}
+};
+const isDinahError = (err) => err instanceof DinahError;
+//#endregion
 //#region src/expression-builder.ts
 const attrTypes = [
 	"S",
@@ -225,6 +244,13 @@ var Repo = class {
 	get tableName() {
 		return `${this.db.config?.tableNamePrefix ?? ""}${this.table.def.name}`;
 	}
+	get resourceName() {
+		if (this.config.resourceName) return this.config.resourceName;
+		const clsName = this.constructor.name;
+		if (clsName && clsName !== "Repo") return clsName.replace(/Repo$/i, "") || clsName;
+		const t = this.table.def.name;
+		return t.charAt(0).toUpperCase() + t.slice(1);
+	}
 	get defaultPutData() {
 		return this.config.defaultPutData?.() ?? {};
 	}
@@ -257,6 +283,7 @@ var Repo = class {
 		const item = await this.db.getOrThrow({
 			table: this.tableName,
 			key: this.extractKey(key),
+			resource: this.resourceName,
 			...options
 		});
 		return this.applyTransformIfNeeded(item, options);
@@ -266,6 +293,7 @@ var Repo = class {
 		const result = await this.db.put({
 			table: this.tableName,
 			item: itemWithDefaults,
+			resource: this.resourceName,
 			...options
 		});
 		return this.applyTransformIfNeeded(result);
@@ -278,6 +306,7 @@ var Repo = class {
 		const result = await this.db.update({
 			table: this.tableName,
 			key: this.extractKey(key),
+			resource: this.resourceName,
 			update: updateWithDefaults,
 			...options
 		});
@@ -296,6 +325,7 @@ var Repo = class {
 		const item = await this.db.delete({
 			table: this.tableName,
 			key: this.extractKey(key),
+			resource: this.resourceName,
 			...options
 		});
 		return item && this.applyTransformIfNeeded(item);
@@ -304,6 +334,7 @@ var Repo = class {
 		const item = await this.db.deleteOrThrow({
 			table: this.tableName,
 			key: this.extractKey(key),
+			resource: this.resourceName,
 			...options
 		});
 		return this.applyTransformIfNeeded(item);
@@ -409,6 +440,7 @@ var Repo = class {
 	async batchGetOrThrow(keys, options) {
 		const result = await this.db.batchGetOrThrow({ [this.tableName]: {
 			keys: keys.map((key) => this.extractKey(key)),
+			resource: this.resourceName,
 			...options
 		} });
 		return this.applyTransformsIfNeeded(result[this.tableName] ?? [], options);
@@ -450,6 +482,7 @@ var Repo = class {
 		const items = await this.db.trxGetOrThrow(...keys.map((key) => ({
 			table: this.tableName,
 			key: this.extractKey(key),
+			resource: this.resourceName,
 			...options
 		})));
 		return this.applyTransformsIfNeeded(items, options);
@@ -620,8 +653,8 @@ var Db = class {
 		}
 		this.config = dbConfig;
 	}
-	createRepo(table) {
-		return new Repo(this, table);
+	makeRepo(table, config) {
+		return new Repo(this, table, config);
 	}
 	async createTable(table) {
 		await this.client.send(new _aws_sdk_client_dynamodb.CreateTableCommand(require_util.extractTableDesc(table)));
@@ -657,7 +690,11 @@ var Db = class {
 	}
 	async getOrThrow(data) {
 		const item = await this.get(data);
-		if (!item) throw new Error(`Item not found in "${data.table}" table.`);
+		if (!item) throw new DinahError({
+			type: "NOT_FOUND",
+			key: data.key,
+			resource: data.resource
+		});
 		return item;
 	}
 	async put(data) {
@@ -672,8 +709,16 @@ var Db = class {
 			ExpressionAttributeNames: exp.attributeNames,
 			ExpressionAttributeValues: exp.attributeValues
 		});
-		const output = await this.client.send(input);
-		return data.returnOld ? output.Attributes : item;
+		try {
+			const output = await this.client.send(input);
+			return data.returnOld ? output.Attributes : item;
+		} catch (err) {
+			if (err instanceof _aws_sdk_client_dynamodb.ConditionalCheckFailedException) throw new DinahError({
+				type: "CONDITIONAL_CHECK_FAILED",
+				resource: data.resource
+			}, { cause: err });
+			throw err;
+		}
 	}
 	async update(data) {
 		const exp = new ExpressionBuilder();
@@ -689,7 +734,16 @@ var Db = class {
 			ExpressionAttributeNames: exp.attributeNames,
 			ExpressionAttributeValues: exp.attributeValues
 		});
-		return (await this.client.send(input)).Attributes;
+		try {
+			return (await this.client.send(input)).Attributes;
+		} catch (err) {
+			if (err instanceof _aws_sdk_client_dynamodb.ConditionalCheckFailedException) throw new DinahError({
+				type: "CONDITIONAL_CHECK_FAILED",
+				key: data.key,
+				resource: data.resource
+			}, { cause: err });
+			throw err;
+		}
 	}
 	async delete(data) {
 		const exp = new ExpressionBuilder();
@@ -702,11 +756,24 @@ var Db = class {
 			ExpressionAttributeNames: exp.attributeNames,
 			ExpressionAttributeValues: exp.attributeValues
 		});
-		return (await this.client.send(input)).Attributes;
+		try {
+			return (await this.client.send(input)).Attributes;
+		} catch (err) {
+			if (err instanceof _aws_sdk_client_dynamodb.ConditionalCheckFailedException) throw new DinahError({
+				type: "CONDITIONAL_CHECK_FAILED",
+				key: data.key,
+				resource: data.resource
+			}, { cause: err });
+			throw err;
+		}
 	}
 	async deleteOrThrow(data) {
 		const item = await this.delete(data);
-		if (!item) throw new Error(`Item not found in "${data.table}" table.`);
+		if (!item) throw new DinahError({
+			type: "NOT_FOUND",
+			key: data.key,
+			resource: data.resource
+		});
 		return item;
 	}
 	async *queryPaged(data) {
@@ -863,7 +930,11 @@ var Db = class {
 		const { items, unprocessed } = await this.batchGet(data);
 		for (const table of Object.keys(data)) {
 			if (unprocessed?.[table]) throw new Error(`One or more batch get requests were not processed in "${table}" table.`);
-			if (items[table]?.length !== data[table]?.keys?.length) throw new Error(`One or more items were not found in "${table}" table.`);
+			if (items[table]?.length !== data[table]?.keys?.length) throw new DinahError({
+				type: "NOT_FOUND",
+				key: {},
+				resource: data[table]?.resource
+			});
 		}
 		return items;
 	}
@@ -983,7 +1054,11 @@ var Db = class {
 	}
 	async trxGetOrThrow(...requests) {
 		const items = await this.trxGet(...requests);
-		for (let i = 0; i < items.length; i++) if (!items[i]) throw new Error(`One or more items were not found in "${requests[i]?.table}" table.`);
+		for (let i = 0; i < items.length; i++) if (!items[i]) throw new DinahError({
+			type: "NOT_FOUND",
+			key: requests[i]?.key ?? {},
+			resource: requests[i]?.resource
+		});
 		return items;
 	}
 	async trxWrite(...requests) {
@@ -1013,7 +1088,18 @@ var Db = class {
 			} };
 		});
 		const input = new _aws_sdk_lib_dynamodb.TransactWriteCommand({ TransactItems: trxItems });
-		await this.client.send(input);
+		try {
+			await this.client.send(input);
+		} catch (err) {
+			if (err instanceof _aws_sdk_client_dynamodb.TransactionCanceledException) throw new DinahError({
+				type: "TRANSACTION_CANCELED",
+				reasons: (err.CancellationReasons ?? []).map((r) => ({
+					type: r.Code ?? "Unknown",
+					message: r.Message
+				}))
+			}, { cause: err });
+			throw err;
+		}
 	}
 };
 //#endregion
@@ -1028,10 +1114,12 @@ var Table = class {
 };
 //#endregion
 exports.Db = Db;
+exports.DinahError = DinahError;
 exports.Repo = Repo;
 exports.Table = Table;
 exports.chunk = require_util.chunk;
 exports.extractTableDesc = require_util.extractTableDesc;
+exports.isDinahError = isDinahError;
 exports.makeRepo = makeRepo;
 exports.removeUndefined = require_util.removeUndefined;
 exports.resolveAttrType = require_util.resolveAttrType;