optimal

library0.2.0jsnpmunverified

Optimal is a JavaScript and TypeScript library designed for robust and type-safe schema definition, validation, and transformation of values. Currently at version 5.1.1, it provides a fluent, immutable API for constructing schemas that define object structures, configuration files, and validation fields. The library maintains a strong focus on performance and minimal footprint, boasting zero runtime dependencies and a small bundle size of just 5kB minified and gzipped. Its release cadence involves periodic major updates preceded by alpha versions, with minor patches addressing fixes. A key differentiator is its TypeScript-first approach, offering powerful inference and ensuring compile-time safety. It operates seamlessly in both Node.js environments (v12.17+) and modern browsers, providing features like recursive validation, automatic defaulting of missing fields, optional strictness for unknown fields, and support for complex logical operators (AND, OR, XOR) to combine schemas. This makes `optimal` suitable for defining and enforcing data contracts across various applications.

serialization

npm install optimal

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OPTIMAL

optimal

serializationjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

optimal

✓ import { optimal } from 'optimal';

✗ const optimal = require('optimal');

Since v5.0.0, optimal is an ESM-only package. The `optimal` function is a named export for creating object schemas.

string

✓ import { string } from 'optimal';

✗ import optimal, { string } from 'optimal';

Individual schema types like `string`, `number`, `array` are named exports. There is no default export for the package.

SchemaError

✓ import { SchemaError } from 'optimal';

✗ import { OptimalError } from 'optimal';

Validation failures throw `SchemaError` instances, which can be imported for specific error handling.

This quickstart demonstrates how to define a complex object schema using `optimal`, including primitive types, arrays, default values, and custom validation predicates, then validates input data.

// Import schemas to build validators with import { array, string, number, optimal } from 'optimal'; // Define and validate values with individual schemas const maxSizeSchema = number().positive().lte(10000); // Or define an explicit shaped blueprint const schema = optimal({ name: string().notEmpty().default('Default Name'), include: array().of(string()).default([]), exclude: array().of(string()).default([]), maxSize: maxSizeSchema.default(5000) }); // Pass a full or partial object to validate try { const options = schema.validate({ name: 'Optimal Project', maxSize: 8000 }); console.log('Validated options:', options); // Expected output: { name: 'Optimal Project', include: [], exclude: [], maxSize: 8000 } const defaultOptions = schema.validate({}); console.log('Default options:', defaultOptions); // Expected output: { name: 'Default Name', include: [], exclude: [], maxSize: 5000 } } catch (error) { console.error('Validation failed:', error); }

Debug

Known issues

breakingThe `optimal` package became an ESM-only module starting with version 5.0.0. CommonJS `require()` statements will no longer work.

fix

Update all module imports from `require('optimal')` to `import { ... } from 'optimal';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` file extension).

affects: >=5.0.0

breakingThe API for defining and manipulating schemas became immutable in version 5.0.0. All schema methods (e.g., `.nullable()`, `.default()`) now return a *new* schema instance instead of modifying the existing one in place.

fix

Always assign the result of schema method calls back to a variable, e.g., `const newSchema = oldSchema.method();`.

affects: >=5.0.0

breakingThe `and()`, `or()`, and `xor()` schema methods in version 5.0.0 and later now expect an *array* of schemas as their argument, instead of variadic arguments.

fix

Wrap multiple schema arguments in an array: `optimal.or([schema1, schema2])`.

affects: >=5.0.0

breakingThe top-level `optimal()` function API was significantly reworked in version 5.0.0, especially for defining complex object schemas and blueprints.

fix

Consult the official `optimal` v5 documentation (https://optimallib.dev) for updated usage patterns for defining object blueprints.

affects: >=5.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use CommonJS `require()` to import `optimal` after it transitioned to an ESM-only package in v5.

fix

Replace `const optimal = require('optimal');` with `import { optimal, string } from 'optimal';` and ensure your project is configured for ESM.

OptimalError: Value "..." is invalid for "..."

The input data provided to `schema.validate()` does not conform to the rules defined in the schema (e.g., wrong type, failed predicate, missing required field).

fix

Examine the full error message, which typically indicates the specific field and the reason for validation failure. Adjust input data or schema definition.

TypeError: Cannot set properties of undefined (setting '...')

In `optimal` v5+, schema methods return *new* instances. If you don't assign the result of a method call, subsequent operations will apply to an un-configured or `undefined` schema.

fix

Always capture the return value of schema methods: `const myStringSchema = string().notEmpty(); const myRequiredString = myStringSchema.required();`

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/milesj/optimal ↗

packagehttps://www.npmjs.com/package/optimal ↗

homepagehttps://optimal.js.org ↗