graphddb 0.1.1 → 0.2.1

package/README.md

@@ -37,6 +37,64 @@ A partition key is a graph entry point, a relation an explicit traversal path, a
 selection set. GraphDDB does not invent a query language — it executes well-designed access
 patterns directly and makes ambiguity visible through plans, limits, and relation resolution.
 
+## Install
+
+```bash
+npm install graphddb
+```
+
+The AWS SDK v3 is a peer dependency — install the clients you use:
+
+```bash
+npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+```
+
+`tsx` is an optional peer dependency, needed only to run the code-generation CLI
+(`graphddb generate …`) directly against TypeScript definition files. Library
+consumers don't need it (so it never pulls esbuild into your runtime bundle):
+
+```bash
+npm install -D tsx
+```
+
+Requires Node.js ≥ 22.
+
+## Quick Start
+
+```ts
+import { DDBModel, model, string, key, k } from 'graphddb';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+@model({ table: 'AppTable', prefix: 'USER' })
+class UserModel extends DDBModel {
+  static readonly keys = key<{ userId: string }>((c) => ({
+    pk: k`USER#${c.userId}`,
+    sk: k`PROFILE`,
+  }));
+
+  @string userId!: string;
+  @string name!: string;
+}
+const User = UserModel.asModel();
+
+// Wire up the DynamoDB client once (configure retries/region on the client itself).
+DDBModel.setClient(new DynamoDBClient({}));
+
+// Read — only the selected fields appear in the result type.
+const user = await User.query({ userId: 'alice' }, { name: true });
+
+// Single-item write — raw base op, named after the DynamoDB API.
+await User.putItem({ userId: 'alice', name: 'Alice' });
+
+// Multi-item atomic write — the unified envelope (default `mode: 'transaction'`).
+await DDBModel.mutate({
+  user: { update: User, key: { userId: 'alice' }, input: { name: 'Alice B.' } },
+});
+```
+
+For cross-service contracts, the Python bridge, multi-fragment atomic mutations,
+and more, see the sections below and [`docs/spec.md`](./docs/spec.md).
+
 ## User Permissions Example
 
 The [user-permissions](./examples/user-permissions/) example models users, groups, memberships, and permissions in a single DynamoDB table.
@@ -217,11 +275,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 +293,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
@@ -275,6 +330,10 @@ are aliased (`ExpressionAttributeNames`) — there is no literal interpolation,
 the compiled expression is injection-free, and it is attached independently of
 the `KeyConditionExpression` / `ProjectionExpression`.
 
+The same `cond` fragment is also accepted as a write `condition` (on
+`putItem` / `updateItem` / `deleteItem`, transaction items, and public commands),
+not just as a read filter.
+
 > **RCU note:** A `FilterExpression` does **not** reduce read capacity —
 > DynamoDB reads matching keys first, then filters. `limit` is applied
 > **before** the filter, so a single page may return **fewer** than `limit`
@@ -283,23 +342,84 @@ 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 a `WriteCondition` write gate — the same declarative
+  operator subset as read filters (`eq`/`ne`/comparisons/`between`/`in`/string
+  ops/`size`/`attributeType` + `and`/`or`/`not`), the legacy existence primitives
+  (`notExists` / `attributeExists` / `attributeNotExists`), or a raw `cond`
+  fragment.
+- **`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.
@@ -461,7 +581,6 @@ Layer 5: Hydrator
 | Structured keys | Keys are built from `k` segment templates; partial keys compile to `begins_with` at a segment boundary. |
 | Typed consistentRead | `consistentRead` is only available for PK queries. GSI queries are rejected at compile time. |
 | Server-side filter | `filter` is a declarative DynamoDB `FilterExpression` (AppSync `ModelFilterInput`-compatible), typed against the full entity and able to reference unprojected attributes. It does not reduce RCU, and `limit` is applied before it. |
-| Post-load filtering | No built-in post-load predicate; use `result.items.filter(...)` on the typed projection. Efficient narrowing belongs in key design. |
 
 ## Architectural Boundaries
 
@@ -529,7 +648,7 @@ The query / relation / write API above is the core layer. GraphDDB also ships:
 - Entity metadata / decorators
 - DDBModel base class / connection management
 - Type system (SelectableOf, QueryResult, QueryKeyOf)
-- CRUD (put, update, delete, conditional writes)
+- CRUD (put, update, delete, conditional writes — `WriteCondition` shares the full declarative filter operator set plus the `cond` raw escape hatch)
 - Query / List (planner, executor, hydrator, cursor pagination)
 - Type-safe filtering: declarative server-side `filter` (FilterExpression / AppSync `ModelFilterInput`-compatible), plus `Model.col` column refs and the `cond` raw escape hatch
 - Structured segment keys (`k` tag): partial keys compile to `begins_with` at a segment boundary