@anil-labs/factory 0.1.0

package/dist/faker/faker.d.ts

@@ -0,0 +1,82 @@
+import { Prng } from '../prng/types';
+import { Person } from './person';
+import { Internet } from './internet';
+import { Location } from './location';
+import { Lorem } from './lorem';
+import { DateGen } from './date';
+import { NumberGen } from './number';
+import { StringGen } from './string';
+import { Color } from './color';
+import { Company } from './company';
+import { Commerce } from './commerce';
+import { Finance } from './finance';
+import { Image } from './image';
+import { System } from './system';
+import { Datatype } from './datatype';
+import { Helpers } from './helpers';
+/** Options for constructing a `Faker` instance. */
+export interface FakerOptions {
+    /** Initial locale name. Defaults to `"en"`. */
+    locale?: string;
+    /** Initial PRNG seed. If omitted, a time-based seed is used. */
+    seed?: number;
+}
+/**
+ * Faceted, seedable, locale-aware random-data generator.
+ *
+ * Every namespace shares the same PRNG and locale reference — `seed()` and
+ * `locale()` mutate that shared state in place, so changes propagate without
+ * re-constructing modules.
+ *
+ * @example
+ * ```ts
+ * import { Faker } from '@anil-labs/factory'
+ *
+ * const f = new Faker({ seed: 42, locale: 'en' })
+ * f.person.fullName()    // "Olivia Patel"
+ * f.seed(42)
+ * f.person.fullName()    // "Olivia Patel" — deterministic
+ *
+ * // Or use the package's default instance:
+ * import { faker } from '@anil-labs/factory'
+ * faker.seed(1)
+ * faker.internet.email()
+ * ```
+ */
+export declare class Faker {
+    private readonly rng;
+    private readonly localeRef;
+    readonly person: Person;
+    readonly internet: Internet;
+    readonly location: Location;
+    readonly lorem: Lorem;
+    readonly date: DateGen;
+    readonly number: NumberGen;
+    readonly string: StringGen;
+    readonly color: Color;
+    readonly company: Company;
+    readonly commerce: Commerce;
+    readonly finance: Finance;
+    readonly image: Image;
+    readonly system: System;
+    readonly datatype: Datatype;
+    readonly helpers: Helpers;
+    constructor(opts?: FakerOptions);
+    /** Reseed the underlying PRNG. Subsequent calls are deterministic from here. */
+    seed(seed: number): this;
+    /** Switch the active locale. Throws if unknown. */
+    locale(name: string): this;
+    /** Read the current locale identifier (e.g. `"en"`). */
+    currentLocale(): string;
+    /** Read the current seed (useful for snapshot reproduction). */
+    currentSeed(): number;
+    /**
+     * Build a fresh, independent `Faker` with its own PRNG seeded from this
+     * one's current state. Useful when you need to fork a deterministic stream.
+     */
+    fork(): Faker;
+    /** Access the underlying PRNG. Advanced use only. */
+    rawPrng(): Prng;
+}
+/** Default singleton — mutable via `faker.seed()` / `faker.locale()`. */
+export declare const faker: Faker;

package/dist/faker/finance.d.cts

@@ -0,0 +1,25 @@
+import { Prng } from '../prng/types';
+/**
+ * Finance generators.
+ *
+ * @example
+ * ```ts
+ * faker.finance.amount()              // "327.41"
+ * faker.finance.amount(0, 10, 2, '$') // "$4.27"
+ * faker.finance.accountNumber()
+ * faker.finance.creditCardNumber()    // 16-digit Luhn-valid number
+ * faker.finance.currencyCode()
+ * faker.finance.iban()
+ * ```
+ */
+export declare class Finance {
+    private readonly rng;
+    constructor(rng: Prng);
+    amount(min?: number, max?: number, decimals?: number, symbol?: string): string;
+    accountNumber(digits?: number): string;
+    /** Generates a Luhn-valid 16-digit credit-card number. */
+    creditCardNumber(): string;
+    currencyCode(): string;
+    iban(countryCode?: string, length?: number): string;
+    bitcoinAddress(): string;
+}

package/dist/faker/finance.d.ts

@@ -0,0 +1,25 @@
+import { Prng } from '../prng/types';
+/**
+ * Finance generators.
+ *
+ * @example
+ * ```ts
+ * faker.finance.amount()              // "327.41"
+ * faker.finance.amount(0, 10, 2, '$') // "$4.27"
+ * faker.finance.accountNumber()
+ * faker.finance.creditCardNumber()    // 16-digit Luhn-valid number
+ * faker.finance.currencyCode()
+ * faker.finance.iban()
+ * ```
+ */
+export declare class Finance {
+    private readonly rng;
+    constructor(rng: Prng);
+    amount(min?: number, max?: number, decimals?: number, symbol?: string): string;
+    accountNumber(digits?: number): string;
+    /** Generates a Luhn-valid 16-digit credit-card number. */
+    creditCardNumber(): string;
+    currencyCode(): string;
+    iban(countryCode?: string, length?: number): string;
+    bitcoinAddress(): string;
+}

package/dist/faker/helpers.d.cts

@@ -0,0 +1,52 @@
+import { Prng } from '../prng/types';
+export interface WeightedItem<T> {
+    /** The value to potentially return. */
+    readonly value: T;
+    /** Relative weight; need not sum to 1. */
+    readonly weight: number;
+}
+export interface UniqueOptions {
+    /** Maximum number of attempts before giving up. Defaults to `count * 10`. */
+    maxRetries?: number;
+}
+/**
+ * General helpers — operate on arbitrary inputs, not tied to any locale or
+ * faker namespace.
+ *
+ * @example
+ * ```ts
+ * faker.helpers.arrayElement([1, 2, 3])           // 2
+ * faker.helpers.arrayElements([1, 2, 3, 4], 2)    // [3, 1]
+ * faker.helpers.shuffle([1, 2, 3])                // [2, 3, 1]
+ * faker.helpers.weightedArrayElement([
+ *   { value: 'rare',   weight: 1 },
+ *   { value: 'common', weight: 9 },
+ * ])
+ * faker.helpers.fromRegExp(/[A-Z]{3}\d{4}/)       // "PWB7401"
+ * faker.helpers.unique(() => faker.internet.email(), 5)
+ * ```
+ */
+export declare class Helpers {
+    private readonly rng;
+    constructor(rng: Prng);
+    arrayElement<T>(items: readonly T[]): T;
+    /** Pick `count` distinct elements from `items` (no replacement). */
+    arrayElements<T>(items: readonly T[], count?: number): T[];
+    shuffle<T>(items: readonly T[]): T[];
+    weightedArrayElement<T>(items: readonly WeightedItem<T>[]): T;
+    /** Build an array of length `length` by calling `fn(index)`. */
+    multiple<T>(length: number, fn: (index: number) => T): T[];
+    /** Repeat a string `count` times. */
+    repeat(value: string, count: number): string;
+    /** Sample-string matching a regex. */
+    fromRegExp(pattern: RegExp | string): string;
+    /**
+     * Collect `count` unique results from `fn`. Throws if the retry budget is
+     * exhausted before reaching `count`.
+     */
+    unique<T>(fn: () => T, count: number, options?: UniqueOptions): T[];
+    /** Pick a random `enum` value, handling numeric reverse-mappings. */
+    enumValue<T>(enumObj: Record<string, T>): T;
+    /** With probability `chance`, return `value`; otherwise `undefined`. */
+    maybe<T>(value: T, chance?: number): T | undefined;
+}

package/dist/faker/helpers.d.ts

@@ -0,0 +1,52 @@
+import { Prng } from '../prng/types';
+export interface WeightedItem<T> {
+    /** The value to potentially return. */
+    readonly value: T;
+    /** Relative weight; need not sum to 1. */
+    readonly weight: number;
+}
+export interface UniqueOptions {
+    /** Maximum number of attempts before giving up. Defaults to `count * 10`. */
+    maxRetries?: number;
+}
+/**
+ * General helpers — operate on arbitrary inputs, not tied to any locale or
+ * faker namespace.
+ *
+ * @example
+ * ```ts
+ * faker.helpers.arrayElement([1, 2, 3])           // 2
+ * faker.helpers.arrayElements([1, 2, 3, 4], 2)    // [3, 1]
+ * faker.helpers.shuffle([1, 2, 3])                // [2, 3, 1]
+ * faker.helpers.weightedArrayElement([
+ *   { value: 'rare',   weight: 1 },
+ *   { value: 'common', weight: 9 },
+ * ])
+ * faker.helpers.fromRegExp(/[A-Z]{3}\d{4}/)       // "PWB7401"
+ * faker.helpers.unique(() => faker.internet.email(), 5)
+ * ```
+ */
+export declare class Helpers {
+    private readonly rng;
+    constructor(rng: Prng);
+    arrayElement<T>(items: readonly T[]): T;
+    /** Pick `count` distinct elements from `items` (no replacement). */
+    arrayElements<T>(items: readonly T[], count?: number): T[];
+    shuffle<T>(items: readonly T[]): T[];
+    weightedArrayElement<T>(items: readonly WeightedItem<T>[]): T;
+    /** Build an array of length `length` by calling `fn(index)`. */
+    multiple<T>(length: number, fn: (index: number) => T): T[];
+    /** Repeat a string `count` times. */
+    repeat(value: string, count: number): string;
+    /** Sample-string matching a regex. */
+    fromRegExp(pattern: RegExp | string): string;
+    /**
+     * Collect `count` unique results from `fn`. Throws if the retry budget is
+     * exhausted before reaching `count`.
+     */
+    unique<T>(fn: () => T, count: number, options?: UniqueOptions): T[];
+    /** Pick a random `enum` value, handling numeric reverse-mappings. */
+    enumValue<T>(enumObj: Record<string, T>): T;
+    /** With probability `chance`, return `value`; otherwise `undefined`. */
+    maybe<T>(value: T, chance?: number): T | undefined;
+}

package/dist/faker/image.d.cts

@@ -0,0 +1,22 @@
+import { Prng } from '../prng/types';
+/**
+ * Image-URL generators. No bytes are produced — just predictable URLs that
+ * resolve to real images from public providers.
+ *
+ * @example
+ * ```ts
+ * faker.image.url()                 // picsum.photos URL
+ * faker.image.avatar()              // ui-avatars URL
+ * faker.image.dataUri(64, 64)       // tiny embeddable PNG
+ * ```
+ */
+export declare class Image {
+    private readonly rng;
+    constructor(rng: Prng);
+    /** Picsum-photos placeholder URL. */
+    url(width?: number, height?: number): string;
+    /** ui-avatars.com avatar URL — needs a name to render initials. */
+    avatar(name?: string): string;
+    /** Tiny single-color PNG data-uri — useful for testing inline-image flows. */
+    dataUri(width?: number, height?: number): string;
+}

package/dist/faker/image.d.ts

@@ -0,0 +1,22 @@
+import { Prng } from '../prng/types';
+/**
+ * Image-URL generators. No bytes are produced — just predictable URLs that
+ * resolve to real images from public providers.
+ *
+ * @example
+ * ```ts
+ * faker.image.url()                 // picsum.photos URL
+ * faker.image.avatar()              // ui-avatars URL
+ * faker.image.dataUri(64, 64)       // tiny embeddable PNG
+ * ```
+ */
+export declare class Image {
+    private readonly rng;
+    constructor(rng: Prng);
+    /** Picsum-photos placeholder URL. */
+    url(width?: number, height?: number): string;
+    /** ui-avatars.com avatar URL — needs a name to render initials. */
+    avatar(name?: string): string;
+    /** Tiny single-color PNG data-uri — useful for testing inline-image flows. */
+    dataUri(width?: number, height?: number): string;
+}

package/dist/faker/index.d.cts

@@ -0,0 +1,21 @@
+export { Faker, faker } from './faker';
+export type { FakerOptions } from './faker';
+export { LocaleRef, registerLocale, getLocale, listLocales, en } from './locale';
+export type { LocaleData } from '../locales/types';
+export { generateFromRegex } from './regex';
+export { Person } from './person';
+export { Internet } from './internet';
+export { Location } from './location';
+export { Lorem } from './lorem';
+export { DateGen } from './date';
+export { NumberGen } from './number';
+export { StringGen } from './string';
+export { Color } from './color';
+export { Company } from './company';
+export { Commerce } from './commerce';
+export { Finance } from './finance';
+export { Image } from './image';
+export { System } from './system';
+export { Datatype } from './datatype';
+export { Helpers } from './helpers';
+export type { WeightedItem, UniqueOptions } from './helpers';

package/dist/faker/index.d.ts

@@ -0,0 +1,21 @@
+export { Faker, faker } from './faker';
+export type { FakerOptions } from './faker';
+export { LocaleRef, registerLocale, getLocale, listLocales, en } from './locale';
+export type { LocaleData } from '../locales/types';
+export { generateFromRegex } from './regex';
+export { Person } from './person';
+export { Internet } from './internet';
+export { Location } from './location';
+export { Lorem } from './lorem';
+export { DateGen } from './date';
+export { NumberGen } from './number';
+export { StringGen } from './string';
+export { Color } from './color';
+export { Company } from './company';
+export { Commerce } from './commerce';
+export { Finance } from './finance';
+export { Image } from './image';
+export { System } from './system';
+export { Datatype } from './datatype';
+export { Helpers } from './helpers';
+export type { WeightedItem, UniqueOptions } from './helpers';

package/dist/faker/internet.d.cts

@@ -0,0 +1,33 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Internet / network namespace.
+ *
+ * @example
+ * ```ts
+ * faker.internet.email()         // "olivia.patel91@example.com"
+ * faker.internet.email({ firstName: 'Alice', lastName: 'Wu' })  // "alice.wu41@…"
+ * faker.internet.userName()      // "alex_anderson"
+ * faker.internet.url()           // "https://app.gupta.io"
+ * faker.internet.ipv4()          // "172.16.42.7"
+ * faker.internet.password(12)    // "K8m$pQrt2Wz!"
+ * ```
+ */
+export declare class Internet {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    email(opts?: {
+        firstName?: string;
+        lastName?: string;
+    }): string;
+    userName(): string;
+    /** Bare domain (e.g. `acme.io`). */
+    domainName(): string;
+    url(): string;
+    ipv4(): string;
+    ipv6(): string;
+    /** Random MAC address (colon-separated). */
+    mac(): string;
+    password(length?: number): string;
+}

package/dist/faker/internet.d.ts

@@ -0,0 +1,33 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Internet / network namespace.
+ *
+ * @example
+ * ```ts
+ * faker.internet.email()         // "olivia.patel91@example.com"
+ * faker.internet.email({ firstName: 'Alice', lastName: 'Wu' })  // "alice.wu41@…"
+ * faker.internet.userName()      // "alex_anderson"
+ * faker.internet.url()           // "https://app.gupta.io"
+ * faker.internet.ipv4()          // "172.16.42.7"
+ * faker.internet.password(12)    // "K8m$pQrt2Wz!"
+ * ```
+ */
+export declare class Internet {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    email(opts?: {
+        firstName?: string;
+        lastName?: string;
+    }): string;
+    userName(): string;
+    /** Bare domain (e.g. `acme.io`). */
+    domainName(): string;
+    url(): string;
+    ipv4(): string;
+    ipv6(): string;
+    /** Random MAC address (colon-separated). */
+    mac(): string;
+    password(length?: number): string;
+}

package/dist/faker/locale.d.cts

@@ -0,0 +1,26 @@
+import { LocaleData } from '../locales/types';
+import { en } from '../locales/en';
+/**
+ * Live reference to the active locale data. A single instance is shared by
+ * every faker namespace, so swapping the locale at the `Faker` level
+ * propagates instantly without rebuilding modules.
+ */
+export declare class LocaleRef {
+    private currentName;
+    private currentData;
+    constructor(initial?: string);
+    /** Read the currently-active locale data. */
+    get data(): LocaleData;
+    /** Read the active locale's identifier (e.g. `"en"`). */
+    get name(): string;
+    /** Swap to a different registered locale. Throws if unknown. */
+    set(name: string): void;
+}
+/** Register a new locale. Overwrites if `name` already exists. */
+export declare function registerLocale(name: string, data: LocaleData): void;
+/** Read a locale's raw data without making it active. */
+export declare function getLocale(name: string): LocaleData | undefined;
+/** List every registered locale identifier. */
+export declare function listLocales(): string[];
+export type { LocaleData };
+export { en };

package/dist/faker/locale.d.ts

@@ -0,0 +1,26 @@
+import { LocaleData } from '../locales/types';
+import { en } from '../locales/en';
+/**
+ * Live reference to the active locale data. A single instance is shared by
+ * every faker namespace, so swapping the locale at the `Faker` level
+ * propagates instantly without rebuilding modules.
+ */
+export declare class LocaleRef {
+    private currentName;
+    private currentData;
+    constructor(initial?: string);
+    /** Read the currently-active locale data. */
+    get data(): LocaleData;
+    /** Read the active locale's identifier (e.g. `"en"`). */
+    get name(): string;
+    /** Swap to a different registered locale. Throws if unknown. */
+    set(name: string): void;
+}
+/** Register a new locale. Overwrites if `name` already exists. */
+export declare function registerLocale(name: string, data: LocaleData): void;
+/** Read a locale's raw data without making it active. */
+export declare function getLocale(name: string): LocaleData | undefined;
+/** List every registered locale identifier. */
+export declare function listLocales(): string[];
+export type { LocaleData };
+export { en };

package/dist/faker/location.d.cts

@@ -0,0 +1,30 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Postal-address namespace.
+ *
+ * @example
+ * ```ts
+ * faker.location.streetAddress()    // "742 Oak Ave"
+ * faker.location.city()             // "Seattle"
+ * faker.location.country()          // "United States"
+ * faker.location.latitude()         // 47.6062
+ * ```
+ */
+export declare class Location {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    streetAddress(): string;
+    city(): string;
+    state(): string;
+    zipCode(): string;
+    /** Locale's primary country (e.g. `"United States"` for `en`). */
+    country(): string;
+    /** Random country from the locale's broader country list. */
+    countryName(): string;
+    /** Full single-line address. */
+    fullAddress(): string;
+    latitude(min?: number, max?: number): number;
+    longitude(min?: number, max?: number): number;
+}

package/dist/faker/location.d.ts

@@ -0,0 +1,30 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Postal-address namespace.
+ *
+ * @example
+ * ```ts
+ * faker.location.streetAddress()    // "742 Oak Ave"
+ * faker.location.city()             // "Seattle"
+ * faker.location.country()          // "United States"
+ * faker.location.latitude()         // 47.6062
+ * ```
+ */
+export declare class Location {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    streetAddress(): string;
+    city(): string;
+    state(): string;
+    zipCode(): string;
+    /** Locale's primary country (e.g. `"United States"` for `en`). */
+    country(): string;
+    /** Random country from the locale's broader country list. */
+    countryName(): string;
+    /** Full single-line address. */
+    fullAddress(): string;
+    latitude(min?: number, max?: number): number;
+    longitude(min?: number, max?: number): number;
+}

package/dist/faker/lorem.d.cts

@@ -0,0 +1,26 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Lorem-ipsum text generator.
+ *
+ * @example
+ * ```ts
+ * faker.lorem.word()              // "consectetur"
+ * faker.lorem.words(3)            // "dolor sit amet"
+ * faker.lorem.sentence()          // "Ut labore et dolore magna aliqua."
+ * faker.lorem.paragraph()
+ * faker.lorem.paragraphs(3)
+ * ```
+ */
+export declare class Lorem {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    word(): string;
+    words(count?: number): string;
+    sentence(wordCount?: number): string;
+    paragraph(sentenceCount?: number): string;
+    paragraphs(count?: number): string;
+    /** Alias of `paragraph()` — matches faker.js. */
+    text(): string;
+}

package/dist/faker/lorem.d.ts

@@ -0,0 +1,26 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Lorem-ipsum text generator.
+ *
+ * @example
+ * ```ts
+ * faker.lorem.word()              // "consectetur"
+ * faker.lorem.words(3)            // "dolor sit amet"
+ * faker.lorem.sentence()          // "Ut labore et dolore magna aliqua."
+ * faker.lorem.paragraph()
+ * faker.lorem.paragraphs(3)
+ * ```
+ */
+export declare class Lorem {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    word(): string;
+    words(count?: number): string;
+    sentence(wordCount?: number): string;
+    paragraph(sentenceCount?: number): string;
+    paragraphs(count?: number): string;
+    /** Alias of `paragraph()` — matches faker.js. */
+    text(): string;
+}

package/dist/faker/number.d.cts

@@ -0,0 +1,31 @@
+import { Prng } from '../prng/types';
+/**
+ * Number generators.
+ *
+ * @example
+ * ```ts
+ * faker.number.int({ min: 1, max: 100 })
+ * faker.number.float({ min: 0, max: 1, decimals: 3 })
+ * faker.number.bigInt({ min: 0n, max: 1000n })
+ * faker.number.between(1, 5)
+ * ```
+ */
+export declare class NumberGen {
+    private readonly rng;
+    constructor(rng: Prng);
+    int(opts?: {
+        max?: number;
+        min?: number;
+    }): number;
+    float(opts?: {
+        decimals?: number;
+        max?: number;
+        min?: number;
+    }): number;
+    bigInt(opts?: {
+        max?: bigint;
+        min?: bigint;
+    }): bigint;
+    /** Convenience: integer in `[min, max]`. */
+    between(min: number, max: number): number;
+}

package/dist/faker/number.d.ts

@@ -0,0 +1,31 @@
+import { Prng } from '../prng/types';
+/**
+ * Number generators.
+ *
+ * @example
+ * ```ts
+ * faker.number.int({ min: 1, max: 100 })
+ * faker.number.float({ min: 0, max: 1, decimals: 3 })
+ * faker.number.bigInt({ min: 0n, max: 1000n })
+ * faker.number.between(1, 5)
+ * ```
+ */
+export declare class NumberGen {
+    private readonly rng;
+    constructor(rng: Prng);
+    int(opts?: {
+        max?: number;
+        min?: number;
+    }): number;
+    float(opts?: {
+        decimals?: number;
+        max?: number;
+        min?: number;
+    }): number;
+    bigInt(opts?: {
+        max?: bigint;
+        min?: bigint;
+    }): bigint;
+    /** Convenience: integer in `[min, max]`. */
+    between(min: number, max: number): number;
+}

package/dist/faker/person.d.cts

@@ -0,0 +1,29 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Personal-name namespace.
+ *
+ * @example
+ * ```ts
+ * faker.person.firstName()       // "Sarah"
+ * faker.person.firstName('male') // "James"
+ * faker.person.fullName()        // "Olivia Patel"
+ * faker.person.jobTitle()        // → from `company.jobTitle()`
+ * ```
+ */
+export declare class Person {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    firstName(sex?: 'male' | 'female'): string;
+    lastName(): string;
+    fullName(opts?: {
+        sex?: 'male' | 'female';
+        withPrefix?: boolean;
+        withSuffix?: boolean;
+    }): string;
+    prefix(): string;
+    suffix(): string;
+    /** Returns `"male"` or `"female"`. */
+    sex(): 'male' | 'female';
+}