graphddb 0.2.0 → 0.2.2

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.
@@ -272,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`
@@ -339,7 +401,11 @@ const res = await DDBModel.mutate({
 - **`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.
+- **`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`:
@@ -515,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
 
@@ -583,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

package/dist/{chunk-UNRQ5YJT.js → chunk-27XBTYVK.js}

@@ -1,7 +1,7 @@
 import {
   ChangeCaptureRegistry,
   resolveModelClass
-} from "./chunk-347U24SB.js";
+} from "./chunk-3MI43FHU.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {