dinah 0.10.0 → 0.11.1

package/README.md

@@ -99,16 +99,29 @@ 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. For a plain repo with no configuration, use `db.createRepo`:
 
 ```typescript
-const userRepo = db.createRepo(UserTable);
+const userRepo = db.makeRepo(UserTable);
+```
+
+For repos with defaults, transforms, or attribute rules, use `makeRepo` to define a class (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 +139,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 +188,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 +199,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 get (throws on missing or unprocessed)
+const items = await userRepo.batchGetOrThrow([{ userId: "u1" }, { userId: "u2" }]);
 
-// Batch write (puts and deletes)
+// 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

@@ -216,24 +216,26 @@ var ExpressionBuilder = class {
 var Repo = class {
 	table;
 	db;
-	constructor(db, table) {
+	config;
+	constructor(db, table, config) {
 		this.db = db;
 		this.table = table;
+		this.config = config ?? {};
 	}
 	get tableName() {
 		return `${this.db.config?.tableNamePrefix ?? ""}${this.table.def.name}`;
 	}
 	get defaultPutData() {
-		return {};
+		return this.config.defaultPutData?.() ?? {};
 	}
 	get defaultUpdateData() {
-		return {};
+		return this.config.defaultUpdateData?.() ?? {};
 	}
 	transformOutput(item) {
-		return item;
+		return this.config.transformOutput?.(item) ?? item;
 	}
 	transformInput(item) {
-		return item;
+		return this.config.transformInput?.(item) ?? item;
 	}
 	extractKey(item) {
 		const { partitionKey, sortKey } = this.table.def;
@@ -260,10 +262,7 @@ var Repo = class {
 		return this.applyTransformIfNeeded(item, options);
 	}
 	async put(item, options) {
-		const itemWithDefaults = this.transformInput({
-			...this.defaultPutData,
-			...item
-		});
+		const itemWithDefaults = this.applyPutTransforms(item);
 		const result = await this.db.put({
 			table: this.tableName,
 			item: itemWithDefaults,
@@ -422,10 +421,7 @@ var Repo = class {
 			};
 			else return {
 				type: "PUT",
-				item: this.transformInput({
-					...this.defaultPutData,
-					...request.item
-				})
+				item: this.applyPutTransforms(request.item)
 			};
 		}) });
 		return {
@@ -518,10 +514,7 @@ var Repo = class {
 		};
 	}
 	trxPutRequest(item, options) {
-		const itemWithDefaults = this.transformInput({
-			...this.defaultPutData,
-			...item
-		});
+		const itemWithDefaults = this.applyPutTransforms(item);
 		return {
 			table: this.tableName,
 			type: "PUT",
@@ -546,10 +539,7 @@ var Repo = class {
 		const { condition: otherCondition, ...otherOptions } = options ?? {};
 		const condition = { $and: [{ [this.table.def.partitionKey]: { $exists: false } }] };
 		if (otherCondition) condition.$and.push(otherCondition);
-		const itemWithDefaults = this.transformInput({
-			...this.defaultPutData,
-			...item
-		});
+		const itemWithDefaults = this.applyPutTransforms(item);
 		return {
 			table: this.tableName,
 			type: "PUT",
@@ -558,28 +548,39 @@ var Repo = class {
 			...otherOptions
 		};
 	}
+	applyPutTransforms(item) {
+		const result = { ...this.transformInput({
+			...this.defaultPutData,
+			...item
+		}) };
+		for (const key of this.config.derivedAttributes ?? []) delete result[key];
+		return result;
+	}
 	applyNormalizersToExpression(expression) {
 		const partial = {};
-		for (const [key, val] of Object.entries(expression)) {
-			if (val === void 0) continue;
-			if (!isOperation(val)) partial[key] = val;
-			else if (val.$set !== void 0) partial[key] = val.$set;
-			else if (val.$ifNotExists !== void 0) partial[key] = Array.isArray(val.$ifNotExists) ? val.$ifNotExists[1] : val.$ifNotExists;
-		}
+		for (const [key, val] of Object.entries(expression)) if (val === void 0 || isOperation(val) && val.$remove === true) partial[key] = void 0;
+		else if (!isOperation(val)) partial[key] = val;
+		else if (val.$set !== void 0) partial[key] = val.$set;
+		else if (val.$ifNotExists !== void 0) partial[key] = Array.isArray(val.$ifNotExists) ? val.$ifNotExists[1] : val.$ifNotExists;
 		const normalized = this.transformInput(partial);
 		const result = { ...expression };
-		for (const [key, normalizedVal] of Object.entries(normalized)) if (key in partial) {
-			const original = expression[key];
-			if (!isOperation(original)) result[key] = normalizedVal;
-			else if (original.$set !== void 0) result[key] = {
-				...original,
-				$set: normalizedVal
-			};
-			else if (original.$ifNotExists !== void 0) result[key] = {
-				...original,
-				$ifNotExists: Array.isArray(original.$ifNotExists) ? [original.$ifNotExists[0], normalizedVal] : normalizedVal
-			};
-		} else if (normalizedVal !== void 0) result[key] = normalizedVal;
+		for (const [key, normalizedVal] of Object.entries(normalized)) {
+			if (normalizedVal === void 0) continue;
+			if (key in partial && partial[key] === void 0 || !(key in partial)) result[key] = normalizedVal;
+			else {
+				const original = expression[key];
+				if (!isOperation(original)) result[key] = normalizedVal;
+				else if (original.$set !== void 0) result[key] = {
+					...original,
+					$set: normalizedVal
+				};
+				else if (original.$ifNotExists !== void 0) result[key] = {
+					...original,
+					$ifNotExists: Array.isArray(original.$ifNotExists) ? [original.$ifNotExists[0], normalizedVal] : normalizedVal
+				};
+			}
+		}
+		for (const key of [...this.config.derivedAttributes ?? [], ...this.config.immutableAttributes ?? []]) delete result[key];
 		return result;
 	}
 	applyTransformsIfNeeded(items, options) {
@@ -595,11 +596,11 @@ var Repo = class {
 		return transformedItem;
 	}
 };
-const makeRepo = (table) => {
+const makeRepo = (table, config) => {
 	return class extends Repo {
 		static table = table;
 		constructor(db) {
-			super(db, table);
+			super(db, table, config);
 		}
 	};
 };
@@ -619,8 +620,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)));