{"id":13721,"library":"optimal","title":"Optimal Schema Validator","description":"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.","status":"active","version":"5.1.1","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/milesj/optimal","tags":["javascript","opts","options","schema","predicate","validator","config","defaults","object","typescript"],"install":[{"cmd":"npm install optimal","lang":"bash","label":"npm"},{"cmd":"yarn add optimal","lang":"bash","label":"yarn"},{"cmd":"pnpm add optimal","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v5.0.0, optimal is an ESM-only package. The `optimal` function is a named export for creating object schemas.","wrong":"const optimal = require('optimal');","symbol":"optimal","correct":"import { optimal } from 'optimal';"},{"note":"Individual schema types like `string`, `number`, `array` are named exports. There is no default export for the package.","wrong":"import optimal, { string } from 'optimal';","symbol":"string","correct":"import { string } from 'optimal';"},{"note":"Validation failures throw `SchemaError` instances, which can be imported for specific error handling.","wrong":"import { OptimalError } from 'optimal';","symbol":"SchemaError","correct":"import { SchemaError } from 'optimal';"}],"quickstart":{"code":"// Import schemas to build validators with\nimport { array, string, number, optimal } from 'optimal';\n\n// Define and validate values with individual schemas\nconst maxSizeSchema = number().positive().lte(10000);\n\n// Or define an explicit shaped blueprint\nconst schema = optimal({\n  name: string().notEmpty().default('Default Name'),\n  include: array().of(string()).default([]),\n  exclude: array().of(string()).default([]),\n  maxSize: maxSizeSchema.default(5000)\n});\n\n// Pass a full or partial object to validate\ntry {\n  const options = schema.validate({ name: 'Optimal Project', maxSize: 8000 });\n  console.log('Validated options:', options);\n  // Expected output: { name: 'Optimal Project', include: [], exclude: [], maxSize: 8000 }\n\n  const defaultOptions = schema.validate({});\n  console.log('Default options:', defaultOptions);\n  // Expected output: { name: 'Default Name', include: [], exclude: [], maxSize: 5000 }\n} catch (error) {\n  console.error('Validation failed:', error);\n}","lang":"typescript","description":"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."},"warnings":[{"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).","message":"The `optimal` package became an ESM-only module starting with version 5.0.0. CommonJS `require()` statements will no longer work.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always assign the result of schema method calls back to a variable, e.g., `const newSchema = oldSchema.method();`.","message":"The 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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Wrap multiple schema arguments in an array: `optimal.or([schema1, schema2])`.","message":"The `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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Consult the official `optimal` v5 documentation (https://optimallib.dev) for updated usage patterns for defining object blueprints.","message":"The top-level `optimal()` function API was significantly reworked in version 5.0.0, especially for defining complex object schemas and blueprints.","severity":"breaking","affected_versions":">=5.0.0"}],"env_vars":null,"search_vec":"'5.1.1':28 '5kb':69 'across':155 'address':87 'alpha':82 'api':34 'applic':157 'approach':97 'automat':123 'boast':58 'browser':117 'bundl':65 'cadenc':75 'combin':143 'compil':104 'compile-tim':103 'complex':136 'config':164 'configur':42 'construct':36 'contract':154 'current':25 'data':153 'default':124,165 'defin':39,150 'definit':19 'depend':61 'design':11 'differenti':91 'enforc':152 'ensur':102 'environ':113 'featur':119 'field':46,127,132 'file':43 'first':96 'fix':88 'fluent':32 'focus':52 'footprint':57 'gzip':72 'immut':33 'infer':100 'involv':76 'javascript':7,158 'key':90 'librari':10,48 'like':120 'logic':137 'maintain':49 'major':78 'make':146 'minifi':70 'minim':56 'minor':85 'miss':126 'modern':116 'node.js':112 'object':40,166 'offer':98 'oper':108,138 'opt':159 'optim':1,4,147 'option':128,160 'patch':86 'perform':54 'period':77 'power':99 'preced':80 'predic':162 'provid':30,118 'recurs':121 'releas':74 'robust':13 'runtim':60 'safe':17 'safeti':106 'schema':2,18,37,144,161 'seamless':109 'size':66 'small':64 'strict':129 'strong':51 'structur':41 'suitabl':148 'support':134 'time':105 'transform':22 'type':16 'type-saf':15 'typescript':9,95,167 'typescript-first':94 'unknown':131 'updat':79 'v12.17':114 'valid':3,20,45,122,163 'valu':24 'various':156 'version':27,83 'xor':141 'zero':59","created_at":"2026-04-20T01:55:57.781337+00:00","updated_at":"2026-04-20T01:55:57.781337+00:00","problems":[{"fix":"Replace `const optimal = require('optimal');` with `import { optimal, string } from 'optimal';` and ensure your project is configured for ESM.","cause":"Attempting to use CommonJS `require()` to import `optimal` after it transitioned to an ESM-only package in v5.","error":"ReferenceError: require is not defined"},{"fix":"Examine the full error message, which typically indicates the specific field and the reason for validation failure. Adjust input data or schema definition.","cause":"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).","error":"OptimalError: Value \"...\" is invalid for \"...\""},{"fix":"Always capture the return value of schema methods: `const myStringSchema = string().notEmpty(); const myRequiredString = myStringSchema.required();`","cause":"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.","error":"TypeError: Cannot set properties of undefined (setting '...')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.2.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://optimal.js.org","github":"https://github.com/milesj/optimal","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/optimal","openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}