@anil-labs/factory 0.1.0

package/dist/index.cjs

@@ -0,0 +1,635 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_faker = require("./chunks/faker-BOtDMmjd.cjs");
+const require_locales_en = require("./locales/en.cjs");
+const require_persist = require("./chunks/persist-DcARfeC-.cjs");
+//#region src/core/collection.ts
+/**
+* Immutable iterable wrapper around an array, with Laravel-style helpers.
+*
+* @example
+* ```ts
+* const users = new Collection(userArray)
+* users.where(u => u.active).count()
+* users.pluck('email').toArray()
+* for (const u of users) console.log(u.name)
+* ```
+*/
+var Collection = class Collection {
+	/** Underlying frozen items. */
+	items;
+	constructor(items = []) {
+		this.items = Object.freeze([...items]);
+	}
+	/** Number of items. */
+	count() {
+		return this.items.length;
+	}
+	/** True when there are no items. */
+	isEmpty() {
+		return this.items.length === 0;
+	}
+	/** Run `fn` for each item; returns the collection for chaining. */
+	each(fn) {
+		this.items.forEach(fn);
+		return this;
+	}
+	/** Project to a new collection via `fn`. */
+	map(fn) {
+		return new Collection(this.items.map(fn));
+	}
+	/** Pluck a single field across all items. */
+	pluck(key) {
+		return new Collection(this.items.map((item) => item[key]));
+	}
+	/** Filter to items matching `predicate`. */
+	where(predicate) {
+		return new Collection(this.items.filter(predicate));
+	}
+	/** First item matching predicate (or first overall if no predicate). */
+	first(predicate) {
+		if (!predicate) return this.items[0];
+		return this.items.find(predicate);
+	}
+	/** Last item in the collection. */
+	last() {
+		return this.items[this.items.length - 1];
+	}
+	/** Sort by a key or comparator, returning a new collection. */
+	sortBy(key, direction = "asc") {
+		return new Collection([...this.items].sort((a, b) => {
+			const av = a[key];
+			const bv = b[key];
+			if (av === bv) return 0;
+			const cmp = av < bv ? -1 : 1;
+			return direction === "asc" ? cmp : -cmp;
+		}));
+	}
+	/** Group items into a `Map` keyed by `fn`. */
+	groupBy(fn) {
+		const out = /* @__PURE__ */ new Map();
+		for (const item of this.items) {
+			const key = fn(item);
+			const bucket = out.get(key);
+			if (bucket) bucket.push(item);
+			else out.set(key, [item]);
+		}
+		return out;
+	}
+	/** Reduce to a single value. */
+	reduce(fn, initial) {
+		return this.items.reduce(fn, initial);
+	}
+	/** Plain-array view (a copy — the collection's storage is frozen). */
+	toArray() {
+		return [...this.items];
+	}
+	[Symbol.iterator]() {
+		return this.items[Symbol.iterator]();
+	}
+};
+//#endregion
+//#region src/core/sequence.ts
+/**
+* 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
+* ```
+*/
+var Sequence = class Sequence {
+	cursor = 0;
+	entries;
+	constructor(entries) {
+		if (entries.length === 0) throw new Error("[Sequence] At least one entry is required.");
+		this.entries = [...entries];
+	}
+	/** Resolve the next patch, cycling when exhausted. */
+	next() {
+		const entry = this.entries[this.cursor % this.entries.length] ?? (() => {
+			throw new Error("[Sequence] unreachable: empty entries");
+		})();
+		const info = {
+			index: this.cursor,
+			count: this.cursor + 1
+		};
+		this.cursor++;
+		return typeof entry === "function" ? entry(info) : entry;
+	}
+	/** Reset the cursor to 0. */
+	reset() {
+		this.cursor = 0;
+		return this;
+	}
+	/** Current cursor position (zero-based). */
+	get currentIndex() {
+		return this.cursor;
+	}
+	/** Return a fresh sequence with the same entries but cursor reset. */
+	clone() {
+		return new Sequence([...this.entries]);
+	}
+};
+/** Functional shorthand for `new Sequence(entries)`. */
+function sequence(entries) {
+	return new Sequence(entries);
+}
+//#endregion
+//#region src/core/factory.ts
+/**
+* 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()
+* ```
+*/
+var Factory = class Factory {
+	/** @internal */ definition;
+	/** @internal */ internals;
+	/** @internal — use {@link defineFactory} or {@link Factory.define} instead. */
+	constructor(definition, internals) {
+		this.definition = definition;
+		this.internals = internals;
+	}
+	/** Create a new factory. Mirrors Laravel's `Factory::new()`. */
+	static define(definition, persist) {
+		return new Factory(definition, {
+			faker: require_faker.faker,
+			count: 1,
+			overrides: {},
+			states: /* @__PURE__ */ new Map(),
+			activeStates: [],
+			sequences: [],
+			fieldSequences: /* @__PURE__ */ new Map(),
+			afterMaking: [],
+			afterCreating: [],
+			hasRelations: [],
+			hasAttachedRelations: [],
+			recycle: /* @__PURE__ */ new Map(),
+			persist: persist ?? null,
+			ownsFaker: false
+		});
+	}
+	/** Internal: build a copy with a single field replaced. */
+	clone(patch) {
+		const next = {
+			faker: this.internals.faker,
+			count: this.internals.count,
+			overrides: this.internals.overrides,
+			states: new Map(this.internals.states),
+			activeStates: [...this.internals.activeStates],
+			sequences: this.internals.sequences.map((s) => s.clone()),
+			fieldSequences: new Map(this.internals.fieldSequences),
+			afterMaking: [...this.internals.afterMaking],
+			afterCreating: [...this.internals.afterCreating],
+			hasRelations: [...this.internals.hasRelations],
+			hasAttachedRelations: [...this.internals.hasAttachedRelations],
+			recycle: new Map(this.internals.recycle),
+			persist: this.internals.persist,
+			ownsFaker: this.internals.ownsFaker,
+			...patch
+		};
+		return new Factory(this.definition, next);
+	}
+	/** Set how many items will be built on the next terminal call. */
+	count(n) {
+		if (!Number.isInteger(n) || n < 0) throw new Error(`[Factory] count(n): expected a non-negative integer, got ${String(n)}.`);
+		return this.clone({ count: n });
+	}
+	/** Alias of {@link count} — matches Laravel's `->times()`. */
+	times(n) {
+		return this.count(n);
+	}
+	/** Merge inline overrides into every built item. */
+	with(overrides) {
+		return this.clone({ overrides: {
+			...this.internals.overrides,
+			...overrides
+		} });
+	}
+	/**
+	* 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, value) {
+		if (arg1 instanceof Sequence) return this.clone({ sequences: [...this.internals.sequences, arg1.clone()] });
+		if (value !== void 0) {
+			const states = new Map(this.internals.states);
+			states.set(arg1, value);
+			return this.clone({ states });
+		}
+		if (!this.internals.states.has(arg1)) throw new Error(`[Factory] Unknown state "${arg1}". Register it first via .state("${arg1}", ...).`);
+		return this.clone({ activeStates: [...this.internals.activeStates, arg1] });
+	}
+	/** Bulk-register multiple states. */
+	states(map) {
+		const states = new Map(this.internals.states);
+		for (const [name, value] of Object.entries(map)) states.set(name, value);
+		return this.clone({ states });
+	}
+	/** Cycle values through one field across generated items. */
+	fieldSequence(field, values) {
+		const fieldSequences = new Map(this.internals.fieldSequences);
+		fieldSequences.set(field, values);
+		return this.clone({ fieldSequences });
+	}
+	/** Attach a sequence of attribute patches. */
+	sequence(entries) {
+		const seq = new Sequence(entries);
+		return this.clone({ sequences: [...this.internals.sequences, seq] });
+	}
+	/** Attach child records under `key` (one-to-many). */
+	has(childFactory, key) {
+		return this.clone({ hasRelations: [...this.internals.hasRelations, {
+			kind: "has",
+			factory: childFactory,
+			count: childFactory.internals.count,
+			key
+		}] });
+	}
+	/**
+	* 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(parent, foreignKey, resolver) {
+		let resolved;
+		if (typeof parent === "function") resolved = parent();
+		else if (parent instanceof Factory) resolved = parent.makeOne();
+		else resolved = parent;
+		const patch = resolver ? resolver(resolved) : { [foreignKey]: resolved["id"] };
+		return this.with(patch);
+	}
+	/** Attach related records with pivot/intermediate data (many-to-many). */
+	hasAttached(childFactory, key, pivot = {}) {
+		return this.clone({ hasAttachedRelations: [...this.internals.hasAttachedRelations, {
+			kind: "hasAttached",
+			factory: childFactory,
+			count: childFactory.internals.count,
+			key,
+			pivot
+		}] });
+	}
+	/** Add models to the recycle pool keyed by `key`. */
+	recycle(models, key) {
+		const list = Array.isArray(models) ? models : [models];
+		const next = new Map(this.internals.recycle);
+		next.set(key, list);
+		return this.clone({ recycle: next });
+	}
+	/** Pick a random recycled model from `key`, or undefined. */
+	getRecycled(key) {
+		const pool = this.internals.recycle.get(key);
+		if (!pool || pool.length === 0) return void 0;
+		return pool[this.internals.faker.rawPrng().int(0, pool.length - 1)];
+	}
+	/** Register a hook fired after each item is built. */
+	afterMaking(fn) {
+		return this.clone({ afterMaking: [...this.internals.afterMaking, fn] });
+	}
+	/** Register a hook fired after each item is persisted via `create()`. */
+	afterCreating(fn) {
+		return this.clone({ afterCreating: [...this.internals.afterCreating, fn] });
+	}
+	/** Set or replace the persistence callback used by `create()`. */
+	persist(fn) {
+		return this.clone({ persist: fn });
+	}
+	/**
+	* 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) {
+		const own = new require_faker.Faker({ seed });
+		return this.clone({
+			faker: own,
+			ownsFaker: true
+		});
+	}
+	/** Set the locale on this factory's faker (creates one if it was shared). */
+	locale(name) {
+		const own = this.internals.ownsFaker ? this.internals.faker : new require_faker.Faker({ seed: this.internals.faker.currentSeed() });
+		own.locale(name);
+		return this.clone({
+			faker: own,
+			ownsFaker: true
+		});
+	}
+	/** Build a single item (ignoring `count`). */
+	makeOne() {
+		const item = this.buildOne(0);
+		this.fireAfterMakingSync([item]);
+		return item;
+	}
+	/** Build `count` items. */
+	makeMany() {
+		const items = this.buildMany();
+		this.fireAfterMakingSync(items);
+		return items;
+	}
+	/**
+	* Build — single item when `count === 1`, array otherwise.
+	* Use {@link makeOne} / {@link makeMany} when you need a specific shape.
+	*/
+	make() {
+		return this.internals.count === 1 ? this.makeOne() : this.makeMany();
+	}
+	/** Raw attribute objects with the same shape as `make()`. */
+	raw() {
+		return this.make();
+	}
+	/** Build and return as a {@link Collection}. */
+	collect() {
+		return new Collection(this.makeMany());
+	}
+	/**
+	* Build and persist via the registered persistence callback.
+	* Returns single item when `count === 1`, array otherwise.
+	*/
+	async create() {
+		const persist = this.internals.persist;
+		if (!persist) throw new Error("[Factory] create(): no persistence callback registered. Use .persist(fn) or pass one to defineFactory().");
+		const items = this.buildMany();
+		await this.runHooks(items, this.internals.afterMaking);
+		const persisted = await Promise.all(items.map((item) => Promise.resolve(persist(item))));
+		await this.runHooks(persisted, this.internals.afterCreating);
+		return this.internals.count === 1 ? persisted[0] : persisted;
+	}
+	/** Always-array variant of {@link create}. */
+	async createMany() {
+		const result = await this.create();
+		return Array.isArray(result) ? result : [result];
+	}
+	buildOne(index) {
+		const ctx = {
+			seq: index + 1,
+			faker: this.internals.faker
+		};
+		let item = this.definition(ctx);
+		for (const stateName of this.internals.activeStates) {
+			const state = this.internals.states.get(stateName);
+			if (!state) continue;
+			item = {
+				...item,
+				...typeof state === "function" ? state(item, ctx) : state
+			};
+		}
+		for (const sequence of this.internals.sequences) item = {
+			...item,
+			...sequence.next()
+		};
+		for (const [field, values] of this.internals.fieldSequences) {
+			const value = values[index % values.length];
+			item = {
+				...item,
+				[field]: value
+			};
+		}
+		item = {
+			...item,
+			...this.internals.overrides
+		};
+		for (const rel of this.internals.hasRelations) {
+			const children = rel.factory.count(rel.count).make();
+			const arr = Array.isArray(children) ? children : [children];
+			item = {
+				...item,
+				[rel.key]: arr
+			};
+		}
+		for (const rel of this.internals.hasAttachedRelations) {
+			const children = rel.factory.count(rel.count).make();
+			const withPivot = (Array.isArray(children) ? children : [children]).map((child) => {
+				const pivotData = typeof rel.pivot === "function" ? rel.pivot(item, child) : rel.pivot;
+				return {
+					...child,
+					pivot: pivotData
+				};
+			});
+			item = {
+				...item,
+				[rel.key]: withPivot
+			};
+		}
+		return item;
+	}
+	buildMany() {
+		const out = [];
+		for (let i = 0; i < this.internals.count; i++) out.push(this.buildOne(i));
+		return out;
+	}
+	/**
+	* 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.
+	*/
+	fireAfterMakingSync(items) {
+		for (let i = 0; i < items.length; i++) {
+			const item = items[i];
+			if (item === void 0) continue;
+			for (const hook of this.internals.afterMaking) {
+				const r = hook(item, i);
+				if (r instanceof Promise) r.catch(swallow);
+			}
+		}
+	}
+	async runHooks(items, hooks) {
+		for (let i = 0; i < items.length; i++) {
+			const item = items[i];
+			if (item === void 0) continue;
+			for (const hook of hooks) await hook(item, i);
+		}
+	}
+};
+function swallow() {}
+/** Functional alias for `Factory.define()`. */
+function defineFactory(definition, persist) {
+	return Factory.define(definition, persist);
+}
+//#endregion
+//#region src/core/registry.ts
+/**
+* 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()
+* ```
+*/
+var FactoryRegistry = {
+	register(name, factory) {
+		registry.set(name, factory);
+	},
+	resolve(name) {
+		const f = registry.get(name);
+		if (!f) throw new Error(`[FactoryRegistry] No factory registered as "${name}". Registered: ${[...registry.keys()].join(", ")}`);
+		return f;
+	},
+	has(name) {
+		return registry.has(name);
+	},
+	unregister(name) {
+		return registry.delete(name);
+	},
+	clear() {
+		registry.clear();
+	},
+	names() {
+		return [...registry.keys()];
+	}
+};
+var registry = /* @__PURE__ */ new Map();
+//#endregion
+//#region src/builders/index.ts
+/**
+* Pick one value from `choices` at call time. Reads from the default faker.
+* Use inside factory definitions to express "any of these".
+*
+* @example
+* ```ts
+* defineFactory<User>(({ faker }) => ({
+*   role: oneOf(['admin', 'editor', 'viewer']),
+* }))
+* ```
+*/
+function oneOf(choices) {
+	return require_faker.faker.helpers.arrayElement(choices);
+}
+/**
+* Return `value` with probability `chance`, else `undefined`. Useful for
+* optional fields.
+*
+* @example
+* ```ts
+* { bio: maybe(faker.lorem.sentence(), 0.6) }
+* ```
+*/
+function maybe(value, chance = .5) {
+	return require_faker.faker.helpers.maybe(value, chance);
+}
+/**
+* Build an array of length `[min, max]` (inclusive) by calling `fn(index)`.
+* If only `min` is given, the length is exactly `min`.
+*
+* @example
+* ```ts
+* { tags: array(2, 5, () => faker.lorem.word()) }
+* ```
+*/
+function array(min, maxOrFn, fn) {
+	if (typeof maxOrFn === "function") return Array.from({ length: min }, (_, i) => maxOrFn(i));
+	if (!fn) throw new Error("[builders] array(min, max, fn): missing builder function.");
+	const length = require_faker.faker.helpers.arrayElement(Array.from({ length: maxOrFn - min + 1 }, (_, i) => min + i));
+	return Array.from({ length }, (_, i) => fn(i));
+}
+/**
+* Defer evaluation until the value is actually read. Inside factory
+* definitions you rarely need this (the definition is a function already),
+* but it's useful for sequence entries and state values.
+*/
+function lazy(fn) {
+	return { resolve: fn };
+}
+//#endregion
+//#region src/snapshot/index.ts
+/**
+* Snapshot helpers.
+*
+* The package doesn't write files itself — it just normalises payloads so
+* test runners (vitest, jest) can snapshot them deterministically.
+*
+* @example
+* ```ts
+* import { snapshot } from '@anil-labs/factory'
+*
+* const items = UserFactory.seed(42).count(3).make()
+* expect(snapshot(items)).toMatchSnapshot()
+* ```
+*/
+/** Recursively normalise dates, undefineds, and key order so snapshots are stable. */
+function snapshot(value) {
+	return normalise(value);
+}
+function normalise(value) {
+	if (value === null || value === void 0) return value;
+	if (value instanceof Date) return {
+		__type: "Date",
+		value: value.toISOString()
+	};
+	if (Array.isArray(value)) return value.map(normalise);
+	if (typeof value === "object") {
+		const out = {};
+		for (const key of Object.keys(value).sort()) out[key] = normalise(value[key]);
+		return out;
+	}
+	return value;
+}
+//#endregion
+exports.Collection = Collection;
+exports.Color = require_faker.Color;
+exports.Commerce = require_faker.Commerce;
+exports.Company = require_faker.Company;
+exports.Datatype = require_faker.Datatype;
+exports.DateGen = require_faker.DateGen;
+exports.Factory = Factory;
+exports.FactoryRegistry = FactoryRegistry;
+exports.Faker = require_faker.Faker;
+exports.Finance = require_faker.Finance;
+exports.Helpers = require_faker.Helpers;
+exports.Image = require_faker.Image;
+exports.Internet = require_faker.Internet;
+exports.LocaleRef = require_faker.LocaleRef;
+exports.Location = require_faker.Location;
+exports.Lorem = require_faker.Lorem;
+exports.Mulberry32 = require_faker.Mulberry32;
+exports.NumberGen = require_faker.NumberGen;
+exports.Person = require_faker.Person;
+exports.Sequence = Sequence;
+exports.StringGen = require_faker.StringGen;
+exports.System = require_faker.System;
+exports.array = array;
+exports.consolePersist = require_persist.consolePersist;
+exports.createPrng = require_faker.createPrng;
+exports.defineFactory = defineFactory;
+exports.en = require_locales_en.en;
+exports.faker = require_faker.faker;
+exports.generateFromRegex = require_faker.generateFromRegex;
+exports.getLocale = require_faker.getLocale;
+exports.httpPersist = require_persist.httpPersist;
+exports.lazy = lazy;
+exports.listLocales = require_faker.listLocales;
+exports.maybe = maybe;
+exports.memoryPersist = require_persist.memoryPersist;
+exports.oneOf = oneOf;
+exports.registerLocale = require_faker.registerLocale;
+exports.sequence = sequence;
+exports.snapshot = snapshot;
+
+//# sourceMappingURL=index.cjs.map