@enbox/api 0.2.2 → 0.2.4

package/README.md

@@ -17,6 +17,10 @@ The high-level SDK for building decentralized applications with protocol-first d
   - [Record Instances](#record-instances)
   - [LiveQuery (Subscriptions)](#livequery-subscriptions)
   - [Web5.anonymous()](#web5anonymousoptions)
+- [Repository Pattern](#repository-pattern)
+  - [Collections vs Singletons](#collections-vs-singletons)
+  - [Nested Records](#nested-records-1)
+  - [Using Pre-built Protocols](#using-pre-built-protocols)
 - [Cookbook](#cookbook)
   - [Nested Records](#nested-records)
   - [Querying with Filters and Pagination](#querying-with-filters-and-pagination)
@@ -24,6 +28,7 @@ The high-level SDK for building decentralized applications with protocol-first d
   - [Publishing Records](#publishing-records)
   - [Reading Public Data Anonymously](#reading-public-data-anonymously)
   - [Sending Records to Remote DWNs](#sending-records-to-remote-dwns)
+- [Code Generation](#code-generation)
 - [Advanced Usage](#advanced-usage)
   - [Unscoped DWN Access](#unscoped-dwn-access)
   - [Permissions](#permissions)
@@ -68,15 +73,16 @@ const notes = web5.using(NotesProtocol);
 // 4. Install the protocol on the local DWN
 await notes.configure();
 
-// 5. Write a record -- path, data, and schema are type-checked
-const { record } = await notes.records.write('note', {
+// 5. Create a record -- path, data, and schema are type-checked
+const { record } = await notes.records.create('note', {
   data: { title: 'Hello', body: 'World' },
 });
 
-// 6. Query records back
+// 6. Query records back -- data is typed automatically
 const { records } = await notes.records.query('note');
 for (const r of records) {
-  console.log(r.id, await r.data.json());
+  const note = await r.data.json(); // { title: string; body: string }
+  console.log(r.id, note.title);
 }
 
 // 7. Send to your remote DWN
@@ -169,22 +175,33 @@ Installs the protocol on the local DWN. If already installed with an identical d
 await chat.configure();
 ```
 
-#### `records.write(path, request)`
+#### `records.create(path, request)`
 
-Write a record at a protocol path. The protocol URI, protocolPath, schema, and dataFormat are automatically injected.
+Create a new record at a protocol path. The protocol URI, protocolPath, schema, and dataFormat are automatically injected. Returns a `TypedRecord<T>` where `T` is inferred from the schema map.
 
 ```ts
-const { record, status } = await chat.records.write('thread', {
+const { record, status } = await chat.records.create('thread', {
   data: { title: 'General', description: 'General discussion' },
 });
 
 console.log(status.code);  // 202
 console.log(record.id);    // unique record ID
+
+// record is TypedRecord<{ title: string; description?: string }>
+const data = await record.data.json(); // typed -- no cast needed
+```
+
+To mutate an existing record, use the instance method `record.update()`:
+
+```ts
+const { record: updated } = await record.update({
+  data: { title: 'Updated Title', description: 'New description' },
+});
 ```
 
 #### `records.query(path, request?)`
 
-Query records at a protocol path. Returns matching records with optional pagination.
+Query records at a protocol path. Returns `TypedRecord<T>[]` with optional pagination.
 
 ```ts
 const { records, cursor } = await chat.records.query('thread', {
@@ -192,8 +209,10 @@ const { records, cursor } = await chat.records.query('thread', {
   pagination : { limit: 20 },
 });
 
+// records is TypedRecord<{ title: string; description?: string }>[]
 for (const thread of records) {
-  console.log(await thread.data.json());
+  const data = await thread.data.json(); // typed automatically
+  console.log(data.title);
 }
 
 // Fetch next page
@@ -228,17 +247,18 @@ const { status } = await chat.records.delete('thread', {
 
 #### `records.subscribe(path, request?)`
 
-Subscribe to real-time changes. Returns a `LiveQuery` with an initial snapshot plus a stream of change events.
+Subscribe to real-time changes. Returns a `TypedLiveQuery<T>` with an initial snapshot of `TypedRecord<T>[]` plus a stream of typed change events.
 
 ```ts
 const { liveQuery } = await chat.records.subscribe('thread/message');
 
-// Initial snapshot
+// Initial snapshot -- typed records
 for (const msg of liveQuery.records) {
-  console.log(await msg.data.json());
+  const data = await msg.data.json(); // { text: string } -- no cast
+  console.log(data.text);
 }
 
-// Real-time updates
+// Real-time updates -- typed records in handlers
 liveQuery.on('create', (record) => console.log('new:', record.id));
 liveQuery.on('update', (record) => console.log('updated:', record.id));
 liveQuery.on('delete', (record) => console.log('deleted:', record.id));
@@ -254,9 +274,11 @@ const { records } = await chat.records.query('thread', {
 
 ---
 
-### Record Instances
+### Record Instances (`TypedRecord<T>`)
+
+Methods like `create`, `query`, and `read` return `TypedRecord<T>` instances -- type-safe wrappers that preserve the data type `T` inferred from the schema map through the entire lifecycle (create, query, read, update, subscribe).
 
-Methods like `write`, `query`, and `read` return `Record` instances.
+`TypedRecord<T>` exposes a typed `data.json()` that returns `Promise<T>` instead of `Promise<unknown>`, eliminating manual type casts. The underlying `Record` is accessible via `record.rawRecord` if needed.
 
 **Properties**:
 
@@ -283,11 +305,11 @@ Methods like `write`, `query`, and `read` return `Record` instances.
 **Data accessors** -- read the record payload in different formats:
 
 ```ts
-const text   = await record.data.text();          // string
-const obj    = await record.data.json<MyType>();  // parsed JSON (typed)
-const blob   = await record.data.blob();          // Blob
-const bytes  = await record.data.bytes();         // Uint8Array
-const stream = await record.data.stream();        // ReadableStream
+const obj    = await record.data.json();   // T -- automatically typed from schema map
+const text   = await record.data.text();   // string
+const blob   = await record.data.blob();   // Blob
+const bytes  = await record.data.bytes();  // Uint8Array
+const stream = await record.data.stream(); // ReadableStream
 ```
 
 **Mutators**:
@@ -317,24 +339,25 @@ await record.import();
 
 ---
 
-### LiveQuery (Subscriptions)
+### LiveQuery (Subscriptions) -- `TypedLiveQuery<T>`
 
-`records.subscribe()` returns a `LiveQuery` that provides an initial snapshot of existing records plus a real-time stream of deduplicated change events.
+`records.subscribe()` returns a `TypedLiveQuery<T>` that provides an initial snapshot of `TypedRecord<T>[]` plus a real-time stream of deduplicated, typed change events.
 
 ```ts
 const { liveQuery } = await chat.records.subscribe('thread/message');
 
-// Initial snapshot
+// Initial snapshot -- TypedRecord<MessageData>[]
 for (const msg of liveQuery.records) {
-  renderMessage(msg);
+  const data = await msg.data.json(); // MessageData -- typed
+  renderMessage(data);
 }
 
-// Real-time changes
+// Real-time changes -- handlers receive TypedRecord<MessageData>
 const offCreate = liveQuery.on('create', (record) => appendMessage(record));
 const offUpdate = liveQuery.on('update', (record) => refreshMessage(record));
 const offDelete = liveQuery.on('delete', (record) => removeMessage(record));
 
-// Catch-all event (receives { type, record })
+// Catch-all event (receives { type: 'create'|'update'|'delete', record: TypedRecord<T> })
 liveQuery.on('change', ({ type, record }) => {
   console.log(`${type}: ${record.id}`);
 });
@@ -346,9 +369,7 @@ offCreate();
 await liveQuery.close();
 ```
 
-`LiveQuery` extends `EventTarget`, so standard `addEventListener` / `removeEventListener` also work. The `.on()` method is a convenience wrapper that returns an unsubscribe function.
-
-Events are automatically deduplicated against the initial snapshot -- you won't receive a `create` event for records already in the `records` array.
+The underlying `LiveQuery` is accessible via `liveQuery.rawLiveQuery` if needed. Events are automatically deduplicated against the initial snapshot -- you won't receive a `create` event for records already in the `records` array.
 
 ---
 
@@ -419,12 +440,12 @@ const chat = web5.using(ChatProtocol);
 await chat.configure();
 
 // Create a parent thread
-const { record: thread } = await chat.records.write('thread', {
+const { record: thread } = await chat.records.create('thread', {
   data: { title: 'General' },
 });
 
-// Write a message nested under the thread
-const { record: msg } = await chat.records.write('thread/message', {
+// Create a message nested under the thread
+const { record: msg } = await chat.records.create('thread/message', {
   parentContextId : thread.contextId,
   data            : { text: 'Hello, world!' },
 });
@@ -468,7 +489,7 @@ const { records: remote } = await notes.records.query('note', {
 Tags are key-value metadata attached to records, useful for filtering without parsing record data.
 
 ```ts
-const { record } = await notes.records.write('note', {
+const { record } = await notes.records.create('note', {
   data : { title: 'Meeting Notes', body: '...' },
   tags : { category: 'work', priority: 'high' },
 });
@@ -486,7 +507,7 @@ const { records } = await notes.records.query('note', {
 Published records are publicly readable by anyone, including anonymous readers.
 
 ```ts
-const { record } = await notes.records.write('note', {
+const { record } = await notes.records.create('note', {
   data      : { title: 'Public Note', body: 'Visible to everyone' },
   published : true,
 });
@@ -527,6 +548,175 @@ The sync engine (enabled by default at 2-minute intervals) automatically synchro
 
 ---
 
+## Repository Pattern
+
+The `repository()` factory provides a higher-level abstraction over `TypedWeb5`. Instead of passing path strings to every call, you get a **structure-aware object** with CRUD methods directly on each protocol type -- with automatic singleton detection.
+
+```ts
+import { defineProtocol, repository, Web5 } from '@enbox/api';
+
+const { web5 } = await Web5.connect({ password: 'secret' });
+
+const TaskProtocol = defineProtocol({
+  protocol  : 'https://example.com/tasks',
+  published : false,
+  types: {
+    project : { schema: 'https://example.com/schemas/project', dataFormats: ['application/json'] },
+    task    : { schema: 'https://example.com/schemas/task',    dataFormats: ['application/json'] },
+    config  : { schema: 'https://example.com/schemas/config',  dataFormats: ['application/json'] },
+  },
+  structure: {
+    project: {
+      task: {},   // collection -- many tasks per project
+    },
+    config: {
+      $recordLimit: { max: 1, strategy: 'reject' },  // singleton
+    },
+  },
+} as const, {} as {
+  project : { name: string; color?: string };
+  task    : { title: string; completed: boolean };
+  config  : { defaultView: 'list' | 'board' };
+});
+
+const repo = repository(web5.using(TaskProtocol));
+await repo.configure();
+```
+
+### Collections vs Singletons
+
+The repository automatically detects types with `$recordLimit: { max: 1 }` and provides different APIs:
+
+**Collections** (default) -- `create`, `query`, `get`, `delete`, `subscribe`:
+
+```ts
+// Create
+const { record } = await repo.project.create({
+  data: { name: 'Website Redesign', color: '#3b82f6' },
+});
+
+// Query all
+const { records } = await repo.project.query();
+
+// Query with filters and pagination
+const { records: recent, cursor } = await repo.project.query({
+  dateSort   : 'createdDescending',
+  pagination : { limit: 10 },
+});
+
+// Get by record ID
+const { record: project } = await repo.project.get(recordId);
+
+// Delete
+await repo.project.delete(recordId);
+
+// Subscribe to real-time changes
+const { liveQuery } = await repo.project.subscribe();
+liveQuery.on('create', (record) => console.log('new project:', record.id));
+```
+
+**Singletons** (`$recordLimit: { max: 1 }`) -- `set`, `get`, `delete`:
+
+```ts
+// Set (creates or updates)
+await repo.config.set({
+  data: { defaultView: 'board' },
+});
+
+// Get the single record
+const { record: config } = await repo.config.get();
+const { defaultView } = await config.data.json(); // 'board'
+
+// Delete
+await repo.config.delete(config.id);
+```
+
+### Nested Records
+
+Nested types take `parentContextId` as the first argument:
+
+```ts
+// Create a task under a project
+const { record: task } = await repo.project.task.create(project.contextId, {
+  data: { title: 'Design mockups', completed: false },
+});
+
+// Query tasks within a project
+const { records: tasks } = await repo.project.task.query(project.contextId);
+
+// Subscribe to tasks within a project
+const { liveQuery } = await repo.project.task.subscribe(project.contextId);
+```
+
+### Using Pre-built Protocols
+
+The `@enbox/protocols` package provides production-ready protocol definitions. Combined with `repository()`, you get zero-boilerplate typed data access:
+
+```ts
+import { repository, Web5 } from '@enbox/api';
+import {
+  PreferencesProtocol,
+  ProfileProtocol,
+  SocialGraphProtocol,
+} from '@enbox/protocols';
+
+const { web5 } = await Web5.connect({ password: 'secret' });
+
+// Social Graph -- friend, block, group, member
+const social = repository(web5.using(SocialGraphProtocol));
+await social.configure();
+
+const { record } = await social.friend.create({
+  data: { did: 'did:dht:alice...', alias: 'Alice' },
+});
+
+// Profile -- profile (singleton), avatar, hero, link, privateNote
+const profile = repository(web5.using(ProfileProtocol));
+await profile.configure();
+
+await profile.profile.set({
+  data: { displayName: 'Bob', bio: 'Building the decentralized web' },
+});
+
+// Add links nested under the profile
+const { record: p } = await profile.profile.get();
+await profile.profile.link.create(p.contextId, {
+  data: { url: 'https://github.com/bob', title: 'GitHub' },
+});
+
+// Preferences -- theme, locale, privacy (singletons), notification (collection)
+const prefs = repository(web5.using(PreferencesProtocol));
+await prefs.configure();
+
+await prefs.theme.set({ data: { mode: 'dark', accentColor: '#8b5cf6' } });
+await prefs.locale.set({ data: { language: 'en', timezone: 'America/New_York' } });
+```
+
+See [`@enbox/protocols`](../protocols) for the full catalog of 6 protocols and 19 typed data shapes.
+
+---
+
+## Code Generation
+
+For protocols defined externally (e.g. from a spec or shared JSON file), use `@enbox/protocol-codegen` to generate TypeScript types from a protocol definition and JSON Schemas:
+
+```bash
+bunx @enbox/protocol-codegen generate \
+  --definition ./my-protocol.json \
+  --schemas ./schemas/ \
+  --name MyProtocol \
+  --output ./my-protocol.generated.ts
+```
+
+This generates:
+- TypeScript interfaces for each type's JSON Schema (via `json-schema-to-typescript`)
+- A `SchemaMap` mapping type names to generated interfaces
+- A ready-to-use `defineProtocol()` call
+
+See [`@enbox/protocol-codegen`](../protocol-codegen) for full documentation.
+
+---
+
 ## Advanced Usage
 
 ### Unscoped DWN Access
@@ -579,7 +769,10 @@ const { didDocument } = await web5.did.resolve('did:dht:abc...');
 |--------|-------------|
 | `Web5` | Main entry point -- `connect()`, `anonymous()`, `using()` |
 | `defineProtocol()` | Factory for creating typed protocol definitions |
-| `TypedWeb5` | Protocol-scoped API returned by `web5.using()` |
+| `repository()` | Factory for creating structure-aware CRUD repositories from `TypedWeb5` |
+| `TypedWeb5` | Protocol-scoped API returned by `web5.using()` -- `create`, `query`, `read`, `delete`, `subscribe` |
+| `TypedRecord<T>` | Type-safe record wrapper -- `data.json()` returns `Promise<T>` |
+| `TypedLiveQuery<T>` | Type-safe subscription with `TypedRecord<T>[]` snapshot and typed change events |
 | `Record` | Mutable record instance with data accessors and side-effect methods |
 | `ReadOnlyRecord` | Immutable record for anonymous/read-only access |
 | `LiveQuery` | Real-time subscription with initial snapshot and change events |
@@ -604,6 +797,13 @@ const { didDocument } = await web5.did.resolve('did:dht:abc...');
 | `TypedProtocol<D, M>` | Typed protocol wrapper with definition and schema map |
 | `ProtocolPaths<D>` | Union of valid slash-delimited paths for a protocol definition |
 | `SchemaMap` | Maps protocol type names to TypeScript interfaces |
+| `TypedCreateRequest<D, M, Path>` | Options for `records.create()` |
+| `TypedCreateResponse<T>` | Response from `records.create()` -- `{ status, record: TypedRecord<T> }` |
+| `TypedQueryRequest` | Options for `records.query()` |
+| `TypedQueryResponse<T>` | Response from `records.query()` -- `{ status, records: TypedRecord<T>[], cursor? }` |
+| `TypedSubscribeResponse<T>` | Response from `records.subscribe()` -- `{ status, liveQuery: TypedLiveQuery<T> }` |
+| `Repository<D, M>` | Repository type -- structure-aware Proxy object with CRUD methods |
+| `DataForPath<D, M, Path>` | Resolves TypeScript data type for a protocol path from the schema map |
 | `Web5ConnectOptions` | Options for `Web5.connect()` |
 | `Web5ConnectResult` | Return type of `Web5.connect()` |
 | `RecordModel` | Structured data model of a record |