@geekmidas/testkit 10.0.0-alpha.4 → 10.0.0-alpha.40

package/README.md

@@ -54,6 +54,12 @@ import { itWithDir } from '@geekmidas/testkit/os';
 import { createMockContext, createMockV1Event, createMockV2Event } from '@geekmidas/testkit/aws';
 import { createMockLogger } from '@geekmidas/testkit/logger';
 import { memoryAdapter } from '@geekmidas/testkit/better-auth';
+
+// Feature tests: the primitives `@geekmidas/constructs/testing` builds on
+import { Browser } from '@geekmidas/testkit/browser';
+import { createMailbox } from '@geekmidas/testkit/mailbox';
+import { runInTestContext, installContextFetch } from '@geekmidas/testkit/context';
+import { TransactionRegistry } from '@geekmidas/testkit/transactions';
 ```
 
 ## Quick Start
@@ -321,6 +327,74 @@ describe('Authentication', () => {
 });
 ```
 
+## Feature Test Primitives
+
+The pieces a feature test is built from — a test that drives an app the way it
+runs deployed: a browser signs in, calls the API, the API calls the auth server,
+each over a URL, every database in a transaction that is rolled back. The wiring
+that knows about constructs lives in `@geekmidas/constructs/testing`; these know
+nothing about them.
+
+### `Browser`
+
+A `fetch` with a cookie jar that follows the browser's rules (RFC 6265): a
+`Set-Cookie` lands in the jar, and every later request to a URL the cookie
+belongs to carries it. Redirects are followed hop by hop, keeping each hop's
+cookies. Give it to an app's real clients:
+
+```typescript
+import { Browser as TestBrowser } from '@geekmidas/testkit/browser';
+
+export class Browser extends TestBrowser {
+  readonly api = createApi({ baseURL: process.env.API_URL, fetch: this.fetch });
+}
+
+const browser = new Browser();
+await browser.visit(magicLink);          // 302 + Set-Cookie → the jar
+await browser.api.get('/profile');       // sent with the session cookie
+const restore = browser.install();       // the global fetch, for module-level clients
+```
+
+On the server side of a test — a handler serving a request — `browser.fetch` is
+the plain `fetch`: a server forwards what it was handed and never reaches into a
+browser's jar.
+
+### `createMailbox`
+
+Reads the mail an app actually sent, from Mailpit's HTTP API. One address per
+test keeps tests apart, since Mailpit has one inbox and no transactions:
+
+```typescript
+const mailbox = createMailbox({ inbox: process.env.MAILER_INBOX_URL! });
+
+const email = await mailbox('ada@shop.test').last(); // waits for it to arrive
+await browser.visit(email.link!);
+await mailbox('ada@shop.test').clear();
+```
+
+### Test context
+
+`runInTestContext(id, fn)` carries a test's id through every await;
+`installContextFetch()` stamps it onto every outgoing request as
+`x-test-context-id`, so whatever serves a URL in-process finds the test the
+request belongs to — including a request the code under test made while
+handling another one.
+
+### `TransactionRegistry`
+
+One transaction per database per test — an app's database and a schema tenant
+each on their own connection, as deployed — opened the first time the test
+touches it and rolled back by `rollbackAll()`. Code under test may use
+transactions freely: a `BEGIN` becomes a savepoint, so nothing it does can end
+the test's transaction.
+
+```typescript
+const registry = new TransactionRegistry();
+const db = await registry.get('Database', process.env.DATABASE_URL!);
+// …
+await registry.rollbackAll();
+```
+
 ## Database Migration
 
 TestKit includes utilities for managing test database migrations.

package/dist/Factory.cjs

@@ -1,3 +1,52 @@
-const require_Factory = require('./Factory-BhjUOBWN.cjs');
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/Factory.ts
+/**
+* Abstract base class for database factories used in testing.
+* Provides a standardized interface for creating test data using builder and seed patterns.
+*
+* @template Builders - Record of builder functions for creating individual entities
+* @template Seeds - Record of seed functions for creating complex test scenarios
+*
+* @example
+* ```typescript
+* // Define builders for creating individual records
+* const builders = {
+*   user: (attrs) => ({ name: 'Test User', email: 'test@example.com', ...attrs }),
+*   post: (attrs) => ({ title: 'Test Post', content: 'Content', ...attrs })
+* };
+*
+* // Define seeds for complex scenarios
+* const seeds = {
+*   userWithPosts: async (attrs, factory) => {
+*     const user = await factory.insert('user', attrs);
+*     await factory.insertMany(3, 'post', { userId: user.id });
+*     return user;
+*   }
+* };
+* ```
+*/
+var Factory = class {
+	/**
+	* Creates a typed seed function with proper type inference.
+	* This is a utility method to help with TypeScript type checking when defining seeds.
+	*
+	* @template Seed - The seed function type
+	* @param seedFn - The seed function to wrap
+	* @returns The same seed function with proper typing
+	*
+	* @example
+	* ```typescript
+	* const userWithPostsSeed = Factory.createSeed(async ({ attrs, factory, db }) => {
+	*   const user = await factory.insert('user', attrs);
+	*   return user;
+	* });
+	* ```
+	*/
+	static createSeed(seedFn) {
+		return seedFn;
+	}
+};
+//#endregion
+exports.Factory = Factory;
 
-exports.Factory = require_Factory.Factory;
+//# sourceMappingURL=Factory.cjs.map

package/dist/Factory.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Factory.cjs","names":[],"sources":["../src/Factory.ts"],"sourcesContent":["import type { FakerFactory } from './faker';\n\n/**\n * Abstract base class for database factories used in testing.\n * Provides a standardized interface for creating test data using builder and seed patterns.\n *\n * @template Builders - Record of builder functions for creating individual entities\n * @template Seeds - Record of seed functions for creating complex test scenarios\n *\n * @example\n * ```typescript\n * // Define builders for creating individual records\n * const builders = {\n *   user: (attrs) => ({ name: 'Test User', email: 'test@example.com', ...attrs }),\n *   post: (attrs) => ({ title: 'Test Post', content: 'Content', ...attrs })\n * };\n *\n * // Define seeds for complex scenarios\n * const seeds = {\n *   userWithPosts: async (attrs, factory) => {\n *     const user = await factory.insert('user', attrs);\n *     await factory.insertMany(3, 'post', { userId: user.id });\n *     return user;\n *   }\n * };\n * ```\n */\nexport abstract class Factory<\n\tBuilders extends Record<string, any>,\n\tSeeds extends Record<string, any>,\n> {\n\t/**\n\t * Creates a typed seed function with proper type inference.\n\t * This is a utility method to help with TypeScript type checking when defining seeds.\n\t *\n\t * @template Seed - The seed function type\n\t * @param seedFn - The seed function to wrap\n\t * @returns The same seed function with proper typing\n\t *\n\t * @example\n\t * ```typescript\n\t * const userWithPostsSeed = Factory.createSeed(async ({ attrs, factory, db }) => {\n\t *   const user = await factory.insert('user', attrs);\n\t *   return user;\n\t * });\n\t * ```\n\t */\n\tstatic createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed {\n\t\treturn seedFn;\n\t}\n\t/**\n\t * Inserts an object into the database using a builder function.\n\t *\n\t * @param builderName - The name of the builder to use\n\t * @param attrs - The attributes to insert\n\t */\n\tabstract insert<K extends keyof Builders>(\n\t\tbuilderName: K,\n\t\tattrs?: Parameters<Builders[K]>[0],\n\t): Promise<Awaited<ReturnType<Builders[K]>>>;\n\n\t/**\n\t * Inserts multiple objects into the database\n\t *\n\t * @param count -  Number of objects to insert\n\t * @param builderName - The name of the builder to use\n\t * @param attrs - The attributes to insert\n\t */\n\tabstract insertMany<K extends keyof Builders>(\n\t\tcount: number,\n\t\tbuilderName: K,\n\t\tattrs?:\n\t\t\t| Parameters<Builders[K]>[0]\n\t\t\t| ((\n\t\t\t\t\tidx: number,\n\t\t\t\t\tfaker: FakerFactory,\n\t\t\t  ) => Promise<Parameters<Builders[K]>[0]>),\n\t): Promise<Awaited<ReturnType<Builders[K]>>[]>;\n\n\t/**\n\t * Seeds the database using a seed function.\n\t *\n\t * @param seedName - The name of the seed to use\n\t * @returns The result of the seed function\n\t * @param attrs - The attributes to pass to the seed function\n\t */\n\tabstract seed<K extends keyof Seeds>(\n\t\tseedName: K,\n\t\tattrs?: ExtractSeedAttrs<Seeds[K]>,\n\t): ReturnType<Seeds[K]>;\n}\n\n/**\n * Type definition for a factory builder function that can work with different database types.\n * Builders are responsible for creating individual database records with default values and relationships.\n *\n * @template Attrs - The attributes/input type for the builder\n * @template Factory - The factory instance type\n * @template Result - The type of object returned by the builder\n * @template DB - The database connection type (Kysely, Knex, etc.)\n *\n * @param attrs - Partial attributes to override defaults\n * @param factory - The factory instance for creating related records\n * @param db - The database connection\n * @returns The created record or a promise resolving to it\n *\n * @example\n * ```typescript\n * const userBuilder: MixedFactoryBuilder<UserAttrs, Factory, User, Kysely<DB>> =\n *   async (attrs, factory, db) => {\n *     return {\n *       id: faker.string.uuid(),\n *       name: faker.person.fullName(),\n *       email: faker.internet.email(),\n *       ...attrs\n *     };\n *   };\n * ```\n */\nexport type MixedFactoryBuilder<\n\tAttrs = any,\n\tFactory = any,\n\tResult = any,\n\tDB = any,\n> = (attrs: Attrs, factory: Factory, db: DB) => Result | Promise<Result>;\n\n/**\n * Type definition for a factory seed function used to create complex test scenarios.\n * Seeds typically create multiple related records to set up a complete test environment.\n *\n * @template Attrs - The attributes/input type for the seed\n * @template Factory - The factory instance type\n * @template Result - The type of object returned by the seed\n * @template DB - The database connection type (Kysely, Knex, etc.)\n *\n * @param context - Object containing attrs, factory, and db\n * @param context.attrs - Configuration attributes for the seed\n * @param context.factory - The factory instance for creating records\n * @param context.db - The database connection\n * @returns A promise resolving to the seed result\n *\n * @example\n * ```typescript\n * const userWithPostsSeed: FactorySeed<{ postCount?: number }, Factory, User, DB> =\n *   async ({ attrs, factory, db }) => {\n *     const user = await factory.insert('user', attrs);\n *     const postCount = attrs.postCount || 3;\n *\n *     for (let i = 0; i < postCount; i++) {\n *       await factory.insert('post', { userId: user.id });\n *     }\n *\n *     return user;\n *   };\n * ```\n */\nexport type FactorySeed<\n\tAttrs = any,\n\tFactory = any,\n\tResult = any,\n\tDB = any,\n> = (context: { attrs: Attrs; factory: Factory; db: DB }) => Promise<Result>;\n\n/**\n * Helper type to extract the Attrs type from a FactorySeed function.\n * Used internally by Factory implementations to correctly type the seed method parameters.\n */\nexport type ExtractSeedAttrs<T> = T extends (context: {\n\tattrs: infer A;\n\tfactory: any;\n\tdb: any;\n}) => any\n\t? A\n\t: never;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,IAAsB,UAAtB,MAGE;;;;;;;;;;;;;;;;;CAiBD,OAAO,WAAqC,QAAoB;EAC/D,OAAO;CACR;AAyCD"}

package/dist/Factory.d.cts

@@ -1,3 +1,143 @@
-import "./faker-DvxiCtxc.cjs";
-import { ExtractSeedAttrs, Factory, FactorySeed, MixedFactoryBuilder } from "./Factory-AWn1IulI.cjs";
-export { ExtractSeedAttrs, Factory, FactorySeed, MixedFactoryBuilder };
+import { FakerFactory } from "./faker.cjs";
+//#region src/Factory.d.ts
+/**
+ * Abstract base class for database factories used in testing.
+ * Provides a standardized interface for creating test data using builder and seed patterns.
+ *
+ * @template Builders - Record of builder functions for creating individual entities
+ * @template Seeds - Record of seed functions for creating complex test scenarios
+ *
+ * @example
+ * ```typescript
+ * // Define builders for creating individual records
+ * const builders = {
+ *   user: (attrs) => ({ name: 'Test User', email: 'test@example.com', ...attrs }),
+ *   post: (attrs) => ({ title: 'Test Post', content: 'Content', ...attrs })
+ * };
+ *
+ * // Define seeds for complex scenarios
+ * const seeds = {
+ *   userWithPosts: async (attrs, factory) => {
+ *     const user = await factory.insert('user', attrs);
+ *     await factory.insertMany(3, 'post', { userId: user.id });
+ *     return user;
+ *   }
+ * };
+ * ```
+ */
+export declare abstract class Factory<Builders extends Record<string, any>, Seeds extends Record<string, any>> {
+  /**
+   * Creates a typed seed function with proper type inference.
+   * This is a utility method to help with TypeScript type checking when defining seeds.
+   *
+   * @template Seed - The seed function type
+   * @param seedFn - The seed function to wrap
+   * @returns The same seed function with proper typing
+   *
+   * @example
+   * ```typescript
+   * const userWithPostsSeed = Factory.createSeed(async ({ attrs, factory, db }) => {
+   *   const user = await factory.insert('user', attrs);
+   *   return user;
+   * });
+   * ```
+   */
+  static createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed;
+  /**
+   * Inserts an object into the database using a builder function.
+   *
+   * @param builderName - The name of the builder to use
+   * @param attrs - The attributes to insert
+   */
+  abstract insert<K extends keyof Builders>(builderName: K, attrs?: Parameters<Builders[K]>[0]): Promise<Awaited<ReturnType<Builders[K]>>>;
+  /**
+   * Inserts multiple objects into the database
+   *
+   * @param count -  Number of objects to insert
+   * @param builderName - The name of the builder to use
+   * @param attrs - The attributes to insert
+   */
+  abstract insertMany<K extends keyof Builders>(count: number, builderName: K, attrs?: Parameters<Builders[K]>[0] | ((idx: number, faker: FakerFactory) => Promise<Parameters<Builders[K]>[0]>)): Promise<Awaited<ReturnType<Builders[K]>>[]>;
+  /**
+   * Seeds the database using a seed function.
+   *
+   * @param seedName - The name of the seed to use
+   * @returns The result of the seed function
+   * @param attrs - The attributes to pass to the seed function
+   */
+  abstract seed<K extends keyof Seeds>(seedName: K, attrs?: ExtractSeedAttrs<Seeds[K]>): ReturnType<Seeds[K]>;
+}
+/**
+ * Type definition for a factory builder function that can work with different database types.
+ * Builders are responsible for creating individual database records with default values and relationships.
+ *
+ * @template Attrs - The attributes/input type for the builder
+ * @template Factory - The factory instance type
+ * @template Result - The type of object returned by the builder
+ * @template DB - The database connection type (Kysely, Knex, etc.)
+ *
+ * @param attrs - Partial attributes to override defaults
+ * @param factory - The factory instance for creating related records
+ * @param db - The database connection
+ * @returns The created record or a promise resolving to it
+ *
+ * @example
+ * ```typescript
+ * const userBuilder: MixedFactoryBuilder<UserAttrs, Factory, User, Kysely<DB>> =
+ *   async (attrs, factory, db) => {
+ *     return {
+ *       id: faker.string.uuid(),
+ *       name: faker.person.fullName(),
+ *       email: faker.internet.email(),
+ *       ...attrs
+ *     };
+ *   };
+ * ```
+ */
+export type MixedFactoryBuilder<Attrs = any, Factory = any, Result = any, DB = any> = (attrs: Attrs, factory: Factory, db: DB) => Result | Promise<Result>;
+/**
+ * Type definition for a factory seed function used to create complex test scenarios.
+ * Seeds typically create multiple related records to set up a complete test environment.
+ *
+ * @template Attrs - The attributes/input type for the seed
+ * @template Factory - The factory instance type
+ * @template Result - The type of object returned by the seed
+ * @template DB - The database connection type (Kysely, Knex, etc.)
+ *
+ * @param context - Object containing attrs, factory, and db
+ * @param context.attrs - Configuration attributes for the seed
+ * @param context.factory - The factory instance for creating records
+ * @param context.db - The database connection
+ * @returns A promise resolving to the seed result
+ *
+ * @example
+ * ```typescript
+ * const userWithPostsSeed: FactorySeed<{ postCount?: number }, Factory, User, DB> =
+ *   async ({ attrs, factory, db }) => {
+ *     const user = await factory.insert('user', attrs);
+ *     const postCount = attrs.postCount || 3;
+ *
+ *     for (let i = 0; i < postCount; i++) {
+ *       await factory.insert('post', { userId: user.id });
+ *     }
+ *
+ *     return user;
+ *   };
+ * ```
+ */
+export type FactorySeed<Attrs = any, Factory = any, Result = any, DB = any> = (context: {
+  attrs: Attrs;
+  factory: Factory;
+  db: DB;
+}) => Promise<Result>;
+/**
+ * Helper type to extract the Attrs type from a FactorySeed function.
+ * Used internally by Factory implementations to correctly type the seed method parameters.
+ */
+export type ExtractSeedAttrs<T> = T extends ((context: {
+  attrs: infer A;
+  factory: any;
+  db: any;
+}) => any) ? A : never;
+//#endregion
+//# sourceMappingURL=Factory.d.cts.map

package/dist/Factory.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Factory.d.cts","names":[],"sources":["../src/Factory.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;8BA2BsB,QACrB,iBAAiB,qBACjB,cAAc;;;;;;;;;;;;;;;;;SAkBP,WAAW,aAAa,aAAa,QAAQ,OAAO;;;;;;;WASlD,OAAO,gBAAgB,UAC/B,aAAa,GACb,QAAQ,WAAW,SAAS,SAC1B,QAAQ,QAAQ,WAAW,SAAS;;;;;;;;WAS9B,WAAW,gBAAgB,UACnC,eACA,aAAa,GACb,QACG,WAAW,SAAS,WAEpB,aACA,OAAO,iBACF,QAAQ,WAAW,SAAS,WAClC,QAAQ,QAAQ,WAAW,SAAS;;;;;;;;WAS9B,KAAK,gBAAgB,OAC7B,UAAU,GACV,QAAQ,iBAAiB,MAAM,MAC7B,WAAW,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YA8BT,oBACX,aACA,eACA,cACA,aACI,OAAO,OAAO,SAAS,SAAS,IAAI,OAAO,SAAS,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAgCrD,YACX,aACA,eACA,cACA,aACI;EAAW,OAAO;EAAO,SAAS;EAAS,IAAI;MAAS,QAAQ;;;;;YAMzD,iBAAiB,KAAK,YAAW;EAC5C,aAAa;EACb;EACA;aAEE"}

package/dist/Factory.d.mts

@@ -1,3 +1,143 @@
-import "./faker-B6bmbGCM.mjs";
-import { ExtractSeedAttrs, Factory, FactorySeed, MixedFactoryBuilder } from "./Factory-C15SSK8_.mjs";
-export { ExtractSeedAttrs, Factory, FactorySeed, MixedFactoryBuilder };
+import { FakerFactory } from "./faker.mjs";
+//#region src/Factory.d.ts
+/**
+ * Abstract base class for database factories used in testing.
+ * Provides a standardized interface for creating test data using builder and seed patterns.
+ *
+ * @template Builders - Record of builder functions for creating individual entities
+ * @template Seeds - Record of seed functions for creating complex test scenarios
+ *
+ * @example
+ * ```typescript
+ * // Define builders for creating individual records
+ * const builders = {
+ *   user: (attrs) => ({ name: 'Test User', email: 'test@example.com', ...attrs }),
+ *   post: (attrs) => ({ title: 'Test Post', content: 'Content', ...attrs })
+ * };
+ *
+ * // Define seeds for complex scenarios
+ * const seeds = {
+ *   userWithPosts: async (attrs, factory) => {
+ *     const user = await factory.insert('user', attrs);
+ *     await factory.insertMany(3, 'post', { userId: user.id });
+ *     return user;
+ *   }
+ * };
+ * ```
+ */
+export declare abstract class Factory<Builders extends Record<string, any>, Seeds extends Record<string, any>> {
+  /**
+   * Creates a typed seed function with proper type inference.
+   * This is a utility method to help with TypeScript type checking when defining seeds.
+   *
+   * @template Seed - The seed function type
+   * @param seedFn - The seed function to wrap
+   * @returns The same seed function with proper typing
+   *
+   * @example
+   * ```typescript
+   * const userWithPostsSeed = Factory.createSeed(async ({ attrs, factory, db }) => {
+   *   const user = await factory.insert('user', attrs);
+   *   return user;
+   * });
+   * ```
+   */
+  static createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed;
+  /**
+   * Inserts an object into the database using a builder function.
+   *
+   * @param builderName - The name of the builder to use
+   * @param attrs - The attributes to insert
+   */
+  abstract insert<K extends keyof Builders>(builderName: K, attrs?: Parameters<Builders[K]>[0]): Promise<Awaited<ReturnType<Builders[K]>>>;
+  /**
+   * Inserts multiple objects into the database
+   *
+   * @param count -  Number of objects to insert
+   * @param builderName - The name of the builder to use
+   * @param attrs - The attributes to insert
+   */
+  abstract insertMany<K extends keyof Builders>(count: number, builderName: K, attrs?: Parameters<Builders[K]>[0] | ((idx: number, faker: FakerFactory) => Promise<Parameters<Builders[K]>[0]>)): Promise<Awaited<ReturnType<Builders[K]>>[]>;
+  /**
+   * Seeds the database using a seed function.
+   *
+   * @param seedName - The name of the seed to use
+   * @returns The result of the seed function
+   * @param attrs - The attributes to pass to the seed function
+   */
+  abstract seed<K extends keyof Seeds>(seedName: K, attrs?: ExtractSeedAttrs<Seeds[K]>): ReturnType<Seeds[K]>;
+}
+/**
+ * Type definition for a factory builder function that can work with different database types.
+ * Builders are responsible for creating individual database records with default values and relationships.
+ *
+ * @template Attrs - The attributes/input type for the builder
+ * @template Factory - The factory instance type
+ * @template Result - The type of object returned by the builder
+ * @template DB - The database connection type (Kysely, Knex, etc.)
+ *
+ * @param attrs - Partial attributes to override defaults
+ * @param factory - The factory instance for creating related records
+ * @param db - The database connection
+ * @returns The created record or a promise resolving to it
+ *
+ * @example
+ * ```typescript
+ * const userBuilder: MixedFactoryBuilder<UserAttrs, Factory, User, Kysely<DB>> =
+ *   async (attrs, factory, db) => {
+ *     return {
+ *       id: faker.string.uuid(),
+ *       name: faker.person.fullName(),
+ *       email: faker.internet.email(),
+ *       ...attrs
+ *     };
+ *   };
+ * ```
+ */
+export type MixedFactoryBuilder<Attrs = any, Factory = any, Result = any, DB = any> = (attrs: Attrs, factory: Factory, db: DB) => Result | Promise<Result>;
+/**
+ * Type definition for a factory seed function used to create complex test scenarios.
+ * Seeds typically create multiple related records to set up a complete test environment.
+ *
+ * @template Attrs - The attributes/input type for the seed
+ * @template Factory - The factory instance type
+ * @template Result - The type of object returned by the seed
+ * @template DB - The database connection type (Kysely, Knex, etc.)
+ *
+ * @param context - Object containing attrs, factory, and db
+ * @param context.attrs - Configuration attributes for the seed
+ * @param context.factory - The factory instance for creating records
+ * @param context.db - The database connection
+ * @returns A promise resolving to the seed result
+ *
+ * @example
+ * ```typescript
+ * const userWithPostsSeed: FactorySeed<{ postCount?: number }, Factory, User, DB> =
+ *   async ({ attrs, factory, db }) => {
+ *     const user = await factory.insert('user', attrs);
+ *     const postCount = attrs.postCount || 3;
+ *
+ *     for (let i = 0; i < postCount; i++) {
+ *       await factory.insert('post', { userId: user.id });
+ *     }
+ *
+ *     return user;
+ *   };
+ * ```
+ */
+export type FactorySeed<Attrs = any, Factory = any, Result = any, DB = any> = (context: {
+  attrs: Attrs;
+  factory: Factory;
+  db: DB;
+}) => Promise<Result>;
+/**
+ * Helper type to extract the Attrs type from a FactorySeed function.
+ * Used internally by Factory implementations to correctly type the seed method parameters.
+ */
+export type ExtractSeedAttrs<T> = T extends ((context: {
+  attrs: infer A;
+  factory: any;
+  db: any;
+}) => any) ? A : never;
+//#endregion
+//# sourceMappingURL=Factory.d.mts.map

package/dist/Factory.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Factory.d.mts","names":[],"sources":["../src/Factory.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;8BA2BsB,QACrB,iBAAiB,qBACjB,cAAc;;;;;;;;;;;;;;;;;SAkBP,WAAW,aAAa,aAAa,QAAQ,OAAO;;;;;;;WASlD,OAAO,gBAAgB,UAC/B,aAAa,GACb,QAAQ,WAAW,SAAS,SAC1B,QAAQ,QAAQ,WAAW,SAAS;;;;;;;;WAS9B,WAAW,gBAAgB,UACnC,eACA,aAAa,GACb,QACG,WAAW,SAAS,WAEpB,aACA,OAAO,iBACF,QAAQ,WAAW,SAAS,WAClC,QAAQ,QAAQ,WAAW,SAAS;;;;;;;;WAS9B,KAAK,gBAAgB,OAC7B,UAAU,GACV,QAAQ,iBAAiB,MAAM,MAC7B,WAAW,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YA8BT,oBACX,aACA,eACA,cACA,aACI,OAAO,OAAO,SAAS,SAAS,IAAI,OAAO,SAAS,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAgCrD,YACX,aACA,eACA,cACA,aACI;EAAW,OAAO;EAAO,SAAS;EAAS,IAAI;MAAS,QAAQ;;;;;YAMzD,iBAAiB,KAAK,YAAW;EAC5C,aAAa;EACb;EACA;aAEE"}

package/dist/Factory.mjs

@@ -1,3 +1,51 @@
-import { Factory } from "./Factory-BFVnMMCC.mjs";
+//#region src/Factory.ts
+/**
+* Abstract base class for database factories used in testing.
+* Provides a standardized interface for creating test data using builder and seed patterns.
+*
+* @template Builders - Record of builder functions for creating individual entities
+* @template Seeds - Record of seed functions for creating complex test scenarios
+*
+* @example
+* ```typescript
+* // Define builders for creating individual records
+* const builders = {
+*   user: (attrs) => ({ name: 'Test User', email: 'test@example.com', ...attrs }),
+*   post: (attrs) => ({ title: 'Test Post', content: 'Content', ...attrs })
+* };
+*
+* // Define seeds for complex scenarios
+* const seeds = {
+*   userWithPosts: async (attrs, factory) => {
+*     const user = await factory.insert('user', attrs);
+*     await factory.insertMany(3, 'post', { userId: user.id });
+*     return user;
+*   }
+* };
+* ```
+*/
+var Factory = class {
+	/**
+	* Creates a typed seed function with proper type inference.
+	* This is a utility method to help with TypeScript type checking when defining seeds.
+	*
+	* @template Seed - The seed function type
+	* @param seedFn - The seed function to wrap
+	* @returns The same seed function with proper typing
+	*
+	* @example
+	* ```typescript
+	* const userWithPostsSeed = Factory.createSeed(async ({ attrs, factory, db }) => {
+	*   const user = await factory.insert('user', attrs);
+	*   return user;
+	* });
+	* ```
+	*/
+	static createSeed(seedFn) {
+		return seedFn;
+	}
+};
+//#endregion
+export { Factory };
 
-export { Factory };
+//# sourceMappingURL=Factory.mjs.map

package/dist/Factory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Factory.mjs","names":[],"sources":["../src/Factory.ts"],"sourcesContent":["import type { FakerFactory } from './faker';\n\n/**\n * Abstract base class for database factories used in testing.\n * Provides a standardized interface for creating test data using builder and seed patterns.\n *\n * @template Builders - Record of builder functions for creating individual entities\n * @template Seeds - Record of seed functions for creating complex test scenarios\n *\n * @example\n * ```typescript\n * // Define builders for creating individual records\n * const builders = {\n *   user: (attrs) => ({ name: 'Test User', email: 'test@example.com', ...attrs }),\n *   post: (attrs) => ({ title: 'Test Post', content: 'Content', ...attrs })\n * };\n *\n * // Define seeds for complex scenarios\n * const seeds = {\n *   userWithPosts: async (attrs, factory) => {\n *     const user = await factory.insert('user', attrs);\n *     await factory.insertMany(3, 'post', { userId: user.id });\n *     return user;\n *   }\n * };\n * ```\n */\nexport abstract class Factory<\n\tBuilders extends Record<string, any>,\n\tSeeds extends Record<string, any>,\n> {\n\t/**\n\t * Creates a typed seed function with proper type inference.\n\t * This is a utility method to help with TypeScript type checking when defining seeds.\n\t *\n\t * @template Seed - The seed function type\n\t * @param seedFn - The seed function to wrap\n\t * @returns The same seed function with proper typing\n\t *\n\t * @example\n\t * ```typescript\n\t * const userWithPostsSeed = Factory.createSeed(async ({ attrs, factory, db }) => {\n\t *   const user = await factory.insert('user', attrs);\n\t *   return user;\n\t * });\n\t * ```\n\t */\n\tstatic createSeed<Seed extends FactorySeed>(seedFn: Seed): Seed {\n\t\treturn seedFn;\n\t}\n\t/**\n\t * Inserts an object into the database using a builder function.\n\t *\n\t * @param builderName - The name of the builder to use\n\t * @param attrs - The attributes to insert\n\t */\n\tabstract insert<K extends keyof Builders>(\n\t\tbuilderName: K,\n\t\tattrs?: Parameters<Builders[K]>[0],\n\t): Promise<Awaited<ReturnType<Builders[K]>>>;\n\n\t/**\n\t * Inserts multiple objects into the database\n\t *\n\t * @param count -  Number of objects to insert\n\t * @param builderName - The name of the builder to use\n\t * @param attrs - The attributes to insert\n\t */\n\tabstract insertMany<K extends keyof Builders>(\n\t\tcount: number,\n\t\tbuilderName: K,\n\t\tattrs?:\n\t\t\t| Parameters<Builders[K]>[0]\n\t\t\t| ((\n\t\t\t\t\tidx: number,\n\t\t\t\t\tfaker: FakerFactory,\n\t\t\t  ) => Promise<Parameters<Builders[K]>[0]>),\n\t): Promise<Awaited<ReturnType<Builders[K]>>[]>;\n\n\t/**\n\t * Seeds the database using a seed function.\n\t *\n\t * @param seedName - The name of the seed to use\n\t * @returns The result of the seed function\n\t * @param attrs - The attributes to pass to the seed function\n\t */\n\tabstract seed<K extends keyof Seeds>(\n\t\tseedName: K,\n\t\tattrs?: ExtractSeedAttrs<Seeds[K]>,\n\t): ReturnType<Seeds[K]>;\n}\n\n/**\n * Type definition for a factory builder function that can work with different database types.\n * Builders are responsible for creating individual database records with default values and relationships.\n *\n * @template Attrs - The attributes/input type for the builder\n * @template Factory - The factory instance type\n * @template Result - The type of object returned by the builder\n * @template DB - The database connection type (Kysely, Knex, etc.)\n *\n * @param attrs - Partial attributes to override defaults\n * @param factory - The factory instance for creating related records\n * @param db - The database connection\n * @returns The created record or a promise resolving to it\n *\n * @example\n * ```typescript\n * const userBuilder: MixedFactoryBuilder<UserAttrs, Factory, User, Kysely<DB>> =\n *   async (attrs, factory, db) => {\n *     return {\n *       id: faker.string.uuid(),\n *       name: faker.person.fullName(),\n *       email: faker.internet.email(),\n *       ...attrs\n *     };\n *   };\n * ```\n */\nexport type MixedFactoryBuilder<\n\tAttrs = any,\n\tFactory = any,\n\tResult = any,\n\tDB = any,\n> = (attrs: Attrs, factory: Factory, db: DB) => Result | Promise<Result>;\n\n/**\n * Type definition for a factory seed function used to create complex test scenarios.\n * Seeds typically create multiple related records to set up a complete test environment.\n *\n * @template Attrs - The attributes/input type for the seed\n * @template Factory - The factory instance type\n * @template Result - The type of object returned by the seed\n * @template DB - The database connection type (Kysely, Knex, etc.)\n *\n * @param context - Object containing attrs, factory, and db\n * @param context.attrs - Configuration attributes for the seed\n * @param context.factory - The factory instance for creating records\n * @param context.db - The database connection\n * @returns A promise resolving to the seed result\n *\n * @example\n * ```typescript\n * const userWithPostsSeed: FactorySeed<{ postCount?: number }, Factory, User, DB> =\n *   async ({ attrs, factory, db }) => {\n *     const user = await factory.insert('user', attrs);\n *     const postCount = attrs.postCount || 3;\n *\n *     for (let i = 0; i < postCount; i++) {\n *       await factory.insert('post', { userId: user.id });\n *     }\n *\n *     return user;\n *   };\n * ```\n */\nexport type FactorySeed<\n\tAttrs = any,\n\tFactory = any,\n\tResult = any,\n\tDB = any,\n> = (context: { attrs: Attrs; factory: Factory; db: DB }) => Promise<Result>;\n\n/**\n * Helper type to extract the Attrs type from a FactorySeed function.\n * Used internally by Factory implementations to correctly type the seed method parameters.\n */\nexport type ExtractSeedAttrs<T> = T extends (context: {\n\tattrs: infer A;\n\tfactory: any;\n\tdb: any;\n}) => any\n\t? A\n\t: never;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,IAAsB,UAAtB,MAGE;;;;;;;;;;;;;;;;;CAiBD,OAAO,WAAqC,QAAoB;EAC/D,OAAO;CACR;AAyCD"}