fluente
Make fluent objects like a boss!
Features
- Zero dependencies: small footprint.
- Protected state
- Selective mutability: choose between immutable objects or a classy object.
- Undo/Redo out of the box
- TypeScript support
Installation
npm install --save fluente
fluente(options)
Returns the build object.
-
options<Object>-
state<Object>Initial state. -
[constants]<Object>Constant values. -
[getters]<Object>Value getters. -
[fluents]<Object>Fluent methods. -
[mappers]<Object>Map (normal) methods. -
[mutable]<Boolean>See mutability. -
[historySize]<Number>See undo and redo. -
[produce]<Function>See state manipulation.
-
- Returns:
<Object>
Quickstart
The easiest way to create a fluent API is by returning the instance itself inside a class method.
class Calculator {
constructor (value = 0) {
this.value = value
}
add (value) {
this.value += value
return this // Fluent API
}
valueOf () {
return this.value
}
}
const calculator = new Calculator(0)
const value = calculator
.add(2)
.add(4)
.add(8)
.add(16)
.valueOf()
console.log(value) // 30Fluente provides a different way to declare fluent objects.
const fluente = require('fluente')
const symCalculator = Symbol('my_calculator')
function valueOf (state) {
return state.value
}
function add (state, value) {
return {
value: valueOf(state) + value
}
}
function subtract (state, value) {
return {
value: valueOf(state) - value
}
}
function multiply (state, value) {
return {
value: valueOf(state) * value
}
}
function divide (state, value) {
return {
value: valueOf(state) / value
}
}
function createCalculator (value = 0) {
return fluente({
// Enable state history (undo/redo)
historySize: 8,
// Initial state
state: {
value
},
// Object constants
constants: {
[symCalculator]: true
},
// Value getters
getters: {
value: valueOf,
integer: state => Number.isInteger(valueOf(state))
},
// Fluent methods
fluents: {
add,
subtract,
multiply,
divide
},
// Map (normal) methods
mappers: {
valueOf
}
})
}
const zero = createCalculator(0)
// Read constant value
if (zero[symCalculator] !== true) {
throw new Error('Expected calculator')
}
// Read value getters
console.log(zero.value, zero.integer) // 0 true
// Use fluent method
const pi = zero.add(Math.PI)
console.log(pi.value, pi.integer) // 3.141592653589793 false
const value = zero
.add(2)
.subtract(8)
.multiply(-1)
.divide(2)
.undo(2) // Undo 2 mutations: divide(2) and multiply(-1)
.redo(1) // Redo 1 mutation: multiply(-1)
.valueOf() // Use map method
console.log(value) // 6Like a constructor, Fluente returns an object. You can still declare methods, constants, and getters, but with a different signature. Functions do not use the this keyword to access the state. Instead, It's always passed as the first argument. Another key difference is how fluent methods mutate the state: by returning an object that contains the changed values.
These rules abstract the methods (and getters) definition and the state mutation, unlocking some cool features like selective mutability, state protection, and undo/redo.
Mutability
By default, all objects build by Fluente are immutable (all fluent methods will return a new object containing the updated state). You can retrieve mutable objects using the mutable option.
const fluente = require('fluente')
function createCalculator (initialValue = 0) {
return fluente({
mutable: true, // Request mutable object
state: {
value: initialValue
},
fluents: {
add (state, value) {
return {
value: state.value + value
}
}
},
mappers: {
valueOf (state) {
return state.value
}
}
})
}
const calculator = createCalculator(0)
calculator.add(40)
calculator.add(2)
console.log(calculator.valueOf()) // 42Undo and Redo
An isolated state enables easy undo-redo implementation. The current state represents the present moment. Applying a mutation move the present into the past, and set a new present state. Undoing a mutation will restore a state from the past, and move the present state into the future. Redoing a mutation will do the opposite. A more detailed example is available in this Redux article.
Fluente automatically injects undo-redo functions. Both functions optionally accept the number of mutations to apply, defaulting to 1 mutation. Infinity is accepted, and means "redo/undo all the mutations available".
The historySize option controls the max number of mutations remembered by Fluente. Set the historySize option to a positive number to enable this feature.
State manipulation
By default, all fluent functions need to return an updated state, even partially, to let Fluente know what is changed. Plus state needs to be treated as immutable. Those rules are necessary to ensure correct state isolation. The subtract function in the next example is updating the state's value property by returning an object containing that property.
function subtract (state, value) {
return {
value: state.value - value
}
}However, other state manipulation systems are viable through a custom Producer. A Producer is a function that accepts both state object and map function. Its purpose is to handle any map mutations applied against the state and then return a new and fully updated state.
const fluente = require('fluente')
function mySimpleProducer (oldState, mapper) {
// Clone current state
const newState = Object.assign({}, oldState)
// Run state mapper (may override some root properties now)
mapper(newState)
// Return updated state
return newState
}
function createCalculator (initialValue = 0) {
return fluente({
produce: mySimpleProducer, // Use a custom producer
state: {
value: initialValue
},
fluents: {
add (state, value) {
state.value += value // Direct state manipulation
}
},
mappers: {
valueOf (state) {
return state.value
}
}
})
}The easiest and safest way to support direct state manipulation is to use Immer's produce function.
const fluente = require('fluente')
const { produce } = require('immer')
function createCalculator (initialValue = 0) {
return fluente({
produce, // Use Immer to handle state changes
state: {
value: initialValue
},
fluents: {
add (state, value) {
state.value += value // Direct state manipulation
}
},
mappers: {
valueOf (state) {
return state.value
}
},
})
}Immutable.js is also supported.
const fluente = require('fluente')
const { Map } = require('immutable')
function valueOf (state) {
return state.get('value')
}
function add (state, value) {
return state.set('value', valueOf(state) + value)
}
function createCalculator (initialValue = 0) {
return fluente({
// Direct mapping (fluent mappers need to return the updated state)
produce: (state, mapper) => mapper(state),
// Initial state (init with Immutable.js)
state: Map({
value: initialValue
}),
fluents: {
add
},
mappers: {
valueOf
}
})
}