loro-repo 0.5.0 → 0.5.2

package/dist/storage/filesystem.cjs

@@ -0,0 +1,164 @@
+const require_chunk = require('../chunk.cjs');
+let __loro_dev_flock = require("@loro-dev/flock");
+__loro_dev_flock = require_chunk.__toESM(__loro_dev_flock);
+let loro_crdt = require("loro-crdt");
+loro_crdt = require_chunk.__toESM(loro_crdt);
+let node_fs = require("node:fs");
+node_fs = require_chunk.__toESM(node_fs);
+let node_path = require("node:path");
+node_path = require_chunk.__toESM(node_path);
+let node_crypto = require("node:crypto");
+node_crypto = require_chunk.__toESM(node_crypto);
+
+//#region src/storage/filesystem.ts
+const textDecoder = new TextDecoder();
+var FileSystemStorageAdaptor = class {
+	baseDir;
+	docsDir;
+	assetsDir;
+	metaPath;
+	initPromise;
+	updateCounter = 0;
+	constructor(options = {}) {
+		this.baseDir = node_path.resolve(options.baseDir ?? node_path.join(process.cwd(), ".loro-repo"));
+		this.docsDir = node_path.join(this.baseDir, options.docsDirName ?? "docs");
+		this.assetsDir = node_path.join(this.baseDir, options.assetsDirName ?? "assets");
+		this.metaPath = node_path.join(this.baseDir, options.metaFileName ?? "meta.json");
+		this.initPromise = this.ensureLayout();
+	}
+	async save(payload) {
+		await this.initPromise;
+		switch (payload.type) {
+			case "doc-snapshot":
+				await this.writeDocSnapshot(payload.docId, payload.snapshot);
+				return;
+			case "doc-update":
+				await this.enqueueDocUpdate(payload.docId, payload.update);
+				return;
+			case "asset":
+				await this.writeAsset(payload.assetId, payload.data);
+				return;
+			case "meta":
+				await writeFileAtomic(this.metaPath, payload.update);
+				return;
+			default: throw new Error(`Unsupported payload type: ${payload.type}`);
+		}
+	}
+	async deleteAsset(assetId) {
+		await this.initPromise;
+		await removeIfExists(this.assetPath(assetId));
+	}
+	async loadDoc(docId) {
+		await this.initPromise;
+		const snapshotBytes = await readFileIfExists(this.docSnapshotPath(docId));
+		const updateDir = this.docUpdatesDir(docId);
+		const updateFiles = await listFiles(updateDir);
+		if (!snapshotBytes && updateFiles.length === 0) return;
+		const doc = snapshotBytes ? loro_crdt.LoroDoc.fromSnapshot(snapshotBytes) : new loro_crdt.LoroDoc();
+		if (updateFiles.length === 0) return doc;
+		const updatePaths = updateFiles.map((file) => node_path.join(updateDir, file));
+		for (const updatePath of updatePaths) {
+			const update = await readFileIfExists(updatePath);
+			if (!update) continue;
+			doc.import(update);
+		}
+		await Promise.all(updatePaths.map((filePath) => removeIfExists(filePath)));
+		const consolidated = doc.export({ mode: "snapshot" });
+		await this.writeDocSnapshot(docId, consolidated);
+		return doc;
+	}
+	async loadMeta() {
+		await this.initPromise;
+		const bytes = await readFileIfExists(this.metaPath);
+		if (!bytes) return void 0;
+		try {
+			const bundle = JSON.parse(textDecoder.decode(bytes));
+			const flock = new __loro_dev_flock.Flock();
+			flock.importJson(bundle);
+			return flock;
+		} catch (error) {
+			throw new Error("Failed to hydrate metadata snapshot", { cause: error });
+		}
+	}
+	async loadAsset(assetId) {
+		await this.initPromise;
+		return readFileIfExists(this.assetPath(assetId));
+	}
+	async ensureLayout() {
+		await Promise.all([
+			ensureDir(this.baseDir),
+			ensureDir(this.docsDir),
+			ensureDir(this.assetsDir)
+		]);
+	}
+	async writeDocSnapshot(docId, snapshot) {
+		await ensureDir(this.docDir(docId));
+		await writeFileAtomic(this.docSnapshotPath(docId), snapshot);
+	}
+	async enqueueDocUpdate(docId, update) {
+		const dir = this.docUpdatesDir(docId);
+		await ensureDir(dir);
+		const counter = this.updateCounter = (this.updateCounter + 1) % 1e6;
+		const fileName = `${Date.now().toString().padStart(13, "0")}-${counter.toString().padStart(6, "0")}.bin`;
+		await writeFileAtomic(node_path.join(dir, fileName), update);
+	}
+	async writeAsset(assetId, data) {
+		const filePath = this.assetPath(assetId);
+		await ensureDir(node_path.dirname(filePath));
+		await writeFileAtomic(filePath, data);
+	}
+	docDir(docId) {
+		return node_path.join(this.docsDir, encodeComponent(docId));
+	}
+	docSnapshotPath(docId) {
+		return node_path.join(this.docDir(docId), "snapshot.bin");
+	}
+	docUpdatesDir(docId) {
+		return node_path.join(this.docDir(docId), "updates");
+	}
+	assetPath(assetId) {
+		return node_path.join(this.assetsDir, encodeComponent(assetId));
+	}
+};
+function encodeComponent(value) {
+	return Buffer.from(value, "utf8").toString("base64url");
+}
+async function ensureDir(dir) {
+	await node_fs.promises.mkdir(dir, { recursive: true });
+}
+async function readFileIfExists(filePath) {
+	try {
+		const data = await node_fs.promises.readFile(filePath);
+		return new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+async function removeIfExists(filePath) {
+	try {
+		await node_fs.promises.rm(filePath);
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+async function listFiles(dir) {
+	try {
+		return (await node_fs.promises.readdir(dir)).sort();
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+async function writeFileAtomic(targetPath, data) {
+	const dir = node_path.dirname(targetPath);
+	await ensureDir(dir);
+	const tempPath = node_path.join(dir, `.tmp-${(0, node_crypto.randomUUID)()}`);
+	await node_fs.promises.writeFile(tempPath, data);
+	await node_fs.promises.rename(tempPath, targetPath);
+}
+
+//#endregion
+exports.FileSystemStorageAdaptor = FileSystemStorageAdaptor;
+//# sourceMappingURL=filesystem.cjs.map

package/dist/storage/filesystem.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.cjs","names":["path","LoroDoc","Flock","fs"],"sources":["../../src/storage/filesystem.ts"],"sourcesContent":["import { promises as fs } from \"node:fs\";\nimport * as path from \"node:path\";\nimport { randomUUID } from \"node:crypto\";\n\nimport { Flock, type ExportBundle } from \"@loro-dev/flock\";\nimport { LoroDoc } from \"loro-crdt\";\n\nimport type { AssetId, StorageAdapter, StorageSavePayload } from \"../types\";\n\nconst textDecoder = new TextDecoder();\n\nexport interface FileSystemStorageAdaptorOptions {\n  /**\n   * Base directory where metadata, document snapshots, and assets will be stored.\n   * Defaults to `.loro-repo` inside the current working directory.\n   */\n  readonly baseDir?: string;\n  /**\n   * Subdirectory dedicated to document persistence. Defaults to `docs`.\n   */\n  readonly docsDirName?: string;\n  /**\n   * Subdirectory dedicated to asset blobs. Defaults to `assets`.\n   */\n  readonly assetsDirName?: string;\n  /**\n   * File name for the metadata snapshot bundle. Defaults to `meta.json`.\n   */\n  readonly metaFileName?: string;\n}\n\nexport class FileSystemStorageAdaptor implements StorageAdapter {\n  private readonly baseDir: string;\n  private readonly docsDir: string;\n  private readonly assetsDir: string;\n  private readonly metaPath: string;\n  private readonly initPromise: Promise<void>;\n  private updateCounter = 0;\n\n  constructor(options: FileSystemStorageAdaptorOptions = {}) {\n    this.baseDir = path.resolve(\n      options.baseDir ?? path.join(process.cwd(), \".loro-repo\"),\n    );\n    this.docsDir = path.join(this.baseDir, options.docsDirName ?? \"docs\");\n    this.assetsDir = path.join(this.baseDir, options.assetsDirName ?? \"assets\");\n    this.metaPath = path.join(this.baseDir, options.metaFileName ?? \"meta.json\");\n    this.initPromise = this.ensureLayout();\n  }\n\n  async save(payload: StorageSavePayload): Promise<void> {\n    await this.initPromise;\n    switch (payload.type) {\n      case \"doc-snapshot\":\n        await this.writeDocSnapshot(payload.docId, payload.snapshot);\n        return;\n      case \"doc-update\":\n        await this.enqueueDocUpdate(payload.docId, payload.update);\n        return;\n      case \"asset\":\n        await this.writeAsset(payload.assetId, payload.data);\n        return;\n      case \"meta\":\n        await writeFileAtomic(this.metaPath, payload.update);\n        return;\n      default:\n        throw new Error(`Unsupported payload type: ${(payload as { type: string }).type}`);\n    }\n  }\n\n  async deleteAsset(assetId: AssetId): Promise<void> {\n    await this.initPromise;\n    const filePath = this.assetPath(assetId);\n    await removeIfExists(filePath);\n  }\n\n  async loadDoc(docId: string): Promise<LoroDoc | undefined> {\n    await this.initPromise;\n    const snapshotPath = this.docSnapshotPath(docId);\n    const snapshotBytes = await readFileIfExists(snapshotPath);\n    const updateDir = this.docUpdatesDir(docId);\n    const updateFiles = await listFiles(updateDir);\n\n    if (!snapshotBytes && updateFiles.length === 0) {\n      return undefined;\n    }\n\n    const doc = snapshotBytes\n      ? LoroDoc.fromSnapshot(snapshotBytes)\n      : new LoroDoc();\n\n    if (updateFiles.length === 0) {\n      return doc;\n    }\n\n    const updatePaths = updateFiles.map((file) => path.join(updateDir, file));\n    for (const updatePath of updatePaths) {\n      const update = await readFileIfExists(updatePath);\n      if (!update) continue;\n      doc.import(update);\n    }\n\n    await Promise.all(updatePaths.map((filePath) => removeIfExists(filePath)));\n\n    const consolidated = doc.export({ mode: \"snapshot\" });\n    await this.writeDocSnapshot(docId, consolidated);\n    return doc;\n  }\n\n  async loadMeta(): Promise<Flock | undefined> {\n    await this.initPromise;\n    const bytes = await readFileIfExists(this.metaPath);\n    if (!bytes) return undefined;\n    try {\n      const bundle = JSON.parse(textDecoder.decode(bytes)) as ExportBundle;\n      const flock = new Flock();\n      flock.importJson(bundle);\n      return flock;\n    } catch (error) {\n      throw new Error(\"Failed to hydrate metadata snapshot\", { cause: error });\n    }\n  }\n\n  async loadAsset(assetId: AssetId): Promise<Uint8Array | undefined> {\n    await this.initPromise;\n    return readFileIfExists(this.assetPath(assetId));\n  }\n\n  private async ensureLayout(): Promise<void> {\n    await Promise.all([\n      ensureDir(this.baseDir),\n      ensureDir(this.docsDir),\n      ensureDir(this.assetsDir),\n    ]);\n  }\n\n  private async writeDocSnapshot(\n    docId: string,\n    snapshot: Uint8Array,\n  ): Promise<void> {\n    const targetDir = this.docDir(docId);\n    await ensureDir(targetDir);\n    await writeFileAtomic(this.docSnapshotPath(docId), snapshot);\n  }\n\n  private async enqueueDocUpdate(\n    docId: string,\n    update: Uint8Array,\n  ): Promise<void> {\n    const dir = this.docUpdatesDir(docId);\n    await ensureDir(dir);\n    const counter = (this.updateCounter = (this.updateCounter + 1) % 1_000_000);\n    const timestamp = Date.now().toString().padStart(13, \"0\");\n    const fileName = `${timestamp}-${counter.toString().padStart(6, \"0\")}.bin`;\n    const filePath = path.join(dir, fileName);\n    await writeFileAtomic(filePath, update);\n  }\n\n  private async writeAsset(assetId: AssetId, data: Uint8Array): Promise<void> {\n    const filePath = this.assetPath(assetId);\n    await ensureDir(path.dirname(filePath));\n    await writeFileAtomic(filePath, data);\n  }\n\n  private docDir(docId: string): string {\n    return path.join(this.docsDir, encodeComponent(docId));\n  }\n\n  private docSnapshotPath(docId: string): string {\n    return path.join(this.docDir(docId), \"snapshot.bin\");\n  }\n\n  private docUpdatesDir(docId: string): string {\n    return path.join(this.docDir(docId), \"updates\");\n  }\n\n  private assetPath(assetId: AssetId): string {\n    return path.join(this.assetsDir, encodeComponent(assetId));\n  }\n}\n\nfunction encodeComponent(value: string): string {\n  return Buffer.from(value, \"utf8\").toString(\"base64url\");\n}\n\nasync function ensureDir(dir: string): Promise<void> {\n  await fs.mkdir(dir, { recursive: true });\n}\n\nasync function readFileIfExists(filePath: string): Promise<Uint8Array | undefined> {\n  try {\n    const data = await fs.readFile(filePath);\n    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return undefined;\n    }\n    throw error;\n  }\n}\n\nasync function removeIfExists(filePath: string): Promise<void> {\n  try {\n    await fs.rm(filePath);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return;\n    }\n    throw error;\n  }\n}\n\nasync function listFiles(dir: string): Promise<string[]> {\n  try {\n    const entries = await fs.readdir(dir);\n    return entries.sort();\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return [];\n    }\n    throw error;\n  }\n}\n\nasync function writeFileAtomic(\n  targetPath: string,\n  data: Uint8Array,\n): Promise<void> {\n  const dir = path.dirname(targetPath);\n  await ensureDir(dir);\n  const tempPath = path.join(dir, `.tmp-${randomUUID()}`);\n  await fs.writeFile(tempPath, data);\n  await fs.rename(tempPath, targetPath);\n}\n"],"mappings":"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"}

package/dist/storage/filesystem.d.cts

@@ -0,0 +1,49 @@
+import { C as StorageAdapter, r as AssetId, w as StorageSavePayload } from "../types.cjs";
+import { Flock } from "@loro-dev/flock";
+import { LoroDoc } from "loro-crdt";
+
+//#region src/storage/filesystem.d.ts
+interface FileSystemStorageAdaptorOptions {
+  /**
+   * Base directory where metadata, document snapshots, and assets will be stored.
+   * Defaults to `.loro-repo` inside the current working directory.
+   */
+  readonly baseDir?: string;
+  /**
+   * Subdirectory dedicated to document persistence. Defaults to `docs`.
+   */
+  readonly docsDirName?: string;
+  /**
+   * Subdirectory dedicated to asset blobs. Defaults to `assets`.
+   */
+  readonly assetsDirName?: string;
+  /**
+   * File name for the metadata snapshot bundle. Defaults to `meta.json`.
+   */
+  readonly metaFileName?: string;
+}
+declare class FileSystemStorageAdaptor implements StorageAdapter {
+  private readonly baseDir;
+  private readonly docsDir;
+  private readonly assetsDir;
+  private readonly metaPath;
+  private readonly initPromise;
+  private updateCounter;
+  constructor(options?: FileSystemStorageAdaptorOptions);
+  save(payload: StorageSavePayload): Promise<void>;
+  deleteAsset(assetId: AssetId): Promise<void>;
+  loadDoc(docId: string): Promise<LoroDoc | undefined>;
+  loadMeta(): Promise<Flock | undefined>;
+  loadAsset(assetId: AssetId): Promise<Uint8Array | undefined>;
+  private ensureLayout;
+  private writeDocSnapshot;
+  private enqueueDocUpdate;
+  private writeAsset;
+  private docDir;
+  private docSnapshotPath;
+  private docUpdatesDir;
+  private assetPath;
+}
+//#endregion
+export { FileSystemStorageAdaptor, FileSystemStorageAdaptorOptions };
+//# sourceMappingURL=filesystem.d.cts.map

package/dist/storage/filesystem.d.ts

@@ -0,0 +1,49 @@
+import { C as StorageAdapter, r as AssetId, w as StorageSavePayload } from "../types.js";
+import { Flock } from "@loro-dev/flock";
+import { LoroDoc } from "loro-crdt";
+
+//#region src/storage/filesystem.d.ts
+interface FileSystemStorageAdaptorOptions {
+  /**
+   * Base directory where metadata, document snapshots, and assets will be stored.
+   * Defaults to `.loro-repo` inside the current working directory.
+   */
+  readonly baseDir?: string;
+  /**
+   * Subdirectory dedicated to document persistence. Defaults to `docs`.
+   */
+  readonly docsDirName?: string;
+  /**
+   * Subdirectory dedicated to asset blobs. Defaults to `assets`.
+   */
+  readonly assetsDirName?: string;
+  /**
+   * File name for the metadata snapshot bundle. Defaults to `meta.json`.
+   */
+  readonly metaFileName?: string;
+}
+declare class FileSystemStorageAdaptor implements StorageAdapter {
+  private readonly baseDir;
+  private readonly docsDir;
+  private readonly assetsDir;
+  private readonly metaPath;
+  private readonly initPromise;
+  private updateCounter;
+  constructor(options?: FileSystemStorageAdaptorOptions);
+  save(payload: StorageSavePayload): Promise<void>;
+  deleteAsset(assetId: AssetId): Promise<void>;
+  loadDoc(docId: string): Promise<LoroDoc | undefined>;
+  loadMeta(): Promise<Flock | undefined>;
+  loadAsset(assetId: AssetId): Promise<Uint8Array | undefined>;
+  private ensureLayout;
+  private writeDocSnapshot;
+  private enqueueDocUpdate;
+  private writeAsset;
+  private docDir;
+  private docSnapshotPath;
+  private docUpdatesDir;
+  private assetPath;
+}
+//#endregion
+export { FileSystemStorageAdaptor, FileSystemStorageAdaptorOptions };
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/storage/filesystem.js

@@ -0,0 +1,158 @@
+import { Flock } from "@loro-dev/flock";
+import { LoroDoc } from "loro-crdt";
+import { promises } from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+
+//#region src/storage/filesystem.ts
+const textDecoder = new TextDecoder();
+var FileSystemStorageAdaptor = class {
+	baseDir;
+	docsDir;
+	assetsDir;
+	metaPath;
+	initPromise;
+	updateCounter = 0;
+	constructor(options = {}) {
+		this.baseDir = path.resolve(options.baseDir ?? path.join(process.cwd(), ".loro-repo"));
+		this.docsDir = path.join(this.baseDir, options.docsDirName ?? "docs");
+		this.assetsDir = path.join(this.baseDir, options.assetsDirName ?? "assets");
+		this.metaPath = path.join(this.baseDir, options.metaFileName ?? "meta.json");
+		this.initPromise = this.ensureLayout();
+	}
+	async save(payload) {
+		await this.initPromise;
+		switch (payload.type) {
+			case "doc-snapshot":
+				await this.writeDocSnapshot(payload.docId, payload.snapshot);
+				return;
+			case "doc-update":
+				await this.enqueueDocUpdate(payload.docId, payload.update);
+				return;
+			case "asset":
+				await this.writeAsset(payload.assetId, payload.data);
+				return;
+			case "meta":
+				await writeFileAtomic(this.metaPath, payload.update);
+				return;
+			default: throw new Error(`Unsupported payload type: ${payload.type}`);
+		}
+	}
+	async deleteAsset(assetId) {
+		await this.initPromise;
+		await removeIfExists(this.assetPath(assetId));
+	}
+	async loadDoc(docId) {
+		await this.initPromise;
+		const snapshotBytes = await readFileIfExists(this.docSnapshotPath(docId));
+		const updateDir = this.docUpdatesDir(docId);
+		const updateFiles = await listFiles(updateDir);
+		if (!snapshotBytes && updateFiles.length === 0) return;
+		const doc = snapshotBytes ? LoroDoc.fromSnapshot(snapshotBytes) : new LoroDoc();
+		if (updateFiles.length === 0) return doc;
+		const updatePaths = updateFiles.map((file) => path.join(updateDir, file));
+		for (const updatePath of updatePaths) {
+			const update = await readFileIfExists(updatePath);
+			if (!update) continue;
+			doc.import(update);
+		}
+		await Promise.all(updatePaths.map((filePath) => removeIfExists(filePath)));
+		const consolidated = doc.export({ mode: "snapshot" });
+		await this.writeDocSnapshot(docId, consolidated);
+		return doc;
+	}
+	async loadMeta() {
+		await this.initPromise;
+		const bytes = await readFileIfExists(this.metaPath);
+		if (!bytes) return void 0;
+		try {
+			const bundle = JSON.parse(textDecoder.decode(bytes));
+			const flock = new Flock();
+			flock.importJson(bundle);
+			return flock;
+		} catch (error) {
+			throw new Error("Failed to hydrate metadata snapshot", { cause: error });
+		}
+	}
+	async loadAsset(assetId) {
+		await this.initPromise;
+		return readFileIfExists(this.assetPath(assetId));
+	}
+	async ensureLayout() {
+		await Promise.all([
+			ensureDir(this.baseDir),
+			ensureDir(this.docsDir),
+			ensureDir(this.assetsDir)
+		]);
+	}
+	async writeDocSnapshot(docId, snapshot) {
+		await ensureDir(this.docDir(docId));
+		await writeFileAtomic(this.docSnapshotPath(docId), snapshot);
+	}
+	async enqueueDocUpdate(docId, update) {
+		const dir = this.docUpdatesDir(docId);
+		await ensureDir(dir);
+		const counter = this.updateCounter = (this.updateCounter + 1) % 1e6;
+		const fileName = `${Date.now().toString().padStart(13, "0")}-${counter.toString().padStart(6, "0")}.bin`;
+		await writeFileAtomic(path.join(dir, fileName), update);
+	}
+	async writeAsset(assetId, data) {
+		const filePath = this.assetPath(assetId);
+		await ensureDir(path.dirname(filePath));
+		await writeFileAtomic(filePath, data);
+	}
+	docDir(docId) {
+		return path.join(this.docsDir, encodeComponent(docId));
+	}
+	docSnapshotPath(docId) {
+		return path.join(this.docDir(docId), "snapshot.bin");
+	}
+	docUpdatesDir(docId) {
+		return path.join(this.docDir(docId), "updates");
+	}
+	assetPath(assetId) {
+		return path.join(this.assetsDir, encodeComponent(assetId));
+	}
+};
+function encodeComponent(value) {
+	return Buffer.from(value, "utf8").toString("base64url");
+}
+async function ensureDir(dir) {
+	await promises.mkdir(dir, { recursive: true });
+}
+async function readFileIfExists(filePath) {
+	try {
+		const data = await promises.readFile(filePath);
+		return new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+async function removeIfExists(filePath) {
+	try {
+		await promises.rm(filePath);
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+}
+async function listFiles(dir) {
+	try {
+		return (await promises.readdir(dir)).sort();
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+async function writeFileAtomic(targetPath, data) {
+	const dir = path.dirname(targetPath);
+	await ensureDir(dir);
+	const tempPath = path.join(dir, `.tmp-${randomUUID()}`);
+	await promises.writeFile(tempPath, data);
+	await promises.rename(tempPath, targetPath);
+}
+
+//#endregion
+export { FileSystemStorageAdaptor };
+//# sourceMappingURL=filesystem.js.map

package/dist/storage/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","names":["fs"],"sources":["../../src/storage/filesystem.ts"],"sourcesContent":["import { promises as fs } from \"node:fs\";\nimport * as path from \"node:path\";\nimport { randomUUID } from \"node:crypto\";\n\nimport { Flock, type ExportBundle } from \"@loro-dev/flock\";\nimport { LoroDoc } from \"loro-crdt\";\n\nimport type { AssetId, StorageAdapter, StorageSavePayload } from \"../types\";\n\nconst textDecoder = new TextDecoder();\n\nexport interface FileSystemStorageAdaptorOptions {\n  /**\n   * Base directory where metadata, document snapshots, and assets will be stored.\n   * Defaults to `.loro-repo` inside the current working directory.\n   */\n  readonly baseDir?: string;\n  /**\n   * Subdirectory dedicated to document persistence. Defaults to `docs`.\n   */\n  readonly docsDirName?: string;\n  /**\n   * Subdirectory dedicated to asset blobs. Defaults to `assets`.\n   */\n  readonly assetsDirName?: string;\n  /**\n   * File name for the metadata snapshot bundle. Defaults to `meta.json`.\n   */\n  readonly metaFileName?: string;\n}\n\nexport class FileSystemStorageAdaptor implements StorageAdapter {\n  private readonly baseDir: string;\n  private readonly docsDir: string;\n  private readonly assetsDir: string;\n  private readonly metaPath: string;\n  private readonly initPromise: Promise<void>;\n  private updateCounter = 0;\n\n  constructor(options: FileSystemStorageAdaptorOptions = {}) {\n    this.baseDir = path.resolve(\n      options.baseDir ?? path.join(process.cwd(), \".loro-repo\"),\n    );\n    this.docsDir = path.join(this.baseDir, options.docsDirName ?? \"docs\");\n    this.assetsDir = path.join(this.baseDir, options.assetsDirName ?? \"assets\");\n    this.metaPath = path.join(this.baseDir, options.metaFileName ?? \"meta.json\");\n    this.initPromise = this.ensureLayout();\n  }\n\n  async save(payload: StorageSavePayload): Promise<void> {\n    await this.initPromise;\n    switch (payload.type) {\n      case \"doc-snapshot\":\n        await this.writeDocSnapshot(payload.docId, payload.snapshot);\n        return;\n      case \"doc-update\":\n        await this.enqueueDocUpdate(payload.docId, payload.update);\n        return;\n      case \"asset\":\n        await this.writeAsset(payload.assetId, payload.data);\n        return;\n      case \"meta\":\n        await writeFileAtomic(this.metaPath, payload.update);\n        return;\n      default:\n        throw new Error(`Unsupported payload type: ${(payload as { type: string }).type}`);\n    }\n  }\n\n  async deleteAsset(assetId: AssetId): Promise<void> {\n    await this.initPromise;\n    const filePath = this.assetPath(assetId);\n    await removeIfExists(filePath);\n  }\n\n  async loadDoc(docId: string): Promise<LoroDoc | undefined> {\n    await this.initPromise;\n    const snapshotPath = this.docSnapshotPath(docId);\n    const snapshotBytes = await readFileIfExists(snapshotPath);\n    const updateDir = this.docUpdatesDir(docId);\n    const updateFiles = await listFiles(updateDir);\n\n    if (!snapshotBytes && updateFiles.length === 0) {\n      return undefined;\n    }\n\n    const doc = snapshotBytes\n      ? LoroDoc.fromSnapshot(snapshotBytes)\n      : new LoroDoc();\n\n    if (updateFiles.length === 0) {\n      return doc;\n    }\n\n    const updatePaths = updateFiles.map((file) => path.join(updateDir, file));\n    for (const updatePath of updatePaths) {\n      const update = await readFileIfExists(updatePath);\n      if (!update) continue;\n      doc.import(update);\n    }\n\n    await Promise.all(updatePaths.map((filePath) => removeIfExists(filePath)));\n\n    const consolidated = doc.export({ mode: \"snapshot\" });\n    await this.writeDocSnapshot(docId, consolidated);\n    return doc;\n  }\n\n  async loadMeta(): Promise<Flock | undefined> {\n    await this.initPromise;\n    const bytes = await readFileIfExists(this.metaPath);\n    if (!bytes) return undefined;\n    try {\n      const bundle = JSON.parse(textDecoder.decode(bytes)) as ExportBundle;\n      const flock = new Flock();\n      flock.importJson(bundle);\n      return flock;\n    } catch (error) {\n      throw new Error(\"Failed to hydrate metadata snapshot\", { cause: error });\n    }\n  }\n\n  async loadAsset(assetId: AssetId): Promise<Uint8Array | undefined> {\n    await this.initPromise;\n    return readFileIfExists(this.assetPath(assetId));\n  }\n\n  private async ensureLayout(): Promise<void> {\n    await Promise.all([\n      ensureDir(this.baseDir),\n      ensureDir(this.docsDir),\n      ensureDir(this.assetsDir),\n    ]);\n  }\n\n  private async writeDocSnapshot(\n    docId: string,\n    snapshot: Uint8Array,\n  ): Promise<void> {\n    const targetDir = this.docDir(docId);\n    await ensureDir(targetDir);\n    await writeFileAtomic(this.docSnapshotPath(docId), snapshot);\n  }\n\n  private async enqueueDocUpdate(\n    docId: string,\n    update: Uint8Array,\n  ): Promise<void> {\n    const dir = this.docUpdatesDir(docId);\n    await ensureDir(dir);\n    const counter = (this.updateCounter = (this.updateCounter + 1) % 1_000_000);\n    const timestamp = Date.now().toString().padStart(13, \"0\");\n    const fileName = `${timestamp}-${counter.toString().padStart(6, \"0\")}.bin`;\n    const filePath = path.join(dir, fileName);\n    await writeFileAtomic(filePath, update);\n  }\n\n  private async writeAsset(assetId: AssetId, data: Uint8Array): Promise<void> {\n    const filePath = this.assetPath(assetId);\n    await ensureDir(path.dirname(filePath));\n    await writeFileAtomic(filePath, data);\n  }\n\n  private docDir(docId: string): string {\n    return path.join(this.docsDir, encodeComponent(docId));\n  }\n\n  private docSnapshotPath(docId: string): string {\n    return path.join(this.docDir(docId), \"snapshot.bin\");\n  }\n\n  private docUpdatesDir(docId: string): string {\n    return path.join(this.docDir(docId), \"updates\");\n  }\n\n  private assetPath(assetId: AssetId): string {\n    return path.join(this.assetsDir, encodeComponent(assetId));\n  }\n}\n\nfunction encodeComponent(value: string): string {\n  return Buffer.from(value, \"utf8\").toString(\"base64url\");\n}\n\nasync function ensureDir(dir: string): Promise<void> {\n  await fs.mkdir(dir, { recursive: true });\n}\n\nasync function readFileIfExists(filePath: string): Promise<Uint8Array | undefined> {\n  try {\n    const data = await fs.readFile(filePath);\n    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength).slice();\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return undefined;\n    }\n    throw error;\n  }\n}\n\nasync function removeIfExists(filePath: string): Promise<void> {\n  try {\n    await fs.rm(filePath);\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return;\n    }\n    throw error;\n  }\n}\n\nasync function listFiles(dir: string): Promise<string[]> {\n  try {\n    const entries = await fs.readdir(dir);\n    return entries.sort();\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n      return [];\n    }\n    throw error;\n  }\n}\n\nasync function writeFileAtomic(\n  targetPath: string,\n  data: Uint8Array,\n): Promise<void> {\n  const dir = path.dirname(targetPath);\n  await ensureDir(dir);\n  const tempPath = path.join(dir, `.tmp-${randomUUID()}`);\n  await fs.writeFile(tempPath, data);\n  await fs.rename(tempPath, targetPath);\n}\n"],"mappings":"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"}