fabricjs-document-engine 0.7.0 → 1.0.0

package/dist/storage/verify-storage-adapter.cjs

@@ -0,0 +1,125 @@
+require("../document/document-format.cjs");
+const require_ids = require("../document/ids.cjs");
+const require_document_version = require("../versions/document-version.cjs");
+//#region src/storage/verify-storage-adapter.ts
+function sampleDocument(id, revision, label) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		schemaVersion: 1,
+		id,
+		createdAt: now,
+		updatedAt: now,
+		revision,
+		canvas: {
+			width: 100,
+			height: 100
+		},
+		objects: [{
+			type: "Rect",
+			id: `${id}-shape`,
+			width: 10,
+			height: 10,
+			fill: label
+		}],
+		metadata: { label }
+	};
+}
+function codeOf(error) {
+	return error?.code;
+}
+async function verifyStorageAdapter(storage) {
+	const checks = [];
+	const documentId = `adapter-check-${require_ids.createId()}`;
+	const signal = new AbortController().signal;
+	let revision = 0;
+	async function check(name, work) {
+		try {
+			const problem = await work();
+			checks.push(problem === void 0 ? {
+				name,
+				passed: true
+			} : {
+				name,
+				passed: false,
+				message: problem
+			});
+			return problem === void 0;
+		} catch (error) {
+			checks.push({
+				name,
+				passed: false,
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return false;
+		}
+	}
+	async function saveAt(expectedRevision, label) {
+		return (await storage.saveDocument(sampleDocument(documentId, (expectedRevision ?? revision) + 1, label), {
+			expectedRevision,
+			signal
+		}))?.revision ?? (expectedRevision ?? revision) + 1;
+	}
+	if (await check("saves a new document when expectedRevision is 0", async () => {
+		revision = await saveAt(0, "first");
+		return revision > 0 ? void 0 : `returned revision ${revision}, expected a number above 0`;
+	})) {
+		await check("loads the document it saved", async () => {
+			const loaded = await storage.loadDocument(documentId);
+			if (loaded?.id !== documentId) return `loaded id ${String(loaded?.id)}, expected ${documentId}`;
+			if (loaded.metadata?.label !== "first") return "loaded content differs from what was saved";
+		});
+		await check("refuses a save based on an old revision with code SAVE_CONFLICT", async () => {
+			try {
+				await saveAt(revision - 1, "stale");
+			} catch (error) {
+				return codeOf(error) === "SAVE_CONFLICT" ? void 0 : `rejected with code ${String(codeOf(error))} instead of SAVE_CONFLICT`;
+			}
+			return "the stale save was accepted, so an older tab could overwrite newer work";
+		});
+		await check("accepts a save based on the current revision", async () => {
+			const next = await saveAt(revision, "second");
+			if (next <= revision) return `revision went from ${revision} to ${next}, it must increase`;
+			revision = next;
+			return (await storage.loadDocument(documentId))?.metadata?.label === "second" ? void 0 : "the newer content was not stored";
+		});
+		await check("overwrites when expectedRevision is null", async () => {
+			revision = await saveAt(null, "overwritten");
+			return (await storage.loadDocument(documentId))?.metadata?.label === "overwritten" ? void 0 : "the overwrite was not stored";
+		});
+	}
+	await check("rejects loading a document that does not exist", async () => {
+		try {
+			const missing = await storage.loadDocument(`adapter-check-missing-${require_ids.createId()}`);
+			return missing === void 0 || missing === null ? "resolved with nothing instead of rejecting, which hides a missing document" : "returned a document for an id that was never saved";
+		} catch {
+			return;
+		}
+	});
+	if (require_document_version.supportsVersions(storage)) {
+		const version = {
+			id: `version-${require_ids.createId()}`,
+			documentId,
+			name: "Adapter check",
+			kind: "named",
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			revision,
+			document: sampleDocument(documentId, revision, "versioned")
+		};
+		await check("keeps, lists, loads and deletes versions", async () => {
+			await storage.saveVersion(version);
+			const listed = await storage.listVersions(documentId);
+			if (!listed.some((summary) => summary.id === version.id)) return "listVersions did not include the saved version";
+			if (listed.some((summary) => "document" in summary)) return "listVersions should return summaries without the document";
+			if ((await storage.loadVersion(documentId, version.id)).document.metadata.label !== "versioned") return "loadVersion returned different content";
+			await storage.deleteVersion(documentId, version.id);
+			return (await storage.listVersions(documentId)).some((summary) => summary.id === version.id) ? "deleteVersion did not remove the version" : void 0;
+		});
+	}
+	await storage.deleteDocument?.(documentId).catch(() => void 0);
+	return {
+		ok: checks.every((result) => result.passed),
+		checks
+	};
+}
+//#endregion
+exports.verifyStorageAdapter = verifyStorageAdapter;

package/dist/storage/verify-storage-adapter.d.cts

@@ -0,0 +1,13 @@
+import { DocumentStorage } from "./storage-contract.cjs";
+//#region src/storage/verify-storage-adapter.d.ts
+export interface AdapterCheck {
+  name: string;
+  passed: boolean;
+  message?: string;
+}
+export interface AdapterReport {
+  ok: boolean;
+  checks: AdapterCheck[];
+}
+export declare function verifyStorageAdapter(storage: DocumentStorage): Promise<AdapterReport>;
+//#endregion

package/dist/storage/verify-storage-adapter.d.ts

@@ -0,0 +1,13 @@
+import { DocumentStorage } from "./storage-contract.js";
+//#region src/storage/verify-storage-adapter.d.ts
+export interface AdapterCheck {
+  name: string;
+  passed: boolean;
+  message?: string;
+}
+export interface AdapterReport {
+  ok: boolean;
+  checks: AdapterCheck[];
+}
+export declare function verifyStorageAdapter(storage: DocumentStorage): Promise<AdapterReport>;
+//#endregion

package/dist/storage/verify-storage-adapter.js

@@ -0,0 +1,125 @@
+import "../document/document-format.js";
+import { createId } from "../document/ids.js";
+import { supportsVersions } from "../versions/document-version.js";
+//#region src/storage/verify-storage-adapter.ts
+function sampleDocument(id, revision, label) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		schemaVersion: 1,
+		id,
+		createdAt: now,
+		updatedAt: now,
+		revision,
+		canvas: {
+			width: 100,
+			height: 100
+		},
+		objects: [{
+			type: "Rect",
+			id: `${id}-shape`,
+			width: 10,
+			height: 10,
+			fill: label
+		}],
+		metadata: { label }
+	};
+}
+function codeOf(error) {
+	return error?.code;
+}
+async function verifyStorageAdapter(storage) {
+	const checks = [];
+	const documentId = `adapter-check-${createId()}`;
+	const signal = new AbortController().signal;
+	let revision = 0;
+	async function check(name, work) {
+		try {
+			const problem = await work();
+			checks.push(problem === void 0 ? {
+				name,
+				passed: true
+			} : {
+				name,
+				passed: false,
+				message: problem
+			});
+			return problem === void 0;
+		} catch (error) {
+			checks.push({
+				name,
+				passed: false,
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return false;
+		}
+	}
+	async function saveAt(expectedRevision, label) {
+		return (await storage.saveDocument(sampleDocument(documentId, (expectedRevision ?? revision) + 1, label), {
+			expectedRevision,
+			signal
+		}))?.revision ?? (expectedRevision ?? revision) + 1;
+	}
+	if (await check("saves a new document when expectedRevision is 0", async () => {
+		revision = await saveAt(0, "first");
+		return revision > 0 ? void 0 : `returned revision ${revision}, expected a number above 0`;
+	})) {
+		await check("loads the document it saved", async () => {
+			const loaded = await storage.loadDocument(documentId);
+			if (loaded?.id !== documentId) return `loaded id ${String(loaded?.id)}, expected ${documentId}`;
+			if (loaded.metadata?.label !== "first") return "loaded content differs from what was saved";
+		});
+		await check("refuses a save based on an old revision with code SAVE_CONFLICT", async () => {
+			try {
+				await saveAt(revision - 1, "stale");
+			} catch (error) {
+				return codeOf(error) === "SAVE_CONFLICT" ? void 0 : `rejected with code ${String(codeOf(error))} instead of SAVE_CONFLICT`;
+			}
+			return "the stale save was accepted, so an older tab could overwrite newer work";
+		});
+		await check("accepts a save based on the current revision", async () => {
+			const next = await saveAt(revision, "second");
+			if (next <= revision) return `revision went from ${revision} to ${next}, it must increase`;
+			revision = next;
+			return (await storage.loadDocument(documentId))?.metadata?.label === "second" ? void 0 : "the newer content was not stored";
+		});
+		await check("overwrites when expectedRevision is null", async () => {
+			revision = await saveAt(null, "overwritten");
+			return (await storage.loadDocument(documentId))?.metadata?.label === "overwritten" ? void 0 : "the overwrite was not stored";
+		});
+	}
+	await check("rejects loading a document that does not exist", async () => {
+		try {
+			const missing = await storage.loadDocument(`adapter-check-missing-${createId()}`);
+			return missing === void 0 || missing === null ? "resolved with nothing instead of rejecting, which hides a missing document" : "returned a document for an id that was never saved";
+		} catch {
+			return;
+		}
+	});
+	if (supportsVersions(storage)) {
+		const version = {
+			id: `version-${createId()}`,
+			documentId,
+			name: "Adapter check",
+			kind: "named",
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			revision,
+			document: sampleDocument(documentId, revision, "versioned")
+		};
+		await check("keeps, lists, loads and deletes versions", async () => {
+			await storage.saveVersion(version);
+			const listed = await storage.listVersions(documentId);
+			if (!listed.some((summary) => summary.id === version.id)) return "listVersions did not include the saved version";
+			if (listed.some((summary) => "document" in summary)) return "listVersions should return summaries without the document";
+			if ((await storage.loadVersion(documentId, version.id)).document.metadata.label !== "versioned") return "loadVersion returned different content";
+			await storage.deleteVersion(documentId, version.id);
+			return (await storage.listVersions(documentId)).some((summary) => summary.id === version.id) ? "deleteVersion did not remove the version" : void 0;
+		});
+	}
+	await storage.deleteDocument?.(documentId).catch(() => void 0);
+	return {
+		ok: checks.every((result) => result.passed),
+		checks
+	};
+}
+//#endregion
+export { verifyStorageAdapter };

package/dist/storage.cjs

@@ -2,6 +2,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_key_value_storage = require("./storage/key-value-storage.cjs");
 const require_memory_storage = require("./storage/memory-storage.cjs");
 const require_local_storage = require("./storage/local-storage.cjs");
+const require_verify_storage_adapter = require("./storage/verify-storage-adapter.cjs");
 exports.createKeyValueStorage = require_key_value_storage.createKeyValueStorage;
 exports.createLocalStorage = require_local_storage.createLocalStorage;
 exports.createMemoryStorage = require_memory_storage.createMemoryStorage;
+exports.verifyStorageAdapter = require_verify_storage_adapter.verifyStorageAdapter;

package/dist/storage.d.cts

@@ -3,4 +3,5 @@ import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-cont
 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 DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage };
+import { AdapterCheck, AdapterReport, verifyStorageAdapter } from "./storage/verify-storage-adapter.cjs";
+export { type AdapterCheck, type AdapterReport, type DocumentStorage, type DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage, verifyStorageAdapter };

package/dist/storage.d.ts

@@ -3,4 +3,5 @@ import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-cont
 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 DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage };
+import { AdapterCheck, AdapterReport, verifyStorageAdapter } from "./storage/verify-storage-adapter.js";
+export { type AdapterCheck, type AdapterReport, type DocumentStorage, type DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage, verifyStorageAdapter };

package/dist/storage.js

@@ -1,4 +1,5 @@
 import { createKeyValueStorage } from "./storage/key-value-storage.js";
 import { createMemoryStorage } from "./storage/memory-storage.js";
 import { createLocalStorage } from "./storage/local-storage.js";
-export { createKeyValueStorage, createLocalStorage, createMemoryStorage };
+import { verifyStorageAdapter } from "./storage/verify-storage-adapter.js";
+export { createKeyValueStorage, createLocalStorage, createMemoryStorage, verifyStorageAdapter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fabricjs-document-engine",
-  "version": "0.7.0",
+  "version": "1.0.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",
@@ -29,6 +29,7 @@
   "sideEffects": false,
   "files": [
     "dist",
+    "schema",
     "README.md",
     "LICENSE"
   ],
@@ -76,6 +77,7 @@
         "default": "./dist/react.cjs"
       }
     },
+    "./schema/document-v1.json": "./schema/document-v1.schema.json",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -84,7 +86,7 @@
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.tools.json",
     "test": "vitest run",
     "test:unit": "vitest run --project unit",
-    "test:browser": "vitest run --project browser-fabric7 --project browser-fabric6",
+    "test:browser": "vitest run --project browser-fabric7 --project browser-fabric6 --project browser-firefox --project browser-webkit",
     "test:watch": "vitest",
     "lint:publint": "publint --strict",
     "lint:attw": "attw --pack . --profile node16",
@@ -117,6 +119,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitest/browser-playwright": "^5.0.2",
+    "ajv": "^8.20.0",
     "fabric": "^7.4.0",
     "fabric6": "npm:fabric@^6.9.1",
     "playwright": "^1.63.0",

package/schema/document-v1.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/fabricjs-document-engine/schema/document-v1.schema.json",
+  "title": "Fabric document, schema version 1",
+  "description": "The document format written by fabricjs-document-engine 1.x. Fabric object properties are kept as Fabric serializes them.",
+  "type": "object",
+  "required": ["schemaVersion", "id", "createdAt", "updatedAt", "canvas", "objects", "metadata"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string" },
+    "updatedAt": { "type": "string" },
+    "revision": { "type": "integer", "minimum": 0 },
+    "fabricVersion": { "type": "string" },
+    "canvas": {
+      "type": "object",
+      "required": ["width", "height"],
+      "properties": {
+        "width": { "type": "number", "exclusiveMinimum": 0 },
+        "height": { "type": "number", "exclusiveMinimum": 0 },
+        "background": {}
+      }
+    },
+    "objects": { "type": "array", "items": { "$ref": "#/$defs/fabricObject" } },
+    "assets": {
+      "type": "object",
+      "required": ["images", "fonts"],
+      "properties": {
+        "images": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["url", "objectIds"],
+            "properties": {
+              "url": { "type": "string" },
+              "objectIds": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        },
+        "fonts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["family", "weight", "style", "objectIds"],
+            "properties": {
+              "family": { "type": "string" },
+              "weight": { "type": "string" },
+              "style": { "type": "string" },
+              "objectIds": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    },
+    "metadata": { "type": "object" }
+  },
+  "$defs": {
+    "fabricObject": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "id": { "type": "string" },
+        "objects": { "type": "array", "items": { "$ref": "#/$defs/fabricObject" } },
+        "clipPath": { "$ref": "#/$defs/fabricObject" }
+      }
+    }
+  }
+}