ascertain 2.0.88 → 3.0.0

package/build/index.d.ts

@@ -1,16 +1,3 @@
-/**
- * Abstract base class for schema operators.
- *
- * Provides a common constructor that enforces having at least one schema.
- *
- * @template T - The type of data the operator validates.
- * @abstract
- * @internal
- */
-declare abstract class Operator<T> {
-    readonly schemas: Schema<T>[];
-    constructor(schemas: Schema<T>[]);
-}
 /**
  * Symbol for validating object keys against a schema.
  */
@@ -23,6 +10,33 @@ export declare const $values: unique symbol;
  * Symbol for enforcing strict object validation (no extra properties allowed).
  */
 export declare const $strict: unique symbol;
+declare const $op: unique symbol;
+declare const OR: unique symbol;
+declare const AND: unique symbol;
+declare const OPTIONAL: unique symbol;
+declare const TUPLE: unique symbol;
+declare const DISCRIMINATED: unique symbol;
+interface OrShape<T> {
+    readonly schemas: Schema<T>[];
+    readonly [$op]: typeof OR;
+}
+interface AndShape<T> {
+    readonly schemas: Schema<T>[];
+    readonly [$op]: typeof AND;
+}
+interface OptionalShape<T> {
+    readonly schemas: Schema<T>[];
+    readonly [$op]: typeof OPTIONAL;
+}
+interface TupleShape<T> {
+    readonly schemas: Schema<T>[];
+    readonly [$op]: typeof TUPLE;
+}
+interface DiscriminatedShape<T> {
+    readonly schemas: Schema<T>[];
+    readonly [$op]: typeof DISCRIMINATED;
+    readonly key: string;
+}
 /**
  * Represents a schema for validating data.
  *
@@ -39,170 +53,61 @@ export type Schema<T> = T extends Record<string | number | symbol, unknown> ? {
 } & {
     [$strict]?: boolean;
 } : T extends Array<infer A> ? Schema<A>[] | unknown : unknown;
-declare class Or<T> extends Operator<T> {
-}
 /**
  * Operator for validating data against any of the provided schemas (logical OR).
- *
- * Creates a schema that accepts data matching any one of the provided schemas.
- * This is useful for creating union types or alternative validation paths.
- *
- * @template T - The type of data the operator validates.
- * @param schemas - Multiple schemas where at least one must match the data.
- * @returns A schema that validates data against any of the provided schemas.
- *
- * @example
- * ```typescript
- * import { or, ascertain } from 'ascertain';
- *
- * // Create a schema that accepts either a string or number
- * const stringOrNumber = or(String, Number);
- *
- * ascertain(stringOrNumber, "hello", "value"); // ✓ Valid
- * ascertain(stringOrNumber, 42, "value");      // ✓ Valid
- * ascertain(stringOrNumber, true, "value");    // ✗ Throws error
- *
- * // Union of literal values
- * const statusSchema = or('pending', 'completed', 'failed');
- * ascertain(statusSchema, 'pending', "status"); // ✓ Valid
- *
- * // Complex schema combinations
- * const userIdSchema = or(Number, { id: Number, temp: Boolean });
- * ascertain(userIdSchema, 123, "userId");                    // ✓ Valid
- * ascertain(userIdSchema, { id: 456, temp: true }, "userId"); // ✓ Valid
- * ```
  */
-export declare const or: <T>(...schemas: Schema<T>[]) => Or<T>;
-declare class And<T> extends Operator<T> {
-}
+export declare const or: <T>(...schemas: Schema<T>[]) => OrShape<T>;
 /**
  * Operator for validating data against all provided schemas (logical AND).
- *
- * Creates a schema that requires data to match every one of the provided schemas.
- * This is useful for combining multiple validation requirements or adding constraints.
- *
- * @template T - The type of data the operator validates.
- * @param schemas - Multiple schemas that all must match the data.
- * @returns A schema that validates data against all of the provided schemas.
- *
- * @example
- * ```typescript
- * import { and, ascertain } from 'ascertain';
- *
- * // Combine object schema with additional constraints
- * const userSchema = and(
- *   { name: String, age: Number },
- *   { age: Number } // Additional constraint
- * );
- *
- * ascertain(userSchema, { name: "John", age: 25 }, "user"); // ✓ Valid
- *
- * // Ensure an object is both a Date and has specific methods
- * const validDateSchema = and(Date, { toISOString: Function });
- * ascertain(validDateSchema, new Date(), "date"); // ✓ Valid
- *
- * // Multiple validation layers
- * const positiveNumberSchema = and(Number, (n: number) => n > 0);
- * ascertain(positiveNumberSchema, 42, "count");   // ✓ Valid
- * ascertain(positiveNumberSchema, -5, "count");   // ✗ Throws error
- * ```
  */
-export declare const and: <T>(...schemas: Schema<T>[]) => And<T>;
-declare class Optional<T> extends Operator<T> {
-    constructor(schema: Schema<T>);
-}
+export declare const and: <T>(...schemas: Schema<T>[]) => AndShape<T>;
 /**
  * Operator for making a schema optional (nullable).
+ */
+export declare const optional: <T>(schema: Schema<T>) => OptionalShape<T>;
+/**
+ * Operator for validating data against a fixed-length tuple of schemas.
+ */
+export declare const tuple: <T>(...schemas: Schema<T>[]) => TupleShape<T>;
+/**
+ * Operator for validating data against a discriminated union.
  *
- * Creates a schema that accepts the provided schema or null/undefined values.
- * This is useful for optional object properties or nullable fields.
+ * Optimizes validation by checking the discriminant field first and only
+ * validating the matching variant. More efficient than `or()` for unions
+ * where each variant has a common field with a unique literal value.
  *
- * @template T - The type of data the operator validates.
- * @param schema - The schema to make optional.
- * @returns A schema that validates data against the provided schema or accepts null/undefined.
+ * @param schemas - Array of object schemas, each with a discriminant field containing a literal value.
+ * @param key - The name of the discriminant field present in all variants.
  *
  * @example
  * ```typescript
- * import { optional, ascertain } from 'ascertain';
- *
- * // Optional string field
- * const userSchema = {
- *   name: String,
- *   nickname: optional(String),
- *   age: Number
- * };
- *
- * // All of these are valid
- * ascertain(userSchema, {
- *   name: "John",
- *   nickname: "Johnny",
- *   age: 30
- * }, "user"); // ✓ Valid
- *
- * ascertain(userSchema, {
- *   name: "Jane",
- *   nickname: null,
- *   age: 25
- * }, "user"); // ✓ Valid
- *
- * ascertain(userSchema, {
- *   name: "Bob",
- *   age: 35
- *   // nickname is undefined
- * }, "user"); // ✓ Valid
- *
- * // Optional complex objects
- * const profileSchema = {
- *   id: Number,
- *   settings: optional({
- *     theme: String,
- *     notifications: Boolean
- *   })
- * };
+ * const messageSchema = discriminated([
+ *   { type: 'email', address: String },
+ *   { type: 'sms', phone: String },
+ *   { type: 'push', token: String },
+ * ], 'type');
  * ```
  */
-export declare const optional: <T>(schema: Schema<T>) => Optional<T>;
-declare class Tuple<T> extends Operator<T> {
-}
+export declare const discriminated: <T>(schemas: Schema<T>[], key: string) => DiscriminatedShape<T>;
 /**
- * Operator for validating data against a fixed-length tuple of schemas.
+ * Decodes a base64-encoded string to UTF-8.
  *
- * Creates a schema that validates arrays with a specific length and type for each position.
- * This is useful for coordinate pairs, RGB values, or any fixed-structure data.
+ * Uses `Buffer` in Node.js environments and `atob` in browsers.
  *
- * @template T - The type of data the operator validates (a tuple of types).
- * @param schemas - Schemas for each position in the tuple, in order.
- * @returns A schema that validates data as a tuple with the specified structure.
- *
- * @example
- * ```typescript
- * import { tuple, ascertain } from 'ascertain';
- *
- * // 2D coordinate tuple
- * const pointSchema = tuple(Number, Number);
- * ascertain(pointSchema, [10, 20], "point"); // ✓ Valid
- * ascertain(pointSchema, [1.5, 2.7], "point"); // ✓ Valid
- * ascertain(pointSchema, [10], "point"); // ✗ Throws error (too short)
- * ascertain(pointSchema, [10, 20, 30], "point"); // ✗ Throws error (too long)
- *
- * // RGB color tuple
- * const colorSchema = tuple(Number, Number, Number);
- * ascertain(colorSchema, [255, 128, 0], "color"); // ✓ Valid
- *
- * // Mixed type tuple
- * const userInfoSchema = tuple(String, Number, Boolean);
- * ascertain(userInfoSchema, ["Alice", 25, true], "userInfo"); // ✓ Valid
- *
- * // Nested tuple
- * const lineSchema = tuple(
- *   tuple(Number, Number), // start point
- *   tuple(Number, Number)  // end point
- * );
- * ascertain(lineSchema, [[0, 0], [10, 10]], "line"); // ✓ Valid
- * ```
+ * @param value - The base64-encoded string to decode.
+ * @returns The decoded UTF-8 string.
  */
-export declare const tuple: <T>(...schemas: Schema<T>[]) => Tuple<T>;
 export declare const fromBase64: (value: string) => string;
+/**
+ * Creates a TypeError with the given message, typed as T for deferred error handling.
+ *
+ * Used by `as.*` conversion utilities to return errors that can be caught
+ * during schema validation rather than throwing immediately.
+ *
+ * @template T - The expected return type (for type compatibility with conversion functions).
+ * @param message - The error message.
+ * @returns A TypeError instance typed as T.
+ */
 export declare const asError: <T>(message: string) => T;
 export declare const as: {
     /**
@@ -215,6 +120,13 @@ export declare const as: {
     /**
      * Attempts to convert a value to a number.
      *
+     * Supports integers, floats, scientific notation (1e10), and prefixed formats:
+     * - Hexadecimal: `0x` or `0X` (e.g., `'0xFF'` → 255)
+     * - Octal: `0o` or `0O` (e.g., `'0o77'` → 63)
+     * - Binary: `0b` or `0B` (e.g., `'0b1010'` → 10)
+     *
+     * All formats support optional leading sign (`+` or `-`).
+     *
      * @param value - The value to convert (expected to be a string representation of a number).
      * @returns The value as a number, or a TypeError if not a valid number.
      */
@@ -266,19 +178,40 @@ export declare const as: {
     base64: (value: string | undefined) => string;
 };
 /**
- * Compiles a schema into a validation function.
+ * Validator function returned by compile().
+ * Returns true if valid, false if invalid.
+ * Access `.issues` property after validation to get error details.
+ */
+export interface Validator<T> {
+    (data: T): boolean;
+    issues: ReadonlyArray<StandardSchemaV1.Issue>;
+}
+/**
+ * Options for the compile function.
+ */
+export interface CompileOptions {
+    /**
+     * When true, collects all validation errors instead of stopping at the first.
+     * Default is false (first-error mode) for optimal performance.
+     */
+    allErrors?: boolean;
+}
+/**
+ * Compiles a schema into a high-performance validation function.
+ *
+ * By default uses first-error mode which stops at the first validation failure
+ * and returns immediately. This provides optimal performance for invalid data.
  *
- * This function takes a schema definition and generates a JavaScript function
- * that can be used to validate data against the schema.
+ * Set `allErrors: true` to collect all validation errors (slower but more informative).
  *
  * @template T - The type of data the schema validates.
  * @param schema - The schema to compile.
- * @param rootName - A name for the root of the data structure (used in error messages).
- * @returns A validation function that takes data as input and throws a TypeError if the data does not conform to the schema.
+ * @param options - Optional configuration (allErrors: boolean).
+ * @returns A validator function that returns boolean. Access `.issues` for error details.
  *
  * @example
  * ```typescript
- * import { compile, optional, and, or } from 'ascertain';
+ * import { compile, optional, or } from 'ascertain';
  *
  * const userSchema = {
  *   name: String,
@@ -287,28 +220,24 @@ export declare const as: {
  *   role: or('admin', 'user', 'guest')
  * };
  *
- * const validateUser = compile(userSchema, 'User');
+ * // First-error mode (default) - fastest for invalid data
+ * const validate = compile(userSchema);
  *
- * // Valid data - no error thrown
- * validateUser({
- *   name: 'John Doe',
- *   age: 30,
- *   email: 'john@example.com',
- *   role: 'user'
- * });
+ * // All-errors mode - collects all validation issues
+ * const validateAll = compile(userSchema, { allErrors: true });
  *
- * // Invalid data - throws TypeError
- * try {
- *   validateUser({
- *     name: 123, // Invalid: should be string
- *     age: 'thirty' // Invalid: should be number
- *   });
- * } catch (error) {
- *   console.error(error.message); // Detailed validation errors
+ * // Valid data
+ * if (validate({ name: 'John', age: 30, role: 'user' })) {
+ *   console.log('Valid!');
+ * }
+ *
+ * // Invalid data - check .issues for details
+ * if (!validate({ name: 123, age: 'thirty' })) {
+ *   console.log(validate.issues); // Array with first validation issue
  * }
  * ```
  */
-export declare const compile: <T>(schema: Schema<T>, rootName: string) => (data: T) => any;
+export declare const compile: <T>(schema: Schema<T>, options?: CompileOptions) => Validator<T>;
 /**
  * Asserts that data conforms to a given schema.
  *
@@ -318,7 +247,6 @@ export declare const compile: <T>(schema: Schema<T>, rootName: string) => (data:
  * @template T - The type of data the schema validates.
  * @param schema - The schema to validate against.
  * @param data - The data to validate.
- * @param rootName - A name for the root of the data structure (used in error messages, defaults to '[root]').
  * @throws `{TypeError}` If the data does not conform to the schema.
  *
  * @example
@@ -340,7 +268,7 @@ export declare const compile: <T>(schema: Schema<T>, rootName: string) => (data:
  * };
  *
  * // Validate data - throws if invalid, otherwise continues silently
- * ascertain(userSchema, userData, 'UserData');
+ * ascertain(userSchema, userData);
  * console.log('User data is valid!');
  *
  * // Example with invalid data
@@ -349,7 +277,7 @@ export declare const compile: <T>(schema: Schema<T>, rootName: string) => (data:
  *     name: 'Bob',
  *     age: 'twenty-five', // Invalid: should be number
  *     active: true
- *   }, 'UserData');
+ *   });
  * } catch (error) {
  *   console.error('Validation failed:', error.message);
  * }
@@ -361,14 +289,131 @@ export declare const compile: <T>(schema: Schema<T>, rootName: string) => (data:
  * const numbersSchema = [Number];
  * const numbers = [1, 2, 3, 4, 5];
  *
- * ascertain(numbersSchema, numbers, 'Numbers');
+ * ascertain(numbersSchema, numbers);
  *
  * // Tuple validation
  * const coordinateSchema = tuple(Number, Number);
  * const point = [10, 20];
  *
- * ascertain(coordinateSchema, point, 'Point');
+ * ascertain(coordinateSchema, point);
  * ```
  */
-export declare const ascertain: <T>(schema: Schema<T>, data: T, rootName?: string) => void;
+export declare const ascertain: <T>(schema: Schema<T>, data: T) => void;
+/**
+ * Extracts the shape of a config object based on the schema keys.
+ * Recursively picks only the properties defined in the schema.
+ */
+export type ExtractShape<C, S> = {
+    [K in keyof S & keyof C]: S[K] extends object ? (C[K] extends object ? ExtractShape<C[K], S[K]> : C[K]) : C[K];
+};
+/**
+ * Creates a typed validator function for a config object.
+ *
+ * Returns a function that validates a schema against the config and returns
+ * the same config reference with a narrowed type containing only the validated fields.
+ *
+ * @template C - The type of the config object.
+ * @param config - The config object to validate against.
+ * @returns A validator function that takes a schema and returns the typed config subset.
+ *
+ * @example
+ * ```typescript
+ * import { createValidator, as } from 'ascertain';
+ *
+ * const config = {
+ *   app: { name: as.string(process.env.APP_NAME) },
+ *   kafka: { brokers: as.array(process.env.BROKERS, ',') },
+ *   redis: { host: as.string(process.env.REDIS_HOST) },
+ * };
+ *
+ * const validate = createValidator(config);
+ *
+ * // Consumer only validates what it needs
+ * const { app, kafka } = validate({
+ *   app: { name: String },
+ *   kafka: { brokers: [String] },
+ * });
+ *
+ * // app.name is typed as string
+ * // kafka.brokers is typed as string[]
+ * // redis is not accessible - TypeScript error
+ * ```
+ */
+export declare const createValidator: <C>(config: C) => <S extends Schema<Partial<C>>>(schema: S) => ExtractShape<C, S>;
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+}
+/**
+ * Wraps an Ascertain schema to make it Standard Schema v1 compliant.
+ *
+ * Creates a validator that implements the Standard Schema specification,
+ * enabling interoperability with tools like tRPC, TanStack Form, and other
+ * ecosystem libraries that consume Standard Schema-compliant validators.
+ *
+ * The returned function can be used both as a regular Ascertain validator
+ * (throws on error) and as a Standard Schema validator (returns result object).
+ *
+ * @template T - The type of data the schema validates.
+ * @param schema - The Ascertain schema to wrap.
+ * @returns A function that validates data, with a `~standard` property for Standard Schema compliance.
+ *
+ * @see https://standardschema.dev/
+ *
+ * @example
+ * ```typescript
+ * import { standardSchema, or, optional } from 'ascertain';
+ *
+ * // Create a Standard Schema-compliant validator
+ * const userValidator = standardSchema({
+ *   name: String,
+ *   age: Number,
+ *   role: or('admin', 'user'),
+ *   email: optional(String),
+ * });
+ *
+ * // Use as regular Ascertain 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); // typed as User
+ * }
+ *
+ * // Works with tRPC, TanStack Form, etc.
+ * ```
+ */
+interface StandardSchemaFn<T> {
+    (data: T): void;
+    '~standard': StandardSchemaV1.Props<T, T>;
+}
+export declare const standardSchema: <T>(schema: Schema<T>) => StandardSchemaFn<T>;
 export {};