coaction 3.0.0 → 3.1.0

package/dist/adapter.d.mts

@@ -431,6 +431,50 @@ declare const replaceExternalStoreState: <T extends CreateState>(store: Middlewa
   syncImmutable
 }?: ReplaceExternalStoreStateOptions) => void;
 //#endregion
+//#region packages/core/src/storeCommit.d.ts
+type StoreCommitSource = 'setState' | 'mutableAction' | 'external' | 'replay';
+/**
+ * A patch pair emitted after Coaction has committed an authoritative state
+ * transition.
+ */
+type StoreCommit<T extends CreateState = CreateState> = {
+  readonly state: T;
+  readonly patches: Patches;
+  readonly inversePatches: Patches;
+  readonly source: StoreCommitSource;
+};
+/** Patch pair to replay through Coaction's authoritative mutation pipeline. */
+type StorePatchTransition = {
+  readonly patches: Patches;
+  readonly inversePatches: Patches;
+};
+type StorePatchReplayOptions<T extends CreateState = CreateState> = {
+  /** Middleware-scoped setState entry that should observe the replay. */setState?: Store<T>['setState'];
+};
+type StoreCommitListener<T extends CreateState> = (commit: StoreCommit<T>) => void;
+type StoreCommitPrepareListener<T extends CreateState> = (commit: StoreCommit<T>) => boolean | void;
+/**
+ * Observe patch pairs after successful Coaction commits.
+ *
+ * @remarks
+ * Registering a listener enables patch generation only while it is needed,
+ * even when the store was created without `enablePatches: true`.
+ */
+declare const onStoreCommit: <T extends CreateState>(store: Store<T>, listener: StoreCommitListener<T>) => () => void;
+/**
+ * Inspect a pending object-valued commit before its patch pair is applied.
+ *
+ * @remarks
+ * Return `true` to request an exact state replacement for transitions whose
+ * object graph cannot be represented safely by the patch pair.
+ */
+declare const onStoreCommitPrepare: <T extends CreateState>(store: Store<T>, listener: StoreCommitPrepareListener<T>) => () => void;
+/**
+ * Replay a patch pair through Coaction validation, patch middleware, adapters,
+ * subscriptions, and transports.
+ */
+declare const replayStorePatches: <T extends CreateState>(store: Store<T>, transition: StorePatchTransition, options?: StorePatchReplayOptions<T>) => T;
+//#endregion
 //#region packages/core/src/utils.d.ts
 declare class StateSchemaError extends Error {
   name: string;
@@ -465,4 +509,4 @@ declare const sanitizeInitialStateValue: <T>(source: T, seen?: WeakMap<object, u
  */
 declare const wrapStore: <T extends object>(store: Store<T>, getState?: (...args: unknown[]) => T) => StoreReturn<T>;
 //#endregion
-export { type CreateState, type ExternalStoreAdapterOptions, type Middleware, type MiddlewareStore, type PatchTransform, type ReactiveTracker, StateSchemaError, type Store, type StoreTraceEvent, applyMutableAdapterPatches, applyRootReplacementWithPatches, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, getMutableAdapterOwnEnumerableKeys, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isStateSchemaError, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, sanitizeInitialStateValue, sanitizeReplacementState, snapshotMutableAdapterPureState, toMutableAdapterSnapshot, wrapStore };
+export { type CreateState, type ExternalStoreAdapterOptions, type Middleware, type MiddlewareStore, type PatchTransform, type ReactiveTracker, StateSchemaError, type Store, type StoreCommit, type StoreCommitSource, type StorePatchReplayOptions, type StorePatchTransition, type StoreTraceEvent, applyMutableAdapterPatches, applyRootReplacementWithPatches, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, getMutableAdapterOwnEnumerableKeys, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isStateSchemaError, onStoreCommit, onStoreCommitPrepare, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, replayStorePatches, sanitizeInitialStateValue, sanitizeReplacementState, snapshotMutableAdapterPureState, toMutableAdapterSnapshot, wrapStore };

package/dist/adapter.d.ts

@@ -431,6 +431,50 @@ declare const replaceExternalStoreState: <T extends CreateState>(store: Middlewa
   syncImmutable
 }?: ReplaceExternalStoreStateOptions) => void;
 //#endregion
+//#region packages/core/src/storeCommit.d.ts
+type StoreCommitSource = 'setState' | 'mutableAction' | 'external' | 'replay';
+/**
+ * A patch pair emitted after Coaction has committed an authoritative state
+ * transition.
+ */
+type StoreCommit<T extends CreateState = CreateState> = {
+  readonly state: T;
+  readonly patches: Patches;
+  readonly inversePatches: Patches;
+  readonly source: StoreCommitSource;
+};
+/** Patch pair to replay through Coaction's authoritative mutation pipeline. */
+type StorePatchTransition = {
+  readonly patches: Patches;
+  readonly inversePatches: Patches;
+};
+type StorePatchReplayOptions<T extends CreateState = CreateState> = {
+  /** Middleware-scoped setState entry that should observe the replay. */setState?: Store<T>['setState'];
+};
+type StoreCommitListener<T extends CreateState> = (commit: StoreCommit<T>) => void;
+type StoreCommitPrepareListener<T extends CreateState> = (commit: StoreCommit<T>) => boolean | void;
+/**
+ * Observe patch pairs after successful Coaction commits.
+ *
+ * @remarks
+ * Registering a listener enables patch generation only while it is needed,
+ * even when the store was created without `enablePatches: true`.
+ */
+declare const onStoreCommit: <T extends CreateState>(store: Store<T>, listener: StoreCommitListener<T>) => () => void;
+/**
+ * Inspect a pending object-valued commit before its patch pair is applied.
+ *
+ * @remarks
+ * Return `true` to request an exact state replacement for transitions whose
+ * object graph cannot be represented safely by the patch pair.
+ */
+declare const onStoreCommitPrepare: <T extends CreateState>(store: Store<T>, listener: StoreCommitPrepareListener<T>) => () => void;
+/**
+ * Replay a patch pair through Coaction validation, patch middleware, adapters,
+ * subscriptions, and transports.
+ */
+declare const replayStorePatches: <T extends CreateState>(store: Store<T>, transition: StorePatchTransition, options?: StorePatchReplayOptions<T>) => T;
+//#endregion
 //#region packages/core/src/utils.d.ts
 declare class StateSchemaError extends Error {
   name: string;
@@ -465,4 +509,4 @@ declare const sanitizeInitialStateValue: <T>(source: T, seen?: WeakMap<object, u
  */
 declare const wrapStore: <T extends object>(store: Store<T>, getState?: (...args: unknown[]) => T) => StoreReturn<T>;
 //#endregion
-export { type CreateState, type ExternalStoreAdapterOptions, type Middleware, type MiddlewareStore, type PatchTransform, type ReactiveTracker, StateSchemaError, type Store, type StoreTraceEvent, applyMutableAdapterPatches, applyRootReplacementWithPatches, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, getMutableAdapterOwnEnumerableKeys, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isStateSchemaError, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, sanitizeInitialStateValue, sanitizeReplacementState, snapshotMutableAdapterPureState, toMutableAdapterSnapshot, wrapStore };
+export { type CreateState, type ExternalStoreAdapterOptions, type Middleware, type MiddlewareStore, type PatchTransform, type ReactiveTracker, StateSchemaError, type Store, type StoreCommit, type StoreCommitSource, type StorePatchReplayOptions, type StorePatchTransition, type StoreTraceEvent, applyMutableAdapterPatches, applyRootReplacementWithPatches, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, getMutableAdapterOwnEnumerableKeys, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isStateSchemaError, onStoreCommit, onStoreCommitPrepare, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, replayStorePatches, sanitizeInitialStateValue, sanitizeReplacementState, snapshotMutableAdapterPureState, toMutableAdapterSnapshot, wrapStore };

package/dist/adapter.js

@@ -108,9 +108,10 @@ const warnDroppedUnsafePatches = (unsafePatches, source) => {
 };
 const sanitizePatches = (patches, options = {}) => {
 	if (options.warnOnDropped) warnDroppedUnsafePatches(getUnsafePatchPaths(patches), options.source ?? "patches");
+	const seen = /* @__PURE__ */ new WeakMap();
 	return patches?.filter((patch) => !hasUnsafePatchPath(patch.path)).map((patch) => Object.prototype.hasOwnProperty.call(patch, "value") ? {
 		...patch,
-		value: sanitizeReplacementState(patch.value)
+		value: sanitizeReplacementState(patch.value, seen)
 	} : patch);
 };
 const sanitizeCheckedPatches = (patches, source) => {
@@ -510,24 +511,107 @@ const createReactiveTracker = () => {
 };
 //#endregion
 //#region packages/core/src/lifecycle.ts
-const readyStores = /* @__PURE__ */ new WeakSet();
-const readyCallbacks = /* @__PURE__ */ new WeakMap();
+const storeReadyRuntimeSymbol = Symbol.for("coaction.lifecycle.ready");
+const getStoreReadyRuntime = (store, create = false) => {
+	const target = store;
+	const existing = target[storeReadyRuntimeSymbol];
+	if (existing || !create) return existing;
+	const runtime = {
+		callbacks: /* @__PURE__ */ new Set(),
+		ready: false
+	};
+	Object.defineProperty(target, storeReadyRuntimeSymbol, {
+		configurable: true,
+		enumerable: true,
+		value: runtime,
+		writable: true
+	});
+	return runtime;
+};
 const onStoreReady = (store, callback) => {
-	if (readyStores.has(store)) {
+	const runtime = getStoreReadyRuntime(store, true);
+	if (runtime.ready) {
 		callback();
 		return () => void 0;
 	}
-	let callbacks = readyCallbacks.get(store);
-	if (!callbacks) {
-		callbacks = /* @__PURE__ */ new Set();
-		readyCallbacks.set(store, callbacks);
-	}
-	callbacks.add(callback);
+	runtime.callbacks.add(callback);
 	return () => {
-		callbacks?.delete(callback);
+		runtime.callbacks.delete(callback);
 	};
 };
 //#endregion
+//#region packages/core/src/storeCommit.ts
+const storeCommitRuntimeSymbol = Symbol.for("coaction.storeCommit.runtime");
+const getStoreCommitRuntime = (store, create = false) => {
+	const target = store;
+	const existing = target[storeCommitRuntimeSymbol];
+	if (existing || !create) return existing;
+	const runtime = {
+		disposed: false,
+		listeners: /* @__PURE__ */ new Set(),
+		prepareListeners: /* @__PURE__ */ new Set()
+	};
+	Object.defineProperty(target, storeCommitRuntimeSymbol, {
+		configurable: true,
+		enumerable: true,
+		value: runtime,
+		writable: true
+	});
+	return runtime;
+};
+/**
+* Observe patch pairs after successful Coaction commits.
+*
+* @remarks
+* Registering a listener enables patch generation only while it is needed,
+* even when the store was created without `enablePatches: true`.
+*/
+const onStoreCommit = (store, listener) => {
+	const runtime = getStoreCommitRuntime(store, true);
+	if (runtime.disposed) throw new Error("onStoreCommit() cannot be called after store.destroy().");
+	runtime.listeners.add(listener);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		runtime.listeners.delete(listener);
+	};
+};
+/**
+* Inspect a pending object-valued commit before its patch pair is applied.
+*
+* @remarks
+* Return `true` to request an exact state replacement for transitions whose
+* object graph cannot be represented safely by the patch pair.
+*/
+const onStoreCommitPrepare = (store, listener) => {
+	const runtime = getStoreCommitRuntime(store, true);
+	if (runtime.disposed) throw new Error("onStoreCommitPrepare() cannot be called after store.destroy().");
+	runtime.prepareListeners.add(listener);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		runtime.prepareListeners.delete(listener);
+	};
+};
+/**
+* Replay a patch pair through Coaction validation, patch middleware, adapters,
+* subscriptions, and transports.
+*/
+const replayStorePatches = (store, transition, options = {}) => {
+	const runtime = getStoreCommitRuntime(store);
+	const replay = runtime?.disposed ? void 0 : runtime?.replay;
+	if (!replay) throw new Error("replayStorePatches() requires a store created by Coaction.");
+	return replay(transition, options.setState);
+};
+/** @internal */
+const publishStoreCommit = (store, commit) => {
+	const runtime = getStoreCommitRuntime(store);
+	if (!runtime || runtime.disposed || !runtime.listeners.size) return;
+	for (const listener of [...runtime.listeners]) listener(commit);
+};
+//#endregion
 //#region packages/core/src/replaceExternalStoreState.ts
 const replaceExternalStoreState = (store, internal, source, { syncImmutable = true } = {}) => {
 	internal.validateReplacementSource?.(source);
@@ -535,13 +619,15 @@ const replaceExternalStoreState = (store, internal, source, { syncImmutable = tr
 		replaceOwnEnumerable(draft, source);
 	}, { enablePatches: true });
 	internal.validateState?.(nextState);
-	const safePatches = sanitizeCheckedPatches((store.patch ? store.patch({
+	const finalPatches = store.patch ? store.patch({
 		patches,
 		inversePatches
 	}) : {
 		patches,
 		inversePatches
-	}).patches, "store.patch()");
+	};
+	const safePatches = sanitizeCheckedPatches(finalPatches.patches, "store.patch()");
+	const safeInversePatches = sanitizeCheckedPatches(finalPatches.inversePatches, "store.patch() inverse patches");
 	if (!safePatches.length) return;
 	const updateImmutable = internal.updateImmutable;
 	if (!syncImmutable) internal.updateImmutable = void 0;
@@ -551,6 +637,12 @@ const replaceExternalStoreState = (store, internal, source, { syncImmutable = tr
 		internal.updateImmutable = updateImmutable;
 	}
 	internal.emitPatches?.(safePatches);
+	publishStoreCommit(store, {
+		state: internal.rootState,
+		patches: safePatches,
+		inversePatches: safeInversePatches,
+		source: "external"
+	});
 };
 //#endregion
 //#region packages/core/src/wrapStore.ts
@@ -580,10 +672,13 @@ exports.getMutableAdapterOwnEnumerableKeys = getMutableAdapterOwnEnumerableKeys;
 exports.isEqualMutableAdapterSnapshot = isEqualMutableAdapterSnapshot;
 exports.isMutableAdapterUnsafeKey = isMutableAdapterUnsafeKey;
 exports.isStateSchemaError = isStateSchemaError;
+exports.onStoreCommit = onStoreCommit;
+exports.onStoreCommitPrepare = onStoreCommitPrepare;
 exports.onStoreReady = onStoreReady;
 exports.replaceExternalStoreState = replaceExternalStoreState;
 exports.replaceMutableAdapterState = replaceMutableAdapterState;
 exports.replaceOwnEnumerable = replaceOwnEnumerable;
+exports.replayStorePatches = replayStorePatches;
 exports.sanitizeInitialStateValue = sanitizeInitialStateValue;
 exports.sanitizeReplacementState = sanitizeReplacementState;
 exports.snapshotMutableAdapterPureState = snapshotMutableAdapterPureState;

package/dist/adapter.mjs

@@ -84,9 +84,10 @@ const warnDroppedUnsafePatches = (unsafePatches, source) => {
 };
 const sanitizePatches = (patches, options = {}) => {
 	if (options.warnOnDropped) warnDroppedUnsafePatches(getUnsafePatchPaths(patches), options.source ?? "patches");
+	const seen = /* @__PURE__ */ new WeakMap();
 	return patches?.filter((patch) => !hasUnsafePatchPath(patch.path)).map((patch) => Object.prototype.hasOwnProperty.call(patch, "value") ? {
 		...patch,
-		value: sanitizeReplacementState(patch.value)
+		value: sanitizeReplacementState(patch.value, seen)
 	} : patch);
 };
 const sanitizeCheckedPatches = (patches, source) => {
@@ -486,23 +487,106 @@ const createReactiveTracker = () => {
 };
 //#endregion
 //#region packages/core/src/lifecycle.ts
-const readyStores = /* @__PURE__ */ new WeakSet();
-const readyCallbacks = /* @__PURE__ */ new WeakMap();
+const storeReadyRuntimeSymbol = Symbol.for("coaction.lifecycle.ready");
+const getStoreReadyRuntime = (store, create = false) => {
+	const target = store;
+	const existing = target[storeReadyRuntimeSymbol];
+	if (existing || !create) return existing;
+	const runtime = {
+		callbacks: /* @__PURE__ */ new Set(),
+		ready: false
+	};
+	Object.defineProperty(target, storeReadyRuntimeSymbol, {
+		configurable: true,
+		enumerable: true,
+		value: runtime,
+		writable: true
+	});
+	return runtime;
+};
 const onStoreReady = (store, callback) => {
-	if (readyStores.has(store)) {
+	const runtime = getStoreReadyRuntime(store, true);
+	if (runtime.ready) {
 		callback();
 		return () => void 0;
 	}
-	let callbacks = readyCallbacks.get(store);
-	if (!callbacks) {
-		callbacks = /* @__PURE__ */ new Set();
-		readyCallbacks.set(store, callbacks);
-	}
-	callbacks.add(callback);
+	runtime.callbacks.add(callback);
+	return () => {
+		runtime.callbacks.delete(callback);
+	};
+};
+//#endregion
+//#region packages/core/src/storeCommit.ts
+const storeCommitRuntimeSymbol = Symbol.for("coaction.storeCommit.runtime");
+const getStoreCommitRuntime = (store, create = false) => {
+	const target = store;
+	const existing = target[storeCommitRuntimeSymbol];
+	if (existing || !create) return existing;
+	const runtime = {
+		disposed: false,
+		listeners: /* @__PURE__ */ new Set(),
+		prepareListeners: /* @__PURE__ */ new Set()
+	};
+	Object.defineProperty(target, storeCommitRuntimeSymbol, {
+		configurable: true,
+		enumerable: true,
+		value: runtime,
+		writable: true
+	});
+	return runtime;
+};
+/**
+* Observe patch pairs after successful Coaction commits.
+*
+* @remarks
+* Registering a listener enables patch generation only while it is needed,
+* even when the store was created without `enablePatches: true`.
+*/
+const onStoreCommit = (store, listener) => {
+	const runtime = getStoreCommitRuntime(store, true);
+	if (runtime.disposed) throw new Error("onStoreCommit() cannot be called after store.destroy().");
+	runtime.listeners.add(listener);
+	let active = true;
 	return () => {
-		callbacks?.delete(callback);
+		if (!active) return;
+		active = false;
+		runtime.listeners.delete(listener);
 	};
 };
+/**
+* Inspect a pending object-valued commit before its patch pair is applied.
+*
+* @remarks
+* Return `true` to request an exact state replacement for transitions whose
+* object graph cannot be represented safely by the patch pair.
+*/
+const onStoreCommitPrepare = (store, listener) => {
+	const runtime = getStoreCommitRuntime(store, true);
+	if (runtime.disposed) throw new Error("onStoreCommitPrepare() cannot be called after store.destroy().");
+	runtime.prepareListeners.add(listener);
+	let active = true;
+	return () => {
+		if (!active) return;
+		active = false;
+		runtime.prepareListeners.delete(listener);
+	};
+};
+/**
+* Replay a patch pair through Coaction validation, patch middleware, adapters,
+* subscriptions, and transports.
+*/
+const replayStorePatches = (store, transition, options = {}) => {
+	const runtime = getStoreCommitRuntime(store);
+	const replay = runtime?.disposed ? void 0 : runtime?.replay;
+	if (!replay) throw new Error("replayStorePatches() requires a store created by Coaction.");
+	return replay(transition, options.setState);
+};
+/** @internal */
+const publishStoreCommit = (store, commit) => {
+	const runtime = getStoreCommitRuntime(store);
+	if (!runtime || runtime.disposed || !runtime.listeners.size) return;
+	for (const listener of [...runtime.listeners]) listener(commit);
+};
 //#endregion
 //#region packages/core/src/replaceExternalStoreState.ts
 const replaceExternalStoreState = (store, internal, source, { syncImmutable = true } = {}) => {
@@ -511,13 +595,15 @@ const replaceExternalStoreState = (store, internal, source, { syncImmutable = tr
 		replaceOwnEnumerable(draft, source);
 	}, { enablePatches: true });
 	internal.validateState?.(nextState);
-	const safePatches = sanitizeCheckedPatches((store.patch ? store.patch({
+	const finalPatches = store.patch ? store.patch({
 		patches,
 		inversePatches
 	}) : {
 		patches,
 		inversePatches
-	}).patches, "store.patch()");
+	};
+	const safePatches = sanitizeCheckedPatches(finalPatches.patches, "store.patch()");
+	const safeInversePatches = sanitizeCheckedPatches(finalPatches.inversePatches, "store.patch() inverse patches");
 	if (!safePatches.length) return;
 	const updateImmutable = internal.updateImmutable;
 	if (!syncImmutable) internal.updateImmutable = void 0;
@@ -527,6 +613,12 @@ const replaceExternalStoreState = (store, internal, source, { syncImmutable = tr
 		internal.updateImmutable = updateImmutable;
 	}
 	internal.emitPatches?.(safePatches);
+	publishStoreCommit(store, {
+		state: internal.rootState,
+		patches: safePatches,
+		inversePatches: safeInversePatches,
+		source: "external"
+	});
 };
 //#endregion
 //#region packages/core/src/wrapStore.ts
@@ -545,4 +637,4 @@ const wrapStore = (store, getState = () => store.getState()) => {
 	return Object.assign({ [name]: (...args) => getState(...args) }[name], _store);
 };
 //#endregion
-export { StateSchemaError, applyMutableAdapterPatches, applyRootReplacementWithPatches, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, getMutableAdapterOwnEnumerableKeys, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isStateSchemaError, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, sanitizeInitialStateValue, sanitizeReplacementState, snapshotMutableAdapterPureState, toMutableAdapterSnapshot, wrapStore };
+export { StateSchemaError, applyMutableAdapterPatches, applyRootReplacementWithPatches, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, getMutableAdapterOwnEnumerableKeys, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isStateSchemaError, onStoreCommit, onStoreCommitPrepare, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, replayStorePatches, sanitizeInitialStateValue, sanitizeReplacementState, snapshotMutableAdapterPureState, toMutableAdapterSnapshot, wrapStore };