@kontsedal/olas-core 0.0.3 → 0.0.5

package/dist/{root-D_xAdcom.cjs → root-lBp7qziQ.cjs}

@@ -978,6 +978,25 @@ function registerQueryById(queryId, query) {
 function lookupRegisteredQuery(queryId) {
 	return queryRegistry.get(queryId);
 }
+const mutationRegistry = /* @__PURE__ */ new Map();
+/** Register a mutation by its `mutationId`. Internal — called from `defineMutation`. */
+function registerMutationById(mutationId, entry) {
+	mutationRegistry.set(mutationId, entry);
+}
+/**
+* Look up a registered mutation by id. Returns `undefined` when no
+* mutation with that id has been defined — typical when a queue entry
+* references a mutation whose module hasn't been imported (e.g. a
+* code-split route boundary). The plugin should leave such entries in
+* place and retry once the module loads.
+*/
+function lookupRegisteredMutation(mutationId) {
+	return mutationRegistry.get(mutationId);
+}
+/** Test-only — drop a registered mutation. Not exported from the package. */
+function _unregisterMutationById(mutationId) {
+	mutationRegistry.delete(mutationId);
+}
 //#endregion
 //#region src/query/client.ts
 const DEFAULT_GC_TIME = 5 * 6e4;
@@ -1342,6 +1361,26 @@ var QueryClient = class {
 			this.callPlugin(() => cb.call(plugin, event));
 		}
 	}
+	/**
+	* Fan out a `MutationEnqueueEvent` to every installed plugin. Called from
+	* `MutationImpl.executeRun` when `spec.persist === true`. Plugins use this
+	* to write the run to durable storage; the queue replays on reload. SPEC §13.3.
+	*/
+	emitMutationEnqueue(event) {
+		if (this.plugins.length === 0) return;
+		for (const plugin of this.plugins) if (plugin.onMutationEnqueue) {
+			const cb = plugin.onMutationEnqueue;
+			this.callPlugin(() => cb.call(plugin, event));
+		}
+	}
+	/** Fan out a `MutationSettleEvent` to every installed plugin. SPEC §13.3. */
+	emitMutationSettle(event) {
+		if (this.plugins.length === 0) return;
+		for (const plugin of this.plugins) if (plugin.onMutationSettle) {
+			const cb = plugin.onMutationSettle;
+			this.callPlugin(() => cb.call(plugin, event));
+		}
+	}
 	/** Resolve `queryId → live entry-map keys`. Empty array when unknown. */
 	subscribedKeysFor(queryId) {
 		const query = lookupRegisteredQuery(queryId);
@@ -2761,6 +2800,7 @@ var LocalCacheImpl = class {
 	refetch = () => this.entry.refetch();
 	reset = () => this.entry.reset();
 	firstValue = () => this.entry.firstValue();
+	promise = () => this.entry.firstValue();
 	invalidate = () => {
 		this.entry.invalidate().catch(() => {});
 	};
@@ -2783,12 +2823,52 @@ function arraysEqual(a, b) {
 }
 //#endregion
 //#region src/query/mutation.ts
+/**
+* Register a persistable mutation at module scope. Returns the spec
+* unchanged (with a `__olas: 'mutation'` brand) so consumers can pass it
+* to `ctx.mutation(...)`, optionally spreading per-controller hooks on
+* top:
+*
+* ```ts
+* // module-scope
+* export const createOrder = defineMutation({
+*   mutationId: 'order/create',
+*   mutate: async (vars: OrderInput, { signal }) => api.createOrder(vars, { signal }),
+* })
+*
+* // controller
+* const m = ctx.mutation({
+*   ...createOrder,
+*   onSuccess: () => toast('Order placed'),
+* })
+* ```
+*
+* The `mutate` function MUST NOT close over controller-instance state — on
+* replay there is no controller. Module-level dependencies (a shared `api`
+* client, etc.) are fine.
+*/
+function defineMutation(spec) {
+	if (typeof spec.mutationId !== "string" || spec.mutationId.length === 0) throw new Error("[olas] defineMutation requires a non-empty `mutationId`.");
+	const persistSpec = {
+		...spec,
+		persist: spec.persist ?? true
+	};
+	registerMutationById(spec.mutationId, {
+		mutationId: spec.mutationId,
+		mutate: spec.mutate
+	});
+	return Object.assign(persistSpec, {
+		__olas: "mutation",
+		mutationId: spec.mutationId
+	});
+}
 var MutationImpl = class {
 	spec;
 	onError;
 	controllerPath;
 	inflightCounter;
 	devtools;
+	lifecycle;
 	data = signal(void 0);
 	error = signal(void 0);
 	isPending = signal(false);
@@ -2797,12 +2877,21 @@ var MutationImpl = class {
 	serialQueue = [];
 	serialActive = false;
 	disposed = false;
-	constructor(spec, onError, controllerPath, inflightCounter, devtools) {
+	constructor(spec, onError, controllerPath, inflightCounter, devtools, lifecycle) {
 		this.spec = spec;
 		this.onError = onError;
 		this.controllerPath = controllerPath;
 		this.inflightCounter = inflightCounter;
 		this.devtools = devtools;
+		this.lifecycle = lifecycle;
+	}
+	/**
+	* True iff this mutation should emit persistable-lifecycle events.
+	* Validated at construction time (in `createMutation`) so any malformed
+	* `persist: true`-without-`mutationId` config surfaces early.
+	*/
+	get isPersistable() {
+		return this.spec.persist === true && this.lifecycle !== void 0;
 	}
 	emit(event) {}
 	run = ((vars = void 0) => {
@@ -2866,10 +2955,30 @@ var MutationImpl = class {
 			this.isPending.set(true);
 			this.lastVariables.set(vars);
 		});
+		const runId = this.isPersistable ? makeRunId() : "";
+		const mutationId = this.spec.mutationId;
+		if (this.isPersistable && mutationId !== void 0) try {
+			this.lifecycle?.emitEnqueue({
+				mutationId,
+				runId,
+				variables: vars,
+				attempt: 0
+			});
+		} catch (err) {
+			dispatchError(this.onError, err, {
+				kind: "plugin",
+				controllerPath: this.controllerPath
+			});
+		}
 		try {
 			const result = await raceAbort(this.runWithRetry(vars, abort.signal), abort.signal);
 			if (abort.signal.aborted || this.disposed) {
 				snapshot?.rollback();
+				if (this.isPersistable && mutationId !== void 0) this.safeEmitSettle({
+					mutationId,
+					runId,
+					outcome: "cancelled"
+				});
 				throw new DOMException("Superseded", "AbortError");
 			}
 			batch(() => {
@@ -2879,16 +2988,32 @@ var MutationImpl = class {
 			this.safeCall(() => this.spec.onSuccess?.(result, vars), "mutation");
 			snapshot?.finalize();
 			this.safeCall(() => this.spec.onSettled?.(result, void 0, vars), "mutation");
+			if (this.isPersistable && mutationId !== void 0) this.safeEmitSettle({
+				mutationId,
+				runId,
+				outcome: "success"
+			});
 			return result;
 		} catch (err) {
 			if (isAbortError(err) || abort.signal.aborted) {
 				snapshot?.rollback();
+				if (this.isPersistable && mutationId !== void 0) this.safeEmitSettle({
+					mutationId,
+					runId,
+					outcome: "cancelled"
+				});
 				throw err;
 			}
 			this.error.set(err);
 			this.safeCall(() => this.spec.onError?.(err, vars, snapshot), "mutation");
 			snapshot?.rollback();
 			this.safeCall(() => this.spec.onSettled?.(void 0, err, vars), "mutation");
+			if (this.isPersistable && mutationId !== void 0) this.safeEmitSettle({
+				mutationId,
+				runId,
+				outcome: "error",
+				error: err
+			});
 			throw err;
 		} finally {
 			this.inflight.delete(handle);
@@ -2896,6 +3021,16 @@ var MutationImpl = class {
 			if (this.inflight.size === 0) this.isPending.set(false);
 		}
 	}
+	safeEmitSettle(event) {
+		try {
+			this.lifecycle?.emitSettle(event);
+		} catch (err) {
+			dispatchError(this.onError, err, {
+				kind: "plugin",
+				controllerPath: this.controllerPath
+			});
+		}
+	}
 	wrapSnapshot(raw) {
 		let consumed = false;
 		return {
@@ -2959,8 +3094,24 @@ var MutationImpl = class {
 		this.serialQueue.length = 0;
 	}
 };
-function createMutation(spec, onError, controllerPath, inflightCounter, devtools) {
-	return new MutationImpl(spec, onError, controllerPath, inflightCounter, devtools);
+function createMutation(spec, onError, controllerPath, inflightCounter, devtools, lifecycle) {
+	if (spec.persist === true) {
+		if (typeof spec.mutationId !== "string" || spec.mutationId.length === 0) throw new Error("[olas] ctx.mutation({ persist: true, ... }) requires a non-empty `mutationId`.");
+	}
+	return new MutationImpl(spec, onError, controllerPath, inflightCounter, devtools, lifecycle);
+}
+/**
+* Generate a unique-enough run id for the persistable-mutation lifecycle.
+* Uses `crypto.randomUUID` where available (Node 19+, modern browsers),
+* with a timestamp+random fallback for older runtimes. Collisions only
+* affect dedup at the plugin layer, not correctness, so the fallback's
+* weakness is acceptable.
+*/
+function makeRunId() {
+	const g = globalThis;
+	if (typeof g.crypto?.randomUUID === "function") return g.crypto.randomUUID();
+	const rand = Math.random().toString(36).slice(2, 12);
+	return `${Date.now().toString(36)}-${rand}`;
 }
 /**
 * Race a promise against an AbortSignal. If the signal fires before the
@@ -3056,6 +3207,7 @@ var SubscriptionImpl = class {
 		if (!cur) return Promise.reject(/* @__PURE__ */ new Error("[olas] no active subscription"));
 		return cur.entry.firstValue().then((v) => this.project(v));
 	};
+	promise = () => this.firstValue();
 	project(v) {
 		return this.select === void 0 ? v : this.select(v);
 	}
@@ -3215,6 +3367,7 @@ var InfiniteSubscriptionImpl = class {
 		if (!cur) return Promise.reject(/* @__PURE__ */ new Error("[olas] no active subscription"));
 		return cur.entry.firstValue();
 	};
+	promise = () => this.firstValue();
 	fetchNextPage = () => {
 		const cur = this.current$.peek();
 		if (!cur) return Promise.resolve();
@@ -3494,7 +3647,11 @@ var ControllerInstance = class ControllerInstance {
 				return handle.subscription;
 			},
 			mutation(spec) {
-				const m = createMutation(spec, self.rootShared.onError, self.path, self.rootShared.queryClient.mutationsInflight$, self.rootShared.devtools);
+				const queryClient = self.rootShared.queryClient;
+				const m = createMutation(spec, self.rootShared.onError, self.path, queryClient.mutationsInflight$, self.rootShared.devtools, spec.persist === true ? {
+					emitEnqueue: (ev) => queryClient.emitMutationEnqueue(ev),
+					emitSettle: (ev) => queryClient.emitMutationSettle(ev)
+				} : void 0);
 				self.entries.push({
 					kind: "cleanup",
 					dispose: () => m.dispose()
@@ -4096,6 +4253,12 @@ function createRoot(def, options) {
 	return createRootWithProps(def, void 0, options);
 }
 //#endregion
+Object.defineProperty(exports, "_unregisterMutationById", {
+	enumerable: true,
+	get: function() {
+		return _unregisterMutationById;
+	}
+});
 Object.defineProperty(exports, "batch", {
 	enumerable: true,
 	get: function() {
@@ -4138,6 +4301,12 @@ Object.defineProperty(exports, "defineController", {
 		return defineController;
 	}
 });
+Object.defineProperty(exports, "defineMutation", {
+	enumerable: true,
+	get: function() {
+		return defineMutation;
+	}
+});
 Object.defineProperty(exports, "effect", {
 	enumerable: true,
 	get: function() {
@@ -4150,6 +4319,12 @@ Object.defineProperty(exports, "isAbortError", {
 		return isAbortError;
 	}
 });
+Object.defineProperty(exports, "lookupRegisteredMutation", {
+	enumerable: true,
+	get: function() {
+		return lookupRegisteredMutation;
+	}
+});
 Object.defineProperty(exports, "lookupRegisteredQuery", {
 	enumerable: true,
 	get: function() {
@@ -4181,4 +4356,4 @@ Object.defineProperty(exports, "untracked", {
 	}
 });
 
-//# sourceMappingURL=root-D_xAdcom.cjs.map
+//# sourceMappingURL=root-lBp7qziQ.cjs.map