@voidhash/mimic-effect 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/DocumentInstance.cjs

@@ -0,0 +1,263 @@
+const require_Metrics = require('./Metrics.cjs');
+let effect = require("effect");
+let _voidhash_mimic = require("@voidhash/mimic");
+let _voidhash_mimic_server = require("@voidhash/mimic/server");
+
+//#region src/DocumentInstance.ts
+/**
+* @voidhash/mimic-effect - DocumentInstance
+*
+* Manages the lifecycle of a single document including:
+* - Restoration from storage (cold storage + WAL replay)
+* - Transaction submission with WAL persistence
+* - Snapshot saving and trigger checking
+*
+* Used by both MimicServerEngine (single-node) and MimicClusterServerEngine (clustered).
+*/
+/**
+* Create a DocumentInstance for a single document.
+*
+* This handles:
+* - Loading from cold storage or computing initial state
+* - Persisting initial state immediately (crash safety)
+* - Replaying WAL entries
+* - Transaction submission with WAL persistence
+* - Snapshot saving
+*/
+const make = (documentId, config, coldStorage, hotStorage) => effect.Effect.gen(function* () {
+	const SCHEMA_VERSION = 1;
+	const storedDoc = yield* coldStorage.load(documentId);
+	let initialState;
+	let initial;
+	let initialVersion = 0;
+	if (storedDoc) {
+		initialState = storedDoc.state;
+		initialVersion = storedDoc.version;
+	} else initial = yield* computeInitialState(config, documentId);
+	const pubsub = yield* effect.PubSub.unbounded();
+	const lastSnapshotVersionRef = yield* effect.Ref.make(initialVersion);
+	const lastSnapshotTimeRef = yield* effect.Ref.make(Date.now());
+	const transactionsSinceSnapshotRef = yield* effect.Ref.make(0);
+	const lastActivityTimeRef = yield* effect.Ref.make(Date.now());
+	const document = _voidhash_mimic_server.ServerDocument.make({
+		schema: config.schema,
+		initial,
+		initialState,
+		initialVersion,
+		maxTransactionHistory: config.maxTransactionHistory,
+		onBroadcast: (message) => {
+			effect.Effect.runSync(effect.PubSub.publish(pubsub, {
+				type: "transaction",
+				transaction: message.transaction,
+				version: message.version
+			}));
+		},
+		onRejection: (transactionId, reason) => {
+			effect.Effect.runSync(effect.PubSub.publish(pubsub, {
+				type: "error",
+				transactionId,
+				reason
+			}));
+		}
+	});
+	if (!storedDoc) {
+		const initialStoredDoc = createStoredDocument(document.get(), 0, SCHEMA_VERSION);
+		yield* coldStorage.save(documentId, initialStoredDoc);
+		yield* effect.Effect.logDebug("Initial state persisted to cold storage", { documentId });
+	}
+	const walEntries = yield* hotStorage.getEntries(documentId, initialVersion);
+	yield* verifyWalContinuity(documentId, walEntries, initialVersion);
+	yield* replayWalEntries(documentId, document, walEntries);
+	if (storedDoc) yield* effect.Metric.increment(require_Metrics.documentsRestored);
+	else yield* effect.Metric.increment(require_Metrics.documentsCreated);
+	yield* effect.Metric.incrementBy(require_Metrics.documentsActive, 1);
+	const getSnapshotTracking = effect.Effect.gen(function* () {
+		return {
+			lastSnapshotVersion: yield* effect.Ref.get(lastSnapshotVersionRef),
+			lastSnapshotTime: yield* effect.Ref.get(lastSnapshotTimeRef),
+			transactionsSinceSnapshot: yield* effect.Ref.get(transactionsSinceSnapshotRef)
+		};
+	});
+	const saveSnapshot = effect.Effect.fn("document.snapshot.save")(function* () {
+		var _baseSnapshot$version;
+		const targetVersion = document.getVersion();
+		if (targetVersion <= (yield* effect.Ref.get(lastSnapshotVersionRef))) return;
+		const snapshotStartTime = Date.now();
+		const baseSnapshot = yield* coldStorage.load(documentId);
+		const baseVersion = (_baseSnapshot$version = baseSnapshot === null || baseSnapshot === void 0 ? void 0 : baseSnapshot.version) !== null && _baseSnapshot$version !== void 0 ? _baseSnapshot$version : 0;
+		const baseState = baseSnapshot === null || baseSnapshot === void 0 ? void 0 : baseSnapshot.state;
+		const walEntries$1 = yield* hotStorage.getEntries(documentId, baseVersion);
+		const snapshotResult = computeSnapshotState(config.schema, baseState, walEntries$1, targetVersion);
+		if (!snapshotResult) return;
+		const currentLastSnapshot = yield* effect.Ref.get(lastSnapshotVersionRef);
+		if (snapshotResult.version <= currentLastSnapshot) return;
+		const storedDoc$1 = createStoredDocument(snapshotResult.state, snapshotResult.version, SCHEMA_VERSION);
+		yield* coldStorage.save(documentId, storedDoc$1);
+		const snapshotDuration = Date.now() - snapshotStartTime;
+		yield* effect.Metric.increment(require_Metrics.storageSnapshots);
+		yield* effect.Metric.update(require_Metrics.storageSnapshotLatency, snapshotDuration);
+		yield* effect.Ref.set(lastSnapshotVersionRef, snapshotResult.version);
+		yield* effect.Ref.set(lastSnapshotTimeRef, Date.now());
+		yield* effect.Ref.set(transactionsSinceSnapshotRef, 0);
+		yield* effect.Effect.catchAll(hotStorage.truncate(documentId, snapshotResult.version), (e) => effect.Effect.logWarning("WAL truncate failed - will retry on next snapshot", {
+			documentId,
+			version: snapshotResult.version,
+			error: e
+		}));
+	});
+	const checkSnapshotTriggers = effect.Effect.fn("document.snapshot.check-triggers")(function* () {
+		if (shouldTriggerSnapshot(yield* effect.Ref.get(transactionsSinceSnapshotRef), yield* effect.Ref.get(lastSnapshotTimeRef), config.snapshot)) yield* saveSnapshot();
+	});
+	const submit = effect.Effect.fn("document.transaction.submit")(function* (transaction) {
+		const submitStartTime = Date.now();
+		yield* effect.Ref.set(lastActivityTimeRef, Date.now());
+		const validation = document.validate(transaction);
+		if (!validation.valid) {
+			yield* effect.Metric.increment(require_Metrics.transactionsRejected);
+			const latency$1 = Date.now() - submitStartTime;
+			yield* effect.Metric.update(require_Metrics.transactionsLatency, latency$1);
+			return {
+				success: false,
+				reason: validation.reason
+			};
+		}
+		const walEntry = {
+			transaction,
+			version: validation.nextVersion,
+			timestamp: Date.now()
+		};
+		const appendResult = yield* effect.Effect.either(hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion));
+		if (appendResult._tag === "Left") {
+			yield* effect.Effect.logError("WAL append failed", {
+				documentId,
+				version: validation.nextVersion,
+				error: appendResult.left
+			});
+			yield* effect.Metric.increment(require_Metrics.walAppendFailures);
+			const latency$1 = Date.now() - submitStartTime;
+			yield* effect.Metric.update(require_Metrics.transactionsLatency, latency$1);
+			return {
+				success: false,
+				reason: "Storage unavailable. Please retry."
+			};
+		}
+		document.apply(transaction);
+		const latency = Date.now() - submitStartTime;
+		yield* effect.Metric.update(require_Metrics.transactionsLatency, latency);
+		yield* effect.Metric.increment(require_Metrics.transactionsProcessed);
+		yield* effect.Metric.increment(require_Metrics.storageWalAppends);
+		yield* effect.Ref.update(transactionsSinceSnapshotRef, (n) => n + 1);
+		yield* checkSnapshotTriggers();
+		return {
+			success: true,
+			version: validation.nextVersion
+		};
+	});
+	const touch = effect.Effect.fn("document.touch")(function* () {
+		yield* effect.Ref.set(lastActivityTimeRef, Date.now());
+	});
+	const needsSnapshot = () => effect.Effect.map(effect.Ref.get(transactionsSinceSnapshotRef), (n) => n > 0);
+	const getLastActivityTime = () => effect.Ref.get(lastActivityTimeRef);
+	return {
+		document,
+		pubsub,
+		getSnapshotTracking,
+		submit,
+		saveSnapshot,
+		checkSnapshotTriggers,
+		touch,
+		getVersion: () => document.getVersion(),
+		getSnapshot: () => document.getSnapshot(),
+		needsSnapshot,
+		getLastActivityTime
+	};
+});
+/**
+* Compute initial state for a new document.
+*/
+const computeInitialState = (config, documentId) => {
+	if (config.initial === void 0) return effect.Effect.succeed(void 0);
+	if (typeof config.initial === "function") return config.initial({ documentId });
+	return effect.Effect.succeed(config.initial);
+};
+/**
+* Verify WAL continuity and log warnings for any gaps.
+*/
+const verifyWalContinuity = effect.Effect.fn("document.wal.verify")(function* (documentId, walEntries, baseVersion) {
+	if (walEntries.length === 0) return;
+	const firstWalVersion = walEntries[0].version;
+	const expectedFirst = baseVersion + 1;
+	if (firstWalVersion !== expectedFirst) {
+		yield* effect.Effect.logWarning("WAL version gap detected", {
+			documentId,
+			snapshotVersion: baseVersion,
+			firstWalVersion,
+			expectedFirst
+		});
+		yield* effect.Metric.increment(require_Metrics.storageVersionGaps);
+	}
+	for (let i = 1; i < walEntries.length; i++) {
+		const prev = walEntries[i - 1].version;
+		const curr = walEntries[i].version;
+		if (curr !== prev + 1) yield* effect.Effect.logWarning("WAL internal gap detected", {
+			documentId,
+			previousVersion: prev,
+			currentVersion: curr
+		});
+	}
+});
+/**
+* Replay WAL entries onto a ServerDocument.
+*/
+const replayWalEntries = effect.Effect.fn("document.wal.replay")(function* (documentId, document, walEntries) {
+	for (const entry of walEntries) {
+		const result = document.submit(entry.transaction);
+		if (!result.success) yield* effect.Effect.logWarning("Skipping corrupted WAL entry", {
+			documentId,
+			version: entry.version,
+			reason: result.reason
+		});
+	}
+});
+/**
+* Compute snapshot state by replaying WAL entries on a base state.
+*/
+const computeSnapshotState = (schema, baseState, walEntries, targetVersion) => {
+	const relevantEntries = walEntries.filter((e) => e.version <= targetVersion);
+	if (relevantEntries.length === 0 && baseState === void 0) return;
+	let snapshotState = baseState;
+	for (const entry of relevantEntries) {
+		const tempDoc = _voidhash_mimic.Document.make(schema, { initialState: snapshotState });
+		tempDoc.apply(entry.transaction.ops);
+		snapshotState = tempDoc.get();
+	}
+	if (snapshotState === void 0) return;
+	const snapshotVersion = relevantEntries.length > 0 ? relevantEntries[relevantEntries.length - 1].version : 0;
+	return {
+		state: snapshotState,
+		version: snapshotVersion
+	};
+};
+/**
+* Check if a snapshot should be triggered.
+*/
+const shouldTriggerSnapshot = (transactionsSinceSnapshot, lastSnapshotTime, config) => {
+	const now = Date.now();
+	const intervalMs = effect.Duration.toMillis(config.interval);
+	if (transactionsSinceSnapshot >= config.transactionThreshold) return true;
+	if (now - lastSnapshotTime >= intervalMs) return true;
+	return false;
+};
+/**
+* Create a StoredDocument for persistence.
+*/
+const createStoredDocument = (state, version, schemaVersion) => ({
+	state,
+	version,
+	schemaVersion,
+	savedAt: Date.now()
+});
+const DocumentInstance = { make };
+
+//#endregion
+exports.DocumentInstance = DocumentInstance;

package/dist/DocumentInstance.d.cts

@@ -0,0 +1,78 @@
+import { ColdStorageError, HotStorageError } from "./Errors.cjs";
+import { ServerBroadcast } from "./Protocol.cjs";
+import { ColdStorage } from "./ColdStorage.cjs";
+import { HotStorage } from "./HotStorage.cjs";
+import { Duration, Effect, PubSub } from "effect";
+import { Primitive, Transaction } from "@voidhash/mimic";
+import { ServerDocument } from "@voidhash/mimic/server";
+
+//#region src/DocumentInstance.d.ts
+
+/**
+ * Result of submitting a transaction
+ */
+type SubmitResult = {
+  readonly success: true;
+  readonly version: number;
+} | {
+  readonly success: false;
+  readonly reason: string;
+};
+/**
+ * Configuration for a DocumentInstance
+ */
+interface DocumentInstanceConfig<TSchema extends Primitive.AnyPrimitive> {
+  readonly schema: TSchema;
+  readonly initial?: Primitive.InferSetInput<TSchema> | ((ctx: {
+    documentId: string;
+  }) => Effect.Effect<Primitive.InferSetInput<TSchema>>);
+  readonly maxTransactionHistory: number;
+  readonly snapshot: {
+    readonly interval: Duration.Duration;
+    readonly transactionThreshold: number;
+  };
+}
+/**
+ * Snapshot tracking state
+ */
+interface SnapshotTracking {
+  readonly lastSnapshotVersion: number;
+  readonly lastSnapshotTime: number;
+  readonly transactionsSinceSnapshot: number;
+}
+/**
+ * A DocumentInstance manages a single document's lifecycle
+ */
+interface DocumentInstance<TSchema extends Primitive.AnyPrimitive> {
+  /** The underlying ServerDocument */
+  readonly document: ServerDocument.ServerDocument<TSchema>;
+  /** PubSub for broadcasting messages to subscribers */
+  readonly pubsub: PubSub.PubSub<ServerBroadcast>;
+  /** Current snapshot tracking state */
+  readonly getSnapshotTracking: Effect.Effect<SnapshotTracking>;
+  /** Submit a transaction */
+  readonly submit: (transaction: Transaction.Transaction) => Effect.Effect<SubmitResult, ColdStorageError | HotStorageError>;
+  /** Save a snapshot to cold storage */
+  readonly saveSnapshot: () => Effect.Effect<void, ColdStorageError | HotStorageError>;
+  /** Check if snapshot should be triggered and save if needed */
+  readonly checkSnapshotTriggers: () => Effect.Effect<void, ColdStorageError | HotStorageError>;
+  /** Update last activity time (for external tracking) */
+  readonly touch: () => Effect.Effect<void>;
+  /** Get current document version */
+  readonly getVersion: () => number;
+  /** Get document snapshot */
+  readonly getSnapshot: () => {
+    state: unknown;
+    version: number;
+  };
+  /** Check if document has unsnapshot transactions that need persisting */
+  readonly needsSnapshot: () => Effect.Effect<boolean>;
+  /** Get the last activity timestamp for idle detection */
+  readonly getLastActivityTime: () => Effect.Effect<number>;
+}
+declare const DocumentInstance: {
+  make: <TSchema extends Primitive.AnyPrimitive>(documentId: string, config: DocumentInstanceConfig<TSchema>, coldStorage: ColdStorage, hotStorage: HotStorage) => Effect.Effect<DocumentInstance<TSchema>, ColdStorageError | HotStorageError>;
+};
+//#endregion
+export { DocumentInstance, SubmitResult };
+//# sourceMappingURL=DocumentInstance.d.cts.map

package/dist/DocumentInstance.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentInstance.d.cts","names":[],"sources":["../src/DocumentInstance.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAkDA;AASiB,KA/BL,YAAA,GA+BqB;EAAiB,SAAU,OAAA,EAAA,IAAA;EAET,SAAA,OAAA,EAAA,MAAA;CAA9B,GAAA;EAEY,SAAA,OAAA,EAAA,KAAA;EAAd,SAAO,MAAA,EAAA,MAAA;CAEoB;;;;AAE2C,UAhCxE,sBAgCwE,CAAA,gBAhCjC,SAAA,CAAU,YAgCuB,CAAA,CAAA;EAAmB,SAAA,MAAA,EA/BzF,OA+ByF;EAA/C,SAAO,OAAA,CAAA,EA7B9D,SAAA,CAAU,aA6BoD,CA7BtC,OA6BsC,CAAA,GAAA,CAAA,CAAA,GAAA,EAAA;IAEjB,UAAA,EAAA,MAAA;EAAmB,CAAA,EAAA,GA9B9B,MAAA,CAAO,MA8BuB,CA9BhB,SAAA,CAAU,aA8BM,CA9BQ,OA8BR,CAAA,CAAA,CAAA;EAAvC,SAAO,qBAAA,EAAA,MAAA;EAEsB,SAAA,QAAA,EAAA;IAAmB,SAAA,QAAA,EA7BxD,QAAA,CAAS,QA6B+C;IAAhC,SAAA,oBAAA,EAAA,MAAA;EAEvB,CAAA;;;;AAmcxB;AA1aqC,UAhDpB,gBAAA,CAgD8B;EAEd,SAAA,mBAAA,EAAA,MAAA;EAAvB,SAAA,gBAAA,EAAA,MAAA;EACK,SAAA,yBAAA,EAAA,MAAA;;;;;AAEgD,UA5C9C,gBA4C8C,CAAA,gBA5Cb,SAAA,CAAU,YA4CG,CAAA,CAAA;EAA5D;EAAa,SAAA,QAAA,EA1CK,cAAA,CAAe,cA0CpB,CA1CmC,OA0CnC,CAAA;;mBAxCG,MAAA,CAAO,OAAO;;gCAED,MAAA,CAAO,OAAO;;iCAEb,WAAA,CAAY,gBAAgB,MAAA,CAAO,OAAO,cAAc,mBAAmB;;+BAE7E,MAAA,CAAO,aAAa,mBAAmB;;wCAE9B,MAAA,CAAO,aAAa,mBAAmB;;wBAEvD,MAAA,CAAO;;;;;;;;;gCAMC,MAAA,CAAO;;sCAED,MAAA,CAAO;;cA2bhC;yBA1awB,SAAA,CAAU,0CAErC,uBAAuB,uBAClB,yBACD,eACX,MAAA,CAAO,OAAO,iBAAiB,UAAU,mBAAmB"}

package/dist/DocumentInstance.d.mts

@@ -0,0 +1,78 @@
+import { ColdStorageError, HotStorageError } from "./Errors.mjs";
+import { ServerBroadcast } from "./Protocol.mjs";
+import { ColdStorage } from "./ColdStorage.mjs";
+import { HotStorage } from "./HotStorage.mjs";
+import { Duration, Effect, PubSub } from "effect";
+import { Primitive, Transaction } from "@voidhash/mimic";
+import { ServerDocument } from "@voidhash/mimic/server";
+
+//#region src/DocumentInstance.d.ts
+
+/**
+ * Result of submitting a transaction
+ */
+type SubmitResult = {
+  readonly success: true;
+  readonly version: number;
+} | {
+  readonly success: false;
+  readonly reason: string;
+};
+/**
+ * Configuration for a DocumentInstance
+ */
+interface DocumentInstanceConfig<TSchema extends Primitive.AnyPrimitive> {
+  readonly schema: TSchema;
+  readonly initial?: Primitive.InferSetInput<TSchema> | ((ctx: {
+    documentId: string;
+  }) => Effect.Effect<Primitive.InferSetInput<TSchema>>);
+  readonly maxTransactionHistory: number;
+  readonly snapshot: {
+    readonly interval: Duration.Duration;
+    readonly transactionThreshold: number;
+  };
+}
+/**
+ * Snapshot tracking state
+ */
+interface SnapshotTracking {
+  readonly lastSnapshotVersion: number;
+  readonly lastSnapshotTime: number;
+  readonly transactionsSinceSnapshot: number;
+}
+/**
+ * A DocumentInstance manages a single document's lifecycle
+ */
+interface DocumentInstance<TSchema extends Primitive.AnyPrimitive> {
+  /** The underlying ServerDocument */
+  readonly document: ServerDocument.ServerDocument<TSchema>;
+  /** PubSub for broadcasting messages to subscribers */
+  readonly pubsub: PubSub.PubSub<ServerBroadcast>;
+  /** Current snapshot tracking state */
+  readonly getSnapshotTracking: Effect.Effect<SnapshotTracking>;
+  /** Submit a transaction */
+  readonly submit: (transaction: Transaction.Transaction) => Effect.Effect<SubmitResult, ColdStorageError | HotStorageError>;
+  /** Save a snapshot to cold storage */
+  readonly saveSnapshot: () => Effect.Effect<void, ColdStorageError | HotStorageError>;
+  /** Check if snapshot should be triggered and save if needed */
+  readonly checkSnapshotTriggers: () => Effect.Effect<void, ColdStorageError | HotStorageError>;
+  /** Update last activity time (for external tracking) */
+  readonly touch: () => Effect.Effect<void>;
+  /** Get current document version */
+  readonly getVersion: () => number;
+  /** Get document snapshot */
+  readonly getSnapshot: () => {
+    state: unknown;
+    version: number;
+  };
+  /** Check if document has unsnapshot transactions that need persisting */
+  readonly needsSnapshot: () => Effect.Effect<boolean>;
+  /** Get the last activity timestamp for idle detection */
+  readonly getLastActivityTime: () => Effect.Effect<number>;
+}
+declare const DocumentInstance: {
+  make: <TSchema extends Primitive.AnyPrimitive>(documentId: string, config: DocumentInstanceConfig<TSchema>, coldStorage: ColdStorage, hotStorage: HotStorage) => Effect.Effect<DocumentInstance<TSchema>, ColdStorageError | HotStorageError>;
+};
+//#endregion
+export { DocumentInstance, SubmitResult };
+//# sourceMappingURL=DocumentInstance.d.mts.map

package/dist/DocumentInstance.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocumentInstance.d.mts","names":[],"sources":["../src/DocumentInstance.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAkDA;AASiB,KA/BL,YAAA,GA+BqB;EAAiB,SAAU,OAAA,EAAA,IAAA;EAET,SAAA,OAAA,EAAA,MAAA;CAA9B,GAAA;EAEY,SAAA,OAAA,EAAA,KAAA;EAAd,SAAO,MAAA,EAAA,MAAA;CAEoB;;;;AAE2C,UAhCxE,sBAgCwE,CAAA,gBAhCjC,SAAA,CAAU,YAgCuB,CAAA,CAAA;EAAmB,SAAA,MAAA,EA/BzF,OA+ByF;EAA/C,SAAO,OAAA,CAAA,EA7B9D,SAAA,CAAU,aA6BoD,CA7BtC,OA6BsC,CAAA,GAAA,CAAA,CAAA,GAAA,EAAA;IAEjB,UAAA,EAAA,MAAA;EAAmB,CAAA,EAAA,GA9B9B,MAAA,CAAO,MA8BuB,CA9BhB,SAAA,CAAU,aA8BM,CA9BQ,OA8BR,CAAA,CAAA,CAAA;EAAvC,SAAO,qBAAA,EAAA,MAAA;EAEsB,SAAA,QAAA,EAAA;IAAmB,SAAA,QAAA,EA7BxD,QAAA,CAAS,QA6B+C;IAAhC,SAAA,oBAAA,EAAA,MAAA;EAEvB,CAAA;;;;AAmcxB;AA1aqC,UAhDpB,gBAAA,CAgD8B;EAEd,SAAA,mBAAA,EAAA,MAAA;EAAvB,SAAA,gBAAA,EAAA,MAAA;EACK,SAAA,yBAAA,EAAA,MAAA;;;;;AAEgD,UA5C9C,gBA4C8C,CAAA,gBA5Cb,SAAA,CAAU,YA4CG,CAAA,CAAA;EAA5D;EAAa,SAAA,QAAA,EA1CK,cAAA,CAAe,cA0CpB,CA1CmC,OA0CnC,CAAA;;mBAxCG,MAAA,CAAO,OAAO;;gCAED,MAAA,CAAO,OAAO;;iCAEb,WAAA,CAAY,gBAAgB,MAAA,CAAO,OAAO,cAAc,mBAAmB;;+BAE7E,MAAA,CAAO,aAAa,mBAAmB;;wCAE9B,MAAA,CAAO,aAAa,mBAAmB;;wBAEvD,MAAA,CAAO;;;;;;;;;gCAMC,MAAA,CAAO;;sCAED,MAAA,CAAO;;cA2bhC;yBA1awB,SAAA,CAAU,0CAErC,uBAAuB,uBAClB,yBACD,eACX,MAAA,CAAO,OAAO,iBAAiB,UAAU,mBAAmB"}

package/dist/DocumentInstance.mjs

@@ -0,0 +1,264 @@
+import { documentsActive, documentsCreated, documentsRestored, storageSnapshotLatency, storageSnapshots, storageVersionGaps, storageWalAppends, transactionsLatency, transactionsProcessed, transactionsRejected, walAppendFailures } from "./Metrics.mjs";
+import { Duration, Effect, Metric, PubSub, Ref } from "effect";
+import { Document } from "@voidhash/mimic";
+import { ServerDocument } from "@voidhash/mimic/server";
+
+//#region src/DocumentInstance.ts
+/**
+* @voidhash/mimic-effect - DocumentInstance
+*
+* Manages the lifecycle of a single document including:
+* - Restoration from storage (cold storage + WAL replay)
+* - Transaction submission with WAL persistence
+* - Snapshot saving and trigger checking
+*
+* Used by both MimicServerEngine (single-node) and MimicClusterServerEngine (clustered).
+*/
+/**
+* Create a DocumentInstance for a single document.
+*
+* This handles:
+* - Loading from cold storage or computing initial state
+* - Persisting initial state immediately (crash safety)
+* - Replaying WAL entries
+* - Transaction submission with WAL persistence
+* - Snapshot saving
+*/
+const make = (documentId, config, coldStorage, hotStorage) => Effect.gen(function* () {
+	const SCHEMA_VERSION = 1;
+	const storedDoc = yield* coldStorage.load(documentId);
+	let initialState;
+	let initial;
+	let initialVersion = 0;
+	if (storedDoc) {
+		initialState = storedDoc.state;
+		initialVersion = storedDoc.version;
+	} else initial = yield* computeInitialState(config, documentId);
+	const pubsub = yield* PubSub.unbounded();
+	const lastSnapshotVersionRef = yield* Ref.make(initialVersion);
+	const lastSnapshotTimeRef = yield* Ref.make(Date.now());
+	const transactionsSinceSnapshotRef = yield* Ref.make(0);
+	const lastActivityTimeRef = yield* Ref.make(Date.now());
+	const document = ServerDocument.make({
+		schema: config.schema,
+		initial,
+		initialState,
+		initialVersion,
+		maxTransactionHistory: config.maxTransactionHistory,
+		onBroadcast: (message) => {
+			Effect.runSync(PubSub.publish(pubsub, {
+				type: "transaction",
+				transaction: message.transaction,
+				version: message.version
+			}));
+		},
+		onRejection: (transactionId, reason) => {
+			Effect.runSync(PubSub.publish(pubsub, {
+				type: "error",
+				transactionId,
+				reason
+			}));
+		}
+	});
+	if (!storedDoc) {
+		const initialStoredDoc = createStoredDocument(document.get(), 0, SCHEMA_VERSION);
+		yield* coldStorage.save(documentId, initialStoredDoc);
+		yield* Effect.logDebug("Initial state persisted to cold storage", { documentId });
+	}
+	const walEntries = yield* hotStorage.getEntries(documentId, initialVersion);
+	yield* verifyWalContinuity(documentId, walEntries, initialVersion);
+	yield* replayWalEntries(documentId, document, walEntries);
+	if (storedDoc) yield* Metric.increment(documentsRestored);
+	else yield* Metric.increment(documentsCreated);
+	yield* Metric.incrementBy(documentsActive, 1);
+	const getSnapshotTracking = Effect.gen(function* () {
+		return {
+			lastSnapshotVersion: yield* Ref.get(lastSnapshotVersionRef),
+			lastSnapshotTime: yield* Ref.get(lastSnapshotTimeRef),
+			transactionsSinceSnapshot: yield* Ref.get(transactionsSinceSnapshotRef)
+		};
+	});
+	const saveSnapshot = Effect.fn("document.snapshot.save")(function* () {
+		var _baseSnapshot$version;
+		const targetVersion = document.getVersion();
+		if (targetVersion <= (yield* Ref.get(lastSnapshotVersionRef))) return;
+		const snapshotStartTime = Date.now();
+		const baseSnapshot = yield* coldStorage.load(documentId);
+		const baseVersion = (_baseSnapshot$version = baseSnapshot === null || baseSnapshot === void 0 ? void 0 : baseSnapshot.version) !== null && _baseSnapshot$version !== void 0 ? _baseSnapshot$version : 0;
+		const baseState = baseSnapshot === null || baseSnapshot === void 0 ? void 0 : baseSnapshot.state;
+		const walEntries$1 = yield* hotStorage.getEntries(documentId, baseVersion);
+		const snapshotResult = computeSnapshotState(config.schema, baseState, walEntries$1, targetVersion);
+		if (!snapshotResult) return;
+		const currentLastSnapshot = yield* Ref.get(lastSnapshotVersionRef);
+		if (snapshotResult.version <= currentLastSnapshot) return;
+		const storedDoc$1 = createStoredDocument(snapshotResult.state, snapshotResult.version, SCHEMA_VERSION);
+		yield* coldStorage.save(documentId, storedDoc$1);
+		const snapshotDuration = Date.now() - snapshotStartTime;
+		yield* Metric.increment(storageSnapshots);
+		yield* Metric.update(storageSnapshotLatency, snapshotDuration);
+		yield* Ref.set(lastSnapshotVersionRef, snapshotResult.version);
+		yield* Ref.set(lastSnapshotTimeRef, Date.now());
+		yield* Ref.set(transactionsSinceSnapshotRef, 0);
+		yield* Effect.catchAll(hotStorage.truncate(documentId, snapshotResult.version), (e) => Effect.logWarning("WAL truncate failed - will retry on next snapshot", {
+			documentId,
+			version: snapshotResult.version,
+			error: e
+		}));
+	});
+	const checkSnapshotTriggers = Effect.fn("document.snapshot.check-triggers")(function* () {
+		if (shouldTriggerSnapshot(yield* Ref.get(transactionsSinceSnapshotRef), yield* Ref.get(lastSnapshotTimeRef), config.snapshot)) yield* saveSnapshot();
+	});
+	const submit = Effect.fn("document.transaction.submit")(function* (transaction) {
+		const submitStartTime = Date.now();
+		yield* Ref.set(lastActivityTimeRef, Date.now());
+		const validation = document.validate(transaction);
+		if (!validation.valid) {
+			yield* Metric.increment(transactionsRejected);
+			const latency$1 = Date.now() - submitStartTime;
+			yield* Metric.update(transactionsLatency, latency$1);
+			return {
+				success: false,
+				reason: validation.reason
+			};
+		}
+		const walEntry = {
+			transaction,
+			version: validation.nextVersion,
+			timestamp: Date.now()
+		};
+		const appendResult = yield* Effect.either(hotStorage.appendWithCheck(documentId, walEntry, validation.nextVersion));
+		if (appendResult._tag === "Left") {
+			yield* Effect.logError("WAL append failed", {
+				documentId,
+				version: validation.nextVersion,
+				error: appendResult.left
+			});
+			yield* Metric.increment(walAppendFailures);
+			const latency$1 = Date.now() - submitStartTime;
+			yield* Metric.update(transactionsLatency, latency$1);
+			return {
+				success: false,
+				reason: "Storage unavailable. Please retry."
+			};
+		}
+		document.apply(transaction);
+		const latency = Date.now() - submitStartTime;
+		yield* Metric.update(transactionsLatency, latency);
+		yield* Metric.increment(transactionsProcessed);
+		yield* Metric.increment(storageWalAppends);
+		yield* Ref.update(transactionsSinceSnapshotRef, (n) => n + 1);
+		yield* checkSnapshotTriggers();
+		return {
+			success: true,
+			version: validation.nextVersion
+		};
+	});
+	const touch = Effect.fn("document.touch")(function* () {
+		yield* Ref.set(lastActivityTimeRef, Date.now());
+	});
+	const needsSnapshot = () => Effect.map(Ref.get(transactionsSinceSnapshotRef), (n) => n > 0);
+	const getLastActivityTime = () => Ref.get(lastActivityTimeRef);
+	return {
+		document,
+		pubsub,
+		getSnapshotTracking,
+		submit,
+		saveSnapshot,
+		checkSnapshotTriggers,
+		touch,
+		getVersion: () => document.getVersion(),
+		getSnapshot: () => document.getSnapshot(),
+		needsSnapshot,
+		getLastActivityTime
+	};
+});
+/**
+* Compute initial state for a new document.
+*/
+const computeInitialState = (config, documentId) => {
+	if (config.initial === void 0) return Effect.succeed(void 0);
+	if (typeof config.initial === "function") return config.initial({ documentId });
+	return Effect.succeed(config.initial);
+};
+/**
+* Verify WAL continuity and log warnings for any gaps.
+*/
+const verifyWalContinuity = Effect.fn("document.wal.verify")(function* (documentId, walEntries, baseVersion) {
+	if (walEntries.length === 0) return;
+	const firstWalVersion = walEntries[0].version;
+	const expectedFirst = baseVersion + 1;
+	if (firstWalVersion !== expectedFirst) {
+		yield* Effect.logWarning("WAL version gap detected", {
+			documentId,
+			snapshotVersion: baseVersion,
+			firstWalVersion,
+			expectedFirst
+		});
+		yield* Metric.increment(storageVersionGaps);
+	}
+	for (let i = 1; i < walEntries.length; i++) {
+		const prev = walEntries[i - 1].version;
+		const curr = walEntries[i].version;
+		if (curr !== prev + 1) yield* Effect.logWarning("WAL internal gap detected", {
+			documentId,
+			previousVersion: prev,
+			currentVersion: curr
+		});
+	}
+});
+/**
+* Replay WAL entries onto a ServerDocument.
+*/
+const replayWalEntries = Effect.fn("document.wal.replay")(function* (documentId, document, walEntries) {
+	for (const entry of walEntries) {
+		const result = document.submit(entry.transaction);
+		if (!result.success) yield* Effect.logWarning("Skipping corrupted WAL entry", {
+			documentId,
+			version: entry.version,
+			reason: result.reason
+		});
+	}
+});
+/**
+* Compute snapshot state by replaying WAL entries on a base state.
+*/
+const computeSnapshotState = (schema, baseState, walEntries, targetVersion) => {
+	const relevantEntries = walEntries.filter((e) => e.version <= targetVersion);
+	if (relevantEntries.length === 0 && baseState === void 0) return;
+	let snapshotState = baseState;
+	for (const entry of relevantEntries) {
+		const tempDoc = Document.make(schema, { initialState: snapshotState });
+		tempDoc.apply(entry.transaction.ops);
+		snapshotState = tempDoc.get();
+	}
+	if (snapshotState === void 0) return;
+	const snapshotVersion = relevantEntries.length > 0 ? relevantEntries[relevantEntries.length - 1].version : 0;
+	return {
+		state: snapshotState,
+		version: snapshotVersion
+	};
+};
+/**
+* Check if a snapshot should be triggered.
+*/
+const shouldTriggerSnapshot = (transactionsSinceSnapshot, lastSnapshotTime, config) => {
+	const now = Date.now();
+	const intervalMs = Duration.toMillis(config.interval);
+	if (transactionsSinceSnapshot >= config.transactionThreshold) return true;
+	if (now - lastSnapshotTime >= intervalMs) return true;
+	return false;
+};
+/**
+* Create a StoredDocument for persistence.
+*/
+const createStoredDocument = (state, version, schemaVersion) => ({
+	state,
+	version,
+	schemaVersion,
+	savedAt: Date.now()
+});
+const DocumentInstance = { make };
+
+//#endregion
+export { DocumentInstance };
+//# sourceMappingURL=DocumentInstance.mjs.map