@nemmtor/ts-databuilders 0.0.1-alpha.7 → 0.0.1-alpha.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +113 -117
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,114 @@
1
1
  # 🧱 TS DataBuilders
2
2
  Automatically generate type-safe builder classes from your TypeScript types to write cleaner, more focused tests.
3
3
 
4
+ ## Installation
5
+ Install the package:
6
+ ```bash
7
+ # npm
8
+ npm install -D @nemmtor/ts-databuilders
9
+
10
+ # pnpm
11
+ pnpm add -D @nemmtor/ts-databuilders
12
+
13
+ # yarn
14
+ yarn add -D @nemmtor/ts-databuilders
15
+ ```
16
+
17
+ ## Configuration
18
+ All configuration is optional with sensible defaults.
19
+
20
+ ### Initialize Config File (optional)
21
+ Generate a default `ts-databuilders.json` configuration file:
22
+ ```bash
23
+ pnpm ts-databuilders init
24
+ ```
25
+ You can also generate configuration file by providing values step by step in an interactive wizard:
26
+ ```bash
27
+ pnpm ts-databuilders init --wizard
28
+ ```
29
+
30
+ ### Configure via CLI flags (optional:
31
+ ```bash
32
+ pnpm ts-databuilders --output-dir="src/__generated__" --jsdoc-tag=MyBuilder
33
+ ```
34
+ You can also provide configuration by going through interactive wizard:
35
+ ```bash
36
+ pnpm ts-databuilders --wizard
37
+ ```
38
+
39
+ ### Options Reference
40
+
41
+ | Name | Flag | Description | Default |
42
+ |---------------|-------------------------------------------------------|-----------------------------------------|----------------------|
43
+ | jsdocTag | `--jsdoc-tag` | JSDoc tag to mark types for generation | `DataBuilder` |
44
+ | outputDir | `--output-dir -o` | Output directory for generated builders | `generated/builders` |
45
+ | include | `--include -i` | Glob pattern for source files | `src/**/*.ts{,x}` |
46
+ | fileSuffix | `--file-suffix` | File suffix for builder files | `.builder` |
47
+ | builderSuffix | `--builder-suffix` | Class name suffix | `Builder` |
48
+ | defaults | `--default-string --default-number --default-boolean` | Default values for primitives | See example above |
49
+
50
+ **Priority:** CLI flags > Config file > Built-in defaults
51
+
52
+ ## Quick Start
53
+ **1. Annotate your types with JSDoc:**
54
+ ```ts
55
+ /**
56
+ * @DataBuilder
57
+ */
58
+ type User = {
59
+ id: string;
60
+ email: string;
61
+ name: string;
62
+ isActive: boolean;
63
+ }
64
+ ```
65
+ **2. Generate builders:**
66
+ ```bash
67
+ pnpm ts-databuilders
68
+ ```
69
+ For the `User` type above, you'll get:
70
+ ```ts
71
+ import type { User } from "...";
72
+ import { DataBuilder } from "./data-builder";
73
+
74
+ export class UserBuilder extends DataBuilder<User> {
75
+ constructor() {
76
+ super({
77
+ id: "",
78
+ email: "",
79
+ name: "",
80
+ isActive: false
81
+ });
82
+ }
83
+
84
+ withId(id: User['id']) {
85
+ return this.with({ id });
86
+ }
87
+
88
+ withEmail(email: User['email']) {
89
+ return this.with({ email });
90
+ }
91
+
92
+ withName(name: User['name']) {
93
+ return this.with({ name });
94
+ }
95
+
96
+ withIsActive(isActive: User['isActive']) {
97
+ return this.with({ isActive });
98
+ }
99
+ }
100
+ ```
101
+
102
+ **3. Use in your tests:**
103
+ ```ts
104
+ import { UserBuilder } from '...';
105
+
106
+ const testUser = new UserBuilder()
107
+ .withEmail('test@example.com')
108
+ .withIsActive(false)
109
+ .build();
110
+ ```
111
+
4
112
  ## Why?
5
113
  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:
6
114
  Imagine testing a case where document aggregate should emit an event when it successfully update it's content:
@@ -19,7 +127,7 @@ it('should emit a ContentUpdatedEvent', () => {
19
127
  expect(...);
20
128
  })
21
129
  ```
22
- Above code obfuscated with all of the default values you need to provide in order to satisfy typescript.
130
+ Above code is obfuscated with all of the default values you need to provide in order to satisfy typescript.
23
131
  Where in reality the only thing specific to this single test is the fact that some new content was provided to `updateContent` method.
24
132
 
25
133
  Imagine even more complex scenario:
@@ -77,113 +185,7 @@ it('should show validation error when email is invalid', async () => {
77
185
 
78
186
  This not only makes the test code less verbose but also highlights what is really being tested.
79
187
 
80
- ## Installation
81
- Install the package:
82
- ```bash
83
- # npm
84
- npm install -D @nemmtor/ts-databuilders
85
-
86
- # pnpm
87
- pnpm add -D @nemmtor/ts-databuilders
88
-
89
- # yarn
90
- yarn add -D @nemmtor/ts-databuilders
91
- ```
92
-
93
- ## Quick Start
94
- **1. Annotate your types with JSDoc:**
95
- ```ts
96
- /**
97
- * @DataBuilder
98
- */
99
- type User = {
100
- id: string;
101
- email: string;
102
- name: string;
103
- isActive: boolean;
104
- }
105
- ```
106
- **2. Generate builders:**
107
- ```bash
108
- pnpm ts-databuilders
109
- ```
110
- **3. Use in your tests:**
111
- ```ts
112
- import { UserBuilder } from '...';
113
-
114
- const testUser = new UserBuilder()
115
- .withEmail('test@example.com')
116
- .withIsActive(false)
117
- .build();
118
- ```
119
- ## Generated Output
120
-
121
- For the `User` type above, you'll get:
122
- ```ts
123
- import type { User } from "...";
124
- import { DataBuilder } from "./data-builder";
125
-
126
- export class UserBuilder extends DataBuilder<User> {
127
- constructor() {
128
- super({
129
- id: "",
130
- email: "",
131
- name: "",
132
- isActive: false
133
- });
134
- }
135
-
136
- withId(id: User['id']) {
137
- return this.with({ id });
138
- }
139
-
140
- withEmail(email: User['email']) {
141
- return this.with({ email });
142
- }
143
-
144
- withName(name: User['name']) {
145
- return this.with({ name });
146
- }
147
-
148
- withIsActive(isActive: User['isActive']) {
149
- return this.with({ isActive });
150
- }
151
- }
152
- ```
153
- ## Configuration
154
- All configuration is optional with sensible defaults.
155
-
156
- ### Initialize Config File (optional)
157
- Generate a default `ts-databuilders.json` configuration file:
158
- ```bash
159
- pnpm ts-databuilders init
160
- ```
161
- You can also generate configuration file by providing values step by step in an interactive wizard:
162
- ```bash
163
- pnpm ts-databuilders init --wizard
164
- ```
165
-
166
- ### Configure via CLI flags (optional:
167
- ```bash
168
- pnpm ts-databuilders --output-dir="src/__generated__" --jsdoc-tag=MyBuilder
169
- ```
170
- You can also provide configuration by going through interactive wizard:
171
- ```bash
172
- pnpm ts-databuilders --wizard
173
- ```
174
-
175
- ### Options Reference
176
-
177
- | Name | Flag | Description | Default |
178
- |---------------|-------------------------------------------------------|-----------------------------------------|----------------------|
179
- | jsdocTag | `--jsdoc-tag` | JSDoc tag to mark types for generation | `DataBuilder` |
180
- | outputDir | `--output-dir -o` | Output directory for generated builders | `generated/builders` |
181
- | include | `--include -i` | Glob pattern for source files | `src/**/*.ts{,x}` |
182
- | fileSuffix | `--file-suffix` | File suffix for builder files | `.builder` |
183
- | builderSuffix | `--builder-suffix` | Class name suffix | `Builder` |
184
- | defaults | `--default-string --default-number --default-boolean` | Default values for primitives | See example above |
185
-
186
- **Priority:** CLI flags > Config file > Built-in defaults
188
+ [Read more about data builders.](http://www.natpryce.com/articles/000714.html)
187
189
 
188
190
  ## Nested Builders
189
191
  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.
@@ -375,23 +377,17 @@ Some TypeScript features are not yet supported and will cause generation errors:
375
377
 
376
378
  - typeof, keyof, any, unknown, bigint, symbol
377
379
 
378
- If you encounter an unsupported type, you'll see an error like:
379
- ```
380
- Unsupported syntax kind of id: XXX with raw type: YYY
381
- ```
382
- Support for above might be added in future.
383
-
384
380
  ### Alpha Stage
385
- ⚠️ **This library is in active development (v0.x.x)**
381
+ ⚠️ **This library is in active development**
386
382
 
387
- - Breaking changes may occur between minor versions
383
+ - Breaking changes may occur
388
384
  - Not all edge cases are covered yet
389
385
  - Test thoroughly before using in production
390
386
 
391
387
  **Found an issue?** Please [report it on GitHub](https://github.com/nemmtor/ts-databuilders/issues) with:
392
388
  - The type definition causing the issue
393
389
  - The error message received
394
- - Your `ts-databuilders.json` config (if applicable)
390
+ - Your `ts-databuilders.json` config and any provided CLI flags (if applicable)
395
391
 
396
392
  Your feedback helps improve the library for everyone! 🙏
397
393
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "@nemmtor/ts-databuilders",
4
- "version": "0.0.1-alpha.7",
4
+ "version": "0.0.1-alpha.8",
5
5
  "type": "module",
6
6
  "private": false,
7
7
  "description": "CLI tool that automatically generates builder classes from annotated TypeScript types.",