# builder-pattern

> Create a builder pattern for Typescript using ES6 proxy.

Latest version **2.2.0** (published 2022-12-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install builder-pattern
pnpm add builder-pattern
yarn add builder-pattern
bun add builder-pattern
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.0 |
| Published | 2022-12-11 |
| First published | 2017-10-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 28.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 223 |
| Maintainers | vincentpang |

## Links

- npm: https://www.npmjs.com/package/builder-pattern
- Repository: https://github.com/Vincent-Pang/builder-pattern
- npm.io page: https://npm.io/package/builder-pattern

## Recent versions

- 2.2.0 (latest) — 2022-12-11
- 2.1.0 — 2022-10-14
- 2.0.0 — 2022-08-30
- 1.3.0 — 2021-03-16
- 1.2.4 — 2019-12-30
- 1.2.3 — 2019-11-21
- 1.2.2 — 2019-08-08
- 1.2.1 — 2019-06-13
- 1.2.0 — 2019-03-22
- 1.1.1 — 2018-09-20
- 1.1.0 — 2018-09-10
- 1.0.2 — 2018-01-24
- 1.0.1 — 2017-10-13
- 1.0.0 — 2017-10-12
- 0.0.3 — 2017-10-12
- … 1 more at https://npm.io/package/builder-pattern/versions

## README

# builder-pattern

Create a builder pattern for Typescript using ES6 proxy.

## Installation

```
yarn add builder-pattern
```

## Usage

### Basic usage
```typescript
interface UserInfo {
  id: number;
  userName: string;
  email: string;
}

const userInfo = Builder<UserInfo>()
                   .id(1)
                   .userName('foo')
                   .email('foo@bar.baz')
                   .build();
```
To get value from existing builder, just call the method without parameter, current value will be returned.
```typescript
const builder = Builder<UserInfo>();

builder.id(1);
console.log(builder.id());        // 1

console.log(builder.userName());  // undefined
builder.userName('foo');
console.log(builder.userName());  // foo

const userInfo = builder.build();
```

A note of caution: when building objects from scratch, the builder currently cannot ensure that all
mandatory fields have been set. The built object might thus violate the contract of the given interface.
For example, the following will compile (see also the example in the tests):

```typescript
const brokenUserInfo = Builder<UserInfo>()
                         .build();
```
A way around this is to use template objects (see Usage with template objects).

Another way is to use StrictBuilder (see Usage with StrictBuilder).

### Usage with template objects

You can also specify a template object, which allows easy creation of variation of objects.
This is especially useful for making test data setup more readable:

```typescript
const defaultUserInfo: UserInfo = {
  id: 1,
  userName: 'foo',
  email: 'foo@bar.baz'
};

const modifiedUserInfo = Builder(defaultUserInfo)
                          .id(2)
                          .build();
```
Notes:
- With this approach, if the template object conforms to the interface, the
built object will, too.
- The builder will effectively create and modify a shallow copy of the template object.

### Usage with class object

You can also specify a class object.

```typescript
class UserInfo {
  id!: number;
  userName!: string;
  email!: string;
}

const userInfo = Builder(UserInfo)  // note that ( ) is used instead of < > here
                   .id(1)
                   .userName('foo')
                   .email('foo@bar.baz')
                   .build();

```

Moreover, you can also specify a class object with a template object.

```typescript
class UserInfo {
  id!: number;
  userName!: string;
  email!: string;
}

const userInfo = Builder(UserInfo, {id: 1, userName: 'foo'})
                   .userName:('foo bar')
                   .email('foo@bar.baz')
                   .build();

```

### Usage with StrictBuilder

`StrictBuilder` is used to make sure all variables are initialized.

```typescript
interface UserInfo {
  id: number;
  userName: string;
  email: string;
}

const userInfo = StrictBuilder<UserInfo>()
                   .id(1)
                   .build(); // This expression is not callable.
                             // Type 'never' has no call signatures.ts(2349)
```

All variables must be initialized before calling `build()`.

```typescript
const userInfo = StrictBuilder<UserInfo>()
                   .id(1)
                   .userName('foo')
                   .email('foo@bar.baz')
                   .build();  // build() is called successfully
```

Notes:
`StrictBuilder` does not support template object nor class.

## Contributing

1. Fork it!
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Submit a pull request :D

## Credits

The idea is by unional and jcalz.
Please refer to the [stackoverflow question](https://stackoverflow.com/questions/45291644/builder-pattern-using-typescript-interfaces).

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

---
_Source: https://npm.io/package/builder-pattern · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._