@aklinker1/zero-factory 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aaron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,254 @@
+<h1 align="center">@aklinker1/zero-factory</h1>
+
+<p align="center">Zero dependency object factory generator for testing.</p>
+
+```ts
+import { createFactory, createSequence } from "@aklinker1/zero-factory";
+
+const userFactory = createFactory<User>({
+  id: createSequence("user-"),
+  username: "example-username",
+  email: () => "example-email-" + Math.random(),
+});
+
+userFactory({ id: "test", username: "user" });
+// => {
+//   id: "test",
+//   username: "user",
+//   email: "example-email-0.20088082049103195"
+// }
+```
+
+```sh
+npm i @aklinker1/zero-factory
+```
+
+**Features:**
+
+- ✅ Type-safe
+- ✨ Deeply merge overrides with default values
+- 🔢 Sequence generator for IDs
+- 🎨 "traits" - define multiple variants of default values
+
+**Not Supported:**
+
+- **Class instances**: Only objects can be created. Factories will not create class instances.
+- **Randomized data**: There are already several mature libraries for generating randomized testing data (`@ngneat/falso`, `faker-js`, `chance`, `casual`, etc).
+
+## Usage
+
+### Factories
+
+Use `createFactory` to build an object factory. Object factories are simple functions that returns an object:
+
+```ts
+const userFactory = createFactory<User>({
+  id: "user-id",
+  username: "username",
+  email: "example@gmail.com",
+  preferences: {
+    receiveMarketingEmails: true,
+    receiveSecurityEmails: true,
+  },
+});
+// typeof userFactory = (overrides?: DeepPartial<User>) => User
+```
+
+Then, to get an object conforming to the `User` type, just call the factory as a function:
+
+```ts
+const user = userFactory();
+// => {
+//   id: "user-id",
+//   username: "username",
+//   email: "example@gmail.com",
+//   preferences: {
+//     receiveMarketingEmails: true,
+//     receiveSecurityEmails: true,
+//   }
+// }
+```
+
+You can also override specific properties at any level:
+
+```ts
+const user = userFactory({
+  username: "overridden",
+  preferences: {
+    receiveMarketingEmails: false,
+  },
+});
+// => {
+//   id: "user-id",
+//   username: "overridden",
+//   email: "example@gmail.com",
+//   preferences: {
+//     receiveMarketingEmails: false,
+//     receiveSecurityEmails: true,
+//   }
+// }
+```
+
+#### Traits
+
+If there are common variants or "traits" of an object you want to be able to generate, use `factory.trait(...)`:
+
+```ts
+const userFactory = createFactory({
+  // same as above
+}).trait("noEmails", {
+  preferences: {
+    receiveMarketingEmails: false,
+    receiveSecurityEmails: false,
+  },
+});
+```
+
+Then, to generate an object using this trait, the trait is a function defined on the object factory:
+
+```ts
+const user = userFactory.noEmails();
+// => {
+//   id: "user-id",
+//   username: "username",
+//   email: "example@gmail.com",
+//   preferences: {
+//     receiveMarketingEmails: false,
+//     receiveSecurityEmails: false,
+//   }
+// }
+```
+
+When using a trait and overriding specific properties, the trait's default values are applied before the overrides:
+
+```ts
+const user = userFactory.noEmails({ username: "overridden" });
+// => {
+//   id: "user-id",
+//   username: "overridden",
+//   email: "example@gmail.com",
+//   preferences: {
+//     receiveMarketingEmails: false,
+//     receiveSecurityEmails: false,
+//   }
+// }
+```
+
+### 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,
+  },
+});
+```
+
+### Sequences
+
+For values like IDs, it can be useful to generate them incrementally instead of using randomized values. Use the `createSequence` function to do this:
+
+```ts
+const userIdSequence = createSequence((i) => `user-${i}`);
+
+userIdSequence(); // "user-0"
+userIdSequence(); // "user-1"
+userIdSequence(); // "user-2"
+// ...
+```
+
+The argument `i` is a number starting at 0 that gets incremented by 1 each time the sequence is called. The return value can be anything (string, boolean, object, integer, etc).
+
+```ts
+const intSequence = createSequence((i) => i + 1);
+intSequence(); // 1
+intSequence(); // 2
+intSequence(); // 3
+// ...
+
+const boolSequence = createSequence((i) => i % 2 === 0);
+boolSequence(); // true
+boolSequence(); // false
+boolSequence(); // true
+// ...
+```
+
+However, the most common types of return values are integers and strings. For both, there is a shorthand:
+
+```ts
+const intSequence = createSequence();
+intSequence(); // 0
+intSequence(); // 1
+intSequence(); // 2
+// ...
+
+const strSequence = createSequence("prefix-");
+intSequence(); // "prefix-0"
+intSequence(); // "prefix-1"
+intSequence(); // "prefix-2"
+```
+
+---
+
+## Future Features?
+
+May or may not implement these.
+
+- Generate multiple items:
+  ```ts
+  userFactory.many(4, { username: "override" });
+  // [
+  //   { id: "user-0", username: "override", ... },
+  //   { id: "user-1", username: "override", ... },
+  //   { id: "user-2", username: "override", ... },
+  //   { id: "user-3", username: "override", ... },
+  // ]
+  ```
+- Associations:
+
+  ```ts
+  const userIdSequence = createSequence("user-")
+  const userFactory = createFactory<User>({
+    id: userIdSequence,
+    // ...
+  })
+  const postFactory = createFactory<Post>({
+    id: createSequence("post-"),
+    userId: userIdSequence,
+  })
+    .associate("user", (user) => ({
+      userId: user.id
+    }))
+
+  const user = userFactory(); // { id: "user-0", ... }
+  const postFactory.with({ user })(/* optional overrides */) // { id: "post-0", userId: "user-0", ... }
+  ```

package/dist/factories.d.ts

@@ -0,0 +1,53 @@
+import { type DeepPartial, type FactoryDefaults } from "./utils";
+/**
+ * A factory is a:
+ * - Function that, when called, returns a new object as defined by the default values.
+ * - 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>;
+/**
+ * Function that takes in overrides and returns a new object.
+ */
+export type FactoryFn<TObject> = {
+    (overrides?: DeepPartial<TObject>): TObject;
+};
+/**
+ * Map of factory functions for traits.
+ */
+export type TraitFactoryFns<TObject, TTraits extends string> = {
+    [name in TTraits]: FactoryFn<TObject>;
+};
+/**
+ * Functions that modify the factory's type.
+ */
+export type FactoryModifiers<TObject extends Record<string, any>, TTraits extends string | undefined> = {
+    /**
+     * Add a trait or variant to the factory, allowing developers to create the
+     * object with multiple sets of default values.
+     *
+     * @example
+     * ```ts
+     * const userFactory = createFactory<User>({
+     *   // ...
+     *   subscribedToEmails: true,
+     * })
+     *   .trait("unsubscribed", { subscribedToEmails: false })
+     *
+     * userFactory() // { subscribedToEmails: true }
+     * userFactory.unsubscribed() // { subscribedToEmails: false }
+     * ```
+     *
+     * @param name The name of the trait to add
+     * @param traitDefaults Default values to apply over the factory's base
+     *                      default values. These can still be overridden when
+     *                      calling the factory function.
+     */
+    trait<T2 extends string>(name: T2, traitDefaults: DeepPartial<FactoryDefaults<TObject>>): Factory<TObject, AddTrait<TTraits, T2>>;
+};
+export type AddTrait<T1 extends string | undefined, T2 extends string> = T1 extends string ? T1 | T2 : T2;
+/**
+ * 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.
+ */
+export declare function createFactory<T extends Record<string, any>>(defaults: FactoryDefaults<T>): Factory<T>;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { DeepPartial } from "./utils";
+export * from "./sequences";
+export * from "./factories";

package/dist/index.js

@@ -0,0 +1,68 @@
+// src/sequences.ts
+function createSequence(arg) {
+  if (!arg)
+    return createSequence((i2) => i2);
+  if (typeof arg === "string")
+    return createSequence((i2) => `${arg}${i2}`);
+  let i = 0;
+  return () => arg(i++);
+}
+// src/utils.ts
+function deepMerge(base, overrides) {
+  if (!isMergeable(overrides))
+    return applyOverride(base, overrides);
+  return Object.fromEntries(Object.keys({ ...base, ...overrides }).map((key) => [
+    key,
+    deepMerge(base[key], overrides[key])
+  ]));
+}
+function applyOverride(base, override) {
+  return override === undefined ? base : override;
+}
+function isMergeable(val) {
+  return val != null && typeof val === "object" && !Array.isArray(val);
+}
+function resolveDefaults(val) {
+  const result = {};
+  for (const key in val) {
+    if (Object.prototype.hasOwnProperty.call(val, key)) {
+      const defaultValue = val[key];
+      if (typeof defaultValue === "function") {
+        result[key] = defaultValue();
+      } else if (isMergeable(defaultValue)) {
+        result[key] = resolveDefaults(defaultValue);
+      } else {
+        result[key] = defaultValue;
+      }
+    }
+  }
+  return result;
+}
+
+// src/factories.ts
+function createFactory(defaults) {
+  return createFactoryInternal(defaults, {});
+}
+function createFactoryInternal(defaults, traits) {
+  console.log("Created factory:", { defaults, traits });
+  return Object.assign((overrides) => generateObject(defaults, overrides), {
+    trait: (name, traitDefaults) => createFactoryInternal(defaults, {
+      ...traits,
+      [name]: deepMerge(defaults, traitDefaults)
+    }),
+    ...Object.fromEntries(Object.entries(traits).map(([name, traitDefaults]) => {
+      return [
+        name,
+        (overrides) => generateObject(traitDefaults, overrides)
+      ];
+    }))
+  });
+}
+function generateObject(defaults, overrides) {
+  const resolvedDefaults = resolveDefaults(defaults);
+  return deepMerge(resolvedDefaults, overrides);
+}
+export {
+  createSequence,
+  createFactory
+};

package/dist/sequences.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A simple function that returns a value based on how many times the function
+ * has been called.
+ */
+export type Sequence<T> = () => T;
+/**
+ * Defines what sequence values look like.
+ */
+export type SequenceDefinition<T> = (i: number) => T;
+/**
+ * Shorthand for creating a sequence of incrementing integers staring at 0.
+ *
+ * Same as `createSequence((i) => i)`.
+ *
+ * @example
+ * ```ts
+ * const seq = createSequence();
+ * seq(); // 0
+ * seq(); // 1
+ * seq(); // 2
+ * // ...
+ * ```
+ */
+export declare function createSequence(): Sequence<number>;
+/**
+ * Shorthand for creating a sequence of incrementing strings staring at 0.
+ *
+ * Same as `createSequence((i) => `${prefix}${i})`.
+ *
+ * @param prefix The string to put in front of the incrementing integer.
+ *
+ * @example
+ * ```ts
+ * const seq = createSequence("user-");
+ * seq(); // "user-0"
+ * seq(); // "user-1"
+ * seq(); // "user-2"
+ * // ...
+ * ```
+ */
+export declare function createSequence(prefix: string): Sequence<string>;
+/**
+ * Use a custom function to generate the sequence values.
+ *
+ * @param fn Callback called each time the sequence needs to generate a value.
+ *           The first argument, `i`, starts at 0.
+ *
+ * @example
+ * ```ts
+ * const seq = createSequence((i) => `example-${i * 2}`)
+ * seq(); // "example-0"
+ * seq(); // "example-2"
+ * seq(); // "example-4"
+ * // ...
+ * ```
+ */
+export declare function createSequence<T>(fn: SequenceDefinition<T>): Sequence<T>;

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deeply make objects partial, but ignoring arrays.
+ */
+export type DeepPartial<T> = T extends Array<any> ? T : T extends Record<string, any> ? {
+    [key in keyof T]?: DeepPartial<T[key]>;
+} : T;
+/**
+ * Deep merge objects, not arrays. Only override values with `null`, `undefined` does not override the base value.
+ */
+export declare function deepMerge<T>(base: T, overrides: DeepPartial<T>): T;
+export type FactoryDefaults<T> = T extends Array<any> ? T | (() => T) : T extends Record<string, any> ? {
+    [key in keyof T]: FactoryDefaults<T[key]>;
+} : T extends Function ? never : T | (() => T);
+export declare function resolveDefaults<T extends Record<string, any>>(val: FactoryDefaults<T>): T;

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@aklinker1/zero-factory",
+  "description": "Zero dependency object factory generator for testing",
+  "version": "0.1.1",
+  "packageManager": "bun@1.2.20",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "build": "bun run build.ts"
+  },
+  "devDependencies": {
+    "@aklinker1/check": "^2.1.0",
+    "@types/bun": "latest",
+    "jsr": "^0.13.5",
+    "oxlint": "^1.11.2",
+    "prettier": "^3.6.2",
+    "publint": "^0.3.12",
+    "typescript": "^5"
+  }
+}