@cleverbrush/schema 1.1.11 → 2.0.0

package/dist/builders/FunctionSchemaBuilder.d.ts

@@ -1,4 +1,4 @@
-import { SchemaBuilder, ValidationResult, ValidationContext } from './SchemaBuilder.js';
+import { type BRAND, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
 type FunctionSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType<FunctionSchemaBuilder<R>['introspect']>>;
 /**
  * Schema builder for functions. Allows to define a schema for a function.
@@ -11,7 +11,7 @@ type FunctionSchemaBuilderCreateProps<R extends boolean = true> = Partial<Return
  * @example
  * ```ts
  * const schema = func();
- * const result = await schema.validate(() => {});
+ * const result = schema.validate(() => {});
  * // result.valid === true
  * // result.object === () => {}
  * ```
@@ -19,43 +19,86 @@ type FunctionSchemaBuilderCreateProps<R extends boolean = true> = Partial<Return
  * @example
  * ```ts
  * const schema = func().optional();
- * const result = await schema.validate(undefined);
+ * const result = schema.validate(undefined);
  * // result.valid === true
  * // result.object === undefined
  * ```
  *
  * @see {@link func}
  */
-export declare class FunctionSchemaBuilder<TRequired extends boolean = true, TExplicitType = undefined, TResult = TExplicitType extends undefined ? (...args: any[]) => any : TExplicitType> extends SchemaBuilder<TResult, TRequired> {
-    static create(props: FunctionSchemaBuilderCreateProps<any>): FunctionSchemaBuilder<true, undefined, (...args: any[]) => any>;
-    private constructor();
+export declare class FunctionSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TResult = TExplicitType extends undefined ? (...args: any[]) => any : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
+    #private;
     /**
      * @hidden
      */
-    hasType<T>(notUsed?: T): FunctionSchemaBuilder<true, T>;
+    static create(props: FunctionSchemaBuilderCreateProps<any>): FunctionSchemaBuilder<true, false, undefined, false, {}, (...args: any[]) => any>;
+    protected constructor(props: FunctionSchemaBuilderCreateProps<TRequired>);
     /**
      * @hidden
      */
-    clearHasType(): FunctionSchemaBuilder<TRequired, undefined>;
+    hasType<T>(_notUsed?: T): FunctionSchemaBuilder<true, TNullable, T, THasDefault, TExtensions> & TExtensions;
     /**
-     * Performs validion of the schema over `object`. Basically runs
-     * validators, preprocessors and checks for required (if schema is not optional).
+     * @hidden
+     */
+    clearHasType(): FunctionSchemaBuilder<TRequired, TNullable, undefined, THasDefault, TExtensions> & TExtensions;
+    /** {@inheritDoc SchemaBuilder.validate} */
+    validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /** {@inheritDoc SchemaBuilder.validateAsync} */
+    validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    /**
+     * Performs synchronous validation of the schema over `object`.
+     * Throws if any preprocessor, validator, or error message provider returns a Promise.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /**
+     * Performs async validation of the schema over `object`.
+     * Supports async preprocessors, validators, and error message providers.
      * @param context Optional `ValidationContext` settings.
      */
-    validate(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    protected _validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
     protected createFromProps<TReq extends boolean>(props: FunctionSchemaBuilderCreateProps<TReq>): this;
     /**
      * @hidden
      */
-    required(): FunctionSchemaBuilder<true, TExplicitType>;
+    required(errorMessage?: ValidationErrorMessageProvider): FunctionSchemaBuilder<true, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): FunctionSchemaBuilder<false, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): FunctionSchemaBuilder<true, TNullable, TExplicitType, true, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): FunctionSchemaBuilder<TRequired, TNullable, TExplicitType, false, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): FunctionSchemaBuilder<TRequired, TNullable, TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Marks the inferred type as `Readonly<Function>`. Sets the
+     * `isReadonly` introspection flag for tooling consistency.
+     *
+     * @see {@link SchemaBuilder.readonly}
+     */
+    readonly(): FunctionSchemaBuilder<TRequired, TNullable, Readonly<TResult>, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): FunctionSchemaBuilder<TRequired, true, TExplicitType, THasDefault, TExtensions> & TExtensions;
     /**
      * @hidden
      */
-    optional(): FunctionSchemaBuilder<false, TExplicitType>;
+    notNullable(): FunctionSchemaBuilder<TRequired, false, TExplicitType, THasDefault, TExtensions> & TExtensions;
 }
 /**
  * Creates a `function` schema.
- * @retuns {@link FunctionSchemaBuilder}
+ * @returns {@link FunctionSchemaBuilder}
  */
 export declare const func: () => FunctionSchemaBuilder<true>;
 export {};

package/dist/builders/FunctionSchemaBuilder.js

@@ -1,113 +1,2 @@
-import { SchemaBuilder } from './SchemaBuilder.js';
-/**
- * Schema builder for functions. Allows to define a schema for a function.
- * It can be: required or optional.
- *
- * **NOTE** this class is exported only to give opportunity to extend it
- * by inheriting. It is not recommended to create an instance of this class
- * directly. Use {@link func | func()} function instead.
- *
- * @example
- * ```ts
- * const schema = func();
- * const result = await schema.validate(() => {});
- * // result.valid === true
- * // result.object === () => {}
- * ```
- *
- * @example
- * ```ts
- * const schema = func().optional();
- * const result = await schema.validate(undefined);
- * // result.valid === true
- * // result.object === undefined
- * ```
- *
- * @see {@link func}
- */
-export class FunctionSchemaBuilder extends SchemaBuilder {
-    static create(props) {
-        return new FunctionSchemaBuilder({
-            type: 'function',
-            ...props
-        });
-    }
-    constructor(props) {
-        super(props);
-    }
-    /**
-     * @hidden
-     */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    hasType(notUsed) {
-        return this.createFromProps({
-            ...this.introspect()
-        });
-    }
-    /**
-     * @hidden
-     */
-    clearHasType() {
-        return this.createFromProps({
-            ...this.introspect()
-        });
-    }
-    /**
-     * Performs validion of the schema over `object`. Basically runs
-     * validators, preprocessors and checks for required (if schema is not optional).
-     * @param context Optional `ValidationContext` settings.
-     */
-    async validate(object, context) {
-        const superResult = await super.preValidate(object, context);
-        const { valid, context: prevalidationContext, transaction: preValidationTransaction, errors } = superResult;
-        const { path } = prevalidationContext;
-        if (!valid) {
-            return { valid, errors };
-        }
-        const { object: { validatedObject: objToValidate } } = preValidationTransaction;
-        if ((typeof objToValidate === 'undefined' || objToValidate === null) &&
-            this.isRequired === false) {
-            return {
-                valid: true,
-                object: objToValidate
-            };
-        }
-        if (typeof objToValidate !== 'function') {
-            return {
-                valid: false,
-                errors: [
-                    {
-                        message: `expected type function, but saw ${typeof objToValidate}`,
-                        path: path
-                    }
-                ]
-            };
-        }
-        return {
-            valid: true,
-            object: objToValidate
-        };
-    }
-    createFromProps(props) {
-        return FunctionSchemaBuilder.create(props);
-    }
-    /**
-     * @hidden
-     */
-    required() {
-        return super.required();
-    }
-    /**
-     * @hidden
-     */
-    optional() {
-        return super.optional();
-    }
-}
-/**
- * Creates a `function` schema.
- * @retuns {@link FunctionSchemaBuilder}
- */
-export const func = () => FunctionSchemaBuilder.create({
-    isRequired: true
-});
+import{a,b}from"../chunk-EUQ5AE3H.js";import"../chunk-CTP4RHDG.js";export{a as FunctionSchemaBuilder,b as func};
+//# sourceMappingURL=FunctionSchemaBuilder.js.map

package/dist/builders/FunctionSchemaBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/builders/LazySchemaBuilder.d.ts

@@ -0,0 +1,167 @@
+import { type BRAND, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+type LazySchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType<LazySchemaBuilder<any, R>['introspect']>>;
+/**
+ * Lazy schema builder class. Allows defining recursive/self-referential schemas
+ * by wrapping a getter function that returns the target schema. The getter is
+ * called once on first validation and the result is cached.
+ *
+ * This is the primary mechanism for building recursive data structures such as
+ * tree nodes, nested menus, and threaded comments.
+ *
+ * **NOTE** TypeScript cannot infer recursive types automatically, so you must
+ * provide an explicit type annotation on the variable holding the schema:
+ *
+ * @example
+ * ```ts
+ * type TreeNode = { value: number; children: TreeNode[] };
+ *
+ * const treeNode: SchemaBuilder<TreeNode, true> = object({
+ *     value: number(),
+ *     children: array(lazy(() => treeNode))
+ * });
+ *
+ * treeNode.validate({ value: 1, children: [{ value: 2, children: [] }] });
+ * // { valid: true, object: { value: 1, children: [{ value: 2, children: [] }] } }
+ * ```
+ *
+ * @example
+ * ```ts
+ * type Comment = { text: string; replies: Comment[] };
+ *
+ * const commentSchema: SchemaBuilder<Comment, true> = object({
+ *     text: string(),
+ *     replies: array(lazy(() => commentSchema))
+ * });
+ * ```
+ */
+export declare class LazySchemaBuilder<TResult = any, TRequired extends boolean = true, TNullable extends boolean = false, THasDefault extends boolean = false, TExtensions = {}> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
+    #private;
+    /**
+     * @hidden
+     */
+    static create(props: LazySchemaBuilderCreateProps<any>): LazySchemaBuilder<any, true, false, false, {}>;
+    protected constructor(props: LazySchemaBuilderCreateProps<TRequired>);
+    /**
+     * Resolves the lazy schema by calling the getter (once; result is cached).
+     * After the first call subsequent calls return the cached schema instance.
+     */
+    resolve(): SchemaBuilder<TResult, any, any>;
+    /**
+     * @inheritdoc
+     */
+    introspect(): {
+        /**
+         * The getter function that returns the lazily-resolved schema.
+         * Call {@link LazySchemaBuilder.resolve} to obtain the schema instance.
+         */
+        getter: () => SchemaBuilder<TResult, any, any>;
+        type: string;
+        isRequired: boolean;
+        isNullable: boolean;
+        isReadonly: boolean;
+        preprocessors: readonly import("./SchemaBuilder.js").PreprocessorEntry<TResult>[];
+        validators: readonly import("./SchemaBuilder.js").ValidatorEntry<TResult>[];
+        requiredValidationErrorMessageProvider: ValidationErrorMessageProvider<SchemaBuilder<any, any, any, any, any>>;
+        extensions: {
+            [x: string]: unknown;
+        };
+        hasDefault: boolean;
+        defaultValue: TResult | (() => TResult) | undefined;
+        description: string | undefined;
+        hasCatch: boolean;
+        catchValue: TResult | (() => TResult) | undefined;
+    };
+    /** {@inheritDoc SchemaBuilder.validate} */
+    validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /** {@inheritDoc SchemaBuilder.validateAsync} */
+    validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    /**
+     * Performs synchronous validation of the schema over `object`.
+     * Throws if any preprocessor, validator, or error message provider returns a Promise.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validate(object: TResult, context?: ValidationContext): ValidationResult<TResult>;
+    /**
+     * Performs async validation of the schema over `object`.
+     * Supports async preprocessors, validators, and error message providers.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validateAsync(object: TResult, context?: ValidationContext): Promise<ValidationResult<TResult>>;
+    protected createFromProps<TReq extends boolean>(props: LazySchemaBuilderCreateProps<TReq>): this;
+    /**
+     * @inheritdoc
+     */
+    hasType<T>(_notUsed?: T): LazySchemaBuilder<T, true, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @inheritdoc
+     */
+    clearHasType(): LazySchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): LazySchemaBuilder<TResult, true, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): LazySchemaBuilder<TResult, false, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): LazySchemaBuilder<TResult, true, TNullable, true, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): LazySchemaBuilder<TResult, TRequired, TNullable, false, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): LazySchemaBuilder<TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    readonly(): LazySchemaBuilder<Readonly<TResult>, TRequired, TNullable, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): LazySchemaBuilder<TResult, TRequired, true, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): LazySchemaBuilder<TResult, TRequired, false, THasDefault, TExtensions> & TExtensions;
+}
+/**
+ * Creates a lazy schema that defers the schema definition until first validation.
+ * Use this to define recursive/self-referential schemas.
+ *
+ * The getter function is called **once** on first use and the result is cached.
+ * You **must** provide an explicit TypeScript type annotation on the variable
+ * holding the outer schema — TypeScript cannot infer recursive types automatically.
+ *
+ * @param getter - A function that returns the schema to use for validation.
+ *
+ * @example
+ * ```ts
+ * // Tree structure
+ * type TreeNode = { value: number; children: TreeNode[] };
+ *
+ * const treeNode: SchemaBuilder<TreeNode, true> = object({
+ *     value: number(),
+ *     children: array(lazy(() => treeNode))
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optional recursive field (submenu)
+ * type MenuItem = { label: string; submenu?: MenuItem[] };
+ *
+ * const menuItem: SchemaBuilder<MenuItem, true> = object({
+ *     label: string(),
+ *     submenu: array(lazy(() => menuItem)).optional()
+ * });
+ * ```
+ */
+export declare function lazy<TResult>(getter: () => SchemaBuilder<TResult, any, any>): LazySchemaBuilder<TResult, true, false, false, {}>;
+export {};

package/dist/builders/NullSchemaBuilder.d.ts

@@ -0,0 +1,162 @@
+import { type BRAND, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+type NullSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType<NullSchemaBuilder<R>['introspect']>>;
+/**
+ * Schema builder for `null` values. Validates that the input is exactly `null`.
+ *
+ * When required (the default), only `null` is accepted. When optional (via
+ * `.optional()`), both `null` and `undefined` are accepted; any other value
+ * is rejected.
+ *
+ * This builder is useful when you need to represent an explicitly-null field
+ * in a typed schema, for example in discriminated-union branches or when
+ * modelling a JSON payload that may carry a JSON `null` value.
+ *
+ * **NOTE** this class is exported only to give opportunity to extend it
+ * by inheriting. It is not recommended to create an instance of this class
+ * directly. Use {@link nul | nul()} function instead.
+ *
+ * @example
+ * ```ts
+ * import { nul } from '@cleverbrush/schema';
+ *
+ * const schema = nul();
+ *
+ * schema.validate(null);       // { valid: true,  object: null }
+ * schema.validate(undefined);  // { valid: false }
+ * schema.validate(0);          // { valid: false }
+ * schema.validate('');         // { valid: false }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optional — accepts null or undefined
+ * const schema = nul().optional();
+ *
+ * schema.validate(null);       // { valid: true, object: null }
+ * schema.validate(undefined);  // { valid: true, object: undefined }
+ * schema.validate(false);      // { valid: false }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Use inside a union to model a nullable string field
+ * import { union, string, nul, InferType } from '@cleverbrush/schema';
+ *
+ * const NullableString = union(string()).or(nul());
+ * type NullableString = InferType<typeof NullableString>;
+ * // string | null
+ *
+ * NullableString.validate('hello');  // valid
+ * NullableString.validate(null);     // valid
+ * NullableString.validate(42);       // invalid
+ * ```
+ *
+ * @see {@link nul}
+ */
+export declare class NullSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}> extends SchemaBuilder<null, TRequired, TNullable, THasDefault, TExtensions> {
+    #private;
+    /**
+     * @hidden
+     */
+    static create(props: NullSchemaBuilderCreateProps<any>): NullSchemaBuilder<true, false, undefined, false, {}>;
+    protected constructor(props: NullSchemaBuilderCreateProps<TRequired>);
+    /**
+     * @hidden
+     */
+    hasType<T>(_notUsed?: T): NullSchemaBuilder<true, TNullable, T, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearHasType(): NullSchemaBuilder<TRequired, TNullable, undefined, THasDefault, TExtensions> & TExtensions;
+    /** {@inheritDoc SchemaBuilder.validate} */
+    validate(object: null, context?: ValidationContext): ValidationResult<null>;
+    /** {@inheritDoc SchemaBuilder.validateAsync} */
+    validateAsync(object: null, context?: ValidationContext): Promise<ValidationResult<null>>;
+    /**
+     * Performs synchronous validation of the schema over `object`.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validate(object: null, _context?: ValidationContext): ValidationResult<null>;
+    /**
+     * Performs async validation of the schema over `object`.
+     * @param context Optional `ValidationContext` settings.
+     */
+    protected _validateAsync(object: null, _context?: ValidationContext): Promise<ValidationResult<null>>;
+    protected createFromProps<TReq extends boolean>(props: NullSchemaBuilderCreateProps<TReq>): this;
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): NullSchemaBuilder<true, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): NullSchemaBuilder<false, TNullable, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: null | (() => null)): NullSchemaBuilder<true, TNullable, TExplicitType, true, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): NullSchemaBuilder<TRequired, TNullable, TExplicitType, false, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): NullSchemaBuilder<TRequired, TNullable, null & {
+        readonly [K in BRAND]: TBrand;
+    }, THasDefault, TExtensions> & TExtensions;
+    /**
+     * Marks the inferred type as `Readonly<null>`. Since `null` is already
+     * immutable this is an identity operation, but it sets the `isReadonly`
+     * introspection flag for tooling consistency.
+     *
+     * @see {@link SchemaBuilder.readonly}
+     */
+    readonly(): NullSchemaBuilder<TRequired, TNullable, Readonly<null>, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): NullSchemaBuilder<TRequired, true, TExplicitType, THasDefault, TExtensions> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): NullSchemaBuilder<TRequired, false, TExplicitType, THasDefault, TExtensions> & TExtensions;
+}
+/**
+ * Creates a schema that validates the value is exactly `null`.
+ *
+ * By default the schema is **required** — only `null` is accepted.
+ * Call `.optional()` to also allow `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { nul } from '@cleverbrush/schema';
+ *
+ * nul().validate(null);       // { valid: true,  object: null }
+ * nul().validate(undefined);  // { valid: false }
+ * nul().validate(0);          // { valid: false }
+ * ```
+ *
+ * @example
+ * ```ts
+ * nul().optional().validate(null);       // { valid: true, object: null }
+ * nul().optional().validate(undefined);  // { valid: true, object: undefined }
+ * nul().optional().validate(false);      // { valid: false }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Nullable field in an object schema
+ * import { object, string, nul, union, InferType } from '@cleverbrush/schema';
+ *
+ * const Schema = object({
+ *   name:    string(),
+ *   deleted: union(nul()).or(string()),   // null | string
+ * });
+ *
+ * type T = InferType<typeof Schema>;
+ * // { name: string; deleted: null | string }
+ * ```
+ */
+export declare const nul: () => NullSchemaBuilder<true>;
+export {};