tcomb-builder
tcomb-builder is an immutable interface for tcomb-form
Install
npm install tcomb-builder tcomb-validation
Benefits
-
Immutability
-
Replaces deeply nested options objects in your codebase
-
Yields a standard tcomb type and options object
Syntax
If you use tcomb-form, you probably have a lot of code that looks like this:
; { return valuelength > 0 ? null : 'Please provide a value';} const FirstName = tcomb; FirstNamegetValidationErrorMessage = validation; const options = ..., label: 'First Name',}; // <tcomb.Form type={FirstName} options={options} />
This code has a few problems:
-
Mutability makes the type hard to reuse.
It is hard to reuse the FirstName type in another place that requires slightly modified validation, e.g. a max length restriction, because
getValidationErrorMessage
is set as a static function on the type. -
Mutability makes the options object hard to reuse.
Creating another field, e.g. 'Last Name', would require copy-pasting or
Object.assign
ing the options object. -
Nested options objects are hard to maintain.
If the above field is placed inside a
tcomb.struct
, the options object is deeply nested. The more structs, the more nesting.
Thanks to its immutable design, tcomb-builder offers a cleaner syntax that encourages code-reuse.
; ; { return valuelength > 0 ? null : 'Please provide a value';} const TextBuilder = ; const firstName = TextBuilder; // <tcomb.Form type={firstName.getType()} options={firstName.getOptions()} />
This code is equivalent to the first example, with the following advantages:
-
Immutability makes the type and options objects easy to reuse.
Making a
lastName
field is as easy asTextBuilder.setLabel('Last Name')
. Every.set
method returns a new builder, soTextBuilder
itself is never modified. -
Type and options objects are built together.
When using structs, you don't have to worry about maintaining parallel type and options structures. tcomb-builder is one interface for all of tcomb, tcomb-validation, and tcomb-form. The parallel structures are maintained internally and accessed with the
.getType
and.getOptions
methods.
Documentation
There is thorough documentation within the docs folder.
Start with the documentation on what this library exports (api.md) and the builder documentation (builder.md).
Background Reading
Example
Here is an example of a simple form. All primitives
and widgets
builders
extend the BaseBuilder
. Note that widgets
are primitives
that have a
template set on them.
; const name = widgetsTextBuilder; const dateOfBirth = widgetsTextBuilder ; const occupation = widgetsTextBuilder ; const bananaStand = widgetsCheckboxBuilder ;const chickenDance = widgetsCheckboxBuilder ;const hugeMistake = widgetsCheckboxBuilder ;const none = widgetsCheckboxBuilder ; const noneKey = 'isNone';const crossValidation = validators; const foodGroup = widgetsCheckboxGroupBuilder ; StructBuilder ;
Once exported, the page builder provides us with its tcomb type and options blob, which can be passed directly to tcomb-form without modification.
const type = InvestorInformationBuilder;const options = InvestorInformationBuilder;<tcombForm type=type options=options />
The end result, once tcomb template factories have been created for the underlying primitive types—text field, drop down, checkbox, and struct template primitives in this example—is that the form will render exactly as we expect it to.
Builders
Builders are composable, and this library uses three terms to describe them:
-
Primitives: Builders that define a single input (e.g. a text field) or a structure (e.g. struct); primitive builders are found in the primitives folder.
-
Widgets: Primitives that have a template provider already set on them. They are found in the widgets folder.
-
Forms: Builders that define an entire page (e.g. Credit Card Information); examples are found in the examples folder
Setting Templates
When you first set up tcomb-builder, it is recommended to create an instance of
LazyTemplateInterface
, which defines a mapping of component types to
templates. With this interface and the setLazyTemplateFactory
function, your
templates are defined in one place (the LazyTemplateInterface
), which makes
refactoring easier.
If you have a Node backend, you can use the same builders on both the client and server. The builders on the server will never realize the lazy templates, so you don't have to require React as a dependency on the server. See the API docs for more details.