katanakit-js 5.1.0 → 5.1.1

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"}

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

@@ -0,0 +1,154 @@
+// ============================================================
+// Path facade — Node-only helpers with runtime guards.
+// `node:path` and `node:url` load through dynamic `import()` so
+// importing this module never pulls Node built-ins into a browser
+// bundle. Outside Node/Bun the helpers throw; the filesystem
+// service catches that surface and returns a Safe Result instead.
+// ============================================================
+/**
+ * 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 const useIsNode = () => typeof process !== "undefined" && typeof process.versions?.node === "string";
+/** Throws when a path helper is called outside a Node-compatible runtime. */
+function assertNodeRuntime() {
+    if (!useIsNode()) {
+        throw new Error("[Filesystem] A Node.js-compatible runtime is required to use filesystem helpers.");
+    }
+}
+/** Lazily loads `node:path` and `node:url` (the ESM loader caches both). */
+async function loadModules() {
+    assertNodeRuntime();
+    const [path, url] = await Promise.all([import("node:path"), import("node:url")]);
+    return { path, url };
+}
+/**
+ * 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 async function useGetDirname(importMetaUrl) {
+    const { path, url } = await loadModules();
+    return path.dirname(url.fileURLToPath(importMetaUrl));
+}
+/**
+ * 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 async function useResolvePath(...segments) {
+    const { path } = await loadModules();
+    return path.resolve(...segments);
+}
+/**
+ * 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 async function useJoinPath(...segments) {
+    const { path } = await loadModules();
+    return path.join(...segments);
+}
+/**
+ * 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 async function useGetRelativePath(from, to) {
+    const { path } = await loadModules();
+    return path.relative(from, to);
+}
+/**
+ * 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 async function useGetBasename(filePath, suffix) {
+    const { path } = await loadModules();
+    return path.basename(filePath, suffix);
+}
+/**
+ * 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 async function useGetFileExtension(filePath) {
+    const { path } = await loadModules();
+    return path.extname(filePath);
+}
+/**
+ * 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 function useGetCwd() {
+    return useIsNode() ? process.cwd() : null;
+}
+//# sourceMappingURL=path.service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path.service.js","sourceRoot":"","sources":["../../../src/infrastructure/filesystem/path.service.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,uDAAuD;AACvD,gEAAgE;AAChE,kEAAkE;AAClE,6DAA6D;AAC7D,kEAAkE;AAClE,+DAA+D;AAK/D;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,GAAY,EAAE,CACtC,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,OAAO,CAAC,QAAQ,EAAE,IAAI,KAAK,QAAQ,CAAC;AAE9E,6EAA6E;AAC7E,SAAS,iBAAiB;IACzB,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACd,kFAAkF,CAClF,CAAC;IACH,CAAC;AACF,CAAC;AAED,4EAA4E;AAC5E,KAAK,UAAU,WAAW;IACzB,iBAAiB,EAAE,CAAC;IACpB,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACjF,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,aAAqB;IACxD,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IAC1C,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAG,QAAkB;IACzD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IACrC,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAG,QAAkB;IACtD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IACrC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY,EAAE,EAAU;IAChE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IACrC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB,EAAE,MAAe;IACrE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IACrC,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAgB;IACzD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,WAAW,EAAE,CAAC;IACrC,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,SAAS;IACxB,OAAO,SAAS,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3C,CAAC"}

package/dist/infrastructure/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./dom/dom.service.js";
+export * from "./filesystem/filesystem.service.js";
+export * from "./filesystem/path.service.js";
 export * from "./media/media.service.js";
 export * from "./observer/observer.service.js";
 export * from "./sensors/sensors.service.js";

package/dist/infrastructure/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/infrastructure/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/infrastructure/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC"}

package/dist/infrastructure/index.js

@@ -1,4 +1,6 @@
 export * from "./dom/dom.service.js";
+export * from "./filesystem/filesystem.service.js";
+export * from "./filesystem/path.service.js";
 export * from "./media/media.service.js";
 export * from "./observer/observer.service.js";
 export * from "./sensors/sensors.service.js";

package/dist/infrastructure/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/infrastructure/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/infrastructure/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,oCAAoC,CAAC;AACnD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC"}

package/dist/schemas/faker.schema.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/** Generic fake vehicle shape returned by `useFakeVehicle`. */
+export declare const FakeVehicleSchema: z.ZodObject<{
+    brand: z.ZodString;
+    model: z.ZodString;
+    type: z.ZodString;
+    fuel: z.ZodString;
+    color: z.ZodString;
+    vin: z.ZodString;
+    plate: z.ZodString;
+}, z.core.$strip>;
+//# sourceMappingURL=faker.schema.d.ts.map

package/dist/schemas/faker.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faker.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/faker.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+DAA+D;AAC/D,eAAO,MAAM,iBAAiB;;;;;;;;iBAQ5B,CAAC"}

package/dist/schemas/faker.schema.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+/** Generic fake vehicle shape returned by `useFakeVehicle`. */
+export const FakeVehicleSchema = z.object({
+    brand: z.string(),
+    model: z.string(),
+    type: z.string(),
+    fuel: z.string(),
+    color: z.string(),
+    vin: z.string(),
+    plate: z.string(),
+});
+//# sourceMappingURL=faker.schema.js.map

package/dist/schemas/faker.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"faker.schema.js","sourceRoot":"","sources":["../../src/schemas/faker.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+DAA+D;AAC/D,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CACjB,CAAC,CAAC"}

package/dist/schemas/filesystem.schema.d.ts

@@ -0,0 +1,64 @@
+import { z } from "zod";
+/** Text encodings accepted by the filesystem helpers. */
+export declare const FileEncodingSchema: z.ZodEnum<{
+    "utf-8": "utf-8";
+    utf8: "utf8";
+    ascii: "ascii";
+    base64: "base64";
+    base64url: "base64url";
+    hex: "hex";
+    latin1: "latin1";
+    binary: "binary";
+    ucs2: "ucs2";
+    "ucs-2": "ucs-2";
+    utf16le: "utf16le";
+    "utf-16le": "utf-16le";
+}>;
+/** Safe error from a filesystem operation (`NodeJS.ErrnoException`-shaped). */
+export declare const FilesystemErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    details: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** Portable stats subset for a file or directory. */
+export declare const FileStatsSchema: z.ZodObject<{
+    size: z.ZodNumber;
+    isFile: z.ZodBoolean;
+    isDirectory: z.ZodBoolean;
+    isSymbolicLink: z.ZodBoolean;
+    createdAt: z.ZodNumber;
+    modifiedAt: z.ZodNumber;
+    accessedAt: z.ZodNumber;
+}, z.core.$strip>;
+/** A single directory entry with pre-resolved type flags. */
+export declare const ReadDirEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    isFile: z.ZodBoolean;
+    isDirectory: z.ZodBoolean;
+}, z.core.$strip>;
+/** Options for directory listing. */
+export declare const ReadDirOptionsSchema: z.ZodObject<{
+    recursive: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Options for writing or appending files. */
+export declare const WriteFileOptionsSchema: z.ZodObject<{
+    encoding: z.ZodOptional<z.ZodEnum<{
+        "utf-8": "utf-8";
+        utf8: "utf8";
+        ascii: "ascii";
+        base64: "base64";
+        base64url: "base64url";
+        hex: "hex";
+        latin1: "latin1";
+        binary: "binary";
+        ucs2: "ucs2";
+        "ucs-2": "ucs-2";
+        utf16le: "utf16le";
+        "utf-16le": "utf-16le";
+    }>>;
+    mode: z.ZodOptional<z.ZodNumber>;
+    flag: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+//# sourceMappingURL=filesystem.schema.d.ts.map

package/dist/schemas/filesystem.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.schema.d.ts","sourceRoot":"","sources":["../../src/schemas/filesystem.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yDAAyD;AACzD,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;EAa7B,CAAC;AAEH,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB;;;;;iBAKhC,CAAC;AAEH,qDAAqD;AACrD,eAAO,MAAM,eAAe;;;;;;;;iBAW1B,CAAC;AAEH,6DAA6D;AAC7D,eAAO,MAAM,kBAAkB;;;;;iBAK7B,CAAC;AAEH,qCAAqC;AACrC,eAAO,MAAM,oBAAoB;;iBAE/B,CAAC;AAEH,8CAA8C;AAC9C,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;iBAIjC,CAAC"}

package/dist/schemas/filesystem.schema.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+/** Text encodings accepted by the filesystem helpers. */
+export const FileEncodingSchema = z.enum([
+    "utf8",
+    "utf-8",
+    "ascii",
+    "base64",
+    "base64url",
+    "hex",
+    "latin1",
+    "binary",
+    "ucs2",
+    "ucs-2",
+    "utf16le",
+    "utf-16le",
+]);
+/** Safe error from a filesystem operation (`NodeJS.ErrnoException`-shaped). */
+export const FilesystemErrorSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    path: z.string().optional(),
+    details: z.unknown().optional(),
+});
+/** Portable stats subset for a file or directory. */
+export const FileStatsSchema = z.object({
+    size: z.number(),
+    isFile: z.boolean(),
+    isDirectory: z.boolean(),
+    isSymbolicLink: z.boolean(),
+    /** Creation time in epoch milliseconds (`birthtimeMs`). */
+    createdAt: z.number(),
+    /** Last modification time in epoch milliseconds (`mtimeMs`). */
+    modifiedAt: z.number(),
+    /** Last access time in epoch milliseconds (`atimeMs`). */
+    accessedAt: z.number(),
+});
+/** A single directory entry with pre-resolved type flags. */
+export const ReadDirEntrySchema = z.object({
+    name: z.string(),
+    path: z.string(),
+    isFile: z.boolean(),
+    isDirectory: z.boolean(),
+});
+/** Options for directory listing. */
+export const ReadDirOptionsSchema = z.object({
+    recursive: z.boolean().optional(),
+});
+/** Options for writing or appending files. */
+export const WriteFileOptionsSchema = z.object({
+    encoding: FileEncodingSchema.optional(),
+    mode: z.number().int().nonnegative().optional(),
+    flag: z.string().optional(),
+});
+//# sourceMappingURL=filesystem.schema.js.map

package/dist/schemas/filesystem.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.schema.js","sourceRoot":"","sources":["../../src/schemas/filesystem.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yDAAyD;AACzD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC;IACxC,MAAM;IACN,OAAO;IACP,OAAO;IACP,QAAQ;IACR,WAAW;IACX,KAAK;IACL,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,OAAO;IACP,SAAS;IACT,UAAU;CACV,CAAC,CAAC;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;IACnB,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE;IACxB,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE;IAC3B,2DAA2D;IAC3D,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,gEAAgE;IAChE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,0DAA0D;IAC1D,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAEH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;IACnB,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE;CACxB,CAAC,CAAC;AAEH,qCAAqC;AACrC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH,8CAA8C;AAC9C,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,EAAE;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;IAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC3B,CAAC,CAAC"}

package/dist/schemas/index.d.ts

@@ -2,6 +2,8 @@ export * from "./access.schema.js";
 export * from "./ai.schema.js";
 export * from "./common.schema.js";
 export * from "./core.schema.js";
+export * from "./faker.schema.js";
+export * from "./filesystem.schema.js";
 export * from "./insforge.schema.js";
 export * from "./media.schema.js";
 export * from "./notion.schema.js";

package/dist/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}

package/dist/schemas/index.js

@@ -2,6 +2,8 @@ export * from "./access.schema.js";
 export * from "./ai.schema.js";
 export * from "./common.schema.js";
 export * from "./core.schema.js";
+export * from "./faker.schema.js";
+export * from "./filesystem.schema.js";
 export * from "./insforge.schema.js";
 export * from "./media.schema.js";
 export * from "./notion.schema.js";

package/dist/schemas/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC"}

package/dist/types/index.d.ts

@@ -5,6 +5,8 @@ import { AccessCapabilitySchema, AccessRoleDefinitionSchema, AccessRoleSchema, A
 import { AiFunctionCallSchema, AiMessageSchema, AiProviderConfigSchema, AiRoleSchema, AiToolCallSchema } from "../schemas/ai.schema.js";
 import { ApiErrorSchema, HttpMethodSchema, LocaleSchema, LogLevelSchema, SerializedErrorSchema, StorageTargetSchema, ThemeModeSchema } from "../schemas/common.schema.js";
 import { AgentDataSchema, AgentStepSchema, AiErrorSchema, AppDateFormatOptionsSchema, AssistantReplySchema, AstroServiceErrorSchema, CurrencyFormatOptionsSchema, CurrencySchema, FieldErrorsSchema, GeometryFormatOptionsSchema, GeoPositionSchema, LazyLoaderEntrySchema, NumberFormatOptionsSchema, ProductTypeSchema, ScrollPositionSchema, ValidationIssueSchema, ViewportSizeSchema } from "../schemas/core.schema.js";
+import { FakeVehicleSchema } from "../schemas/faker.schema.js";
+import { FileEncodingSchema, FileStatsSchema, FilesystemErrorSchema, ReadDirEntrySchema, ReadDirOptionsSchema, WriteFileOptionsSchema } from "../schemas/filesystem.schema.js";
 import { IfConfigSchema, IfInsertRowsSchema, IfInvokeOptionsSchema, IfListOptionsSchema, IfOrderSchema, IfRpcCallSchema, IfStorageRefSchema, IfTableQuerySchema, IfUpdatePatchSchema, IfWriteQuerySchema } from "../schemas/insforge.schema.js";
 import { MediaProviderSchema, MediaSourceSchema, SmartVideoOptionsSchema, YoutubeEmbedOptionsSchema, YoutubeThumbnailQualitySchema } from "../schemas/media.schema.js";
 import { NotionBlockListSchema, NotionBlockSchema, NotionConfigSchema, NotionCoverSchema, NotionDatabaseQuerySchema, NotionDatabaseSchema, NotionIconSchema, NotionPageListSchema, NotionPageSchema, NotionParentSchema, NotionPropertySchemaSchema, NotionPropertyValueSchema, NotionRichTextSchema, NotionSearchQuerySchema, NotionSearchResultSchema, NotionSortSchema, NotionUserListSchema, NotionUserSchema } from "../schemas/notion.schema.js";
@@ -85,6 +87,28 @@ export interface StorageStrategy {
     useRemoveItem(key: string): void;
     useClear(): void;
 }
+/** Text encodings accepted by the filesystem helpers. */
+export type FileEncoding = z.infer<typeof FileEncodingSchema>;
+/** Safe error from a filesystem operation (`NodeJS.ErrnoException`-shaped). */
+export type FilesystemError = z.infer<typeof FilesystemErrorSchema>;
+/** Safe Result for filesystem operations: `{ data, error, ok }`, never throws. */
+export type FilesystemResult<T> = {
+    data: T;
+    error: null;
+    ok: true;
+} | {
+    data: null;
+    error: FilesystemError;
+    ok: false;
+};
+/** Portable stats subset returned by `useGetFileStats`. */
+export type FileStats = z.infer<typeof FileStatsSchema>;
+/** A single directory entry returned by `useReadDir`. */
+export type ReadDirEntry = z.infer<typeof ReadDirEntrySchema>;
+/** Options for `useReadDir`. */
+export type ReadDirOptions = z.infer<typeof ReadDirOptionsSchema>;
+/** Options for `useWriteFile` / `useAppendFile`. */
+export type WriteFileOptions = z.infer<typeof WriteFileOptionsSchema>;
 export type Locale = z.infer<typeof LocaleSchema>;
 export type Currency = z.infer<typeof CurrencySchema>;
 export type CurrencyFormatOptions = z.infer<typeof CurrencyFormatOptionsSchema>;
@@ -194,6 +218,8 @@ export interface ICryptoStrategy {
 export interface IUuidStrategy {
     useGenerate(): string;
 }
+/** Generic fake vehicle returned by `useFakeVehicle`. */
+export type FakeVehicle = z.infer<typeof FakeVehicleSchema>;
 /** Options for number formatting in geometry calculations. */
 export type GeometryFormatOptions = z.infer<typeof GeometryFormatOptionsSchema>;
 export type SignalListener<T> = (newValue: T, oldValue: T) => void;