doxum 0.1.37 → 0.1.38

package/README.md

@@ -362,6 +362,20 @@ and group keys are ordered by the earliest current source member that belongs to
 If several groups first appear on the same source member, they follow that member's
 selector-result order. Source membership/order changes may therefore reorder group keys.
 `singleton` converts an optional scalar projection into a zero-or-one keyed projection.
+It also computes an optional member directly from named dependencies:
+
+```ts
+const preview = derive.keyed.singleton(
+  { record: activeRecord, enabled: previewEnabled },
+  ({ record, enabled }) => (!enabled || record === undefined ? undefined : [record.id, record])
+);
+```
+
+The named form returns one readonly `[key, value]` tuple or `undefined` for no member.
+`[key, undefined]` is a present member. Optional equality compares values under the
+same key and preserves equivalent references; it cannot suppress a key change.
+Use `singleton` for zero or one result, and `fromEntries` for a complete result with
+arbitrary membership. See [Singleton](docs/projections.md#zero-or-one-keyed-member).
 
 All keyed projection producers use the public `KeyedProjection<K,V>` handle, including
 collection `observe`, `derive.keyed`, `incremental.collection`, and collection leaves

package/dist/index.cjs

@@ -3158,35 +3158,57 @@ function createKeyedMerge(sources, options) {
 	});
 	return projection;
 }
-const createKeyedSingleton = (source, keyOf, equality = Object.is) => {
-	if (require_transform.outputKind(source) !== "value") throw new TypeError("derive.keyed.singleton source must be a scalar projection.");
-	if (typeof keyOf !== "function") throw new TypeError("derive.keyed.singleton requires a key selector.");
+function createKeyedSingleton(sourceOrDependencies, compute, equality) {
+	const name = "derive.keyed.singleton";
+	const selection = require_transform.isProjection(sourceOrDependencies) ? {
+		kind: "scalar",
+		source: sourceOrDependencies,
+		keyOf: compute
+	} : {
+		kind: "named",
+		compiled: require_transform.compileProjectionDependencies(sourceOrDependencies, name),
+		computeEntry: compute
+	};
+	if (selection.kind === "scalar" && require_transform.outputKind(selection.source) !== "value") throw new TypeError(`${name} source must be a scalar projection.`);
+	if (typeof compute !== "function") throw new TypeError(`${name} requires a ${selection.kind === "scalar" ? "key selector" : "compute callback"}.`);
+	const outputEquality = assertEquality(equality, name);
 	const [projection] = require_transform.defineProcessor({
-		dependencies: [source],
+		dependencies: selection.kind === "named" ? selection.compiled.projections : [selection.source],
 		outputs: [{
 			kind: "collection",
-			equality
+			equality: outputEquality
 		}],
 		create: () => ({ evaluate: (evaluation) => {
-			const scalar = evaluation.sources[0];
 			const output = evaluation.outputs[0];
-			if (scalar.kind !== "value" || output.kind !== "collection") throw new Error("derive.keyed.singleton resolved invalid input/output kinds.");
-			const previous = output.previous.ids();
-			if (scalar.value === void 0) {
-				for (const key of previous) output.output.remove(key);
-				return;
+			if (output.kind !== "collection") throw new Error(`${name} requires a collection output.`);
+			let key;
+			let value;
+			if (selection.kind === "named") {
+				const entry = selection.computeEntry(require_transform.snapshotProjectionValues(selection.compiled.names, evaluation.sources));
+				require_transform.assertSynchronous(entry);
+				if (entry !== void 0) {
+					assertKeyedEntry(entry, name);
+					key = entry[0];
+					value = entry[1];
+				}
+			} else {
+				const scalar = evaluation.sources[0];
+				if (scalar?.kind !== "value") throw new Error(`${name} resolved a non-scalar input.`);
+				value = scalar.value;
+				if (value !== void 0) {
+					key = selection.keyOf(value);
+					require_transform.assertSynchronous(key);
+					if (typeof key !== "string") throw new TypeError(`${name} key selector must return a string.`);
+				}
 			}
-			const key = keyOf(scalar.value);
-			require_transform.assertSynchronous(key);
-			if (typeof key !== "string") throw new TypeError("derive.keyed.singleton key selector must return a string.");
-			for (const previousKey of previous) if (previousKey !== key) output.output.remove(previousKey);
-			output.output.set(key, scalar.value);
-			if (previous.length !== 1 || previous[0] !== key) output.output.order([key]);
+			const previousKey = output.previous.ids()[0];
+			if (previousKey !== void 0 && previousKey !== key) output.output.remove(previousKey);
+			if (key !== void 0) output.output.set(key, value);
 		} }),
-		name: "derive.keyed.singleton"
+		name
 	});
 	return projection;
-};
+}
 //#endregion
 //#region core/src/projection/derive/keyed.ts
 const compileOrderedKeys = (value, role) => {

package/dist/index.d.cts

@@ -53,6 +53,8 @@ declare function createKeyedMerge<K extends string, V>(sources: readonly KeyedPr
   }[], key: NoInfer<K>) => Synchronous<V>;
   readonly equality?: Equality$2<V>;
 }): KeyedProjection<K, V>;
+declare function createKeyedSingleton<const K extends string, V>(source: Projection<V | undefined>, keyOf: (value: V) => K, equality?: Equality$2<V>): KeyedProjection<K, V>;
+declare function createKeyedSingleton<const D extends ProjectionDependencies, K extends string, V>(dependencies: D, computeEntry: (values: ProjectionValues<D>) => Synchronous<readonly [K, V] | undefined>, equality?: Equality$2<V>): KeyedProjection<K, V>;
 //#endregion
 //#region core/src/projection/keyed/flat-map.d.ts
 type Equality$1<V> = (previous: V, next: V) => boolean;
@@ -79,7 +81,7 @@ declare const derive: typeof createValueDerive & {
       <K extends string, V, const D extends object, G extends string>(source: KeyedProjection<K, V>, dependencies: D & KeyedDependencies<NoInfer<K>, NoInfer<V>, D>, selector: (value: NoInfer<V>, key: NoInfer<K>, dependencies: KeyedDependencyValues<D>) => Synchronous<G | readonly G[]>): KeyedProjection<G, readonly K[]>;
     };
     flatMap: typeof createKeyedFlatMap;
-    singleton: <K extends string, V>(source: Projection<V | undefined>, keyOf: (value: V) => Synchronous<K>, equality?: (previous: V, next: V) => boolean) => KeyedProjection<K, V>;
+    singleton: typeof createKeyedSingleton;
     subset: <K extends string, V>(source: KeyedProjection<K, V>, orderedKeys: Projection<readonly K[]> | readonly K[]) => KeyedProjection<K, V>;
     filter: {
       <K extends string, V>(source: KeyedProjection<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>) => Synchronous<boolean>): KeyedProjection<K, V>;

package/dist/index.d.ts

@@ -53,6 +53,8 @@ declare function createKeyedMerge<K extends string, V>(sources: readonly KeyedPr
   }[], key: NoInfer<K>) => Synchronous<V>;
   readonly equality?: Equality$2<V>;
 }): KeyedProjection<K, V>;
+declare function createKeyedSingleton<const K extends string, V>(source: Projection<V | undefined>, keyOf: (value: V) => K, equality?: Equality$2<V>): KeyedProjection<K, V>;
+declare function createKeyedSingleton<const D extends ProjectionDependencies, K extends string, V>(dependencies: D, computeEntry: (values: ProjectionValues<D>) => Synchronous<readonly [K, V] | undefined>, equality?: Equality$2<V>): KeyedProjection<K, V>;
 //#endregion
 //#region core/src/projection/keyed/flat-map.d.ts
 type Equality$1<V> = (previous: V, next: V) => boolean;
@@ -79,7 +81,7 @@ declare const derive: typeof createValueDerive & {
       <K extends string, V, const D extends object, G extends string>(source: KeyedProjection<K, V>, dependencies: D & KeyedDependencies<NoInfer<K>, NoInfer<V>, D>, selector: (value: NoInfer<V>, key: NoInfer<K>, dependencies: KeyedDependencyValues<D>) => Synchronous<G | readonly G[]>): KeyedProjection<G, readonly K[]>;
     };
     flatMap: typeof createKeyedFlatMap;
-    singleton: <K extends string, V>(source: Projection<V | undefined>, keyOf: (value: V) => Synchronous<K>, equality?: (previous: V, next: V) => boolean) => KeyedProjection<K, V>;
+    singleton: typeof createKeyedSingleton;
     subset: <K extends string, V>(source: KeyedProjection<K, V>, orderedKeys: Projection<readonly K[]> | readonly K[]) => KeyedProjection<K, V>;
     filter: {
       <K extends string, V>(source: KeyedProjection<K, V>, predicate: (value: NoInfer<V>, key: NoInfer<K>) => Synchronous<boolean>): KeyedProjection<K, V>;

package/dist/index.js

@@ -3157,35 +3157,57 @@ function createKeyedMerge(sources, options) {
 	});
 	return projection;
 }
-const createKeyedSingleton = (source, keyOf, equality = Object.is) => {
-	if (outputKind(source) !== "value") throw new TypeError("derive.keyed.singleton source must be a scalar projection.");
-	if (typeof keyOf !== "function") throw new TypeError("derive.keyed.singleton requires a key selector.");
+function createKeyedSingleton(sourceOrDependencies, compute, equality) {
+	const name = "derive.keyed.singleton";
+	const selection = isProjection(sourceOrDependencies) ? {
+		kind: "scalar",
+		source: sourceOrDependencies,
+		keyOf: compute
+	} : {
+		kind: "named",
+		compiled: compileProjectionDependencies(sourceOrDependencies, name),
+		computeEntry: compute
+	};
+	if (selection.kind === "scalar" && outputKind(selection.source) !== "value") throw new TypeError(`${name} source must be a scalar projection.`);
+	if (typeof compute !== "function") throw new TypeError(`${name} requires a ${selection.kind === "scalar" ? "key selector" : "compute callback"}.`);
+	const outputEquality = assertEquality(equality, name);
 	const [projection] = defineProcessor({
-		dependencies: [source],
+		dependencies: selection.kind === "named" ? selection.compiled.projections : [selection.source],
 		outputs: [{
 			kind: "collection",
-			equality
+			equality: outputEquality
 		}],
 		create: () => ({ evaluate: (evaluation) => {
-			const scalar = evaluation.sources[0];
 			const output = evaluation.outputs[0];
-			if (scalar.kind !== "value" || output.kind !== "collection") throw new Error("derive.keyed.singleton resolved invalid input/output kinds.");
-			const previous = output.previous.ids();
-			if (scalar.value === void 0) {
-				for (const key of previous) output.output.remove(key);
-				return;
+			if (output.kind !== "collection") throw new Error(`${name} requires a collection output.`);
+			let key;
+			let value;
+			if (selection.kind === "named") {
+				const entry = selection.computeEntry(snapshotProjectionValues(selection.compiled.names, evaluation.sources));
+				assertSynchronous(entry);
+				if (entry !== void 0) {
+					assertKeyedEntry(entry, name);
+					key = entry[0];
+					value = entry[1];
+				}
+			} else {
+				const scalar = evaluation.sources[0];
+				if (scalar?.kind !== "value") throw new Error(`${name} resolved a non-scalar input.`);
+				value = scalar.value;
+				if (value !== void 0) {
+					key = selection.keyOf(value);
+					assertSynchronous(key);
+					if (typeof key !== "string") throw new TypeError(`${name} key selector must return a string.`);
+				}
 			}
-			const key = keyOf(scalar.value);
-			assertSynchronous(key);
-			if (typeof key !== "string") throw new TypeError("derive.keyed.singleton key selector must return a string.");
-			for (const previousKey of previous) if (previousKey !== key) output.output.remove(previousKey);
-			output.output.set(key, scalar.value);
-			if (previous.length !== 1 || previous[0] !== key) output.output.order([key]);
+			const previousKey = output.previous.ids()[0];
+			if (previousKey !== void 0 && previousKey !== key) output.output.remove(previousKey);
+			if (key !== void 0) output.output.set(key, value);
 		} }),
-		name: "derive.keyed.singleton"
+		name
 	});
 	return projection;
-};
+}
 //#endregion
 //#region core/src/projection/derive/keyed.ts
 const compileOrderedKeys = (value, role) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doxum",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "private": false,
   "license": "MIT",
   "description": "Doxum is a typed runtime for complex mutable documents.",

package/skills/doxum-runtime/SKILL.md

@@ -44,7 +44,7 @@ Follow these choices unless the requirement says otherwise:
 3. Use `read` for one synchronous document read and `select` for a document `Readable` with dynamic dependency tracking.
 4. Use `observe` to bring a document/readable/external source into the projection graph.
 5. Use named-object `derive` for pure aggregate values.
-6. Use `derive.keyed.from` to turn an ordered scalar/static collection into a keyed projection. Use `derive.keyed.fromEntries({ inputs }, compute)` when named projections compute a complete keyed result; use `flatMap` when individual keyed parents must recompute independently. Use `derive.keyed.merge` to compose multiple keyed projections; for base + sparse overrides, use `{ conflict: 'last' }`.
+6. Use `derive.keyed.from` to turn an ordered scalar/static collection into a keyed projection. Use `derive.keyed.singleton({ inputs }, computeEntry)` for zero or one computed member (`[key, value]` or `undefined`), and `derive.keyed.fromEntries({ inputs }, compute)` for a complete keyed result of arbitrary size; use `flatMap` when individual keyed parents must recompute independently. Use `derive.keyed.merge` to compose multiple keyed projections; for base + sparse overrides, use `{ conflict: 'last' }`.
 7. Use `derive.keyed` when one keyed source owns output membership/order. Prefer its built-in `keys`, `values`, `entries`, `get`, `from`, `fromEntries`, `merge`, `subset`, `filter`, `compact`, `groupBy`, `flatMap`, and `singleton` primitives over hand-written incremental collection patches.
 8. Express per-output-key joins through `{ source }` for same-key lookup, `{ source, key }` for one mapped key, or `{ source, keys }` for several mapped keys. Let the Runtime own binding and reverse invalidation; do not maintain an application `Map` just to route dependency changes.
 9. Use `runtime.items(keyedProjection)` or `scope.items(...)` for stable per-membership item `Readable`s.

package/skills/doxum-runtime/references/projections.md

@@ -280,9 +280,41 @@ Use this for domain-neutral reverse indexing such as record→sections, node→e
 
 ```ts
 const activeEntity = derive.keyed.singleton(activeRecord, record => record.id);
+
+const preview = derive.keyed.singleton(
+  { record: activeRecord, enabled: previewEnabled },
+  ({ record, enabled }) => (!enabled || record === undefined ? undefined : [record.id, record])
+);
+
+const fixed = derive.keyed.singleton({}, () => ['fixed', 1]);
 ```
 
-Input is `Projection<V | undefined>`. `undefined` becomes empty membership; a present value becomes exactly one keyed entry.
+Scalar form accepts `Projection<V | undefined>` and `keyOf(value)`. Undefined sources
+are empty and skip `keyOf`; present values are preserved as one member. Named form
+accepts ordinary `derive` dependencies, including `{}`, and a synchronous callback
+returning a readonly `[K, V]` tuple or `undefined`. `undefined` means no member;
+`[key, undefined]` is a present member. Keys must be strings. `null`, `false`, `[]`,
+malformed tuples and thenables are errors. Formal order is empty or the sole key.
+
+Optional equality defaults to `Object.is` and compares same-key values, retaining equal
+references. Changing the key removes the old member and adds the new one regardless of
+value equality. Typed equality participates in inference and must accept every emitted
+variant; inline tuples, optional branches and union values do not require an output
+projection annotation. Use a declared value type or `as const` when object discriminants
+would otherwise widen under normal TypeScript rules.
+
+Dependencies are captured at definition time; callback values are readonly. Keyed named
+inputs are whole durable map snapshots. For a precise active-entry dependency, compose
+`derive.keyed.get(records, activeId)` first; driver-relative specs do not belong here.
+Public Runtime reads in callbacks remain forbidden. Callback, validation and equality
+failures install no partial output and follow normal processor recovery. Definitions
+are lazy, isolated per runtime and compatible with scopes. Current reads can evaluate
+multiple times in a batch; item lifecycles end only at the notification boundary.
+
+Both forms use one processor and one collection output. Singleton's member coordination
+is O(1), plus callback and dependency snapshot costs. Use this primitive for optional
+previews, selections and active members instead of manually building zero-or-one arrays
+or staging collection patches. Use `fromEntries` when more than one member is possible.
 
 ## Runtime read/select
 

package/skills/doxum-runtime/references/public-api.md

@@ -331,7 +331,7 @@ The keyed family:
 | `merge`       | Multiple keyed projections → union with explicit conflict policy |
 | `flatMap`     | Ordered pure one-to-many keyed expansion                         |
 | `groupBy`     | One-to-many reverse index                                        |
-| `singleton`   | Optional scalar → zero-or-one keyed projection                   |
+| `singleton`   | Optional scalar or named dependencies → zero-or-one keyed result |
 | `subset`      | Externally ordered keyed subset                                  |
 | `filter`      | Predicate-controlled membership preserving source values         |
 | `compact`     | Map values while dropping `undefined` results                    |
@@ -364,12 +364,16 @@ derive.keyed.flatMap(source, dependencies, select, equality?): KeyedProjection<O
 derive.keyed.groupBy(source, selector): KeyedProjection<GroupKey, readonly K[]>
 derive.keyed.groupBy(source, dependencies, selector): KeyedProjection<GroupKey, readonly K[]>
 derive.keyed.singleton(sourceProjection, keyOf, equality?): KeyedProjection<K,V>
+derive.keyed.singleton(dependencies, computeEntry, equality?): KeyedProjection<K,V>
+// computeEntry(readonlyNamedValues) returns Synchronous<readonly [K,V] | undefined>
 ```
 
 `from` uses `keyOf(value)` as member identity and preserves the input array's formal order. Duplicate keys are processor errors; there is no silent first/last overwrite. Static arrays are shallow-snapshotted at definition creation while `keyOf` remains lazy. For a scalar array projection, each scalar publication is scanned because the source has no per-entry delta. Equality defaults to `Object.is`; an equality-equivalent value under the same key retains the previous published value identity.
 
 `fromEntries` accepts the same named projection object as `derive`, including `{}` and keyed projections. Single inputs use `{ source }`; direct-source, static-array and driver-relative dependency specs are not overloads. The callback receives readonly named values and returns the complete ordered tuple array synchronously. Empty arrays mean no members; missing keys are removed; present `undefined` is valid. Duplicate string keys, malformed tuples and callback/equality failures follow processor error/recovery rules without partial installation. Per-entry equality defaults to `Object.is` and retains equivalent value references without suppressing membership or order. Computation scans the complete old/new result, while downstream publication is incremental. A keyed dependency is a whole collection, not automatically tracked by `get`; compose `derive.keyed.get` for precise scalar lookup. See [Projections](projections.md#keyed-results-from-named-dependencies) for lifecycle, cost and examples.
 
+`singleton` returns at most one member. Scalar form accepts `Projection<V | undefined>`, omits undefined sources and preserves the source value under `keyOf(value)`. Named form uses ordinary `derive` dependencies (including `{}`), returning `[key, value]` or `undefined`; `[key, undefined]` is present. Keys are strings; empty arrays, null, false, malformed tuples and thenables are rejected. Typed equality participates in inference and compares same-key values only, preserving equivalent references. Key changes remain membership changes. Both forms share normal processor recovery and notification-boundary item lifecycles. Keyed named inputs are whole snapshots; compose `derive.keyed.get` for precise lookup. See [Singleton](projections.md#singleton) for examples and costs.
+
 `merge` has union membership and requires an explicit conflict policy. `first` and `last` use source-list priority. `error` rejects overlapping keys. `resolve` calls `resolve(contributions, key)` only for keys with two or more current contributions; contributions are ordered by source priority and have `{ sourceIndex, value }`. A single contribution passes through unchanged. The source list is fixed at definition time.
 
 Merged formal order is always `stableUnique(S0.ids() ++ S1.ids() ++ ... ++ Sn.ids())`, independent of which source supplies the effective value. Therefore `derive.keyed.merge([base, overrides], { conflict: 'last' })` is the standard base + sparse-override composition: override values win for shared keys without moving their base positions; override-only keys are included after earlier-source first occurrences. Removing an override does not end the merged membership lifecycle while another source still contains the key.

package/skills/doxum-runtime/references/recipes.md

@@ -337,13 +337,24 @@ Output is keyed by section id; each value is ordered source record ids. Use this
 
 Group keys follow first appearance in the source's formal order. If one source record returns several groups, those groups use the selector's returned order for that record when they first appear together.
 
-## Optional scalar to keyed singleton
+## Zero or one keyed member
 
 ```ts
 const activeRecordCollection = derive.keyed.singleton(activeRecord, record => record.id);
+
+const preview = derive.keyed.singleton(
+  { record: activeRecord, enabled: previewEnabled },
+  ({ record, enabled }) => (!enabled || record === undefined ? undefined : [record.id, record])
+);
 ```
 
-`undefined` becomes empty membership; present value becomes one keyed member.
+Scalar form turns an undefined source into empty membership. Named form returns a
+tuple for a present member or `undefined` for no member; `[key, undefined]` is present.
+Use the named form when several projections determine the member. Pass a value equality
+callback when constructing equivalent objects; it preserves same-key value references
+but cannot suppress a key change. For a precise dynamic input, obtain `activeRecord`
+with `derive.keyed.get(records, activeId)`. Do not wrap dependencies in an intermediate
+scalar derive or use `fromEntries` solely to wrap one tuple in an array.
 
 ## Stable keyed item Readables