object-builder

Builder pattern for objects.

About

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.

Installation

Simply run:

npm i @heap-code/object-builder

CDN

Thanks to jsdelivr, this package can easily be used in browsers like this:

<script
 src="https://cdn.jsdelivr.net/npm/@heap-code/object-builder/dist/bundles/object-builder.umd.js"
 type="application/javascript"
></script>

Note:
It is recommended to use a minified and versioned bundle.

For example:

<script
 src="https://cdn.jsdelivr.net/npm/@heap-code/object-builder@0.1.3/dist/bundles/object-builder.umd.min.js"
 type="application/javascript"
></script>

More at this jsdelivr package page.

Usage

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.
    Simulates the this keyword (here).

Simple object

To create a simple object, that does not refer to itself, could be created as follows:

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)); // => `4`

method and property types are inferred.

Equivalent to the class:

class MyClass {
 property = 10;
 method(n: number) {
  return n * 2;
 }
}

const myClass = new MyClass();
console.log(myClass.property);
console.log(myClass.method(2));

With an initial pattern

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.

import { ObjectBuilder } from "@heap-code/object-builder";

interface Pattern {
 method: (n: number) => number;
 property: number;
}

const { method, property } = ObjectBuilder.create<Pattern>()
 .with("property", () => 10)
 // `n` type is deduced from the pattern
 .with("method", () => n => n * 2)
 .build();

Equivalent to the class:

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.

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<Product>();

Incomplete Product

When trying to build from a pattern without all handlers defined, a special type is returned to invalidate the type of the product.

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<Pattern>();
const product2 = ObjectBuilder.create<Pattern>()
 .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.

Use of self

The first parameter of an handler is the created product.
It corresponds to this in a class.

import { ObjectBuilder } from "@heap-code/object-builder";

ObjectBuilder.create()
 .with("property", () => 10)
 .with("method", self => (n: number) => n * self.property);

Equivalent to the class:

class MyClass {
 property = 10;
 method(n: number) {
  return n * this.property;
 }
}

Recursion

Recursion is easily possible with a pattern (initial pattern).

But without it, the type must be set manually when using with:

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.

Override

A key can be overridden any time.

It simulates an extends and provide a way to reuse the previous implementation (prev).

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:

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

Releases

See information about breaking changes and release notes here.