Schisma

Schisma is a zero-dependency object schema creator, validator, conformer, and object instantizer.

Features

Schema Creation

Creation of new schemas is easy.

const schisma = require('schisma')

let mySchema = schisma({
  name: String,
  age: {
    $type: Number,
    $default: () => new Date%104,
  },
  owns: {
    apples: Number,
    cats: [{
      hairless: Boolean,
      age: {
        $type: Number,
        $validate: (v) => {
          if (v > 38) {
            return {expected: '<=38', received: v}
          }
        },
      },
    }],
  },
})

Schema Definition Format

Objects passed to schisma can be declared a variety of ways.

• As a primitive type.
• As a null value.
• As a containing object.
• As a schisma-style object.
• As a Schisma instance.
• As an Array of any of the previous.

Primitive Types

The simplest way of declaring the value a key is supposed to represent is with a primitive type.

{
  name: String,
  age:  Number,
}

Null Value

Null values can be used to declare a field to be null or, if as part of a $typeof Array, that it can be null or otherwise.

{
  alwaysNull: null,
  age: {
    $typeof: [Number, null]
  }
}

Containing Objects

Objects can be used to compose more complex schemas. The key-value pairs can use any of the standard methods outlined earlier.

{
  mouse: {
    manufacturer: String,
    buttons: Number,
    dpi: Number,
  },
}

Regular expression key matching

Regular expressions can also be used via the special $/ key prefix. These allow schemas to receive arbitrary keys that map to concrete types. The value of these regex keys must always be an array of desired types.

{
  "$/.*": [Number],
}

Multiple regular expressions can be used. Matching attempts will be done in order of declaration.

{
  "$/*": [Number],
  "$/(.*)key": [String],
}

Regular keys may be mixed freely and take priority over regex matching.

{
  "$/*": [Number],
  "$/(.*)key": [String],
  myProperty: Boolean,
}

Schisma-style Object

A Schisma-style object can also be used.

{
  $type: Number,
  $default: 20,
}

{
  $typeof: [Number, String],
  $default: 20,
}

Unlike the other value declarations, schisma-style objects are how you can provide validation and default value generation.

• $type - May be a primitive type, an array, or another object, as per the schisma formatting rules.
• $typeof [] - An array of any of the types allowed within $type. This limits the given field/object's type to be one of the provided types. If $type and $typeof are used in the same declaration, $type will be ignored.
• [$default] <Any|Function> - The default value to use when inserting a value or generating a default object. If it is a function, then the return value of said function is used.
• [$required] - Whether the value should be considered as required for validation and conforming. Defaults to true
• [$validate] <Function(value,where)> - The function used to validate the value. May return an object that is merged with the resulting SchismaError with any of the following fields. Additionally, if a plain string is returned, it is used as the message field.
  • [value] - The value of the entry. Defaults to the object's original value
  • [where] - Where in the tree the error occurred. Defaults to the full object path
  • [message] - Message of the error.
  • [expected] - Type expected to be seen.
  • [received] - Received type instead of the expected type.

{
  mouse: {
    manufacturer: {
      $type: String,
      $default: "Grojitech",
      $validate: v => {
        switch(v) {
          case 'Grojitech':
          case 'Bricoshift':
          case 'Tacerr':
          case 'Loresair:
            return
          default:
            return {expected: 'Grojitech, Bricoshift, Tacerr, or Loresair'}
        }
      },
    },
    buttons: {
      $type: Number,
      $default: () => { return new Date%2400 },
      $validate: v => {
        if (v < 1 || v > 10) {
          return {expected: 'greater than 1 and less than 10'}
        }
      }
    },
    dpi: {
      $type: Number,
      $required: true,
    }
  },
}

Schisma Instance

Schisma instances can also be used as values.

let ChildSchema = schisma({
  childPropA: Number,
  childPropB: String,
})

let ParentSchema = schisma({
  child: ChildSchema,
  children: [ChildSchema],
})

Schema Validation

A Schisma object can be used to validate provided objects.

let myPersonhood = {
  name: 'OXXO',
  height: 180,
  owns: {
    cats: [
      {
        hairless: true,
        age: 400,
      },
      {
        hairless: false,
        age: 10,
      },
      {
        hairless: 'maybe',
        age: 20,
      },
    ],
  },
}

mySchema.validate(myPersonhood)
/* Returns:
[
  SchismaResult { code: 'missing key', where: 'age' },
  SchismaResult { code: 'missing key', where: 'owns.apples' },
  SchismaResult {
    code: 'no match',
    where: 'owns.cats.2.hairless',
    expected: [Function: Boolean],
    received: 'string',
    value: 'maybe',
    __typeIndex: 0
  },
  SchismaResult {
    code: 'invalid',
    where: 'owns.cats.0.age',
    expected: '<=38',
    received: 400,
    value: 400
  },
  SchismaResult {
    code: 'unexpected key',
    where: 'height',
    received: 180
  }
]
*/

Options can also be passed to validate.

| option | value | default | description |-|-|-|-| | ignoreUnexpected | Boolean | false | Ignores unexpected object keys. | ignoreRequired | Boolean | false | Ignores required object keys. | ignoreShortArrays | Boolean | true | Ignores arrays that are shorter than the schema's array. | ignoreLongArrays | Boolean | true | Ignores arrays that are longer than the schema's array. | flattenErrors | Boolean | true | Flattens all errors to return as a single array rather than heirarchically. | filterNonErrors | Boolean | true | Filters out non error results.

mySchema.validate(myPersonhood, {ignoreUnexpected: true, ignoreRequired: true})
/* Returns:
[
  SchismaResult {
    code: 'no match',
    where: 'owns.cats.2.hairless',
    expected: [Function: Boolean],
    received: 'string',
    value: 'maybe',
    __typeIndex: 0
  },
  SchismaResult {
    code: 'invalid',
    where: 'owns.cats.0.age',
    expected: '<=38',
    received: 400,
    value: 400
  }
]
*/

Schema Conforming

Schisma can also conform an object to itself.

let conformedPerson = mySchema.conform(myPersonhood)
/* Returns:
{ name: 'OXXO',
  age: 89,
  owns:
   { apples: 0,
     cats:
      [ { hairless: true, age: 400 },
        { hairless: false, age: 10 },
        { hairless: true, age: 20 } ] } }
*/

Just like validate, conform can also take options to adjust the output.

| option | value | default | description |-|-|-|-| | removeUnexpected | Boolean | true | Removes unexpected object keys. | insertMissing | Boolean | true | Inserts missing object keys with default values. | growArrays | Boolean | false | Grow arrays to match the length of the schema's array. | shrinkArrays | Boolean | false | Shrink arrays to match the length of the schema's array. | populateArrays | Boolean | false | Populate empty arrays with default instances of their schema elements.

let conformedPerson2 = mySchema.conform(myPersonhood, {removeUnexpected: false, insertMissing: false})
/* Returns:
{ name: 'OXXO',
  owns:
   { cats:
      [ { hairless: true, age: 400 },
        { hairless: false, age: 10 },
        { hairless: true, age: 20 } ] },
  height: 180 }
*/

Schema Default Object Creation

Schisma can create a default object that conforms to its schema.

let newPerson = mySchema.create()
/* Returns:
{ name: '', age: 75, owns: { apples: 0, cats: [] } }
*/

Just like validate and conform, create can take options to adjust object creation.

| option | value | default | description |-|-|-|-| | populateArrays | Boolean | false | Populate arrays with default instances of their schema elements.

let newPerson = mySchema.create({populateArrays: false})
/* Returns:
{ name: '',
  age: 81,
  owns: { apples: 0, cats: [ { hairless: false, age: 0 } ] } }
*/