yedra 0.20.11 → 0.20.13

package/dist/src/validation/lazy.d.ts

@@ -0,0 +1,48 @@
+import { ModifiableSchema } from './modifiable.js';
+import type { Schema } from './schema.js';
+/**
+ * Run a function while collecting lazy schema definitions.
+ * Any `LazySchema` whose `documentation()` is called during `fn`
+ * will register its full definition in the returned map.
+ */
+export declare function collectLazySchemas<T>(fn: () => T): {
+    result: T;
+    schemas: Map<string, object>;
+};
+/**
+ * A schema that defers evaluation to support recursive definitions.
+ * The getter function is called lazily on each parse/documentation
+ * invocation, breaking the circular reference at definition time.
+ *
+ * Usage:
+ * ```typescript
+ * interface Category {
+ *   name: string;
+ *   subcategories: Category[];
+ * }
+ *
+ * const category: y.LazySchema<Category> = y.lazy("Category", () =>
+ *   y.object({
+ *     name: y.string(),
+ *     subcategories: category.array(),
+ *   }),
+ * );
+ * ```
+ */
+export declare class LazySchema<T> extends ModifiableSchema<T> {
+    readonly schemaName: string;
+    private readonly getter;
+    constructor(name: string, getter: () => Schema<T>);
+    parse(obj: unknown): T;
+    documentation(): object;
+    private registerSchema;
+    isOptional(): boolean;
+}
+/**
+ * Create a lazily-evaluated schema for recursive type definitions.
+ * @param name - The schema name, used for `$ref` in OpenAPI documentation.
+ * @param getter - A function that returns the schema. Called at
+ *   parse time, not at definition time, so circular references
+ *   are safe.
+ */
+export declare const lazy: <T>(name: string, getter: () => Schema<T>) => LazySchema<T>;

package/dist/src/validation/lazy.js

@@ -0,0 +1,78 @@
+import { ModifiableSchema } from './modifiable.js';
+/**
+ * Temporary context used during OpenAPI doc generation to accumulate
+ * lazy schema definitions. Set by `collectLazySchemas()`, read by
+ * `LazySchema.documentation()`. Not a persistent global registry —
+ * only lives for the duration of a single doc generation call.
+ */
+let schemaCollector = null;
+/**
+ * Run a function while collecting lazy schema definitions.
+ * Any `LazySchema` whose `documentation()` is called during `fn`
+ * will register its full definition in the returned map.
+ */
+export function collectLazySchemas(fn) {
+    const schemas = new Map();
+    schemaCollector = schemas;
+    try {
+        const result = fn();
+        return { result, schemas };
+    }
+    finally {
+        schemaCollector = null;
+    }
+}
+/**
+ * A schema that defers evaluation to support recursive definitions.
+ * The getter function is called lazily on each parse/documentation
+ * invocation, breaking the circular reference at definition time.
+ *
+ * Usage:
+ * ```typescript
+ * interface Category {
+ *   name: string;
+ *   subcategories: Category[];
+ * }
+ *
+ * const category: y.LazySchema<Category> = y.lazy("Category", () =>
+ *   y.object({
+ *     name: y.string(),
+ *     subcategories: category.array(),
+ *   }),
+ * );
+ * ```
+ */
+export class LazySchema extends ModifiableSchema {
+    constructor(name, getter) {
+        super();
+        this.schemaName = name;
+        this.getter = getter;
+    }
+    parse(obj) {
+        return this.getter().parse(obj);
+    }
+    documentation() {
+        if (schemaCollector && !schemaCollector.has(this.schemaName)) {
+            this.registerSchema(schemaCollector);
+        }
+        return { $ref: `#/components/schemas/${this.schemaName}` };
+    }
+    registerSchema(collector) {
+        // Set a placeholder first to break infinite recursion —
+        // if the getter references this schema, documentation()
+        // will see the key already exists and skip re-registration.
+        collector.set(this.schemaName, {});
+        collector.set(this.schemaName, this.getter().documentation());
+    }
+    isOptional() {
+        return this.getter().isOptional();
+    }
+}
+/**
+ * Create a lazily-evaluated schema for recursive type definitions.
+ * @param name - The schema name, used for `$ref` in OpenAPI documentation.
+ * @param getter - A function that returns the schema. Called at
+ *   parse time, not at definition time, so circular references
+ *   are safe.
+ */
+export const lazy = (name, getter) => new LazySchema(name, getter);

package/dist/src/validation/modifiable.d.ts

@@ -0,0 +1,105 @@
+import type { Typeof } from './body.js';
+import { DocSchema } from './doc.js';
+import { Schema } from './schema.js';
+export declare abstract class ModifiableSchema<T> extends Schema<T> {
+    /**
+     * Mark this schema as optional.
+     */
+    optional(): OptionalSchema<T>;
+    /**
+     * Provide a default value. If the input is undefined or null, the default
+     * value is returned instead.
+     * @param value - The default value.
+     */
+    default(value: T): DefaultSchema<T>;
+    /**
+     * Add a custom validation predicate. The inner schema is parsed first,
+     * then the predicate is checked against the parsed value.
+     * @param fn - A predicate that returns true if the value is valid, or a
+     *   string error message if it is not.
+     */
+    refine(fn: (value: T) => boolean | string, docs?: Record<string, unknown>): RefinedSchema<T>;
+    describe(description: string, example?: T): DocSchema<T>;
+    array(): ArraySchema<Schema<T>>;
+}
+declare class OptionalSchema<T> extends Schema<T | undefined> {
+    private schema;
+    constructor(schema: Schema<T>);
+    /**
+     * Add a description and example to the schema.
+     * @param doc - The documentation.
+     * @deprecated - Use .describe() instead.
+     */
+    doc(doc: {
+        description: string;
+        example?: T;
+    }): DocSchema<T | undefined>;
+    describe(description: string, example?: T): DocSchema<T | undefined>;
+    array(): ArraySchema<Schema<T | undefined>>;
+    parse(obj: unknown): T | undefined;
+    documentation(): object;
+    isOptional(): boolean;
+}
+declare class DefaultSchema<T> extends Schema<T> {
+    private readonly schema;
+    private readonly defaultValue;
+    constructor(schema: Schema<T>, defaultValue: T);
+    describe(description: string, example?: T): DocSchema<T>;
+    array(): ArraySchema<Schema<T>>;
+    parse(obj: unknown): T;
+    documentation(): object;
+    isOptional(): boolean;
+}
+export declare class RefinedSchema<T> extends ModifiableSchema<T> {
+    private readonly schema;
+    private readonly predicate;
+    private readonly docs?;
+    constructor(schema: Schema<T>, predicate: (value: T) => boolean | string, docs?: Record<string, unknown>);
+    /**
+     * Set the minimum length/items for strings and arrays.
+     * @param value - The minimum constraint.
+     */
+    min(value: number): RefinedSchema<T>;
+    /**
+     * Set the maximum length/items for strings and arrays.
+     * @param value - The maximum constraint.
+     */
+    max(value: number): RefinedSchema<T>;
+    /**
+     * Set the exact length/items for strings and arrays.
+     * @param value - The exact constraint.
+     */
+    length(value: number): RefinedSchema<T>;
+    parse(obj: unknown): T;
+    documentation(): object;
+    isOptional(): boolean;
+}
+export declare class ArraySchema<ItemSchema extends Schema<unknown>> extends ModifiableSchema<Typeof<ItemSchema>[]> {
+    private readonly itemSchema;
+    constructor(itemSchema: ItemSchema);
+    /**
+     * Set the minimum number of items for arrays.
+     * @param items - The minimum number of items.
+     */
+    min(items: number): RefinedSchema<Typeof<ItemSchema>[]>;
+    /**
+     * Set the maximum number of items for arrays.
+     * @param items - The maximum number of items.
+     */
+    max(items: number): RefinedSchema<Typeof<ItemSchema>[]>;
+    /**
+     * Set the exact number of items for arrays.
+     * This is equivalent to calling both min and max.
+     * @param items - The number of items.
+     */
+    length(items: number): RefinedSchema<Typeof<ItemSchema>[]>;
+    parse(obj: unknown): Typeof<ItemSchema>[];
+    documentation(): object;
+}
+/**
+ * A schema matching arrays of the provided item type.
+ * @param itemSchema - The schema for array items.
+ * @deprecated Use the .array() method instead.
+ */
+export declare const array: <ItemSchema extends Schema<unknown>>(itemSchema: ItemSchema) => ArraySchema<ItemSchema>;
+export {};

package/dist/src/validation/modifiable.js

@@ -0,0 +1,223 @@
+import { DocSchema } from './doc.js';
+import { Issue, ValidationError } from './error.js';
+import { Schema } from './schema.js';
+export class ModifiableSchema extends Schema {
+    /**
+     * Mark this schema as optional.
+     */
+    optional() {
+        return new OptionalSchema(this);
+    }
+    /**
+     * Provide a default value. If the input is undefined or null, the default
+     * value is returned instead.
+     * @param value - The default value.
+     */
+    default(value) {
+        return new DefaultSchema(this, value);
+    }
+    /**
+     * Add a custom validation predicate. The inner schema is parsed first,
+     * then the predicate is checked against the parsed value.
+     * @param fn - A predicate that returns true if the value is valid, or a
+     *   string error message if it is not.
+     */
+    refine(fn, docs) {
+        return new RefinedSchema(this, fn, docs);
+    }
+    describe(description, example) {
+        return new DocSchema(this, description, example);
+    }
+    array() {
+        return new ArraySchema(this);
+    }
+}
+class OptionalSchema extends Schema {
+    constructor(schema) {
+        super();
+        this.schema = schema;
+    }
+    /**
+     * Add a description and example to the schema.
+     * @param doc - The documentation.
+     * @deprecated - Use .describe() instead.
+     */
+    doc(doc) {
+        return new DocSchema(this, doc.description, doc.example);
+    }
+    describe(description, example) {
+        return new DocSchema(this, description, example);
+    }
+    array() {
+        return new ArraySchema(this);
+    }
+    parse(obj) {
+        if (obj === undefined) {
+            return undefined;
+        }
+        return this.schema.parse(obj);
+    }
+    documentation() {
+        return this.schema.documentation();
+    }
+    isOptional() {
+        return true;
+    }
+}
+class DefaultSchema extends Schema {
+    constructor(schema, defaultValue) {
+        super();
+        this.schema = schema;
+        this.defaultValue = defaultValue;
+    }
+    describe(description, example) {
+        return new DocSchema(this, description, example);
+    }
+    array() {
+        return new ArraySchema(this);
+    }
+    parse(obj) {
+        if (obj === undefined || obj === null) {
+            return this.defaultValue;
+        }
+        return this.schema.parse(obj);
+    }
+    documentation() {
+        return {
+            ...this.schema.documentation(),
+            default: this.defaultValue,
+        };
+    }
+    isOptional() {
+        return true;
+    }
+}
+export class RefinedSchema extends ModifiableSchema {
+    constructor(schema, predicate, docs) {
+        super();
+        this.schema = schema;
+        this.predicate = predicate;
+        this.docs = docs;
+    }
+    /**
+     * Set the minimum length/items for strings and arrays.
+     * @param value - The minimum constraint.
+     */
+    min(value) {
+        const docs = this.documentation();
+        const isArray = docs.type === 'array';
+        return this.refine(((v) => {
+            const len = v.length;
+            return (len >= value ||
+                (isArray
+                    ? `Must have at least ${value} items`
+                    : `Must be at least ${value} characters`));
+        }), isArray ? { minItems: value } : { minLength: value });
+    }
+    /**
+     * Set the maximum length/items for strings and arrays.
+     * @param value - The maximum constraint.
+     */
+    max(value) {
+        const docs = this.documentation();
+        const isArray = docs.type === 'array';
+        return this.refine(((v) => {
+            const len = v.length;
+            return (len <= value ||
+                (isArray
+                    ? `Must have at most ${value} items`
+                    : `Must be at most ${value} characters`));
+        }), isArray ? { maxItems: value } : { maxLength: value });
+    }
+    /**
+     * Set the exact length/items for strings and arrays.
+     * @param value - The exact constraint.
+     */
+    length(value) {
+        return this.min(value).max(value);
+    }
+    parse(obj) {
+        const parsed = this.schema.parse(obj);
+        const result = this.predicate(parsed);
+        if (result === true) {
+            return parsed;
+        }
+        const message = typeof result === 'string' ? result : 'Validation failed';
+        throw new ValidationError([new Issue([], message)]);
+    }
+    documentation() {
+        return {
+            ...this.schema.documentation(),
+            ...this.docs,
+        };
+    }
+    isOptional() {
+        return this.schema.isOptional();
+    }
+}
+export class ArraySchema extends ModifiableSchema {
+    constructor(itemSchema) {
+        super();
+        this.itemSchema = itemSchema;
+    }
+    /**
+     * Set the minimum number of items for arrays.
+     * @param items - The minimum number of items.
+     */
+    min(items) {
+        return this.refine((arr) => arr.length >= items || `Must have at least ${items} items`, { minItems: items });
+    }
+    /**
+     * Set the maximum number of items for arrays.
+     * @param items - The maximum number of items.
+     */
+    max(items) {
+        return this.refine((arr) => arr.length <= items || `Must have at most ${items} items`, { maxItems: items });
+    }
+    /**
+     * Set the exact number of items for arrays.
+     * This is equivalent to calling both min and max.
+     * @param items - The number of items.
+     */
+    length(items) {
+        return this.min(items).refine((arr) => arr.length <= items || `Must have at most ${items} items`, { maxItems: items });
+    }
+    parse(obj) {
+        if (!Array.isArray(obj)) {
+            throw new ValidationError([
+                new Issue([], `Expected array but got ${typeof obj}`),
+            ]);
+        }
+        const elems = [];
+        const issues = [];
+        for (let i = 0; i < obj.length; ++i) {
+            try {
+                elems.push(this.itemSchema.parse(obj[i]));
+            }
+            catch (error) {
+                if (error instanceof ValidationError) {
+                    issues.push(...error.withPrefix(i.toString()));
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        if (issues.length > 0) {
+            throw new ValidationError(issues);
+        }
+        return elems;
+    }
+    documentation() {
+        return {
+            type: 'array',
+            items: this.itemSchema.documentation(),
+        };
+    }
+}
+/**
+ * A schema matching arrays of the provided item type.
+ * @param itemSchema - The schema for array items.
+ * @deprecated Use the .array() method instead.
+ */
+export const array = (itemSchema) => new ArraySchema(itemSchema);

package/dist/src/validation/none.d.ts

@@ -0,0 +1,10 @@
+import type { Readable } from 'node:stream';
+import { BodyType } from './body.js';
+export declare class NoneBody extends BodyType<undefined, undefined> {
+    deserialize(_stream: Readable, _contentType: string): Promise<undefined>;
+    bodyDocs(): object;
+}
+/**
+ * Accepts no input body.
+ */
+export declare const none: () => NoneBody;

package/dist/src/validation/none.js

@@ -0,0 +1,14 @@
+import { BodyType } from './body.js';
+export class NoneBody extends BodyType {
+    deserialize(_stream, _contentType) {
+        return Promise.resolve(undefined);
+    }
+    bodyDocs() {
+        // TODO
+        return {};
+    }
+}
+/**
+ * Accepts no input body.
+ */
+export const none = () => new NoneBody();

package/dist/src/validation/null.d.ts

@@ -0,0 +1,10 @@
+import { ModifiableSchema } from './modifiable.js';
+declare class NullSchema extends ModifiableSchema<null> {
+    parse(obj: unknown): null;
+    documentation(): object;
+}
+/**
+ * A schema that matches only null.
+ */
+export declare const _null: () => NullSchema;
+export {};

package/dist/src/validation/null.js

@@ -0,0 +1,21 @@
+import { Issue, ValidationError } from './error.js';
+import { ModifiableSchema } from './modifiable.js';
+class NullSchema extends ModifiableSchema {
+    parse(obj) {
+        if (obj !== null) {
+            throw new ValidationError([
+                new Issue([], `Expected null but got ${typeof obj}`),
+            ]);
+        }
+        return null;
+    }
+    documentation() {
+        return {
+            type: 'null',
+        };
+    }
+}
+/**
+ * A schema that matches only null.
+ */
+export const _null = () => new NullSchema();

package/dist/src/validation/number.d.ts

@@ -0,0 +1,23 @@
+import { ModifiableSchema } from './modifiable.js';
+declare class NumberSchema extends ModifiableSchema<number> {
+    private readonly minValue?;
+    private readonly maxValue?;
+    constructor(min?: number, max?: number);
+    /**
+     * Set the minimum value the number is allowed to be.
+     * @param value - The minimum value.
+     */
+    min(value: number): NumberSchema;
+    /**
+     * Set the maximum value the number is allowed to be.
+     * @param value - The maximum value.
+     */
+    max(value: number): NumberSchema;
+    parse(obj: unknown): number;
+    documentation(): object;
+}
+/**
+ * A schema that matches a number.
+ */
+export declare const number: () => NumberSchema;
+export {};

package/dist/src/validation/number.js

@@ -0,0 +1,58 @@
+import { Issue, ValidationError } from './error.js';
+import { ModifiableSchema } from './modifiable.js';
+class NumberSchema extends ModifiableSchema {
+    constructor(min, max) {
+        super();
+        this.minValue = min;
+        this.maxValue = max;
+    }
+    /**
+     * Set the minimum value the number is allowed to be.
+     * @param value - The minimum value.
+     */
+    min(value) {
+        return new NumberSchema(value, this.maxValue);
+    }
+    /**
+     * Set the maximum value the number is allowed to be.
+     * @param value - The maximum value.
+     */
+    max(value) {
+        return new NumberSchema(this.minValue, value);
+    }
+    parse(obj) {
+        if (typeof obj !== 'number' && typeof obj !== 'string') {
+            throw new ValidationError([
+                new Issue([], `Expected number but got ${typeof obj}`),
+            ]);
+        }
+        const num = typeof obj === 'number' ? obj : Number.parseFloat(obj);
+        if (Number.isNaN(num)) {
+            throw new ValidationError([
+                new Issue([], `Expected number but got ${typeof obj}`),
+            ]);
+        }
+        if (this.minValue !== undefined && num < this.minValue) {
+            throw new ValidationError([
+                new Issue([], `Must be at least ${this.minValue}, but was ${num}`),
+            ]);
+        }
+        if (this.maxValue !== undefined && num > this.maxValue) {
+            throw new ValidationError([
+                new Issue([], `Must be at most ${this.maxValue}, but was ${num}`),
+            ]);
+        }
+        return num;
+    }
+    documentation() {
+        return {
+            type: 'number',
+            ...(this.minValue !== undefined && { minimum: this.minValue }),
+            ...(this.maxValue !== undefined && { maximum: this.maxValue }),
+        };
+    }
+}
+/**
+ * A schema that matches a number.
+ */
+export const number = () => new NumberSchema();

package/dist/src/validation/object.d.ts

@@ -0,0 +1,38 @@
+import type { Typeof } from './body.js';
+import { ModifiableSchema } from './modifiable.js';
+import { Schema } from './schema.js';
+/**
+ * Make a union of all keys that are not extended by undefined
+ * (i.e. have undefined as a variant) of the specified type.
+ */
+type RequiredKeys<T> = {
+    [K in keyof T]: undefined extends T[K] ? never : K;
+}[keyof T];
+/**
+ * Make all fields that have undefined as a variant optional.
+ */
+type MakeFieldsOptional<T> = Pick<T, RequiredKeys<T>> & Partial<T>;
+export declare class ObjectSchema<Shape extends Record<string, Schema<unknown>>> extends ModifiableSchema<MakeFieldsOptional<{
+    [K in keyof Shape]: Typeof<Shape[K]>;
+}>> {
+    readonly shape: Shape;
+    private lax;
+    constructor(shape: Shape, lax: boolean);
+    parse(obj: unknown): MakeFieldsOptional<{
+        [K in keyof Shape]: Typeof<Shape[K]>;
+    }>;
+    documentation(): object;
+}
+/**
+ * A schema matching a JavaScript object of the specified shape. Fields which
+ * can be undefined are automatically marked as optional.
+ * @param shape - The object shape.
+ *
+ * ```typescript
+ * const schema = y.object({ num: y.number(), str: y.string().optional() });
+ * type SchemaType = y.Typeof<typeof schema>; // { num: number, str?: string }
+ * ```
+ */
+export declare const object: <Shape extends Record<string, Schema<unknown>>>(shape: Shape) => ObjectSchema<Shape>;
+export declare const laxObject: <Shape extends Record<string, Schema<unknown>>>(shape: Shape) => ObjectSchema<Shape>;
+export {};