value-schema

library4.0.0jsnpmunverified

value-schema is a declarative input validator for Node.js, TypeScript, Deno, and Bun. Version 4.0.0 (stable) provides schema-based validation with automatic type coercion, default values, trimming, and checksum support (e.g., Luhn). It simplifies the common web app pattern of existence check, type check, and domain check into a single, readable schema definition. Unlike JSON Schema or Joi, it offers built-in email, date, IPv4/IPv6, and credit card validators with compact syntax. It ships TypeScript types and supports ESM and CJS.

testing

npm install value-schema

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VALUE-SCHEMA

value-schema

testingjavascriptv4.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

✓ import vs from 'value-schema'

✗ const vs = require('value-schema')

Default ESM import. For CJS, use `const { default: vs } = require('value-schema');` or dynamic import.

Schema

✓ import { Schema } from 'value-schema'

✗ import Schema from 'value-schema'

Named export for type usage. The default export is a factory object.

VsNumber, VsString, etc.

✓ import { VsNumber, VsString } from 'value-schema'

✗ import vsNum from 'value-schema'

TypeScript users can import individual schema types for type annotations.

Demonstrates schema definition with various validators and applying to input, showing type coercion and default values.

import vs from 'value-schema'; const schemaObject = { id: vs.number({ minValue: 1 }), name: vs.string({ maxLength: { length: 16, trims: true } }), age: vs.number({ integer: vs.NUMBER.INTEGER.FLOOR_RZ, minValue: 0 }), email: vs.email(), state: vs.string({ only: ['active', 'inactive'] }), classes: vs.array({ separatedBy: ',', each: { schema: vs.number(), ignoresErrors: true } }), creditCard: vs.numericString({ separatedBy: '-', checksum: vs.NUMERIC_STRING.CHECKSUM_ALGORITHM.CREDIT_CARD }), remoteAddr: vs.string({ pattern: vs.STRING.PATTERN.IPV4 }), limit: vs.number({ ifUndefined: 10, integer: true, minValue: { value: 1, adjusts: true }, maxValue: { value: 100, adjusts: true } }), offset: vs.number({ ifUndefined: 0, integer: true, minValue: { value: 0, adjusts: true } }), }; const input = { id: '1', name: 'Pablo Picasso', birthday: '2000-01-02T03:04:05.678Z', age: 20.5, email: 'picasso@example.com', state: 'active', classes: '1,3,abc,4', creditCard: '4111-1111-1111-1111', remoteAddr: '127.0.0.1', limit: '0', }; try { const result = vs.applySchemaObject(schemaObject, input); console.log(result); } catch (err) { console.error(err.message); }

Debug

Known issues

breakingVersion 4.0.0 changed default import from `value-schema` to ESM; CJS `require` no longer works directly.

fix

Use `import vs from 'value-schema'` or `const vs = (await import('value-schema')).default;` for CJS.

affects: >=4.0.0

deprecatedThe `Schema` class constructor pattern is deprecated in favor of using the `vs` factory object.

fix

Replace `new Schema(...)` with `vs.object({...})` or `vs.applySchemaObject(...)`.

affects: >=3.0.0

gotchaCommon mistake: applying schema to `null` or `undefined` input throws instead of returning defaults. Use `ifUndefined` per field.

fix

Wrap call in try/catch or pre-validate input existence.

affects: >=4.0.0

breaking`vs.NUMBER.INTEGER` constants renamed: `ROUND` -> `ROUND_HALF_UP`, `FLOOR` -> `FLOOR_RZ`, etc.

fix

Update to new constant names from migration guide.

affects: >=4.0.0

gotchaThe `separatedBy` option for arrays does not trim whitespace; input like '1, 2' yields ['1', ' 2'].

fix

Use `vs.string({ trim: true })` for each element or pre-trim the string.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: vs is not a function

Using CJS `require` on ESM default export.

fix

Use `const vs = require('value-schema').default;` or switch to ESM `import vs from 'value-schema';`.

Cannot find module 'value-schema'

Package not installed or incorrect path.

fix

Run `npm install value-schema` and ensure correct import path.

vs.number is not a function

Importing the whole module as a different name (e.g., `import * as vs from 'value-schema'`) flattens exports.

fix

Use default import: `import vs from 'value-schema'`.

Error: Input is required

Passing undefined/null to `applySchemaObject` instead of an object.

fix

Ensure input is an object (use `{}` as fallback).

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/shimataro/value-schema ↗

packagevalue-schema ↗

homepagehttps://github.com/shimataro/value-schema#readme ↗