@ucdjs/test-utils 1.0.1-beta.1

package/dist/fs-bridges/index.d.mts

@@ -0,0 +1,84 @@
+import * as _ucdjs_fs_bridge0 from "@ucdjs/fs-bridge";
+import { FSEntry, FileSystemBridge } from "@ucdjs/fs-bridge";
+import { z } from "zod";
+
+//#region src/fs-bridges/memory-fs-bridge.d.ts
+declare const createMemoryMockFS: _ucdjs_fs_bridge0.FileSystemBridgeFactory<z.ZodOptional<z.ZodObject<{
+  basePath: z.ZodOptional<z.ZodString>;
+  initialFiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  functions: z.ZodOptional<z.ZodObject<{
+    read: z.ZodOptional<z.ZodOptional<z.ZodXor<readonly [z.ZodFunction<z.ZodTuple<readonly [z.ZodString], null>, z.ZodPromise<z.ZodString>>, z.ZodLiteral<false>]>>>;
+    exists: z.ZodOptional<z.ZodOptional<z.ZodXor<readonly [z.ZodFunction<z.ZodTuple<readonly [z.ZodString], null>, z.ZodPromise<z.ZodBoolean>>, z.ZodLiteral<false>]>>>;
+    listdir: z.ZodOptional<z.ZodOptional<z.ZodXor<readonly [z.ZodFunction<z.ZodTuple<readonly [z.ZodString, z.ZodOptional<z.ZodBoolean>], null>, z.ZodPromise<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+      name: z.ZodString;
+      path: z.ZodString;
+      lastModified: z.ZodUnion<[z.ZodNumber, z.ZodNull]>;
+      type: z.ZodLiteral<"directory">;
+    }, z.core.$strip>, z.ZodObject<{
+      name: z.ZodString;
+      path: z.ZodString;
+      lastModified: z.ZodUnion<[z.ZodNumber, z.ZodNull]>;
+      type: z.ZodLiteral<"file">;
+    }, z.core.$strip>]>>>>, z.ZodLiteral<false>]>>>;
+    write: z.ZodOptional<z.ZodOptional<z.ZodXor<readonly [z.ZodFunction<z.ZodTuple<readonly [z.ZodString, z.ZodXor<readonly [z.ZodString, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>, z.ZodOptional<z.ZodString>], null>, z.ZodPromise<z.ZodVoid>>, z.ZodLiteral<false>]>>>;
+    mkdir: z.ZodOptional<z.ZodOptional<z.ZodXor<readonly [z.ZodFunction<z.ZodTuple<readonly [z.ZodString, z.ZodOptional<z.ZodObject<{
+      recursive: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>], null>, z.ZodPromise<z.ZodVoid>>, z.ZodLiteral<false>]>>>;
+    rm: z.ZodOptional<z.ZodOptional<z.ZodXor<readonly [z.ZodFunction<z.ZodTuple<readonly [z.ZodString, z.ZodOptional<z.ZodObject<{
+      recursive: z.ZodOptional<z.ZodBoolean>;
+      force: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>], null>, z.ZodPromise<z.ZodVoid>>, z.ZodLiteral<false>]>>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>>>;
+//#endregion
+//#region src/fs-bridges/read-only-bridge.d.ts
+interface CreateReadOnlyBridgeOptions {
+  /**
+   * Mock function for reading files
+   * @default vi.fn().mockResolvedValue("content")
+   */
+  read?: (path: string) => Promise<string>;
+  /**
+   * Mock function for checking file existence
+   * @default vi.fn().mockResolvedValue(true)
+   */
+  exists?: (path: string) => Promise<boolean>;
+  /**
+   * Mock function for listing directory contents
+   * @default vi.fn().mockResolvedValue([])
+   */
+  listdir?: (path: string, recursive?: boolean) => Promise<FSEntry[]>;
+}
+/**
+ * Creates a read-only filesystem bridge for testing.
+ *
+ * Useful for testing operations that should skip when write capability is unavailable.
+ * All functions are optional and will use sensible defaults if not provided.
+ *
+ * @param options - Optional mock functions for read, exists, and listdir
+ * @returns A read-only FileSystemBridge instance
+ *
+ * @example
+ * ```typescript
+ * import { createReadOnlyBridge } from "#test-utils/fs-bridges";
+ * import { vi } from "vitest";
+ *
+ * // Use defaults
+ * const bridge = createReadOnlyBridge();
+ *
+ * // Custom read function
+ * const bridge = createReadOnlyBridge({
+ *   read: vi.fn().mockResolvedValue("custom content"),
+ * });
+ *
+ * // All custom functions
+ * const bridge = createReadOnlyBridge({
+ *   read: vi.fn().mockResolvedValue("file content"),
+ *   exists: vi.fn().mockResolvedValue(false),
+ *   listdir: vi.fn().mockResolvedValue([...]),
+ * });
+ * ```
+ */
+declare function createReadOnlyBridge(options?: CreateReadOnlyBridgeOptions): FileSystemBridge;
+//#endregion
+export { type CreateReadOnlyBridgeOptions, createMemoryMockFS, createReadOnlyBridge };

package/dist/fs-bridges/index.mjs

@@ -0,0 +1,303 @@
+import { vi } from "vitest";
+import { Buffer } from "node:buffer";
+import { appendTrailingSlash, prependLeadingSlash } from "@luxass/utils/path";
+import { defineFileSystemBridge } from "@ucdjs/fs-bridge";
+import { FileEntrySchema } from "@ucdjs/schemas";
+import { z } from "zod";
+
+//#region src/fs-bridges/memory-fs-bridge.ts
+/**
+* Normalizes root path inputs to an empty string.
+* Treats "", ".", "/" and undefined as the empty root.
+*/
+function normalizeRootPath(path) {
+	return !path || path === "." || path === "/" ? "" : path;
+}
+/**
+* Formats a relative path to match FSEntry schema requirements (parity with node/http bridges):
+* - Leading slash required for all paths
+* - Trailing slash required for directories
+*/
+function formatEntryPath(relativePath, isDirectory) {
+	const withLeadingSlash = prependLeadingSlash(relativePath);
+	return isDirectory ? appendTrailingSlash(withLeadingSlash) : withLeadingSlash;
+}
+/**
+* Marker value for explicit directories in the flat Map storage.
+* Directories are stored as "path/" -> DIR_MARKER
+*/
+const DIR_MARKER = Symbol("directory");
+/**
+* Checks if a path represents an explicit directory marker.
+*/
+function isDirMarkerKey(path) {
+	return path.endsWith("/");
+}
+/**
+* Gets the directory marker key for a given path.
+*/
+function getDirMarkerKey(path) {
+	const normalized = normalizeRootPath(path);
+	if (normalized === "") return "";
+	return normalized.endsWith("/") ? normalized : `${normalized}/`;
+}
+const createMemoryMockFS = defineFileSystemBridge({
+	meta: {
+		name: "In-Memory File System Bridge",
+		description: "A simple in-memory file system bridge using a flat Map for storage, perfect for testing."
+	},
+	optionsSchema: z.object({
+		basePath: z.string().optional(),
+		initialFiles: z.record(z.string(), z.string()).optional(),
+		functions: z.object({
+			read: z.xor([z.function({
+				input: [z.string()],
+				output: z.promise(z.string())
+			}), z.literal(false)]).optional(),
+			exists: z.xor([z.function({
+				input: [z.string()],
+				output: z.promise(z.boolean())
+			}), z.literal(false)]).optional(),
+			listdir: z.xor([z.function({
+				input: [z.string(), z.boolean().optional()],
+				output: z.promise(z.array(FileEntrySchema))
+			}), z.literal(false)]).optional(),
+			write: z.xor([z.function({
+				input: [
+					z.string(),
+					z.xor([z.string(), z.instanceof(Uint8Array)]),
+					z.string().optional()
+				],
+				output: z.promise(z.void())
+			}), z.literal(false)]).optional(),
+			mkdir: z.xor([z.function({
+				input: [z.string(), z.object({ recursive: z.boolean().optional() }).optional()],
+				output: z.promise(z.void())
+			}), z.literal(false)]).optional(),
+			rm: z.xor([z.function({
+				input: [z.string(), z.object({
+					recursive: z.boolean().optional(),
+					force: z.boolean().optional()
+				}).optional()],
+				output: z.promise(z.void())
+			}), z.literal(false)]).optional()
+		}).partial().optional()
+	}).optional(),
+	state: { files: /* @__PURE__ */ new Map() },
+	setup({ options, state, resolveSafePath }) {
+		const basePath = options?.basePath ?? "/";
+		const resolve = (path) => {
+			return resolveSafePath(basePath, path);
+		};
+		if (options?.initialFiles) for (const [path, content] of Object.entries(options.initialFiles)) state.files.set(resolve(path), content);
+		const operations = {
+			read: async (path) => {
+				const resolvedPath = resolve(path);
+				const content = state.files.get(resolvedPath);
+				if (content === void 0) throw new Error(`ENOENT: no such file or directory, open '${resolvedPath}'`);
+				if (content === DIR_MARKER) throw new Error(`EISDIR: illegal operation on a directory, read '${resolvedPath}'`);
+				return content;
+			},
+			exists: async (path) => {
+				const resolvedPath = resolve(path);
+				if (state.files.has(resolvedPath)) return true;
+				const dirMarkerKey = getDirMarkerKey(resolvedPath);
+				if (dirMarkerKey && state.files.has(dirMarkerKey)) return true;
+				const normalizedPath = normalizeRootPath(resolvedPath);
+				const pathWithSlash = normalizedPath === "" ? "" : normalizedPath.endsWith("/") ? normalizedPath : `${normalizedPath}/`;
+				for (const filePath of state.files.keys()) if (filePath.startsWith(pathWithSlash)) return true;
+				return false;
+			},
+			listdir: async (path, recursive = false) => {
+				const resolvedPath = resolve(path);
+				const entries = [];
+				const normalizedPath = normalizeRootPath(resolvedPath);
+				const pathPrefix = normalizedPath === "" ? "" : normalizedPath.endsWith("/") ? normalizedPath : `${normalizedPath}/`;
+				const requestedPath = normalizeRootPath(path).replace(/^\/+/, "").replace(/\/+$/, "");
+				const prefixToRoot = (relative) => {
+					if (!requestedPath) return relative;
+					if (!relative) return requestedPath;
+					return `${requestedPath}/${relative}`;
+				};
+				const seenDirs = /* @__PURE__ */ new Set();
+				for (const [filePath, value] of state.files.entries()) {
+					if (!filePath.startsWith(pathPrefix)) continue;
+					const relativePath = filePath.slice(pathPrefix.length);
+					if (isDirMarkerKey(filePath) && value === DIR_MARKER) {
+						const parts = relativePath.slice(0, -1).split("/");
+						if (!recursive) {
+							if (parts.length === 1 && parts[0]) {
+								const dirName = parts[0];
+								if (!seenDirs.has(dirName)) {
+									seenDirs.add(dirName);
+									entries.push({
+										type: "directory",
+										name: dirName,
+										path: formatEntryPath(prefixToRoot(dirName), true),
+										children: []
+									});
+								}
+							}
+						} else {
+							let currentLevel = entries;
+							for (let i = 0; i < parts.length; i++) {
+								const part = parts[i];
+								if (!part) continue;
+								const partPath = parts.slice(0, i + 1).join("/");
+								let dirEntry = currentLevel.find((e) => e.type === "directory" && e.name === part);
+								if (!dirEntry) {
+									dirEntry = {
+										type: "directory",
+										name: part,
+										path: formatEntryPath(prefixToRoot(partPath), true),
+										children: []
+									};
+									currentLevel.push(dirEntry);
+								}
+								currentLevel = dirEntry.children;
+							}
+						}
+						continue;
+					}
+					const parts = relativePath.split("/");
+					if (!recursive) {
+						if (parts.length === 1 && parts[0]) entries.push({
+							type: "file",
+							name: parts[0],
+							path: formatEntryPath(prefixToRoot(relativePath), false)
+						});
+						else if (parts.length > 1 && parts[0]) {
+							const dirName = parts[0];
+							if (!seenDirs.has(dirName)) {
+								seenDirs.add(dirName);
+								entries.push({
+									type: "directory",
+									name: dirName,
+									path: formatEntryPath(prefixToRoot(dirName), true),
+									children: []
+								});
+							}
+						}
+					} else {
+						let currentLevel = entries;
+						for (let i = 0; i < parts.length; i++) {
+							const part = parts[i];
+							if (!part) continue;
+							const isLastPart = i === parts.length - 1;
+							const partPath = parts.slice(0, i + 1).join("/");
+							if (isLastPart) currentLevel.push({
+								type: "file",
+								name: part,
+								path: formatEntryPath(prefixToRoot(partPath), false)
+							});
+							else {
+								let dirEntry = currentLevel.find((e) => e.type === "directory" && e.name === part);
+								if (!dirEntry) {
+									dirEntry = {
+										type: "directory",
+										name: part,
+										path: formatEntryPath(prefixToRoot(partPath), true),
+										children: []
+									};
+									currentLevel.push(dirEntry);
+								}
+								currentLevel = dirEntry.children;
+							}
+						}
+					}
+				}
+				return entries;
+			},
+			write: async (path, data, encoding = "utf8") => {
+				const resolvedPath = resolve(path);
+				const content = typeof data === "string" ? data : Buffer.from(data).toString(encoding);
+				state.files.set(resolvedPath, content);
+			},
+			mkdir: async (path) => {
+				const normalizedPath = normalizeRootPath(resolve(path));
+				if (normalizedPath === "") return;
+				const dirMarkerKey = getDirMarkerKey(normalizedPath);
+				state.files.set(dirMarkerKey, DIR_MARKER);
+				const parts = normalizedPath.split("/");
+				for (let i = 1; i < parts.length; i++) {
+					const parentMarkerKey = getDirMarkerKey(parts.slice(0, i).join("/"));
+					if (parentMarkerKey && !state.files.has(parentMarkerKey)) state.files.set(parentMarkerKey, DIR_MARKER);
+				}
+			},
+			rm: async (path, options) => {
+				const resolvedPath = resolve(path);
+				if (state.files.has(resolvedPath)) {
+					state.files.delete(resolvedPath);
+					return;
+				}
+				const dirMarkerKey = getDirMarkerKey(resolvedPath);
+				if (dirMarkerKey && state.files.has(dirMarkerKey)) state.files.delete(dirMarkerKey);
+				if (options?.recursive) {
+					const normalizedPath = normalizeRootPath(resolvedPath);
+					const pathPrefix = normalizedPath === "" ? "" : normalizedPath.endsWith("/") ? normalizedPath : `${normalizedPath}/`;
+					const keysToDelete = [];
+					for (const filePath of state.files.keys()) if (filePath.startsWith(pathPrefix)) keysToDelete.push(filePath);
+					for (const key of keysToDelete) state.files.delete(key);
+				}
+			}
+		};
+		if (options?.functions) {
+			const fns = options.functions;
+			for (const key of Object.keys(fns)) {
+				const val = fns[key];
+				if (val === false) delete operations[key];
+				else operations[key] = val;
+			}
+		}
+		return operations;
+	}
+});
+
+//#endregion
+//#region src/fs-bridges/read-only-bridge.ts
+/**
+* Creates a read-only filesystem bridge for testing.
+*
+* Useful for testing operations that should skip when write capability is unavailable.
+* All functions are optional and will use sensible defaults if not provided.
+*
+* @param options - Optional mock functions for read, exists, and listdir
+* @returns A read-only FileSystemBridge instance
+*
+* @example
+* ```typescript
+* import { createReadOnlyBridge } from "#test-utils/fs-bridges";
+* import { vi } from "vitest";
+*
+* // Use defaults
+* const bridge = createReadOnlyBridge();
+*
+* // Custom read function
+* const bridge = createReadOnlyBridge({
+*   read: vi.fn().mockResolvedValue("custom content"),
+* });
+*
+* // All custom functions
+* const bridge = createReadOnlyBridge({
+*   read: vi.fn().mockResolvedValue("file content"),
+*   exists: vi.fn().mockResolvedValue(false),
+*   listdir: vi.fn().mockResolvedValue([...]),
+* });
+* ```
+*/
+function createReadOnlyBridge(options = {}) {
+	return defineFileSystemBridge({
+		meta: {
+			name: "Read-Only Test Bridge",
+			description: "A read-only bridge for testing"
+		},
+		setup: () => ({
+			read: options.read ?? vi.fn().mockResolvedValue("content"),
+			exists: options.exists ?? vi.fn().mockResolvedValue(true),
+			listdir: options.listdir ?? vi.fn().mockResolvedValue([])
+		})
+	})();
+}
+
+//#endregion
+export { createMemoryMockFS, createReadOnlyBridge };