katanakit-js 4.0.4 → 5.2.0

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

@@ -0,0 +1,267 @@
+import type { ZodType } from "zod";
+import type { FileEncoding, FileHashAlgorithm, FileStats, FilesystemResult, ReadDirEntry, ReadDirOptions, WriteFileOptions } from "../../types/index.js";
+/**
+ * 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 declare function useReadFile(path: string, encoding?: FileEncoding): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useReadFileBuffer(path: string): Promise<FilesystemResult<Uint8Array>>;
+/**
+ * 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 declare function useHashFile(path: string, algorithm?: FileHashAlgorithm): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useVerifyFileHash(path: string, expected: string, algorithm?: FileHashAlgorithm): Promise<FilesystemResult<boolean>>;
+/**
+ * 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 declare function useWriteFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useAppendFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useReadJsonFile<T = unknown>(path: string, schema?: ZodType<T>): Promise<FilesystemResult<T>>;
+/**
+ * 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 declare function useWriteJsonFile(path: string, data: unknown, options?: {
+    pretty?: boolean;
+}): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useReadDir(path: string, options?: ReadDirOptions): Promise<FilesystemResult<ReadDirEntry[]>>;
+/**
+ * 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 declare function useEnsureDir(path: string): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useFileExists(path: string): Promise<boolean>;
+/**
+ * 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 declare function useGetFileStats(path: string): Promise<FilesystemResult<FileStats>>;
+/**
+ * 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 declare function useCopyFile(source: string, destination: string, options?: {
+    overwrite?: boolean;
+}): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useMoveFile(source: string, destination: string): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useRemoveFile(path: string): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useRemoveDir(path: string, options?: {
+    force?: boolean;
+    recursive?: boolean;
+}): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useReadModuleFile(importMetaUrl: string, relativePath: string, encoding?: FileEncoding): Promise<FilesystemResult<string>>;
+/**
+ * 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 declare function useReadModuleJson<T = unknown>(importMetaUrl: string, relativePath: string, schema?: ZodType<T>): Promise<FilesystemResult<T>>;
+//# sourceMappingURL=filesystem.service.d.ts.map

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

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