@directive-run/core 0.4.2 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -1
- package/README.md +3 -2
- package/dist/adapter-utils.cjs +1 -1
- package/dist/adapter-utils.cjs.map +1 -1
- package/dist/adapter-utils.d.cts +6 -6
- package/dist/adapter-utils.d.ts +6 -6
- package/dist/adapter-utils.js +1 -1
- package/dist/adapter-utils.js.map +1 -1
- package/dist/index.cjs +8 -26
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +247 -592
- package/dist/index.d.ts +247 -592
- package/dist/index.js +8 -26
- package/dist/index.js.map +1 -1
- package/dist/plugins/index.cjs +2 -2
- package/dist/plugins/index.cjs.map +1 -1
- package/dist/plugins/index.d.cts +2 -70
- package/dist/plugins/index.d.ts +2 -70
- package/dist/plugins/index.js +2 -2
- package/dist/plugins/index.js.map +1 -1
- package/dist/{plugins-cDWoL7A7.d.cts → plugins-DaglUQVX.d.cts} +308 -72
- package/dist/{plugins-cDWoL7A7.d.ts → plugins-DaglUQVX.d.ts} +308 -72
- package/dist/testing.cjs +8 -3
- package/dist/testing.cjs.map +1 -1
- package/dist/testing.d.cts +64 -2
- package/dist/testing.d.ts +64 -2
- package/dist/testing.js +8 -3
- package/dist/testing.js.map +1 -1
- package/dist/worker.cjs +8 -3
- package/dist/worker.cjs.map +1 -1
- package/dist/worker.d.cts +3 -4
- package/dist/worker.d.ts +3 -4
- package/dist/worker.js +8 -3
- package/dist/worker.js.map +1 -1
- package/package.json +2 -3
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
|
-
import { S as Schema, F as Facts, R as Requirement, a as RequirementOutput, b as RetryPolicy, B as BatchConfig, c as ResolverContext, d as SchemaType,
|
|
2
|
-
export {
|
|
1
|
+
import { S as Schema, F as Facts, R as Requirement, a as RequirementOutput, b as RetryPolicy, B as BatchConfig, c as ResolverContext, d as SchemaType, M as ModuleSchema, T as TypedDerivationsDef, e as TypedEventsDef, E as EffectsDef, f as TypedConstraintsDef, g as TypedResolversDef, h as ModuleHooks, C as CrossModuleDeps, i as CrossModuleDerivationsDef, j as CrossModuleEffectsDef, k as CrossModuleConstraintsDef, l as ModuleDef, m as CreateSystemOptionsSingle, n as SingleModuleSystem, o as ModulesMap, p as CreateSystemOptionsNamed, N as NamespacedSystem, P as Plugin, q as TraceOption, r as ErrorBoundaryConfig, s as RequirementWithId, t as RequirementKeyFn, u as FactsStore, v as ConstraintsDef, w as ConstraintState, x as ResolversDef, y as ResolverStatus, z as System, A as FactChange, D as FactsSnapshot, G as ReconcileResult, H as Snapshot, I as DirectiveError, J as RecoveryStrategy, K as TraceEntry, L as ErrorSource, O as RetryLaterConfig, Q as HistoryAPI, U as HistoryOption, V as SystemConfig } from './plugins-DaglUQVX.js';
|
|
2
|
+
export { W as AnySystem, X as BatchItemResult, Y as BatchResolveResults, Z as ConstraintsControl, _ as CrossModuleConstraintDef, $ as CrossModuleDerivationFn, a0 as CrossModuleEffectDef, a1 as CrossModuleFactsWithSelf, a2 as DerivationKeys, a3 as DerivationReturnType, a4 as DerivationsControl, a5 as DerivationsSchema, a6 as DeriveAccessor, a7 as DispatchEventsFromSchema, a8 as DistributableSnapshot, a9 as DistributableSnapshotOptions, aa as DynamicConstraintDef, ab as DynamicEffectDef, ac as DynamicResolverDef, ad as EffectCleanup, ae as EffectsControl, af as EventPayloadSchema, ag as EventsAccessor, ah as EventsAccessorFromSchema, ai as EventsDef, aj as EventsSchema, ak as FactKeys, al as FactReturnType, am as FlexibleEventHandler, an as HistoryConfig, ao as HistoryState, ap as InferDerivations, aq as InferEventPayloadFromSchema, ar as InferEvents, as as InferFacts, at as InferRequirementPayloadFromSchema, au as InferRequirementTypes, av as InferRequirements, aw as InferSchema, ax as InferSchemaType, ay as InferSelectorState, az as MutableNamespacedFacts, aA as NamespacedDerivations, aB as NamespacedEventsAccessor, aC as NamespacedFacts, aD as ObservableKeys, aE as RequirementExplanation, aF as RequirementOutput, aG as RequirementPayloadSchema, aH as RequirementsSchema, aI as ResolversControl, aJ as SnapshotMeta, aK as SystemEvent, aL as SystemInspection, aM as SystemMode, aN as SystemSnapshot, aO as TraceConfig, aP as TypedConstraintDef, aQ as TypedResolverContext, aR as TypedResolverDef, aS as UnionEvents, aT as isNamespacedSystem, aU as isSingleModuleSystem } from './plugins-DaglUQVX.js';
|
|
3
3
|
export { D as DistributableSnapshotLike, S as SignedSnapshot, a as SnapshotDiff, b as SnapshotDiffEntry, d as diffSnapshots, i as isSignedSnapshot, c as isSnapshotExpired, s as shallowEqual, e as signSnapshot, v as validateSnapshot, f as verifySnapshotSignature } from './utils-4JrY5fk9.js';
|
|
4
|
-
export { DirectiveModuleStructure, ReduxSliceConfig, XStateMachineConfig, ZustandStoreConfig, analyzeReduxSlice, analyzeXStateMachine, analyzeZustandStore, generateMigrationChecklist, generateModuleCode } from './migration.js';
|
|
5
4
|
|
|
6
5
|
/**
|
|
7
6
|
* Derivation Types - Type definitions for derivations
|
|
@@ -15,7 +14,7 @@ interface TrackingContext {
|
|
|
15
14
|
}
|
|
16
15
|
/** Derivation definition function signature. */
|
|
17
16
|
interface DerivationDef<S extends Schema, T, D extends DerivationsDef<S>> {
|
|
18
|
-
(facts: Facts<S>,
|
|
17
|
+
(facts: Facts<S>, derived: DerivedValues<S, D>): T;
|
|
19
18
|
}
|
|
20
19
|
/** Map of derivation definitions. */
|
|
21
20
|
type DerivationsDef<S extends Schema> = Record<string, DerivationDef<S, unknown, DerivationsDef<S>>>;
|
|
@@ -143,7 +142,7 @@ interface TypedResolver<S extends Schema, R extends Requirement = Requirement> {
|
|
|
143
142
|
* @example
|
|
144
143
|
* ```typescript
|
|
145
144
|
* const schema = { count: t.number(), threshold: t.number() };
|
|
146
|
-
* const factory =
|
|
145
|
+
* const factory = createConstraintFactory<typeof schema>();
|
|
147
146
|
*
|
|
148
147
|
* const maxCountConstraint = factory.create({
|
|
149
148
|
* when: (facts) => facts.count > facts.threshold,
|
|
@@ -151,7 +150,7 @@ interface TypedResolver<S extends Schema, R extends Requirement = Requirement> {
|
|
|
151
150
|
* });
|
|
152
151
|
* ```
|
|
153
152
|
*/
|
|
154
|
-
declare function
|
|
153
|
+
declare function createConstraintFactory<S extends Schema>(): {
|
|
155
154
|
/**
|
|
156
155
|
* Create a typed constraint
|
|
157
156
|
*/
|
|
@@ -164,7 +163,7 @@ declare function constraintFactory<S extends Schema>(): {
|
|
|
164
163
|
* @example
|
|
165
164
|
* ```typescript
|
|
166
165
|
* const schema = { user: t.object<User>() };
|
|
167
|
-
* const factory =
|
|
166
|
+
* const factory = createResolverFactory<typeof schema>();
|
|
168
167
|
*
|
|
169
168
|
* const fetchUserResolver = factory.create<FetchUserReq>({
|
|
170
169
|
* requirement: (req): req is FetchUserReq => req.type === "FETCH_USER",
|
|
@@ -174,7 +173,7 @@ declare function constraintFactory<S extends Schema>(): {
|
|
|
174
173
|
* });
|
|
175
174
|
* ```
|
|
176
175
|
*/
|
|
177
|
-
declare function
|
|
176
|
+
declare function createResolverFactory<S extends Schema>(): {
|
|
178
177
|
/**
|
|
179
178
|
* Create a typed resolver
|
|
180
179
|
*/
|
|
@@ -182,7 +181,7 @@ declare function resolverFactory<S extends Schema>(): {
|
|
|
182
181
|
};
|
|
183
182
|
/**
|
|
184
183
|
* Type-safe constraint creator.
|
|
185
|
-
* Simpler alternative to
|
|
184
|
+
* Simpler alternative to createConstraintFactory when you don't need a factory pattern.
|
|
186
185
|
*
|
|
187
186
|
* @example
|
|
188
187
|
* ```typescript
|
|
@@ -195,7 +194,7 @@ declare function resolverFactory<S extends Schema>(): {
|
|
|
195
194
|
declare function typedConstraint<S extends Schema, R extends Requirement = Requirement>(constraint: TypedConstraint<S, R>): TypedConstraint<S, R>;
|
|
196
195
|
/**
|
|
197
196
|
* Type-safe resolver creator.
|
|
198
|
-
* Simpler alternative to
|
|
197
|
+
* Simpler alternative to createResolverFactory when you don't need a factory pattern.
|
|
199
198
|
*
|
|
200
199
|
* @example
|
|
201
200
|
* ```typescript
|
|
@@ -210,14 +209,12 @@ declare function typedConstraint<S extends Schema, R extends Requirement = Requi
|
|
|
210
209
|
declare function typedResolver<S extends Schema, R extends Requirement = Requirement>(resolver: TypedResolver<S, R>): TypedResolver<S, R>;
|
|
211
210
|
|
|
212
211
|
/**
|
|
213
|
-
*
|
|
212
|
+
* Schema Type Builders
|
|
214
213
|
*
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
* - Granular subscriptions by key
|
|
220
|
-
* - Schema validation in development mode
|
|
214
|
+
* Provides type-safe schema definitions with optional runtime validation.
|
|
215
|
+
* Used to define fact types, derivation types, event payload types, etc.
|
|
216
|
+
*
|
|
217
|
+
* This module has no dependency on the facts store or tracking system.
|
|
221
218
|
*/
|
|
222
219
|
|
|
223
220
|
/** Brand symbol for branded types */
|
|
@@ -497,108 +494,6 @@ declare const t: {
|
|
|
497
494
|
*/
|
|
498
495
|
bigint(): ChainableSchemaType<bigint>;
|
|
499
496
|
};
|
|
500
|
-
/** Options for creating a facts store */
|
|
501
|
-
interface CreateFactsStoreOptions<S extends Schema> {
|
|
502
|
-
schema: S;
|
|
503
|
-
/** Validate values against schema (default: process.env.NODE_ENV !== 'production') */
|
|
504
|
-
validate?: boolean;
|
|
505
|
-
/** Throw on unknown schema keys (default: true in dev mode) */
|
|
506
|
-
strictKeys?: boolean;
|
|
507
|
-
/** Redact sensitive values in error messages */
|
|
508
|
-
redactErrors?: boolean;
|
|
509
|
-
/** Callback when facts change (for plugin hooks) */
|
|
510
|
-
onChange?: (key: string, value: unknown, prev: unknown) => void;
|
|
511
|
-
/** Callback for batch changes */
|
|
512
|
-
onBatch?: (changes: Array<{
|
|
513
|
-
key: string;
|
|
514
|
-
value: unknown;
|
|
515
|
-
prev: unknown;
|
|
516
|
-
type: "set" | "delete";
|
|
517
|
-
}>) => void;
|
|
518
|
-
}
|
|
519
|
-
/**
|
|
520
|
-
* Create a reactive facts store backed by a Map with schema validation,
|
|
521
|
-
* batched mutations, and granular key-level subscriptions.
|
|
522
|
-
*
|
|
523
|
-
* @remarks
|
|
524
|
-
* The store is the low-level primitive that powers the `facts` proxy.
|
|
525
|
-
* Most users should use {@link createFacts} or `createModule` instead.
|
|
526
|
-
*
|
|
527
|
-
* @param options - Store configuration including schema, validation settings, and change callbacks
|
|
528
|
-
* @returns A {@link FactsStore} with get/set/batch/subscribe methods and automatic schema validation
|
|
529
|
-
*
|
|
530
|
-
* @example
|
|
531
|
-
* ```ts
|
|
532
|
-
* const store = createFactsStore({
|
|
533
|
-
* schema: { count: t.number(), name: t.string() },
|
|
534
|
-
* });
|
|
535
|
-
*
|
|
536
|
-
* store.set("count", 1);
|
|
537
|
-
* store.get("count"); // 1
|
|
538
|
-
*
|
|
539
|
-
* store.batch(() => {
|
|
540
|
-
* store.set("count", 2);
|
|
541
|
-
* store.set("name", "hello");
|
|
542
|
-
* }); // listeners fire once after batch completes
|
|
543
|
-
* ```
|
|
544
|
-
*
|
|
545
|
-
* @internal
|
|
546
|
-
*/
|
|
547
|
-
declare function createFactsStore<S extends Schema>(options: CreateFactsStoreOptions<S>): FactsStore<S>;
|
|
548
|
-
/**
|
|
549
|
-
* Create a Proxy wrapper around a {@link FactsStore} for clean property-style
|
|
550
|
-
* access (`facts.phase`) with automatic dependency tracking.
|
|
551
|
-
*
|
|
552
|
-
* @remarks
|
|
553
|
-
* Reading a property calls `store.get()` (which tracks the access for
|
|
554
|
-
* auto-tracked derivations). Writing a property calls `store.set()` (which
|
|
555
|
-
* validates against the schema). The proxy also exposes `$store` for direct
|
|
556
|
-
* store access and `$snapshot()` for untracked reads.
|
|
557
|
-
*
|
|
558
|
-
* @param store - The underlying facts store to wrap
|
|
559
|
-
* @param schema - The schema definition used for `ownKeys` enumeration
|
|
560
|
-
* @returns A {@link Facts} proxy with property-style get/set and prototype pollution guards
|
|
561
|
-
*
|
|
562
|
-
* @example
|
|
563
|
-
* ```ts
|
|
564
|
-
* const store = createFactsStore({ schema: { phase: t.string() } });
|
|
565
|
-
* const facts = createFactsProxy(store, { phase: t.string() });
|
|
566
|
-
*
|
|
567
|
-
* facts.phase = "red";
|
|
568
|
-
* console.log(facts.phase); // "red"
|
|
569
|
-
* ```
|
|
570
|
-
*
|
|
571
|
-
* @internal
|
|
572
|
-
*/
|
|
573
|
-
declare function createFactsProxy<S extends Schema>(store: FactsStore<S>, schema: S): Facts<S>;
|
|
574
|
-
/**
|
|
575
|
-
* Convenience factory that creates both a {@link FactsStore} and its
|
|
576
|
-
* {@link createFactsProxy | proxy wrapper} in a single call.
|
|
577
|
-
*
|
|
578
|
-
* @remarks
|
|
579
|
-
* This is the recommended entry point when you need low-level store access
|
|
580
|
-
* outside of `createModule` / `createSystem`.
|
|
581
|
-
*
|
|
582
|
-
* @param options - Same options as {@link createFactsStore}
|
|
583
|
-
* @returns An object with `store` (the reactive Map-backed store) and `facts` (the Proxy accessor)
|
|
584
|
-
*
|
|
585
|
-
* @example
|
|
586
|
-
* ```ts
|
|
587
|
-
* const { store, facts } = createFacts({
|
|
588
|
-
* schema: { phase: t.string<"red" | "green">() },
|
|
589
|
-
* });
|
|
590
|
-
*
|
|
591
|
-
* facts.phase = "red";
|
|
592
|
-
* console.log(facts.phase); // "red"
|
|
593
|
-
* store.subscribe(["phase"], () => console.log("phase changed"));
|
|
594
|
-
* ```
|
|
595
|
-
*
|
|
596
|
-
* @internal
|
|
597
|
-
*/
|
|
598
|
-
declare function createFacts<S extends Schema>(options: CreateFactsStoreOptions<S>): {
|
|
599
|
-
store: FactsStore<S>;
|
|
600
|
-
facts: Facts<S>;
|
|
601
|
-
};
|
|
602
497
|
|
|
603
498
|
/**
|
|
604
499
|
* Module - The declarative API for defining Directive modules
|
|
@@ -620,8 +515,11 @@ interface ModuleConfig<M extends ModuleSchema> {
|
|
|
620
515
|
constraints?: TypedConstraintsDef<M>;
|
|
621
516
|
resolvers?: TypedResolversDef<M>;
|
|
622
517
|
hooks?: ModuleHooks<M>;
|
|
623
|
-
/**
|
|
624
|
-
|
|
518
|
+
/** History configuration — controls which events create snapshots for undo/redo. */
|
|
519
|
+
history?: {
|
|
520
|
+
/** Events that create history snapshots. Omit to snapshot all events. */
|
|
521
|
+
snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
|
|
522
|
+
};
|
|
625
523
|
}
|
|
626
524
|
/**
|
|
627
525
|
* Module configuration with cross-module dependencies for type-safe access
|
|
@@ -691,14 +589,17 @@ interface ModuleConfigWithDeps<M extends ModuleSchema, Deps extends CrossModuleD
|
|
|
691
589
|
/** Resolvers. Uses flat access (`ctx.facts.myFact`) to keep async mutations scoped to own module. */
|
|
692
590
|
resolvers?: TypedResolversDef<M>;
|
|
693
591
|
hooks?: ModuleHooks<M>;
|
|
694
|
-
/**
|
|
695
|
-
|
|
592
|
+
/** History configuration — controls which events create snapshots for undo/redo. */
|
|
593
|
+
history?: {
|
|
594
|
+
/** Events that create history snapshots. Omit to snapshot all events. */
|
|
595
|
+
snapshotEvents?: Array<keyof (M["events"] extends Record<string, unknown> ? M["events"] : Record<string, never>) & string>;
|
|
596
|
+
};
|
|
696
597
|
}
|
|
697
598
|
/**
|
|
698
599
|
* Create a module definition with full type inference.
|
|
699
600
|
*
|
|
700
601
|
* The consolidated schema provides:
|
|
701
|
-
* - Derivation composition (`
|
|
602
|
+
* - Derivation composition (`derived.otherDerivation` is typed)
|
|
702
603
|
* - Event dispatch (`system.dispatch({ type: "..." })` has autocomplete)
|
|
703
604
|
* - Resolver requirements (`req.payload` is typed based on requirement type)
|
|
704
605
|
*
|
|
@@ -732,9 +633,9 @@ interface ModuleConfigWithDeps<M extends ModuleSchema, Deps extends CrossModuleD
|
|
|
732
633
|
* },
|
|
733
634
|
* derive: {
|
|
734
635
|
* isRed: (facts) => facts.phase === "red",
|
|
735
|
-
* timeRemaining: (facts,
|
|
736
|
-
* //
|
|
737
|
-
* return
|
|
636
|
+
* timeRemaining: (facts, derived) => {
|
|
637
|
+
* // derived.isRed is typed as boolean!
|
|
638
|
+
* return derived.isRed ? 30 - facts.elapsed : 0;
|
|
738
639
|
* },
|
|
739
640
|
* },
|
|
740
641
|
* events: {
|
|
@@ -872,431 +773,6 @@ declare function createModuleFactory<const M extends ModuleSchema, const Deps ex
|
|
|
872
773
|
declare function createSystem<S extends ModuleSchema>(options: CreateSystemOptionsSingle<S>): SingleModuleSystem<S>;
|
|
873
774
|
declare function createSystem<const Modules extends ModulesMap>(options: CreateSystemOptionsNamed<Modules>): NamespacedSystem<Modules>;
|
|
874
775
|
|
|
875
|
-
/**
|
|
876
|
-
* Builder Pattern API for Directive Modules
|
|
877
|
-
*
|
|
878
|
-
* An alternative, fluent API for creating modules that provides
|
|
879
|
-
* a more declarative style for module definition.
|
|
880
|
-
*
|
|
881
|
-
* @example
|
|
882
|
-
* ```typescript
|
|
883
|
-
* import { module, t } from '@directive-run/core';
|
|
884
|
-
*
|
|
885
|
-
* const counter = module("counter")
|
|
886
|
-
* .schema({
|
|
887
|
-
* facts: { count: t.number(), lastAction: t.string() },
|
|
888
|
-
* derivations: { doubled: t.number(), isPositive: t.boolean() },
|
|
889
|
-
* events: { increment: {}, decrement: {} },
|
|
890
|
-
* requirements: {},
|
|
891
|
-
* })
|
|
892
|
-
* .init((facts) => {
|
|
893
|
-
* facts.count = 0;
|
|
894
|
-
* facts.lastAction = "";
|
|
895
|
-
* })
|
|
896
|
-
* .derive({
|
|
897
|
-
* doubled: (facts) => facts.count * 2,
|
|
898
|
-
* isPositive: (facts) => facts.count > 0,
|
|
899
|
-
* })
|
|
900
|
-
* .events({
|
|
901
|
-
* increment: (facts) => {
|
|
902
|
-
* facts.count += 1;
|
|
903
|
-
* facts.lastAction = "increment";
|
|
904
|
-
* },
|
|
905
|
-
* decrement: (facts) => {
|
|
906
|
-
* facts.count -= 1;
|
|
907
|
-
* facts.lastAction = "decrement";
|
|
908
|
-
* },
|
|
909
|
-
* })
|
|
910
|
-
* .build();
|
|
911
|
-
* ```
|
|
912
|
-
*/
|
|
913
|
-
|
|
914
|
-
/**
|
|
915
|
-
* Fluent builder interface for constructing {@link ModuleDef} instances step by step.
|
|
916
|
-
*
|
|
917
|
-
* Chain methods like `.schema()`, `.init()`, `.derive()`, `.events()`, and others
|
|
918
|
-
* to configure the module, then call `.build()` to produce the final definition.
|
|
919
|
-
* The builder validates that all schema-declared derivations and events have
|
|
920
|
-
* corresponding implementations before returning.
|
|
921
|
-
*
|
|
922
|
-
* @typeParam M - The module schema type, narrowed after calling `.schema()`.
|
|
923
|
-
* @public
|
|
924
|
-
*/
|
|
925
|
-
interface ModuleBuilder<M extends ModuleSchema = ModuleSchema> {
|
|
926
|
-
/**
|
|
927
|
-
* Define the schema for this module (facts, derivations, events, requirements).
|
|
928
|
-
*/
|
|
929
|
-
schema<NewM extends ModuleSchema>(schema: NewM): ModuleBuilder<NewM>;
|
|
930
|
-
/**
|
|
931
|
-
* Define the initialization function for this module.
|
|
932
|
-
*/
|
|
933
|
-
init(initFn: (facts: Facts<M["facts"]>) => void): ModuleBuilder<M>;
|
|
934
|
-
/**
|
|
935
|
-
* Define derivation implementations for this module.
|
|
936
|
-
* Keys must match those declared in schema.derivations.
|
|
937
|
-
*/
|
|
938
|
-
derive<D extends Record<string, (facts: Facts<M["facts"]>, derive: DeriveAccessor<M>) => unknown>>(derivations: D): ModuleBuilder<M>;
|
|
939
|
-
/**
|
|
940
|
-
* Define event handler implementations for this module.
|
|
941
|
-
* Keys must match those declared in schema.events.
|
|
942
|
-
*/
|
|
943
|
-
events<E extends Record<string, (facts: Facts<M["facts"]>, payload: unknown) => void>>(events: E): ModuleBuilder<M>;
|
|
944
|
-
/**
|
|
945
|
-
* Define effects (side effects) for this module.
|
|
946
|
-
*/
|
|
947
|
-
effects(effects: EffectsDef<M["facts"]>): ModuleBuilder<M>;
|
|
948
|
-
/**
|
|
949
|
-
* Define constraints for this module.
|
|
950
|
-
*/
|
|
951
|
-
constraints<C extends Record<string, ConstraintDef<M>>>(constraints: C): ModuleBuilder<M>;
|
|
952
|
-
/**
|
|
953
|
-
* Define resolvers for this module.
|
|
954
|
-
*/
|
|
955
|
-
resolvers<R extends Record<string, ResolverDef<M>>>(resolvers: R): ModuleBuilder<M>;
|
|
956
|
-
/**
|
|
957
|
-
* Define lifecycle hooks for this module.
|
|
958
|
-
*/
|
|
959
|
-
hooks(hooks: ModuleHooks<M>): ModuleBuilder<M>;
|
|
960
|
-
/**
|
|
961
|
-
* Build the module definition.
|
|
962
|
-
*/
|
|
963
|
-
build(): ModuleDef<M>;
|
|
964
|
-
}
|
|
965
|
-
/**
|
|
966
|
-
* Accessor for reading other derivations within a derivation function.
|
|
967
|
-
*/
|
|
968
|
-
type DeriveAccessor<M extends ModuleSchema> = M["derivations"] extends DerivationsSchema ? {
|
|
969
|
-
readonly [K in keyof M["derivations"]]: InferSchemaType<M["derivations"][K]>;
|
|
970
|
-
} : Record<string, never>;
|
|
971
|
-
/**
|
|
972
|
-
* Infer the TypeScript type from a schema type definition.
|
|
973
|
-
*/
|
|
974
|
-
type InferSchemaType<T> = T extends {
|
|
975
|
-
_type: infer U;
|
|
976
|
-
} ? U : any;
|
|
977
|
-
/**
|
|
978
|
-
* Constraint definition for the builder.
|
|
979
|
-
*/
|
|
980
|
-
interface ConstraintDef<M extends ModuleSchema> {
|
|
981
|
-
when: (facts: Facts<M["facts"]>) => boolean;
|
|
982
|
-
require: {
|
|
983
|
-
type: string;
|
|
984
|
-
[key: string]: unknown;
|
|
985
|
-
} | ((facts: Facts<M["facts"]>) => {
|
|
986
|
-
type: string;
|
|
987
|
-
[key: string]: unknown;
|
|
988
|
-
} | null);
|
|
989
|
-
priority?: number;
|
|
990
|
-
}
|
|
991
|
-
/**
|
|
992
|
-
* Resolver definition for the builder.
|
|
993
|
-
*/
|
|
994
|
-
interface ResolverDef<M extends ModuleSchema> {
|
|
995
|
-
requirement: string | ((req: {
|
|
996
|
-
type: string;
|
|
997
|
-
[key: string]: unknown;
|
|
998
|
-
}) => boolean);
|
|
999
|
-
resolve: (req: {
|
|
1000
|
-
type: string;
|
|
1001
|
-
[key: string]: unknown;
|
|
1002
|
-
}, ctx: {
|
|
1003
|
-
facts: Facts<M["facts"]>;
|
|
1004
|
-
signal?: AbortSignal;
|
|
1005
|
-
}) => void | Promise<void>;
|
|
1006
|
-
retry?: {
|
|
1007
|
-
attempts?: number;
|
|
1008
|
-
backoff?: "linear" | "exponential";
|
|
1009
|
-
delay?: number;
|
|
1010
|
-
};
|
|
1011
|
-
timeout?: number;
|
|
1012
|
-
key?: (req: {
|
|
1013
|
-
type: string;
|
|
1014
|
-
[key: string]: unknown;
|
|
1015
|
-
}) => string;
|
|
1016
|
-
}
|
|
1017
|
-
/**
|
|
1018
|
-
* Create a new module using the fluent builder pattern.
|
|
1019
|
-
*
|
|
1020
|
-
* Returns a {@link ModuleBuilder} that lets you declaratively define a module's
|
|
1021
|
-
* schema, initialization, derivations, events, effects, constraints, resolvers,
|
|
1022
|
-
* and lifecycle hooks via method chaining. Call `.build()` at the end to produce
|
|
1023
|
-
* the final {@link ModuleDef}.
|
|
1024
|
-
*
|
|
1025
|
-
* @remarks
|
|
1026
|
-
* The builder validates at build time that every derivation and event declared
|
|
1027
|
-
* in the schema has a corresponding implementation. Missing implementations
|
|
1028
|
-
* cause a descriptive error.
|
|
1029
|
-
*
|
|
1030
|
-
* @param id - Unique identifier for this module, used for namespacing in multi-module systems.
|
|
1031
|
-
* @returns A {@link ModuleBuilder} ready for configuration via method chaining.
|
|
1032
|
-
*
|
|
1033
|
-
* @example
|
|
1034
|
-
* ```typescript
|
|
1035
|
-
* import { module, t } from '@directive-run/core';
|
|
1036
|
-
*
|
|
1037
|
-
* const counter = module("counter")
|
|
1038
|
-
* .schema({
|
|
1039
|
-
* facts: { count: t.number() },
|
|
1040
|
-
* derivations: { doubled: t.number() },
|
|
1041
|
-
* events: { increment: {} },
|
|
1042
|
-
* requirements: {},
|
|
1043
|
-
* })
|
|
1044
|
-
* .init((facts) => {
|
|
1045
|
-
* facts.count = 0;
|
|
1046
|
-
* })
|
|
1047
|
-
* .derive({
|
|
1048
|
-
* doubled: (facts) => facts.count * 2,
|
|
1049
|
-
* })
|
|
1050
|
-
* .events({
|
|
1051
|
-
* increment: (facts) => {
|
|
1052
|
-
* facts.count += 1;
|
|
1053
|
-
* },
|
|
1054
|
-
* })
|
|
1055
|
-
* .build();
|
|
1056
|
-
* ```
|
|
1057
|
-
*
|
|
1058
|
-
* @public
|
|
1059
|
-
*/
|
|
1060
|
-
declare function module$1(id: string): ModuleBuilder<ModuleSchema>;
|
|
1061
|
-
|
|
1062
|
-
/**
|
|
1063
|
-
* Constraint Builder API
|
|
1064
|
-
*
|
|
1065
|
-
* Fluent builders for creating typed constraint definitions.
|
|
1066
|
-
*
|
|
1067
|
-
* @example Full builder
|
|
1068
|
-
* ```typescript
|
|
1069
|
-
* import { constraint } from '@directive-run/core';
|
|
1070
|
-
*
|
|
1071
|
-
* const escalate = constraint<typeof schema>()
|
|
1072
|
-
* .when(f => f.confidence < 0.7)
|
|
1073
|
-
* .require({ type: 'ESCALATE' })
|
|
1074
|
-
* .priority(50)
|
|
1075
|
-
* .build();
|
|
1076
|
-
* ```
|
|
1077
|
-
*
|
|
1078
|
-
* @example Quick shorthand
|
|
1079
|
-
* ```typescript
|
|
1080
|
-
* import { when } from '@directive-run/core';
|
|
1081
|
-
*
|
|
1082
|
-
* const pause = when<typeof schema>(f => f.errors > 3)
|
|
1083
|
-
* .require({ type: 'PAUSE' });
|
|
1084
|
-
* ```
|
|
1085
|
-
*/
|
|
1086
|
-
|
|
1087
|
-
type WhenFn<M extends ModuleSchema> = (facts: Facts<M["facts"]>) => boolean | Promise<boolean>;
|
|
1088
|
-
type RequireValue<M extends ModuleSchema> = RequirementOutput$1<InferRequirements<M>> | ((facts: Facts<M["facts"]>) => RequirementOutput$1<InferRequirements<M>>);
|
|
1089
|
-
/** Builder after constraint() — must call .when() first */
|
|
1090
|
-
interface ConstraintBuilderStart<M extends ModuleSchema> {
|
|
1091
|
-
when(condition: WhenFn<M>): ConstraintBuilderWithWhen<M>;
|
|
1092
|
-
}
|
|
1093
|
-
/** Builder after .when() — must call .require() next */
|
|
1094
|
-
interface ConstraintBuilderWithWhen<M extends ModuleSchema> {
|
|
1095
|
-
require(req: RequireValue<M>): ConstraintBuilderComplete<M>;
|
|
1096
|
-
}
|
|
1097
|
-
/** Builder after .require() — optional chaining + .build() */
|
|
1098
|
-
interface ConstraintBuilderComplete<M extends ModuleSchema> {
|
|
1099
|
-
priority(n: number): ConstraintBuilderComplete<M>;
|
|
1100
|
-
after(...ids: string[]): ConstraintBuilderComplete<M>;
|
|
1101
|
-
deps(...keys: string[]): ConstraintBuilderComplete<M>;
|
|
1102
|
-
timeout(ms: number): ConstraintBuilderComplete<M>;
|
|
1103
|
-
async(value: boolean): ConstraintBuilderComplete<M>;
|
|
1104
|
-
build(): TypedConstraintDef<M>;
|
|
1105
|
-
}
|
|
1106
|
-
/** Result from when().require() — a valid constraint with optional immutable chaining */
|
|
1107
|
-
type WhenConstraint<M extends ModuleSchema> = TypedConstraintDef<M> & {
|
|
1108
|
-
withPriority(n: number): WhenConstraint<M>;
|
|
1109
|
-
withAfter(...ids: string[]): WhenConstraint<M>;
|
|
1110
|
-
withDeps(...keys: string[]): WhenConstraint<M>;
|
|
1111
|
-
withTimeout(ms: number): WhenConstraint<M>;
|
|
1112
|
-
withAsync(value: boolean): WhenConstraint<M>;
|
|
1113
|
-
};
|
|
1114
|
-
/** Result from when() — must call .require() */
|
|
1115
|
-
interface WhenBuilder<M extends ModuleSchema> {
|
|
1116
|
-
require(req: RequireValue<M>): WhenConstraint<M>;
|
|
1117
|
-
}
|
|
1118
|
-
/**
|
|
1119
|
-
* Create a constraint using the full builder pattern.
|
|
1120
|
-
* Requires `.when()`, `.require()`, and `.build()`.
|
|
1121
|
-
*
|
|
1122
|
-
* @example
|
|
1123
|
-
* ```typescript
|
|
1124
|
-
* const c = constraint<typeof schema>()
|
|
1125
|
-
* .when(f => f.phase === "red")
|
|
1126
|
-
* .require({ type: "TRANSITION", to: "green" })
|
|
1127
|
-
* .priority(50)
|
|
1128
|
-
* .after("healthCheck")
|
|
1129
|
-
* .build();
|
|
1130
|
-
* ```
|
|
1131
|
-
*/
|
|
1132
|
-
declare function constraint<M extends ModuleSchema>(): ConstraintBuilderStart<M>;
|
|
1133
|
-
/**
|
|
1134
|
-
* Quick shorthand for creating constraints.
|
|
1135
|
-
* Returns a valid constraint directly (no `.build()` needed).
|
|
1136
|
-
*
|
|
1137
|
-
* @example
|
|
1138
|
-
* ```typescript
|
|
1139
|
-
* const pause = when<typeof schema>(f => f.errors > 3)
|
|
1140
|
-
* .require({ type: 'PAUSE' });
|
|
1141
|
-
*
|
|
1142
|
-
* // With optional chaining (immutable — returns new constraint)
|
|
1143
|
-
* const halt = when<typeof schema>(f => f.errors > 10)
|
|
1144
|
-
* .require({ type: 'HALT' })
|
|
1145
|
-
* .withPriority(100)
|
|
1146
|
-
* .withAfter('healthCheck');
|
|
1147
|
-
* ```
|
|
1148
|
-
*/
|
|
1149
|
-
declare function when<M extends ModuleSchema>(condition: WhenFn<M>): WhenBuilder<M>;
|
|
1150
|
-
|
|
1151
|
-
/**
|
|
1152
|
-
* System Builder API
|
|
1153
|
-
*
|
|
1154
|
-
* Fluent builder for creating Directive systems.
|
|
1155
|
-
*
|
|
1156
|
-
* @example Single module
|
|
1157
|
-
* ```typescript
|
|
1158
|
-
* import { system } from '@directive-run/core';
|
|
1159
|
-
*
|
|
1160
|
-
* const sys = system()
|
|
1161
|
-
* .module(counterModule)
|
|
1162
|
-
* .plugins([loggingPlugin()])
|
|
1163
|
-
* .debug({ timeTravel: true })
|
|
1164
|
-
* .build();
|
|
1165
|
-
* ```
|
|
1166
|
-
*
|
|
1167
|
-
* @example Multiple modules
|
|
1168
|
-
* ```typescript
|
|
1169
|
-
* const sys = system()
|
|
1170
|
-
* .modules({ auth: authModule, cart: cartModule })
|
|
1171
|
-
* .plugins([loggingPlugin()])
|
|
1172
|
-
* .build();
|
|
1173
|
-
* ```
|
|
1174
|
-
*/
|
|
1175
|
-
|
|
1176
|
-
/**
|
|
1177
|
-
* Entry point of the system builder, returned by {@link system}.
|
|
1178
|
-
*
|
|
1179
|
-
* Choose `.module()` for a single-module {@link SingleModuleSystem} with direct
|
|
1180
|
-
* fact/derivation access, or `.modules()` for a namespaced {@link NamespacedSystem}
|
|
1181
|
-
* that composes multiple modules.
|
|
1182
|
-
*
|
|
1183
|
-
* @public
|
|
1184
|
-
*/
|
|
1185
|
-
interface SystemBuilderStart {
|
|
1186
|
-
/**
|
|
1187
|
-
* Configure the system with a single module definition.
|
|
1188
|
-
*
|
|
1189
|
-
* @param mod - The module definition to use as the system's sole module.
|
|
1190
|
-
* @returns A {@link SingleModuleSystemBuilder} for further configuration.
|
|
1191
|
-
*/
|
|
1192
|
-
module<S extends ModuleSchema>(mod: ModuleDef<S>): SingleModuleSystemBuilder<S>;
|
|
1193
|
-
/**
|
|
1194
|
-
* Configure the system with multiple named modules.
|
|
1195
|
-
*
|
|
1196
|
-
* @param mods - A map of namespace keys to module definitions.
|
|
1197
|
-
* @returns A {@link NamespacedSystemBuilder} for further configuration.
|
|
1198
|
-
*/
|
|
1199
|
-
modules<const Modules extends ModulesMap>(mods: Modules): NamespacedSystemBuilder<Modules>;
|
|
1200
|
-
}
|
|
1201
|
-
/**
|
|
1202
|
-
* Builder for a single-module system with direct access to facts, derivations, and events.
|
|
1203
|
-
*
|
|
1204
|
-
* @remarks
|
|
1205
|
-
* Use this builder when your system contains exactly one module. The resulting
|
|
1206
|
-
* {@link SingleModuleSystem} exposes facts, derivations, and dispatch without
|
|
1207
|
-
* namespace prefixes.
|
|
1208
|
-
*
|
|
1209
|
-
* @typeParam S - The module schema type.
|
|
1210
|
-
* @public
|
|
1211
|
-
*/
|
|
1212
|
-
interface SingleModuleSystemBuilder<S extends ModuleSchema> {
|
|
1213
|
-
/** Register plugins that hook into system lifecycle events. */
|
|
1214
|
-
plugins(plugins: Array<Plugin<ModuleSchema>>): SingleModuleSystemBuilder<S>;
|
|
1215
|
-
/** Enable debug features such as time-travel debugging and snapshot limits. */
|
|
1216
|
-
debug(config: DebugConfig): SingleModuleSystemBuilder<S>;
|
|
1217
|
-
/** Configure error boundary behavior including recovery strategies. */
|
|
1218
|
-
errorBoundary(config: ErrorBoundaryConfig): SingleModuleSystemBuilder<S>;
|
|
1219
|
-
/** Set the reconciliation tick interval in milliseconds. */
|
|
1220
|
-
tickMs(ms: number): SingleModuleSystemBuilder<S>;
|
|
1221
|
-
/** Enable zero-config mode which auto-generates constraints from schema metadata. */
|
|
1222
|
-
zeroConfig(enabled?: boolean): SingleModuleSystemBuilder<S>;
|
|
1223
|
-
/** Provide initial fact values to hydrate the system on startup. */
|
|
1224
|
-
initialFacts(facts: Partial<InferFacts<S>>): SingleModuleSystemBuilder<S>;
|
|
1225
|
-
/** Finalize configuration and create the running {@link SingleModuleSystem}. */
|
|
1226
|
-
build(): SingleModuleSystem<S>;
|
|
1227
|
-
}
|
|
1228
|
-
/**
|
|
1229
|
-
* Builder for a namespaced multi-module system.
|
|
1230
|
-
*
|
|
1231
|
-
* @remarks
|
|
1232
|
-
* Use this builder when composing multiple modules. The resulting
|
|
1233
|
-
* {@link NamespacedSystem} prefixes facts and derivations with the module
|
|
1234
|
-
* namespace key (e.g., `system.facts.auth.token`).
|
|
1235
|
-
*
|
|
1236
|
-
* @typeParam Modules - The modules map type mapping namespace keys to module definitions.
|
|
1237
|
-
* @public
|
|
1238
|
-
*/
|
|
1239
|
-
interface NamespacedSystemBuilder<Modules extends ModulesMap> {
|
|
1240
|
-
/** Register plugins that hook into system lifecycle events. */
|
|
1241
|
-
plugins(plugins: Array<Plugin<ModuleSchema>>): NamespacedSystemBuilder<Modules>;
|
|
1242
|
-
/** Enable debug features such as time-travel debugging and snapshot limits. */
|
|
1243
|
-
debug(config: DebugConfig): NamespacedSystemBuilder<Modules>;
|
|
1244
|
-
/** Configure error boundary behavior including recovery strategies. */
|
|
1245
|
-
errorBoundary(config: ErrorBoundaryConfig): NamespacedSystemBuilder<Modules>;
|
|
1246
|
-
/** Set the reconciliation tick interval in milliseconds. */
|
|
1247
|
-
tickMs(ms: number): NamespacedSystemBuilder<Modules>;
|
|
1248
|
-
/** Enable zero-config mode which auto-generates constraints from schema metadata. */
|
|
1249
|
-
zeroConfig(enabled?: boolean): NamespacedSystemBuilder<Modules>;
|
|
1250
|
-
/** Provide initial fact values keyed by module namespace for hydration on startup. */
|
|
1251
|
-
initialFacts(facts: Partial<{
|
|
1252
|
-
[K in keyof Modules]: Partial<InferFacts<ExtractSchema<Modules[K]>>>;
|
|
1253
|
-
}>): NamespacedSystemBuilder<Modules>;
|
|
1254
|
-
/** Control the order in which modules are initialized: automatic, declaration order, or explicit. */
|
|
1255
|
-
initOrder(order: "auto" | "declaration" | Array<keyof Modules & string>): NamespacedSystemBuilder<Modules>;
|
|
1256
|
-
/** Finalize configuration and create the running {@link NamespacedSystem}. */
|
|
1257
|
-
build(): NamespacedSystem<Modules>;
|
|
1258
|
-
}
|
|
1259
|
-
/**
|
|
1260
|
-
* Create a Directive system using the fluent builder pattern.
|
|
1261
|
-
*
|
|
1262
|
-
* Returns a {@link SystemBuilderStart} that branches into either a
|
|
1263
|
-
* single-module path (`.module()`) or a namespaced multi-module path
|
|
1264
|
-
* (`.modules()`). Chain configuration methods like `.plugins()`, `.debug()`,
|
|
1265
|
-
* and `.errorBoundary()`, then call `.build()` to produce the running system.
|
|
1266
|
-
*
|
|
1267
|
-
* @remarks
|
|
1268
|
-
* This is a convenience wrapper around {@link createSystem}. Both produce
|
|
1269
|
-
* identical systems; the builder simply offers a more discoverable,
|
|
1270
|
-
* chainable API.
|
|
1271
|
-
*
|
|
1272
|
-
* @returns A {@link SystemBuilderStart} ready to receive a module or modules map.
|
|
1273
|
-
*
|
|
1274
|
-
* @example Single-module system
|
|
1275
|
-
* ```typescript
|
|
1276
|
-
* import { system } from '@directive-run/core';
|
|
1277
|
-
*
|
|
1278
|
-
* const sys = system()
|
|
1279
|
-
* .module(counterModule)
|
|
1280
|
-
* .plugins([loggingPlugin()])
|
|
1281
|
-
* .debug({ timeTravel: true })
|
|
1282
|
-
* .build();
|
|
1283
|
-
* ```
|
|
1284
|
-
*
|
|
1285
|
-
* @example Multi-module namespaced system
|
|
1286
|
-
* ```typescript
|
|
1287
|
-
* import { system } from '@directive-run/core';
|
|
1288
|
-
*
|
|
1289
|
-
* const sys = system()
|
|
1290
|
-
* .modules({ auth: authModule, cart: cartModule })
|
|
1291
|
-
* .plugins([loggingPlugin()])
|
|
1292
|
-
* .initOrder(["auth", "cart"])
|
|
1293
|
-
* .build();
|
|
1294
|
-
* ```
|
|
1295
|
-
*
|
|
1296
|
-
* @public
|
|
1297
|
-
*/
|
|
1298
|
-
declare function system(): SystemBuilderStart;
|
|
1299
|
-
|
|
1300
776
|
/**
|
|
1301
777
|
* Requirement Status Utilities
|
|
1302
778
|
*
|
|
@@ -1383,8 +859,8 @@ interface CreateSystemWithStatusOptions<M extends ModuleSchema> {
|
|
|
1383
859
|
module: ModuleDef<M>;
|
|
1384
860
|
/** Additional plugins to include alongside the status plugin */
|
|
1385
861
|
plugins?: Plugin<any>[];
|
|
1386
|
-
/**
|
|
1387
|
-
|
|
862
|
+
/** Trace: per-run reconciliation changelog */
|
|
863
|
+
trace?: TraceOption;
|
|
1388
864
|
/** Error boundary configuration */
|
|
1389
865
|
errorBoundary?: ErrorBoundaryConfig;
|
|
1390
866
|
/** Tick interval in milliseconds */
|
|
@@ -1450,20 +926,6 @@ declare function createSystemWithStatus<M extends ModuleSchema>(options: CreateS
|
|
|
1450
926
|
* - Requirement comparison and hashing
|
|
1451
927
|
*/
|
|
1452
928
|
|
|
1453
|
-
/**
|
|
1454
|
-
* Generate a stable identity string for a requirement.
|
|
1455
|
-
*
|
|
1456
|
-
* When no custom key function is provided, the ID is formed from the
|
|
1457
|
-
* requirement's `type` plus a deterministic JSON serialization of its
|
|
1458
|
-
* remaining properties. A custom {@link RequirementKeyFn} can override
|
|
1459
|
-
* this to control deduplication granularity.
|
|
1460
|
-
*
|
|
1461
|
-
* @param req - The requirement to generate an ID for.
|
|
1462
|
-
* @param keyFn - Optional custom key function that overrides the default identity logic.
|
|
1463
|
-
* @returns A stable string that uniquely identifies this requirement for deduplication.
|
|
1464
|
-
*
|
|
1465
|
-
* @public
|
|
1466
|
-
*/
|
|
1467
929
|
declare function generateRequirementId(req: Requirement, keyFn?: RequirementKeyFn): string;
|
|
1468
930
|
/**
|
|
1469
931
|
* Create a typed requirement factory for a given requirement type string.
|
|
@@ -1639,6 +1101,120 @@ declare class RequirementSet {
|
|
|
1639
1101
|
};
|
|
1640
1102
|
}
|
|
1641
1103
|
|
|
1104
|
+
/**
|
|
1105
|
+
* Facts Store - Proxy-based reactive state with auto-tracking
|
|
1106
|
+
*
|
|
1107
|
+
* Features:
|
|
1108
|
+
* - Proxy-based access (facts.phase instead of facts.get("phase"))
|
|
1109
|
+
* - Automatic dependency tracking via tracking context
|
|
1110
|
+
* - Batched updates with coalesced notifications
|
|
1111
|
+
* - Granular subscriptions by key
|
|
1112
|
+
* - Schema validation in development mode
|
|
1113
|
+
*/
|
|
1114
|
+
|
|
1115
|
+
/** Options for creating a facts store */
|
|
1116
|
+
interface CreateFactsStoreOptions<S extends Schema> {
|
|
1117
|
+
schema: S;
|
|
1118
|
+
/** Validate values against schema (default: process.env.NODE_ENV !== 'production') */
|
|
1119
|
+
validate?: boolean;
|
|
1120
|
+
/** Throw on unknown schema keys (default: true in dev mode) */
|
|
1121
|
+
strictKeys?: boolean;
|
|
1122
|
+
/** Redact sensitive values in error messages */
|
|
1123
|
+
redactErrors?: boolean;
|
|
1124
|
+
/** Callback when facts change (for plugin hooks) */
|
|
1125
|
+
onChange?: (key: string, value: unknown, prev: unknown) => void;
|
|
1126
|
+
/** Callback for batch changes */
|
|
1127
|
+
onBatch?: (changes: Array<{
|
|
1128
|
+
key: string;
|
|
1129
|
+
value: unknown;
|
|
1130
|
+
prev: unknown;
|
|
1131
|
+
type: "set" | "delete";
|
|
1132
|
+
}>) => void;
|
|
1133
|
+
}
|
|
1134
|
+
/**
|
|
1135
|
+
* Create a reactive facts store backed by a Map with schema validation,
|
|
1136
|
+
* batched mutations, and granular key-level subscriptions.
|
|
1137
|
+
*
|
|
1138
|
+
* @remarks
|
|
1139
|
+
* The store is the low-level primitive that powers the `facts` proxy.
|
|
1140
|
+
* Most users should use {@link createFacts} or `createModule` instead.
|
|
1141
|
+
*
|
|
1142
|
+
* @param options - Store configuration including schema, validation settings, and change callbacks
|
|
1143
|
+
* @returns A {@link FactsStore} with get/set/batch/subscribe methods and automatic schema validation
|
|
1144
|
+
*
|
|
1145
|
+
* @example
|
|
1146
|
+
* ```ts
|
|
1147
|
+
* const store = createFactsStore({
|
|
1148
|
+
* schema: { count: t.number(), name: t.string() },
|
|
1149
|
+
* });
|
|
1150
|
+
*
|
|
1151
|
+
* store.set("count", 1);
|
|
1152
|
+
* store.get("count"); // 1
|
|
1153
|
+
*
|
|
1154
|
+
* store.batch(() => {
|
|
1155
|
+
* store.set("count", 2);
|
|
1156
|
+
* store.set("name", "hello");
|
|
1157
|
+
* }); // listeners fire once after batch completes
|
|
1158
|
+
* ```
|
|
1159
|
+
*
|
|
1160
|
+
* @internal
|
|
1161
|
+
*/
|
|
1162
|
+
declare function createFactsStore<S extends Schema>(options: CreateFactsStoreOptions<S>): FactsStore<S>;
|
|
1163
|
+
/**
|
|
1164
|
+
* Create a Proxy wrapper around a {@link FactsStore} for clean property-style
|
|
1165
|
+
* access (`facts.phase`) with automatic dependency tracking.
|
|
1166
|
+
*
|
|
1167
|
+
* @remarks
|
|
1168
|
+
* Reading a property calls `store.get()` (which tracks the access for
|
|
1169
|
+
* auto-tracked derivations). Writing a property calls `store.set()` (which
|
|
1170
|
+
* validates against the schema). The proxy also exposes `$store` for direct
|
|
1171
|
+
* store access and `$snapshot()` for untracked reads.
|
|
1172
|
+
*
|
|
1173
|
+
* @param store - The underlying facts store to wrap
|
|
1174
|
+
* @param schema - The schema definition used for `ownKeys` enumeration
|
|
1175
|
+
* @returns A {@link Facts} proxy with property-style get/set and prototype pollution guards
|
|
1176
|
+
*
|
|
1177
|
+
* @example
|
|
1178
|
+
* ```ts
|
|
1179
|
+
* const store = createFactsStore({ schema: { phase: t.string() } });
|
|
1180
|
+
* const facts = createFactsProxy(store, { phase: t.string() });
|
|
1181
|
+
*
|
|
1182
|
+
* facts.phase = "red";
|
|
1183
|
+
* console.log(facts.phase); // "red"
|
|
1184
|
+
* ```
|
|
1185
|
+
*
|
|
1186
|
+
* @internal
|
|
1187
|
+
*/
|
|
1188
|
+
declare function createFactsProxy<S extends Schema>(store: FactsStore<S>, schema: S): Facts<S>;
|
|
1189
|
+
/**
|
|
1190
|
+
* Convenience factory that creates both a {@link FactsStore} and its
|
|
1191
|
+
* {@link createFactsProxy | proxy wrapper} in a single call.
|
|
1192
|
+
*
|
|
1193
|
+
* @remarks
|
|
1194
|
+
* This is the recommended entry point when you need low-level store access
|
|
1195
|
+
* outside of `createModule` / `createSystem`.
|
|
1196
|
+
*
|
|
1197
|
+
* @param options - Same options as {@link createFactsStore}
|
|
1198
|
+
* @returns An object with `store` (the reactive Map-backed store) and `facts` (the Proxy accessor)
|
|
1199
|
+
*
|
|
1200
|
+
* @example
|
|
1201
|
+
* ```ts
|
|
1202
|
+
* const { store, facts } = createFacts({
|
|
1203
|
+
* schema: { phase: t.string<"red" | "green">() },
|
|
1204
|
+
* });
|
|
1205
|
+
*
|
|
1206
|
+
* facts.phase = "red";
|
|
1207
|
+
* console.log(facts.phase); // "red"
|
|
1208
|
+
* store.subscribe(["phase"], () => console.log("phase changed"));
|
|
1209
|
+
* ```
|
|
1210
|
+
*
|
|
1211
|
+
* @internal
|
|
1212
|
+
*/
|
|
1213
|
+
declare function createFacts<S extends Schema>(options: CreateFactsStoreOptions<S>): {
|
|
1214
|
+
store: FactsStore<S>;
|
|
1215
|
+
facts: Facts<S>;
|
|
1216
|
+
};
|
|
1217
|
+
|
|
1642
1218
|
/**
|
|
1643
1219
|
* Derivations - Auto-tracked computed values with composition
|
|
1644
1220
|
*
|
|
@@ -1669,6 +1245,12 @@ interface DerivationsManager<S extends Schema, D extends DerivationsDef<S>> {
|
|
|
1669
1245
|
getDependencies(id: keyof D): Set<string>;
|
|
1670
1246
|
/** Register new derivation definitions (for dynamic module registration) */
|
|
1671
1247
|
registerDefinitions(newDefs: DerivationsDef<S>): void;
|
|
1248
|
+
/** Override an existing derivation function */
|
|
1249
|
+
assignDefinition(id: string, fn: DerivationsDef<S>[keyof DerivationsDef<S>]): void;
|
|
1250
|
+
/** Remove a derivation and clean up its state */
|
|
1251
|
+
unregisterDefinition(id: string): void;
|
|
1252
|
+
/** Compute a derivation immediately (ignores cache) */
|
|
1253
|
+
callOne(id: string): unknown;
|
|
1672
1254
|
}
|
|
1673
1255
|
/** Options for creating a derivations manager */
|
|
1674
1256
|
interface CreateDerivationsOptions<S extends Schema, D extends DerivationsDef<S>> {
|
|
@@ -1792,6 +1374,26 @@ interface EffectsManager<_S extends Schema = Schema> {
|
|
|
1792
1374
|
* @param newDefs - New effect definitions to merge into the manager.
|
|
1793
1375
|
*/
|
|
1794
1376
|
registerDefinitions(newDefs: EffectsDef<Schema>): void;
|
|
1377
|
+
/**
|
|
1378
|
+
* Override an existing effect definition. Runs cleanup of the old effect first.
|
|
1379
|
+
*
|
|
1380
|
+
* @param id - The effect definition ID to override.
|
|
1381
|
+
* @param def - The new effect definition.
|
|
1382
|
+
* @throws If no effect with this ID exists.
|
|
1383
|
+
*/
|
|
1384
|
+
assignDefinition(id: string, def: EffectsDef<Schema>[string]): void;
|
|
1385
|
+
/**
|
|
1386
|
+
* Remove an effect definition. Runs cleanup (try-catch) and removes from state.
|
|
1387
|
+
*
|
|
1388
|
+
* @param id - The effect definition ID to remove.
|
|
1389
|
+
*/
|
|
1390
|
+
unregisterDefinition(id: string): void;
|
|
1391
|
+
/**
|
|
1392
|
+
* Execute an effect's `run()` function immediately.
|
|
1393
|
+
*
|
|
1394
|
+
* @param id - The effect definition ID.
|
|
1395
|
+
*/
|
|
1396
|
+
callOne(id: string): Promise<void>;
|
|
1795
1397
|
}
|
|
1796
1398
|
/**
|
|
1797
1399
|
* Configuration options accepted by {@link createEffectsManager}.
|
|
@@ -1963,6 +1565,30 @@ interface ConstraintsManager<_S extends Schema> {
|
|
|
1963
1565
|
* @param newDefs - New constraint definitions to merge into the manager.
|
|
1964
1566
|
*/
|
|
1965
1567
|
registerDefinitions(newDefs: ConstraintsDef<Schema>): void;
|
|
1568
|
+
/**
|
|
1569
|
+
* Override an existing constraint definition.
|
|
1570
|
+
* Stores the original in an internal map for inspection.
|
|
1571
|
+
*
|
|
1572
|
+
* @param id - The constraint definition ID to override.
|
|
1573
|
+
* @param def - The new constraint definition.
|
|
1574
|
+
* @throws If no constraint with this ID exists.
|
|
1575
|
+
*/
|
|
1576
|
+
assignDefinition(id: string, def: ConstraintsDef<Schema>[string]): void;
|
|
1577
|
+
/**
|
|
1578
|
+
* Remove a constraint definition and all its internal state.
|
|
1579
|
+
*
|
|
1580
|
+
* @param id - The constraint definition ID to remove.
|
|
1581
|
+
*/
|
|
1582
|
+
unregisterDefinition(id: string): void;
|
|
1583
|
+
/**
|
|
1584
|
+
* Evaluate a single constraint and emit its requirement if active.
|
|
1585
|
+
* Props are merged into the requirement object.
|
|
1586
|
+
*
|
|
1587
|
+
* @param id - The constraint definition ID.
|
|
1588
|
+
* @param props - Optional properties to merge into the requirement.
|
|
1589
|
+
* @returns The emitted requirements (if any).
|
|
1590
|
+
*/
|
|
1591
|
+
callOne(id: string, props?: Record<string, unknown>): Promise<RequirementWithId[]>;
|
|
1966
1592
|
}
|
|
1967
1593
|
/**
|
|
1968
1594
|
* Configuration options accepted by {@link createConstraintsManager}.
|
|
@@ -2124,6 +1750,31 @@ interface ResolversManager<_S extends Schema> {
|
|
|
2124
1750
|
* @param newDefs - New resolver definitions to merge into the manager.
|
|
2125
1751
|
*/
|
|
2126
1752
|
registerDefinitions(newDefs: ResolversDef<Schema>): void;
|
|
1753
|
+
/**
|
|
1754
|
+
* Override an existing resolver definition.
|
|
1755
|
+
*
|
|
1756
|
+
* @param id - The resolver definition ID to override.
|
|
1757
|
+
* @param def - The new resolver definition.
|
|
1758
|
+
* @throws If no resolver with this ID exists.
|
|
1759
|
+
*/
|
|
1760
|
+
assignDefinition(id: string, def: ResolversDef<Schema>[string]): void;
|
|
1761
|
+
/**
|
|
1762
|
+
* Remove a resolver definition. Cancels any inflight resolution.
|
|
1763
|
+
*
|
|
1764
|
+
* @param id - The resolver definition ID to remove.
|
|
1765
|
+
*/
|
|
1766
|
+
unregisterDefinition(id: string): void;
|
|
1767
|
+
/**
|
|
1768
|
+
* Execute a resolver with a given requirement object.
|
|
1769
|
+
*
|
|
1770
|
+
* @param id - The resolver definition ID.
|
|
1771
|
+
* @param requirement - The requirement to resolve.
|
|
1772
|
+
*/
|
|
1773
|
+
callOne(id: string, requirement: Requirement): Promise<void>;
|
|
1774
|
+
/**
|
|
1775
|
+
* Clean up all internal state. Called on system destroy.
|
|
1776
|
+
*/
|
|
1777
|
+
destroy(): void;
|
|
2127
1778
|
}
|
|
2128
1779
|
/**
|
|
2129
1780
|
* Configuration options accepted by {@link createResolversManager}.
|
|
@@ -2230,9 +1881,9 @@ declare function createResolversManager<S extends Schema>(options: CreateResolve
|
|
|
2230
1881
|
* - **Requirements:** `emitRequirementCreated`, `emitRequirementMet`, `emitRequirementCanceled`
|
|
2231
1882
|
* - **Resolvers:** `emitResolverStart`, `emitResolverComplete`, `emitResolverError`, `emitResolverRetry`, `emitResolverCancel`
|
|
2232
1883
|
* - **Effects:** `emitEffectRun`, `emitEffectError`
|
|
2233
|
-
* - **
|
|
1884
|
+
* - **History:** `emitSnapshot`, `emitHistoryNavigate`
|
|
2234
1885
|
* - **Errors:** `emitError`, `emitErrorRecovery`
|
|
2235
|
-
* - **
|
|
1886
|
+
* - **Trace:** `emitTraceComplete`
|
|
2236
1887
|
*
|
|
2237
1888
|
* @typeParam _S - The flat schema type (unused at runtime).
|
|
2238
1889
|
*
|
|
@@ -2269,10 +1920,14 @@ interface PluginManager<_S extends Schema = any> {
|
|
|
2269
1920
|
emitEffectRun(id: string): void;
|
|
2270
1921
|
emitEffectError(id: string, error: unknown): void;
|
|
2271
1922
|
emitSnapshot(snapshot: Snapshot): void;
|
|
2272
|
-
|
|
1923
|
+
emitHistoryNavigate(from: number, to: number): void;
|
|
2273
1924
|
emitError(error: DirectiveError): void;
|
|
2274
1925
|
emitErrorRecovery(error: DirectiveError, strategy: RecoveryStrategy): void;
|
|
2275
|
-
|
|
1926
|
+
emitDefinitionRegister(type: string, id: string, def: unknown): void;
|
|
1927
|
+
emitDefinitionAssign(type: string, id: string, def: unknown, original: unknown): void;
|
|
1928
|
+
emitDefinitionUnregister(type: string, id: string): void;
|
|
1929
|
+
emitDefinitionCall(type: string, id: string, props?: unknown): void;
|
|
1930
|
+
emitTraceComplete(run: TraceEntry): void;
|
|
2276
1931
|
}
|
|
2277
1932
|
/**
|
|
2278
1933
|
* Create a {@link PluginManager} that broadcasts lifecycle events to registered plugins.
|
|
@@ -2430,7 +2085,7 @@ interface CreateErrorBoundaryOptions {
|
|
|
2430
2085
|
declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions): ErrorBoundaryManager;
|
|
2431
2086
|
|
|
2432
2087
|
/**
|
|
2433
|
-
*
|
|
2088
|
+
* History — Snapshot-based state history
|
|
2434
2089
|
*
|
|
2435
2090
|
* Features:
|
|
2436
2091
|
* - Ring buffer of state snapshots
|
|
@@ -2440,7 +2095,7 @@ declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions
|
|
|
2440
2095
|
*/
|
|
2441
2096
|
|
|
2442
2097
|
/**
|
|
2443
|
-
* Internal
|
|
2098
|
+
* Internal history manager that extends the public {@link HistoryAPI}
|
|
2444
2099
|
* with snapshot capture, restoration, and pause/resume controls.
|
|
2445
2100
|
*
|
|
2446
2101
|
* @remarks
|
|
@@ -2456,12 +2111,12 @@ declare function createErrorBoundaryManager(options?: CreateErrorBoundaryOptions
|
|
|
2456
2111
|
*
|
|
2457
2112
|
* @internal
|
|
2458
2113
|
*/
|
|
2459
|
-
interface
|
|
2114
|
+
interface HistoryManager<_S extends Schema> extends HistoryAPI {
|
|
2460
2115
|
/** Take a snapshot of current state */
|
|
2461
2116
|
takeSnapshot(trigger: string): Snapshot;
|
|
2462
2117
|
/** Restore facts from a snapshot */
|
|
2463
2118
|
restore(snapshot: Snapshot): void;
|
|
2464
|
-
/** Check if
|
|
2119
|
+
/** Check if history is enabled */
|
|
2465
2120
|
readonly isEnabled: boolean;
|
|
2466
2121
|
/** True while restoring a snapshot (engine should skip reconciliation) */
|
|
2467
2122
|
readonly isRestoring: boolean;
|
|
@@ -2471,23 +2126,23 @@ interface TimeTravelManager<_S extends Schema> extends TimeTravelAPI {
|
|
|
2471
2126
|
resume(): void;
|
|
2472
2127
|
}
|
|
2473
2128
|
/**
|
|
2474
|
-
* Options for creating a
|
|
2129
|
+
* Options for creating a history manager via {@link createHistoryManager}.
|
|
2475
2130
|
*
|
|
2476
2131
|
* @typeParam S - The facts schema type.
|
|
2477
2132
|
*
|
|
2478
2133
|
* @internal
|
|
2479
2134
|
*/
|
|
2480
|
-
interface
|
|
2481
|
-
|
|
2135
|
+
interface CreateHistoryOptions<S extends Schema> {
|
|
2136
|
+
historyOption: HistoryOption;
|
|
2482
2137
|
facts: Facts<S>;
|
|
2483
2138
|
store: FactsStore<S>;
|
|
2484
2139
|
/** Callback when a snapshot is taken */
|
|
2485
2140
|
onSnapshot?: (snapshot: Snapshot) => void;
|
|
2486
|
-
/** Callback when
|
|
2487
|
-
|
|
2141
|
+
/** Callback when history navigation occurs */
|
|
2142
|
+
onHistoryChange?: (from: number, to: number) => void;
|
|
2488
2143
|
}
|
|
2489
2144
|
/**
|
|
2490
|
-
* Create a snapshot-based
|
|
2145
|
+
* Create a snapshot-based history manager backed by a ring buffer.
|
|
2491
2146
|
*
|
|
2492
2147
|
* @remarks
|
|
2493
2148
|
* Snapshots are taken automatically after fact changes (during reconciliation)
|
|
@@ -2499,25 +2154,25 @@ interface CreateTimeTravelOptions<S extends Schema> {
|
|
|
2499
2154
|
* Call `pause()` to temporarily stop recording snapshots (e.g., during bulk
|
|
2500
2155
|
* fact imports) and `resume()` to re-enable recording.
|
|
2501
2156
|
*
|
|
2502
|
-
* @param options -
|
|
2503
|
-
* @returns A {@link
|
|
2157
|
+
* @param options - History config, facts proxy, store, and optional snapshot/history callbacks.
|
|
2158
|
+
* @returns A {@link HistoryManager} with snapshot capture, navigation, changeset, and export/import methods.
|
|
2504
2159
|
*
|
|
2505
2160
|
* @internal
|
|
2506
2161
|
*/
|
|
2507
|
-
declare function
|
|
2162
|
+
declare function createHistoryManager<S extends Schema>(options: CreateHistoryOptions<S>): HistoryManager<S>;
|
|
2508
2163
|
/**
|
|
2509
|
-
* Create a no-op
|
|
2164
|
+
* Create a no-op history manager for use when history is disabled.
|
|
2510
2165
|
*
|
|
2511
2166
|
* @remarks
|
|
2512
2167
|
* All methods are safe to call but perform no work. This avoids null-checks
|
|
2513
|
-
* throughout the engine -- callers can use the same {@link
|
|
2514
|
-
* interface regardless of whether
|
|
2168
|
+
* throughout the engine -- callers can use the same {@link HistoryManager}
|
|
2169
|
+
* interface regardless of whether history is enabled.
|
|
2515
2170
|
*
|
|
2516
|
-
* @returns A {@link
|
|
2171
|
+
* @returns A {@link HistoryManager} where every method is a no-op and `isEnabled` is `false`.
|
|
2517
2172
|
*
|
|
2518
2173
|
* @internal
|
|
2519
2174
|
*/
|
|
2520
|
-
declare function
|
|
2175
|
+
declare function createDisabledHistory<S extends Schema>(): HistoryManager<S>;
|
|
2521
2176
|
|
|
2522
2177
|
/**
|
|
2523
2178
|
* Engine - The core reconciliation loop
|
|
@@ -2532,7 +2187,7 @@ declare function createDisabledTimeTravel<S extends Schema>(): TimeTravelManager
|
|
|
2532
2187
|
|
|
2533
2188
|
/**
|
|
2534
2189
|
* Create the core Directive reconciliation engine that wires facts, derivations,
|
|
2535
|
-
* effects, constraints, resolvers, plugins, error boundaries, and
|
|
2190
|
+
* effects, constraints, resolvers, plugins, error boundaries, and history
|
|
2536
2191
|
* into a single reactive system.
|
|
2537
2192
|
*
|
|
2538
2193
|
* @remarks
|
|
@@ -2640,4 +2295,4 @@ declare const Backoff: {
|
|
|
2640
2295
|
readonly Exponential: "exponential";
|
|
2641
2296
|
};
|
|
2642
2297
|
|
|
2643
|
-
export { Backoff, BatchConfig, type Branded, type ChainableSchemaType,
|
|
2298
|
+
export { Backoff, BatchConfig, type Branded, type ChainableSchemaType, ConstraintState, ConstraintsDef, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleConstraintsDef, CrossModuleDeps, CrossModuleDerivationsDef, CrossModuleEffectsDef, type DerivationState, type DerivationsDef, type DerivedValues, DirectiveError, EffectsDef, ErrorBoundaryConfig, ErrorSource, type ExtendedSchemaType, FactChange, Facts, FactsSnapshot, FactsStore, HistoryAPI, HistoryOption, type InflightInfo, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, type PendingRetry, Plugin, ReconcileResult, RecoveryStrategy, Requirement, RequirementKeyFn, RequirementSet, type RequirementTypeStatus, RequirementWithId, ResolverContext, ResolverStatus, ResolversDef, RetryLaterConfig, RetryPolicy, Schema, SchemaType, SingleModuleSystem, Snapshot, System, SystemConfig, TraceEntry, TraceOption, type TypedConstraint, TypedConstraintsDef, TypedDerivationsDef, TypedEventsDef, type TypedResolver, TypedResolversDef, createConstraintFactory, createConstraintsManager, createDerivationsManager, createDisabledHistory, createEffectsManager, createEngine, createErrorBoundaryManager, createFacts, createFactsProxy, createFactsStore, createHistoryManager, createModule, createModuleFactory, createPluginManager, createRequirementStatusPlugin, createResolverFactory, createResolversManager, createRetryLaterManager, createStatusHook, createSystem, createSystemWithStatus, forType, generateRequirementId, getCurrentTracker, isRequirementType, isTracking, req, t, trackAccess, typedConstraint, typedResolver, withTracking, withoutTracking };
|