@nemmtor/ts-databuilders 0.0.1-alpha.5 → 0.0.1-alpha.6

package/README.md

@@ -1,97 +1,9 @@
 # 🧱 TS DataBuilders
-A CLI tool that automatically generates builder classes from annotated TypeScript types.
+Automatically generate type-safe builder classes from your TypeScript types to write cleaner, more focused tests.
 
-## Usage
-Install the package:
-```bash
-pnpm add -D @nemmtor/ts-databuilders
-```
-
-Annotate the types you want to build with JsDoc tag:
-```ts
-/**
- * @DataBuilder
- */
-type Example = {
-  bar: string;
-  baz: string;
-}
-```
-
-Run the command:
-```bash
-pnpm ts-databuilders
-```
-By default it tries to find annotated types in `src/**/*.ts{,x}` and outputs builders in `generated/builders`.
-Above and much more is configurable - check out configuration section.
-
-Above example will result in output:
-```ts
-import type { Example } from "../../src/example";
-import { DataBuilder } from "./data-builder";
-
-export class ExampleBuilder extends DataBuilder<Example> {
-    constructor() {
-        super({
-          bar: "",
-          baz: ""
-        });
-    }
-
-    withBar(bar: Example['bar']) {
-        return this.with({ bar: bar });
-    }
-
-    withBaz(baz: Example['baz']) {
-        return this.with({ baz: baz });
-    }
-}
-```
-
-## Configuration
-> [!NOTE]
-> Name column is equal to field names in ts-databuilders.json file.
-
-| Name          | Flag            | Description                                                    | Default                                          | Type       |
-|---------------|-----------------|----------------------------------------------------------------|--------------------------------------------------|------------|
-| jsdocTag      | --jsdoc-tag      | JSDoc tag used to mark types for data building generation.     | DataBuilder                                      | string     |
-| outputDir     | --output-dir -o  | Output directory for generated builders.                       | generated/builders                               | string     |
-| include       | --include -i    | Glob pattern for files included while searching for jsdoc tag. | src/**/*.ts{,x}                                  | string     |
-| fileSuffix    | --file-suffix   | File suffix for created builder files.                         | .builder                                         | string     |
-| builderSuffix | --builder-suffix | Suffix for generated classes.                                  | Builder                                          | string     |
-| defaults      | --defaults      | Default values to be used in data builder constructor.         | {   string: '',   number: 0,   boolean: false, } | object/map |
-
-All of the above flags are optional and are having sensible defaults which should be good enough for most cases.
-You can configure these via cli flags or by creating `ts-databuilders.json` file in the root of your repository.
-Example of config file:
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/nemmtor/ts-databuilders/refs/heads/main/schema.json",
-  "include": "example-data/**",
-  "builderSuffix": "GeneratedBuilder",
-  "fileSuffix": ".generated-builder",
-  "jsdocTag": "GenerateBuilder",
-  "outputDir": "generated-builders/",
-  "defaults": {
-    "boolean": true,
-    "number": 2000,
-    "string": "foo"
-  }
-}
-```
-
-Priority when resolving config values is:
-1. Cli flags
-2. Config file values
-3. Hardcoded defaults
-
-## Motivation
-When writing tests you often want to test some scenario that is happening when
-one of the input values is in a specific shape.
-Often times this value is only one of many options provided.
-
-Imagine testing a case where document aggregate should emit an event when it successfully
-update it's content:
+## Why?
+Tests often become cluttered with boilerplate when you need to create complex objects just to test one specific field. DataBuilders let you focus on what matters:
+Imagine testing a case where document aggregate should emit an event when it successfully update it's content:
 ```ts
 it('should emit a ContentUpdatedEvent', () => {
   const aggregate = DocumentAggregate.create({
@@ -165,8 +77,330 @@ it('should show validation error when email is invalid', async () => {
 
 This not only makes the test code less verbose but also highlights what is really being tested.
 
-## Nested builders
-TODO
+## Installation
+Install the package:
+```bash
+# npm
+npm install -D @nemmtor/ts-databuilders
+
+# pnpm
+pnpm add -D @nemmtor/ts-databuilders
+
+# yarn
+yarn add -D @nemmtor/ts-databuilders
+```
+
+## Quick Start
+**1. Annotate your types with JSDoc:**
+```ts
+/**
+ * @DataBuilder
+ */
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  isActive: boolean;
+}
+```
+**2. Generate builders:**
+```bash
+pnpm ts-databuilders
+```
+**3. Use in your tests:**
+```ts
+import { UserBuilder } from '...';
+
+const testUser = new UserBuilder()
+  .withEmail('test@example.com')
+  .withIsActive(false)
+  .build();
+```
+## Generated Output
+
+For the `User` type above, you'll get:
+```ts
+import type { User } from "...";
+import { DataBuilder } from "./data-builder";
+
+export class UserBuilder extends DataBuilder<User> {
+    constructor() {
+        super({
+          id: "",
+          email: "",
+          name: "",
+          isActive: false
+        });
+    }
+
+    withId(id: User['id']) {
+        return this.with({ id });
+    }
+
+    withEmail(email: User['email']) {
+        return this.with({ email });
+    }
+
+    withName(name: User['name']) {
+        return this.with({ name });
+    }
+
+    withIsActive(isActive: User['isActive']) {
+        return this.with({ isActive });
+    }
+}
+```
+## Configuration
+All configuration is optional with sensible defaults.
+### Via CLI flags:
+```bash
+pnpm ts-databuilders --output-dir="src/__generated__" --jsdoc-tag=MyBuilder
+```
+### Via config file (`ts-databuilders.json`):
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/nemmtor/ts-databuilders/refs/heads/main/schema.json",
+  "include": "src/**/*.ts",
+  "outputDir": "src/__generated__/builders",
+  "jsdocTag": "DataBuilder",
+  "fileSuffix": ".builder",
+  "builderSuffix": "Builder",
+  "defaults": {
+    "string": "",
+    "number": 0,
+    "boolean": false
+  }
+}
+```
+
+### Options Reference
+
+| Name          | Flag              | Description                                      | Default                     |
+|---------------|-------------------|--------------------------------------------------|-----------------------------|
+| jsdocTag      | `--jsdoc-tag`     | JSDoc tag to mark types for generation           | `DataBuilder`               |
+| outputDir     | `--output-dir -o` | Output directory for generated builders          | `generated/builders`        |
+| include       | `--include -i`    | Glob pattern for source files                    | `src/**/*.ts{,x}`           |
+| fileSuffix    | `--file-suffix`   | File suffix for builder files                    | `.builder`                  |
+| builderSuffix | `--builder-suffix`| Class name suffix                                | `Builder`                   |
+| defaults      | `--defaults`      | Default values for primitives                    | See example above           |
+
+**Priority:** CLI flags > Config file > Built-in defaults
+
+## Nested Builders
+When your types contain complex nested objects, you can annotate their type definitions and TS DataBuilders will automatically generate nested builders, allowing you to compose them fluently.
+### Example
+
+**Input types:**
+```ts
+/**
+ * @DataBuilder
+ */
+export type User = {
+  name: string;
+  address: Address;
+};
+
+/**
+ * @DataBuilder
+ */
+export type Address = {
+  street: string;
+  city: string;
+  country: string;
+};
+```
+**Generated builders:**
+```ts
+export class UserBuilder extends DataBuilder<User> {
+    constructor() {
+        super({
+          name: "",
+          address: new AddressBuilder().build();
+        });
+    }
+
+    withName(name: User['name']) {
+        return this.with({ name });
+    }
+
+    withAddress(address: DataBuilder<User['address']>) {
+        return this.with({ address: address.build() });
+    }
+}
+
+export class AddressBuilder extends DataBuilder<Address> {
+    constructor() {
+        super({
+          street: "",
+          city: "",
+          country: ""
+        });
+    }
+
+    withStreet(street: Address['street']) {
+        return this.with({ street });
+    }
+
+    withCity(city: Address['city']) {
+        return this.with({ city });
+    }
+
+    withCountry(country: Address['country']) {
+        return this.with({ country });
+    }
+}
+```
+**Usage:**
+```ts
+// ✅ Compose builders fluently
+const user = new UserBuilder()
+  .withName('John Doe')
+  .withAddress(
+    new AddressBuilder()
+      .withStreet('123 Main St')
+      .withCity('New York')
+  )
+  .build();
+// {..., address: { street: "123 Main st", city: "New York", country: "" } }
+
+// ✅ Use default values
+const userWithDefaultAddress = new UserBuilder().build();
+// {..., address: { street: "", city: "", country: "" } }
+
+// ✅ Override just one nested field
+const userWithCity = new UserBuilder()
+  .withAddress(
+    new AddressBuilder()
+      .withCity('San Francisco')
+  )
+  .build();
+// {..., address: { street: "", city: "San Francisco", country: "" } }
+```
+
+### Supported Types
+
+The library supports a wide range of TypeScript type features:
+
+✅ **Primitives & Built-ins**
+- `string`, `number`, `boolean`, `Date`
+- Literal types: `'active' | 'inactive'`, `1 | 2 | 3`
+
+✅ **Complex Structures**
+- Objects and nested objects
+- Arrays: `string[]`, `Array<number>`
+- Tuples: `[string, number]`
+- Records: `Record<string, string>` `Record<'foo' | 'bar', string>`
+
+✅ **Type Operations**
+- Unions: `string | number | true | false`
+- Intersections: `A & B`
+- Utility types: `Pick<T, K>`, `Omit<T, K>`, `Partial<T>`, `Required<T>`, `Readonly<T>`, `Extract<T, U>`, `NonNullable<T>`
+- Branded types: `type UserId = string & { __brand: 'UserId' }`
+
+✅ **References**
+- Type references from the same file
+- Type references from other files
+- External library types (e.g., `z.infer<typeof schema>`)
+
+**For a comprehensive example** of supported types, check out the [example-data/bar.ts](https://github.com/nemmtor/ts-databuilders/blob/main/example-data/bar.ts) file in the repository. This file is used during development and demonstrates complex real-world type scenarios.
+
+## Important Rules & Limitations
+
+### Unique Builder Names
+Each type annotated with the JSDoc tag must have a **unique name** across your codebase:
+```ts
+// ❌ Error: Duplicate builder names
+// In file-a.ts
+/** @DataBuilder */
+export type User = { name: string };
+
+// In file-b.ts
+/** @DataBuilder */
+export type User = { email: string };  // 💥 Duplicate!
+```
+
+### Exported Types Only
+Types must be **exported** to generate builders:
+```ts
+// ❌ Won't work
+/** @DataBuilder */
+type User = { name: string };
+
+// ✅ Works
+/** @DataBuilder */
+export type User = { name: string };
+```
+
+### Type Aliases Only
+Currently, only **type aliases** are supported as root builder types. Interfaces, classes, and enums are not supported:
+```ts
+// ❌ Not supported
+/** @DataBuilder */
+export interface User {
+  name: string;
+}
+
+// ❌ Not supported
+/** @DataBuilder */
+export class User {
+  name: string;
+}
+
+// ✅ Supported
+/** @DataBuilder */
+export type User = {
+  name: string;
+};
+```
+
+### Unsupported Type Features
+
+Some TypeScript features are not yet supported and will cause generation errors:
+
+- **Recursive types**: Types that reference themselves
+```ts
+  // ❌ Not supported
+  type TreeNode = {
+    value: string;
+    children: TreeNode[];  // Self-reference
+  };
+```
+
+- **Function types**: Properties that are functions
+```ts
+  // ❌ Not supported
+  type WithCallback = {
+    onSave: (data: string) => void;
+  };
+```
+
+- typeof, keyof, any, unknown, bigint, symbol
+
+If you encounter an unsupported type, you'll see an error like:
+```
+Unsupported syntax kind of id: XXX with raw type: YYY
+```
+Support for above might be added in future.
+
+### Alpha Stage
+⚠️ **This library is in active development (v0.x.x)**
+
+- Breaking changes may occur between minor versions
+- Not all edge cases are covered yet
+- Test thoroughly before using in production
+
+**Found an issue?** Please [report it on GitHub](https://github.com/nemmtor/ts-databuilders/issues) with:
+- The type definition causing the issue
+- The error message received
+- Your `ts-databuilders.json` config (if applicable)
+
+Your feedback helps improve the library for everyone! 🙏
+
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR on [GitHub](https://github.com/nemmtor/ts-databuilders).
+
+## License
 
-## Supported types
-TODO
+MIT © [nemmtor](https://github.com/nemmtor)

package/package.json

@@ -58,5 +58,5 @@
     "glob": "^11.0.3",
     "ts-morph": "^27.0.2"
   },
-  "version": "0.0.1-alpha.5"
+  "version": "0.0.1-alpha.6"
 }