katanakit-js 5.1.0 → 5.1.1

package/README.md

@@ -329,6 +329,145 @@ const stop = useKatanaWatch(newProduct, () => checkValidations(), { deep: true }
 - **Hexagonal architecture** — pure core, infrastructure adapters, framework adapters
 - **Tree-shakeable** — destructured re-exports from Singleton facades
 - **SSR-safe** — all infrastructure adapters guard or fall back gracefully in server environments
+- **Filesystem (Node/Bun)** — `useReadFile`, `useWriteFile`, `useReadJsonFile`, `useReadModuleJson` and friends return Safe Results with native errno codes, loaded lazily through dynamic `import()` and guarded by `useIsNode()`
+- **Fake data (optional)** — `useFakeVehicle`, `useFakeEmail`, `useFakeList`, … via an optional, lazy-loaded `@faker-js/faker` peer
+
+## Filesystem (Node/Bun)
+
+Node-only helpers that wrap `node:fs/promises` and `node:path` with the Safe
+Result contract. Built-ins load through dynamic `import()`, so importing them is
+browser-safe; outside Node/Bun every fallible call returns `ERR_FS_UNAVAILABLE`
+instead of throwing.
+
+```ts
+import {
+  useEnsureDir,
+  useReadDir,
+  useReadJsonFile,
+  useReadModuleJson,
+  useWriteJsonFile,
+} from "katanakit-js";
+import { z } from "zod";
+
+const BooksSchema = z.array(z.object({ title: z.string() }));
+
+// Read relative to the current module (the __dirname pattern, without __dirname)
+const result = await useReadModuleJson(import.meta.url, "../data/books.json", BooksSchema);
+
+if (result.ok) {
+  console.log(result.data);
+} else {
+  console.error(result.error.code, result.error.message); // ENOENT | ERR_VALIDATION | ...
+}
+
+// Or with an explicit path (relative paths resolve against process.cwd())
+await useEnsureDir("data/cache");
+await useWriteJsonFile("data/cache/books.json", [{ title: "Kata" }]);
+const books = await useReadJsonFile("data/cache/books.json", BooksSchema);
+const files = await useReadDir("data/cache", { recursive: true });
+```
+
+| Group | Helpers |
+| ----- | ------- |
+| Read | `useReadFile`, `useReadFileBuffer`, `useReadJsonFile`, `useReadModuleFile`, `useReadModuleJson` |
+| Write | `useWriteFile`, `useAppendFile`, `useWriteJsonFile`, `useEnsureDir` |
+| Inspect | `useFileExists`, `useGetFileStats`, `useReadDir` |
+| Move / delete | `useCopyFile`, `useMoveFile`, `useRemoveFile`, `useRemoveDir` |
+| Paths | `useGetDirname`, `useResolvePath`, `useJoinPath`, `useGetRelativePath`, `useGetBasename`, `useGetFileExtension`, `useGetCwd`, `useIsNode` |
+
+## Fake data (optional)
+
+`@faker-js/faker` is an **optional peer dependency**: these helpers load it
+through dynamic `import()` on first call, so install it only if you use them
+(`bun add @faker-js/faker` / `npm install @faker-js/faker`).
+
+| Group             | Helpers                                                                                                        |
+| ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| People / internet | `useFakeFullName`, `useFakeFirstName`, `useFakeLastName`, `useFakeEmail`, `useFakePhone`, `useFakeCompanyName`, `useFakeUrl` |
+| Values            | `useFakeUuid`, `useFakeText`, `useFakeNumber`, `useFakeBoolean`, `useFakeDate`, `useFakeVehicle`                |
+| Collections       | `useFakeList(factory, count)` — the factory receives the zero-based index                                       |
+| Reproducibility   | `useFakeSeed(seed?)`, `useFakeSetDefaultRefDate(refDate?)`                                                      |
+
+### Reproducible seeds
+
+`useFakeSeed(42)` sets the seed **and returns it**. Call it with no arguments to
+roll a fresh random seed (also returned) — log it in CI and pass it back later
+to replay the exact run. `useFakeSetDefaultRefDate("2026-01-01")` pins the
+reference date used by date helpers. Same seed + same reference date + same
+call order + same faker major = identical output.
+
+```ts
+import { useFakeSeed, useFakeSetDefaultRefDate, useFakeUuid } from "katanakit-js";
+
+const seed = await useFakeSeed(); // e.g. 1696121567592875 — log it in CI
+await useFakeSetDefaultRefDate("2026-01-01");
+
+await useFakeSeed(seed); // replay the exact same sequence
+const id = await useFakeUuid();
+```
+
+### Seed data (users, products, orders)
+
+Compose the helpers with `useFakeList` to build realistic fixtures, then write
+them anywhere with the [filesystem helpers](#filesystem-nodebun):
+
+```ts
+import {
+  useEnsureDir,
+  useFakeDate,
+  useFakeEmail,
+  useFakeFullName,
+  useFakeList,
+  useFakeNumber,
+  useFakeSeed,
+  useFakeSetDefaultRefDate,
+  useFakeText,
+  useFakeUuid,
+  useWriteJsonFile,
+} from "katanakit-js";
+
+await useFakeSeed(42);
+await useFakeSetDefaultRefDate("2026-01-01");
+
+const users = await useFakeList(
+  async () => ({
+    id: await useFakeUuid(),
+    fullName: await useFakeFullName(),
+    email: await useFakeEmail(),
+    createdAt: (await useFakeDate("2024-01-01")).toISOString(),
+  }),
+  5,
+);
+
+const products = await useFakeList(
+  async () => ({
+    id: await useFakeUuid(),
+    name: await useFakeText(3),
+    price: await useFakeNumber(5, 250),
+    stock: await useFakeNumber(0, 120),
+  }),
+  8,
+);
+
+// Relations: the factory receives the index
+const orders = await useFakeList(
+  async (index) => ({
+    id: await useFakeUuid(),
+    userId: users[index % users.length].id,
+    productId: products[index % products.length].id,
+    quantity: await useFakeNumber(1, 6),
+    placedAt: (await useFakeDate("2025-01-01")).toISOString(),
+  }),
+  12,
+);
+
+await useEnsureDir("data/seed");
+await useWriteJsonFile("data/seed/users.json", users);
+// feed the arrays to your seeder: prisma.user.createMany({ data: users }), ...
+```
+
+A runnable version (users, products and orders with relations, written as JSON)
+lives in [`examples/seed/`](./examples/seed/README.md).
 
 ## AI assistant (Kitt)
 

package/dist/core/index.d.ts

@@ -3,6 +3,7 @@ export * from "./services/agent.service.js";
 export * from "./services/assistant.service.js";
 export * from "./services/dates.service.js";
 export * from "./services/error.service.js";
+export * from "./services/faker.service.js";
 export * from "./services/formatter.service.js";
 export * from "./services/generator.service.js";
 export * from "./services/geometry.service.js";

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC"}

package/dist/core/index.js

@@ -3,6 +3,7 @@ export * from "./services/agent.service.js";
 export * from "./services/assistant.service.js";
 export * from "./services/dates.service.js";
 export * from "./services/error.service.js";
+export * from "./services/faker.service.js";
 export * from "./services/formatter.service.js";
 export * from "./services/generator.service.js";
 export * from "./services/geometry.service.js";

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,+BAA+B,CAAC"}

package/dist/core/services/faker.service.d.ts

@@ -0,0 +1,160 @@
+import type { FakeVehicle } from "../../types/index.js";
+/**
+ * Seeds the faker instance for reproducible output, or rolls a new random seed.
+ *
+ * The sequence depends on the seed, the number of calls made since it was set
+ * and the faker major version — keep the call order stable for stable output.
+ *
+ * @param seed - Optional numeric seed. Omit it to generate a fresh random seed
+ * (log the returned value and pass it back later to replay the exact run).
+ * @returns The seed that was set.
+ *
+ * @example
+ * ```ts
+ * import { useFakeSeed, useFakeUuid } from "katanakit-js";
+ *
+ * const seed = await useFakeSeed(); // random, but loggable/replayable
+ * await useFakeSeed(seed);          // replays the same sequence
+ * await useFakeUuid();
+ * ```
+ */
+export declare function useFakeSeed(seed?: number): Promise<number>;
+/**
+ * Pins the reference date faker uses for relative date helpers, so
+ * date-dependent output stays reproducible next to {@link useFakeSeed}.
+ *
+ * @param refDate - Static date (`Date`, ISO string or epoch ms) or a factory
+ * returning a fresh `Date` on every call. Omit it to reset to the current time.
+ * @returns The reference date now in effect.
+ *
+ * @example
+ * ```ts
+ * import { useFakeSeed, useFakeSetDefaultRefDate, useFakeDate } from "katanakit-js";
+ *
+ * await useFakeSeed(42);
+ * await useFakeSetDefaultRefDate("2026-01-01");
+ * await useFakeDate(); // reproducible between 1970-01-01 and 2026-01-01
+ * ```
+ */
+export declare function useFakeSetDefaultRefDate(refDate?: Date | number | string | (() => Date)): Promise<Date>;
+/**
+ * Generates a v4 UUID.
+ *
+ * @returns A random UUID string.
+ *
+ * @example
+ * ```ts
+ * const id = await useFakeUuid();
+ * ```
+ */
+export declare function useFakeUuid(): Promise<string>;
+/**
+ * Generates a fake email address.
+ *
+ * @returns An email address.
+ */
+export declare function useFakeEmail(): Promise<string>;
+/**
+ * Generates a fake full name.
+ *
+ * @returns A full name, e.g. `"Ada Lovelace"`.
+ */
+export declare function useFakeFullName(): Promise<string>;
+/**
+ * Generates a fake first name.
+ *
+ * @returns A first name.
+ */
+export declare function useFakeFirstName(): Promise<string>;
+/**
+ * Generates a fake last name.
+ *
+ * @returns A last name.
+ */
+export declare function useFakeLastName(): Promise<string>;
+/**
+ * Generates a fake phone number.
+ *
+ * @returns A phone number string.
+ */
+export declare function useFakePhone(): Promise<string>;
+/**
+ * Generates a fake company name.
+ *
+ * @returns A company name.
+ */
+export declare function useFakeCompanyName(): Promise<string>;
+/**
+ * Generates a fake URL.
+ *
+ * @returns An absolute URL.
+ */
+export declare function useFakeUrl(): Promise<string>;
+/**
+ * Generates lorem-ipsum text.
+ *
+ * @param words - Number of words (default: `12`).
+ * @returns A space-separated string of words.
+ */
+export declare function useFakeText(words?: number): Promise<string>;
+/**
+ * Generates an integer within an inclusive range.
+ *
+ * @param min - Lower bound (default: `0`).
+ * @param max - Upper bound (default: `100`).
+ * @returns A random integer between `min` and `max`.
+ *
+ * @example
+ * ```ts
+ * const age = await useFakeNumber(18, 65);
+ * ```
+ */
+export declare function useFakeNumber(min?: number, max?: number): Promise<number>;
+/**
+ * Generates a random boolean.
+ *
+ * @returns `true` or `false`.
+ */
+export declare function useFakeBoolean(): Promise<boolean>;
+/**
+ * Generates a random date within an optional range.
+ *
+ * @param from - Lower bound (default: `1970-01-01`).
+ * @param to - Upper bound (default: faker's reference date, see
+ * {@link useFakeSetDefaultRefDate} — the current time when unset).
+ * @returns A `Date` instance.
+ *
+ * @example
+ * ```ts
+ * const hiredAt = await useFakeDate(new Date("2020-01-01"), new Date("2025-12-31"));
+ * ```
+ */
+export declare function useFakeDate(from?: Date | number | string, to?: Date | number | string): Promise<Date>;
+/**
+ * Generates a generic fake vehicle (brand, model, type, fuel, color, vin, plate).
+ *
+ * @returns A {@link FakeVehicle} object.
+ *
+ * @example
+ * ```ts
+ * const vehicle = await useFakeVehicle();
+ * // { brand: "Jeep", model: "Wrangler", plate: "HJ47FNP", ... }
+ * ```
+ */
+export declare function useFakeVehicle(): Promise<FakeVehicle>;
+/**
+ * Builds an array of fake items from a factory (sync or async).
+ *
+ * @typeParam T - Item type produced by the factory.
+ * @param factory - Called once per item; receives the zero-based index.
+ * @param count - Number of items to generate (non-negative integer).
+ * @returns A promise resolving to the generated array.
+ *
+ * @example
+ * ```ts
+ * const vehicles = await useFakeList(() => useFakeVehicle(), 5);
+ * const relations = await useFakeList((index) => ({ user: users[index % users.length] }), 10);
+ * ```
+ */
+export declare function useFakeList<T>(factory: (index: number) => T | Promise<T>, count: number): Promise<T[]>;
+//# sourceMappingURL=faker.service.d.ts.map

package/dist/core/services/faker.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faker.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/faker.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AA+BxD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,wBAAwB,CAC7C,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,GAC7C,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAGnD;AAED;;;;GAIG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAGpD;AAED;;;;GAIG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAGvD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC,CAGxD;AAED;;;;GAIG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAGvD;AAED;;;;GAIG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAGpD;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED;;;;GAIG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAGlD;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,GAAG,SAAI,EAAE,GAAG,SAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGvE;AAED;;;;GAIG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC,CAGvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAChC,IAAI,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAC7B,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GACzB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAW3D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAClC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC1C,KAAK,EAAE,MAAM,GACX,OAAO,CAAC,CAAC,EAAE,CAAC,CAKd"}

package/dist/core/services/faker.service.js

@@ -0,0 +1,235 @@
+/** Cached lazy faker instance (reset on failure so a later call can retry). */
+let fakerPromise = null;
+/** Loads faker on first use, or rejects with an actionable install error. */
+async function loadFaker() {
+    if (!fakerPromise) {
+        fakerPromise = import("@faker-js/faker")
+            .then((module) => module.faker)
+            .catch((error) => {
+            fakerPromise = null;
+            throw new Error('[Faker] The optional peer dependency "@faker-js/faker" is not installed. Run "bun add @faker-js/faker" (or "npm install @faker-js/faker").', { cause: error });
+        });
+    }
+    return fakerPromise;
+}
+/**
+ * Seeds the faker instance for reproducible output, or rolls a new random seed.
+ *
+ * The sequence depends on the seed, the number of calls made since it was set
+ * and the faker major version — keep the call order stable for stable output.
+ *
+ * @param seed - Optional numeric seed. Omit it to generate a fresh random seed
+ * (log the returned value and pass it back later to replay the exact run).
+ * @returns The seed that was set.
+ *
+ * @example
+ * ```ts
+ * import { useFakeSeed, useFakeUuid } from "katanakit-js";
+ *
+ * const seed = await useFakeSeed(); // random, but loggable/replayable
+ * await useFakeSeed(seed);          // replays the same sequence
+ * await useFakeUuid();
+ * ```
+ */
+export async function useFakeSeed(seed) {
+    const faker = await loadFaker();
+    return seed === undefined ? faker.seed() : faker.seed(seed);
+}
+/**
+ * Pins the reference date faker uses for relative date helpers, so
+ * date-dependent output stays reproducible next to {@link useFakeSeed}.
+ *
+ * @param refDate - Static date (`Date`, ISO string or epoch ms) or a factory
+ * returning a fresh `Date` on every call. Omit it to reset to the current time.
+ * @returns The reference date now in effect.
+ *
+ * @example
+ * ```ts
+ * import { useFakeSeed, useFakeSetDefaultRefDate, useFakeDate } from "katanakit-js";
+ *
+ * await useFakeSeed(42);
+ * await useFakeSetDefaultRefDate("2026-01-01");
+ * await useFakeDate(); // reproducible between 1970-01-01 and 2026-01-01
+ * ```
+ */
+export async function useFakeSetDefaultRefDate(refDate) {
+    const faker = await loadFaker();
+    faker.setDefaultRefDate(refDate);
+    return faker.defaultRefDate();
+}
+/**
+ * Generates a v4 UUID.
+ *
+ * @returns A random UUID string.
+ *
+ * @example
+ * ```ts
+ * const id = await useFakeUuid();
+ * ```
+ */
+export async function useFakeUuid() {
+    const faker = await loadFaker();
+    return faker.string.uuid();
+}
+/**
+ * Generates a fake email address.
+ *
+ * @returns An email address.
+ */
+export async function useFakeEmail() {
+    const faker = await loadFaker();
+    return faker.internet.email();
+}
+/**
+ * Generates a fake full name.
+ *
+ * @returns A full name, e.g. `"Ada Lovelace"`.
+ */
+export async function useFakeFullName() {
+    const faker = await loadFaker();
+    return faker.person.fullName();
+}
+/**
+ * Generates a fake first name.
+ *
+ * @returns A first name.
+ */
+export async function useFakeFirstName() {
+    const faker = await loadFaker();
+    return faker.person.firstName();
+}
+/**
+ * Generates a fake last name.
+ *
+ * @returns A last name.
+ */
+export async function useFakeLastName() {
+    const faker = await loadFaker();
+    return faker.person.lastName();
+}
+/**
+ * Generates a fake phone number.
+ *
+ * @returns A phone number string.
+ */
+export async function useFakePhone() {
+    const faker = await loadFaker();
+    return faker.phone.number();
+}
+/**
+ * Generates a fake company name.
+ *
+ * @returns A company name.
+ */
+export async function useFakeCompanyName() {
+    const faker = await loadFaker();
+    return faker.company.name();
+}
+/**
+ * Generates a fake URL.
+ *
+ * @returns An absolute URL.
+ */
+export async function useFakeUrl() {
+    const faker = await loadFaker();
+    return faker.internet.url();
+}
+/**
+ * Generates lorem-ipsum text.
+ *
+ * @param words - Number of words (default: `12`).
+ * @returns A space-separated string of words.
+ */
+export async function useFakeText(words = 12) {
+    const faker = await loadFaker();
+    return faker.lorem.words(words);
+}
+/**
+ * Generates an integer within an inclusive range.
+ *
+ * @param min - Lower bound (default: `0`).
+ * @param max - Upper bound (default: `100`).
+ * @returns A random integer between `min` and `max`.
+ *
+ * @example
+ * ```ts
+ * const age = await useFakeNumber(18, 65);
+ * ```
+ */
+export async function useFakeNumber(min = 0, max = 100) {
+    const faker = await loadFaker();
+    return faker.number.int({ max, min });
+}
+/**
+ * Generates a random boolean.
+ *
+ * @returns `true` or `false`.
+ */
+export async function useFakeBoolean() {
+    const faker = await loadFaker();
+    return faker.datatype.boolean();
+}
+/**
+ * Generates a random date within an optional range.
+ *
+ * @param from - Lower bound (default: `1970-01-01`).
+ * @param to - Upper bound (default: faker's reference date, see
+ * {@link useFakeSetDefaultRefDate} — the current time when unset).
+ * @returns A `Date` instance.
+ *
+ * @example
+ * ```ts
+ * const hiredAt = await useFakeDate(new Date("2020-01-01"), new Date("2025-12-31"));
+ * ```
+ */
+export async function useFakeDate(from, to) {
+    const faker = await loadFaker();
+    return faker.date.between({
+        from: from ?? "1970-01-01",
+        to: to ?? faker.defaultRefDate(),
+    });
+}
+/**
+ * Generates a generic fake vehicle (brand, model, type, fuel, color, vin, plate).
+ *
+ * @returns A {@link FakeVehicle} object.
+ *
+ * @example
+ * ```ts
+ * const vehicle = await useFakeVehicle();
+ * // { brand: "Jeep", model: "Wrangler", plate: "HJ47FNP", ... }
+ * ```
+ */
+export async function useFakeVehicle() {
+    const faker = await loadFaker();
+    return {
+        brand: faker.vehicle.manufacturer(),
+        color: faker.vehicle.color(),
+        fuel: faker.vehicle.fuel(),
+        model: faker.vehicle.model(),
+        plate: faker.vehicle.vrm(),
+        type: faker.vehicle.type(),
+        vin: faker.vehicle.vin(),
+    };
+}
+/**
+ * Builds an array of fake items from a factory (sync or async).
+ *
+ * @typeParam T - Item type produced by the factory.
+ * @param factory - Called once per item; receives the zero-based index.
+ * @param count - Number of items to generate (non-negative integer).
+ * @returns A promise resolving to the generated array.
+ *
+ * @example
+ * ```ts
+ * const vehicles = await useFakeList(() => useFakeVehicle(), 5);
+ * const relations = await useFakeList((index) => ({ user: users[index % users.length] }), 10);
+ * ```
+ */
+export async function useFakeList(factory, count) {
+    if (!Number.isInteger(count) || count < 0) {
+        throw new Error("[Faker] count must be a non-negative integer.");
+    }
+    return Promise.all(Array.from({ length: count }, (_, index) => factory(index)));
+}
+//# sourceMappingURL=faker.service.js.map

package/dist/core/services/faker.service.js.map

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