A powerful TypeScript library for building any complex type, 100% fluent within a single builder, arbitrarily nested, zero config, with full IntelliSense support and compile-time type & data safety mechanisms.
- Simple & Powerful: A single function to build any complex type, interface, array, tuple, record or object union
- Type-Safe: Full TypeScript support with compile-time validation
- Data-Safe: Prevents overwriting data or building incomplete objects
- Fluent API: Intuitive method chaining for object construction
- IntelliSense: Rich autocomplete and type hints in your IDE
- Flexible: Works with any valid TypeScript type structure
npm install ts-fluent-builder
# or
yarn add ts-fluent-builderimport { fluentBuilder } from 'ts-fluent-builder';
// Define your types
interface User {
id: number;
name: string;
email: string;
addresses: Address[];
}
interface Address {
street: string;
city: string;
country: string;
}
// Build objects fluently
const user = fluentBuilder<User>()
.id(1)
.name('John Doe')
.email('john@example.com')
.addressesArray()
.pushObject()
.street('123 Main St')
.city('New York')
.country('USA')
.build()
.push({
street: '456 Oak Ave',
city: 'Boston',
country: 'USA'
})
.buildAddresses()
.build();Creates a new fluent builder for the specified type.
Parameters:
T: The TypeScript type to build
Returns: A builder instance with functions ready to build the type
// objects
interface Person {
name: string;
age: number;
address: Address;
}
const person = fluentBuilder<Person>()
.name('Alice')
.age(30)
.addressObject()
.street('123 Main St')
.city('Springfield')
.country('USA')
.buildAddress()
.build();// arrays
const numbers = fluentBuilder<number[]>()
.push(1)
.push(2)
.push(3)
.build(); // [1, 2, 3]
interface TodoItem {
id: number;
title: string;
completed: boolean;
}
interface TodoList {
items: TodoItem[];
}
const todoList = fluentBuilder<TodoList>()
.itemsArray()
.pushObject()
.id(1)
.title('Buy groceries')
.completed(false)
.build()
.pushObject()
.id(2)
.title('Walk the dog')
.completed(true)
.build()
.buildItems()
.build();// tuples
const falsyValues = fluentBuilder<[boolean, number, bigint, string]>()
.index0(false)
.index1(0)
.index2(0n)
.index3('')
.buildArray();// polymorphic types via unions (currently only object unions are supported)
interface Shape {
type: string;
area: number;
}
interface Circle extends Shape {
type: 'circle';
radius: number;
}
interface Rectangle extends Shape {
type: 'rectangle';
width: number;
height: number;
}
const shapes = fluentBuilder<(Circle | Rectangle)[]>()
.pushObject()
.type('circle')
.area(Math.PI * 5 * 5)
.radius(5)
.buildElement()
.pushObject()
.type('rectangle')
.area(20)
.width(4)
.height(5)
.buildElement()
.buildArray();// records
interface Config {
url: string;
timeout: number;
enabled: boolean;
}
const config = fluentBuilder<Record<string, Config>>()
.set('production', {
url: 'https://api.example.com',
timeout: 5000,
enabled: true
})
.setObject('development')
.url('https://dev.api.example.com')
.timeout(10000)
.enabled(false)
.buildDevelopment()
.buildRecord();There are a few common patterns used:
.propertyName(value) // Set a property value on an object
.push(value) // Append to an array
.set(key, value) // Set a key value entry on a record
.indexN(value) // Set indexed value on a tuple.propertyNameArray() // Start building a nested array
.propertyNameObject() // Start building a nested object
.propertyNameRecord() // Start building a nested record
.pushArray() // Start building a nested array to push onto the array
.pushObject() // Start building a nested object to push onto the array
.pushRecord() // Start building a nested record to push onto the array
.indexNArray() // Start building a nested array at the array index
.indexNObject() // Start building a nested object at the array index
.indexNRecord() // Start building a nested record at the array index
.setArray(name) // Start building a nested array to set on the record
.setObject(name) // Start building a nested sub-type to set on the record
.setRecord(name) // Start building a nested record to set on the record// Build and return either the result or the parent builder for continued chaining
.build()
// all build...() functions are aliases of build() and can be used as hints to the developer, eg:
.buildPropertyName()
.buildRecordName()
.buildArray()
.buildObject()
.buildRecord()interface Company {
name: string;
departments: Department[];
settings: Record<string, any>;
}
interface Department {
name: string;
employees: Employee[];
budget: number;
}
interface Employee {
id: number;
name: string;
role: string;
}
const company = fluentBuilder<Company>()
.name('TechCorp')
.departmentsArray()
.pushObject()
.name('Engineering')
.budget(500000)
.employeesArray()
.pushObject()
.id(1)
.name('John Doe')
.role('Senior Developer')
.build()
.pushObject()
.id(2)
.name('Jane Smith')
.role('Tech Lead')
.build()
.buildEmployees()
.build()
.buildDepartments()
.settingsRecord()
.set('theme', 'dark')
.set('notifications', true)
.set('autoSave', false)
.buildSettings()
.build();The builder automatically handles optional properties and will only require you to set mandatory fields:
interface User {
id: number;
name: string;
email?: string; // optional
phone?: string; // optional
}
// This works - only required fields need to be set
const user = fluentBuilder<User>()
.id(1)
.name('John')
.build();
// Optional fields can be added
const fullUser = fluentBuilder<User>()
.id(1)
.name('John')
.email('john@example.com')
.phone('+1234567890')
.build();ts-fluent-builder prevents common type and data mistakes at compile time:
interface User {
id: number;
name: string;
email?: string; // optional
phone?: string; // optional
}
// ❌ This won't compile - missing required property
const invalid = fluentBuilder<User>()
.name('John')
// .id(1) - missing required field
.build();
// ❌ This won't compile - wrong type
const wrongType = fluentBuilder<User>()
.id('not-a-number') // id expects number
.build();
// ❌ This won't compile - tuple not completely filled
const missingTupleElement = fluentBuilder<[boolean, string, number]>()
.index0(true)
.index1('abc')
// .index2(123) - missing element
.build();
// ❌ This won't compile - duplicate property
const duplicateProperty = fluentBuilder<User>()
.id(1)
.id(2) // can't set id twice
.build();
// ❌ This won't compile - duplicate record key
const duplicateKey = fluentBuilder<Record<string, boolean>>()
.set('production', true)
.set('production', false) // can't set same key twice
.build();- Autocomplete for available properties
- Type hints for expected values
- Documentation in tooltips
- Error highlighting for type mismatches
-
Use TypeScript: ts-fluent-builder is designed for TypeScript and provides minimal value in plain JavaScript
-
Define Interfaces or Types First: Always define your types before using the builders
-
Leverage IntelliSense: Let your IDE guide you through the available methods
-
Use the build...() Aliases: Help later developers easily see where they're looking in the build chain
Contributions are very welcome! Please open an issue or submit a pull request on GitHub Issues.
This project is licensed under the MIT License - see the LICENSE file for details.
Happy Building!