forgeframe 0.0.1

package/dist/props/prop.d.ts

@@ -0,0 +1,636 @@
+/**
+ * @packageDocumentation
+ * Lightweight prop schema builders for ForgeFrame.
+ *
+ * @remarks
+ * This module provides a fluent, Zod-like API for defining prop schemas.
+ * All schemas implement StandardSchemaV1, enabling seamless integration
+ * with ForgeFrame's validation pipeline and compatibility with external
+ * schema libraries.
+ *
+ * @example
+ * ```typescript
+ * import ForgeFrame, { prop } from 'forgeframe';
+ *
+ * const MyComponent = ForgeFrame.create({
+ *   tag: 'my-component',
+ *   url: '/component',
+ *   props: {
+ *     name: prop.string(),
+ *     count: prop.number().default(0),
+ *     onSubmit: prop.function<(data: unknown) => void>().optional(),
+ *   },
+ * });
+ * ```
+ */
+import type { StandardSchemaV1, StandardSchemaV1Props, StandardSchemaV1Result } from './schema';
+/**
+ * Abstract base class for all prop schemas.
+ *
+ * @remarks
+ * Implements StandardSchemaV1 for compatibility with ForgeFrame's validation
+ * system and external schema libraries like Zod, Valibot, and ArkType.
+ *
+ * @typeParam T - The output type after validation
+ *
+ * @public
+ */
+export declare abstract class PropSchema<T> implements StandardSchemaV1<unknown, T> {
+    /** @internal */
+    protected _optional: boolean;
+    /** @internal */
+    protected _nullable: boolean;
+    /** @internal */
+    protected _default?: T | (() => T);
+    /**
+     * StandardSchemaV1 implementation.
+     * @internal
+     */
+    readonly '~standard': StandardSchemaV1Props<unknown, T>;
+    /**
+     * Validates a non-undefined value.
+     * @internal
+     */
+    protected abstract _validate(value: unknown): StandardSchemaV1Result<T>;
+    /**
+     * Marks this prop as optional.
+     *
+     * @returns Schema that accepts undefined
+     *
+     * @example
+     * ```typescript
+     * props: {
+     *   nickname: prop.string().optional(),
+     * }
+     * ```
+     */
+    optional(): PropSchema<T | undefined>;
+    /**
+     * Marks this prop as nullable (accepts null).
+     *
+     * @returns Schema that accepts null
+     *
+     * @example
+     * ```typescript
+     * props: {
+     *   middleName: prop.string().nullable(),
+     * }
+     * ```
+     */
+    nullable(): PropSchema<T | null>;
+    /**
+     * Sets a default value for this prop.
+     *
+     * @param value - Default value or function returning default
+     * @returns Schema with default value
+     *
+     * @example
+     * ```typescript
+     * props: {
+     *   count: prop.number().default(0),
+     *   id: prop.string().default(() => crypto.randomUUID()),
+     * }
+     * ```
+     */
+    default(value: T | (() => T)): PropSchema<T>;
+    /**
+     * Creates a shallow clone of this schema.
+     * @internal
+     */
+    protected abstract _clone(): PropSchema<T>;
+}
+/**
+ * Schema for string props with optional validation constraints.
+ *
+ * @public
+ */
+export declare class StringSchema extends PropSchema<string> {
+    /** @internal */
+    private _minLength?;
+    /** @internal */
+    private _maxLength?;
+    /** @internal */
+    private _pattern?;
+    /** @internal */
+    private _patternMessage?;
+    /** @internal */
+    private _trim;
+    /** @internal */
+    protected _validate(value: unknown): StandardSchemaV1Result<string>;
+    /** @internal */
+    protected _clone(): StringSchema;
+    /**
+     * Requires minimum string length.
+     *
+     * @param length - Minimum number of characters
+     *
+     * @example
+     * ```typescript
+     * name: prop.string().min(2)
+     * ```
+     */
+    min(length: number): StringSchema;
+    /**
+     * Requires maximum string length.
+     *
+     * @param length - Maximum number of characters
+     *
+     * @example
+     * ```typescript
+     * bio: prop.string().max(500)
+     * ```
+     */
+    max(length: number): StringSchema;
+    /**
+     * Requires exact string length.
+     *
+     * @param length - Exact number of characters required
+     *
+     * @example
+     * ```typescript
+     * code: prop.string().length(6)
+     * ```
+     */
+    length(length: number): StringSchema;
+    /**
+     * Requires string to match a regex pattern.
+     *
+     * @param regex - Pattern to match
+     * @param message - Optional custom error message
+     *
+     * @example
+     * ```typescript
+     * slug: prop.string().pattern(/^[a-z0-9-]+$/, 'Invalid slug format')
+     * ```
+     */
+    pattern(regex: RegExp, message?: string): StringSchema;
+    /**
+     * Validates as email address.
+     *
+     * @example
+     * ```typescript
+     * email: prop.string().email()
+     * ```
+     */
+    email(): StringSchema;
+    /**
+     * Validates as URL.
+     *
+     * @example
+     * ```typescript
+     * website: prop.string().url()
+     * ```
+     */
+    url(): StringSchema;
+    /**
+     * Validates as UUID.
+     *
+     * @example
+     * ```typescript
+     * id: prop.string().uuid()
+     * ```
+     */
+    uuid(): StringSchema;
+    /**
+     * Trims whitespace from both ends of the string.
+     *
+     * @remarks
+     * The trimmed value is used for validation and returned as the result.
+     *
+     * @example
+     * ```typescript
+     * name: prop.string().trim()
+     * username: prop.string().trim().min(3)
+     * ```
+     */
+    trim(): StringSchema;
+    /**
+     * Requires non-empty string (at least 1 character).
+     *
+     * @example
+     * ```typescript
+     * title: prop.string().nonempty()
+     * ```
+     */
+    nonempty(): StringSchema;
+}
+/**
+ * Schema for number props with optional validation constraints.
+ *
+ * @public
+ */
+export declare class NumberSchema extends PropSchema<number> {
+    /** @internal */
+    private _min?;
+    /** @internal */
+    private _max?;
+    /** @internal */
+    private _int;
+    /** @internal */
+    protected _validate(value: unknown): StandardSchemaV1Result<number>;
+    /** @internal */
+    protected _clone(): NumberSchema;
+    /**
+     * Requires minimum value.
+     *
+     * @param n - Minimum value (inclusive)
+     *
+     * @example
+     * ```typescript
+     * age: prop.number().min(0)
+     * ```
+     */
+    min(n: number): NumberSchema;
+    /**
+     * Requires maximum value.
+     *
+     * @param n - Maximum value (inclusive)
+     *
+     * @example
+     * ```typescript
+     * rating: prop.number().max(5)
+     * ```
+     */
+    max(n: number): NumberSchema;
+    /**
+     * Requires integer value.
+     *
+     * @example
+     * ```typescript
+     * count: prop.number().int()
+     * ```
+     */
+    int(): NumberSchema;
+    /**
+     * Requires positive number (> 0).
+     *
+     * @example
+     * ```typescript
+     * price: prop.number().positive()
+     * ```
+     */
+    positive(): NumberSchema;
+    /**
+     * Requires non-negative number (>= 0).
+     *
+     * @example
+     * ```typescript
+     * quantity: prop.number().nonnegative()
+     * ```
+     */
+    nonnegative(): NumberSchema;
+    /**
+     * Requires negative number (< 0).
+     *
+     * @example
+     * ```typescript
+     * debt: prop.number().negative()
+     * ```
+     */
+    negative(): NumberSchema;
+}
+/**
+ * Schema for boolean props.
+ *
+ * @public
+ */
+export declare class BooleanSchema extends PropSchema<boolean> {
+    /** @internal */
+    protected _validate(value: unknown): StandardSchemaV1Result<boolean>;
+    /** @internal */
+    protected _clone(): BooleanSchema;
+}
+/**
+ * Schema for function props.
+ *
+ * @typeParam T - Function type
+ *
+ * @public
+ */
+export declare class FunctionSchema<T extends (...args: any[]) => any = (...args: any[]) => any> extends PropSchema<T> {
+    /** @internal */
+    protected _validate(value: unknown): StandardSchemaV1Result<T>;
+    /** @internal */
+    protected _clone(): FunctionSchema<T>;
+}
+/**
+ * Schema for array props with optional item validation.
+ *
+ * @typeParam T - Array item type
+ *
+ * @public
+ */
+export declare class ArraySchema<T = unknown> extends PropSchema<T[]> {
+    /** @internal */
+    private _itemSchema?;
+    /** @internal */
+    private _minLength?;
+    /** @internal */
+    private _maxLength?;
+    /** @internal */
+    protected _validate(value: unknown): StandardSchemaV1Result<T[]>;
+    /** @internal */
+    protected _clone(): ArraySchema<T>;
+    /**
+     * Specifies the schema for array items.
+     *
+     * @typeParam U - Item type
+     * @param schema - Schema for validating each item
+     *
+     * @example
+     * ```typescript
+     * tags: prop.array().of(prop.string())
+     * scores: prop.array().of(prop.number().min(0).max(100))
+     * ```
+     */
+    of<U>(schema: PropSchema<U>): ArraySchema<U>;
+    /**
+     * Requires minimum array length.
+     *
+     * @param length - Minimum number of items
+     *
+     * @example
+     * ```typescript
+     * items: prop.array().min(1)
+     * ```
+     */
+    min(length: number): ArraySchema<T>;
+    /**
+     * Requires maximum array length.
+     *
+     * @param length - Maximum number of items
+     *
+     * @example
+     * ```typescript
+     * selections: prop.array().max(5)
+     * ```
+     */
+    max(length: number): ArraySchema<T>;
+    /**
+     * Requires non-empty array.
+     *
+     * @example
+     * ```typescript
+     * options: prop.array().nonempty()
+     * ```
+     */
+    nonempty(): ArraySchema<T>;
+}
+/**
+ * Infers the output type from an object shape definition.
+ * @public
+ */
+export type InferObjectShape<S extends Record<string, PropSchema<unknown>>> = {
+    [K in keyof S]: S[K] extends PropSchema<infer U> ? U : never;
+};
+/**
+ * Schema for object props with optional shape validation.
+ *
+ * @typeParam T - Object type
+ *
+ * @public
+ */
+export declare class ObjectSchema<T extends object = Record<string, unknown>> extends PropSchema<T> {
+    /** @internal */
+    private _shape?;
+    /** @internal */
+    private _strict;
+    /** @internal */
+    protected _validate(value: unknown): StandardSchemaV1Result<T>;
+    /** @internal */
+    protected _clone(): ObjectSchema<T>;
+    /**
+     * Defines the shape of the object with field schemas.
+     *
+     * @typeParam S - Shape definition type
+     * @param shape - Object mapping field names to schemas
+     *
+     * @example
+     * ```typescript
+     * user: prop.object().shape({
+     *   name: prop.string(),
+     *   age: prop.number().optional(),
+     * })
+     * ```
+     */
+    shape<S extends Record<string, PropSchema<unknown>>>(shape: S): ObjectSchema<InferObjectShape<S>>;
+    /**
+     * Rejects objects with unknown keys.
+     *
+     * @example
+     * ```typescript
+     * config: prop.object().shape({ debug: prop.boolean() }).strict()
+     * ```
+     */
+    strict(): ObjectSchema<T>;
+}
+/**
+ * Schema for literal value props.
+ *
+ * @typeParam T - Literal type
+ *
+ * @public
+ */
+export declare class LiteralSchema<T extends string | number | boolean> extends PropSchema<T> {
+    /** @internal */
+    private _value;
+    constructor(value: T);
+    /** @internal */
+    protected _validate(value: unknown): StandardSchemaV1Result<T>;
+    /** @internal */
+    protected _clone(): LiteralSchema<T>;
+}
+/**
+ * Schema for enum/union value props.
+ *
+ * @typeParam T - Union of allowed values
+ *
+ * @public
+ */
+export declare class EnumSchema<T extends string | number> extends PropSchema<T> {
+    /** @internal */
+    private _values;
+    constructor(values: readonly T[]);
+    /** @internal */
+    protected _validate(value: unknown): StandardSchemaV1Result<T>;
+    /** @internal */
+    protected _clone(): EnumSchema<T>;
+}
+/**
+ * Schema that accepts any value.
+ *
+ * @remarks
+ * Accepts null by default since "any" means any value.
+ *
+ * @public
+ */
+export declare class AnySchema extends PropSchema<unknown> {
+    constructor();
+    /** @internal */
+    protected _validate(value: unknown): StandardSchemaV1Result<unknown>;
+    /** @internal */
+    protected _clone(): AnySchema;
+}
+/**
+ * Factory functions for creating prop schemas.
+ *
+ * @remarks
+ * Use these functions to define props with a fluent, chainable API.
+ * All schemas implement StandardSchemaV1 and integrate seamlessly with
+ * ForgeFrame's validation system.
+ *
+ * @example
+ * ```typescript
+ * import ForgeFrame, { prop } from 'forgeframe';
+ *
+ * const MyComponent = ForgeFrame.create({
+ *   tag: 'my-component',
+ *   url: '/component',
+ *   props: {
+ *     // Required string
+ *     name: prop.string(),
+ *
+ *     // Number with default
+ *     count: prop.number().default(0),
+ *
+ *     // Optional email
+ *     email: prop.string().email().optional(),
+ *
+ *     // Function callback
+ *     onSubmit: prop.function<(data: { ok: boolean }) => void>(),
+ *
+ *     // Array of strings
+ *     tags: prop.array().of(prop.string()),
+ *
+ *     // Nested object
+ *     config: prop.object().shape({
+ *       theme: prop.enum(['light', 'dark']).default('light'),
+ *       debug: prop.boolean().default(false),
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare const prop: {
+    /**
+     * Creates a string schema.
+     *
+     * @example
+     * ```typescript
+     * prop.string()
+     * prop.string().min(1).max(100)
+     * prop.string().email()
+     * prop.string().url()
+     * prop.string().pattern(/^[a-z]+$/)
+     * ```
+     */
+    readonly string: () => StringSchema;
+    /**
+     * Creates a number schema.
+     *
+     * @example
+     * ```typescript
+     * prop.number()
+     * prop.number().min(0).max(100)
+     * prop.number().int()
+     * prop.number().positive()
+     * ```
+     */
+    readonly number: () => NumberSchema;
+    /**
+     * Creates a boolean schema.
+     *
+     * @example
+     * ```typescript
+     * prop.boolean()
+     * prop.boolean().default(false)
+     * ```
+     */
+    readonly boolean: () => BooleanSchema;
+    /**
+     * Creates a function schema.
+     *
+     * @typeParam T - Function type signature
+     *
+     * @example
+     * ```typescript
+     * prop.function()
+     * prop.function<() => void>()
+     * prop.function<(data: { id: string }) => Promise<void>>()
+     * ```
+     */
+    readonly function: <T extends (...args: any[]) => any = (...args: any[]) => any>() => FunctionSchema<T>;
+    /**
+     * Creates an array schema.
+     *
+     * @typeParam T - Array item type
+     *
+     * @example
+     * ```typescript
+     * prop.array()
+     * prop.array().of(prop.string())
+     * prop.array().of(prop.number()).min(1).max(10)
+     * ```
+     */
+    readonly array: <T = unknown>() => ArraySchema<T>;
+    /**
+     * Creates an object schema.
+     *
+     * @typeParam T - Object type
+     *
+     * @example
+     * ```typescript
+     * prop.object()
+     * prop.object().shape({
+     *   name: prop.string(),
+     *   age: prop.number().optional(),
+     * })
+     * prop.object().shape({ key: prop.string() }).strict()
+     * ```
+     */
+    readonly object: <T extends object = Record<string, unknown>>() => ObjectSchema<T>;
+    /**
+     * Creates a literal schema for exact value matching.
+     *
+     * @param value - The exact value to match
+     *
+     * @example
+     * ```typescript
+     * prop.literal('active')
+     * prop.literal(42)
+     * prop.literal(true)
+     * ```
+     */
+    readonly literal: <T extends string | number | boolean>(value: T) => LiteralSchema<T>;
+    /**
+     * Creates an enum schema for a set of allowed values.
+     *
+     * @param values - Array of allowed values
+     *
+     * @example
+     * ```typescript
+     * prop.enum(['pending', 'active', 'completed'])
+     * prop.enum([1, 2, 3])
+     * ```
+     */
+    readonly enum: <T extends string | number>(values: readonly T[]) => EnumSchema<T>;
+    /**
+     * Creates a schema that accepts any value.
+     *
+     * @remarks
+     * Use sparingly - prefer typed schemas when possible.
+     *
+     * @example
+     * ```typescript
+     * prop.any()
+     * ```
+     */
+    readonly any: () => AnySchema;
+};
+/**
+ * Type alias for the prop factory namespace.
+ * @public
+ */
+export type Prop = typeof prop;