graphddb 0.1.1 → 0.2.0

package/README.md

@@ -217,11 +217,8 @@ The return type is inferred from `select`:
 ```ts
 const result = await GroupMembership.list(
   { groupId: 'eng' },
-  {
-    select: { userId: true, role: true },
-    limit: 20,
-    after: cursor,
-  },
+  { userId: true, role: true },
+  { limit: 20, after: cursor },
 );
 // result.items: GroupMembership[]
 // result.cursor: string | null
@@ -238,8 +235,8 @@ logical groups. It is typed against the **full entity**, so it can reference att
 ```ts
 const result = await Order.list(
   { userId: 'u001' },
+  { orderId: true },                  // amount / status need not be projected
   {
-    select: { orderId: true },        // amount / status need not be projected
     filter: {
       status: 'confirmed',            // #status = :v        (equality shorthand)
       amount: { gt: 100 },            // #amount > :v
@@ -283,23 +280,80 @@ the `KeyConditionExpression` / `ProjectionExpression`.
 
 ### Writes
 
+Raw base-table writes are `putItem` / `updateItem` / `deleteItem` — the primitive
+single-item operations with no lifecycle semantics:
+
 ```ts
-await User.put({
+await User.putItem({
   userId: 'alice',
   name: 'Alice',
   email: 'alice@example.com',
   status: 'active',
 });
 
-await GroupMembership.put({
+await GroupMembership.putItem({
   groupId: 'eng',
   userId: 'alice',
   role: 'admin',
 });
 
-await User.update(alice, { status: 'disabled' });
+await User.updateItem({ userId: 'alice' }, { status: 'disabled' });
 ```
 
+Lifecycle-aware single writes — conditional gates, read-back, referential
+effects — go through `DDBModel.mutate`, not the raw primitives (see
+[The in-process unified envelope](#the-in-process-unified-envelope) below).
+
+### The in-process unified envelope
+
+`DDBModel.query` and `DDBModel.mutate` take a single **alias-map envelope** that
+runs multiple routes in one call. This is the in-process analog of a GraphQL
+operation: each alias is a named route, and the result is keyed by the same
+aliases.
+
+`DDBModel.query(map)` runs each read route independently and in parallel — there
+is no cross-route consistency, exactly like GraphQL's parallel field resolution:
+
+```ts
+const { user, members } = await DDBModel.query({
+  user:    { query: User,            key: { userId: 'u1' },   select: { name: true } },
+  members: { list:  GroupMembership, key: { groupId: 'eng' }, select: { role: true }, options: { limit: 20 } },
+});
+// user: Item | null ; members: { items, cursor }
+```
+
+A read route descriptor is `{ query | list: Model, key, select, options? }`
+(exactly one of `query` / `list`). `options` for `query` is
+`{ consistentRead?, maxDepth? }`; for `list` it is `{ limit?, after?, order?, filter? }`.
+
+`DDBModel.mutate(map, { mode })` runs write routes. A write route descriptor is
+`{ create | update | remove: Model, key, input?, condition?, result? }`:
+
+```ts
+const res = await DDBModel.mutate({
+  a: { create: GroupMembership, key: { groupId: 'eng', userId: 'u1' }, input: { role: 'admin' } },
+  b: { update: User, key: { userId: 'u1' }, input: { name: 'Ann' }, condition: { status: 'active' }, result: { select: { name: true } } },
+}, { mode: 'transaction' });
+```
+
+- **`key`** is a single object or an **array of objects** (key-array bulk). A
+  transaction compiles to `TransactWriteItems`; parallel mode compiles to
+  `BatchWriteItem` (chunked, with `UnprocessedItems` retry).
+- **`condition`** is an equality subset that gates the write.
+- **`result: { select, options? }`** reads the written item back; omit it and the
+  route returns void.
+- **`mode: 'transaction'`** (DEFAULT) is one atomic `TransactWriteItems`:
+  all-or-nothing rollback, throws on failure, and a map of more than 25 items
+  errors (it is never split). This is GraphQL's all-or-nothing atomic contract.
+- **`mode: 'parallel'`** is non-atomic: each alias reports partial success in the
+  result object as `{ ok }` | `{ error }`, mirroring GraphQL's per-field partial
+  success. Independent ops run in parallel; dependencies are ordered by
+  `$.alias.field` references.
+
+In GraphQL terms: a transaction is atomic all-or-nothing; parallel is non-atomic
+per-field partial success; and `query` routes are parallel independent reads with
+no cross-route consistency.
+
 ### Inspect Execution Plans
 
 `explain()` shows the DynamoDB operations before they are executed.