Builder pattern for objects
npm install @heap-code/object-builder
!Code coverage
!Comment coverage
Builder pattern for objects.
This package allows to create objects with the Builder Pattern.
The builder can add different keys and overridden them.
The product (builded object) type can be constraint by a pattern or determined by its use.
> It is most useful with _typescript_.
Simply run:
``bash`
npm i @heap-code/object-builder
Thanks to _jsdelivr_,
this package can easily be used in browsers like this:
`html`
type="application/javascript"
>
> Note:
> It is recommended to use a minified and versioned bundle.
>
> For example:
>
> `html`
>
> type="application/javascript"
> >
>
More at this _jsdelivr_ package page.
The builder can be created for different uses.
Most of the examples give an example of use for an equivalent class.
The following terms are used:
- pattern: The _model_, that the product should satisfy when building.
It can be optional.
- product: the final object that is builded, regardless of the pattern.
- handler: the "constructor" for a given key.
- self: first parameter, reference to the builded product. this
Simulates the keyword (here).
To create a simple object, that does not refer to itself,
could be created as follows:
`typescript
import { ObjectBuilder } from "@heap-code/object-builder";
const { method, property } = ObjectBuilder.create()
.with("property", () => 10)
.with("method", () => (n: number) => n * 2)
.build();
console.log(property); // => 10
console.log(method(2)); // =>
> method and property types are inferred.
Equivalent to the class:
`typescript
class MyClass {
property = 10;
method(n: number) {
return n * 2;
}
}
const myClass = new MyClass();
console.log(myClass.property);
console.log(myClass.method(2));
`
A pattern can be use to constraint the builder.
Adding unknown keys, or wrongly type their handler, will result on a type error at compilation.
`typescript
import { ObjectBuilder } from "@heap-code/object-builder";
interface Pattern {
method: (n: number) => number;
property: number;
}
const { method, property } = ObjectBuilder.create
.with("property", () => 10)
// n type is deduced from the pattern`
.with("method", () => n => n * 2)
.build();
Equivalent to the class:
`typescript`
class MyClass implements Product {
property = 10;
method(n) {
return n * 2;
}
}
---
A pattern can also be set when calling build.
This "asks" that the output product satisfies the given pattern.
> More at this section.
`typescript
import { ObjectBuilder } from "@heap-code/object-builder";
interface Product {
method: (n: number) => number;
property: number;
}
// product satisfies Product
const product = ObjectBuilder.create()
.with("property", () => 10)
.with("method", () => (n: number) => n * 2)
.build
When trying to build from a pattern without all handlers defined,
a special type is returned to invalidate the type of the product.
`typescript
import { ObjectBuilder } from "@heap-code/object-builder";
interface Pattern {
method: (n: number) => number;
property: number;
}
const product1 = ObjectBuilder.create()
.with("method", () => (n: number) => n * 2)
.build
const product2 = ObjectBuilder.create
.with("method", () => n => n * 2)
.build();
`
> Both products are of a type incompatible with the pattern.
> This issue is already created to improve its behavior.
The first parameter of an handler is the created product.
It corresponds to this in a class.
`typescript
import { ObjectBuilder } from "@heap-code/object-builder";
ObjectBuilder.create()
.with("property", () => 10)
.with("method", self => (n: number) => n * self.property);
`
Equivalent to the class:
`typescript`
class MyClass {
property = 10;
method(n: number) {
return n * this.property;
}
}
Recursion is easily possible with a pattern (initial pattern).
But without it, the type must be set manually when using with:
`typescript
import { ObjectBuilder } from "@heap-code/object-builder";
ObjectBuilder.create()
.with<"count", (n: number) => number[]>(
"count",
self => n => (0 <= n ? [0] : [n, ...self.count(n - 1)]),
);
`
> The key (count) must also be defined or it can not be "injected" into self.
A key can be overridden any time.
It simulates an extends and provide a way to reuse the previous implementation (prev).
`typescript
import { ObjectBuilder } from "@heap-code/object-builder";
const builder1 = ObjectBuilder.create()
.with("property", () => 2)
.with("protected", self => (n: number) => n + self.property)
.with("method", self => (n: number) => 2 * self.protected(n));
const builder2 = builder1.override(
"protected",
(self, prev) => n => prev(n) + self.property,
);
const product1 = builder1.build();
const product2 = builder2.build();
console.log(product1.method(2)); // => 8
console.log(product2.method(2)); // => 12
`
Equivalent to the classes:
`typescript
class MyClass1 {
property = 2;
protected(n: number) {
return n + this.property;
}
method(n: number) {
return 2 * this.protected(n);
}
}
class MyClass2 extends MyClass1 {
override protected(n: number) {
return super.protected(n) + this.property;
}
}
const myClass1 = new MyClass1();
const myClass2 = new MyClass2();
console.log(myClass1.method(2)); // => 8
console.log(myClass2.method(2)); // => 12
``
See information about breaking changes and release notes here.