@ucdjs/lockfile 0.1.1-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Lucas Nørgård
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# @ucdjs/lockfile
+
+Lockfile and snapshot management utilities for UCD stores.
+
+## Installation
+
+```bash
+pnpm add @ucdjs/lockfile
+```
+
+## Usage
+
+### Reading and Writing Lockfiles
+
+```typescript
+import { NodeFileSystemBridge } from "@ucdjs/fs-bridge";
+import { getLockfilePath, readLockfile, writeLockfile } from "@ucdjs/lockfile";
+
+const fs = NodeFileSystemBridge({ basePath: "./store" });
+const lockfilePath = getLockfilePath("./store");
+
+// Read lockfile
+const lockfile = await readLockfile(fs, lockfilePath);
+
+// Write lockfile
+await writeLockfile(fs, lockfilePath, {
+  lockfileVersion: 1,
+  versions: {
+    "16.0.0": {
+      path: "16.0.0/snapshot.json",
+      fileCount: 10,
+      totalSize: 1024,
+    },
+  },
+});
+```
+
+### Reading and Writing Snapshots
+
+```typescript
+import { getSnapshotPath, readSnapshot, writeSnapshot } from "@ucdjs/lockfile";
+
+const basePath = "./store";
+const version = "16.0.0";
+
+// Read snapshot
+const snapshot = await readSnapshot(fs, basePath, version);
+
+// Write snapshot
+await writeSnapshot(fs, basePath, version, {
+  unicodeVersion: "16.0.0",
+  files: {
+    "UnicodeData.txt": {
+      hash: "sha256:...",
+      size: 1024,
+    },
+  },
+});
+```
+
+### Computing File Hashes
+
+```typescript
+import { computeFileHash } from "@ucdjs/lockfile";
+
+const content = "file content";
+const hash = await computeFileHash(content);
+// Returns: "sha256:..."
+```
+
+## API Reference
+
+### Lockfile Operations
+
+- `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
+
+### 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
+
+### Path Utilities
+
+- `getLockfilePath(_basePath: string): string` - Get default lockfile path (`.ucd-store.lock`)
+- `getSnapshotPath(basePath: string, version: string): string` - Get snapshot path for version
+
+### Hash Utilities
+
+- `computeFileHash(content: string | Uint8Array): Promise<string>` - Compute SHA-256 hash
+
+### Error Types
+
+- `LockfileInvalidError` - Thrown when a lockfile or snapshot is invalid
+- `LockfileBridgeUnsupportedOperation` - Thrown when a filesystem bridge operation is not supported
+
+## Test Utilities
+
+The package also exports test utilities for creating lockfiles and snapshots in tests:
+
+```typescript
+import {
+  createEmptyLockfile,
+  createLockfile,
+  createLockfileEntry,
+  createSnapshot,
+  createSnapshotWithHashes,
+} from "@ucdjs/lockfile/test-utils";
+
+// Create an empty lockfile
+const lockfile = createEmptyLockfile(["16.0.0", "15.1.0"]);
+
+// Create a lockfile with custom options
+const customLockfile = createLockfile(["16.0.0"], {
+  fileCounts: { "16.0.0": 10 },
+  totalSizes: { "16.0.0": 1024 },
+});
+
+// Create a snapshot
+const snapshot = await createSnapshot("16.0.0", {
+  "UnicodeData.txt": "file content",
+  "Blocks.txt": "more content",
+});
+```
+
+## License
+
+MIT

package/dist/hash-DYmMzCbf.mjs

@@ -0,0 +1,107 @@
+//#region src/hash.ts
+/**
+* Checks if a line looks like a Unicode header line.
+* Header lines typically contain:
+* - Filename with version (e.g., "DerivedBinaryProperties-15.1.0.txt")
+* - Date line (e.g., "Date: 2023-01-05")
+* - Copyright line (e.g., "© 2023 Unicode®, Inc.")
+*
+* Uses simple string operations instead of complex regex to avoid ReDoS vulnerabilities.
+*
+* @internal
+*/
+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);
+}
+/**
+* Strips the Unicode file header from content.
+* The header typically contains:
+* - Filename with version (e.g., "# DerivedBinaryProperties-15.1.0.txt")
+* - Date line (e.g., "# Date: 2023-01-05, 20:34:33 GMT")
+* - Copyright line (e.g., "# © 2023 Unicode®, Inc.")
+*
+* @param {string} content - The file content to strip the header from
+* @returns {string} The content with the header stripped
+*/
+function stripUnicodeHeader(content) {
+	const lines = content.split("\n");
+	let headerEndIndex = 0;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (line == null) continue;
+		const trimmedLine = line.trim();
+		if (trimmedLine === "" || trimmedLine === "#") continue;
+		if (trimmedLine.startsWith("#") && isHeaderLine(trimmedLine)) {
+			headerEndIndex = i + 1;
+			continue;
+		}
+		break;
+	}
+	if (headerEndIndex > 0) {
+		while (headerEndIndex < lines.length && lines[headerEndIndex]?.trim() === "") headerEndIndex++;
+		return lines.slice(headerEndIndex).join("\n");
+	}
+	return content;
+}
+/**
+* Cached TextEncoder instance for UTF-8 string encoding.
+*
+* @internal
+*/
+const textEncoder = new TextEncoder();
+/**
+* Hex characters for nibble-to-hex conversion.
+*
+* @internal
+*/
+const HEX_CHARS = "0123456789abcdef";
+/**
+* Pre-computed lookup table for byte-to-hex conversion.
+* Maps each byte value (0-255) to its two-character hex representation.
+* Uses bit operations to extract high and low nibbles.
+*
+* @internal
+*/
+const HEX_TABLE = [];
+for (let i = 0; i < 256; i++) HEX_TABLE[i] = HEX_CHARS[i >> 4] + HEX_CHARS[i & 15];
+/**
+* Converts a Uint8Array to a hex string using pre-computed lookup table.
+*
+* @internal
+*/
+function uint8ArrayToHex(bytes) {
+	let result = "";
+	for (let i = 0; i < bytes.length; i++) result += HEX_TABLE[bytes[i]];
+	return result;
+}
+/**
+* Computes the SHA-256 hash of file content using Web Crypto API.
+*
+* @param {string | Uint8Array} content - The file content to hash
+* @returns {Promise<string>} A promise that resolves to the hash in format "sha256:..."
+* @throws {Error} When Web Crypto API is not available
+*/
+async function computeFileHash(content) {
+	const data = typeof content === "string" ? textEncoder.encode(content) : content;
+	if (typeof crypto !== "undefined" && crypto.subtle && typeof crypto.subtle.digest === "function") {
+		const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+		return `sha256:${uint8ArrayToHex(new Uint8Array(hashBuffer))}`;
+	}
+	throw new Error("SHA-256 hashing is not available. Web Crypto API is required for hash computation.");
+}
+/**
+* Computes the SHA-256 hash of file content after stripping the Unicode header.
+* This is useful for comparing file content across versions, since the header
+* contains version-specific information (version number, date, copyright year).
+*
+* @param {string} content - The file content to hash
+* @returns {Promise<string>} A promise that resolves to the hash in format "sha256:..."
+* @throws {Error} When Web Crypto API is not available
+*/
+async function computeFileHashWithoutUCDHeader(content) {
+	return computeFileHash(stripUnicodeHeader(content));
+}
+
+//#endregion
+export { computeFileHashWithoutUCDHeader as n, stripUnicodeHeader as r, computeFileHash as t };

package/dist/index.d.mts

@@ -0,0 +1,185 @@
+import { FileSystemBridge } from "@ucdjs/fs-bridge";
+import { Lockfile, LockfileInput, Snapshot } from "@ucdjs/schemas";
+
+//#region src/errors.d.ts
+/**
+ * Base error class for lockfile-related errors
+ */
+declare class LockfileBaseError extends Error {
+  constructor(message: string);
+}
+/**
+ * Error thrown when a lockfile or snapshot is invalid or cannot be read
+ */
+declare class LockfileInvalidError extends LockfileBaseError {
+  readonly lockfilePath: string;
+  readonly details: string[];
+  constructor({
+    lockfilePath,
+    message,
+    details
+  }: {
+    lockfilePath: string;
+    message: string;
+    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
+/**
+ * Strips the Unicode file header from content.
+ * The header typically contains:
+ * - Filename with version (e.g., "# DerivedBinaryProperties-15.1.0.txt")
+ * - Date line (e.g., "# Date: 2023-01-05, 20:34:33 GMT")
+ * - Copyright line (e.g., "# © 2023 Unicode®, Inc.")
+ *
+ * @param {string} content - The file content to strip the header from
+ * @returns {string} The content with the header stripped
+ */
+declare function stripUnicodeHeader(content: string): string;
+/**
+ * Computes the SHA-256 hash of file content using Web Crypto API.
+ *
+ * @param {string | Uint8Array} content - The file content to hash
+ * @returns {Promise<string>} A promise that resolves to the hash in format "sha256:..."
+ * @throws {Error} When Web Crypto API is not available
+ */
+declare function computeFileHash(content: string | Uint8Array): Promise<string>;
+/**
+ * Computes the SHA-256 hash of file content after stripping the Unicode header.
+ * This is useful for comparing file content across versions, since the header
+ * contains version-specific information (version number, date, copyright year).
+ *
+ * @param {string} content - The file content to hash
+ * @returns {Promise<string>} A promise that resolves to the hash in format "sha256:..."
+ * @throws {Error} When Web Crypto API is not available
+ */
+declare function computeFileHashWithoutUCDHeader(content: string): Promise<string>;
+//#endregion
+//#region src/lockfile.d.ts
+/**
+ * Result of validating a lockfile
+ */
+interface ValidateLockfileResult {
+  /** Whether the lockfile is valid */
+  valid: boolean;
+  /** The parsed lockfile data (only present if valid) */
+  data?: Lockfile;
+  /** Validation errors (only present if invalid) */
+  errors?: Array<{
+    /** The path to the field that failed validation */path: string; /** Human-readable error message */
+    message: string; /** Zod error code */
+    code: string;
+  }>;
+}
+/**
+ * Validates lockfile data against the schema without reading from filesystem.
+ * Useful for validating lockfile objects before writing or for CLI validation commands.
+ *
+ * @param {unknown} data - The data to validate as a lockfile
+ * @returns {ValidateLockfileResult} Validation result with parsed data or errors
+ *
+ * @example
+ * ```ts
+ * const result = validateLockfile(someData);
+ * if (result.valid) {
+ *   console.log('Lockfile is valid:', result.data);
+ * } else {
+ *   console.error('Validation errors:', result.errors);
+ * }
+ * ```
+ */
+declare function validateLockfile(data: unknown): ValidateLockfileResult;
+/**
+ * Checks if the filesystem bridge supports lockfile operations (requires write capability)
+ *
+ * @param {FileSystemBridge} fs - The filesystem bridge to check
+ * @returns {boolean} True if the bridge supports lockfile operations
+ */
+declare function canUseLockfile(fs: FileSystemBridge): fs is FileSystemBridge & Required<Pick<FileSystemBridge, "write">>;
+/**
+ * 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
+ */
+declare function readLockfile(fs: FileSystemBridge, lockfilePath: string): Promise<Lockfile>;
+/**
+ * Writes a lockfile to the filesystem.
+ * If the filesystem bridge 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 {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>;
+/**
+ * Reads a lockfile or returns undefined if it doesn't exist or is invalid.
+ *
+ * @param {FileSystemBridge} fs - Filesystem bridge 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>;
+//#endregion
+//#region src/paths.d.ts
+/**
+ * Gets the lockfile filename.
+ * The lockfile is always named `.ucd-store.lock` and stored at the store root.
+ *
+ * @returns {string} The lockfile filename
+ */
+declare function getLockfilePath(): string;
+/**
+ * Gets the snapshot path for a given version (relative to store root).
+ * Snapshots are stored inside version directories: {version}/snapshot.json
+ *
+ * @param {string} version - The Unicode version
+ * @returns {string} The snapshot path relative to store root
+ */
+declare function getSnapshotPath(version: string): string;
+//#endregion
+//#region src/snapshot.d.ts
+/**
+ * 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
+ */
+declare function readSnapshot(fs: FileSystemBridge, version: string): Promise<Snapshot>;
+/**
+ * Writes a snapshot for a specific version to the filesystem.
+ * Only works if the filesystem bridge supports write operations.
+ *
+ * @param {FileSystemBridge} fs - Filesystem bridge 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>;
+/**
+ * Reads a snapshot or returns undefined if it doesn't exist or is invalid.
+ *
+ * @param {FileSystemBridge} fs - Filesystem bridge 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>;
+//#endregion
+export { LockfileBaseError, LockfileBridgeUnsupportedOperation, LockfileInvalidError, type ValidateLockfileResult, canUseLockfile, computeFileHash, computeFileHashWithoutUCDHeader, getLockfilePath, getSnapshotPath, readLockfile, readLockfileOrUndefined, readSnapshot, readSnapshotOrUndefined, stripUnicodeHeader, validateLockfile, writeLockfile, writeSnapshot };

package/dist/index.mjs

@@ -0,0 +1,275 @@
+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 { LockfileSchema, SnapshotSchema } from "@ucdjs/schemas";
+import { dirname, join } from "pathe";
+
+//#region src/errors.ts
+/**
+* Base error class for lockfile-related errors
+*/
+var LockfileBaseError = class LockfileBaseError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "LockfileBaseError";
+		Object.setPrototypeOf(this, LockfileBaseError.prototype);
+	}
+};
+/**
+* Error thrown when a lockfile or snapshot is invalid or cannot be read
+*/
+var LockfileInvalidError = class LockfileInvalidError extends LockfileBaseError {
+	lockfilePath;
+	details;
+	constructor({ lockfilePath, message, details }) {
+		super(`invalid lockfile at ${lockfilePath}: ${message}`);
+		this.name = "LockfileInvalidError";
+		this.lockfilePath = lockfilePath;
+		this.details = details || [];
+		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");
+/**
+* Validates lockfile data against the schema without reading from filesystem.
+* Useful for validating lockfile objects before writing or for CLI validation commands.
+*
+* @param {unknown} data - The data to validate as a lockfile
+* @returns {ValidateLockfileResult} Validation result with parsed data or errors
+*
+* @example
+* ```ts
+* const result = validateLockfile(someData);
+* if (result.valid) {
+*   console.log('Lockfile is valid:', result.data);
+* } else {
+*   console.error('Validation errors:', result.errors);
+* }
+* ```
+*/
+function validateLockfile(data) {
+	const result = LockfileSchema.safeParse(data);
+	if (result.success) return {
+		valid: true,
+		data: result.data
+	};
+	return {
+		valid: false,
+		errors: result.error.issues.map((issue) => ({
+			path: issue.path.join("."),
+			message: issue.message,
+			code: issue.code
+		}))
+	};
+}
+/**
+* Checks if the filesystem bridge supports lockfile operations (requires write capability)
+*
+* @param {FileSystemBridge} fs - The filesystem bridge to check
+* @returns {boolean} True if the bridge supports lockfile operations
+*/
+function canUseLockfile(fs) {
+	return hasCapability(fs, "write");
+}
+/**
+* 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
+*/
+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({
+		lockfilePath,
+		message: "lockfile is not valid JSON"
+	});
+	const parsedLockfile = LockfileSchema.safeParse(jsonData);
+	if (!parsedLockfile.success) {
+		debug$1?.("Failed to parse lockfile:", parsedLockfile.error.issues);
+		throw new LockfileInvalidError({
+			lockfilePath,
+			message: "lockfile does not match expected schema",
+			details: parsedLockfile.error.issues.map((issue) => issue.message)
+		});
+	}
+	debug$1?.("Successfully read lockfile");
+	return parsedLockfile.data;
+}
+/**
+* Writes a lockfile to the filesystem.
+* If the filesystem bridge 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 {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");
+		return;
+	}
+	debug$1?.("Writing lockfile to:", lockfilePath);
+	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 {string} lockfilePath - Path to the lockfile
+* @returns {Promise<Lockfile | undefined>} A promise that resolves to the lockfile or undefined
+*/
+async function readLockfileOrUndefined(fs, lockfilePath) {
+	return readLockfile(fs, lockfilePath).catch(() => {
+		debug$1?.("Failed to read lockfile, returning undefined");
+	});
+}
+
+//#endregion
+//#region src/paths.ts
+/**
+* Gets the lockfile filename.
+* The lockfile is always named `.ucd-store.lock` and stored at the store root.
+*
+* @returns {string} The lockfile filename
+*/
+function getLockfilePath() {
+	return ".ucd-store.lock";
+}
+/**
+* Gets the snapshot path for a given version (relative to store root).
+* Snapshots are stored inside version directories: {version}/snapshot.json
+*
+* @param {string} version - The Unicode version
+* @returns {string} The snapshot path relative to store root
+*/
+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
+*/
+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({
+		lockfilePath: snapshotPath,
+		message: "snapshot is not valid JSON"
+	});
+	const parsedSnapshot = SnapshotSchema.safeParse(jsonData);
+	if (!parsedSnapshot.success) {
+		debug?.("Failed to parse snapshot:", parsedSnapshot.error.issues);
+		throw new LockfileInvalidError({
+			lockfilePath: snapshotPath,
+			message: "snapshot does not match expected schema",
+			details: parsedSnapshot.error.issues.map((issue) => issue.message)
+		});
+	}
+	debug?.("Successfully read snapshot");
+	return parsedSnapshot.data;
+}
+/**
+* Writes a snapshot for a specific version to the filesystem.
+* Only works if the filesystem bridge supports write operations.
+*
+* @param {FileSystemBridge} fs - Filesystem bridge 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");
+		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);
+	}
+	await fs.write(snapshotPath, JSON.stringify(snapshot, null, 2));
+	debug?.("Successfully wrote 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 {string} version - The Unicode version
+* @returns {Promise<Snapshot | undefined>} A promise that resolves to the snapshot or undefined
+*/
+async function readSnapshotOrUndefined(fs, version) {
+	return readSnapshot(fs, version).catch((err) => {
+		debug?.("Failed to read snapshot, returning undefined", err);
+	});
+}
+
+//#endregion
+export { LockfileBaseError, LockfileBridgeUnsupportedOperation, LockfileInvalidError, canUseLockfile, computeFileHash, computeFileHashWithoutUCDHeader, getLockfilePath, getSnapshotPath, readLockfile, readLockfileOrUndefined, readSnapshot, readSnapshotOrUndefined, stripUnicodeHeader, validateLockfile, writeLockfile, writeSnapshot };

package/dist/test-utils/index.d.mts

@@ -0,0 +1,103 @@
+import { Lockfile, Snapshot } from "@ucdjs/schemas";
+
+//#region src/test-utils/lockfile-builder.d.ts
+interface CreateLockfileOptions {
+  /**
+   * Custom file counts per version
+   */
+  fileCounts?: Record<string, number>;
+  /**
+   * Custom total sizes per version (in bytes)
+   */
+  totalSizes?: Record<string, number>;
+  /**
+   * Custom snapshot paths per version
+   * If not provided, defaults to `{version}/snapshot.json`
+   */
+  snapshotPaths?: Record<string, string>;
+  /**
+   * Custom filters for the lockfile
+   */
+  filters?: {
+    disableDefaultExclusions?: boolean;
+    exclude?: string[];
+    include?: string[];
+  };
+  /**
+   * Custom createdAt timestamp for the lockfile
+   * If not provided, defaults to current date
+   */
+  createdAt?: Date;
+  /**
+   * Custom updatedAt timestamp for the lockfile
+   * If not provided, defaults to current date
+   */
+  updatedAt?: Date;
+  /**
+   * Custom timestamps per version entry
+   */
+  versionTimestamps?: Record<string, {
+    createdAt?: Date;
+    updatedAt?: Date;
+  }>;
+}
+/**
+ * Creates a lockfile entry for a single version
+ */
+declare function createLockfileEntry(version: string, options?: {
+  fileCount?: number;
+  totalSize?: number;
+  snapshotPath?: string;
+  createdAt?: Date;
+  updatedAt?: Date;
+}): Lockfile["versions"][string];
+/**
+ * Creates an empty lockfile with the specified versions
+ * All versions will have fileCount: 0 and totalSize: 0
+ */
+declare function createEmptyLockfile(versions: string[]): Lockfile;
+/**
+ * Creates a lockfile with the specified versions and optional customizations
+ */
+declare function createLockfile(versions: string[], options?: CreateLockfileOptions): Lockfile;
+//#endregion
+//#region src/test-utils/snapshot-builder.d.ts
+interface CreateSnapshotOptions {
+  /**
+   * Pre-computed content hashes for files (hash without Unicode header)
+   * If not provided, will be computed using computeFileHashWithoutUCDHeader
+   */
+  hashes?: Record<string, string>;
+  /**
+   * Pre-computed file hashes for files (hash of complete file)
+   * If not provided, will be computed using computeFileHash
+   */
+  fileHashes?: Record<string, string>;
+  /**
+   * Pre-computed sizes for files (if not provided, will be computed from content)
+   */
+  sizes?: Record<string, number>;
+}
+/**
+ * Creates a snapshot for a version with the specified files
+ * Automatically computes hashes and sizes if not provided
+ *
+ * @param version - The Unicode version for this snapshot
+ * @param files - Map of file paths to file content
+ * @param options - Optional pre-computed values
+ */
+declare function createSnapshot(version: string, files: Record<string, string>, options?: CreateSnapshotOptions): Promise<Snapshot>;
+/**
+ * Creates a snapshot with pre-computed hashes and sizes
+ * Useful when you want to control the exact hash/size values
+ *
+ * @param version - The Unicode version for this snapshot
+ * @param files - Map of file paths to file metadata
+ */
+declare function createSnapshotWithHashes(version: string, files: Record<string, {
+  hash: string;
+  fileHash: string;
+  size: number;
+}>): Snapshot;
+//#endregion
+export { type CreateLockfileOptions, type CreateSnapshotOptions, createEmptyLockfile, createLockfile, createLockfileEntry, createSnapshot, createSnapshotWithHashes };

package/dist/test-utils/index.mjs

@@ -0,0 +1,104 @@
+import { n as computeFileHashWithoutUCDHeader, t as computeFileHash } from "../hash-DYmMzCbf.mjs";
+
+//#region src/test-utils/lockfile-builder.ts
+/**
+* Creates a lockfile entry for a single version
+*/
+function createLockfileEntry(version, options) {
+	const now = /* @__PURE__ */ new Date();
+	return {
+		path: options?.snapshotPath ?? `${version}/snapshot.json`,
+		fileCount: options?.fileCount ?? 0,
+		totalSize: options?.totalSize ?? 0,
+		createdAt: options?.createdAt ?? now,
+		updatedAt: options?.updatedAt ?? now
+	};
+}
+/**
+* Creates an empty lockfile with the specified versions
+* All versions will have fileCount: 0 and totalSize: 0
+*/
+function createEmptyLockfile(versions) {
+	const now = /* @__PURE__ */ new Date();
+	return {
+		lockfileVersion: 1,
+		createdAt: now,
+		updatedAt: now,
+		versions: Object.fromEntries(versions.map((version) => [version, createLockfileEntry(version, {
+			createdAt: now,
+			updatedAt: now
+		})]))
+	};
+}
+/**
+* Creates a lockfile with the specified versions and optional customizations
+*/
+function createLockfile(versions, options) {
+	const now = /* @__PURE__ */ new Date();
+	const createdAt = options?.createdAt ?? now;
+	const updatedAt = options?.updatedAt ?? now;
+	const lockfile = {
+		lockfileVersion: 1,
+		createdAt,
+		updatedAt,
+		versions: Object.fromEntries(versions.map((version) => {
+			const versionTimestamps = options?.versionTimestamps?.[version];
+			return [version, createLockfileEntry(version, {
+				fileCount: options?.fileCounts?.[version],
+				totalSize: options?.totalSizes?.[version],
+				snapshotPath: options?.snapshotPaths?.[version],
+				createdAt: versionTimestamps?.createdAt ?? createdAt,
+				updatedAt: versionTimestamps?.updatedAt ?? updatedAt
+			})];
+		}))
+	};
+	if (options?.filters) lockfile.filters = {
+		disableDefaultExclusions: options.filters.disableDefaultExclusions,
+		exclude: options.filters.exclude,
+		include: options.filters.include
+	};
+	return lockfile;
+}
+
+//#endregion
+//#region src/test-utils/snapshot-builder.ts
+/**
+* Creates a snapshot for a version with the specified files
+* Automatically computes hashes and sizes if not provided
+*
+* @param version - The Unicode version for this snapshot
+* @param files - Map of file paths to file content
+* @param options - Optional pre-computed values
+*/
+async function createSnapshot(version, files, options) {
+	const snapshotFiles = {};
+	for (const [filePath, content] of Object.entries(files)) snapshotFiles[filePath] = {
+		hash: options?.hashes?.[filePath] ?? await computeFileHashWithoutUCDHeader(content),
+		fileHash: options?.fileHashes?.[filePath] ?? await computeFileHash(content),
+		size: options?.sizes?.[filePath] ?? new TextEncoder().encode(content).length
+	};
+	return {
+		unicodeVersion: version,
+		files: snapshotFiles
+	};
+}
+/**
+* Creates a snapshot with pre-computed hashes and sizes
+* Useful when you want to control the exact hash/size values
+*
+* @param version - The Unicode version for this snapshot
+* @param files - Map of file paths to file metadata
+*/
+function createSnapshotWithHashes(version, files) {
+	return {
+		unicodeVersion: version,
+		files: Object.fromEntries(Object.entries(files).map(([filePath, { hash, fileHash, size }]) => [filePath, {
+			hash,
+			fileHash,
+			size
+		}]))
+	};
+}
+
+//#endregion
+export { createEmptyLockfile, createLockfile, createLockfileEntry, createSnapshot, createSnapshotWithHashes };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@ucdjs/lockfile",
+  "version": "0.1.1-beta.1",
+  "type": "module",
+  "author": {
+    "name": "Lucas Nørgård",
+    "email": "lucasnrgaard@gmail.com",
+    "url": "https://luxass.dev"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/ucdjs/ucd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ucdjs/ucd.git",
+    "directory": "packages/lockfile"
+  },
+  "bugs": {
+    "url": "https://github.com/ucdjs/ucd/issues"
+  },
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./test-utils": "./dist/test-utils/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "pathe": "2.0.3",
+    "@ucdjs-internal/shared": "0.1.1-beta.1",
+    "@ucdjs/fs-bridge": "0.1.1-beta.1",
+    "@ucdjs/schemas": "0.1.1-beta.1"
+  },
+  "devDependencies": {
+    "@luxass/eslint-config": "7.2.0",
+    "@luxass/utils": "2.7.3",
+    "eslint": "10.0.0",
+    "publint": "0.3.17",
+    "tsdown": "0.20.3",
+    "typescript": "5.9.3",
+    "vitest-testdirs": "4.4.2",
+    "@ucdjs-tooling/tsdown-config": "1.0.0",
+    "@ucdjs-tooling/tsconfig": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --tsconfig=./tsconfig.build.json",
+    "dev": "tsdown --watch",
+    "clean": "git clean -xdf dist node_modules",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json"
+  }
+}