@aklinker1/zero-factory 1.0.3 → 1.1.0

package/README.md

@@ -98,6 +98,45 @@ const user = userFactory({
 > [!IMPORTANT]
 > Arrays are not deeply merged. If a property is an array, overrides will fully replace it, like any other value.
 
+#### Function Defaults
+
+In addition to static values, you can pass a function as a value:
+
+```ts
+const userFactory = createFactory({
+  email: () => `example.${Math.floor(Math.random() * 1000)}@gmail.com`,
+  // ...
+});
+```
+
+Every time the factory is called, this will call the function and, in this case, generate a different `email` each time:
+
+```ts
+userFactory(); // { email: "example.424@gmail.com", ... }
+userFactory(); // { email: "example.133@gmail.com", ... }
+```
+
+This is where [fake data generators](https://www.npmjs.com/search?q=fake%20data) and [sequences](#sequences) come in clutch:
+
+```ts
+import { createFactory, createSequence } from "@aklinker1/zero-factory";
+import {
+  randEmail, // () => string
+  randUsername, // () => string
+  randBoolean, // () => boolean
+} from "@ngneat/falso";
+
+const userFactory = createFactory({
+  id: createSequence("user-"),
+  username: randUsername,
+  email: randEmail,
+  preferences: {
+    receiveMarketingEmails: randBoolean,
+    receiveSecurityEmails: randBoolean,
+  },
+});
+```
+
 #### Many
 
 You can generate multiple objects using `factory.many(...)`. This method will return an array of objects.
@@ -157,43 +196,39 @@ const user = userFactory.noEmails({ username: "overridden" });
 // }
 ```
 
-### Function Defaults
+#### Associations
 
-In addition to static values, you can pass a function as a value:
+If you want to override one or more fields based on a single value, use associations:
 
 ```ts
-const userFactory = createFactory({
-  email: () => `example.${Math.floor(Math.random() * 1000)}@gmail.com`,
+const postFactory = createFactory<Post>({
+  id: createSequence(),
+  userId: userIdSequence,
   // ...
-});
+}).associate("user", (user: User) => ({ userId: user.id }));
 ```
 
-Every time the factory is called, this will call the function and, in this case, generate a different `email` each time:
+Then to generate a post associated with a user, use `with`:
 
 ```ts
-userFactory(); // { email: "example.424@gmail.com", ... }
-userFactory(); // { email: "example.133@gmail.com", ... }
+user;
+// => {
+//   id: 3,
+//   ...
+// }
+
+postFactory.with({ user })();
+// => {
+//   id: 0,
+//   userId: 3,
+//   ...
+// }
 ```
 
-This is where [fake data generators](https://www.npmjs.com/search?q=fake%20data) and [sequences](#sequences) come in clutch:
+Note that `with` returns a factory function, which needs to be called to generate the final object. This allows you to chain other utilities like `.many` or `.trait`:
 
 ```ts
-import { createFactory, createSequence } from "@aklinker1/zero-factory";
-import {
-  randEmail, // () => string
-  randUsername, // () => string
-  randBoolean, // () => boolean
-} from "@ngneat/falso";
-
-const userFactory = createFactory({
-  id: createSequence("user-"),
-  username: randUsername,
-  email: randEmail,
-  preferences: {
-    receiveMarketingEmails: randBoolean,
-    receiveSecurityEmails: randBoolean,
-  },
-});
+postFactory.with({ user }).noEmails.many(3);
 ```
 
 ### Sequences
@@ -249,19 +284,18 @@ May or may not implement these.
 - Associations:
 
   ```ts
-  const userIdSequence = createSequence("user-")
+  const userIdSequence = createSequence("user-");
   const userFactory = createFactory<User>({
     id: userIdSequence,
     // ...
-  })
+  });
   const postFactory = createFactory<Post>({
     id: createSequence("post-"),
     userId: userIdSequence,
-  })
-    .associate<User>("user", (user) => ({
-      userId: user.id
-    }))
+  }).associate("user", (user: User) => ({
+    userId: user.id,
+  }));
 
   const user = userFactory(); // { id: "user-0", ... }
-  const postFactory.with({ user })(/* optional overrides */) // { id: "post-0", userId: "user-0", ... }
+  postFactory.with({ user })(/* optional overrides */); // { id: "post-0", userId: "user-0", ... }
   ```

package/dist/factories.d.ts

@@ -5,11 +5,11 @@ import { type DeepPartial, type FactoryDefaults } from "./utils";
  * - Object containing any `.traitName(...)` functions that, when called, return a new object applying the trait's defaults over the factory's base defaults.
  * - Object containing immutable modifier functions (`trait`) that, when called, returns a new factory with more ways of generating objects.
  */
-export type Factory<TObject extends Record<string, any>, TTraits extends string | undefined = undefined> = FactoryFn<TObject> & TraitFactoryFns<TObject, TTraits extends string ? TTraits : never> & FactoryModifiers<TObject, TTraits>;
+export type Factory<TObject extends Record<string, any>, TTraits extends string | undefined = undefined, TAssociations extends Record<string, any> = {}> = FactoryFn<TObject, TAssociations> & TraitFactoryFns<TObject, TTraits extends string ? TTraits : never, TAssociations> & FactoryModifiers<TObject, TTraits>;
 /**
  * Function that takes in overrides and returns a new object.
  */
-export type FactoryFn<TObject> = {
+export type FactoryFn<TObject, TAssociations extends Record<string, any> = {}> = {
     (overrides?: DeepPartial<TObject>): TObject;
     /**
      * Generate multiple items.
@@ -26,17 +26,23 @@ export type FactoryFn<TObject> = {
      * ```
      */
     many(count: number, overrides?: DeepPartial<TObject>): TObject[];
+    /**
+     * Apply associations and return a new factory function.
+     *
+     * @see {@link FactoryModifiers#associate}
+     */
+    with(associations: Partial<TAssociations>): FactoryFn<TObject, {}>;
 };
 /**
  * Map of factory functions for traits.
  */
-export type TraitFactoryFns<TObject, TTraits extends string> = {
-    [name in TTraits]: FactoryFn<TObject>;
+export type TraitFactoryFns<TObject, TTraits extends string, TAssociations extends Record<string, any> = {}> = {
+    [name in TTraits]: FactoryFn<TObject, TAssociations>;
 };
 /**
  * Functions that modify the factory's type.
  */
-export type FactoryModifiers<TObject extends Record<string, any>, TTraits extends string | undefined> = {
+export type FactoryModifiers<TObject extends Record<string, any>, TTraits extends string | undefined, TAssociations extends Record<string, any> = {}> = {
     /**
      * Add a trait or variant to the factory, allowing developers to create the
      * object with multiple sets of default values.
@@ -59,8 +65,68 @@ export type FactoryModifiers<TObject extends Record<string, any>, TTraits extend
      *                      calling the factory function.
      */
     trait<T2 extends string>(name: T2, traitDefaults: DeepPartial<FactoryDefaults<TObject>>): Factory<TObject, AddTrait<TTraits, T2>>;
+    /**
+     * Returns a factory that uses associations to apply default values.
+     *
+     * There are two common use-cases:
+     * - Generating "dependent" properties
+     * - Database relationships
+     *
+     * @example
+     * ```ts
+     * const userFactory = createFactory<User>({
+     *   id: createSequence("user-"),
+     *   email: randEmail(),
+     *   fullName: randFullName(),
+     *   firstName: randFirstName(),
+     *   lastName: randLastName(),
+     * })
+     *   .associate("fullName", (fullName: string) => ({
+     *     fullName,
+     *     firstName: fullName.split(" ")[0],
+     *     lastName: fullName.split(" ")[1],
+     *   })
+     *
+     * userFactory.with({ fullName: "John Doe" })()
+     * // {
+     * //   id: "user-0",
+     * //   email: "john.doe@example.com",
+     * //   fullName: "John Doe",
+     * //   firstName: "John",
+     * //   lastName: "Doe",
+     * // }
+     * ```
+     *
+     * @example
+     * ```ts
+     * const postFactory = createFactory<Post>({
+     *   id: createSequence("post-"),
+     *   userId: createSequence("user-"),
+     *   // ...
+     * })
+     *   .associate("user", (user: User) => ({
+     *     userId: user.id,
+     *   })
+     *
+     * const user = userFactory();
+     * // {
+     * //   id: "user-0",
+     * //   ...
+     * // }
+     * const post = postFactory.with({ user })()
+     * // {
+     * //   id: "post-0",
+     * //   userId: "user-0",
+     * //   // ...
+     * // }
+     * ```
+     */
+    associate<TKey extends string, TValue>(key: TKey, apply: (value: TValue) => DeepPartial<TObject>): Factory<TObject, TTraits, AddAssociation<TAssociations, TKey, TValue>>;
 };
 export type AddTrait<T1 extends string | undefined, T2 extends string> = T1 extends string ? T1 | T2 : T2;
+export type AddAssociation<TAssociations extends Record<string, any>, TKey extends string, TValue> = {
+    [key in keyof TAssociations | TKey]: key extends TKey ? TValue : TAssociations[key];
+};
 /**
  * Create a function that returns objects of the specified type.
  * @param defaults The default values for the returned object. Each property can be a value or function that return a value.

package/dist/index.js

@@ -43,20 +43,49 @@ function resolveDefaults(val) {
 
 // src/factories.ts
 function createFactory(defaults) {
-  return createFactoryInternal(defaults, {});
+  return createFactoryInternal(defaults, {
+    traits: {},
+    associations: {}
+  });
 }
-function createFactoryInternal(defaults, traits) {
-  return Object.assign((overrides) => generateObject(defaults, overrides), {
-    many: (count, overrides) => generateManyObjects(count, defaults, overrides),
+function createFactoryInternal(defaults, state) {
+  const createFactoryFn = (factoryDefaults) => {
+    const factoryFn = (overrides) => generateObject(factoryDefaults, overrides);
+    factoryFn.many = (count, overrides) => generateManyObjects(count, factoryDefaults, overrides);
+    factoryFn.with = (associations) => {
+      const combinedDefaults = Object.entries(associations).reduce((acc, [key, value]) => {
+        if (state.associations[key]) {
+          const override = state.associations[key](value);
+          return deepMerge(acc, override);
+        } else {
+          return acc;
+        }
+      }, defaults);
+      return createFactoryInternal(combinedDefaults, state);
+    };
+    return factoryFn;
+  };
+  return Object.assign(createFactoryFn(defaults), {
     trait: (name, traitDefaults) => createFactoryInternal(defaults, {
-      ...traits,
-      [name]: deepMerge(defaults, traitDefaults)
+      ...state,
+      traits: {
+        ...state.traits,
+        [name]: deepMerge(defaults, traitDefaults)
+      }
     }),
-    ...Object.fromEntries(Object.entries(traits).map(([name, traitDefaults]) => {
-      const traitFactory = (overrides) => generateObject(traitDefaults, overrides);
-      traitFactory.many = (count, overrides) => generateManyObjects(count, traitDefaults, overrides);
-      return [name, traitFactory];
-    }))
+    associate: (key, apply) => {
+      return createFactoryInternal(defaults, {
+        ...state,
+        associations: {
+          ...state.associations,
+          [key]: apply
+        }
+      });
+    },
+    ...Object.fromEntries(Object.entries(state.traits).map(([name, traitDefaults]) => [
+      name,
+      createFactoryFn(traitDefaults)
+    ]))
   });
 }
 function generateObject(defaults, overrides) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aklinker1/zero-factory",
   "description": "Zero dependency object factory generator for testing",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "packageManager": "bun@1.2.20",
   "type": "module",
   "license": "MIT",