@cleverbrush/schema 0.0.0-beta-20260410073748

package/dist/builders/FunctionSchemaBuilder.d.ts

@@ -0,0 +1,246 @@
+import { type BRAND, type InferType, SchemaBuilder, type ValidationContext, type ValidationErrorMessageProvider, type ValidationResult } from './SchemaBuilder.js';
+type FunctionSchemaBuilderCreateProps<R extends boolean = true> = Partial<ReturnType<FunctionSchemaBuilder<R>['introspect']>>;
+type InferParameters<TParams extends SchemaBuilder<any, any, any, any, any>[]> = {
+    [K in keyof TParams]: InferType<TParams[K]>;
+};
+/**
+ * Schema builder for functions. Allows to define a schema for a function.
+ * It can be required or optional, and may carry typed parameter and return-type
+ * schemas so that the inferred TypeScript function signature is fully typed.
+ *
+ * **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 Basic validation
+ * ```ts
+ * const schema = func();
+ * const result = schema.validate(() => {});
+ * // result.valid === true
+ * // result.object === () => {}
+ * ```
+ *
+ * @example Optional function schema
+ * ```ts
+ * const schema = func().optional();
+ * const result = schema.validate(undefined);
+ * // result.valid === true
+ * // result.object === undefined
+ * ```
+ *
+ * @example Typed parameters and return type
+ * ```ts
+ * import { func, string, number, InferType } from '@cleverbrush/schema';
+ *
+ * const greet = func()
+ *     .addParameter(string())           // first param: string
+ *     .addParameter(number().optional()) // second param: number | undefined
+ *     .hasReturnType(string());          // return type: string
+ *
+ * type Greet = InferType<typeof greet>;
+ * // → (param0: string, param1: number | undefined) => string
+ *
+ * // Introspect at runtime
+ * const info = greet.introspect();
+ * // info.parameters  → [StringSchemaBuilder, NumberSchemaBuilder]
+ * // info.returnType  → StringSchemaBuilder
+ * ```
+ *
+ * @see {@link func}
+ */
+export declare class FunctionSchemaBuilder<TRequired extends boolean = true, TNullable extends boolean = false, TExplicitType = undefined, THasDefault extends boolean = false, TExtensions = {}, TParameters extends SchemaBuilder<any, any, any, any, any>[] = [], TReturnTypeSchema extends SchemaBuilder<any, any, any, any, any> | undefined = undefined, TResult = TExplicitType extends undefined ? (...args: TParameters extends [] ? any[] : InferParameters<TParameters>) => TReturnTypeSchema extends SchemaBuilder<any, any, any, any, any> ? InferType<TReturnTypeSchema> : any : TExplicitType> extends SchemaBuilder<TResult, TRequired, TNullable, THasDefault, TExtensions> {
+    #private;
+    /**
+     * @hidden
+     */
+    static create(props: FunctionSchemaBuilderCreateProps<any>): FunctionSchemaBuilder<true, false, undefined, false, {}, [], undefined, (...args: any[]) => any>;
+    protected constructor(props: FunctionSchemaBuilderCreateProps<TRequired>);
+    /**
+     * @hidden
+     */
+    hasType<T>(_notUsed?: T): FunctionSchemaBuilder<true, TNullable, T, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearHasType(): FunctionSchemaBuilder<TRequired, TNullable, undefined, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * Returns an object describing the current schema configuration.
+     *
+     * In addition to the base fields exposed by {@link SchemaBuilder.introspect},
+     * the following fields are included:
+     *
+     * - `parameters` — an array of {@link SchemaBuilder} instances accumulated via
+     *   {@link addParameter}. Each element describes one positional parameter of the
+     *   function in the order they were added.
+     * - `returnType` — the {@link SchemaBuilder} set via {@link hasReturnType}, or
+     *   `undefined` when no return-type schema has been configured.
+     *
+     * @example
+     * ```ts
+     * const schema = func()
+     *     .addParameter(string())
+     *     .addParameter(number())
+     *     .hasReturnType(boolean());
+     *
+     * const info = schema.introspect();
+     * // info.parameters.length === 2
+     * // info.returnType instanceof BooleanSchemaBuilder
+     * ```
+     */
+    introspect(): {
+        /** List of parameter schemas added via {@link addParameter}. */
+        parameters: SchemaBuilder<any, any, any, any, any>[];
+        /** Return type schema set via {@link hasReturnType}, or `undefined` if not set. */
+        returnType: SchemaBuilder<any, any, any, any, any> | undefined;
+        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: FunctionSchemaBuilderCreateProps<TReq>): this;
+    /**
+     * @hidden
+     */
+    required(errorMessage?: ValidationErrorMessageProvider): FunctionSchemaBuilder<true, TNullable, TExplicitType, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    optional(): FunctionSchemaBuilder<false, TNullable, TExplicitType, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    default(value: TResult | (() => TResult)): FunctionSchemaBuilder<true, TNullable, TExplicitType, true, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    clearDefault(): FunctionSchemaBuilder<TRequired, TNullable, TExplicitType, false, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    brand<TBrand extends string | symbol>(_name?: TBrand): FunctionSchemaBuilder<TRequired, TNullable, TResult & {
+        readonly [K in BRAND]: TBrand;
+    }, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & 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, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    nullable(): FunctionSchemaBuilder<TRequired, true, TExplicitType, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+    /**
+     * Appends a positional parameter schema to the function schema.
+     *
+     * Each call extends the inferred function signature by one parameter.
+     * The full list of parameter schemas is available at runtime via
+     * `introspect().parameters`.
+     *
+     * Parameter order matches the call order — the first `addParameter()` call
+     * defines the type of the first argument, the second call defines the second
+     * argument, and so on.
+     *
+     * @param schema - The schema describing the parameter. Pass an optional schema
+     *   (e.g. `string().optional()`) to make the corresponding argument optional.
+     *
+     * @example
+     * ```ts
+     * const fn = func()
+     *     .addParameter(string())          // (a: string, ...) => any
+     *     .addParameter(number().optional()) // (..., b?: number) => any
+     *     .addParameter(boolean());        // (..., c: boolean) => any
+     *
+     * type Fn = InferType<typeof fn>;
+     * // → (a: string, b: number | undefined, c: boolean) => any
+     * ```
+     */
+    addParameter<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): FunctionSchemaBuilder<TRequired, TNullable, TExplicitType, THasDefault, TExtensions, [
+        ...TParameters,
+        TSchema
+    ], TReturnTypeSchema> & TExtensions;
+    /**
+     * Sets the return type schema for the function schema.
+     *
+     * Replaces any previously set return type. The inferred function signature
+     * gains a concrete return type instead of `any`. The schema is accessible at
+     * runtime via `introspect().returnType`.
+     *
+     * @param schema - The schema describing the return type of the function.
+     *
+     * @example
+     * ```ts
+     * const fn = func()
+     *     .addParameter(string())
+     *     .hasReturnType(number());
+     *
+     * type Fn = InferType<typeof fn>;
+     * // → (param0: string) => number
+     *
+     * fn.introspect().returnType; // NumberSchemaBuilder
+     * ```
+     */
+    hasReturnType<TSchema extends SchemaBuilder<any, any, any, any, any>>(schema: TSchema): FunctionSchemaBuilder<TRequired, TNullable, TExplicitType, THasDefault, TExtensions, TParameters, TSchema> & TExtensions;
+    /**
+     * @hidden
+     */
+    notNullable(): FunctionSchemaBuilder<TRequired, false, TExplicitType, THasDefault, TExtensions, TParameters, TReturnTypeSchema> & TExtensions;
+}
+/**
+ * Creates a `function` schema that validates the value is a JavaScript function.
+ *
+ * The returned builder is immutable and fully chainable. Use
+ * {@link FunctionSchemaBuilder.addParameter} to annotate the expected parameter
+ * types and {@link FunctionSchemaBuilder.hasReturnType} to annotate the return
+ * type — the inferred TypeScript function signature is updated automatically.
+ *
+ * @returns A new {@link FunctionSchemaBuilder} with `isRequired` set to `true`.
+ *
+ * @example
+ * ```ts
+ * import { func, string, number, InferType } from '@cleverbrush/schema';
+ *
+ * const schema = func()
+ *     .addParameter(string())
+ *     .addParameter(number().optional())
+ *     .hasReturnType(string());
+ *
+ * type Fn = InferType<typeof schema>;
+ * // → (param0: string, param1?: number) => string
+ *
+ * schema.validate(() => 'hello');  // { valid: true }
+ * schema.validate('not a fn');     // { valid: false }
+ * ```
+ *
+ * @see {@link FunctionSchemaBuilder}
+ */
+export declare const func: () => FunctionSchemaBuilder<true>;
+export {};

package/dist/builders/FunctionSchemaBuilder.js

@@ -0,0 +1,2 @@
+import{a,b}from"../chunk-Z72HXYKX.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 {};