fabricjs-document-engine 0.5.0 → 0.7.0

package/dist/state/document-state-store.d.cts

@@ -0,0 +1,28 @@
+import { AssetWarning } from "../assets/asset-pipeline.cjs";
+import { DocumentEngineError } from "../engine/errors.cjs";
+import { SaveStatus } from "../save/save-controller.cjs";
+import { DocumentEngine } from "../engine/create-document-engine.cjs";
+//#region src/state/document-state-store.d.ts
+export interface DocumentState {
+  documentId: string;
+  isLoading: boolean;
+  loadError: DocumentEngineError | undefined;
+  saveStatus: SaveStatus;
+  isDirty: boolean;
+  isSaving: boolean;
+  revision: number;
+  lastSavedAt: string | undefined;
+  saveError: DocumentEngineError | undefined;
+  canUndo: boolean;
+  canRedo: boolean;
+  undoLabel: string | undefined;
+  redoLabel: string | undefined;
+  assetWarnings: AssetWarning[];
+}
+export interface DocumentStateStore {
+  getSnapshot(): DocumentState;
+  subscribe(listener: () => void): () => void;
+  destroy(): void;
+}
+export declare function createDocumentStateStore(engine: DocumentEngine): DocumentStateStore;
+//#endregion

package/dist/state/document-state-store.d.ts

@@ -0,0 +1,28 @@
+import { AssetWarning } from "../assets/asset-pipeline.js";
+import { DocumentEngineError } from "../engine/errors.js";
+import { SaveStatus } from "../save/save-controller.js";
+import { DocumentEngine } from "../engine/create-document-engine.js";
+//#region src/state/document-state-store.d.ts
+export interface DocumentState {
+  documentId: string;
+  isLoading: boolean;
+  loadError: DocumentEngineError | undefined;
+  saveStatus: SaveStatus;
+  isDirty: boolean;
+  isSaving: boolean;
+  revision: number;
+  lastSavedAt: string | undefined;
+  saveError: DocumentEngineError | undefined;
+  canUndo: boolean;
+  canRedo: boolean;
+  undoLabel: string | undefined;
+  redoLabel: string | undefined;
+  assetWarnings: AssetWarning[];
+}
+export interface DocumentStateStore {
+  getSnapshot(): DocumentState;
+  subscribe(listener: () => void): () => void;
+  destroy(): void;
+}
+export declare function createDocumentStateStore(engine: DocumentEngine): DocumentStateStore;
+//#endregion

package/dist/state/document-state-store.js

@@ -0,0 +1,114 @@
+//#region src/state/document-state-store.ts
+function initialState(engine) {
+	const saveState = engine.getSaveState();
+	const history = engine.getHistory();
+	return {
+		documentId: engine.getDocumentInfo().id,
+		isLoading: false,
+		loadError: void 0,
+		saveStatus: saveState.status,
+		isDirty: saveState.isDirty,
+		isSaving: saveState.isSaving,
+		revision: saveState.revision,
+		lastSavedAt: saveState.lastSavedAt,
+		saveError: saveState.error,
+		canUndo: history.undo.length > 0,
+		canRedo: history.redo.length > 0,
+		undoLabel: history.undo[0],
+		redoLabel: history.redo[0],
+		assetWarnings: []
+	};
+}
+function withLiveEngineValues(engine, previous) {
+	return {
+		...previous,
+		...initialState(engine),
+		isLoading: previous.isLoading,
+		loadError: previous.loadError,
+		assetWarnings: previous.assetWarnings
+	};
+}
+function isSameState(first, second) {
+	return Object.keys(first).every((key) => first[key] === second[key]);
+}
+function createDocumentStateStore(engine) {
+	let state = initialState(engine);
+	const listeners = /* @__PURE__ */ new Set();
+	let detachFromEngine;
+	function update(changes) {
+		const next = {
+			...state,
+			...changes
+		};
+		if (isSameState(state, next)) return;
+		state = next;
+		for (const listener of [...listeners]) listener();
+	}
+	function attachToEngine() {
+		const unsubscribers = [
+			engine.on("load:start", () => update({
+				isLoading: true,
+				loadError: void 0
+			})),
+			engine.on("load:success", ({ warnings }) => update({
+				isLoading: false,
+				assetWarnings: warnings
+			})),
+			engine.on("load:error", ({ error }) => {
+				if (error.code !== "LOAD_ABORTED") update({
+					isLoading: false,
+					loadError: error
+				});
+			}),
+			engine.on("document:change", ({ documentId }) => update({
+				documentId,
+				loadError: void 0
+			})),
+			engine.on("assets:warning", ({ warnings }) => update({ assetWarnings: warnings })),
+			engine.on("save:status", (saveState) => update({
+				saveStatus: saveState.status,
+				isDirty: saveState.isDirty,
+				isSaving: saveState.isSaving,
+				revision: saveState.revision,
+				lastSavedAt: saveState.lastSavedAt,
+				saveError: saveState.error
+			})),
+			engine.on("history:change", (history) => update({
+				canUndo: history.canUndo,
+				canRedo: history.canRedo,
+				undoLabel: history.undoLabel,
+				redoLabel: history.redoLabel
+			}))
+		];
+		return () => unsubscribers.forEach((unsubscribe) => unsubscribe());
+	}
+	function refreshWhileDetached() {
+		if (detachFromEngine) return;
+		const fresh = withLiveEngineValues(engine, state);
+		if (!isSameState(state, fresh)) state = fresh;
+	}
+	return {
+		getSnapshot() {
+			refreshWhileDetached();
+			return state;
+		},
+		subscribe(listener) {
+			refreshWhileDetached();
+			listeners.add(listener);
+			detachFromEngine ?? (detachFromEngine = attachToEngine());
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size > 0) return;
+				detachFromEngine?.();
+				detachFromEngine = void 0;
+			};
+		},
+		destroy() {
+			listeners.clear();
+			detachFromEngine?.();
+			detachFromEngine = void 0;
+		}
+	};
+}
+//#endregion
+export { createDocumentStateStore };

package/dist/storage/key-value-storage.cjs

@@ -1,4 +1,5 @@
 const require_errors = require("../engine/errors.cjs");
+const require_document_version = require("../versions/document-version.cjs");
 //#region src/storage/key-value-storage.ts
 function readRevision(json) {
 	if (json === null) return 0;
@@ -6,7 +7,19 @@ function readRevision(json) {
 	return typeof revision === "number" ? revision : 0;
 }
 function createKeyValueStorage(store, prefix) {
+	const versionMarker = "::version::";
 	const keyFor = (id) => `${prefix}${id}`;
+	const versionPrefixFor = (documentId) => `${keyFor(documentId)}${versionMarker}`;
+	const versionKeyFor = (documentId, versionId) => `${versionPrefixFor(documentId)}${versionId}`;
+	function readVersion(documentId, versionId) {
+		const json = store.read(versionKeyFor(documentId, versionId));
+		if (json === null) throw new require_errors.DocumentEngineError("VERSION_NOT_FOUND", `Document "${documentId}" has no version "${versionId}"`);
+		return JSON.parse(json);
+	}
+	function versionKeysOf(documentId) {
+		const versionPrefix = versionPrefixFor(documentId);
+		return store.keys().filter((key) => key.startsWith(versionPrefix));
+	}
 	return {
 		async loadDocument(id) {
 			const json = store.read(keyFor(id));
@@ -24,10 +37,23 @@ function createKeyValueStorage(store, prefix) {
 			return { revision };
 		},
 		async listDocuments() {
-			return store.keys().filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+			return store.keys().filter((key) => key.startsWith(prefix) && !key.includes(versionMarker)).map((key) => key.slice(prefix.length));
 		},
 		async deleteDocument(id) {
+			versionKeysOf(id).forEach((key) => store.remove(key));
 			store.remove(keyFor(id));
+		},
+		async saveVersion(version) {
+			store.write(versionKeyFor(version.documentId, version.id), JSON.stringify(version));
+		},
+		async listVersions(documentId) {
+			return versionKeysOf(documentId).map((key) => require_document_version.summarize(JSON.parse(store.read(key) ?? "null"))).sort(require_document_version.newestFirst);
+		},
+		async loadVersion(documentId, versionId) {
+			return readVersion(documentId, versionId);
+		},
+		async deleteVersion(documentId, versionId) {
+			store.remove(versionKeyFor(documentId, versionId));
 		}
 	};
 }

package/dist/storage/key-value-storage.d.cts

@@ -1,3 +1,4 @@
+import { VersionStorage } from "../versions/document-version.cjs";
 import { DocumentStorage } from "./storage-contract.cjs";
 //#region src/storage/key-value-storage.d.ts
 export interface KeyValueStore {
@@ -6,7 +7,7 @@ export interface KeyValueStore {
   remove(key: string): void;
   keys(): string[];
 }
-export interface ManagedDocumentStorage extends DocumentStorage {
+export interface ManagedDocumentStorage extends DocumentStorage, VersionStorage {
   listDocuments(): Promise<string[]>;
   deleteDocument(id: string): Promise<void>;
 }

package/dist/storage/key-value-storage.d.ts

@@ -1,3 +1,4 @@
+import { VersionStorage } from "../versions/document-version.js";
 import { DocumentStorage } from "./storage-contract.js";
 //#region src/storage/key-value-storage.d.ts
 export interface KeyValueStore {
@@ -6,7 +7,7 @@ export interface KeyValueStore {
   remove(key: string): void;
   keys(): string[];
 }
-export interface ManagedDocumentStorage extends DocumentStorage {
+export interface ManagedDocumentStorage extends DocumentStorage, VersionStorage {
   listDocuments(): Promise<string[]>;
   deleteDocument(id: string): Promise<void>;
 }

package/dist/storage/key-value-storage.js

@@ -1,4 +1,5 @@
 import { DocumentEngineError, createConflictError } from "../engine/errors.js";
+import { newestFirst, summarize } from "../versions/document-version.js";
 //#region src/storage/key-value-storage.ts
 function readRevision(json) {
 	if (json === null) return 0;
@@ -6,7 +7,19 @@ function readRevision(json) {
 	return typeof revision === "number" ? revision : 0;
 }
 function createKeyValueStorage(store, prefix) {
+	const versionMarker = "::version::";
 	const keyFor = (id) => `${prefix}${id}`;
+	const versionPrefixFor = (documentId) => `${keyFor(documentId)}${versionMarker}`;
+	const versionKeyFor = (documentId, versionId) => `${versionPrefixFor(documentId)}${versionId}`;
+	function readVersion(documentId, versionId) {
+		const json = store.read(versionKeyFor(documentId, versionId));
+		if (json === null) throw new DocumentEngineError("VERSION_NOT_FOUND", `Document "${documentId}" has no version "${versionId}"`);
+		return JSON.parse(json);
+	}
+	function versionKeysOf(documentId) {
+		const versionPrefix = versionPrefixFor(documentId);
+		return store.keys().filter((key) => key.startsWith(versionPrefix));
+	}
 	return {
 		async loadDocument(id) {
 			const json = store.read(keyFor(id));
@@ -24,10 +37,23 @@ function createKeyValueStorage(store, prefix) {
 			return { revision };
 		},
 		async listDocuments() {
-			return store.keys().filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+			return store.keys().filter((key) => key.startsWith(prefix) && !key.includes(versionMarker)).map((key) => key.slice(prefix.length));
 		},
 		async deleteDocument(id) {
+			versionKeysOf(id).forEach((key) => store.remove(key));
 			store.remove(keyFor(id));
+		},
+		async saveVersion(version) {
+			store.write(versionKeyFor(version.documentId, version.id), JSON.stringify(version));
+		},
+		async listVersions(documentId) {
+			return versionKeysOf(documentId).map((key) => summarize(JSON.parse(store.read(key) ?? "null"))).sort(newestFirst);
+		},
+		async loadVersion(documentId, versionId) {
+			return readVersion(documentId, versionId);
+		},
+		async deleteVersion(documentId, versionId) {
+			store.remove(versionKeyFor(documentId, versionId));
 		}
 	};
 }

package/dist/storage.d.cts

@@ -1,5 +1,6 @@
+import { DocumentVersion, VersionStorage, VersionSummary } from "./versions/document-version.cjs";
 import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-contract.cjs";
 import { KeyValueStore, ManagedDocumentStorage, createKeyValueStorage } from "./storage/key-value-storage.cjs";
 import { createMemoryStorage } from "./storage/memory-storage.cjs";
 import { LocalStorageOptions, createLocalStorage } from "./storage/local-storage.cjs";
-export { type DocumentStorage, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, createKeyValueStorage, createLocalStorage, createMemoryStorage };
+export { type DocumentStorage, type DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage };

package/dist/storage.d.ts

@@ -1,5 +1,6 @@
+import { DocumentVersion, VersionStorage, VersionSummary } from "./versions/document-version.js";
 import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-contract.js";
 import { KeyValueStore, ManagedDocumentStorage, createKeyValueStorage } from "./storage/key-value-storage.js";
 import { createMemoryStorage } from "./storage/memory-storage.js";
 import { LocalStorageOptions, createLocalStorage } from "./storage/local-storage.js";
-export { type DocumentStorage, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, createKeyValueStorage, createLocalStorage, createMemoryStorage };
+export { type DocumentStorage, type DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage };

package/dist/versions/document-version.cjs

@@ -0,0 +1,20 @@
+//#region src/versions/document-version.ts
+function summarize(version) {
+	const { document: _document, ...summary } = version;
+	return summary;
+}
+function newestFirst(first, second) {
+	return second.createdAt.localeCompare(first.createdAt);
+}
+function versionsToPrune(versions, keepAuto) {
+	return versions.filter((version) => version.kind === "auto").sort(newestFirst).slice(Math.max(0, keepAuto));
+}
+function supportsVersions(storage) {
+	const candidate = storage;
+	return typeof candidate?.saveVersion === "function" && typeof candidate.listVersions === "function" && typeof candidate.loadVersion === "function" && typeof candidate.deleteVersion === "function";
+}
+//#endregion
+exports.newestFirst = newestFirst;
+exports.summarize = summarize;
+exports.supportsVersions = supportsVersions;
+exports.versionsToPrune = versionsToPrune;

package/dist/versions/document-version.d.cts

@@ -0,0 +1,25 @@
+import { FabricDocument } from "../document/document-format.cjs";
+//#region src/versions/document-version.d.ts
+export type VersionKind = "named" | "auto";
+export interface VersionSummary {
+  id: string;
+  documentId: string;
+  name: string;
+  kind: VersionKind;
+  createdAt: string;
+  revision: number;
+}
+export interface DocumentVersion extends VersionSummary {
+  document: FabricDocument;
+}
+export interface VersionStorage {
+  saveVersion(version: DocumentVersion): Promise<void>;
+  listVersions(documentId: string): Promise<VersionSummary[]>;
+  loadVersion(documentId: string, versionId: string): Promise<DocumentVersion>;
+  deleteVersion(documentId: string, versionId: string): Promise<void>;
+}
+export interface VersionOptions {
+  keepAuto?: number;
+  autoEvery?: number;
+}
+//#endregion

package/dist/versions/document-version.d.ts

@@ -0,0 +1,25 @@
+import { FabricDocument } from "../document/document-format.js";
+//#region src/versions/document-version.d.ts
+export type VersionKind = "named" | "auto";
+export interface VersionSummary {
+  id: string;
+  documentId: string;
+  name: string;
+  kind: VersionKind;
+  createdAt: string;
+  revision: number;
+}
+export interface DocumentVersion extends VersionSummary {
+  document: FabricDocument;
+}
+export interface VersionStorage {
+  saveVersion(version: DocumentVersion): Promise<void>;
+  listVersions(documentId: string): Promise<VersionSummary[]>;
+  loadVersion(documentId: string, versionId: string): Promise<DocumentVersion>;
+  deleteVersion(documentId: string, versionId: string): Promise<void>;
+}
+export interface VersionOptions {
+  keepAuto?: number;
+  autoEvery?: number;
+}
+//#endregion

package/dist/versions/document-version.js

@@ -0,0 +1,17 @@
+//#region src/versions/document-version.ts
+function summarize(version) {
+	const { document: _document, ...summary } = version;
+	return summary;
+}
+function newestFirst(first, second) {
+	return second.createdAt.localeCompare(first.createdAt);
+}
+function versionsToPrune(versions, keepAuto) {
+	return versions.filter((version) => version.kind === "auto").sort(newestFirst).slice(Math.max(0, keepAuto));
+}
+function supportsVersions(storage) {
+	const candidate = storage;
+	return typeof candidate?.saveVersion === "function" && typeof candidate.listVersions === "function" && typeof candidate.loadVersion === "function" && typeof candidate.deleteVersion === "function";
+}
+//#endregion
+export { newestFirst, summarize, supportsVersions, versionsToPrune };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fabricjs-document-engine",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Turn an existing Fabric.js canvas into a dependable editable document: stable object ids, versioned save and load, undo and redo, safe autosave with conflict protection, custom objects and clear errors.",
   "keywords": [
     "fabric",
@@ -19,7 +19,9 @@
     "editor",
     "typescript",
     "storage",
-    "recovery"
+    "recovery",
+    "react",
+    "react hooks"
   ],
   "license": "MIT",
   "author": "Sohail Khan (https://me.jscrate.dev)",
@@ -64,10 +66,20 @@
         "default": "./dist/recovery.cjs"
       }
     },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsdown && npm run lint:publint && npm run lint:attw",
+    "build": "tsdown && node scripts/verify-build.mjs && npm run lint:publint && npm run lint:attw",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.tools.json",
     "test": "vitest run",
@@ -80,7 +92,8 @@
     "release": "changeset publish"
   },
   "peerDependencies": {
-    "fabric": "^6.0.0 || ^7.0.0"
+    "fabric": "^6.0.0 || ^7.0.0",
+    "react": "^18.0.0 || ^19.0.0"
   },
   "publishConfig": {
     "access": "public",
@@ -101,13 +114,22 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@changesets/cli": "^3.0.3",
     "@types/node": "^22.20.4",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@vitest/browser-playwright": "^5.0.2",
     "fabric": "^7.4.0",
     "fabric6": "npm:fabric@^6.9.1",
     "playwright": "^1.63.0",
     "publint": "^0.3.24",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "tsdown": "^0.23.0",
     "typescript": "^5.9.3",
     "vitest": "^5.0.2"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }