Recordari NPM | npm.io

	Master	Next
Tests
Coverage
Dependency Analysis

Recordjs is a type and structure validation tool for configuration files.

const { Record, R } = require('Recordari');

// 1) Create a Record of how the configurations should look
const RConfig = Record('MyConfig', {
  port: R.Number.Natural,
  env: R.String.Either(['dev', 'prod']),
  loglevel: R.String.Either(['none', 'error', 'warn', 'info', 'debug'])
});

// 2) Test the actual configurations against the Record
const config = RConfig(require('config.json')); // Will throw if any of the constraints fail

// 3) You can use all of the properties on config without worrying about some of them not being valid.
config.loglevel // Will ALWAYS be valid
config.port     // Will ALWAYS be valid
config.env      // Will ALWAYS be valid

NPM: npm install recordari

Using Recordjs

Using Recordjs is divided into two steps, the record constructions, and the record evaluation. In the construction you will be creating a sort of "template" for Recordjs to use in the evaluation step. This "template" is what we call a record and will be denoted by the capital R preceding the variable name. Ex: ROptions or RConfig.

Construction

When constructing a record you will be using the Record function provided by Recordjs. This function takes two arguments, the first is the name of the record (this can be anything you like), and the second is the constraint object (this is the important part).

const { Record } = require('Recordari');
const RDemo = Record('Demo', {
  // This is the constraint object
});

In essence "the constraint object should be a modified copy of the object that you are creating a record for", let me explain. Lets say you want to create a record for this object: { a: 42 } And lets assume that the application expects the property a to always be a number. We could then construct a constraint for the property a that asserts the type of the value to be a number, like this: R.Number

const { R, Record } = require('Recordari');
const RDemo = Record('Demo', {
  a: R.Number
});

R.Number is a constraint that tells Recordjs that when it evaluates an object against the Demo record, the property a should be a number.

You can read about all the available constraints here!

Evaluation

After you've constructed a record you can now use it to assert the validity of objects.

const { R, Record } = require('Recordari');
const RDemo = Record('Demo', {
  a: R.Number
});

const demo = RDemo({ a: 42 });
console.log(demo.a); // 42

As you can see above, the Record function returns a function. This function expects a single argument, and it expects this argument to be an object that complies to the constraints of the record that you previously constructed. If the argument does comply to the constraints, then function will act like the identity function (aka it will return the object that was passed in). If the argument does not comply to the constraints then the function will throw a TypeError.

const { R, Record } = require('Recordari');
const RDemo = Record('Demo', {
  a: R.Number
});

const demo = RDemo({ a: 'hi' }); // Will throw TypeError
console.log(demo.a); // Won't be executed

Constraints

See docs/constraints.md

A great way to explore the available constraints is through intellisense exploration. Either by using typescript or by using a typescript enabled editor with javascript (such as vscode).