doxum 0.1.17 → 0.1.19

package/README.md

@@ -232,12 +232,39 @@ runtime.batch({ cause: { action: 'refresh' } }, () => {
 stop();
 ```
 
-Projection declarations are lazy and reusable. The only Runtime operations are
-`get`, `readable`, `set`, `batch` and `dispose`; materialization, incremental
-state, publication and recovery stay inside the Runtime. Collection values are
+Root projection declarations are lazy and reusable; scoped declarations are
+lazy but tied to their scope. The Runtime owns `get`,
+`readable`, scalar `set`, keyed `update`, `batch`, `scope` and `dispose`;
+materialization, incremental state, publication and recovery stay inside that
+one Runtime. Collection values are
 immutable `ReadonlyMap`-like snapshots, while a `Readable` owns selector
 tracking, equality and subscription lifecycle.
 
+Local projections live in the same graph as their parent definitions:
+
+```ts
+const scope = runtime.scope();
+const localFilter = scope.input<'all' | 'open'>('all');
+const localVisible = scope.derive([tasks, localFilter], (tasks, filter) =>
+  filter === 'all' ? tasks : new Map([...tasks].filter(([, task]) => !task.done))
+);
+scope.get(localVisible);
+scope.dispose(); // Releases local nodes, state and subscriptions; parent tasks remain.
+```
+
+For Runtime-local keyed state, `input.collection` publishes the same exact
+`CollectionChange` as document collections. One `update` edits one or many keys
+atomically; the enclosing Runtime batch coalesces accepted edits into one net
+change:
+
+```ts
+const overrides = input.collection<string, Task>();
+runtime.update(overrides, draft => {
+  draft.set(taskId, task);
+  draft.remove(oldTaskId);
+});
+```
+
 `observe` is the single source boundary for documents, Doxum `Readable` values,
 and eventful external sources. External sources declare `kind: 'value'` or
 `kind: 'collection'`; collection invalidation remains keyed internally.
@@ -252,6 +279,24 @@ import { incremental } from 'doxum/advanced';
 const doubled = incremental.collection([tasks], ({ sources, output }) => {
   for (const [id, task] of sources[0]) output.set(id, task.value * 2);
 });
+
+const render = incremental.group(
+  [tasks],
+  define => ({
+    node: {
+      shell: define.collection<string, { readonly title: string }>(),
+      content: define.collection<string, string>(),
+    },
+    labels: define.collection<string, string>(),
+  }),
+  ({ sources, outputs }) => {
+    for (const [id, task] of sources[0]) {
+      outputs.node.shell.set(id, { title: task.title });
+      outputs.node.content.set(id, task.title);
+      outputs.labels.set(id, task.title);
+    }
+  }
+);
 ```
 
 Incremental processors receive a dependency-aligned `changes` tuple. Collection
@@ -259,6 +304,12 @@ entries carry `added`/`updated`/`removed` transitions with complete
 `before`/`after` values, so a processor can patch indexes without rescanning the
 collection; scalar dependencies use `undefined` and the initial collection build
 reports `{ kind: 'reset' }`.
+`incremental.group` runs one processor for several named keyed collection outputs.
+Its static nested namespace is only API organization: every leaf is an ordinary
+`Projection`, all leaves publish atomically in one causal settle, and downstream
+processors depend directly on those leaves. A group materializes as a whole when
+any leaf is first read; split groups when outputs do not share computation or
+atomicity requirements. There is no output event bus or per-output runtime.
 
 In React, `useProjection(projection)` reads a value and
 `useProjection(projection, selector, equality?)` tracks keyed reads such as