picosv (Pico Schema Validator)

picosv is pico schema validator (2.50 KB) based on JavaScript data types and written in vanilla JavaScript with no dependencies.

Usable on both the frontend and backend, this lightweight validator is able to validate JavaScript entities from schemas.

Install

1npm install picosv

Getting started

Picosv is designed to be easy to use. Here's how to get started with schema creation and entities validation.

Schema Creation

A schema in Picosv is an object that defines the structure of your data. The following types are supported: string, number (including bigint), boolean, array of primitives or objects, and objects themselves.

Here's a simple example:

1import { picosv, string, number } from 'picosv';
2
3const schema = {
4  name: string(),
5  age: number()
6};
7
8const picoSchema = picosv(schema);

And here's a more complex example with arrays and objects:

1import { picosv, array, object, string, number, boolean } from 'picosv';
2
3const schema = {
4  events: array(object({
5    type: string(),
6    content: object({
7      message: string(),
8      source: string(),
9    }),
10  })),
11  data: object({
12    foo: string(),
13    bar: number(),
14  }),
15  count: number(),
16  active: boolean(),
17};
18
19const picoSchema = picosv(schema);

Schema typing rules

• Only JS primitive types, arrays and objects are allowed
• Arrays with multiple types are not allowed (primitive or object)
• Empty arrays are not allowed

Primitive types

Primitives types can be defined with the following functions :

• string: string()
• number: number()
• bigint: bigint()
• boolean: boolean()

Examples :

1import {string, number, bigint, boolean} from 'picosv';
2
3const schema = {
4  a: string(),
5  b: number(),
6  c: bigint(),
7  d: boolean(),
8}

Objects

Objects can be defined with the object() function.

Object properties can be defined in two ways:

• generically using the object() function without parameter'
• in detail by describing the properties of the object as a object function parameter

In the first case, the properties of the object will not be checked.

Generic example :

1import {string, number, boolean, object} from 'picosv';
2
3const schema = {
4  event: string(),
5  count: number(),
6  active: boolean(),
7  data: object(),
8}

Detailed example :

1import {string, number, boolean, object} from 'picosv';
2
3const schema = {
4  event: string(),
5  count: number(),
6  active: boolean(),
7  data: object({
8    foo: 'string',
9    bar: 'number'
10  })
11}

Arrays

Arrays can be defined with the array() function.

They are two types of arrays :

• Array of primitives (ex: ['foo', 'bar'])
• Array of objects (ex: [{key: 'foo'}, {key: 'bar'}])

Primitive array example :

1import {string, number, boolean, array} from 'picosv';
2
3const schema = {
4  event: string(),
5  count: number(),
6  active: boolean(),
7  arr: array(string()),
8}

Object array example :

1import {string, number, boolean, object, array} from 'picosv';
2
3const schema = {
4  event: string(),
5  count: number(),
6  active: boolean(),
7  arr: array(object({
8    key: 'string',
9  }))
10}

Optionals

Optional properties can be defined with the optional() function.

All attributes can be optionals (primitives, objects, arrays), you just need to encapsulate the type declaration in a optional() function call.

Primitive example :

1import {string, number, boolean, optional} from 'picosv';
2
3const schema = {
4  event: string(),
5  count: optional(number()),
6  active: boolean(),
7}

Object example :

1import {string, number, boolean, optional, object} from 'picosv';
2
3const schema = {
4  event: string(),
5  count: number(),
6  active: boolean(),
7  data: optional(object({
8    foo: 'string',
9    bar: 'number'
10  }))
11}

Array example :

1import {string, number, boolean, optional, array, object} from 'picosv';
2
3const schema = {
4  event: string(),
5  count: number(),
6  active: boolean(),
7  arr: optional(array(object({
8    key: 'string',
9  }))),
10  arr2: optional(array(string())),
11}

Entities Validation

To validate an object against a schema, simply call the validate function in your picosv schema instance and pass the object to validate. The function will throw an error if the object does not match the schema.

Here's an example:

1import { picosv } from 'picosv';
2
3const picoSchema = picosv(schema);
4
5const object = {
6  events: [
7    { type: 'foo', content: { message: 'hello world!', source: 'blu' } }
8  ],
9  data: {
10    foo: 'test',
11    bar: 55
12  },
13  count: 42,
14  active: false
15};
16
17try {
18  picoSchema.validate(object);
19} catch (error) {
20  console.error(error);
21}

Typescript type inference

The library also provides Typescript type inference from your schemas.

Let's see how it's works :

First, declare your schema like this :

1import {string, number, boolean, object, array} from 'picosv';
2import type { FromSchema, SchemaType } from 'picosv';
3
4const schema = {
5  event: string(),
6  count: number(),
7  active: boolean(),
8  data: object({
9    foo: string(),
10    bar: number(),
11  }),
12  arr: array(string()),
13  events: array(object({
14    type: string(),
15    content: {
16      description: string(),
17      author: string(),
18      valid: boolean(),
19    }
20  })),
21} as const satisfies SchemaType;

Notice that the as const statifies SchemaType will validate that our schema respects the type SchemaType.

Then create your type :

1type YourAwesomeType = FromSchema<typeof schema>;

And thats it ! You can use the schema inferred type on your objects.

1const a: YourAwesomeType = {
2  count: 55,
3  active: false,
4  event: 'coucou',
5  data: {
6    bar: 55,
7    foo: "test",
8    infinite: {
9      infinity: 55
10    }
11  },
12  arr: ["foo", "bar"],
13  events: [{
14    type: "foo",
15    content: {
16      author: "blu",
17      description: "qwe",
18      valid: 42 // Error: Type 'number' is not assignable to type 'boolean'.
19    }
20  }]
21}

Benchmark

Library	Size (Minified)	Size (Minified + Gzipped)	Bench (simple schema)	Bench (complex schema)
Ajv	119.6 kb	35.2 kb	157,815,912 ops/sec	51,951,659 ops/sec
Picosv	2.53 kb	0.94 kb	53,005,826 ops/sec	5,918,499 ops/sec
Zod	60.9 kb	14.2 kb	5,089,661 ops/sec	709,588 ops/sec

Benchmark files are available in the src/benchmark directory

Contributors

• luciani-c
• gabrielDevlog