ascertain 2.0.88 → 3.0.0

package/README.md

@@ -1,8 +1,6 @@
 # Ascertain
 
-### Ascertain what data is not suitable for your library
-
-0-Deps, simple, blazing fast, for browser and Node.js object schema validator
+Zero-dependency, high-performance schema validator for Node.js and browsers.
 
 [![Coverage Status][codecov-image]][codecov-url]
 [![Build Status][github-image]][github-url]
@@ -10,182 +8,354 @@
 [![Downloads][downloads-image]][npm-url]
 [![Snyk][snyk-image]][snyk-url]
 
-
 [Documentation](https://3axap4ehko.github.io/ascertain/)
 
 ## Features
 
-- Type-safe validation: Ensures your data conforms to predefined schemas.
-- Composite schemas: Supports logical AND, OR, and optional schemas.
-- Type casting: Automatically parses and casts strings to other types.
-- Error handling: Provides detailed error messages for invalid data.
+- **Zero dependencies** - Minimal footprint, no external dependencies
+- **High performance** - Compiles schemas to optimized JS functions (~6x faster than dynamic validation)
+- **Type-safe** - Full TypeScript support with type inference
+- **Flexible schemas** - AND, OR, optional, tuple, discriminated operators
+- **Type casting** - Built-in parsers for numbers (hex, octal, binary), dates, JSON, base64
+- **Object validation** - Validate keys/values with `$keys`, `$values`, `$strict`
+- **Partial validation** - `createValidator` validates subsets with type narrowing
+- **Detailed errors** - Clear error messages with paths for debugging
+- **Standard Schema v1** - Interoperable with tRPC, TanStack Form, and other ecosystem tools
+
+## Install
+
+```bash
+npm install ascertain
+```
 
-## Schema description
+## Quick Start
 
- - Primitive Values: Any primitive value (e.g., string, number, bigint, boolean, undefined, symbol, null) is used as an expected constant to match against.
- - Function Types: Functions are used as constructors for non-objects and instance types for object types.
- - Array Values: Arrays are used to represent an expected array type, where every item in the array must match the specified type (acting as an "and" operator).
- - Regular Expressions: Regular expressions are used to validate that a value matches a specified string pattern.
- - Object Types: Non-null objects are used as templates for expected properties, where each property of the object must match the corresponding schema definition.
+```typescript
+import { ascertain, or, optional } from 'ascertain';
 
+ascertain({
+  name: String,
+  age: Number,
+  role: or('admin', 'user'),
+  email: optional(String),
+}, userData);
+```
 
+## Performance
 
-## Usage Example
+Ascertain compiles schemas into optimized JavaScript functions. Compiled validators run **~6x faster** than dynamic validation.
 
-### Schema compilation
 ```typescript
-import { compile, optional, and, or, $keys, $values, Schema, as } from 'ascertain';
-
-const validate = compile({
-  number: Number,
-  string: String,
-  boolean: Boolean,
-  function: Function,
-  array: Array,
-  object: Object,
-  date: and(Date, { toJSON: Function }),
-  regexp: /regexp/,
-  oneOfValue: or(1, 2, 3),
-  arrayOfNumbers: [Number],
-  objectSchema: {
-    number: Number,
-  },
-  optional: optional({
-    number: Number,
-  }),
-  keyValue: {
-    [$keys]: /^key[A-Z]/,
-    [$values]: Number
-  },
-  parsedNumber: Number,
-  parsedString: String,
-  parsedBoolean: Boolean,
-  parsedArray: [String],
-  parsedJSON: {
-    number: 1,
-  },
-  parsedBase64: String,
-  parsedTime: 2 * 60 * 1000, // two minutes
-  parsedDate: Date,
+import { compile } from 'ascertain';
+
+// Compile once
+const validateUser = compile(userSchema);
+
+// Validate many (no recompilation)
+validateUser(user1);
+validateUser(user2);
+```
+
+| When to use | Function | Speed |
+|-------------|----------|-------|
+| Repeated validation (API handlers, loops) | `compile()` | Fastest |
+| One-off validation | `ascertain()` | Convenient |
+
+### Benchmark
+
+| Library | Mode | Valid (ops/s) | Invalid (ops/s) |
+|---------|------|---------------|-----------------|
+| **Ascertain** | first-error | 80M | 41M |
+| **Ascertain** | all-errors | 80M | 25M |
+| AJV | first-error | 52M | 35M |
+| AJV | all-errors | 52M | 20M |
+| Zod | all-errors | 34M | 77K |
+
+## Schema Reference
+
+| Schema | Validates | Example |
+|--------|-----------|---------|
+| `String`, `Number`, `Boolean` | Type check | `{ age: Number }` |
+| `Date`, `Array`, `Object` | Instance check | `{ created: Date }` |
+| `Function` | Any callable | `{ handler: Function }` |
+| Primitives | Exact value | `{ status: 'active' }` |
+| RegExp | Pattern match | `{ email: /^.+@.+$/ }` |
+| `[Schema]` | Array of type | `{ tags: [String] }` |
+| `{ key: Schema }` | Object shape | `{ user: { name: String } }` |
+| `or(a, b, ...)` | Any match | `or(String, Number)` |
+| `and(a, b, ...)` | All match | `and(Date, { toJSON: Function })` |
+| `optional(s)` | Nullable | `optional(String)` |
+| `tuple(a, b)` | Fixed array | `tuple(Number, Number)` |
+| `discriminated(schemas, key)` | Tagged union | `discriminated([{ type: 'a' }, { type: 'b' }], 'type')` |
+
+### Special Symbols
+
+```typescript
+import { $keys, $values, $strict } from 'ascertain';
+
+const schema = {
+  [$keys]: /^[a-z]+$/,   // Validate all keys
+  [$values]: Number,      // Validate all values
+  [$strict]: true,        // No extra properties
+};
+```
+
+## Type Casting
+
+Parse strings into typed values (environment variables, query params):
+
+```typescript
+import { as } from 'ascertain';
+
+as.number('42')        // 42
+as.number('3.14')      // 3.14
+as.number('0xFF')      // 255 (hex)
+as.number('0o77')      // 63 (octal)
+as.number('0b1010')    // 10 (binary)
+as.number('1e10')      // 10000000000
+
+as.boolean('true')     // true
+as.boolean('1')        // true
+
+as.time('500ms')       // 500
+as.time('30s')         // 30000
+as.time('5m')          // 300000
+as.time('2h')          // 7200000
+as.time('1d')          // 86400000
+
+as.date('2024-12-31')  // Date object
+as.array('a,b,c', ',') // ['a', 'b', 'c']
+as.json('{"x":1}')     // { x: 1 }
+as.base64('dGVzdA==')  // 'test'
+```
+
+Invalid values return `TypeError` for deferred validation:
+
+```typescript
+const config = {
+  port: as.number(process.env.PORT),  // TypeError if invalid
+  host: as.string(process.env.HOST),
+};
+
+// Errors surface with clear paths
+ascertain({ port: Number, host: String }, config);
+// → TypeError: "Invalid value undefined, expected non-nullable"
+```
+
+## Patterns
+
+### Batch Validation
+
+Compile once, validate many:
+
+```typescript
+const validateUser = compile(userSchema);
+
+const results = users.map((user, i) => {
+  if (validateUser(user)) {
+    return { index: i, valid: true };
+  }
+  return { index: i, valid: false, error: validateUser.issues[0].message };
 });
+```
+
+### Discriminated Unions
+
+Use `discriminated()` for efficient tagged union validation. Instead of trying each variant like `or()`, it checks the discriminant field first and only validates the matching variant:
+
+```typescript
+import { compile, discriminated } from 'ascertain';
+
+const messageSchema = discriminated([
+  { type: 'email', address: String },
+  { type: 'sms', phone: String },
+  { type: 'push', token: String },
+], 'type');
 
+const validate = compile(messageSchema);
+
+validate({ type: 'email', address: 'user@example.com' }); // true
+validate({ type: 'sms', phone: '123456' });                // true
+validate({ type: 'push', token: 123 });                    // false
+validate({ type: 'unknown' });                             // false
 ```
 
-### Runtime validation
-Create data ascertain
+Discriminant values must be string, number, or boolean literals.
+
+### Conditional Rules
+
+Use `or()` and `and()` for complex conditions:
+
 ```typescript
-import { ascertain, optional, and, or, $keys, $values, Schema, as } from 'ascertain';
-
-// create data sample
-const data = {
-  number: 1,
-  string: 'string',
-  boolean: true,
-  function: () => {},
-  array: [],
-  object: {},
-  date: new Date,
-  regexp: 'regexp',
-  oneOfValue: 1,
-  arrayOfNumbers: [1,2,3,4,5],
-  objectSchema: {
-    number: 1,
-  },
-  optional: null,
-  keyValue: {
-    keyOne: 1,
-    keyTwo: 2,
-    keyThree: 3,
-  },
-  // fault tolernat type casting
-  parsedNumber: as.number('1'),
-  parsedString: as.string('string'),
-  parsedBoolean: as.boolean('false'),
-  parsedArray: as.array('1,2,3,4,5', ','),
-  parsedJSON: as.json('{ "number": 1 }'),
-  parsedBase64: as.base64('dGVzdA=='),
-  parsedTime: as.time('2m'),
-  parsedDate: as.date('31-12-2024'),
+const schema = {
+  type: or('email', 'sms'),
+  // Conditional: email requires address, sms requires phone
+  contact: or(
+    and({ type: 'email' }, { address: String }),
+    and({ type: 'sms' }, { phone: String }),
+  ),
 };
+```
 
-// create data schema
-const schema: Schema<typeof data> = {
-  number: Number,
-  string: String,
-  boolean: Boolean,
-  function: Function,
-  array: Array,
-  object: Object,
-  date: and(Date, { toJSON: Function }),
-  regexp: /regexp/,
-  oneOfValue: or(1, 2, 3),
-  arrayOfNumbers: [Number],
-  objectSchema: {
-    number: Number,
-  },
-  optional: optional({
-    number: Number,
-  }),
-  keyValue: {
-    [$keys]: /^key[A-Z]/,
-    [$values]: Number
-  },
-  parsedNumber: Number,
-  parsedString: String,
-  parsedBoolean: Boolean,
-  parsedArray: [String],
-  parsedJSON: {
-    number: 1,
-  },
-  parsedBase64: String,
-  parsedTime: 2 * 60 * 1000, // two minutes
-  parsedDate: Date,
+### Schema Composition
+
+Build schemas from reusable parts:
+
+```typescript
+const addressSchema = {
+  street: String,
+  city: String,
+  zip: /^\d{5}$/,
+};
+
+const personSchema = {
+  name: String,
+  address: addressSchema,
 };
 
-// validate
-const validate = ascertain<typeof data>(schema, data, '[DATA]');
+const companySchema = {
+  name: String,
+  headquarters: addressSchema,
+  employees: [personSchema],
+};
 ```
 
-### Benchmark VS zod and ajv
+### Versioned Schemas
+
+Version schemas as modules:
+
+```typescript
+// schemas/user.v1.ts
+export const userSchemaV1 = { name: String, email: String };
+
+// schemas/user.v2.ts
+export const userSchemaV2 = {
+  ...userSchemaV1,
+  phone: optional(String),
+  createdAt: Date,
+};
+
+// api/handler.ts
+import { userSchemaV2 } from './schemas/user.v2';
+const validate = compile(userSchemaV2);
 ```
-⭐ Script ajv-vs-zod-vs-ascertain.js
-  ⇶ Suite ajv vs zod vs ascertain
-    ➤ Perform benchmark
-      ✓ Measure 500000 zod static schema validation
-        ┌──────────┬──────────┬──────────┬──────────┬────────────┬────────┐
-        │ (index)  │ med      │ p95      │ p99      │ total      │ count  │
-        ├──────────┼──────────┼──────────┼──────────┼────────────┼────────┤
-        │ 0.000699 │ 0.000788 │ 0.000996 │ 0.001624 │ 462.602373 │ 500000 │
-        └──────────┴──────────┴──────────┴──────────┴────────────┴────────┘
-      ✓ Measure 500000 zod dynamic schema validation
-        ┌──────────┬──────────┬──────────┬──────────┬─────────────┬────────┐
-        │ (index)  │ med      │ p95      │ p99      │ total       │ count  │
-        ├──────────┼──────────┼──────────┼──────────┼─────────────┼────────┤
-        │ 0.006248 │ 0.006918 │ 0.007524 │ 0.016948 │ 3780.465563 │ 500000 │
-        └──────────┴──────────┴──────────┴──────────┴─────────────┴────────┘
-      ✓ Measure 500000 ascertain static schema validation
-        ┌──────────┬──────────┬──────────┬──────────┬───────────┬────────┐
-        │ (index)  │ med      │ p95      │ p99      │ total     │ count  │
-        ├──────────┼──────────┼──────────┼──────────┼───────────┼────────┤
-        │ 0.000063 │ 0.000071 │ 0.000098 │ 0.000267 │ 41.673271 │ 500000 │
-        └──────────┴──────────┴──────────┴──────────┴───────────┴────────┘
-      ✓ Measure 500000 ascertain dynamic schema validation
-        ┌──────────┬──────────┬──────────┬──────────┬────────────┬────────┐
-        │ (index)  │ med      │ p95      │ p99      │ total      │ count  │
-        ├──────────┼──────────┼──────────┼──────────┼────────────┼────────┤
-        │ 0.000367 │ 0.000415 │ 0.000525 │ 0.001055 │ 239.078129 │ 500000 │
-        └──────────┴──────────┴──────────┴──────────┴────────────┴────────┘
-      ✓ Measure 500000 ajv compiled schema validation
-        ┌──────────┬──────────┬──────────┬──────────┬───────────┬────────┐
-        │ (index)  │ med      │ p95      │ p99      │ total     │ count  │
-        ├──────────┼──────────┼──────────┼──────────┼───────────┼────────┤
-        │ 0.000063 │ 0.000072 │ 0.000124 │ 0.000307 │ 44.542936 │ 500000 │
-        └──────────┴──────────┴──────────┴──────────┴───────────┴────────┘
+
+### Config Validation
+
+Validate only what each module needs:
+
+```typescript
+import { createValidator, as } from 'ascertain';
+
+const config = {
+  app: { name: as.string(process.env.APP_NAME), port: as.number(process.env.PORT) },
+  db: { host: as.string(process.env.DB_HOST), pool: as.number(process.env.DB_POOL) },
+  cache: { ttl: as.time(process.env.CACHE_TTL) },
+};
+
+const validate = createValidator(config);
+
+// Each module validates only what it needs
+const { db } = validate({
+  db: { host: String, pool: Number },
+});
+
+db.host;   // string - validated and typed
+db.pool;   // number - validated and typed
+// db.xxx  // TypeScript error - property doesn't exist
+
+// cache not validated = not accessible
+// cache.ttl  // TypeScript error - cache not in returned type
+```
+
+## Compile Options
+
+By default `compile()` stops at the first validation error (fastest for invalid data). Pass `{ allErrors: true }` to collect all errors:
+
+```typescript
+import { compile } from 'ascertain';
+
+const schema = { name: String, age: Number, active: Boolean };
+
+// First-error mode (default) - stops at first failure
+const validate = compile(schema);
+if (!validate({ name: 123, age: 'bad', active: 'no' })) {
+  console.log(validate.issues.length); // 1
+  console.log(validate.issues[0].path); // ['name']
+}
+
+// All-errors mode - collects every failure
+const validateAll = compile(schema, { allErrors: true });
+if (!validateAll({ name: 123, age: 'bad', active: 'no' })) {
+  console.log(validateAll.issues.length); // 3
+}
+```
+
+## Standard Schema
+
+Wrap a schema for [Standard Schema v1](https://standardschema.dev/) compliance, enabling interoperability with tRPC, TanStack Form, and other ecosystem libraries:
+
+```typescript
+import { standardSchema, or, optional } from 'ascertain';
+
+const userValidator = standardSchema({
+  name: String,
+  age: Number,
+  role: or('admin', 'user'),
+  email: optional(String),
+});
+
+// Use as regular validator (throws on error)
+userValidator({ name: 'Alice', age: 30, role: 'admin' });
+
+// Use Standard Schema interface (returns result object)
+const result = userValidator['~standard'].validate(unknownData);
+if (result.issues) {
+  console.log(result.issues);
+} else {
+  console.log(result.value);
+}
+```
+
+## Complete Example
+
+```typescript
+import { compile, or, optional, and, tuple, $keys, $values, $strict, as } from 'ascertain';
+
+const schema = {
+  id: Number,
+  name: String,
+  email: /^[^@]+@[^@]+$/,
+  status: or('active', 'inactive', 'pending'),
+  role: optional(or('admin', 'user')),
+
+  profile: {
+    bio: optional(String),
+    avatar: optional(String),
+  },
+
+  settings: {
+    [$keys]: /^[a-z_]+$/,
+    [$values]: or(String, Number, Boolean),
+    [$strict]: true,
+  },
+
+  coordinates: optional(tuple(Number, Number)),
+  createdAt: and(Date, { toISOString: Function }),
+
+  retries: as.number(process.env.MAX_RETRIES),
+  timeout: as.time(process.env.TIMEOUT),
+};
+
+const validate = compile(schema);
+if (!validate(data)) {
+  console.error(validate.issues);
+}
 ```
 
 ## License
-License [The MIT License](http://opensource.org/licenses/MIT)
-Copyright (c) 2019-2025 Ivan Zakharchanka
+
+[MIT](http://opensource.org/licenses/MIT) - Ivan Zakharchanka
 
 [npm-url]: https://www.npmjs.com/package/ascertain
 [downloads-image]: https://img.shields.io/npm/dw/ascertain.svg?maxAge=43200