katanakit-js 5.1.0 → 5.1.1

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

@@ -0,0 +1,238 @@
+import type { ZodType } from "zod";
+import type { FileEncoding, 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>>;
+/**
+ * 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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"}

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

@@ -0,0 +1,403 @@
+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));
+}
+/**
+ * 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":"AAWA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAW1F,gEAAgE;AAChE,MAAM,wBAAyB,SAAQ,KAAK;IAClC,IAAI,CAAS;IACb,OAAO,CAAW;IAClB,IAAI,CAAU;IAEvB,YAAY,IAAY,EAAE,OAAe,EAAE,IAAa,EAAE,OAAiB;QAC1E,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD;AAQD,+EAA+E;AAC/E,SAAS,iBAAiB,CAAC,KAAc,EAAE,YAAqB;IAC/D,IAAI,KAAK,YAAY,wBAAwB,EAAE,CAAC;QAC/C,OAAO;YACN,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,YAAY;YAChC,OAAO,EAAE,KAAK,CAAC,OAAO;SACtB,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,KAAsB,CAAC;IACrC,OAAO;QACN,IAAI,EAAE,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB;QACrE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B;QAC5E,IAAI,EAAE,OAAO,KAAK,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY;KACjE,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,SAAS,sBAAsB;IAC9B,OAAO;QACN,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,kFAAkF;KAC3F,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,KAAK,CACnB,UAA8B,EAC9B,SAAyC;IAEzC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;QAClB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,sBAAsB,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IACnE,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IAC7D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;IAC/E,CAAC;AACF,CAAC;AAED,uEAAuE;AACvE,SAAS,SAAS,CAAI,GAAW,EAAE,IAAY,EAAE,MAAmB;IACnE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACJ,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QAChB,MAAM,IAAI,wBAAwB,CACjC,kBAAkB,EAClB,iCAAiC,IAAI,MACpC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,aAC1C,EAAE,EACF,IAAI,CACJ,CAAC;IACH,CAAC;IAED,IAAI,CAAC,MAAM;QAAE,OAAO,MAAW,CAAC;IAEhC,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,IAAI,wBAAwB,CACjC,gBAAgB,EAChB,yBAAyB,IAAI,uCAAuC,EACpE,IAAI,EACJ,MAAM,CAAC,KAAK,CAAC,MAAM,CACnB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACpB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,IAAY,EACZ,WAAyB,MAAM;IAE/B,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY;IACnD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,IAAY,EACZ,IAAyB,EACzB,OAA0B;IAE1B,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QAC/B,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC;IACb,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,IAAY,EACZ,IAAyB,EACzB,OAA0B;IAE1B,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QAC/B,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC;IACb,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,IAAY,EACZ,MAAmB;IAEnB,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,SAAS,CAAI,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AAC/F,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,IAAY,EACZ,IAAa,EACb,OAA8B;IAE9B,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QAC/B,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC;IACb,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC/B,IAAY,EACZ,OAAwB;IAExB,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QAC/B,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE;YACtC,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,KAAK;YACtC,aAAa,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,OAAO,OAAO,CAAC,GAAG,CACjB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YAC7B,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,MAAM,WAAW,CAAC,KAAK,CAAC,UAAU,IAAI,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC;YAC7D,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE;SAChC,CAAC,CAAC,CACH,CAAC;IACH,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC9C,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QAC/B,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,OAAO,IAAI,CAAC;IACb,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY;IAC/C,IAAI,CAAC,SAAS,EAAE;QAAE,OAAO,KAAK,CAAC;IAE/B,IAAI,CAAC;QACJ,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAC5C,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY;IACjD,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QAC/B,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,OAAO;YACN,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE;YAChC,cAAc,EAAE,KAAK,CAAC,cAAc,EAAE;YACtC,SAAS,EAAE,KAAK,CAAC,WAAW;YAC5B,UAAU,EAAE,KAAK,CAAC,OAAO;YACzB,UAAU,EAAE,KAAK,CAAC,OAAO;SACzB,CAAC;IACH,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,MAAc,EACd,WAAmB,EACnB,OAAiC;IAEjC,OAAO,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QACjC,MAAM,IAAI,GAAG,OAAO,EAAE,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3E,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;QAC7C,OAAO,WAAW,CAAC;IACpB,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,MAAc,EACd,WAAmB;IAEnB,OAAO,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QACjC,MAAM,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACrC,OAAO,WAAW,CAAC;IACpB,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY;IAC/C,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QAC/B,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACb,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,IAAY,EACZ,OAAkD;IAElD,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QAC/B,MAAM,EAAE,CAAC,EAAE,CAAC,IAAI,EAAE;YACjB,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,KAAK;YAC9B,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,IAAI;SACrC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACb,CAAC,CAAC,CAAC;AACJ,CAAC;AAED,wEAAwE;AACxE,KAAK,UAAU,iBAAiB,CAAC,aAAqB,EAAE,YAAoB;IAC3E,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,CAAC;IAChD,OAAO,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,aAAqB,EACrB,YAAoB,EACpB,WAAyB,MAAM;IAE/B,OAAO,KAAK,CAAC,YAAY,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QACvC,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;QACtE,OAAO,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACtC,aAAqB,EACrB,YAAoB,EACpB,MAAmB;IAEnB,OAAO,KAAK,CAAC,YAAY,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE;QACvC,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;QACtE,OAAO,SAAS,CAAI,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACJ,CAAC"}