@anil-labs/factory 0.1.0

package/dist/core/factory.d.ts

@@ -0,0 +1,115 @@
+import { Collection } from './collection';
+import { Sequence, SequenceEntry } from './sequence';
+import { Definition, Hook, Persist, StateValue } from './types';
+/**
+ * Laravel-inspired model factory for TypeScript. Immutable fluent chain — every
+ * method returns a new factory, never mutating the original.
+ *
+ * @example
+ * ```ts
+ * interface User { id: number; name: string; email: string; active: boolean }
+ *
+ * const UserFactory = defineFactory<User>(({ seq, faker }) => ({
+ *   id: seq,
+ *   name: faker.person.fullName(),
+ *   email: faker.internet.email(),
+ *   active: true,
+ * }))
+ *   .state('admin', { role: 'admin' })
+ *   .state('inactive', { active: false })
+ *
+ * UserFactory.make()                    // single User
+ * UserFactory.count(5).make()           // User[]
+ * UserFactory.state('admin').make()     // with admin overrides
+ * await UserFactory.persist(...).create()
+ * ```
+ */
+export declare class Factory<T extends object> {
+    /** @internal */ private readonly definition;
+    /** @internal */ private readonly internals;
+    /** @internal — use {@link defineFactory} or {@link Factory.define} instead. */
+    private constructor();
+    /** Create a new factory. Mirrors Laravel's `Factory::new()`. */
+    static define<T extends object>(definition: Definition<T>, persist?: Persist<T>): Factory<T>;
+    /** Internal: build a copy with a single field replaced. */
+    private clone;
+    /** Set how many items will be built on the next terminal call. */
+    count(n: number): Factory<T>;
+    /** Alias of {@link count} — matches Laravel's `->times()`. */
+    times(n: number): Factory<T>;
+    /** Merge inline overrides into every built item. */
+    with(overrides: Partial<T>): Factory<T>;
+    /**
+     * Register a named state OR activate a previously-registered state.
+     *
+     *   - Two-arg form (`state(name, value)`) **registers** the state.
+     *   - One-arg form (`state(name)`) **activates** it.
+     *   - One-arg with a Sequence (`state(seq)`) attaches a sequence as a state.
+     */
+    state(arg1: string | Sequence<T>, value?: StateValue<T>): Factory<T>;
+    /** Bulk-register multiple states. */
+    states(map: Record<string, StateValue<T>>): Factory<T>;
+    /** Cycle values through one field across generated items. */
+    fieldSequence<K extends keyof T>(field: K, values: readonly T[K][]): Factory<T>;
+    /** Attach a sequence of attribute patches. */
+    sequence(entries: readonly SequenceEntry<T>[]): Factory<T>;
+    /** Attach child records under `key` (one-to-many). */
+    has<C extends object>(childFactory: Factory<C>, key: keyof T | string): Factory<T>;
+    /**
+     * Set a foreign-key field by either resolving from another factory
+     * (eager — built once), a plain object (used directly), or a lazy callback
+     * (built per-item).
+     */
+    for<P extends object>(parent: Factory<P> | P | (() => P), foreignKey: keyof T | string, resolver?: (parent: P) => Partial<T>): Factory<T>;
+    /** Attach related records with pivot/intermediate data (many-to-many). */
+    hasAttached<C extends object>(childFactory: Factory<C>, key: keyof T | string, pivot?: Record<string, unknown> | ((parent: T, child: C) => Record<string, unknown>)): Factory<T>;
+    /** Add models to the recycle pool keyed by `key`. */
+    recycle<M extends object>(models: M | readonly M[], key: string): Factory<T>;
+    /** Pick a random recycled model from `key`, or undefined. */
+    getRecycled(key: string): object | undefined;
+    /** Register a hook fired after each item is built. */
+    afterMaking(fn: Hook<T>): Factory<T>;
+    /** Register a hook fired after each item is persisted via `create()`. */
+    afterCreating(fn: Hook<T>): Factory<T>;
+    /** Set or replace the persistence callback used by `create()`. */
+    persist(fn: Persist<T>): Factory<T>;
+    /**
+     * Bind this factory to its own private `Faker` instance, seeded as given.
+     * Useful when one factory in a suite must be deterministic without
+     * affecting the shared default faker.
+     */
+    seed(seed: number): Factory<T>;
+    /** Set the locale on this factory's faker (creates one if it was shared). */
+    locale(name: string): Factory<T>;
+    /** Build a single item (ignoring `count`). */
+    makeOne(): T;
+    /** Build `count` items. */
+    makeMany(): T[];
+    /**
+     * Build — single item when `count === 1`, array otherwise.
+     * Use {@link makeOne} / {@link makeMany} when you need a specific shape.
+     */
+    make(): T | T[];
+    /** Raw attribute objects with the same shape as `make()`. */
+    raw(): T | T[];
+    /** Build and return as a {@link Collection}. */
+    collect(): Collection<T>;
+    /**
+     * Build and persist via the registered persistence callback.
+     * Returns single item when `count === 1`, array otherwise.
+     */
+    create(): Promise<T | T[]>;
+    /** Always-array variant of {@link create}. */
+    createMany(): Promise<T[]>;
+    private buildOne;
+    private buildMany;
+    /**
+     * Fire afterMaking hooks for the sync build path (`make`/`makeOne`/`makeMany`/
+     * `collect`). Async hooks are kicked off without awaiting — use {@link create}
+     * if you need guaranteed sequencing.
+     */
+    private fireAfterMakingSync;
+    private runHooks;
+}
+/** Functional alias for `Factory.define()`. */
+export declare function defineFactory<T extends object>(definition: Definition<T>, persist?: Persist<T>): Factory<T>;

package/dist/core/index.d.cts

@@ -0,0 +1,6 @@
+export { Factory, defineFactory } from './factory';
+export { Sequence, sequence } from './sequence';
+export type { SequenceEntry, SequenceInfo } from './sequence';
+export { Collection } from './collection';
+export { FactoryRegistry } from './registry';
+export type { BuildContext, Definition, Hook, HasAttachedRelation, HasRelation, Persist, StateFn, StateValue, } from './types';

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+export { Factory, defineFactory } from './factory';
+export { Sequence, sequence } from './sequence';
+export type { SequenceEntry, SequenceInfo } from './sequence';
+export { Collection } from './collection';
+export { FactoryRegistry } from './registry';
+export type { BuildContext, Definition, Hook, HasAttachedRelation, HasRelation, Persist, StateFn, StateValue, } from './types';

package/dist/core/registry.d.cts

@@ -0,0 +1,20 @@
+import { Factory } from './factory';
+/**
+ * Process-global registry that lets you look up factories by name.
+ * Mirrors how Laravel resolves `UserFactory` from `User::factory()`.
+ *
+ * @example
+ * ```ts
+ * FactoryRegistry.register('User', UserFactory)
+ * const f = FactoryRegistry.resolve<User>('User')
+ * f.count(5).make()
+ * ```
+ */
+export declare const FactoryRegistry: {
+    register<T extends object>(name: string, factory: Factory<T>): void;
+    resolve<T extends object>(name: string): Factory<T>;
+    has(name: string): boolean;
+    unregister(name: string): boolean;
+    clear(): void;
+    names(): string[];
+};

package/dist/core/registry.d.ts

@@ -0,0 +1,20 @@
+import { Factory } from './factory';
+/**
+ * Process-global registry that lets you look up factories by name.
+ * Mirrors how Laravel resolves `UserFactory` from `User::factory()`.
+ *
+ * @example
+ * ```ts
+ * FactoryRegistry.register('User', UserFactory)
+ * const f = FactoryRegistry.resolve<User>('User')
+ * f.count(5).make()
+ * ```
+ */
+export declare const FactoryRegistry: {
+    register<T extends object>(name: string, factory: Factory<T>): void;
+    resolve<T extends object>(name: string): Factory<T>;
+    has(name: string): boolean;
+    unregister(name: string): boolean;
+    clear(): void;
+    names(): string[];
+};

package/dist/core/sequence.d.cts

@@ -0,0 +1,36 @@
+/** Info passed to closure-style sequence entries. */
+export interface SequenceInfo {
+    /** One-based count (index + 1). */
+    readonly count: number;
+    /** Zero-based index of this draw. */
+    readonly index: number;
+}
+/** An entry is either a literal patch or a function receiving the index info. */
+export type SequenceEntry<T> = Partial<T> | ((info: SequenceInfo) => Partial<T>);
+/**
+ * Cycle through a list of attribute patches across generated items.
+ *
+ * @example
+ * ```ts
+ * factory.sequence([{ role: 'admin' }, { role: 'editor' }]).count(4).make()
+ * // → admin, editor, admin, editor
+ *
+ * factory.sequence([({ index }) => ({ name: `User ${index}` })]).count(3).make()
+ * // → User 0, User 1, User 2
+ * ```
+ */
+export declare class Sequence<T extends object = object> {
+    private cursor;
+    private readonly entries;
+    constructor(entries: readonly SequenceEntry<T>[]);
+    /** Resolve the next patch, cycling when exhausted. */
+    next(): Partial<T>;
+    /** Reset the cursor to 0. */
+    reset(): this;
+    /** Current cursor position (zero-based). */
+    get currentIndex(): number;
+    /** Return a fresh sequence with the same entries but cursor reset. */
+    clone(): Sequence<T>;
+}
+/** Functional shorthand for `new Sequence(entries)`. */
+export declare function sequence<T extends object = object>(entries: readonly SequenceEntry<T>[]): Sequence<T>;

package/dist/core/sequence.d.ts

@@ -0,0 +1,36 @@
+/** Info passed to closure-style sequence entries. */
+export interface SequenceInfo {
+    /** One-based count (index + 1). */
+    readonly count: number;
+    /** Zero-based index of this draw. */
+    readonly index: number;
+}
+/** An entry is either a literal patch or a function receiving the index info. */
+export type SequenceEntry<T> = Partial<T> | ((info: SequenceInfo) => Partial<T>);
+/**
+ * Cycle through a list of attribute patches across generated items.
+ *
+ * @example
+ * ```ts
+ * factory.sequence([{ role: 'admin' }, { role: 'editor' }]).count(4).make()
+ * // → admin, editor, admin, editor
+ *
+ * factory.sequence([({ index }) => ({ name: `User ${index}` })]).count(3).make()
+ * // → User 0, User 1, User 2
+ * ```
+ */
+export declare class Sequence<T extends object = object> {
+    private cursor;
+    private readonly entries;
+    constructor(entries: readonly SequenceEntry<T>[]);
+    /** Resolve the next patch, cycling when exhausted. */
+    next(): Partial<T>;
+    /** Reset the cursor to 0. */
+    reset(): this;
+    /** Current cursor position (zero-based). */
+    get currentIndex(): number;
+    /** Return a fresh sequence with the same entries but cursor reset. */
+    clone(): Sequence<T>;
+}
+/** Functional shorthand for `new Sequence(entries)`. */
+export declare function sequence<T extends object = object>(entries: readonly SequenceEntry<T>[]): Sequence<T>;

package/dist/core/types.d.cts

@@ -0,0 +1,47 @@
+import { Faker } from '../faker';
+/** Context passed to definition + state callbacks. */
+export interface BuildContext {
+    /** Shared faker instance — already seeded if the factory was. */
+    readonly faker: Faker;
+    /** One-based item index for this build. */
+    readonly seq: number;
+}
+/** Factory definition: returns the base attributes for a single item. */
+export type Definition<T> = (ctx: BuildContext) => T;
+/** State function: returns an attribute patch to merge over the base. */
+export type StateFn<T> = (attrs: T, ctx: BuildContext) => Partial<T>;
+/** State value — either an inline patch or a function returning one. */
+export type StateValue<T> = Partial<T> | StateFn<T>;
+/** Persistence callback used by `create()`. */
+export type Persist<T> = (item: T) => T | Promise<T>;
+/** Lifecycle hook — may be sync or async. */
+export type Hook<T> = (item: T, index: number) => void | Promise<void>;
+/** Relation descriptor for `has()`. */
+export interface HasRelation<P, C> {
+    readonly count: number;
+    readonly factory: {
+        make(): C[];
+    } & {
+        count(n: number): {
+            make(): C[];
+        };
+    };
+    readonly key: keyof P | string;
+    readonly kind: 'has';
+}
+/** Relation descriptor for `hasAttached()`. */
+export interface HasAttachedRelation<P, C> {
+    readonly count: number;
+    readonly factory: {
+        make(): C[];
+    } & {
+        count(n: number): {
+            make(): C[];
+        };
+    };
+    readonly key: keyof P | string;
+    readonly kind: 'hasAttached';
+    readonly pivot: Partial<Record<string, unknown>> | ((parent: P, child: C) => Record<string, unknown>);
+}
+/** Pool of recyclable model instances, keyed by an arbitrary string. */
+export type RecyclePool = ReadonlyMap<string, readonly object[]>;

package/dist/core/types.d.ts

@@ -0,0 +1,47 @@
+import { Faker } from '../faker';
+/** Context passed to definition + state callbacks. */
+export interface BuildContext {
+    /** Shared faker instance — already seeded if the factory was. */
+    readonly faker: Faker;
+    /** One-based item index for this build. */
+    readonly seq: number;
+}
+/** Factory definition: returns the base attributes for a single item. */
+export type Definition<T> = (ctx: BuildContext) => T;
+/** State function: returns an attribute patch to merge over the base. */
+export type StateFn<T> = (attrs: T, ctx: BuildContext) => Partial<T>;
+/** State value — either an inline patch or a function returning one. */
+export type StateValue<T> = Partial<T> | StateFn<T>;
+/** Persistence callback used by `create()`. */
+export type Persist<T> = (item: T) => T | Promise<T>;
+/** Lifecycle hook — may be sync or async. */
+export type Hook<T> = (item: T, index: number) => void | Promise<void>;
+/** Relation descriptor for `has()`. */
+export interface HasRelation<P, C> {
+    readonly count: number;
+    readonly factory: {
+        make(): C[];
+    } & {
+        count(n: number): {
+            make(): C[];
+        };
+    };
+    readonly key: keyof P | string;
+    readonly kind: 'has';
+}
+/** Relation descriptor for `hasAttached()`. */
+export interface HasAttachedRelation<P, C> {
+    readonly count: number;
+    readonly factory: {
+        make(): C[];
+    } & {
+        count(n: number): {
+            make(): C[];
+        };
+    };
+    readonly key: keyof P | string;
+    readonly kind: 'hasAttached';
+    readonly pivot: Partial<Record<string, unknown>> | ((parent: P, child: C) => Record<string, unknown>);
+}
+/** Pool of recyclable model instances, keyed by an arbitrary string. */
+export type RecyclePool = ReadonlyMap<string, readonly object[]>;

package/dist/faker/color.d.cts

@@ -0,0 +1,22 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Color generators.
+ *
+ * @example
+ * ```ts
+ * faker.color.name()    // "amber"
+ * faker.color.hex()     // "#3f8ad5"
+ * faker.color.rgb()     // "rgb(63, 138, 213)"
+ * faker.color.hsl()     // "hsl(217, 64%, 54%)"
+ * ```
+ */
+export declare class Color {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    name(): string;
+    hex(): string;
+    rgb(): string;
+    hsl(): string;
+}

package/dist/faker/color.d.ts

@@ -0,0 +1,22 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Color generators.
+ *
+ * @example
+ * ```ts
+ * faker.color.name()    // "amber"
+ * faker.color.hex()     // "#3f8ad5"
+ * faker.color.rgb()     // "rgb(63, 138, 213)"
+ * faker.color.hsl()     // "hsl(217, 64%, 54%)"
+ * ```
+ */
+export declare class Color {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    name(): string;
+    hex(): string;
+    rgb(): string;
+    hsl(): string;
+}

package/dist/faker/commerce.d.cts

@@ -0,0 +1,21 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Commerce generators.
+ *
+ * @example
+ * ```ts
+ * faker.commerce.productName()   // "Bamboo Notebook"
+ * faker.commerce.price()         // 24.99
+ * faker.commerce.department()    // "Electronics"
+ * ```
+ */
+export declare class Commerce {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    productName(): string;
+    department(): string;
+    price(min?: number, max?: number, decimals?: number): number;
+    productDescription(): string;
+}

package/dist/faker/commerce.d.ts

@@ -0,0 +1,21 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Commerce generators.
+ *
+ * @example
+ * ```ts
+ * faker.commerce.productName()   // "Bamboo Notebook"
+ * faker.commerce.price()         // 24.99
+ * faker.commerce.department()    // "Electronics"
+ * ```
+ */
+export declare class Commerce {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    productName(): string;
+    department(): string;
+    price(min?: number, max?: number, decimals?: number): number;
+    productDescription(): string;
+}

package/dist/faker/company.d.cts

@@ -0,0 +1,20 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Company / employment generators.
+ *
+ * @example
+ * ```ts
+ * faker.company.name()        // "Stark Industries"
+ * faker.company.jobTitle()    // "Frontend Developer"
+ * faker.company.buzzPhrase()  // "leverage cross-platform synergies"
+ * ```
+ */
+export declare class Company {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    name(): string;
+    jobTitle(): string;
+    buzzPhrase(): string;
+}

package/dist/faker/company.d.ts

@@ -0,0 +1,20 @@
+import { Prng } from '../prng/types';
+import { LocaleRef } from './locale';
+/**
+ * Company / employment generators.
+ *
+ * @example
+ * ```ts
+ * faker.company.name()        // "Stark Industries"
+ * faker.company.jobTitle()    // "Frontend Developer"
+ * faker.company.buzzPhrase()  // "leverage cross-platform synergies"
+ * ```
+ */
+export declare class Company {
+    private readonly rng;
+    private readonly locale;
+    constructor(rng: Prng, locale: LocaleRef);
+    name(): string;
+    jobTitle(): string;
+    buzzPhrase(): string;
+}

package/dist/faker/datatype.d.cts

@@ -0,0 +1,16 @@
+import { Prng } from '../prng/types';
+/**
+ * Primitive datatype generators.
+ *
+ * @example
+ * ```ts
+ * faker.datatype.boolean()        // true or false
+ * faker.datatype.boolean(0.8)     // true with 80% probability
+ * ```
+ */
+export declare class Datatype {
+    private readonly rng;
+    constructor(rng: Prng);
+    /** Boolean with probability `chance` of `true` (default 0.5). */
+    boolean(chance?: number): boolean;
+}

package/dist/faker/datatype.d.ts

@@ -0,0 +1,16 @@
+import { Prng } from '../prng/types';
+/**
+ * Primitive datatype generators.
+ *
+ * @example
+ * ```ts
+ * faker.datatype.boolean()        // true or false
+ * faker.datatype.boolean(0.8)     // true with 80% probability
+ * ```
+ */
+export declare class Datatype {
+    private readonly rng;
+    constructor(rng: Prng);
+    /** Boolean with probability `chance` of `true` (default 0.5). */
+    boolean(chance?: number): boolean;
+}

package/dist/faker/date.d.cts

@@ -0,0 +1,29 @@
+import { Prng } from '../prng/types';
+/**
+ * Date / time generators.
+ *
+ * @example
+ * ```ts
+ * faker.date.past()            // a Date in the last 365 days
+ * faker.date.recent(30)        // last 30 days
+ * faker.date.future(60)        // next 60 days
+ * faker.date.between(a, b)
+ * faker.date.birthdate({ min: 18, max: 65 })
+ * ```
+ */
+export declare class DateGen {
+    private readonly rng;
+    constructor(rng: Prng);
+    past(days?: number): Date;
+    recent(days?: number): Date;
+    future(days?: number): Date;
+    soon(days?: number): Date;
+    between(from: Date, to: Date): Date;
+    /** ISO-8601 string of a random recent date. */
+    iso(days?: number): string;
+    /** A plausible birthdate for someone in `[min, max]` years old. */
+    birthdate(opts?: {
+        max?: number;
+        min?: number;
+    }): Date;
+}

package/dist/faker/date.d.ts

@@ -0,0 +1,29 @@
+import { Prng } from '../prng/types';
+/**
+ * Date / time generators.
+ *
+ * @example
+ * ```ts
+ * faker.date.past()            // a Date in the last 365 days
+ * faker.date.recent(30)        // last 30 days
+ * faker.date.future(60)        // next 60 days
+ * faker.date.between(a, b)
+ * faker.date.birthdate({ min: 18, max: 65 })
+ * ```
+ */
+export declare class DateGen {
+    private readonly rng;
+    constructor(rng: Prng);
+    past(days?: number): Date;
+    recent(days?: number): Date;
+    future(days?: number): Date;
+    soon(days?: number): Date;
+    between(from: Date, to: Date): Date;
+    /** ISO-8601 string of a random recent date. */
+    iso(days?: number): string;
+    /** A plausible birthdate for someone in `[min, max]` years old. */
+    birthdate(opts?: {
+        max?: number;
+        min?: number;
+    }): Date;
+}

package/dist/faker/faker.d.cts

@@ -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;