doxum 0.1.7 → 0.1.9

package/dist/store-cp5CpfCy.d.ts

@@ -0,0 +1,262 @@
+import { B as CollectionPath, C as CollectionAccess, Q as ObjectNode, R as CollectionId, T as Read, _ as Unsubscribe, m as Synchronous, ot as ValueSchemaNode, r as DocumentCommit, rt as SchemaPath, s as DocumentReadable, tt as PathPick, v as Readable, x as CollectionImpact, z as CollectionNode } from "./contract-BNStLbSE.js";
+
+//#region core/src/projection/contract.d.ts
+declare const sourceContext: unique symbol;
+type EngineSource<T> = {
+  readonly [sourceContext]: T;
+};
+type EngineSources = Readonly<Record<string, EngineSource<unknown>>>;
+type EngineInputs<S extends EngineSources> = { readonly [K in keyof S]: S[K] extends EngineSource<infer T> ? T : never };
+type DocumentInput<S extends ObjectNode> = {
+  readonly read: Read<S>;
+  readonly revision: number;
+  readonly commits: readonly DocumentCommit<S>[];
+  readonly reset: boolean;
+};
+type DocumentCollectionInput<S extends ObjectNode, N extends ValueSchemaNode, K extends string = string> = {
+  readonly read: CollectionAccess<K, N>;
+  readonly revision: number;
+  readonly commits: readonly DocumentCommit<S>[];
+  readonly reset: boolean;
+  readonly candidates: {
+    readonly keys: readonly K[];
+    readonly orderDirty: boolean;
+  };
+};
+type DocumentSource<S extends ObjectNode> = EngineSource<DocumentInput<S>> & {
+  collection<P extends CollectionPath>(pick: (path: SchemaPath<S['shape']>) => P): DocumentCollectionSource<S, CollectionNode<P>, CollectionId<P>>;
+  targets(...targets: readonly [PathPick<S>, ...PathPick<S>[]]): EngineSource<DocumentInput<S>>;
+};
+type DocumentCollectionSource<S extends ObjectNode, N extends ValueSchemaNode, K extends string = string> = EngineSource<DocumentCollectionInput<S, N, K>>;
+type ValueInput<T> = {
+  readonly value: T;
+  readonly previous: T;
+  readonly changed: boolean;
+  readonly revision: number;
+  readonly reset: boolean;
+};
+type EngineInput<T> = {
+  readonly source: EngineSource<ValueInput<T>>;
+  set(value: T): void;
+};
+type ValueUpdate<T> = {
+  readonly kind: 'unchanged';
+} | {
+  readonly kind: 'changed';
+  readonly value: T;
+} | {
+  readonly kind: 'rebuild';
+};
+type EngineValueSpec<S extends EngineSources, T> = {
+  readonly name?: string;
+  readonly sources: S;
+  readonly build: (sources: EngineInputs<S>) => {
+    readonly value: T;
+    readonly update: (sources: EngineInputs<S>) => ValueUpdate<NoInfer<T>>;
+  };
+};
+type MaterializedValue<T> = Readable<T> & EngineSource<ValueInput<T>> & {
+  rebuild(): void;
+  dispose(): void;
+};
+type CollectionRead<K extends string, V> = {
+  get(key: K): V | undefined;
+  has(key: K): boolean;
+  ids(): readonly K[];
+};
+type CollectionInput<K extends string, V> = CollectionRead<K, V> & {
+  readonly change: CollectionImpact<K> | undefined;
+  readonly revision: number;
+  readonly reset: boolean;
+};
+type MaterializedCollection<K extends string, V> = EngineSource<CollectionInput<K, V>> & {
+  current(): CollectionRead<K, V>;
+  readonly ids: Readable<readonly K[]>;
+  readonly all: Readable<readonly V[]>;
+  item(key: K): Readable<V | undefined>;
+  revision(): number;
+  subscribe(listener: (change: CollectionImpact<K>) => void): Unsubscribe;
+  rebuild(): void;
+  dispose(): void;
+};
+type MaterializedCollectionWriter<K extends string, V> = {
+  set(key: K, value: V): void;
+  remove(key: K): void;
+  order(ids: readonly K[]): void;
+  replace(entries: readonly (readonly [K, V])[]): void;
+};
+type EngineCollectionProcess<S extends EngineSources, K extends string, V> = {
+  readonly sources: EngineInputs<S>;
+  readonly previous: CollectionRead<K, V>;
+  readonly next: CollectionRead<K, V>;
+  readonly writer: MaterializedCollectionWriter<K, V>;
+};
+type EngineCollectionSpec<S extends EngineSources, K extends string, V> = {
+  readonly name?: string;
+  readonly sources: S;
+  readonly isEqual?: (previous: V, next: V) => boolean;
+  readonly build: (input: EngineCollectionProcess<S, K, V>) => {
+    readonly update: (input: EngineCollectionProcess<S, K, V>) => void | {
+      readonly kind: 'rebuild';
+    };
+  };
+};
+declare class ProjectionError extends Error {
+  readonly phase: 'processor' | 'listener' | 'source' | 'blocked';
+  readonly identity: string;
+  readonly revisions: readonly number[];
+  constructor(phase: 'processor' | 'listener' | 'source' | 'blocked', identity: string, revisions: readonly number[], cause: unknown);
+}
+declare class ProjectionDisposedError extends Error {
+  constructor();
+}
+type ProjectionEngine = {
+  document<S extends ObjectNode>(runtime: DocumentReadable<S>): DocumentSource<S>;
+  fromReadable<T>(readable: Readable<T>, options?: {
+    readonly isEqual?: (a: T, b: T) => boolean;
+  }): EngineSource<ValueInput<T>>;
+  input<T>(initial: T, options?: {
+    readonly isEqual?: (a: T, b: T) => boolean;
+  }): EngineInput<T>;
+  value<S extends EngineSources, T>(sources: S, compute: (sources: EngineInputs<S>) => Synchronous<T>, options?: {
+    readonly isEqual?: (a: NoInfer<T>, b: NoInfer<T>) => boolean;
+  }): MaterializedValue<T>;
+  value<S extends EngineSources, T>(spec: EngineValueSpec<S, T>, options?: {
+    readonly isEqual?: (a: NoInfer<T>, b: NoInfer<T>) => boolean;
+  }): MaterializedValue<T>;
+  collection<V, K extends string = string>(): <S extends EngineSources>(spec: EngineCollectionSpec<S, K, V>) => MaterializedCollection<K, V>;
+  map<S extends ObjectNode, N extends ValueSchemaNode, K extends string, V>(source: DocumentCollectionSource<S, N, K>, mapper: (id: K, entry: Read<N>) => Synchronous<V>, options?: {
+    readonly isEqual?: (a: V, b: V) => boolean;
+  }): MaterializedCollection<K, V>;
+  map<K extends string, V, R>(source: MaterializedCollection<K, V>, mapper: (id: K, entry: V) => Synchronous<R>, options?: {
+    readonly isEqual?: (a: NoInfer<R>, b: NoInfer<R>) => boolean;
+  }): MaterializedCollection<K, R>;
+  batch<T>(run: () => Synchronous<T>): T;
+  dispose(): void;
+};
+//#endregion
+//#region core/src/projection/definition.d.ts
+declare const projectionDefinition: unique symbol;
+declare const writableInput: unique symbol;
+type Projection<T, E = T, K extends 'source' | 'value' | 'collection' = 'source' | 'value' | 'collection'> = {
+  readonly [projectionDefinition]: {
+    readonly value: T;
+    readonly event: E;
+    readonly kind: K;
+  };
+};
+type ProjectionSources = Readonly<Record<string, Projection<unknown, unknown, 'source' | 'value' | 'collection'>>>;
+type ProjectionValues<S extends ProjectionSources> = { readonly [K in keyof S]: S[K] extends Projection<infer T, unknown, 'source' | 'value' | 'collection'> ? T : never };
+type ProjectionEvents<S extends ProjectionSources> = { readonly [K in keyof S]: S[K] extends Projection<unknown, infer E, 'source' | 'value' | 'collection'> ? E : never };
+type ValueProjection<T, E = ValueEvent<T>> = Projection<T, E, 'value'>;
+type InputProjection<T> = ValueProjection<T> & {
+  readonly [writableInput]: true;
+};
+type CollectionProjection<K extends string, V, E = CollectionEvent<K, V>> = Projection<CollectionRead<K, V>, E, 'collection'>;
+type CollectionSource<K extends string, V, E> = Projection<CollectionRead<K, V>, E, 'source'>;
+type DocumentProjection<S extends ObjectNode> = Projection<Read<S>, DocumentEvent<S>, 'source'>;
+type DocumentCollectionProjection<S extends ObjectNode, N extends ValueSchemaNode, K extends string = string> = CollectionSource<K, Read<N>, DocumentCollectionEvent<S, N, K>>;
+type ValueEvent<T> = {
+  readonly value: T;
+  readonly previous: T;
+  readonly changed: boolean;
+  readonly revision: number;
+  readonly reset: boolean;
+};
+type DocumentEvent<S extends ObjectNode> = {
+  readonly read: Read<S>;
+  readonly revision: number;
+  readonly commits: readonly DocumentCommit<S>[];
+  readonly reset: boolean;
+};
+type DocumentCollectionEvent<S extends ObjectNode, N extends ValueSchemaNode, K extends string = string> = {
+  readonly read: CollectionAccess<K, N>;
+  readonly revision: number;
+  readonly commits: readonly DocumentCommit<S>[];
+  readonly reset: boolean;
+  readonly candidates: {
+    readonly keys: readonly K[];
+    readonly orderDirty: boolean;
+  };
+};
+type CollectionEvent<K extends string, V> = CollectionRead<K, V> & {
+  readonly change: CollectionImpact<K> | undefined;
+  readonly revision: number;
+  readonly reset: boolean;
+};
+declare const input: <T>(initial: T, options?: {
+  readonly isEqual?: (a: T, b: T) => boolean;
+}) => InputProjection<T>;
+type AdvancedValueSpec<S extends ProjectionSources, T> = {
+  readonly kind: 'value';
+  readonly name?: string;
+  readonly sources: S;
+  readonly build: (sources: ProjectionEvents<S>) => {
+    readonly value: T;
+    readonly update: (sources: ProjectionEvents<S>) => ValueUpdate<NoInfer<T>>;
+  };
+  readonly isEqual?: (previous: T, next: T) => boolean;
+};
+type AdvancedCollectionSpec<S extends ProjectionSources, K extends string, V> = {
+  readonly kind: 'collection';
+  readonly name?: string;
+  readonly sources: S;
+  readonly build: (input: AdvancedCollectionProcess<S, K, V>) => {
+    readonly update: (input: AdvancedCollectionProcess<S, K, V>) => void | {
+      readonly kind: 'rebuild';
+    };
+  };
+  readonly isEqual?: (previous: V, next: V) => boolean;
+};
+type AdvancedCollectionProcess<S extends ProjectionSources, K extends string, V> = {
+  readonly sources: ProjectionEvents<S>;
+  readonly previous: CollectionRead<K, V>;
+  readonly next: CollectionRead<K, V>;
+  readonly writer: MaterializedCollectionWriter<K, V>;
+};
+declare function project<T>(readable: Readable<T>): ValueProjection<T>;
+declare function project<S extends ObjectNode>(document: DocumentReadable<S>): DocumentProjection<S>;
+declare function project<S extends ObjectNode>(document: DocumentReadable<S>, targets: readonly [PathPick<S>, ...PathPick<S>[]]): DocumentProjection<S>;
+declare function project<S extends ObjectNode, P extends CollectionPath>(document: DocumentReadable<S>, pick: (path: SchemaPath<S['shape']>) => P): DocumentCollectionProjection<S, CollectionNode<P>, CollectionId<P>>;
+declare function project<S extends ObjectNode, P extends CollectionPath, V>(document: DocumentReadable<S>, pick: (path: SchemaPath<S['shape']>) => P, mapper: (id: CollectionId<P>, entry: Read<CollectionNode<P>>) => Synchronous<V>, options?: {
+  readonly isEqual?: (a: V, b: V) => boolean;
+}): CollectionProjection<CollectionId<P>, V>;
+declare function project<K extends string, V, E, R>(source: Projection<CollectionRead<K, V>, E, 'source' | 'collection'>, mapper: (id: K, entry: V) => Synchronous<R>, options?: {
+  readonly isEqual?: (a: R, b: R) => boolean;
+}): CollectionProjection<K, R>;
+declare function project<S extends ProjectionSources, T>(sources: S, compute: (sources: ProjectionValues<S>) => Synchronous<T>, options?: {
+  readonly isEqual?: (a: T, b: T) => boolean;
+}): ValueProjection<T>;
+declare function project<S extends ProjectionSources, T>(spec: AdvancedValueSpec<S, T>): ValueProjection<T>;
+declare function project<V, K extends string = string, S extends ProjectionSources = ProjectionSources>(spec: AdvancedCollectionSpec<S, K, V>): CollectionProjection<K, V>;
+//#endregion
+//#region core/src/projection/runtime.d.ts
+declare const createProjectionEngine: (options: {
+  readonly onError: (error: ProjectionError) => void;
+}) => ProjectionEngine;
+//#endregion
+//#region core/src/projection/store.d.ts
+type ProjectionStore = {
+  get<K extends string, V>(projection: CollectionProjection<K, V>): CollectionRead<K, V>;
+  get<T>(projection: ValueProjection<T>): T;
+  set<T>(projection: InputProjection<T>, value: T): void;
+  subscribe<K extends string, V>(projection: CollectionProjection<K, V>, listener: (change: CollectionImpact<K>) => void): Unsubscribe;
+  subscribe<T>(projection: ValueProjection<T>, listener: () => void): Unsubscribe;
+  revision(projection: ValueProjection<unknown> | CollectionProjection<string, unknown>): number;
+  rebuild(projection: ValueProjection<unknown> | CollectionProjection<string, unknown>): void;
+  release(projection: ValueProjection<unknown> | CollectionProjection<string, unknown>): void;
+  batch<T>(run: () => T): T;
+  dispose(): void;
+};
+declare const projectionStoreDebug: (store: ProjectionStore) => Readonly<{
+  nodes: number;
+  sources: number;
+  subscriptions: number;
+  pending: number;
+}>;
+declare const createProjectionStore: (options: {
+  readonly onError: Parameters<typeof createProjectionEngine>[0]["onError"];
+}) => ProjectionStore;
+//#endregion
+export { ProjectionDisposedError as C, project as S, ProjectionSources as _, AdvancedCollectionSpec as a, ValueProjection as b, CollectionProjection as c, DocumentCollectionProjection as d, DocumentEvent as f, ProjectionEvents as g, Projection as h, AdvancedCollectionProcess as i, CollectionSource as l, InputProjection as m, createProjectionStore as n, AdvancedValueSpec as o, DocumentProjection as p, projectionStoreDebug as r, CollectionEvent as s, ProjectionStore as t, DocumentCollectionEvent as u, ProjectionValues as v, ProjectionError as w, input as x, ValueEvent as y };
+//# sourceMappingURL=store-cp5CpfCy.d.ts.map

package/package.json

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

package/skills/doxum-runtime/SKILL.md

@@ -1,52 +1,34 @@
 ---
 name: doxum-runtime
-description: 'Use doxum and doxum/react to design, build, or review Doxum document runtime code. Apply for schemas, mutations, operations, views, subscriptions, and React integration.'
+description: 'Use doxum and doxum/react for schemas, scoped draft updates, ChangeSets, history, projections, subscriptions and React integration.'
 ---
 
 # Doxum Runtime
 
-Use this skill when a task creates, modifies, reviews, or explains Doxum code.
-It applies to `doxum`, `doxum/react`, and application code that uses
-Doxum's schema, runtime, transaction, operation, impact, projection, or React
-APIs. Do not apply it to unrelated TypeScript or React work merely because the
-application happens to contain a Doxum runtime.
+Read the [English guide](references/guide.en.md) or [中文指南](references/guide.zh-CN.md).
+For examples read [patterns](references/patterns.en.md) or [中文模式](references/patterns.zh-CN.md).
+Before runtime changes read [invariants](references/invariants.en.md) or
+[中文不变量](references/invariants.zh-CN.md).
 
-## Read the right reference
+- Root object defines schema identity; Infer describes readonly data with shared immutable payloads.
+- createDocument owns canonical state. update, apply and replace share one session.
+- Draft and trusted internal readWith scopes are borrowed for synchronous callbacks;
+  their proxies must not escape. Public values should use snapshot when they need to
+  outlive the callback.
+- Atomic fields are deeply readonly during access and replaced whole.
+- Use assign(scope, key, value) for replacements containing nested collection tools.
+- Expected business failure throws TransactionRejected. Other exceptions roll back
+  and rethrow unchanged. Callback returns carry business values and notices.
+- Commits contain final reversible ChangeSets. History and impact share those facts.
+- ChangeSets group member transitions by container, with explicit added/removed/updated
+  kinds, optional before/after order in the same group, and a separate root reset.
+  Standalone order records and duplicate groups are invalid. Grouping preserves field-level impact.
+- Paths belong in subscription, impact and collection source callbacks.
+- Projection dependencies are explicit; React selectors track actual reads.
+- Observer errors leave commits accepted. Do not retry as if they rolled back.
+- Core stays framework-neutral; adapters use integration capabilities.
+- Local sync owns browser persistence/leadership. Network conflict policy and
+  collaborative undo belong at a separate boundary.
 
-- Start with [the English guide](references/guide.en.md) for English requests
-  or [中文指南](references/guide.zh-CN.md) for Chinese requests. They are
-  equivalent task-oriented introductions.
-- Read [the English patterns](references/patterns.en.md) or
-  [中文模式参考](references/patterns.zh-CN.md) when implementing schema models,
-  transactions, replay, selectors, views, or React code.
-- Read [the English invariants](references/invariants.en.md) or
-  [中文不变量](references/invariants.zh-CN.md) before changing mutation,
-  addressing, impact, notification, history, tree, or derived-view behavior.
-
-## Required Doxum decisions
-
-- Treat `createDocument` as the only write authority for canonical document
-  state. Application writes use `runtime.update`; replayed external operations
-  use `runtime.apply`.
-- A transaction is synchronous and atomic. Do not retain a transaction reader
-  or writer after its callback returns, and do not introduce another writable
-  state cache.
-- Use the runtime's schema selectors, anchors, addresses, and `target` APIs.
-  Do not add local path parsers, duplicate impact-target helpers, or manually
-  synchronize derived data.
-- Handle expected mutation failure from the returned `rejected` result and its
-  `MutationIssue` values. Use `tx.report` or `tx.reject` with
-  `{ code, message, address? }` for application validation; runtime adds the
-  application source to published `DocumentDiagnostic` values. A thrown callback error
-  rolls back and is rethrown.
-- A committed result with `observerErrors` is still committed. Do not retry its
-  write as if canonical state had been rolled back.
-- Keep `core` framework-neutral. React code belongs behind `doxum/react` and
-  must not make `core` import UI concepts.
-- Doxum does not define persistence, synchronization, authorization, or
-  conflict resolution. Keep those policies in the application boundary before
-  `apply` or `replace`.
-
-When public behavior or lifecycle semantics change, update the README and
-architecture guide and add focused tests for rollback, inverse history, impact
-or subscription behavior, and performance-sensitive collection or tree paths.
+Update examples and tests when behavior changes. Never add compatibility APIs,
+a second path grammar or another writable derived cache.