Getting Started

Installation

pnpm add @alexify/metaschema
# or
npm install @alexify/metaschema

Node.js 18 or newer. The package has no runtime dependencies.

Validate a value

const { Schema } = require('@alexify/metaschema');

const schema = Schema.from({
  name: {
    first: 'string',
    last: 'string',
    third: '?string',
  },
  age: 'number',
  levelOne: {
    levelTwo: {
      levelThree: { type: 'enum', enum: [1, 2, 3] },
    },
  },
  collection: { array: { array: 'number' } },
});

const data = {
  name: { first: 'a', last: 'b' },
  age: 5,
  levelOne: { levelTwo: { levelThree: 1 } },
  collection: [
    [1, 2, 3],
    [3, 5, 6],
  ],
};

console.log(schema.check(data));
// ValidationResult { valid: true, errors: [], issues: [] }

When the value does not match, check reports every problem it finds:

const result = schema.check({ name: { first: 'a' }, age: '5' });
console.log(result.valid); // false
console.log(result.errors);
// [
//   'Field "name.last" is required',
//   'Field "age" not of expected type: number',
//   'Field "levelOne" is required',
//   'Field "collection" is required'
// ]
result.issues[1];
// { code: 'type', path: ['age'], message: 'not of expected type: number', params: { expected: 'number', received: 'string' } }

errors is the list to print; issues is the same problems as data, for a form or an API response.

ESM and TypeScript

The package is CommonJS, and its named exports are visible to ESM:

import { Schema, Model } from '@alexify/metaschema';

Type declarations ship with the package (index.d.ts), so TypeScript needs no extra setup, and InferSchema<typeof schema> is the type of a value a schema accepts; see TypeScript.

Next steps

• Schema Syntax: every way to write a field.
• Validation: what check returns and how to add your own rules.
• Domain Models: entities, references and generated TypeScript.
• Why metaschema? and Compared with alternatives: where it fits among the other schema libraries.
• Migrating from 2.x: what changed in 3.x, if you come from 2.x.
• Migrating from 1.x: what changed in 2.0, if you come from 1.x.