@ucdjs/lockfile 0.1.1-beta.7 → 0.1.1-beta.8

package/README.md

@@ -17,7 +17,7 @@ import { NodeFileSystemBridge } from "@ucdjs/fs-bridge";
 import { getLockfilePath, readLockfile, writeLockfile } from "@ucdjs/lockfile";
 
 const fs = NodeFileSystemBridge({ basePath: "./store" });
-const lockfilePath = getLockfilePath("./store");
+const lockfilePath = getLockfilePath();
 
 // Read lockfile
 const lockfile = await readLockfile(fs, lockfilePath);
@@ -35,19 +35,37 @@ await writeLockfile(fs, lockfilePath, {
 });
 ```
 
+### Parsing Lockfiles Without a Filesystem Bridge
+
+When you already have the lockfile content as a string (e.g., fetched from HTTP, read from a KV store, etc.), you can parse and validate it directly without needing a filesystem bridge:
+
+```typescript
+import { parseLockfile, parseLockfileOrUndefined } from "@ucdjs/lockfile";
+
+// Parse from a fetch response
+const response = await fetch("https://ucdjs.dev/.ucd-store.lock");
+const content = await response.text();
+const lockfile = parseLockfile(content);
+
+// Or use the non-throwing variant
+const lockfileOrUndefined = parseLockfileOrUndefined(content);
+if (lockfileOrUndefined) {
+  console.log("Lockfile version:", lockfileOrUndefined.lockfileVersion);
+}
+```
+
 ### Reading and Writing Snapshots
 
 ```typescript
-import { getSnapshotPath, readSnapshot, writeSnapshot } from "@ucdjs/lockfile";
+import { getSnapshotPath, parseSnapshot, parseSnapshotOrUndefined, readSnapshot, writeSnapshot } from "@ucdjs/lockfile";
 
-const basePath = "./store";
 const version = "16.0.0";
 
 // Read snapshot
-const snapshot = await readSnapshot(fs, basePath, version);
+const snapshot = await readSnapshot(fs, version);
 
 // Write snapshot
-await writeSnapshot(fs, basePath, version, {
+await writeSnapshot(fs, version, {
   unicodeVersion: "16.0.0",
   files: {
     "UnicodeData.txt": {
@@ -56,6 +74,14 @@ await writeSnapshot(fs, basePath, version, {
     },
   },
 });
+
+// Parse snapshot content directly (without a filesystem bridge)
+const response = await fetch("https://ucdjs.dev/16.0.0/snapshot.json");
+const content = await response.text();
+const parsedSnapshot = parseSnapshot(content);
+
+// Or use the non-throwing variant
+const parsedSnapshotOrUndefined = parseSnapshotOrUndefined(content);
 ```
 
 ### Computing File Hashes
@@ -68,6 +94,15 @@ const hash = await computeFileHash(content);
 // Returns: "sha256:..."
 ```
 
+## Overview
+
+`@ucdjs/lockfile` manages the canonical persisted state for mirrored local UCD stores. Two artifacts define what's in a local store:
+
+- **Lockfile** (`.ucd-store.lock`) - index of all mirrored Unicode versions, with their snapshot paths, file counts, and total sizes.
+- **Snapshots** (`{version}/snapshot.json`) - per-version manifest listing every file, its hash, and size.
+
+Together these are the source of truth for a local store. The `parseLockfile()` and `parseSnapshot()` utilities also accept content from remote sources (HTTP, KV stores) with the same shape, but those are read-only compatibility uses - not local store management.
+
 ## API Reference
 
 ### Lockfile Operations
@@ -75,27 +110,36 @@ const hash = await computeFileHash(content);
 - `canUseLockfile(fs: FileSystemBridge): boolean` - Check if bridge supports lockfile operations
 - `readLockfile(fs: FileSystemBridge, lockfilePath: string): Promise<Lockfile>` - Read and validate lockfile
 - `writeLockfile(fs: FileSystemBridge, lockfilePath: string, lockfile: Lockfile): Promise<void>` - Write lockfile
-- `readLockfileOrDefault(fs: FileSystemBridge, lockfilePath: string): Promise<Lockfile | undefined>` - Read lockfile or return undefined
+- `readLockfileOrUndefined(fs: FileSystemBridge, lockfilePath: string): Promise<Lockfile | undefined>` - Read lockfile or return undefined
+- `parseLockfile(content: string): Lockfile` - Parse and validate lockfile from a raw string
+- `parseLockfileOrUndefined(content: string): Lockfile | undefined` - Parse lockfile from a raw string or return undefined
+- `validateLockfile(data: unknown): ValidateLockfileResult` - Validate lockfile data without reading from filesystem
 
 ### Snapshot Operations
 
-- `readSnapshot(fs: FileSystemBridge, basePath: string, version: string): Promise<Snapshot>` - Read and validate snapshot
-- `writeSnapshot(fs: FileSystemBridge, basePath: string, version: string, snapshot: Snapshot): Promise<void>` - Write snapshot
-- `readSnapshotOrDefault(fs: FileSystemBridge, basePath: string, version: string): Promise<Snapshot | undefined>` - Read snapshot or return undefined
+- `readSnapshot(fs: FileSystemBridge, version: string): Promise<Snapshot>` - Read and validate snapshot
+- `writeSnapshot(fs: FileSystemBridge, version: string, snapshot: Snapshot): Promise<void>` - Write snapshot
+- `readSnapshotOrUndefined(fs: FileSystemBridge, version: string): Promise<Snapshot | undefined>` - Read snapshot or return undefined
+- `parseSnapshot(content: string): Snapshot` - Parse and validate snapshot from a raw string
+- `parseSnapshotOrUndefined(content: string): Snapshot | undefined` - Parse snapshot from a raw string or return undefined
 
 ### Path Utilities
 
-- `getLockfilePath(_basePath: string): string` - Get default lockfile path (`.ucd-store.lock`)
-- `getSnapshotPath(basePath: string, version: string): string` - Get snapshot path for version
+- `getLockfilePath(): string` - Get default lockfile path (`.ucd-store.lock`)
+- `getSnapshotPath(version: string): string` - Get snapshot path for version
 
 ### Hash Utilities
 
 - `computeFileHash(content: string | Uint8Array): Promise<string>` - Compute SHA-256 hash
+- `computeFileHashWithoutUCDHeader(content: string): Promise<string>` - Compute SHA-256 hash after stripping the Unicode file header (useful for comparing content across versions)
+- `stripUnicodeHeader(content: string): string` - Strip the Unicode file header (filename, date, copyright lines) from content
+
+In snapshot metadata, `fileHash` is always the hash of the exact file bytes. The `hash` field is the semantic comparison hash: text Unicode files strip the Unicode header first, while binary files use the same value as `fileHash`.
 
 ### Error Types
 
+- `LockfileBaseError` - Base error class for all lockfile errors
 - `LockfileInvalidError` - Thrown when a lockfile or snapshot is invalid
-- `LockfileBridgeUnsupportedOperation` - Thrown when a filesystem bridge operation is not supported
 
 ## Test Utilities
 

package/dist/{hash-DYmMzCbf.mjs → hash-Bf5WIJe6.mjs}

@@ -1,4 +1,5 @@
 //#region src/hash.ts
+const HEADER_FILE_VERSION_RE = /\d{1,3}\.\d{1,3}\.\d{1,3}\.txt$/;
 /**
 * Checks if a line looks like a Unicode header line.
 * Header lines typically contain:
@@ -12,7 +13,7 @@
 */
 function isHeaderLine(line) {
 	const lower = line.toLowerCase();
-	return lower.includes("date:") || line.includes("©") || lower.includes("unicode®") || lower.includes("unicode, inc") || /\d{1,3}\.\d{1,3}\.\d{1,3}\.txt$/.test(line);
+	return lower.includes("date:") || line.includes("©") || lower.includes("unicode®") || lower.includes("unicode, inc") || HEADER_FILE_VERSION_RE.test(line);
 }
 /**
 * Strips the Unicode file header from content.
@@ -102,6 +103,5 @@ async function computeFileHash(content) {
 async function computeFileHashWithoutUCDHeader(content) {
 	return computeFileHash(stripUnicodeHeader(content));
 }
-
 //#endregion
-export { computeFileHashWithoutUCDHeader as n, stripUnicodeHeader as r, computeFileHash as t };
+export { computeFileHashWithoutUCDHeader as n, stripUnicodeHeader as r, computeFileHash as t };

package/dist/index.d.mts

@@ -1,5 +1,4 @@
-import { FileSystemBridge } from "@ucdjs/fs-bridge";
-import { Lockfile, LockfileInput, Snapshot } from "@ucdjs/schemas";
+import { BackendEntry, Lockfile, LockfileInput, Snapshot } from "@ucdjs/schemas";
 
 //#region src/errors.d.ts
 /**
@@ -24,15 +23,6 @@ declare class LockfileInvalidError extends LockfileBaseError {
     details?: string[];
   });
 }
-/**
- * Error thrown when a filesystem bridge operation is not supported
- */
-declare class LockfileBridgeUnsupportedOperation extends LockfileBaseError {
-  readonly operation: string;
-  readonly requiredCapabilities: string[];
-  readonly availableCapabilities: string[];
-  constructor(operation: string, requiredCapabilities: string[], availableCapabilities: string[]);
-}
 //#endregion
 //#region src/hash.d.ts
 /**
@@ -65,6 +55,170 @@ declare function computeFileHash(content: string | Uint8Array): Promise<string>;
  */
 declare function computeFileHashWithoutUCDHeader(content: string): Promise<string>;
 //#endregion
+//#region ../../node_modules/.pnpm/hookable@6.1.0/node_modules/hookable/dist/index.d.mts
+//#region src/types.d.ts
+type HookCallback = (...arguments_: any) => Promise<void> | void;
+type HookKeys<T> = keyof T & string;
+//#endregion
+//#region src/hookable.d.ts
+type InferCallback<HT, HN extends keyof HT> = HT[HN] extends HookCallback ? HT[HN] : never;
+declare class HookableCore<HooksT extends Record<string, any> = Record<string, HookCallback>, HookNameT extends HookKeys<HooksT> = HookKeys<HooksT>> {
+  protected _hooks: {
+    [key: string]: HookCallback[] | undefined;
+  };
+  constructor();
+  hook<NameT extends HookNameT>(name: NameT, fn: InferCallback<HooksT, NameT>): () => void;
+  removeHook<NameT extends HookNameT>(name: NameT, function_: InferCallback<HooksT, NameT>): void;
+  callHook<NameT extends HookNameT>(name: NameT, ...args: Parameters<InferCallback<HooksT, NameT>>): Promise<any> | void;
+} //#endregion
+//#region src/utils.d.ts
+type CreateTask = (name?: string) => {
+  run: (function_: () => Promise<any> | any) => Promise<any> | any;
+};
+declare global {
+  interface Console {
+    createTask?: CreateTask;
+  }
+}
+/** @deprecated */
+//#endregion
+//#region ../fs-backend/dist/types-B5lbklgx.d.mts
+//#region src/types.d.ts
+interface ListOptions {
+  recursive?: boolean;
+}
+interface RemoveOptions {
+  recursive?: boolean;
+  force?: boolean;
+}
+interface CopyOptions {
+  recursive?: boolean;
+  overwrite?: boolean;
+}
+type BackendEntry$1 = BackendEntry;
+interface BackendStat {
+  type: BackendEntry$1["type"];
+  size: number;
+  mtime?: Date;
+}
+interface FileSystemBackendOperations {
+  read: (path: string) => Promise<string>;
+  readBytes: (path: string) => Promise<Uint8Array>;
+  list: (path: string, options?: ListOptions) => Promise<BackendEntry$1[]>;
+  /**
+   * Best-effort existence check.
+   *
+   * Backends may collapse "missing" and "could not determine existence" into
+   * `false`, especially for remote transports. Use `stat()` when you need
+   * error details instead of a lossy boolean.
+   */
+  exists: (path: string) => Promise<boolean>;
+  stat: (path: string) => Promise<BackendStat>;
+}
+interface FileSystemBackendMutableOperations {
+  write?: (path: string, data: string | Uint8Array) => Promise<void>;
+  mkdir?: (path: string) => Promise<void>;
+  remove?: (path: string, options?: RemoveOptions) => Promise<void>;
+  /**
+   * Copy a file or directory to the exact destination path within the same backend.
+   *
+   * File copies use `destinationPath` as an exact target path by default, but
+   * will copy into a destination directory when the destination ends with `/`
+   * or already exists as a directory. Directory copies require `recursive: true`.
+   */
+  copy?: (sourcePath: string, destinationPath: string, options?: CopyOptions) => Promise<void>;
+}
+interface FileSystemBackendMutableMethods {
+  write: (path: string, data: string | Uint8Array) => Promise<void>;
+  mkdir: (path: string) => Promise<void>;
+  remove: (path: string, options?: RemoveOptions) => Promise<void>;
+  copy: (sourcePath: string, destinationPath: string, options?: CopyOptions) => Promise<void>;
+}
+type FileSystemBackendFeature = keyof FileSystemBackendMutableOperations;
+interface FileSystemBackendMeta {
+  name: string;
+  description?: string;
+}
+interface FileSystemBackend extends FileSystemBackendOperations, FileSystemBackendMutableMethods {
+  readonly features: ReadonlySet<FileSystemBackendFeature>;
+  readonly meta: FileSystemBackendMeta;
+  hook: HookableCore<BackendHooks>["hook"];
+}
+interface BackendErrorHookPayload {
+  op: keyof (FileSystemBackendOperations & FileSystemBackendMutableOperations);
+  path: string;
+  error: Error;
+  sourcePath?: string;
+  destinationPath?: string;
+}
+interface BackendHooks {
+  "error": (payload: BackendErrorHookPayload) => void;
+  "read:before": (payload: {
+    path: string;
+  }) => void;
+  "read:after": (payload: {
+    path: string;
+    content: string;
+  }) => void;
+  "readBytes:before": (payload: {
+    path: string;
+  }) => void;
+  "readBytes:after": (payload: {
+    path: string;
+    data: Uint8Array;
+  }) => void;
+  "list:before": (payload: {
+    path: string;
+    recursive: boolean;
+  }) => void;
+  "list:after": (payload: {
+    path: string;
+    recursive: boolean;
+    entries: BackendEntry$1[];
+  }) => void;
+  "exists:before": (payload: {
+    path: string;
+  }) => void;
+  "exists:after": (payload: {
+    path: string;
+    result: boolean;
+  }) => void;
+  "stat:before": (payload: {
+    path: string;
+  }) => void;
+  "stat:after": (payload: {
+    path: string;
+    stat: BackendStat;
+  }) => void;
+  "write:before": (payload: {
+    path: string;
+    data: string | Uint8Array;
+  }) => void;
+  "write:after": (payload: {
+    path: string;
+  }) => void;
+  "mkdir:before": (payload: {
+    path: string;
+  }) => void;
+  "mkdir:after": (payload: {
+    path: string;
+  }) => void;
+  "remove:before": (payload: {
+    path: string;
+  } & RemoveOptions) => void;
+  "remove:after": (payload: {
+    path: string;
+  } & RemoveOptions) => void;
+  "copy:before": (payload: {
+    sourcePath: string;
+    destinationPath: string;
+  } & CopyOptions) => void;
+  "copy:after": (payload: {
+    sourcePath: string;
+    destinationPath: string;
+  } & CopyOptions) => void;
+} //#endregion
+//#endregion
 //#region src/lockfile.d.ts
 /**
  * Result of validating a lockfile
@@ -100,40 +254,73 @@ interface ValidateLockfileResult {
  */
 declare function validateLockfile(data: unknown): ValidateLockfileResult;
 /**
- * Checks if the filesystem bridge supports lockfile operations (requires write capability)
+ * Checks if the filesystem backend supports lockfile operations (requires write & mkdir features)
  *
- * @param {FileSystemBridge} fs - The filesystem bridge to check
- * @returns {boolean} True if the bridge supports lockfile operations
+ * @param {FileSystemBackend} fs - The filesystem backend to check
+ * @returns {boolean} True if the filesystem supports lockfile operations
  */
-declare function canUseLockfile(fs: FileSystemBridge): fs is FileSystemBridge & Required<Pick<FileSystemBridge, "write">>;
+declare function canUseLockfile(fs: FileSystemBackend): boolean;
 /**
  * Reads and validates a lockfile from the filesystem.
  *
- * @param {FileSystemBridge} fs - Filesystem bridge to use for reading
+ * @param {FileSystemBackend} fs - Filesystem backend to use for reading
  * @param {string} lockfilePath - Path to the lockfile
  * @returns {Promise<Lockfile>} A promise that resolves to the validated lockfile
  * @throws {LockfileInvalidError} When the lockfile is invalid or missing
  */
-declare function readLockfile(fs: FileSystemBridge, lockfilePath: string): Promise<Lockfile>;
+declare function readLockfile(fs: FileSystemBackend, lockfilePath: string): Promise<Lockfile>;
 /**
  * Writes a lockfile to the filesystem.
- * If the filesystem bridge does not support write operations, the function
+ * If the filesystem backend does not support write operations, the function
  * will skip writing the lockfile and return without throwing.
  *
- * @param {FileSystemBridge} fs - Filesystem bridge to use for writing
+ * @param {FileSystemBackend} fs - Filesystem backend to use for writing
  * @param {string} lockfilePath - Path where the lockfile should be written
  * @param {LockfileInput} lockfile - The lockfile data to write
  * @returns {Promise<void>} A promise that resolves when the lockfile has been written
  */
-declare function writeLockfile(fs: FileSystemBridge, lockfilePath: string, lockfile: LockfileInput): Promise<void>;
+declare function writeLockfile(fs: FileSystemBackend, lockfilePath: string, lockfile: LockfileInput): Promise<void>;
 /**
  * Reads a lockfile or returns undefined if it doesn't exist or is invalid.
  *
- * @param {FileSystemBridge} fs - Filesystem bridge to use for reading
+ * @param {FileSystemBackend} fs - Filesystem backend to use for reading
  * @param {string} lockfilePath - Path to the lockfile
  * @returns {Promise<Lockfile | undefined>} A promise that resolves to the lockfile or undefined
  */
-declare function readLockfileOrUndefined(fs: FileSystemBridge, lockfilePath: string): Promise<Lockfile | undefined>;
+declare function readLockfileOrUndefined(fs: FileSystemBackend, lockfilePath: string): Promise<Lockfile | undefined>;
+/**
+ * Parses and validates lockfile content from a raw string without requiring a filesystem bridge.
+ * Useful when lockfile content has been obtained from any source (HTTP, KV store, memory, etc.).
+ *
+ * @param {string} content - The raw lockfile content to parse
+ * @returns {Lockfile} The validated lockfile
+ * @throws {LockfileInvalidError} When the content is invalid or does not match the expected schema
+ *
+ * @example
+ * ```ts
+ * const response = await fetch("https://ucdjs.dev/.ucd-store.lock");
+ * const content = await response.text();
+ * const lockfile = parseLockfile(content);
+ * ```
+ */
+declare function parseLockfile(content: string): Lockfile;
+/**
+ * Parses and validates lockfile content from a raw string, returning undefined if parsing fails.
+ *
+ * @param {string} content - The raw lockfile content to parse
+ * @returns {Lockfile | undefined} The validated lockfile or undefined if parsing fails
+ *
+ * @example
+ * ```ts
+ * const response = await fetch("https://ucdjs.dev/.ucd-store.lock");
+ * const content = await response.text();
+ * const lockfile = parseLockfileOrUndefined(content);
+ * if (lockfile) {
+ *   console.log("Lockfile version:", lockfile.lockfileVersion);
+ * }
+ * ```
+ */
+declare function parseLockfileOrUndefined(content: string): Lockfile | undefined;
 //#endregion
 //#region src/paths.d.ts
 /**
@@ -156,30 +343,62 @@ declare function getSnapshotPath(version: string): string;
 /**
  * Reads and validates a snapshot for a specific version.
  *
- * @param {FileSystemBridge} fs - Filesystem bridge to use for reading
+ * @param {FileSystemBackend} fs - Filesystem backend to use for reading
  * @param {string} version - The Unicode version
  * @returns {Promise<Snapshot>} A promise that resolves to the validated snapshot
  * @throws {LockfileInvalidError} When the snapshot is invalid or missing
  */
-declare function readSnapshot(fs: FileSystemBridge, version: string): Promise<Snapshot>;
+declare function readSnapshot(fs: FileSystemBackend, version: string): Promise<Snapshot>;
 /**
  * Writes a snapshot for a specific version to the filesystem.
- * Only works if the filesystem bridge supports write operations.
+ * Only works if the filesystem backend supports write operations.
  *
- * @param {FileSystemBridge} fs - Filesystem bridge to use for writing
+ * @param {FileSystemBackend} fs - Filesystem backend to use for writing
  * @param {string} version - The Unicode version
  * @param {Snapshot} snapshot - The snapshot data to write
  * @returns {Promise<void>} A promise that resolves when the snapshot has been written
- * @throws {LockfileBridgeUnsupportedOperation} When directory doesn't exist and mkdir is not available
  */
-declare function writeSnapshot(fs: FileSystemBridge, version: string, snapshot: Snapshot): Promise<void>;
+declare function writeSnapshot(fs: FileSystemBackend, version: string, snapshot: Snapshot): Promise<void>;
 /**
  * Reads a snapshot or returns undefined if it doesn't exist or is invalid.
  *
- * @param {FileSystemBridge} fs - Filesystem bridge to use for reading
+ * @param {FileSystemBackend} fs - Filesystem backend to use for reading
  * @param {string} version - The Unicode version
  * @returns {Promise<Snapshot | undefined>} A promise that resolves to the snapshot or undefined
  */
-declare function readSnapshotOrUndefined(fs: FileSystemBridge, version: string): Promise<Snapshot | undefined>;
+declare function readSnapshotOrUndefined(fs: FileSystemBackend, version: string): Promise<Snapshot | undefined>;
+/**
+ * Parses and validates snapshot content from a raw string without requiring a filesystem bridge.
+ * Useful when snapshot content has been obtained from any source (HTTP, KV store, memory, etc.).
+ *
+ * @param {string} content - The raw snapshot content to parse
+ * @returns {Snapshot} The validated snapshot
+ * @throws {LockfileInvalidError} When the content is invalid or does not match the expected schema
+ *
+ * @example
+ * ```ts
+ * const response = await fetch("https://ucdjs.dev/16.0.0/snapshot.json");
+ * const content = await response.text();
+ * const snapshot = parseSnapshot(content);
+ * ```
+ */
+declare function parseSnapshot(content: string): Snapshot;
+/**
+ * Parses and validates snapshot content from a raw string, returning undefined if parsing fails.
+ *
+ * @param {string} content - The raw snapshot content to parse
+ * @returns {Snapshot | undefined} The validated snapshot or undefined if parsing fails
+ *
+ * @example
+ * ```ts
+ * const response = await fetch("https://ucdjs.dev/16.0.0/snapshot.json");
+ * const content = await response.text();
+ * const snapshot = parseSnapshotOrUndefined(content);
+ * if (snapshot) {
+ *   console.log("Unicode version:", snapshot.unicodeVersion);
+ * }
+ * ```
+ */
+declare function parseSnapshotOrUndefined(content: string): Snapshot | undefined;
 //#endregion
-export { LockfileBaseError, LockfileBridgeUnsupportedOperation, LockfileInvalidError, type ValidateLockfileResult, canUseLockfile, computeFileHash, computeFileHashWithoutUCDHeader, getLockfilePath, getSnapshotPath, readLockfile, readLockfileOrUndefined, readSnapshot, readSnapshotOrUndefined, stripUnicodeHeader, validateLockfile, writeLockfile, writeSnapshot };
+export { LockfileBaseError, LockfileInvalidError, type ValidateLockfileResult, canUseLockfile, computeFileHash, computeFileHashWithoutUCDHeader, getLockfilePath, getSnapshotPath, parseLockfile, parseLockfileOrUndefined, parseSnapshot, parseSnapshotOrUndefined, readLockfile, readLockfileOrUndefined, readSnapshot, readSnapshotOrUndefined, stripUnicodeHeader, validateLockfile, writeLockfile, writeSnapshot };

package/dist/index.mjs

@@ -1,9 +1,7 @@
-import { n as computeFileHashWithoutUCDHeader, r as stripUnicodeHeader, t as computeFileHash } from "./hash-DYmMzCbf.mjs";
-import { createDebugger, safeJsonParse, tryOr } from "@ucdjs-internal/shared";
-import { hasCapability } from "@ucdjs/fs-bridge";
+import { n as computeFileHashWithoutUCDHeader, r as stripUnicodeHeader, t as computeFileHash } from "./hash-Bf5WIJe6.mjs";
+import { createDebugger, safeJsonParse } from "@ucdjs-internal/shared";
 import { LockfileSchema, SnapshotSchema } from "@ucdjs/schemas";
 import { dirname, join } from "pathe";
-
 //#region src/errors.ts
 /**
 * Base error class for lockfile-related errors
@@ -29,25 +27,6 @@ var LockfileInvalidError = class LockfileInvalidError extends LockfileBaseError
 		Object.setPrototypeOf(this, LockfileInvalidError.prototype);
 	}
 };
-/**
-* Error thrown when a filesystem bridge operation is not supported
-*/
-var LockfileBridgeUnsupportedOperation = class LockfileBridgeUnsupportedOperation extends LockfileBaseError {
-	operation;
-	requiredCapabilities;
-	availableCapabilities;
-	constructor(operation, requiredCapabilities, availableCapabilities) {
-		let message = `Operation "${operation}" is not supported.`;
-		if (requiredCapabilities.length > 0 || availableCapabilities.length > 0) message += ` Required capabilities: ${requiredCapabilities.join(", ")}. Available capabilities: ${availableCapabilities.join(", ")}`;
-		super(message);
-		this.name = "LockfileBridgeUnsupportedOperation";
-		this.operation = operation;
-		this.requiredCapabilities = requiredCapabilities;
-		this.availableCapabilities = availableCapabilities;
-		Object.setPrototypeOf(this, LockfileBridgeUnsupportedOperation.prototype);
-	}
-};
-
 //#endregion
 //#region src/lockfile.ts
 const debug$1 = createDebugger("ucdjs:lockfile");
@@ -84,40 +63,21 @@ function validateLockfile(data) {
 	};
 }
 /**
-* Checks if the filesystem bridge supports lockfile operations (requires write capability)
+* Checks if the filesystem backend supports lockfile operations (requires write & mkdir features)
 *
-* @param {FileSystemBridge} fs - The filesystem bridge to check
-* @returns {boolean} True if the bridge supports lockfile operations
+* @param {FileSystemBackend} fs - The filesystem backend to check
+* @returns {boolean} True if the filesystem supports lockfile operations
 */
 function canUseLockfile(fs) {
-	return hasCapability(fs, "write");
+	return fs.features.has("write") && fs.features.has("mkdir");
 }
 /**
-* Reads and validates a lockfile from the filesystem.
-*
-* @param {FileSystemBridge} fs - Filesystem bridge to use for reading
-* @param {string} lockfilePath - Path to the lockfile
-* @returns {Promise<Lockfile>} A promise that resolves to the validated lockfile
-* @throws {LockfileInvalidError} When the lockfile is invalid or missing
+* Internal helper: parses and validates raw JSON content against the LockfileSchema.
+* Throws LockfileInvalidError with the given `lockfilePath` context on failure.
 */
-async function readLockfile(fs, lockfilePath) {
-	debug$1?.("Reading lockfile from:", lockfilePath);
-	const lockfileData = await tryOr({
-		try: fs.read(lockfilePath),
-		err: (err) => {
-			debug$1?.("Failed to read lockfile:", err);
-			throw new LockfileInvalidError({
-				lockfilePath,
-				message: "lockfile could not be read"
-			});
-		}
-	});
-	if (!lockfileData) throw new LockfileInvalidError({
-		lockfilePath,
-		message: "lockfile is empty"
-	});
-	const jsonData = safeJsonParse(lockfileData);
-	if (!jsonData) throw new LockfileInvalidError({
+function parseLockfileFromContent(content, lockfilePath) {
+	const jsonData = safeJsonParse(content);
+	if (jsonData === null) throw new LockfileInvalidError({
 		lockfilePath,
 		message: "lockfile is not valid JSON"
 	});
@@ -130,32 +90,64 @@ async function readLockfile(fs, lockfilePath) {
 			details: parsedLockfile.error.issues.map((issue) => issue.message)
 		});
 	}
-	debug$1?.("Successfully read lockfile");
 	return parsedLockfile.data;
 }
 /**
+* Reads and validates a lockfile from the filesystem.
+*
+* @param {FileSystemBackend} fs - Filesystem backend to use for reading
+* @param {string} lockfilePath - Path to the lockfile
+* @returns {Promise<Lockfile>} A promise that resolves to the validated lockfile
+* @throws {LockfileInvalidError} When the lockfile is invalid or missing
+*/
+async function readLockfile(fs, lockfilePath) {
+	debug$1?.("Reading lockfile from:", lockfilePath);
+	let lockfileData;
+	try {
+		lockfileData = await fs.read(lockfilePath);
+	} catch (err) {
+		debug$1?.("Failed to read lockfile:", err);
+		throw new LockfileInvalidError({
+			lockfilePath,
+			message: "lockfile could not be read"
+		});
+	}
+	if (!lockfileData) throw new LockfileInvalidError({
+		lockfilePath,
+		message: "lockfile is empty"
+	});
+	debug$1?.("Successfully read lockfile");
+	return parseLockfileFromContent(lockfileData, lockfilePath);
+}
+/**
 * Writes a lockfile to the filesystem.
-* If the filesystem bridge does not support write operations, the function
+* If the filesystem backend does not support write operations, the function
 * will skip writing the lockfile and return without throwing.
 *
-* @param {FileSystemBridge} fs - Filesystem bridge to use for writing
+* @param {FileSystemBackend} fs - Filesystem backend to use for writing
 * @param {string} lockfilePath - Path where the lockfile should be written
 * @param {LockfileInput} lockfile - The lockfile data to write
 * @returns {Promise<void>} A promise that resolves when the lockfile has been written
 */
 async function writeLockfile(fs, lockfilePath, lockfile) {
 	if (!canUseLockfile(fs)) {
-		debug$1?.("Filesystem bridge does not support write operations, skipping lockfile write");
+		debug$1?.("Filesystem does not support write operations, skipping lockfile write");
 		return;
 	}
 	debug$1?.("Writing lockfile to:", lockfilePath);
+	const lockfileDir = dirname(lockfilePath);
+	debug$1?.("Writing lockfile to:", lockfilePath);
+	if (!await fs.exists(lockfileDir)) {
+		debug$1?.("Creating lockfile directory:", lockfileDir);
+		await fs.mkdir(lockfileDir);
+	}
 	await fs.write(lockfilePath, JSON.stringify(lockfile, null, 2));
 	debug$1?.("Successfully wrote lockfile");
 }
 /**
 * Reads a lockfile or returns undefined if it doesn't exist or is invalid.
 *
-* @param {FileSystemBridge} fs - Filesystem bridge to use for reading
+* @param {FileSystemBackend} fs - Filesystem backend to use for reading
 * @param {string} lockfilePath - Path to the lockfile
 * @returns {Promise<Lockfile | undefined>} A promise that resolves to the lockfile or undefined
 */
@@ -164,7 +156,54 @@ async function readLockfileOrUndefined(fs, lockfilePath) {
 		debug$1?.("Failed to read lockfile, returning undefined");
 	});
 }
-
+/**
+* Parses and validates lockfile content from a raw string without requiring a filesystem bridge.
+* Useful when lockfile content has been obtained from any source (HTTP, KV store, memory, etc.).
+*
+* @param {string} content - The raw lockfile content to parse
+* @returns {Lockfile} The validated lockfile
+* @throws {LockfileInvalidError} When the content is invalid or does not match the expected schema
+*
+* @example
+* ```ts
+* const response = await fetch("https://ucdjs.dev/.ucd-store.lock");
+* const content = await response.text();
+* const lockfile = parseLockfile(content);
+* ```
+*/
+function parseLockfile(content) {
+	debug$1?.("Parsing lockfile from content");
+	if (!content) throw new LockfileInvalidError({
+		lockfilePath: "<content>",
+		message: "lockfile is empty"
+	});
+	debug$1?.("Successfully parsed lockfile");
+	return parseLockfileFromContent(content, "<content>");
+}
+/**
+* Parses and validates lockfile content from a raw string, returning undefined if parsing fails.
+*
+* @param {string} content - The raw lockfile content to parse
+* @returns {Lockfile | undefined} The validated lockfile or undefined if parsing fails
+*
+* @example
+* ```ts
+* const response = await fetch("https://ucdjs.dev/.ucd-store.lock");
+* const content = await response.text();
+* const lockfile = parseLockfileOrUndefined(content);
+* if (lockfile) {
+*   console.log("Lockfile version:", lockfile.lockfileVersion);
+* }
+* ```
+*/
+function parseLockfileOrUndefined(content) {
+	try {
+		return parseLockfile(content);
+	} catch {
+		debug$1?.("Failed to parse lockfile, returning undefined");
+		return;
+	}
+}
 //#endregion
 //#region src/paths.ts
 /**
@@ -186,37 +225,16 @@ function getLockfilePath() {
 function getSnapshotPath(version) {
 	return join(version, "snapshot.json");
 }
-
 //#endregion
 //#region src/snapshot.ts
 const debug = createDebugger("ucdjs:lockfile:snapshot");
 /**
-* Reads and validates a snapshot for a specific version.
-*
-* @param {FileSystemBridge} fs - Filesystem bridge to use for reading
-* @param {string} version - The Unicode version
-* @returns {Promise<Snapshot>} A promise that resolves to the validated snapshot
-* @throws {LockfileInvalidError} When the snapshot is invalid or missing
+* Internal helper: parses and validates raw JSON content against the SnapshotSchema.
+* Throws LockfileInvalidError with the given `snapshotPath` context on failure.
 */
-async function readSnapshot(fs, version) {
-	const snapshotPath = getSnapshotPath(version);
-	debug?.("Reading snapshot from:", snapshotPath);
-	const snapshotData = await tryOr({
-		try: fs.read(snapshotPath),
-		err: (err) => {
-			debug?.("Failed to read snapshot:", err);
-			throw new LockfileInvalidError({
-				lockfilePath: snapshotPath,
-				message: "snapshot could not be read"
-			});
-		}
-	});
-	if (!snapshotData) throw new LockfileInvalidError({
-		lockfilePath: snapshotPath,
-		message: "snapshot is empty"
-	});
-	const jsonData = safeJsonParse(snapshotData);
-	if (!jsonData) throw new LockfileInvalidError({
+function parseSnapshotFromContent(content, snapshotPath) {
+	const jsonData = safeJsonParse(content);
+	if (jsonData === null) throw new LockfileInvalidError({
 		lockfilePath: snapshotPath,
 		message: "snapshot is not valid JSON"
 	});
@@ -229,29 +247,54 @@ async function readSnapshot(fs, version) {
 			details: parsedSnapshot.error.issues.map((issue) => issue.message)
 		});
 	}
-	debug?.("Successfully read snapshot");
 	return parsedSnapshot.data;
 }
 /**
+* Reads and validates a snapshot for a specific version.
+*
+* @param {FileSystemBackend} fs - Filesystem backend to use for reading
+* @param {string} version - The Unicode version
+* @returns {Promise<Snapshot>} A promise that resolves to the validated snapshot
+* @throws {LockfileInvalidError} When the snapshot is invalid or missing
+*/
+async function readSnapshot(fs, version) {
+	const snapshotPath = getSnapshotPath(version);
+	debug?.("Reading snapshot from:", snapshotPath);
+	let snapshotData;
+	try {
+		snapshotData = await fs.read(snapshotPath);
+	} catch (err) {
+		debug?.("Failed to read snapshot:", err);
+		throw new LockfileInvalidError({
+			lockfilePath: snapshotPath,
+			message: "snapshot could not be read"
+		});
+	}
+	if (!snapshotData) throw new LockfileInvalidError({
+		lockfilePath: snapshotPath,
+		message: "snapshot is empty"
+	});
+	debug?.("Successfully read snapshot");
+	return parseSnapshotFromContent(snapshotData, snapshotPath);
+}
+/**
 * Writes a snapshot for a specific version to the filesystem.
-* Only works if the filesystem bridge supports write operations.
+* Only works if the filesystem backend supports write operations.
 *
-* @param {FileSystemBridge} fs - Filesystem bridge to use for writing
+* @param {FileSystemBackend} fs - Filesystem backend to use for writing
 * @param {string} version - The Unicode version
 * @param {Snapshot} snapshot - The snapshot data to write
 * @returns {Promise<void>} A promise that resolves when the snapshot has been written
-* @throws {LockfileBridgeUnsupportedOperation} When directory doesn't exist and mkdir is not available
 */
 async function writeSnapshot(fs, version, snapshot) {
 	if (!canUseLockfile(fs)) {
-		debug?.("Filesystem bridge does not support write operations, skipping snapshot write");
+		debug?.("Filesystem does not support write operations, skipping snapshot write");
 		return;
 	}
 	const snapshotPath = getSnapshotPath(version);
 	const snapshotDir = dirname(snapshotPath);
 	debug?.("Writing snapshot to:", snapshotPath);
 	if (!await fs.exists(snapshotDir)) {
-		if (!hasCapability(fs, "mkdir")) throw new LockfileBridgeUnsupportedOperation("writeSnapshot", ["mkdir"], Object.keys(fs.optionalCapabilities).filter((k) => fs.optionalCapabilities[k]));
 		debug?.("Creating snapshot directory:", snapshotDir);
 		await fs.mkdir(snapshotDir);
 	}
@@ -261,7 +304,7 @@ async function writeSnapshot(fs, version, snapshot) {
 /**
 * Reads a snapshot or returns undefined if it doesn't exist or is invalid.
 *
-* @param {FileSystemBridge} fs - Filesystem bridge to use for reading
+* @param {FileSystemBackend} fs - Filesystem backend to use for reading
 * @param {string} version - The Unicode version
 * @returns {Promise<Snapshot | undefined>} A promise that resolves to the snapshot or undefined
 */
@@ -270,6 +313,53 @@ async function readSnapshotOrUndefined(fs, version) {
 		debug?.("Failed to read snapshot, returning undefined", err);
 	});
 }
-
+/**
+* Parses and validates snapshot content from a raw string without requiring a filesystem bridge.
+* Useful when snapshot content has been obtained from any source (HTTP, KV store, memory, etc.).
+*
+* @param {string} content - The raw snapshot content to parse
+* @returns {Snapshot} The validated snapshot
+* @throws {LockfileInvalidError} When the content is invalid or does not match the expected schema
+*
+* @example
+* ```ts
+* const response = await fetch("https://ucdjs.dev/16.0.0/snapshot.json");
+* const content = await response.text();
+* const snapshot = parseSnapshot(content);
+* ```
+*/
+function parseSnapshot(content) {
+	debug?.("Parsing snapshot from content");
+	if (!content) throw new LockfileInvalidError({
+		lockfilePath: "<content>",
+		message: "snapshot is empty"
+	});
+	debug?.("Successfully parsed snapshot");
+	return parseSnapshotFromContent(content, "<content>");
+}
+/**
+* Parses and validates snapshot content from a raw string, returning undefined if parsing fails.
+*
+* @param {string} content - The raw snapshot content to parse
+* @returns {Snapshot | undefined} The validated snapshot or undefined if parsing fails
+*
+* @example
+* ```ts
+* const response = await fetch("https://ucdjs.dev/16.0.0/snapshot.json");
+* const content = await response.text();
+* const snapshot = parseSnapshotOrUndefined(content);
+* if (snapshot) {
+*   console.log("Unicode version:", snapshot.unicodeVersion);
+* }
+* ```
+*/
+function parseSnapshotOrUndefined(content) {
+	try {
+		return parseSnapshot(content);
+	} catch {
+		debug?.("Failed to parse snapshot, returning undefined");
+		return;
+	}
+}
 //#endregion
-export { LockfileBaseError, LockfileBridgeUnsupportedOperation, LockfileInvalidError, canUseLockfile, computeFileHash, computeFileHashWithoutUCDHeader, getLockfilePath, getSnapshotPath, readLockfile, readLockfileOrUndefined, readSnapshot, readSnapshotOrUndefined, stripUnicodeHeader, validateLockfile, writeLockfile, writeSnapshot };
+export { LockfileBaseError, LockfileInvalidError, canUseLockfile, computeFileHash, computeFileHashWithoutUCDHeader, getLockfilePath, getSnapshotPath, parseLockfile, parseLockfileOrUndefined, parseSnapshot, parseSnapshotOrUndefined, readLockfile, readLockfileOrUndefined, readSnapshot, readSnapshotOrUndefined, stripUnicodeHeader, validateLockfile, writeLockfile, writeSnapshot };

package/dist/test-utils/index.mjs

@@ -1,5 +1,4 @@
-import { n as computeFileHashWithoutUCDHeader, t as computeFileHash } from "../hash-DYmMzCbf.mjs";
-
+import { n as computeFileHashWithoutUCDHeader, t as computeFileHash } from "../hash-Bf5WIJe6.mjs";
 //#region src/test-utils/lockfile-builder.ts
 /**
 * Creates a lockfile entry for a single version
@@ -59,7 +58,6 @@ function createLockfile(versions, options) {
 	};
 	return lockfile;
 }
-
 //#endregion
 //#region src/test-utils/snapshot-builder.ts
 /**
@@ -99,6 +97,5 @@ function createSnapshotWithHashes(version, files) {
 		}]))
 	};
 }
-
 //#endregion
-export { createEmptyLockfile, createLockfile, createLockfileEntry, createSnapshot, createSnapshotWithHashes };
+export { createEmptyLockfile, createLockfile, createLockfileEntry, createSnapshot, createSnapshotWithHashes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ucdjs/lockfile",
-  "version": "0.1.1-beta.7",
+  "version": "0.1.1-beta.8",
   "type": "module",
   "author": {
     "name": "Lucas Nørgård",
@@ -31,24 +31,27 @@
   },
   "dependencies": {
     "pathe": "2.0.3",
-    "@ucdjs/schemas": "0.1.1-beta.7",
-    "@ucdjs-internal/shared": "0.1.1-beta.7",
-    "@ucdjs/fs-bridge": "0.1.1-beta.7"
+    "@ucdjs/schemas": "0.1.1-beta.8",
+    "@ucdjs-internal/shared": "0.1.1-beta.8"
   },
   "devDependencies": {
-    "@luxass/eslint-config": "7.2.1",
+    "@luxass/eslint-config": "7.4.1",
     "@luxass/utils": "2.7.3",
-    "eslint": "10.0.2",
-    "publint": "0.3.17",
-    "tsdown": "0.20.3",
-    "typescript": "5.9.3",
-    "vitest-testdirs": "4.4.2",
+    "eslint": "10.1.0",
+    "publint": "0.3.18",
+    "tsdown": "0.21.4",
+    "typescript": "6.0.2",
+    "vitest-testdirs": "4.4.3",
     "@ucdjs-tooling/tsconfig": "1.0.0",
-    "@ucdjs-tooling/tsdown-config": "1.0.0"
+    "@ucdjs-tooling/tsdown-config": "1.0.0",
+    "@ucdjs/fs-backend": "0.1.0-beta.0"
   },
   "publishConfig": {
     "access": "public"
   },
+  "inlinedDependencies": {
+    "hookable": "6.1.0"
+  },
   "scripts": {
     "build": "tsdown --tsconfig=./tsconfig.build.json",
     "dev": "tsdown --watch",