@c9up/atlas 0.2.0 → 0.2.2

package/src/testing/Factory.ts

@@ -19,6 +19,7 @@ import type { BaseEntity } from "../BaseEntity.js";
 import { BaseRepository, type DatabaseConnection } from "../BaseRepository.js";
 import { getPrimaryKey, getRelationMetadata } from "../decorators/entity.js";
 import { getConnection } from "../services/db.js";
+import { transaction } from "../Transaction.js";
 
 type EntityConstructor<T extends BaseEntity> = new () => T;
 
@@ -33,19 +34,51 @@ interface WithRequest {
 }
 
 /**
- * Context handed to the `define` callback (Adonis Lucid parity). Currently just
- * a Faker instance for generating fake data. A callback that takes no argument
- * keeps working — it simply ignores the context.
+ * Per-factory internals reached across factory closures to support NESTED
+ * `.with()` (Adonis Lucid: `post.with('comments', 5)` inside a parent's `.with`
+ * callback). Kept off the public {@link FactoryBuilder} type and keyed by the
+ * builder object in a {@link WeakMap} — no `any`/cast, no leaked API surface.
+ */
+interface FactoryInternals {
+	/** Take and clear the queued `.with()` requests (before a `make` clears them). */
+	consumeWith(): WithRequest[];
+	/** Take and clear the queued m2m `.pivotAttributes()` (set in a `.with` callback). */
+	consumePivot():
+		| Record<string, unknown>
+		| Array<Record<string, unknown>>
+		| undefined;
+	/** Persist this factory's `.with()` relations onto an already-created parent. */
+	applyRelations(
+		parent: BaseEntity,
+		reqs: WithRequest[],
+		db: DatabaseConnection,
+		recursive?: Record<string, unknown>,
+	): Promise<void>;
+}
+
+const factoryInternals = new WeakMap<object, FactoryInternals>();
+
+/**
+ * Runtime context handed to the factory callbacks (Adonis Lucid parity):
+ * `faker` for fake data, `isStubbed` (true during a `makeStubbed*` build), and
+ * `$trx` — the bound transaction/connection, if any, so a hook's own DB queries
+ * commit/roll back alongside the factory. A callback that ignores it keeps
+ * working.
  */
 export interface FactoryContext {
 	faker: Faker;
+	isStubbed: boolean;
+	$trx?: DatabaseConnection;
 }
 
 /** Attributes callback — receives {@link FactoryContext}, returns the row shape. */
 type DefaultsFn = (ctx: FactoryContext) => Record<string, unknown>;
 
-/** A named state — mutates an in-progress data object in place. */
-type StateFn<D> = (data: D) => void;
+/**
+ * A named state — mutates the built model INSTANCE (Adonis Lucid: states receive
+ * the instance + runtime context, not a raw data object).
+ */
+type StateFn<T extends BaseEntity> = (model: T, ctx: FactoryContext) => void;
 
 /**
  * Process-wide counter for stubbed primary keys (Lucid's stub id). Every
@@ -55,6 +88,13 @@ type StateFn<D> = (data: D) => void;
  */
 let stubIdCounter = 0;
 
+/**
+ * Global stub-id generator override (Adonis Lucid `Factory.stubId`). Set via
+ * {@link Factory.stubId} when models use non-integer primary keys (uuid, etc.);
+ * receives the running counter and the instance, returns the id to assign.
+ */
+let globalStubId: ((counter: number, model: BaseEntity) => unknown) | undefined;
+
 /** Keys that must never be written through a recursive merge — prototype-pollution guard. */
 const FORBIDDEN_MERGE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
@@ -85,9 +125,31 @@ function deepMerge(
 	return out;
 }
 
+/**
+ * A `merge` callback (Adonis Lucid) — receives the built model INSTANCE, the
+ * resolved attributes, and the runtime context, e.g.
+ * `.merge((user, attributes) => { user.merge(attributes) })`.
+ */
+type MergeFn<T extends BaseEntity> = (
+	model: T,
+	attributes: Record<string, unknown>,
+	ctx: FactoryContext,
+) => void;
+
 export interface FactoryBuilder<T extends BaseEntity> {
-	/** Override specific fields for the next call (reset after consumption). */
-	merge(overrides: Partial<Record<string, unknown>>): FactoryBuilder<T>;
+	/**
+	 * Override specific fields for the next call (reset after consumption). Pass an
+	 * object to shallow-merge, a CALLBACK to mutate the resolved attributes
+	 * imperatively (Adonis Lucid `merge`), or an ARRAY to override per row on
+	 * `makeMany`/`createMany` — `merge([{a:1},{a:2}]).createMany(2)` applies index
+	 * `i` to row `i` (rows past the array length keep the plain defaults).
+	 */
+	merge(
+		overrides:
+			| Partial<Record<string, unknown>>
+			| MergeFn<T>
+			| Array<Partial<Record<string, unknown>>>,
+	): FactoryBuilder<T>;
 
 	/**
 	 * Like {@link merge} but deep — nested plain objects are merged key by key
@@ -98,8 +160,12 @@ export interface FactoryBuilder<T extends BaseEntity> {
 		overrides: Partial<Record<string, unknown>>,
 	): FactoryBuilder<T>;
 
-	/** Declare a named variation of this factory, stored on the factory's state map. */
-	state(name: string, fn: StateFn<Record<string, unknown>>): FactoryBuilder<T>;
+	/**
+	 * Declare a named variation. The callback receives the built model INSTANCE
+	 * and the runtime context (Adonis Lucid `state`), e.g.
+	 * `.state('admin', (user) => { user.role = 'admin' })`.
+	 */
+	state(name: string, fn: StateFn<T>): FactoryBuilder<T>;
 
 	/**
 	 * Activate one or more declared states for the NEXT build. Multiple applies
@@ -135,11 +201,17 @@ export interface FactoryBuilder<T extends BaseEntity> {
 	/** Create and persist multiple entities (fires hooks per row). */
 	createMany(count: number, db?: DatabaseConnection): Promise<T[]>;
 
-	/** Build the data object without persisting and without instantiating an entity. */
-	make(): Record<string, unknown>;
+	/**
+	 * Build an entity INSTANCE without persisting it (Adonis Lucid `make`). The
+	 * instance has NO primary key and `$isPersisted === false` — use it to
+	 * exercise model logic (computed props, validation) with no DB round trip.
+	 * For an instance that looks persisted (stub id, `$isPersisted === true`),
+	 * use {@link makeStubbed}.
+	 */
+	make(): T;
 
-	/** Build multiple data objects without persisting. */
-	makeMany(count: number): Record<string, unknown>[];
+	/** Build many un-persisted instances (Adonis Lucid `makeMany`). */
+	makeMany(count: number): T[];
 
 	/**
 	 * Build an entity INSTANCE without persisting it (Lucid's `makeStubbed`).
@@ -162,12 +234,10 @@ export interface FactoryBuilder<T extends BaseEntity> {
 	/**
 	 * Queue related rows to create together with the next `create`/`createMany`
 	 * (Adonis Lucid `.with`). `count` defaults to 1 (ignored past 1 for hasOne).
-	 * The callback receives the related factory to customize it (`merge`/`apply`).
-	 *
-	 * One level deep: the related rows are persisted through the parent's
-	 * relation proxy (which wires the FK / pivot), so a nested `.with()` on the
-	 * callback's factory is not itself applied. `.with()` runs on persistence
-	 * only — `make`/`makeStubbed` ignore it.
+	 * The callback receives the related factory to customize it — `merge`/`apply`,
+	 * `.pivotAttributes()` for m2m pivot columns, and its own nested `.with()`
+	 * (arbitrarily deep, Adonis Lucid nested factories). `.with()` runs on
+	 * persistence only — `make`/`makeStubbed` ignore it.
 	 */
 	with(
 		name: string,
@@ -176,13 +246,76 @@ export interface FactoryBuilder<T extends BaseEntity> {
 	): FactoryBuilder<T>;
 
 	/**
-	 * Register a callback that runs on the built entity INSTANCE before it is
-	 * persisted (Adonis Lucid `.tap`). Multiple taps run in order. Applies to the
-	 * instance-producing paths — `create`/`createMany`/`makeStubbed`/
-	 * `makeStubbedMany` — and is reset after consumption; `make`/`makeMany`
-	 * return plain data, so they ignore it.
+	 * Register a callback that runs on the built entity INSTANCE (Adonis Lucid
+	 * `.tap`). Receives the model, the runtime {@link FactoryContext}, and this
+	 * factory builder. Multiple taps run in order, on every instance-producing
+	 * path (`make`/`makeMany`/`create`/`createMany`/`makeStubbed*`); reset after
+	 * consumption.
+	 */
+	tap(
+		fn: (model: T, ctx: FactoryContext, builder: FactoryBuilder<T>) => void,
+	): FactoryBuilder<T>;
+
+	/**
+	 * Replace the default `new Model()` instantiation (Adonis Lucid `.newUp`).
+	 * The callback receives the resolved attributes and the runtime context and
+	 * returns the model instance to use for every subsequent build.
+	 */
+	newUp(
+		fn: (attributes: Record<string, unknown>, ctx: FactoryContext) => T,
+	): FactoryBuilder<T>;
+
+	/**
+	 * Set pivot columns for the NEXT many-to-many `.with()` link (Adonis Lucid
+	 * `.pivotAttributes`). Called on the RELATED factory inside a `.with()`
+	 * callback; the values are written on the pivot row alongside the link. A
+	 * single object applies to every linked row; pass an ARRAY for different
+	 * values per row (its length should match the related-row count).
+	 */
+	pivotAttributes(
+		attrs: Record<string, unknown> | Array<Record<string, unknown>>,
+	): FactoryBuilder<T>;
+
+	/**
+	 * Bind the connection/transaction for subsequent `create`/`createMany` via an
+	 * options object (Adonis Lucid `.query({ client }) / .query({ connection })`).
+	 * Sugar over {@link client} / {@link connection}; `client` wins over `connection`.
+	 */
+	query(options: {
+		client?: DatabaseConnection;
+		connection?: string;
+	}): FactoryBuilder<T>;
+
+	/**
+	 * Register a lifecycle hook that runs BEFORE the given event (Adonis Lucid
+	 * factory `before`). `create` fires before the INSERT; `makeStubbed` fires
+	 * before the stub is finalised (so it can assign the primary key). The
+	 * callback receives the factory and the model instance. Persistent (declared
+	 * once, applies to every build).
+	 */
+	before(
+		event: "create" | "makeStubbed",
+		callback: (
+			factory: FactoryBuilder<T>,
+			model: T,
+			ctx: FactoryContext,
+		) => void,
+	): FactoryBuilder<T>;
+
+	/**
+	 * Register a lifecycle hook that runs AFTER the given event (Adonis Lucid
+	 * factory `after`). `create` fires after the INSERT; `makeStubbed` after the
+	 * stub is built. `make` fires after an un-persisted `make`/`makeMany` instance
+	 * is built and tapped (Adonis Lucid `after('make')`). Persistent.
 	 */
-	tap(fn: (entity: T) => void): FactoryBuilder<T>;
+	after(
+		event: "make" | "create" | "makeStubbed",
+		callback: (
+			factory: FactoryBuilder<T>,
+			model: T,
+			ctx: FactoryContext,
+		) => void,
+	): FactoryBuilder<T>;
 }
 
 /**
@@ -193,14 +326,47 @@ export interface FactoryBuilder<T extends BaseEntity> {
  *       name: 'Test User',
  *     }))
  */
+/**
+ * Adonis Lucid `Factory.define(Model, callback).build()` entry point. `define`
+ * captures the model and its defaults; `build()` returns the usable factory
+ * builder. Equivalent to the one-call {@link factory} shorthand, which stays.
+ *
+ *     const UserFactory = Factory.define(User, ({ faker }) => ({
+ *       email: faker.internet.email(),
+ *     })).build()
+ */
+export const Factory = {
+	define<T extends BaseEntity>(
+		entityClass: EntityConstructor<T>,
+		defaults: DefaultsFn,
+	): { build(): FactoryBuilder<T> } {
+		return { build: () => factory(entityClass, defaults) };
+	},
+
+	/**
+	 * Override the global stub-id generator (Adonis Lucid `Factory.stubId`). Use
+	 * when your models have non-integer primary keys — the callback receives the
+	 * running counter and the instance and returns the id to assign. Pass
+	 * `null`/nothing to restore the default incrementing integer.
+	 */
+	stubId(generator?: ((counter: number, model: BaseEntity) => unknown) | null) {
+		globalStubId = generator ?? undefined;
+	},
+};
+
 export function factory<T extends BaseEntity>(
 	entityClass: EntityConstructor<T>,
 	defaults: DefaultsFn,
 ): FactoryBuilder<T> {
 	// Persistent state — lives across calls.
-	const states = new Map<string, StateFn<Record<string, unknown>>>();
+	const states = new Map<string, StateFn<T>>();
 	// Transient state — resets after every `make`/`create`.
 	let pendingOverrides: Partial<Record<string, unknown>> = {};
+	// Per-row overrides from `merge([...])`, applied by row index on makeMany/createMany.
+	let pendingOverridesList: Array<Partial<Record<string, unknown>>> | undefined;
+	// `merge(callback)` mutators, applied on the built INSTANCE (with the resolved
+	// attributes) after instantiation, in call order.
+	let pendingMergeFns: MergeFn<T>[] = [];
 	// Recursive overrides are kept apart from the shallow `pendingOverrides`
 	// because they must deep-merge into `defaults()`, which only exists at build
 	// time — a shallow spread here would clobber a whole nested object.
@@ -212,7 +378,22 @@ export function factory<T extends BaseEntity>(
 	const relations = new Map<string, RelationResolver>();
 	let pendingWith: WithRequest[] = [];
 	// Transient `.tap()` callbacks run on the built instance before persistence.
-	let pendingTap: Array<(entity: T) => void> = [];
+	// Adonis Lucid passes the model, the runtime context, and the factory builder.
+	let pendingTap: Array<
+		(model: T, ctx: FactoryContext, builder: FactoryBuilder<T>) => void
+	> = [];
+	// Transient pivot columns for the NEXT m2m `.with()` link (Adonis Lucid
+	// `.pivotAttributes()`), read by the parent factory's applyRelations. A single
+	// object applies to every linked row; an array sets per-row values.
+	let pendingPivot:
+		| Record<string, unknown>
+		| Array<Record<string, unknown>>
+		| undefined;
+	// Persistent custom instantiation (Adonis Lucid `.newUp`) — replaces
+	// `new Model() + setProp` when set.
+	let customNewUp:
+		| ((attributes: Record<string, unknown>, ctx: FactoryContext) => T)
+		| undefined;
 	// Persistent connection bound via `.client()`/`.connection()`, used when
 	// create()/createMany() are called without an explicit `db`.
 	let boundClient: DatabaseConnection | undefined;
@@ -228,12 +409,34 @@ export function factory<T extends BaseEntity>(
 		return conn;
 	};
 
+	// Persistent lifecycle hooks (Adonis Lucid factory before/after), by event.
+	type Hook = (
+		factory: FactoryBuilder<T>,
+		model: T,
+		ctx: FactoryContext,
+	) => void;
+	const beforeHooks: Record<"create" | "makeStubbed", Hook[]> = {
+		create: [],
+		makeStubbed: [],
+	};
+	// `make` has no `before` counterpart in Lucid (nothing to gate before an
+	// un-persisted build), so it lives on the after-side only.
+	const afterHooks: Record<"make" | "create" | "makeStubbed", Hook[]> = {
+		make: [],
+		create: [],
+		makeStubbed: [],
+	};
+
 	// Primary-key property, resolved once, for stub-id assignment. Same fallback
 	// as BaseRepository so a model without an explicit `@PrimaryKey` uses `id`.
 	const primaryKey = getPrimaryKey(entityClass) ?? "id";
 
-	/** Hydrate a fresh (not-yet-persisted) instance from a data object. */
-	const newInstance = (data: Record<string, unknown>): T => {
+	/** Hydrate a fresh (not-yet-persisted) instance — or defer to `.newUp` when set. */
+	const newInstance = (
+		data: Record<string, unknown>,
+		ctx: FactoryContext,
+	): T => {
+		if (customNewUp) return customNewUp(data, ctx);
 		const entity = new entityClass();
 		for (const [key, value] of Object.entries(data)) {
 			entity.setProp(key, value);
@@ -241,47 +444,137 @@ export function factory<T extends BaseEntity>(
 		return entity;
 	};
 
+	/** Run every tap with the Lucid `(model, ctx, builder)` signature. */
+	const runTaps = (
+		taps: Array<
+			(model: T, ctx: FactoryContext, builder: FactoryBuilder<T>) => void
+		>,
+		entity: T,
+		ctx: FactoryContext,
+	): void => {
+		for (const tap of taps) tap(entity, ctx, builder);
+	};
+
 	/** Build a stubbed instance: hydrate, run taps, give it a stub id if none was
 	 * supplied, then mark persisted so it mirrors a fetched row. Taps run before
 	 * `markAsPersisted` so tapped fields land in the clean snapshot. */
+	/** Build the runtime context for a build (Adonis Lucid factory `ctx`). */
+	const makeCtx = (isStubbed: boolean): FactoryContext => ({
+		faker,
+		isStubbed,
+		$trx: boundClient,
+	});
+
 	const stub = (
 		data: Record<string, unknown>,
-		taps: Array<(entity: T) => void>,
+		taps: Array<
+			(model: T, ctx: FactoryContext, builder: FactoryBuilder<T>) => void
+		>,
+		mergeFns: MergeFn<T>[],
+		stateNames: string[],
+		ctx: FactoryContext,
 	): T => {
-		const entity = newInstance(data);
-		for (const tap of taps) tap(entity);
-		if (data[primaryKey] === undefined) {
-			entity.setProp(primaryKey, ++stubIdCounter);
+		const entity = newInstance(data, ctx);
+		applyMergeFns(entity, data, mergeFns, ctx);
+		applyStates(entity, stateNames, ctx);
+		runTaps(taps, entity, ctx);
+		// before('makeStubbed') runs BEFORE the stub id, so a hook can set the PK.
+		for (const hook of beforeHooks.makeStubbed) hook(builder, entity, ctx);
+		// Assign a stub id only when neither the data NOR a before hook set the PK.
+		// A global `Factory.stubId` override generates it (uuid, etc.) when set.
+		if (entity[primaryKey] === undefined) {
+			const next = ++stubIdCounter;
+			entity.setProp(
+				primaryKey,
+				globalStubId ? globalStubId(next, entity) : next,
+			);
 		}
 		entity.markAsPersisted();
+		for (const hook of afterHooks.makeStubbed) hook(builder, entity, ctx);
 		return entity;
 	};
 
-	const buildData = (): Record<string, unknown> => {
+	const buildData = (
+		ctx: FactoryContext,
+		index = 0,
+	): Record<string, unknown> => {
 		let data: Record<string, unknown> = {
-			...defaults({ faker }),
+			...defaults(ctx),
 			...pendingOverrides,
+			// Per-row array overrides (merge([...])) win over the shared object.
+			...(pendingOverridesList?.[index] ?? {}),
 		};
 		// Deep overrides layer on top of the shallow one so nested defaults survive.
 		if (Object.keys(pendingRecursive).length > 0) {
 			data = deepMerge(data, pendingRecursive);
 		}
-		for (const name of pendingStates) {
+		return data;
+	};
+
+	/**
+	 * Run `merge(callback)` mutators on the built INSTANCE (Adonis Lucid passes the
+	 * model, the resolved attributes, and the context). Runs before states/taps.
+	 */
+	const applyMergeFns = (
+		entity: T,
+		attributes: Record<string, unknown>,
+		mergeFns: MergeFn<T>[],
+		ctx: FactoryContext,
+	): void => {
+		for (const fn of mergeFns) fn(entity, attributes, ctx);
+	};
+
+	/**
+	 * Run the named states on the built INSTANCE (Adonis Lucid). Separated from
+	 * {@link buildData} because states mutate the model, not the raw attributes.
+	 */
+	const applyStates = (
+		entity: T,
+		stateNames: string[],
+		ctx: FactoryContext,
+	): void => {
+		for (const name of stateNames) {
 			const fn = states.get(name);
-			if (!fn)
+			if (!fn) {
 				throw new Error(
 					`Factory state '${name}' is not defined on ${entityClass.name}Factory`,
 				);
-			fn(data);
+			}
+			fn(entity, ctx);
 		}
+	};
+
+	/** Build one raw row and clear transient state — the persistence paths
+	 * (`create`/`createMany`) need the plain object, not an instance. */
+	const consumeData = (ctx: FactoryContext): Record<string, unknown> => {
+		const data = buildData(ctx);
+		resetPending();
 		return data;
 	};
 
+	/** Build `count` raw rows (distinct faker/Date values per row), then reset. */
+	const consumeDataMany = (
+		count: number,
+		ctx: FactoryContext,
+	): Record<string, unknown>[] => {
+		const rows: Record<string, unknown>[] = [];
+		for (let i = 0; i < count; i++) rows.push(buildData(ctx, i));
+		resetPending();
+		return rows;
+	};
+
 	const resetPending = (): void => {
 		pendingOverrides = {};
+		pendingOverridesList = undefined;
+		pendingMergeFns = [];
 		pendingRecursive = {};
 		pendingStates = [];
 		pendingTap = [];
+		pendingPivot = undefined;
+		// Also clear queued relations, so `.with(...).make()` — which ignores
+		// relations — cannot leak them into the NEXT create() (create/createMany
+		// capture the queue before make() runs, so they are unaffected).
+		pendingWith = [];
 	};
 
 	/**
@@ -293,26 +586,77 @@ export function factory<T extends BaseEntity>(
 	const persist = async (
 		repo: BaseRepository<T>,
 		data: Record<string, unknown>,
-		taps: Array<(entity: T) => void>,
+		taps: Array<
+			(model: T, ctx: FactoryContext, builder: FactoryBuilder<T>) => void
+		>,
+		mergeFns: MergeFn<T>[],
+		stateNames: string[],
+		ctx: FactoryContext,
 	): Promise<T> => {
-		if (taps.length === 0) return repo.create(data);
-		const entity = newInstance(data);
-		for (const tap of taps) tap(entity);
+		if (
+			taps.length === 0 &&
+			mergeFns.length === 0 &&
+			stateNames.length === 0 &&
+			beforeHooks.create.length === 0 &&
+			afterHooks.create.length === 0 &&
+			!customNewUp
+		) {
+			return repo.create(data);
+		}
+		const entity = newInstance(data, ctx);
+		applyMergeFns(entity, data, mergeFns, ctx);
+		applyStates(entity, stateNames, ctx);
+		runTaps(taps, entity, ctx);
+		for (const hook of beforeHooks.create) hook(builder, entity, ctx);
 		await repo.save(entity);
+		for (const hook of afterHooks.create) hook(builder, entity, ctx);
 		return entity;
 	};
 
+	/**
+	 * Persist a parent and its queued `.with()` relations. With relations, the
+	 * whole graph runs in a managed transaction (Adonis Lucid: if a related write
+	 * fails the parent insert rolls back too); the parent is created through a
+	 * `useTransaction`-bound repo so its `related()` proxies also use the trx.
+	 * With no relations there's nothing to make atomic — a single insert already
+	 * is — so it stays on the plain connection.
+	 */
+	const persistWithRelations = async (
+		conn: DatabaseConnection,
+		withReqs: WithRequest[],
+		recursive: Record<string, unknown>,
+		build: (repo: BaseRepository<T>, ctx: FactoryContext) => Promise<T>,
+	): Promise<T> => {
+		if (withReqs.length === 0) {
+			// ctx.$trx is the connection actually used to persist (an explicit
+			// create(db) client, or the bound one) — not just the bound client.
+			return build(new BaseRepository(entityClass, conn), {
+				faker,
+				isStubbed: false,
+				$trx: conn,
+			});
+		}
+		return transaction(conn, async (trx) => {
+			const repo = new BaseRepository(entityClass, conn).useTransaction(trx);
+			const entity = await build(repo, { faker, isStubbed: false, $trx: trx });
+			await applyRelations(entity, withReqs, trx, recursive);
+			return entity;
+		});
+	};
+
 	/**
 	 * Persist the queued `.with()` relations for one just-created parent, routing
 	 * through the parent's relation proxy so the FK / pivot is wired by the
 	 * already-tested relation-write code (not re-derived here).
 	 */
 	const applyRelations = async (
-		parent: T,
+		parent: BaseEntity,
 		reqs: WithRequest[],
 		db: DatabaseConnection,
+		recursive?: Record<string, unknown>,
 	): Promise<void> => {
 		const meta = getRelationMetadata(entityClass);
+		const hasRecursive = recursive && Object.keys(recursive).length > 0;
 		for (const req of reqs) {
 			const relMeta = meta.find((r) => r.propertyKey === req.name);
 			if (!relMeta) {
@@ -327,23 +671,60 @@ export function factory<T extends BaseEntity>(
 				);
 			}
 			const childFactory = resolver();
+			// mergeRecursive cascades the SAME overrides onto every related factory
+			// (Adonis Lucid) — applied before the callback so an explicit merge in
+			// the callback still wins.
+			if (hasRecursive && recursive) childFactory.mergeRecursive(recursive);
 			if (req.callback) req.callback(childFactory);
+			const childInternals = factoryInternals.get(childFactory);
 
 			const proxy = parent.related(req.name);
+			if (proxy.type === "belongsTo") {
+				// FK lives on the parent: create() runs the owner's OWN with-graph,
+				// then associate re-saves the parent with the FK set.
+				const owner = await childFactory.create(db);
+				await proxy.associate(owner);
+				continue;
+			}
+
+			// The proxy-persisted branches bypass the child factory's create() path,
+			// so its queued nested `.with()` must be captured before make() clears it,
+			// then recursed onto each persisted child (Adonis Lucid nested factories:
+			// `post.with('comments', 5)` inside the callback).
+			const nestedWith = childInternals?.consumeWith() ?? [];
+			// Pivot columns from a `.pivotAttributes()` in the callback — captured
+			// now, before make() clears the child's transient state.
+			const nestedPivot = childInternals?.consumePivot();
+			const recurse = async (children: BaseEntity[]): Promise<void> => {
+				if (nestedWith.length === 0 || !childInternals) return;
+				for (const child of children) {
+					// Cascade the recursive overrides further down the graph.
+					await childInternals.applyRelations(child, nestedWith, db, recursive);
+				}
+			};
+
 			if (proxy.type === "hasMany") {
-				await proxy.createMany(childFactory.makeMany(req.count));
+				await recurse(await proxy.createMany(childFactory.makeMany(req.count)));
 			} else if (proxy.type === "hasOne") {
-				await proxy.create(childFactory.make());
+				await recurse([await proxy.create(childFactory.make())]);
 			} else if (proxy.type === "manyToMany") {
-				// The m2m proxy's create() inserts the related row AND the pivot link.
-				for (const row of childFactory.makeMany(req.count)) {
-					await proxy.create(row);
+				// The m2m proxy's create() inserts the related row AND the pivot link,
+				// with the `.pivotAttributes()` columns on the pivot row. An array of
+				// pivot attrs applies per-row (`pivot[i]`); a single object, to all.
+				const rows = childFactory.makeMany(req.count);
+				// Adonis Lucid: an array's length must match the related-row count —
+				// reject a mismatch rather than silently leave rows without pivot data.
+				if (Array.isArray(nestedPivot) && nestedPivot.length !== rows.length) {
+					throw new Error(
+						`Factory .with('${req.name}'): pivotAttributes array length (${nestedPivot.length}) must match the related-row count (${rows.length}).`,
+					);
+				}
+				for (let i = 0; i < rows.length; i++) {
+					const pivot = Array.isArray(nestedPivot)
+						? nestedPivot[i]
+						: nestedPivot;
+					await recurse([await proxy.create(rows[i], pivot)]);
 				}
-			} else if (proxy.type === "belongsTo") {
-				// FK lives on the parent: create the owner, then associate re-saves
-				// the parent with the FK set.
-				const owner = await childFactory.create(db);
-				await proxy.associate(owner);
 			} else {
 				throw new Error(
 					`Factory .with('${req.name}'): '${relMeta.type}' relations are not supported`,
@@ -354,7 +735,13 @@ export function factory<T extends BaseEntity>(
 
 	const builder: FactoryBuilder<T> = {
 		merge(overrides) {
-			pendingOverrides = { ...pendingOverrides, ...overrides };
+			if (typeof overrides === "function") {
+				pendingMergeFns.push(overrides);
+			} else if (Array.isArray(overrides)) {
+				pendingOverridesList = overrides;
+			} else {
+				pendingOverrides = { ...pendingOverrides, ...overrides };
+			}
 			return builder;
 		},
 
@@ -388,6 +775,31 @@ export function factory<T extends BaseEntity>(
 			return builder;
 		},
 
+		newUp(fn) {
+			customNewUp = fn;
+			return builder;
+		},
+
+		pivotAttributes(attrs) {
+			// An array (per-row values) replaces wholesale; objects merge (repeated
+			// `.pivotAttributes({...})` accumulate, matching the single-object case).
+			pendingPivot =
+				Array.isArray(attrs) || Array.isArray(pendingPivot)
+					? attrs
+					: { ...pendingPivot, ...attrs };
+			return builder;
+		},
+
+		before(event, callback) {
+			beforeHooks[event].push(callback);
+			return builder;
+		},
+
+		after(event, callback) {
+			afterHooks[event].push(callback);
+			return builder;
+		},
+
 		client(connection) {
 			boundClient = connection;
 			return builder;
@@ -404,19 +816,54 @@ export function factory<T extends BaseEntity>(
 			return builder;
 		},
 
+		query(options) {
+			if (options.client) {
+				boundClient = options.client;
+			} else if (options.connection) {
+				const conn = getConnection(options.connection);
+				if (!conn) {
+					throw new Error(
+						`Factory ${entityClass.name}: no connection registered under '${options.connection}'.`,
+					);
+				}
+				boundClient = conn;
+			}
+			return builder;
+		},
+
 		make() {
-			const data = buildData();
+			// Lucid `make`: an UN-persisted instance (no PK, `$isPersisted` false).
+			// Taps run on it, like the other instance-producing paths.
+			const taps = pendingTap;
+			const mergeFns = pendingMergeFns;
+			const stateNames = pendingStates;
+			const ctx = makeCtx(false);
+			const data = buildData(ctx);
+			const entity = newInstance(data, ctx);
+			applyMergeFns(entity, data, mergeFns, ctx);
+			applyStates(entity, stateNames, ctx);
+			runTaps(taps, entity, ctx);
+			for (const hook of afterHooks.make) hook(builder, entity, ctx);
 			resetPending();
-			return data;
+			return entity;
 		},
 
 		makeMany(count) {
 			// Re-evaluate defaults for each row so `Date.now()` / faker generate
-			// distinct values. `buildData()` reads (never mutates) the pending
-			// overrides/states, so they stay stable across iterations on their own.
-			const rows: Record<string, unknown>[] = [];
+			// distinct values, each hydrated into its own un-persisted instance.
+			const taps = pendingTap;
+			const mergeFns = pendingMergeFns;
+			const stateNames = pendingStates;
+			const ctx = makeCtx(false);
+			const rows: T[] = [];
 			for (let i = 0; i < count; i++) {
-				rows.push(buildData());
+				const data = buildData(ctx, i);
+				const entity = newInstance(data, ctx);
+				applyMergeFns(entity, data, mergeFns, ctx);
+				applyStates(entity, stateNames, ctx);
+				runTaps(taps, entity, ctx);
+				for (const hook of afterHooks.make) hook(builder, entity, ctx);
+				rows.push(entity);
 			}
 			resetPending();
 			return rows;
@@ -424,8 +871,10 @@ export function factory<T extends BaseEntity>(
 
 		makeStubbed() {
 			const taps = pendingTap;
-			const data = buildData();
-			const entity = stub(data, taps);
+			const mergeFns = pendingMergeFns;
+			const stateNames = pendingStates;
+			const ctx = makeCtx(true);
+			const entity = stub(buildData(ctx), taps, mergeFns, stateNames, ctx);
 			resetPending();
 			return entity;
 		},
@@ -434,45 +883,76 @@ export function factory<T extends BaseEntity>(
 			// Re-evaluate defaults per row (distinct Date.now()/faker values), same
 			// as makeMany; each row then gets its own stub id + taps via `stub`.
 			const taps = pendingTap;
+			const mergeFns = pendingMergeFns;
+			const stateNames = pendingStates;
+			const ctx = makeCtx(true);
 			const rows: T[] = [];
 			for (let i = 0; i < count; i++) {
-				rows.push(stub(buildData(), taps));
+				rows.push(stub(buildData(ctx, i), taps, mergeFns, stateNames, ctx));
 			}
 			resetPending();
 			return rows;
 		},
 
 		async create(db) {
-			const conn = resolveConnection(db);
-			// Capture + clear the relation/tap queues before make() (which resets
-			// pending state) so they aren't lost and a later create() starts clean.
+			// Capture + clear the relation/tap queues, then consume the raw data
+			// (which resets the rest of the pending state) — BEFORE resolveConnection,
+			// so a missing connection can't throw with pending overrides/states/with/
+			// tap still dirty and leak them into the next create().
 			const withReqs = pendingWith;
 			pendingWith = [];
 			const taps = pendingTap;
-			const data = builder.make();
-			const repo = new BaseRepository(entityClass, conn);
-			const entity = await persist(repo, data, taps);
-			if (withReqs.length > 0) await applyRelations(entity, withReqs, conn);
-			return entity;
+			const mergeFns = pendingMergeFns;
+			const stateNames = pendingStates;
+			// Snapshot the recursive overrides BEFORE consumeData resets them — they
+			// cascade onto every related factory (Adonis Lucid `mergeRecursive`).
+			const recursive = { ...pendingRecursive };
+			const ctx = makeCtx(false);
+			const data = consumeData(ctx);
+			const conn = resolveConnection(db);
+			return persistWithRelations(conn, withReqs, recursive, (repo, txCtx) =>
+				persist(repo, data, taps, mergeFns, stateNames, txCtx),
+			);
 		},
 
 		async createMany(count, db) {
-			const conn = resolveConnection(db);
 			const withReqs = pendingWith;
 			pendingWith = [];
 			const taps = pendingTap;
-			const rows = builder.makeMany(count);
-			const repo = new BaseRepository(entityClass, conn);
+			const mergeFns = pendingMergeFns;
+			const stateNames = pendingStates;
+			const recursive = { ...pendingRecursive };
+			const ctx = makeCtx(false);
+			const rows = consumeDataMany(count, ctx);
+			const conn = resolveConnection(db);
 			const created: T[] = [];
 			for (const data of rows) {
-				const entity = await persist(repo, data, taps);
-				// Each created parent gets its own related rows (Lucid semantics).
-				if (withReqs.length > 0) await applyRelations(entity, withReqs, conn);
-				created.push(entity);
+				// Each created parent + its relations are atomic (Lucid semantics).
+				created.push(
+					await persistWithRelations(conn, withReqs, recursive, (repo, txCtx) =>
+						persist(repo, data, taps, mergeFns, stateNames, txCtx),
+					),
+				);
 			}
 			return created;
 		},
 	};
 
+	// Register this builder's internals so a PARENT factory can drive nested
+	// `.with()` on it (kept off the public type, keyed by the builder object).
+	factoryInternals.set(builder, {
+		consumeWith() {
+			const reqs = pendingWith;
+			pendingWith = [];
+			return reqs;
+		},
+		consumePivot() {
+			const pivot = pendingPivot;
+			pendingPivot = undefined;
+			return pivot;
+		},
+		applyRelations,
+	});
+
 	return builder;
 }