katanakit-js 4.0.4 → 5.2.0

package/dist/infrastructure/filesystem/filesystem.service.js

@@ -0,0 +1,453 @@
+import { useGetDirname, useIsNode, useJoinPath, useResolvePath } from "./path.service.js";
+/** Internal error carrying `code`/`details` through `runFs`. */
+class FilesystemOperationError extends Error {
+    code;
+    details;
+    path;
+    constructor(code, message, path, details) {
+        super(message);
+        this.name = "FilesystemOperationError";
+        this.code = code;
+        this.path = path;
+        this.details = details;
+    }
+}
+/** Normalizes any thrown value into a serializable {@link FilesystemError}. */
+function toFilesystemError(error, fallbackPath) {
+    if (error instanceof FilesystemOperationError) {
+        return {
+            code: error.code,
+            message: error.message,
+            path: error.path ?? fallbackPath,
+            details: error.details,
+        };
+    }
+    const errno = error;
+    return {
+        code: typeof errno?.code === "string" ? errno.code : "ERR_FILESYSTEM",
+        message: error instanceof Error ? error.message : "Unknown filesystem error",
+        path: typeof errno?.path === "string" ? errno.path : fallbackPath,
+    };
+}
+/** Safe Result used when `node:fs` is not available (browser/edge). */
+function createUnavailableError() {
+    return {
+        code: "ERR_FS_UNAVAILABLE",
+        message: "[Filesystem] A Node.js-compatible runtime is required for filesystem operations.",
+    };
+}
+/**
+ * Internal runner: guards the runtime, loads `node:fs/promises` lazily and
+ * wraps the operation into a Safe Result (`{ data, error, ok }`).
+ */
+async function runFs(targetPath, operation) {
+    if (!useIsNode()) {
+        return { data: null, error: createUnavailableError(), ok: false };
+    }
+    try {
+        const fs = await import("node:fs/promises");
+        return { data: await operation(fs), error: null, ok: true };
+    }
+    catch (error) {
+        return { data: null, error: toFilesystemError(error, targetPath), ok: false };
+    }
+}
+/** Parses JSON text, optionally validating it against a Zod schema. */
+function parseJson(raw, path, schema) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new FilesystemOperationError("ERR_INVALID_JSON", `[Filesystem] Invalid JSON in "${path}": ${error instanceof Error ? error.message : "parse error"}`, path);
+    }
+    if (!schema)
+        return parsed;
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+        throw new FilesystemOperationError("ERR_VALIDATION", `[Filesystem] JSON in "${path}" does not match the expected schema.`, path, result.error.issues);
+    }
+    return result.data;
+}
+/**
+ * Reads a text file.
+ *
+ * @param path - File path (relative paths resolve against `process.cwd()`).
+ * @param encoding - Text encoding (default: `"utf8"`).
+ * @returns Safe Result with the file contents as a string.
+ *
+ * @example
+ * ```ts
+ * import { useReadFile } from "katanakit-js";
+ *
+ * const result = await useReadFile("data/books.json");
+ * if (result.ok) console.log(result.data);
+ * ```
+ */
+export async function useReadFile(path, encoding = "utf8") {
+    return runFs(path, (fs) => fs.readFile(path, encoding));
+}
+/**
+ * Reads a file as raw bytes (no encoding).
+ *
+ * @param path - File path.
+ * @returns Safe Result with the contents as a `Uint8Array`.
+ *
+ * @example
+ * ```ts
+ * const result = await useReadFileBuffer("assets/logo.png");
+ * if (result.ok) upload(result.data);
+ * ```
+ */
+export async function useReadFileBuffer(path) {
+    return runFs(path, (fs) => fs.readFile(path));
+}
+/**
+ * Streams a file and returns its checksum as a lowercase hex digest.
+ *
+ * @param path - File path.
+ * @param algorithm - `"md5" | "sha1" | "sha256" | "sha512"` (default: `"sha256"`).
+ * @returns Safe Result with the hex digest.
+ *
+ * @example
+ * ```ts
+ * const result = await useHashFile("image.iso"); // sha256
+ * const md5 = await useHashFile("image.iso", "md5");
+ * ```
+ */
+export async function useHashFile(path, algorithm = "sha256") {
+    return runFs(path, async () => {
+        const [{ createHash }, { createReadStream }] = await Promise.all([
+            import("node:crypto"),
+            import("node:fs"),
+        ]);
+        const hash = createHash(algorithm);
+        for await (const chunk of createReadStream(path)) {
+            hash.update(chunk);
+        }
+        return hash.digest("hex");
+    });
+}
+/**
+ * Verifies a file checksum against an expected value (case-insensitive).
+ *
+ * @param path - File path.
+ * @param expected - Expected hex digest (from a `.sha256` sidecar, release page, …).
+ * @param algorithm - Algorithm used for both values (default: `"sha256"`).
+ * @returns Safe Result with `true` when the digests match.
+ *
+ * @example
+ * ```ts
+ * const check = await useVerifyFileHash("image.iso", "e3b0c442…");
+ * if (check.ok && !check.data) throw new Error("checksum mismatch");
+ * ```
+ */
+export async function useVerifyFileHash(path, expected, algorithm = "sha256") {
+    const hashed = await useHashFile(path, algorithm);
+    if (!hashed.ok)
+        return hashed;
+    return {
+        data: hashed.data.toLowerCase() === expected.trim().toLowerCase(),
+        error: null,
+        ok: true,
+    };
+}
+/**
+ * Writes (or overwrites) a file, creating it when missing.
+ *
+ * @param path - Destination file path.
+ * @param data - Text or bytes to write.
+ * @param options - Encoding, mode and flag overrides.
+ * @returns Safe Result with the written path.
+ *
+ * @example
+ * ```ts
+ * const result = await useWriteFile("logs/app.log", "started\n");
+ * ```
+ */
+export async function useWriteFile(path, data, options) {
+    return runFs(path, async (fs) => {
+        await fs.writeFile(path, data, options);
+        return path;
+    });
+}
+/**
+ * Appends text or bytes to a file, creating it when missing.
+ *
+ * @param path - Destination file path.
+ * @param data - Text or bytes to append.
+ * @param options - Encoding, mode and flag overrides.
+ * @returns Safe Result with the written path.
+ *
+ * @example
+ * ```ts
+ * await useAppendFile("logs/app.log", "request handled\n");
+ * ```
+ */
+export async function useAppendFile(path, data, options) {
+    return runFs(path, async (fs) => {
+        await fs.appendFile(path, data, options);
+        return path;
+    });
+}
+/**
+ * Reads and parses a JSON file, optionally validating it with a Zod schema.
+ *
+ * @typeParam T - Expected parsed (and validated) shape.
+ * @param path - File path.
+ * @param schema - Optional Zod schema; invalid shapes fail with `ERR_VALIDATION`.
+ * @returns Safe Result with the parsed data, or `ERR_INVALID_JSON` / `ERR_VALIDATION`.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ *
+ * const BookSchema = z.object({ title: z.string() });
+ * const result = await useReadJsonFile("data/books.json", BookSchema);
+ * ```
+ */
+export async function useReadJsonFile(path, schema) {
+    return runFs(path, async (fs) => parseJson(await fs.readFile(path, "utf8"), path, schema));
+}
+/**
+ * Serializes data to JSON and writes it to a file (pretty-printed by default).
+ *
+ * @param path - Destination file path.
+ * @param data - Value to serialize (`JSON.stringify` rules apply).
+ * @param options - Set `pretty: false` for compact output.
+ * @returns Safe Result with the written path.
+ *
+ * @example
+ * ```ts
+ * await useWriteJsonFile("data/books.json", books);
+ * ```
+ */
+export async function useWriteJsonFile(path, data, options) {
+    return runFs(path, async (fs) => {
+        const spaces = options?.pretty === false ? undefined : 2;
+        await fs.writeFile(path, `${JSON.stringify(data, null, spaces)}\n`, "utf8");
+        return path;
+    });
+}
+/**
+ * Lists a directory with type flags resolved per entry.
+ *
+ * @param path - Directory path.
+ * @param options - `recursive: true` walks nested directories.
+ * @returns Safe Result with `{ name, path, isFile, isDirectory }` entries.
+ *
+ * @example
+ * ```ts
+ * const result = await useReadDir("content", { recursive: true });
+ * if (result.ok) result.data.filter((entry) => entry.isFile);
+ * ```
+ */
+export async function useReadDir(path, options) {
+    return runFs(path, async (fs) => {
+        const entries = await fs.readdir(path, {
+            recursive: options?.recursive ?? false,
+            withFileTypes: true,
+        });
+        return Promise.all(entries.map(async (entry) => ({
+            name: entry.name,
+            path: await useJoinPath(entry.parentPath ?? path, entry.name),
+            isFile: entry.isFile(),
+            isDirectory: entry.isDirectory(),
+        })));
+    });
+}
+/**
+ * Creates a directory (and any missing parents).
+ *
+ * @param path - Directory path to ensure.
+ * @returns Safe Result with the directory path.
+ *
+ * @example
+ * ```ts
+ * await useEnsureDir("data/cache/books");
+ * ```
+ */
+export async function useEnsureDir(path) {
+    return runFs(path, async (fs) => {
+        await fs.mkdir(path, { recursive: true });
+        return path;
+    });
+}
+/**
+ * Checks whether a path exists and is accessible.
+ * Never throws: returns `false` for missing paths and non-Node runtimes.
+ *
+ * @param path - Path to check.
+ * @returns `true` when the path exists.
+ *
+ * @example
+ * ```ts
+ * if (await useFileExists("data/books.json")) {
+ *   // read it
+ * }
+ * ```
+ */
+export async function useFileExists(path) {
+    if (!useIsNode())
+        return false;
+    try {
+        const fs = await import("node:fs/promises");
+        await fs.access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns a portable stats subset for a file or directory.
+ *
+ * @param path - Path to inspect (follows symlinks).
+ * @returns Safe Result with size, type flags and epoch-ms timestamps.
+ *
+ * @example
+ * ```ts
+ * const result = await useGetFileStats("assets/logo.png");
+ * if (result.ok) console.log(result.data.size);
+ * ```
+ */
+export async function useGetFileStats(path) {
+    return runFs(path, async (fs) => {
+        const stats = await fs.stat(path);
+        return {
+            size: stats.size,
+            isFile: stats.isFile(),
+            isDirectory: stats.isDirectory(),
+            isSymbolicLink: stats.isSymbolicLink(),
+            createdAt: stats.birthtimeMs,
+            modifiedAt: stats.mtimeMs,
+            accessedAt: stats.atimeMs,
+        };
+    });
+}
+/**
+ * Copies a file. Existing destinations are overwritten unless
+ * `overwrite: false` is passed (`COPYFILE_EXCL`).
+ *
+ * @param source - Source file path.
+ * @param destination - Destination file path.
+ * @param options - Set `overwrite: false` to fail when the target exists.
+ * @returns Safe Result with the destination path.
+ *
+ * @example
+ * ```ts
+ * await useCopyFile("data/books.json", "backup/books.json");
+ * ```
+ */
+export async function useCopyFile(source, destination, options) {
+    return runFs(source, async (fs) => {
+        const mode = options?.overwrite === false ? fs.constants.COPYFILE_EXCL : 0;
+        await fs.copyFile(source, destination, mode);
+        return destination;
+    });
+}
+/**
+ * Moves (renames) a file or directory.
+ *
+ * @param source - Source path.
+ * @param destination - Destination path.
+ * @returns Safe Result with the destination path.
+ *
+ * @example
+ * ```ts
+ * await useMoveFile("data/draft.json", "data/books.json");
+ * ```
+ */
+export async function useMoveFile(source, destination) {
+    return runFs(source, async (fs) => {
+        await fs.rename(source, destination);
+        return destination;
+    });
+}
+/**
+ * Removes a file.
+ *
+ * @param path - File path to remove.
+ * @returns Safe Result with the removed path.
+ *
+ * @example
+ * ```ts
+ * await useRemoveFile("data/cache/books.json");
+ * ```
+ */
+export async function useRemoveFile(path) {
+    return runFs(path, async (fs) => {
+        await fs.unlink(path);
+        return path;
+    });
+}
+/**
+ * Removes a directory tree. Recursive by default; `force: false`
+ * surfaces `ENOENT` instead of ignoring missing paths.
+ *
+ * @param path - Directory path to remove.
+ * @param options - `recursive` (default `true`) and `force` (default `false`).
+ * @returns Safe Result with the removed path.
+ *
+ * @example
+ * ```ts
+ * await useRemoveDir("data/cache");
+ * ```
+ */
+export async function useRemoveDir(path, options) {
+    return runFs(path, async (fs) => {
+        await fs.rm(path, {
+            force: options?.force ?? false,
+            recursive: options?.recursive ?? true,
+        });
+        return path;
+    });
+}
+/** Resolves `relativePath` against the directory of `importMetaUrl`. */
+async function resolveModulePath(importMetaUrl, relativePath) {
+    const base = await useGetDirname(importMetaUrl);
+    return useResolvePath(base, relativePath);
+}
+/**
+ * Reads a file resolved from the caller's module directory — the
+ * `__dirname` + relative path pattern, without `__dirname`.
+ *
+ * @param importMetaUrl - Your module's `import.meta.url`.
+ * @param relativePath - Path relative to that module (e.g. `"../data/books.json"`).
+ * @param encoding - Text encoding (default: `"utf8"`).
+ * @returns Safe Result with the file contents as a string.
+ *
+ * @example
+ * ```ts
+ * const css = await useReadModuleFile(import.meta.url, "./theme.css");
+ * ```
+ */
+export async function useReadModuleFile(importMetaUrl, relativePath, encoding = "utf8") {
+    return runFs(relativePath, async (fs) => {
+        const absolute = await resolveModulePath(importMetaUrl, relativePath);
+        return fs.readFile(absolute, encoding);
+    });
+}
+/**
+ * Reads and parses a JSON file resolved from the caller's module directory,
+ * optionally validating it with a Zod schema.
+ *
+ * @typeParam T - Expected parsed (and validated) shape.
+ * @param importMetaUrl - Your module's `import.meta.url`.
+ * @param relativePath - Path relative to that module.
+ * @param schema - Optional Zod schema for runtime validation.
+ * @returns Safe Result with the parsed data.
+ *
+ * @example
+ * ```ts
+ * const result = await useReadModuleJson<Book[]>(import.meta.url, "../data/books.json");
+ * if (result.ok) initBooks(result.data);
+ * ```
+ */
+export async function useReadModuleJson(importMetaUrl, relativePath, schema) {
+    return runFs(relativePath, async (fs) => {
+        const absolute = await resolveModulePath(importMetaUrl, relativePath);
+        return parseJson(await fs.readFile(absolute, "utf8"), absolute, schema);
+    });
+}
+//# sourceMappingURL=filesystem.service.js.map

package/dist/infrastructure/filesystem/filesystem.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.service.js","sourceRoot":"","sources":["../../../src/infrastructure/filesystem/filesystem.service.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/filesystem/path.service.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Checks whether the code runs in a Node.js-compatible runtime
+ * (Node, Bun or Deno). Returns `false` in browsers and edge runtimes.
+ *
+ * @returns `true` when `process.versions.node` is available.
+ *
+ * @example
+ * ```ts
+ * import { useIsNode } from "katanakit-js";
+ *
+ * if (useIsNode()) {
+ *   // safe to use node:fs / node:path
+ * }
+ * ```
+ */
+export declare const useIsNode: () => boolean;
+/**
+ * Resolves the directory of a module from its `import.meta.url`.
+ *
+ * Unlike `import.meta.dirname`, this works for any module you pass in,
+ * so a consumer's app resolves its own paths — never KatanaKit's `dist/`.
+ *
+ * @param importMetaUrl - Your module's `import.meta.url`.
+ * @returns The absolute directory that contains the module.
+ *
+ * @example
+ * ```ts
+ * import { useGetDirname } from "katanakit-js";
+ *
+ * const dir = await useGetDirname(import.meta.url);
+ * // "<project>/src/features/books"
+ * ```
+ */
+export declare function useGetDirname(importMetaUrl: string): Promise<string>;
+/**
+ * Resolves a sequence of path segments into an absolute path.
+ * Relative segments resolve against `process.cwd()`; if the first
+ * segment is absolute (like a `useGetDirname` result), cwd is ignored.
+ *
+ * @param segments - Path segments to resolve.
+ * @returns The resolved absolute path.
+ *
+ * @example
+ * ```ts
+ * const base = await useGetDirname(import.meta.url);
+ * const file = await useResolvePath(base, "../data/books.json");
+ * ```
+ */
+export declare function useResolvePath(...segments: string[]): Promise<string>;
+/**
+ * Joins path segments without resolving against `process.cwd()`.
+ *
+ * @param segments - Path segments to join.
+ * @returns The joined (possibly relative) path.
+ *
+ * @example
+ * ```ts
+ * await useJoinPath("data", "books.json"); // "data/books.json"
+ * ```
+ */
+export declare function useJoinPath(...segments: string[]): Promise<string>;
+/**
+ * Computes the relative path from `from` to `to`.
+ *
+ * @param from - Origin path.
+ * @param to - Destination path.
+ * @returns The relative path between both.
+ *
+ * @example
+ * ```ts
+ * await useGetRelativePath("/app/src", "/app/data/books.json"); // "../data/books.json"
+ * ```
+ */
+export declare function useGetRelativePath(from: string, to: string): Promise<string>;
+/**
+ * Returns the last portion of a path (file name).
+ *
+ * @param filePath - The path to inspect.
+ * @param suffix - Optional suffix to strip (e.g. `".json"`).
+ * @returns The base name.
+ *
+ * @example
+ * ```ts
+ * await useGetBasename("/data/books.json");        // "books.json"
+ * await useGetBasename("/data/books.json", ".json"); // "books"
+ * ```
+ */
+export declare function useGetBasename(filePath: string, suffix?: string): Promise<string>;
+/**
+ * Returns the extension of a path, including the leading dot.
+ *
+ * @param filePath - The path to inspect.
+ * @returns The extension (`""` when there is none).
+ *
+ * @example
+ * ```ts
+ * await useGetFileExtension("/data/books.json"); // ".json"
+ * ```
+ */
+export declare function useGetFileExtension(filePath: string): Promise<string>;
+/**
+ * Returns the current working directory of the process (where the
+ * command was launched), or `null` outside a Node-compatible runtime.
+ * Use it for project-relative paths; use {@link useGetDirname} for
+ * file-relative paths.
+ *
+ * @returns The cwd, or `null` in browsers/edge runtimes.
+ *
+ * @example
+ * ```ts
+ * const cwd = useGetCwd(); // "/app" when launched from the project root
+ * ```
+ */
+export declare function useGetCwd(): string | null;
+//# sourceMappingURL=path.service.d.ts.map

package/dist/infrastructure/filesystem/path.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.service.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/filesystem/path.service.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,QAAO,OACgD,CAAC;AAkB9E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG1E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAGxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGvF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,IAAI,MAAM,GAAG,IAAI,CAEzC"}