ascertain 2.1.0 → 3.1.0

package/README.md

@@ -12,135 +12,237 @@ Zero-dependency, high-performance schema validator for Node.js and browsers.
 
 ## Features
 
-- **Zero dependencies**: Minimal footprint, no external dependencies
-- **High performance**: Compiles schemas to optimized JavaScript functions
-- **Type-safe**: Full TypeScript support with type inference
-- **Flexible schemas**: Supports AND, OR, optional, and tuple operators
-- **Type casting**: Built-in parsers for numbers, dates, JSON, base64, and more
-- **Object validation**: Validate keys and values with `$keys`, `$values`, and `$strict`
-- **Detailed errors**: Clear error messages with paths for debugging
-
-## Installation
+- **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
-# or
-pnpm add ascertain
 ```
 
 ## Quick Start
 
 ```typescript
-import { ascertain, compile, or, optional } from 'ascertain';
+import { ascertain, or, optional } from 'ascertain';
 
-// Define a schema
-const userSchema = {
+ascertain({
   name: String,
   age: Number,
+  role: or('admin', 'user'),
   email: optional(String),
-  role: or('admin', 'user', 'guest'),
-};
-
-// Validate data (throws on invalid)
-ascertain(userSchema, userData, 'User');
+}, userData);
 ```
 
 ## Performance
 
-Ascertain compiles schemas into optimized JavaScript functions at runtime. This compilation step generates specialized validation code that runs significantly faster than interpreting schemas on each validation.
-
-**For best performance, compile schemas once and reuse the validator:**
+Ascertain compiles schemas into optimized JavaScript functions. Compiled validators run **~6x faster** than dynamic validation.
 
 ```typescript
 import { compile } from 'ascertain';
 
-// Compile once at startup
-const validateUser = compile(userSchema, 'User');
+// Compile once
+const validateUser = compile(userSchema);
 
-// Reuse for each validation (no recompilation)
+// Validate many (no recompilation)
 validateUser(user1);
 validateUser(user2);
 ```
 
-Use `ascertain()` for one-off validations where convenience matters more than performance. Use `compile()` when validating the same schema repeatedly (e.g., API request handlers).
+| When to use | Function | Speed |
+|-------------|----------|-------|
+| Repeated validation (API handlers, loops) | `compile()` | Fastest |
+| One-off validation | `ascertain()` | Convenient |
 
 ### Benchmark
 
-| Library | Operations/sec | Relative Speed |
-|---------|----------------|----------------|
-| **Ascertain** | 58,962,264 | **1.0x (fastest)** |
-| AJV | 42,204,777 | 0.72x |
-| Zod | 32,309,133 | 0.55x |
+| 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
 
-```bash
-pnpm bench
+```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
+};
 ```
 
-## Schema Types
+## Type Casting
 
-| Schema | Description | Example |
-|--------|-------------|---------|
-| Primitives | Match exact values | `42`, `'active'`, `true`, `null` |
-| Constructors | Validate by type | `String`, `Number`, `Boolean`, `Date` |
-| Arrays | Validate array items | `[Number]` (array of numbers) |
-| Objects | Validate properties | `{ name: String, age: Number }` |
-| RegExp | Match string patterns | `/^[a-z]+$/` |
-| `or()` | Match any schema | `or(String, Number)` |
-| `and()` | Match all schemas | `and(Date, { toJSON: Function })` |
-| `optional()` | Allow null/undefined | `optional(String)` |
-| `tuple()` | Fixed-length arrays | `tuple(Number, Number)` |
+Parse strings into typed values (environment variables, query params):
 
-### Object Validation Symbols
+```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
-import { $keys, $values, $strict } from 'ascertain';
+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
+```
+
+Discriminant values must be string, number, or boolean literals.
+
+### Conditional Rules
+
+Use `or()` and `and()` for complex conditions:
+
+```typescript
 const schema = {
-  [$keys]: /^[a-z]+$/,     // All keys must match pattern
-  [$values]: Number,        // All values must be numbers
-  [$strict]: true,          // No extra properties allowed
+  type: or('email', 'sms'),
+  // Conditional: email requires address, sms requires phone
+  contact: or(
+    and({ type: 'email' }, { address: String }),
+    and({ type: 'sms' }, { phone: String }),
+  ),
 };
 ```
 
-## Type Casting with `as`
+### Schema Composition
 
-Parse and validate values from strings (useful for environment variables, query params, etc.):
+Build schemas from reusable parts:
 
 ```typescript
-import { as } from 'ascertain';
+const addressSchema = {
+  street: String,
+  city: String,
+  zip: /^\d{5}$/,
+};
+
+const personSchema = {
+  name: String,
+  address: addressSchema,
+};
 
-as.string('hello')           // 'hello'
-as.number('42')              // 42
-as.number('3.14')            // 3.14
-as.number('1e10')            // 10000000000
-as.number('0xFF')            // 255 (hex)
-as.number('0o77')            // 63 (octal)
-as.number('0b1010')          // 10 (binary)
-as.boolean('true')           // true
-as.boolean('1')              // true
-as.date('2024-12-31')        // Date object
-as.time('2m')                // 120000 (milliseconds)
-as.time('1h')                // 3600000
-as.array('a,b,c', ',')       // ['a', 'b', 'c']
-as.json('{"x":1}')           // { x: 1 }
-as.base64('dGVzdA==')        // 'test'
+const companySchema = {
+  name: String,
+  headquarters: addressSchema,
+  employees: [personSchema],
+};
 ```
 
-Invalid values return a `TypeError` instead of throwing, enabling deferred validation:
+### Versioned Schemas
+
+Version schemas as modules:
 
 ```typescript
-const config = {
-  port: as.number(process.env.PORT),      // TypeError if invalid
-  host: as.string(process.env.HOST),
+// schemas/user.v1.ts
+export const userSchemaV1 = { name: String, email: String };
+
+// schemas/user.v2.ts
+export const userSchemaV2 = {
+  ...userSchemaV1,
+  phone: optional(String),
+  createdAt: Date,
 };
 
-// Errors surface during schema validation with clear paths
-ascertain({ port: Number, host: String }, config, 'Config');
+// api/handler.ts
+import { userSchemaV2 } from './schemas/user.v2';
+const validate = compile(userSchemaV2);
 ```
 
-## Config Validation with `createValidator`
+### Config Validation
 
-For configuration objects, `createValidator` provides type-safe partial validation:
+Validate only what each module needs:
 
 ```typescript
 import { createValidator, as } from 'ascertain';
@@ -148,19 +250,71 @@ 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) },
-  redis: { url: as.string(process.env.REDIS_URL) },
+  cache: { ttl: as.time(process.env.CACHE_TTL) },
 };
 
-const validate = createValidator(config, 'Config');
+const validate = createValidator(config);
 
 // Each module validates only what it needs
-const { app, db } = validate({
-  app: { name: String, port: Number },
+const { db } = validate({
   db: { host: String, pool: Number },
 });
-// app.name is typed as string
-// app.port is typed as number
-// redis is not accessible (TypeScript error)
+
+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
@@ -169,55 +323,39 @@ const { app, db } = validate({
 import { compile, or, optional, and, tuple, $keys, $values, $strict, as } from 'ascertain';
 
 const schema = {
-  // Type validation
   id: Number,
   name: String,
-  active: Boolean,
-
-  // Pattern matching
   email: /^[^@]+@[^@]+$/,
+  status: or('active', 'inactive', 'pending'),
+  role: optional(or('admin', 'user')),
 
-  // Union types
-  status: or('pending', 'active', 'disabled'),
-
-  // Optional fields
-  nickname: optional(String),
-
-  // Nested objects
   profile: {
-    bio: String,
-    links: [String],
+    bio: optional(String),
+    avatar: optional(String),
   },
 
-  // Combined constraints
-  createdAt: and(Date, { toISOString: Function }),
-
-  // Tuples
-  coordinates: tuple(Number, Number),
-
-  // Dynamic objects
-  metadata: {
+  settings: {
     [$keys]: /^[a-z_]+$/,
-    [$values]: or(String, Number),
+    [$values]: or(String, Number, Boolean),
     [$strict]: true,
   },
 
-  // Parsed values
-  retryCount: as.number(process.env.RETRY_COUNT),
+  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, 'AppConfig');
-
-// Throws TypeError with detailed path on validation failure
-validate(data);
+const validate = compile(schema);
+if (!validate(data)) {
+  console.error(validate.issues);
+}
 ```
 
 ## License
 
-[The MIT License](http://opensource.org/licenses/MIT)
-
-Copyright (c) 2019-2026 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