doxum 0.1.31 → 0.1.33

package/README.md

@@ -280,6 +280,29 @@ exposes `read`, `select`, `items`, `update`, `batch`, `scope` and `dispose`.
 `ProjectionScope` mirrors `read`, `select`, `items`, `update`, `batch` and `dispose`, plus
 `own(definitionOrTree)` for lifecycle ownership of lazy projection definitions.
 
+### Commands inside a batch
+
+Ordinary reads use `runtime.read`. A batch can read the latest accepted input state through its callback while projection readers keep the last published view:
+
+```ts
+const count = input(0);
+const doubled = derive({ count }, ({ count }) => count * 2);
+
+function increment() {
+  runtime.batch(read => {
+    runtime.update(count, read(count) + 1);
+  });
+}
+
+runtime.batch(() => {
+  increment();
+  increment();
+});
+runtime.read(doubled); // 4
+```
+
+The borrowed reader supports scalar and collection inputs and expires with its callback. Nested batches settle at the outer boundary. Cross-input commands can read several latest source values without mirrors. Input equality is checked before acceptance; a failed edit leaves earlier successes intact. A batch is not a transaction. See [batch source reads](docs/projections.md#batch-source-reads) for snapshots, errors and lifecycle.
+
 ### Keyed projection
 
 `derive.keyed` preserves a keyed driver's membership and order while deriving entries
@@ -354,14 +377,22 @@ projection dependencies by name:
 const cardContent = derive.keyed(
   items,
   {
+    metadata: { source: metadataByItemId },
     record: { source: records, key: item => item.recordId },
     view: activeView,
     fields: visibleFields,
   },
-  (item, itemId, { record, view, fields }) => renderCard(itemId, item, record, view, fields)
+  (item, itemId, { metadata, record, view, fields }) =>
+    renderCard(itemId, item, metadata, record, view, fields)
 );
 ```
 
+Use `{ source }` when driver and dependency use the same key. It directly binds driver
+key `K` to source key `K`, requires the driver key type to be assignable to the source
+key type, and avoids a redundant `key: (_value, id) => id` selector. Source value or
+membership changes invalidate only the driver entry with that key; source order-only
+changes do not invalidate it.
+
 For `{ source, key }` dependencies, the Runtime owns output-key → source-key bindings
 and reverse invalidation. A missing source entry resolves to `undefined` but remains
 bound, so adding it later invalidates the dependent output keys. An ordinary projection
@@ -392,6 +423,16 @@ key later creates a new generation. A subscribed missing item stays latent and a
 if the key is later added. Runtime batches follow the net published membership, so a
 remove/add collapsed to an update does not create a false lifecycle break.
 
+### One-to-many keyed derivation
+
+```ts
+const lines = derive.keyed.flatMap(orders, order =>
+  order.lines.map(line => [line.id, line] as const)
+);
+```
+
+Each parent returns ordered `[globalKey, value]` tuples, including zero entries. `flatMap` reuses named/dynamic keyed dependencies and only recomputes invalidated parents. Formal output order follows parent order then child order; parent-only reordering runs no selectors. Duplicate final output keys are errors, and present `undefined` is valid. Same-batch transfers preserve a global key's membership identity. Structural changes can rebuild full order; this is not a claim that every operation costs only the changed entries.
+
 ### Runtime-local keyed state
 
 Use `input.collection` for selection, expanded state, local overrides and other

package/dist/advanced.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_transform = require("./transform-B6YxfR0R.cjs");
+const require_transform = require("./transform-CSPGdBe5.cjs");
 const require_record = require("./record-ChYUi8PP.cjs");
 //#region core/src/projection/advanced.ts
 const resetCollectionChange = Object.freeze({ kind: "reset" });

package/dist/advanced.d.cts

@@ -1,4 +1,4 @@
-import { c as ProjectionChange, d as CollectionRead, l as CollectionChange, n as KeyedDependencyValues, o as KeyedProjection, s as Projection, t as KeyedDependencies, u as CollectionDraft } from "./dependency-B3E65M1E.cjs";
+import { c as ProjectionChange, d as CollectionRead, l as CollectionChange, n as KeyedDependencyValues, o as KeyedProjection, s as Projection, t as KeyedDependencies, u as CollectionDraft } from "./dependency-Cbf3C8eJ.cjs";
 
 //#region core/src/projection/collection/change.d.ts
 declare const collectionChange: {

package/dist/advanced.d.ts

@@ -1,4 +1,4 @@
-import { c as ProjectionChange, d as CollectionRead, l as CollectionChange, n as KeyedDependencyValues, o as KeyedProjection, s as Projection, t as KeyedDependencies, u as CollectionDraft } from "./dependency-BYbdDHNa.js";
+import { c as ProjectionChange, d as CollectionRead, l as CollectionChange, n as KeyedDependencyValues, o as KeyedProjection, s as Projection, t as KeyedDependencies, u as CollectionDraft } from "./dependency-DzxXGYe1.js";
 
 //#region core/src/projection/collection/change.d.ts
 declare const collectionChange: {

package/dist/advanced.js

@@ -1,4 +1,4 @@
-import { D as defineProcessor, S as compileProjectionDependencies, l as assertSynchronous, p as collectionChange, t as createKeyedTransform, w as collectionView } from "./transform-BQY9I6il.js";
+import { C as compileProjectionDependencies, O as defineProcessor, T as collectionView, r as collectionChange, t as createKeyedTransform, v as assertSynchronous } from "./transform-A9Lx5R2l.js";
 import { n as isPlainObject } from "./record-B2yRhYsc.js";
 //#region core/src/projection/advanced.ts
 const resetCollectionChange = Object.freeze({ kind: "reset" });

package/dist/{dependency-B3E65M1E.d.cts → dependency-Cbf3C8eJ.d.cts}

@@ -113,6 +113,11 @@ type SingularKeyedDependency<DriverKey extends string, DriverValue, SourceKey ex
   readonly key: (value: DriverValue, key: DriverKey) => Synchronous<SourceKey | undefined>;
   readonly keys?: never;
 };
+type SameKeyedDependency<SourceKey extends string, SourceValue> = {
+  readonly source: KeyedProjection<SourceKey, SourceValue>;
+  readonly key?: never;
+  readonly keys?: never;
+};
 type PluralKeyedDependency<DriverKey extends string, DriverValue, SourceKey extends string, SourceValue> = {
   readonly source: KeyedProjection<SourceKey, SourceValue>;
   readonly keys: (value: DriverValue, key: DriverKey) => Synchronous<readonly SourceKey[]>;
@@ -122,8 +127,15 @@ type KeyedDependency<DriverKey extends string, DriverValue> = (Projection<unknow
   readonly source?: never;
   readonly key?: never;
   readonly keys?: never;
-}) | SingularKeyedDependency<DriverKey, DriverValue, string, unknown> | PluralKeyedDependency<DriverKey, DriverValue, string, unknown>;
-type KeyedDependencies<DriverKey extends string, DriverValue, D extends object> = { readonly [P in keyof D]: P extends string ? KeyedDependency<DriverKey, DriverValue> : never };
+}) | SameKeyedDependency<string, unknown> | SingularKeyedDependency<DriverKey, DriverValue, string, unknown> | PluralKeyedDependency<DriverKey, DriverValue, string, unknown>;
+type SameKeyConstraint<DriverKey extends string, Dependency> = Dependency extends {
+  readonly source: KeyedProjection<infer SourceKey extends string, unknown>;
+} ? Dependency extends {
+  readonly key: unknown;
+} | {
+  readonly keys: unknown;
+} ? unknown : [DriverKey] extends [SourceKey] ? unknown : never : unknown;
+type KeyedDependencies<DriverKey extends string, DriverValue, D extends object> = { readonly [P in keyof D]: P extends string ? KeyedDependency<DriverKey, DriverValue> & SameKeyConstraint<DriverKey, D[P]> : never };
 type KeyedDependencyValues<D extends object> = { readonly [P in keyof D]: D[P] extends {
   readonly source: KeyedProjection<infer K extends string, infer V>;
   readonly keys: (...args: never[]) => unknown;
@@ -132,4 +144,4 @@ type KeyedDependencyValues<D extends object> = { readonly [P in keyof D]: D[P] e
 } ? V | undefined : D[P] extends Projection<infer T> ? T : never };
 //#endregion
 export { ProjectionDisposedError as _, Input as a, ProjectionChange as c, CollectionRead as d, ExternalCollectionEvent as f, ExternalValueSource as g, ExternalValueEvent as h, CollectionInputDraft as i, CollectionChange as l, ExternalCollectionSource as m, KeyedDependencyValues as n, KeyedProjection as o, ExternalCollectionRead as p, CollectionInput as r, Projection as s, KeyedDependencies as t, CollectionDraft as u, ProjectionError as v };
-//# sourceMappingURL=dependency-B3E65M1E.d.cts.map
+//# sourceMappingURL=dependency-Cbf3C8eJ.d.cts.map

package/dist/{dependency-BYbdDHNa.d.ts → dependency-DzxXGYe1.d.ts}

@@ -113,6 +113,11 @@ type SingularKeyedDependency<DriverKey extends string, DriverValue, SourceKey ex
   readonly key: (value: DriverValue, key: DriverKey) => Synchronous<SourceKey | undefined>;
   readonly keys?: never;
 };
+type SameKeyedDependency<SourceKey extends string, SourceValue> = {
+  readonly source: KeyedProjection<SourceKey, SourceValue>;
+  readonly key?: never;
+  readonly keys?: never;
+};
 type PluralKeyedDependency<DriverKey extends string, DriverValue, SourceKey extends string, SourceValue> = {
   readonly source: KeyedProjection<SourceKey, SourceValue>;
   readonly keys: (value: DriverValue, key: DriverKey) => Synchronous<readonly SourceKey[]>;
@@ -122,8 +127,15 @@ type KeyedDependency<DriverKey extends string, DriverValue> = (Projection<unknow
   readonly source?: never;
   readonly key?: never;
   readonly keys?: never;
-}) | SingularKeyedDependency<DriverKey, DriverValue, string, unknown> | PluralKeyedDependency<DriverKey, DriverValue, string, unknown>;
-type KeyedDependencies<DriverKey extends string, DriverValue, D extends object> = { readonly [P in keyof D]: P extends string ? KeyedDependency<DriverKey, DriverValue> : never };
+}) | SameKeyedDependency<string, unknown> | SingularKeyedDependency<DriverKey, DriverValue, string, unknown> | PluralKeyedDependency<DriverKey, DriverValue, string, unknown>;
+type SameKeyConstraint<DriverKey extends string, Dependency> = Dependency extends {
+  readonly source: KeyedProjection<infer SourceKey extends string, unknown>;
+} ? Dependency extends {
+  readonly key: unknown;
+} | {
+  readonly keys: unknown;
+} ? unknown : [DriverKey] extends [SourceKey] ? unknown : never : unknown;
+type KeyedDependencies<DriverKey extends string, DriverValue, D extends object> = { readonly [P in keyof D]: P extends string ? KeyedDependency<DriverKey, DriverValue> & SameKeyConstraint<DriverKey, D[P]> : never };
 type KeyedDependencyValues<D extends object> = { readonly [P in keyof D]: D[P] extends {
   readonly source: KeyedProjection<infer K extends string, infer V>;
   readonly keys: (...args: never[]) => unknown;
@@ -132,4 +144,4 @@ type KeyedDependencyValues<D extends object> = { readonly [P in keyof D]: D[P] e
 } ? V | undefined : D[P] extends Projection<infer T> ? T : never };
 //#endregion
 export { ProjectionDisposedError as _, Input as a, ProjectionChange as c, CollectionRead as d, ExternalCollectionEvent as f, ExternalValueSource as g, ExternalValueEvent as h, CollectionInputDraft as i, CollectionChange as l, ExternalCollectionSource as m, KeyedDependencyValues as n, KeyedProjection as o, ExternalCollectionRead as p, CollectionInput as r, Projection as s, KeyedDependencies as t, CollectionDraft as u, ProjectionError as v };
-//# sourceMappingURL=dependency-BYbdDHNa.d.ts.map
+//# sourceMappingURL=dependency-DzxXGYe1.d.ts.map