@commodo/fields
Enables defining rich data models by decorating function instances with specified model fields. Additionally, it adds populate
and validate
methods, for populating model instances with data, and then validating it, respectively.
Usage
import { withFields, string, number, boolean, fields } from "@commodo/fields";
import { compose } from "ramda";
// User function (data model).
const User = compose(
withFields({
// A field which accepts string values.
email: string(),
// Set "list" to true in order to store a list of string values.
previousEmails: string({ list: true }),
// A field which accepts boolean values.
verified: boolean(),
// A field that consists of nested fields. It can accept an instance of Company data model,
// or a plain object, from which a new Company instance will be created upon value assignment.
company: fields({ instanceOf: Company }),
// A field which accepts number values. Additionally, with the passed "validation" callback,
// we are ensuring that the assigned value is greater than or equal to 30.
age: number({
validation: value => {
if (value < 30) {
throw Error("User too young.")
}
}
})
})
)();
// Company function (data model).
const Company = compose(
withFields({
name: string()
})
)();
// Let's create an instance of the User data model, and populate it with some data.
const user = new User();
user.populate({
email: "user3@email.com",
previousEmails: ["user2@email.com", "user1@email.com"],
age: 25,
verified: true,
company: {
name: "Awesome Company"
}
});
// Using the "validate" method, we can check if the assigned values are valid.
// This will throws an error with the "User too young" message.
async user.validate();
Available fields
Out of the box, there are four types of fields you can utilize:
-
string
- accepts string values -
number
- accepts number values -
boolean
- accepts boolean values -
fields
- accepts a plain object or an instance of anotherwithFields
function
In the following examples, all types of fields are utilized:
// Company function (data model).
const Company = compose(
withFields({
name: string()
})
)();
const User = compose(
withFields({
email: string(),
age: number(),
verified: boolean(),
company: fields({ instanceOf: Company })
})
)();
Data validation
Data-type validation
When a value is assigned to a field of a model instance, it is immediately validated on a data-type level, meaning you cannot pass a string value to a field that doesn't accept strings.
Consider the following example:
import { withFields, string, number } from "@commodo/fields";
const User = withFields({
name: string(),
age: number(),
})();
const user = new User();
// Will throw data type error, because we cannot populate the "age" field with a string
// value. Since the field accepts only numbers, the age must be an integer or a float.
user.age = "7";
// The same will happen here.
user.populate({ name: "Rex", age: "7", drools: false });
Data-type validation is always executed upon value assignment, synchronously.
Custom validation
Additionally, you can also add your own custom, business logic related, validation. Unlike the data-type validation, which happens immediately upon assigning the value to a field, the custom validation is triggered by calling the validate
method. Note that this method validates the whole model instance.
The following snippet shows how we can add your own custom validation and trigger it:
import { withFields, string, number } from "@commodo/fields";
const User = withFields({
name: string({
validate: value => {
if (!value) {
throw new Error("Name is required.");
}
}
}),
age: number({
validate: value => {
if (value && value < 2) {
throw new Error("Your dog is to young.");
}
}
})
})();
const user = new User();
// Will throw an error, since the dog is too young.
user.populate({ name: "Rex", age: 1 });
await user.validate();
// The age is now correct, but now the name is missing.
user.populate({ age: 2 });
await user.validate();
Unlike the data-type validation, custom validation can perform asynchronous operations.
Field options
Each field can accept a few options:
list: boolean
If set to true
, field will accept an null
or an array of values. When setting field value, if a single item in the passed array is of incorrect data type, an error will be thrown.
validation: Function
A function for validating the assigned value. Not for data-type validation (since it's already done upon assigning a value), but for checking if the value complies with custom logic, for example if the assigned value is greater than 20.
value: any
Additional higher order functions
Except options, fields can also be enhanced with a couple of provided higher order functions:
onGet: Function => Function
onSet: Function => Function
skipOnPopulate: Function => Function
setOnce: Function => Function
Reference
withFields(fields : { [string] : FieldFactory }): WithFieldsFunction
Creates a new function, whose instances contain defined fields and are decorated with a couple of useful methods.
### FieldFactory
WithFieldsFunction
Except fields, instances of WithFieldsFunction
are decorated with a couple of useful methods.
populate(data: Object): void
Populates fields with given data.
validate(): Promise<void>
Validates all fields.
getFields(): Array<Field>
Returns all fields.
getField(name: string): ?Field
Returns a single field.
clean(): void
Sets instance as clean.
isDirty(): boolean
Checks if instance is dirty.