@context-action/store-core 0.1.3 → 0.1.4

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/CHANGELOG.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # Change Log
2
2
 
3
+ ## [0.1.4] (2026-11-19)
4
+
5
+ - Export `createStateStore`, `StateStore<T>`, `StateStoreOptions`, optional `getValue?()` on `StateReader`, optional-version `StateSnapshot`, `ReadonlyStateSnapshot<T>`, and `TransactionBatchControl` / participant contracts while remaining 100% framework-neutral and zero-dependency.
6
+
3
7
  ## [0.1.3] (2026-10-02)
4
8
 
5
9
  - Reissue the framework-neutral backend contract in the coordinated stability cohort.
package/README.md CHANGED
@@ -15,3 +15,37 @@ backend exposes that capability.
15
15
  notification hold. Pair it with `resumeNotifications()` and then call
16
16
  `flushNotifications()` when the surrounding integration is ready to publish the
17
17
  coalesced transition.
18
+
19
+ `TransactionBatchControl` describes only that lifecycle authority. It is also
20
+ inherited by `TransactionBackend`, so existing backend implementations keep the
21
+ same methods. A coordinator may use an operation-scoped control for admission,
22
+ commit, rollback and publication while retaining the original backend identity
23
+ for conflict detection and later undo/redo. The type alone does not isolate
24
+ writers; a backend must enforce its scoped authority.
25
+
26
+ ## Ownership and coordination are different roles
27
+
28
+ | Contract | Responsibility |
29
+ | --- | --- |
30
+ | `StateSnapshot<T>` | Readonly observation shape; legacy Stores may omit `version` |
31
+ | `ReadonlyStateSnapshot<T>` | Backend snapshot with required monotonic `version` |
32
+ | `StateReader<T>` / `StateBackend<T>` | Strict versioned observation (with optional `getValue?(): T`) / state ownership |
33
+ | `StateStore<T>` | Synchronous `StateBackend<T>` extension with required `getValue(): T`, returned by `createStateStore(name, initialValue, options?)` |
34
+ | `TransactionParticipantBackend<T>` | Observation, retained-entry navigation, batch lifecycle and disposal status; no state writer or materialized history required |
35
+ | `TransactionParticipant<T>` | Stable backend identity plus optional operation-scoped `batchControl` |
36
+ | `TransactionCoordinatorPort` | `begin(participants, options)` returning a `TransactionHandle` with metadata, commit and rollback |
37
+
38
+ `TransactionMeta` and `TransactionOptions` define the shared correlation fields.
39
+ They do not inherit `StateMutationMeta`'s arbitrary metadata index signature.
40
+ `TransactionBackend` remains the full state-owning timeline plus batch capability;
41
+ it is not renamed or weakened to match the minimal participant role.
42
+
43
+ The optional second parameter of `StateReader<T, Snapshot>` selects an observation
44
+ shape explicitly. Its default, and `StateBackend`'s contract, still require a
45
+ versioned snapshot. These are type-only protocols, not runtime isolation or
46
+ distributed transaction implementations. Their definitions live in
47
+ `src/contracts.ts` and `src/transaction-contracts.ts`; the public import remains
48
+ `@context-action/store-core`, with no new private-path imports or runtime dependencies.
49
+
50
+ For XState (`ActorRefLike` projection onto `StateReader`) and Effect `TransactionCoordinatorPort`
51
+ scoped adapters, use `@context-action/xstate` and `@context-action/xstate/effect`.
package/dist/index.cjs CHANGED
@@ -42,6 +42,7 @@ function createStateStore(name, initialValue, options = {}) {
42
42
  immutableSnapshots: false
43
43
  },
44
44
  getSnapshot: () => snapshot,
45
+ getValue: () => snapshot.value,
45
46
  subscribe(listener) {
46
47
  if (typeof listener !== "function") throw new TypeError("Store subscriber must be a function.");
47
48
  if (disposed) return () => {};
package/dist/index.d.cts CHANGED
@@ -1,35 +1,39 @@
1
- //#region src/index.d.ts
2
- export type StateMutationOrigin = 'user' | 'system' | 'network' | 'undo' | 'redo' | 'reset';
3
- export interface StateMutationMeta {
1
+ //#region src/contracts.d.ts
2
+ type StateMutationOrigin = 'user' | 'system' | 'network' | 'undo' | 'redo' | 'reset';
3
+ interface StateMutationMeta {
4
4
  readonly transactionId?: string;
5
5
  readonly actionId?: string;
6
6
  readonly origin?: StateMutationOrigin;
7
7
  readonly label?: string;
8
8
  readonly [key: string]: unknown;
9
9
  }
10
- export interface StatePatch {
10
+ interface StatePatch {
11
11
  readonly op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
12
12
  readonly path: readonly unknown[];
13
13
  readonly from?: readonly unknown[];
14
14
  readonly value?: unknown;
15
15
  }
16
- export type HistoryEntryId = string | number;
17
- export interface ReadonlyStateSnapshot<T> {
16
+ type HistoryEntryId = string | number;
17
+ interface StateSnapshot<T> {
18
18
  readonly value: T;
19
19
  readonly name: string;
20
- readonly version: number;
20
+ readonly version?: number;
21
21
  readonly lastUpdate: number;
22
22
  }
23
- export interface StateReader<T> {
23
+ interface ReadonlyStateSnapshot<T> extends StateSnapshot<T> {
24
+ readonly version: number;
25
+ }
26
+ interface StateReader<T, Snapshot extends StateSnapshot<T> = ReadonlyStateSnapshot<T>> {
24
27
  readonly name: string;
25
- getSnapshot(): ReadonlyStateSnapshot<T>;
28
+ getSnapshot(): Snapshot;
29
+ getValue?(): T;
26
30
  subscribe(listener: () => void): () => void;
27
31
  }
28
- export interface StateWriter<T> {
32
+ interface StateWriter<T> {
29
33
  setValue(value: T, meta?: StateMutationMeta): void;
30
34
  update(updater: (current: T) => T | undefined, meta?: StateMutationMeta): void;
31
35
  }
32
- export interface StateBackend<T, Patch = StatePatch> extends StateReader<T>, StateWriter<T> {
36
+ interface StateBackend<T, Patch = StatePatch> extends StateReader<T>, StateWriter<T> {
33
37
  readonly capabilities?: {
34
38
  readonly patches?: boolean;
35
39
  readonly timeline?: boolean;
@@ -41,7 +45,10 @@ export interface StateBackend<T, Patch = StatePatch> extends StateReader<T>, Sta
41
45
  isDisposed?(): boolean;
42
46
  subscribeWithPatches?(listener: (patches: readonly Patch[] | null) => void): () => void;
43
47
  }
44
- export interface TimelineBackend<T, Patch = StatePatch> extends StateBackend<T, Patch> {
48
+ interface StateStore<T, Patch = StatePatch> extends StateBackend<T, Patch> {
49
+ getValue(): T;
50
+ }
51
+ interface TimelineBackend<T, Patch = StatePatch> extends StateBackend<T, Patch> {
45
52
  getHistoryEntryId(): HistoryEntryId;
46
53
  hasHistoryEntry(entryId: HistoryEntryId): boolean;
47
54
  canUndo(): boolean;
@@ -55,7 +62,7 @@ export interface TimelineBackend<T, Patch = StatePatch> extends StateBackend<T,
55
62
  goToHistoryEntry(entryId: HistoryEntryId, meta?: StateMutationMeta): void;
56
63
  reset(meta?: StateMutationMeta): void;
57
64
  }
58
- export interface TransactionBackend<T, Patch = StatePatch> extends TimelineBackend<T, Patch> {
65
+ interface TransactionBatchControl {
59
66
  beginBatch(meta?: StateMutationMeta, options?: {
60
67
  readonly deferNotification?: boolean;
61
68
  }): void;
@@ -63,17 +70,42 @@ export interface TransactionBackend<T, Patch = StatePatch> extends TimelineBacke
63
70
  cancelBatch(): void;
64
71
  resumeNotifications(): void;
65
72
  flushNotifications(): void;
73
+ }
74
+ interface TransactionBackend<T, Patch = StatePatch> extends TimelineBackend<T, Patch>, TransactionBatchControl {
66
75
  isStoreDisposed(): boolean;
67
76
  }
68
- export interface StateTransition<T> {
77
+ interface StateTransition<T> {
69
78
  readonly previous: T;
70
79
  readonly next: T;
71
80
  readonly meta: StateMutationMeta;
72
81
  readonly position?: number;
73
82
  }
83
+ //#endregion
84
+ //#region src/transaction-contracts.d.ts
85
+ interface TransactionParticipantBackend<T = unknown> extends StateReader<T, StateSnapshot<T>>, Pick<TransactionBackend<T>, 'getHistoryEntryId' | 'hasHistoryEntry' | 'canUndo' | 'canRedo' | 'getPosition' | 'getHistoryLength' | 'goToHistoryEntry' | 'isStoreDisposed'>, TransactionBatchControl {}
86
+ interface TransactionMeta extends Pick<StateMutationMeta, 'transactionId' | 'actionId' | 'label' | 'origin'> {
87
+ readonly id: string;
88
+ }
89
+ type TransactionOptions = Omit<TransactionMeta, 'id'>;
90
+ interface TransactionParticipant<T = unknown> {
91
+ readonly name: string;
92
+ readonly store: TransactionParticipantBackend<T>;
93
+ readonly batchControl?: TransactionBatchControl;
94
+ }
95
+ interface TransactionHandle {
96
+ readonly meta: TransactionMeta;
97
+ commit(): void;
98
+ rollback(): void;
99
+ }
100
+ interface TransactionCoordinatorPort {
101
+ begin(participants: readonly TransactionParticipant[], options?: TransactionOptions): TransactionHandle;
102
+ }
103
+ //#endregion
104
+ //#region src/index.d.ts
74
105
  export interface StateStoreOptions {
75
106
  readonly now?: () => number;
76
107
  }
77
- export declare function createStateStore<T>(name: string, initialValue: T, options?: StateStoreOptions): StateBackend<T>;
108
+ export declare function createStateStore<T>(name: string, initialValue: T, options?: StateStoreOptions): StateStore<T>;
78
109
  //#endregion
110
+ export type { HistoryEntryId, ReadonlyStateSnapshot, StateBackend, StateMutationMeta, StateMutationOrigin, StatePatch, StateReader, StateSnapshot, StateStore, StateTransition, StateWriter, TimelineBackend, TransactionBackend, TransactionBatchControl, TransactionCoordinatorPort, TransactionHandle, TransactionMeta, TransactionOptions, TransactionParticipant, TransactionParticipantBackend };
79
111
  //# sourceMappingURL=index.d.cts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.cts","names":[],"sources":["../src/index.ts"],"mappings":";YAQY;iBAGK;WACN;WACA;WACA,SAAS;WACT;YACC;;iBAIK;WACN;WACA;WACA;WACA;;YAGC;iBAEK,sBAAsB;WAC5B,OAAO;WACP;WAEA;WACA;;iBAGM,YAAY;WAClB;EACT,eAAe,sBAAsB;EACrC,UAAU;;iBAGK,YAAY;EAE3B,SAAS,OAAO,GAAG,OAAO;EAE1B,OAAO,UAAU,SAAS,MAAM,eAAe,OAAO;;iBAGvC,aAAa,GAAG,QAAQ,oBAAoB,YAAY,IAAI,YAAY;WAC9E;aACE;aACA;aACA;;EAEX,4BAA4B;EAE5B,iBAAiB;EAEjB;EACA;EACA,sBAAsB,WAAW,kBAAkB;;iBAGpC,gBAAgB,GAAG,QAAQ,oBAAoB,aAAa,GAAG;EAC9E,qBAAqB;EACrB,gBAAgB,SAAS;EACzB;EACA;EACA;EACA,uBAAuB;EACvB;EACA,KAAK,gBAAgB,OAAO;EAC5B,KAAK,gBAAgB,OAAO;EAC5B,KAAK,kBAAkB,OAAO;EAC9B,iBAAiB,SAAS,gBAAgB,OAAO;EACjD,MAAM,OAAO;;iBAGE,mBAAmB,GAAG,QAAQ,oBAAoB,gBAAgB,GAAG;EACpF,WAAW,OAAO,mBAAmB;aAAqB;;EAC1D;EACA;EACA;EACA;EACA;;iBAGe,gBAAgB;WACtB,UAAU;WACV,MAAM;WACN,MAAM;WACN;;iBAGM;WACN;;wBAOK,iBAAiB,GAC/B,cACA,cAAc,GACd,UAAS,oBACR,aAAa"}
1
+ {"version":3,"file":"index.d.cts","names":[],"sources":["../src/contracts.ts","../src/transaction-contracts.ts","../src/index.ts"],"mappings":";KACY;UAGK;WACN;WACA;WACA,SAAS;WACT;YACC;;UAIK;WACN;WACA;WACA;WACA;;KAGC;UAGK,cAAc;WACpB,OAAO;WACP;WACA;WACA;;UAIM,sBAAsB,WAAW,cAAc;WACrD;;UAGM,YAAY,GAAG,iBAAiB,cAAc,KAAK,sBAAsB;WAC/E;EACT,eAAe;EACf,aAAa;EACb,UAAU;;UAGK,YAAY;EAE3B,SAAS,OAAO,GAAG,OAAO;EAE1B,OAAO,UAAU,SAAS,MAAM,eAAe,OAAO;;UAGvC,aAAa,GAAG,QAAQ,oBAAoB,YAAY,IAAI,YAAY;WAC9E;aACE;aACA;aACA;;EAEX,4BAA4B;EAE5B,iBAAiB;EAEjB;EACA;EACA,sBAAsB,WAAW,kBAAkB;;UAGpC,WAAW,GAAG,QAAQ,oBAAoB,aAAa,GAAG;EACzE,YAAY;;UAGG,gBAAgB,GAAG,QAAQ,oBAAoB,aAAa,GAAG;EAC9E,qBAAqB;EACrB,gBAAgB,SAAS;EACzB;EACA;EACA;EACA,uBAAuB;EACvB;EACA,KAAK,gBAAgB,OAAO;EAC5B,KAAK,gBAAgB,OAAO;EAC5B,KAAK,kBAAkB,OAAO;EAC9B,iBAAiB,SAAS,gBAAgB,OAAO;EACjD,MAAM,OAAO;;UAIE;EACf,WAAW,OAAO,mBAAmB;aAAqB;;EAC1D;EACA;EACA;EACA;;UAGe,mBAAmB,GAAG,QAAQ,oBAAoB,gBAAgB,GAAG,QAAQ;EAC5F;;UAGe,gBAAgB;WACtB,UAAU;WACV,MAAM;WACN,MAAM;WACN;;;;UCvFM,8BAA8B,qBAC7C,YAAY,GAAG,cAAc,KAC7B,KAAK,mBAAmB,oJAGxB;UAGe,wBAAwB,KAAK;WACnC;;KAGC,qBAAqB,KAAK;UAErB,uBAAuB;WAC7B;WACA,OAAO,8BAA8B;WAErC,eAAe;;UAGT;WACN,MAAM;EACf;EACA;;UAIe;EACf,MAAM,uBAAuB,0BAA0B,UAAU,qBAAqB;;;;iBCvBvE;WACN;;wBAOK,iBAAiB,GAC/B,cACA,cAAc,GACd,UAAS,oBACR,WAAW"}
package/dist/index.d.ts CHANGED
@@ -1,35 +1,39 @@
1
- //#region src/index.d.ts
2
- export type StateMutationOrigin = 'user' | 'system' | 'network' | 'undo' | 'redo' | 'reset';
3
- export interface StateMutationMeta {
1
+ //#region src/contracts.d.ts
2
+ type StateMutationOrigin = 'user' | 'system' | 'network' | 'undo' | 'redo' | 'reset';
3
+ interface StateMutationMeta {
4
4
  readonly transactionId?: string;
5
5
  readonly actionId?: string;
6
6
  readonly origin?: StateMutationOrigin;
7
7
  readonly label?: string;
8
8
  readonly [key: string]: unknown;
9
9
  }
10
- export interface StatePatch {
10
+ interface StatePatch {
11
11
  readonly op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
12
12
  readonly path: readonly unknown[];
13
13
  readonly from?: readonly unknown[];
14
14
  readonly value?: unknown;
15
15
  }
16
- export type HistoryEntryId = string | number;
17
- export interface ReadonlyStateSnapshot<T> {
16
+ type HistoryEntryId = string | number;
17
+ interface StateSnapshot<T> {
18
18
  readonly value: T;
19
19
  readonly name: string;
20
- readonly version: number;
20
+ readonly version?: number;
21
21
  readonly lastUpdate: number;
22
22
  }
23
- export interface StateReader<T> {
23
+ interface ReadonlyStateSnapshot<T> extends StateSnapshot<T> {
24
+ readonly version: number;
25
+ }
26
+ interface StateReader<T, Snapshot extends StateSnapshot<T> = ReadonlyStateSnapshot<T>> {
24
27
  readonly name: string;
25
- getSnapshot(): ReadonlyStateSnapshot<T>;
28
+ getSnapshot(): Snapshot;
29
+ getValue?(): T;
26
30
  subscribe(listener: () => void): () => void;
27
31
  }
28
- export interface StateWriter<T> {
32
+ interface StateWriter<T> {
29
33
  setValue(value: T, meta?: StateMutationMeta): void;
30
34
  update(updater: (current: T) => T | undefined, meta?: StateMutationMeta): void;
31
35
  }
32
- export interface StateBackend<T, Patch = StatePatch> extends StateReader<T>, StateWriter<T> {
36
+ interface StateBackend<T, Patch = StatePatch> extends StateReader<T>, StateWriter<T> {
33
37
  readonly capabilities?: {
34
38
  readonly patches?: boolean;
35
39
  readonly timeline?: boolean;
@@ -41,7 +45,10 @@ export interface StateBackend<T, Patch = StatePatch> extends StateReader<T>, Sta
41
45
  isDisposed?(): boolean;
42
46
  subscribeWithPatches?(listener: (patches: readonly Patch[] | null) => void): () => void;
43
47
  }
44
- export interface TimelineBackend<T, Patch = StatePatch> extends StateBackend<T, Patch> {
48
+ interface StateStore<T, Patch = StatePatch> extends StateBackend<T, Patch> {
49
+ getValue(): T;
50
+ }
51
+ interface TimelineBackend<T, Patch = StatePatch> extends StateBackend<T, Patch> {
45
52
  getHistoryEntryId(): HistoryEntryId;
46
53
  hasHistoryEntry(entryId: HistoryEntryId): boolean;
47
54
  canUndo(): boolean;
@@ -55,7 +62,7 @@ export interface TimelineBackend<T, Patch = StatePatch> extends StateBackend<T,
55
62
  goToHistoryEntry(entryId: HistoryEntryId, meta?: StateMutationMeta): void;
56
63
  reset(meta?: StateMutationMeta): void;
57
64
  }
58
- export interface TransactionBackend<T, Patch = StatePatch> extends TimelineBackend<T, Patch> {
65
+ interface TransactionBatchControl {
59
66
  beginBatch(meta?: StateMutationMeta, options?: {
60
67
  readonly deferNotification?: boolean;
61
68
  }): void;
@@ -63,17 +70,42 @@ export interface TransactionBackend<T, Patch = StatePatch> extends TimelineBacke
63
70
  cancelBatch(): void;
64
71
  resumeNotifications(): void;
65
72
  flushNotifications(): void;
73
+ }
74
+ interface TransactionBackend<T, Patch = StatePatch> extends TimelineBackend<T, Patch>, TransactionBatchControl {
66
75
  isStoreDisposed(): boolean;
67
76
  }
68
- export interface StateTransition<T> {
77
+ interface StateTransition<T> {
69
78
  readonly previous: T;
70
79
  readonly next: T;
71
80
  readonly meta: StateMutationMeta;
72
81
  readonly position?: number;
73
82
  }
83
+ //#endregion
84
+ //#region src/transaction-contracts.d.ts
85
+ interface TransactionParticipantBackend<T = unknown> extends StateReader<T, StateSnapshot<T>>, Pick<TransactionBackend<T>, 'getHistoryEntryId' | 'hasHistoryEntry' | 'canUndo' | 'canRedo' | 'getPosition' | 'getHistoryLength' | 'goToHistoryEntry' | 'isStoreDisposed'>, TransactionBatchControl {}
86
+ interface TransactionMeta extends Pick<StateMutationMeta, 'transactionId' | 'actionId' | 'label' | 'origin'> {
87
+ readonly id: string;
88
+ }
89
+ type TransactionOptions = Omit<TransactionMeta, 'id'>;
90
+ interface TransactionParticipant<T = unknown> {
91
+ readonly name: string;
92
+ readonly store: TransactionParticipantBackend<T>;
93
+ readonly batchControl?: TransactionBatchControl;
94
+ }
95
+ interface TransactionHandle {
96
+ readonly meta: TransactionMeta;
97
+ commit(): void;
98
+ rollback(): void;
99
+ }
100
+ interface TransactionCoordinatorPort {
101
+ begin(participants: readonly TransactionParticipant[], options?: TransactionOptions): TransactionHandle;
102
+ }
103
+ //#endregion
104
+ //#region src/index.d.ts
74
105
  export interface StateStoreOptions {
75
106
  readonly now?: () => number;
76
107
  }
77
- export declare function createStateStore<T>(name: string, initialValue: T, options?: StateStoreOptions): StateBackend<T>;
108
+ export declare function createStateStore<T>(name: string, initialValue: T, options?: StateStoreOptions): StateStore<T>;
78
109
  //#endregion
110
+ export type { HistoryEntryId, ReadonlyStateSnapshot, StateBackend, StateMutationMeta, StateMutationOrigin, StatePatch, StateReader, StateSnapshot, StateStore, StateTransition, StateWriter, TimelineBackend, TransactionBackend, TransactionBatchControl, TransactionCoordinatorPort, TransactionHandle, TransactionMeta, TransactionOptions, TransactionParticipant, TransactionParticipantBackend };
79
111
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";YAQY;iBAGK;WACN;WACA;WACA,SAAS;WACT;YACC;;iBAIK;WACN;WACA;WACA;WACA;;YAGC;iBAEK,sBAAsB;WAC5B,OAAO;WACP;WAEA;WACA;;iBAGM,YAAY;WAClB;EACT,eAAe,sBAAsB;EACrC,UAAU;;iBAGK,YAAY;EAE3B,SAAS,OAAO,GAAG,OAAO;EAE1B,OAAO,UAAU,SAAS,MAAM,eAAe,OAAO;;iBAGvC,aAAa,GAAG,QAAQ,oBAAoB,YAAY,IAAI,YAAY;WAC9E;aACE;aACA;aACA;;EAEX,4BAA4B;EAE5B,iBAAiB;EAEjB;EACA;EACA,sBAAsB,WAAW,kBAAkB;;iBAGpC,gBAAgB,GAAG,QAAQ,oBAAoB,aAAa,GAAG;EAC9E,qBAAqB;EACrB,gBAAgB,SAAS;EACzB;EACA;EACA;EACA,uBAAuB;EACvB;EACA,KAAK,gBAAgB,OAAO;EAC5B,KAAK,gBAAgB,OAAO;EAC5B,KAAK,kBAAkB,OAAO;EAC9B,iBAAiB,SAAS,gBAAgB,OAAO;EACjD,MAAM,OAAO;;iBAGE,mBAAmB,GAAG,QAAQ,oBAAoB,gBAAgB,GAAG;EACpF,WAAW,OAAO,mBAAmB;aAAqB;;EAC1D;EACA;EACA;EACA;EACA;;iBAGe,gBAAgB;WACtB,UAAU;WACV,MAAM;WACN,MAAM;WACN;;iBAGM;WACN;;wBAOK,iBAAiB,GAC/B,cACA,cAAc,GACd,UAAS,oBACR,aAAa"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/contracts.ts","../src/transaction-contracts.ts","../src/index.ts"],"mappings":";KACY;UAGK;WACN;WACA;WACA,SAAS;WACT;YACC;;UAIK;WACN;WACA;WACA;WACA;;KAGC;UAGK,cAAc;WACpB,OAAO;WACP;WACA;WACA;;UAIM,sBAAsB,WAAW,cAAc;WACrD;;UAGM,YAAY,GAAG,iBAAiB,cAAc,KAAK,sBAAsB;WAC/E;EACT,eAAe;EACf,aAAa;EACb,UAAU;;UAGK,YAAY;EAE3B,SAAS,OAAO,GAAG,OAAO;EAE1B,OAAO,UAAU,SAAS,MAAM,eAAe,OAAO;;UAGvC,aAAa,GAAG,QAAQ,oBAAoB,YAAY,IAAI,YAAY;WAC9E;aACE;aACA;aACA;;EAEX,4BAA4B;EAE5B,iBAAiB;EAEjB;EACA;EACA,sBAAsB,WAAW,kBAAkB;;UAGpC,WAAW,GAAG,QAAQ,oBAAoB,aAAa,GAAG;EACzE,YAAY;;UAGG,gBAAgB,GAAG,QAAQ,oBAAoB,aAAa,GAAG;EAC9E,qBAAqB;EACrB,gBAAgB,SAAS;EACzB;EACA;EACA;EACA,uBAAuB;EACvB;EACA,KAAK,gBAAgB,OAAO;EAC5B,KAAK,gBAAgB,OAAO;EAC5B,KAAK,kBAAkB,OAAO;EAC9B,iBAAiB,SAAS,gBAAgB,OAAO;EACjD,MAAM,OAAO;;UAIE;EACf,WAAW,OAAO,mBAAmB;aAAqB;;EAC1D;EACA;EACA;EACA;;UAGe,mBAAmB,GAAG,QAAQ,oBAAoB,gBAAgB,GAAG,QAAQ;EAC5F;;UAGe,gBAAgB;WACtB,UAAU;WACV,MAAM;WACN,MAAM;WACN;;;;UCvFM,8BAA8B,qBAC7C,YAAY,GAAG,cAAc,KAC7B,KAAK,mBAAmB,oJAGxB;UAGe,wBAAwB,KAAK;WACnC;;KAGC,qBAAqB,KAAK;UAErB,uBAAuB;WAC7B;WACA,OAAO,8BAA8B;WAErC,eAAe;;UAGT;WACN,MAAM;EACf;EACA;;UAIe;EACf,MAAM,uBAAuB,0BAA0B,UAAU,qBAAqB;;;;iBCvBvE;WACN;;wBAOK,iBAAiB,GAC/B,cACA,cAAc,GACd,UAAS,oBACR,WAAW"}
package/dist/index.js CHANGED
@@ -41,6 +41,7 @@ function createStateStore(name, initialValue, options = {}) {
41
41
  immutableSnapshots: false
42
42
  },
43
43
  getSnapshot: () => snapshot,
44
+ getValue: () => snapshot.value,
44
45
  subscribe(listener) {
45
46
  if (typeof listener !== "function") throw new TypeError("Store subscriber must be a function.");
46
47
  if (disposed) return () => {};
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Framework-neutral state contracts and a deliberately small reference store.\n *\n * This package owns no immutable-update, draft, clone, React, or DOM runtime.\n * A backend owns its value semantics; consumers must only rely on the\n * snapshot/subscription and capability contracts below.\n */\n\nexport type StateMutationOrigin = 'user' | 'system' | 'network' | 'undo' | 'redo' | 'reset';\n\n/** Metadata is extensible so adapters can preserve their own correlation data. */\nexport interface StateMutationMeta {\n readonly transactionId?: string;\n readonly actionId?: string;\n readonly origin?: StateMutationOrigin;\n readonly label?: string;\n readonly [key: string]: unknown;\n}\n\n/** Patch paths intentionally accept non-string keys such as Map keys and Symbols. */\nexport interface StatePatch {\n readonly op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';\n readonly path: readonly unknown[];\n readonly from?: readonly unknown[];\n readonly value?: unknown;\n}\n\nexport type HistoryEntryId = string | number;\n\nexport interface ReadonlyStateSnapshot<T> {\n readonly value: T;\n readonly name: string;\n /** Monotonically increases when the backend publishes a new snapshot. */\n readonly version: number;\n readonly lastUpdate: number;\n}\n\nexport interface StateReader<T> {\n readonly name: string;\n getSnapshot(): ReadonlyStateSnapshot<T>;\n subscribe(listener: () => void): () => void;\n}\n\nexport interface StateWriter<T> {\n /** The backend owns mutation safety; values are passed through unchanged. */\n setValue(value: T, meta?: StateMutationMeta): void;\n /** Returning undefined is a no-op. In-place mutation is backend-specific. */\n update(updater: (current: T) => T | undefined, meta?: StateMutationMeta): void;\n}\n\nexport interface StateBackend<T, Patch = StatePatch> extends StateReader<T>, StateWriter<T> {\n readonly capabilities?: {\n readonly patches?: boolean;\n readonly timeline?: boolean;\n readonly immutableSnapshots?: boolean;\n };\n getLastPatches?(): readonly Patch[] | null;\n /** Optional defensive read. Its absence means reads are backend-owned references. */\n getSafeValue?(): T;\n /** Optional lifecycle hook. Backends are shared by default. */\n dispose?(): void;\n isDisposed?(): boolean;\n subscribeWithPatches?(listener: (patches: readonly Patch[] | null) => void): () => void;\n}\n\nexport interface TimelineBackend<T, Patch = StatePatch> extends StateBackend<T, Patch> {\n getHistoryEntryId(): HistoryEntryId;\n hasHistoryEntry(entryId: HistoryEntryId): boolean;\n canUndo(): boolean;\n canRedo(): boolean;\n getPosition(): number;\n getHistory(): readonly T[];\n getHistoryLength(): number;\n undo(steps?: number, meta?: StateMutationMeta): void;\n redo(steps?: number, meta?: StateMutationMeta): void;\n goTo(position: number, meta?: StateMutationMeta): void;\n goToHistoryEntry(entryId: HistoryEntryId, meta?: StateMutationMeta): void;\n reset(meta?: StateMutationMeta): void;\n}\n\nexport interface TransactionBackend<T, Patch = StatePatch> extends TimelineBackend<T, Patch> {\n beginBatch(meta?: StateMutationMeta, options?: { readonly deferNotification?: boolean }): void;\n endBatch(): void;\n cancelBatch(): void;\n resumeNotifications(): void;\n flushNotifications(): void;\n isStoreDisposed(): boolean;\n}\n\nexport interface StateTransition<T> {\n readonly previous: T;\n readonly next: T;\n readonly meta: StateMutationMeta;\n readonly position?: number;\n}\n\nexport interface StateStoreOptions {\n readonly now?: () => number;\n}\n\n/**\n * A trusted-reference backend for applications that already own immutability.\n * No clone, freeze, draft, or patch generation is performed.\n */\nexport function createStateStore<T>(\n name: string,\n initialValue: T,\n options: StateStoreOptions = {},\n): StateBackend<T> {\n const now = options.now ?? Date.now;\n let value = initialValue;\n let version = 0;\n let disposed = false;\n let snapshot: ReadonlyStateSnapshot<T> = { value, name, version, lastUpdate: now() };\n const listeners = new Set<() => void>();\n\n const notify = (): void => {\n for (const listener of [...listeners]) {\n try {\n listener();\n } catch {\n // A subscriber cannot prevent other subscribers from observing a commit.\n }\n }\n };\n\n const publish = (next: T): void => {\n if (disposed || Object.is(value, next)) return;\n // Resolve the timestamp before mutating the backend. A caller-provided\n // clock is part of the store boundary and may throw (for example, when a\n // deterministic test clock is exhausted); a failed timestamp must not\n // leave the value and snapshot out of sync.\n const updatedAt = now();\n value = next;\n version += 1;\n snapshot = { value, name, version, lastUpdate: updatedAt };\n notify();\n };\n\n const backend: StateBackend<T> = {\n name,\n capabilities: { patches: false, timeline: false, immutableSnapshots: false },\n getSnapshot: () => snapshot,\n subscribe(listener) {\n if (typeof listener !== 'function') {\n throw new TypeError('Store subscriber must be a function.');\n }\n if (disposed) return () => {};\n listeners.add(listener);\n return () => listeners.delete(listener);\n },\n setValue(next) {\n publish(next);\n },\n update(updater) {\n if (disposed) return;\n const next = updater(value);\n if (next !== undefined) publish(next);\n },\n isDisposed: () => disposed,\n dispose() {\n if (disposed) return;\n disposed = true;\n listeners.clear();\n },\n };\n return backend;\n}\n"],"mappings":";;;;;AAwGA,SAAgB,iBACd,MACA,cACA,UAA6B,CAAC,GACb;CACjB,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,IAAI,QAAQ;CACZ,IAAI,UAAU;CACd,IAAI,WAAW;CACf,IAAI,WAAqC;EAAE;EAAO;EAAM;EAAS,YAAY,IAAI;CAAE;CACnF,MAAM,4BAAY,IAAI,IAAgB;CAEtC,MAAM,eAAqB;EACzB,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GAClC,IAAI;GACF,SAAS;EACX,QAAQ,CAER;CAEJ;CAEA,MAAM,WAAW,SAAkB;EACjC,IAAI,YAAY,OAAO,GAAG,OAAO,IAAI,GAAG;EAKxC,MAAM,YAAY,IAAI;EACtB,QAAQ;EACR,WAAW;EACX,WAAW;GAAE;GAAO;GAAM;GAAS,YAAY;EAAU;EACzD,OAAO;CACT;CA6BA,OAAO;EA1BL;EACA,cAAc;GAAE,SAAS;GAAO,UAAU;GAAO,oBAAoB;EAAM;EAC3E,mBAAmB;EACnB,UAAU,UAAU;GAClB,IAAI,OAAO,aAAa,YACtB,MAAM,IAAI,UAAU,sCAAsC;GAE5D,IAAI,UAAU,aAAa,CAAC;GAC5B,UAAU,IAAI,QAAQ;GACtB,aAAa,UAAU,OAAO,QAAQ;EACxC;EACA,SAAS,MAAM;GACb,QAAQ,IAAI;EACd;EACA,OAAO,SAAS;GACd,IAAI,UAAU;GACd,MAAM,OAAO,QAAQ,KAAK;GAC1B,IAAI,SAAS,KAAA,GAAW,QAAQ,IAAI;EACtC;EACA,kBAAkB;EAClB,UAAU;GACR,IAAI,UAAU;GACd,WAAW;GACX,UAAU,MAAM;EAClB;CAEW;AACf"}
1
+ {"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * Framework-neutral state contracts and a deliberately small reference store.\n *\n * This package owns no immutable-update, draft, clone, React, or DOM runtime.\n * A backend owns its value semantics; consumers must only rely on the\n * snapshot/subscription and capability contracts below.\n */\n\nimport type { ReadonlyStateSnapshot, StateStore } from './contracts';\nexport type {\n StateMutationOrigin, StateMutationMeta, StatePatch, HistoryEntryId,\n StateSnapshot, ReadonlyStateSnapshot, StateReader, StateWriter, StateBackend, StateStore,\n TimelineBackend, TransactionBatchControl, TransactionBackend, StateTransition,\n} from './contracts';\nexport type {\n TransactionParticipantBackend, TransactionMeta, TransactionOptions,\n TransactionParticipant, TransactionHandle, TransactionCoordinatorPort,\n} from './transaction-contracts';\n\nexport interface StateStoreOptions {\n readonly now?: () => number;\n}\n\n/**\n * A trusted-reference backend for applications that already own immutability.\n * No clone, freeze, draft, or patch generation is performed.\n */\nexport function createStateStore<T>(\n name: string,\n initialValue: T,\n options: StateStoreOptions = {},\n): StateStore<T> {\n const now = options.now ?? Date.now;\n let value = initialValue;\n let version = 0;\n let disposed = false;\n let snapshot: ReadonlyStateSnapshot<T> = { value, name, version, lastUpdate: now() };\n const listeners = new Set<() => void>();\n\n const notify = (): void => {\n for (const listener of [...listeners]) {\n try {\n listener();\n } catch {\n // A subscriber cannot prevent other subscribers from observing a commit.\n }\n }\n };\n\n const publish = (next: T): void => {\n if (disposed || Object.is(value, next)) return;\n // Resolve the timestamp before mutating the backend. A caller-provided\n // clock is part of the store boundary and may throw (for example, when a\n // deterministic test clock is exhausted); a failed timestamp must not\n // leave the value and snapshot out of sync.\n const updatedAt = now();\n value = next;\n version += 1;\n snapshot = { value, name, version, lastUpdate: updatedAt };\n notify();\n };\n\n const backend: StateStore<T> = {\n name,\n capabilities: { patches: false, timeline: false, immutableSnapshots: false },\n getSnapshot: () => snapshot,\n getValue: () => snapshot.value,\n subscribe(listener) {\n if (typeof listener !== 'function') {\n throw new TypeError('Store subscriber must be a function.');\n }\n if (disposed) return () => {};\n listeners.add(listener);\n return () => listeners.delete(listener);\n },\n setValue(next) {\n publish(next);\n },\n update(updater) {\n if (disposed) return;\n const next = updater(value);\n if (next !== undefined) publish(next);\n },\n isDisposed: () => disposed,\n dispose() {\n if (disposed) return;\n disposed = true;\n listeners.clear();\n },\n };\n return backend;\n}\n"],"mappings":";;;;;AA2BA,SAAgB,iBACd,MACA,cACA,UAA6B,CAAC,GACf;CACf,MAAM,MAAM,QAAQ,OAAO,KAAK;CAChC,IAAI,QAAQ;CACZ,IAAI,UAAU;CACd,IAAI,WAAW;CACf,IAAI,WAAqC;EAAE;EAAO;EAAM;EAAS,YAAY,IAAI;CAAE;CACnF,MAAM,4BAAY,IAAI,IAAgB;CAEtC,MAAM,eAAqB;EACzB,KAAK,MAAM,YAAY,CAAC,GAAG,SAAS,GAClC,IAAI;GACF,SAAS;EACX,QAAQ,CAER;CAEJ;CAEA,MAAM,WAAW,SAAkB;EACjC,IAAI,YAAY,OAAO,GAAG,OAAO,IAAI,GAAG;EAKxC,MAAM,YAAY,IAAI;EACtB,QAAQ;EACR,WAAW;EACX,WAAW;GAAE;GAAO;GAAM;GAAS,YAAY;EAAU;EACzD,OAAO;CACT;CA8BA,OAAO;EA3BL;EACA,cAAc;GAAE,SAAS;GAAO,UAAU;GAAO,oBAAoB;EAAM;EAC3E,mBAAmB;EACnB,gBAAgB,SAAS;EACzB,UAAU,UAAU;GAClB,IAAI,OAAO,aAAa,YACtB,MAAM,IAAI,UAAU,sCAAsC;GAE5D,IAAI,UAAU,aAAa,CAAC;GAC5B,UAAU,IAAI,QAAQ;GACtB,aAAa,UAAU,OAAO,QAAQ;EACxC;EACA,SAAS,MAAM;GACb,QAAQ,IAAI;EACd;EACA,OAAO,SAAS;GACd,IAAI,UAAU;GACd,MAAM,OAAO,QAAQ,KAAK;GAC1B,IAAI,SAAS,KAAA,GAAW,QAAQ,IAAI;EACtC;EACA,kBAAkB;EAClB,UAAU;GACR,IAAI,UAAU;GACd,WAAW;GACX,UAAU,MAAM;EAClB;CAEW;AACf"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@context-action/store-core",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "type": "module",
5
5
  "description": "Framework-neutral store and timeline contracts for Context-Action",
6
6
  "main": "dist/index.cjs",
@@ -50,7 +50,7 @@
50
50
  "access": "public"
51
51
  },
52
52
  "devDependencies": {
53
- "@types/node": "24.13.3",
53
+ "@types/node": "24.19.2",
54
54
  "rimraf": "^6.1.3",
55
55
  "tsdown": "0.23.0",
56
56
  "tslib": "^2.8.1",