yedra 0.20.2 → 0.20.4

package/dist/validation/doc.d.ts

@@ -1,4 +1,4 @@
-import { Schema } from './schema.js';
+import { Schema } from "./schema.js";
 export declare class DocSchema<T> extends Schema<T> {
     private readonly _schema;
     private readonly _description;

package/dist/validation/doc.js

@@ -1,4 +1,4 @@
-import { Schema } from './schema.js';
+import { Schema } from "./schema.js";
 export class DocSchema extends Schema {
     constructor(schema, description, example) {
         super();
@@ -12,7 +12,7 @@ export class DocSchema extends Schema {
     documentation() {
         return {
             description: this._description,
-            example: this._example,
+            ...(this._example !== undefined && { example: this._example }),
             ...this._schema.documentation(),
         };
     }

package/dist/validation/integer.d.ts

@@ -1,4 +1,4 @@
-import { ModifiableSchema } from './modifiable.js';
+import { ModifiableSchema } from "./modifiable.js";
 declare class IntegerSchema extends ModifiableSchema<number> {
     private readonly minValue?;
     private readonly maxValue?;

package/dist/validation/integer.js

@@ -1,5 +1,5 @@
-import { Issue, ValidationError } from './error.js';
-import { ModifiableSchema } from './modifiable.js';
+import { Issue, ValidationError } from "./error.js";
+import { ModifiableSchema } from "./modifiable.js";
 class IntegerSchema extends ModifiableSchema {
     constructor(min, max) {
         super();
@@ -12,7 +12,7 @@ class IntegerSchema extends ModifiableSchema {
      */
     min(value) {
         if (!Number.isInteger(value)) {
-            throw new Error('minimum value has to be an integer');
+            throw new Error("minimum value has to be an integer");
         }
         return new IntegerSchema(value, this.maxValue);
     }
@@ -22,17 +22,17 @@ class IntegerSchema extends ModifiableSchema {
      */
     max(value) {
         if (!Number.isInteger(value)) {
-            throw new Error('maximum value has to be an integer');
+            throw new Error("maximum value has to be an integer");
         }
         return new IntegerSchema(this.minValue, value);
     }
     parse(obj) {
-        if (typeof obj !== 'number' && typeof obj !== 'string') {
+        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);
+        const num = typeof obj === "number" ? obj : Number.parseFloat(obj);
         if (Number.isNaN(num) || !Number.isInteger(num)) {
             throw new ValidationError([
                 new Issue([], `Expected integer but got ${typeof obj}`),
@@ -52,9 +52,9 @@ class IntegerSchema extends ModifiableSchema {
     }
     documentation() {
         return {
-            type: 'integer',
-            minimum: this.minValue,
-            maximum: this.maxValue,
+            type: "integer",
+            ...(this.minValue !== undefined && { minimum: this.minValue }),
+            ...(this.maxValue !== undefined && { maximum: this.maxValue }),
         };
     }
 }

package/dist/validation/modifiable.d.ts

@@ -1,11 +1,24 @@
-import type { Typeof } from './body.js';
-import { DocSchema } from './doc.js';
-import { Schema } from './schema.js';
+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>>;
 }
@@ -27,27 +40,59 @@ declare class OptionalSchema<T> extends Schema<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;
-    private readonly minItems?;
-    private readonly maxItems?;
-    constructor(itemSchema: ItemSchema, minItems?: number, maxItems?: number);
+    constructor(itemSchema: ItemSchema);
     /**
      * Set the minimum number of items for arrays.
      * @param items - The minimum number of items.
      */
-    min(items: number): ArraySchema<ItemSchema>;
+    min(items: number): RefinedSchema<Typeof<ItemSchema>[]>;
     /**
      * Set the maximum number of items for arrays.
      * @param items - The maximum number of items.
      */
-    max(items: number): ArraySchema<ItemSchema>;
+    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): ArraySchema<ItemSchema>;
+    length(items: number): RefinedSchema<Typeof<ItemSchema>[]>;
     parse(obj: unknown): Typeof<ItemSchema>[];
     documentation(): object;
 }

package/dist/validation/modifiable.js

@@ -1,6 +1,6 @@
-import { DocSchema } from './doc.js';
-import { Issue, ValidationError } from './error.js';
-import { Schema } from './schema.js';
+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.
@@ -8,6 +8,23 @@ export class ModifiableSchema extends Schema {
     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);
     }
@@ -47,26 +64,115 @@ class OptionalSchema extends Schema {
         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, minItems, maxItems) {
+    constructor(itemSchema) {
         super();
         this.itemSchema = itemSchema;
-        this.minItems = minItems;
-        this.maxItems = maxItems;
     }
     /**
      * Set the minimum number of items for arrays.
      * @param items - The minimum number of items.
      */
     min(items) {
-        return new ArraySchema(this.itemSchema, items, this.maxItems);
+        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 new ArraySchema(this.itemSchema, this.minItems, items);
+        return this.refine((arr) => arr.length <= items || `Must have at most ${items} items`, { maxItems: items });
     }
     /**
      * Set the exact number of items for arrays.
@@ -74,7 +180,7 @@ export class ArraySchema extends ModifiableSchema {
      * @param items - The number of items.
      */
     length(items) {
-        return new ArraySchema(this.itemSchema, items, items);
+        return this.min(items).refine((arr) => arr.length <= items || `Must have at most ${items} items`, { maxItems: items });
     }
     parse(obj) {
         if (!Array.isArray(obj)) {
@@ -82,16 +188,6 @@ export class ArraySchema extends ModifiableSchema {
                 new Issue([], `Expected array but got ${typeof obj}`),
             ]);
         }
-        if (this.minItems && obj.length < this.minItems) {
-            throw new ValidationError([
-                new Issue([], `Must have at least ${this.minItems} items, but has ${obj.length}`),
-            ]);
-        }
-        if (this.maxItems && obj.length > this.maxItems) {
-            throw new ValidationError([
-                new Issue([], `Must have at most ${this.maxItems} items, but has ${obj.length}`),
-            ]);
-        }
         const elems = [];
         const issues = [];
         for (let i = 0; i < obj.length; ++i) {
@@ -114,10 +210,8 @@ export class ArraySchema extends ModifiableSchema {
     }
     documentation() {
         return {
-            type: 'array',
+            type: "array",
             items: this.itemSchema.documentation(),
-            minItems: this.minItems,
-            maxItems: this.maxItems,
         };
     }
 }

package/dist/validation/number.d.ts

@@ -1,4 +1,4 @@
-import { ModifiableSchema } from './modifiable.js';
+import { ModifiableSchema } from "./modifiable.js";
 declare class NumberSchema extends ModifiableSchema<number> {
     private readonly minValue?;
     private readonly maxValue?;

package/dist/validation/number.js

@@ -1,5 +1,5 @@
-import { Issue, ValidationError } from './error.js';
-import { ModifiableSchema } from './modifiable.js';
+import { Issue, ValidationError } from "./error.js";
+import { ModifiableSchema } from "./modifiable.js";
 class NumberSchema extends ModifiableSchema {
     constructor(min, max) {
         super();
@@ -21,12 +21,12 @@ class NumberSchema extends ModifiableSchema {
         return new NumberSchema(this.minValue, value);
     }
     parse(obj) {
-        if (typeof obj !== 'number' && typeof obj !== 'string') {
+        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);
+        const num = typeof obj === "number" ? obj : Number.parseFloat(obj);
         if (Number.isNaN(num)) {
             throw new ValidationError([
                 new Issue([], `Expected number but got ${typeof obj}`),
@@ -46,9 +46,9 @@ class NumberSchema extends ModifiableSchema {
     }
     documentation() {
         return {
-            type: 'number',
-            minimum: this.minValue,
-            maximum: this.maxValue,
+            type: "number",
+            ...(this.minValue !== undefined && { minimum: this.minValue }),
+            ...(this.maxValue !== undefined && { maximum: this.maxValue }),
         };
     }
 }

package/dist/validation/object.d.ts

@@ -1,6 +1,6 @@
-import type { Typeof } from './body.js';
-import { ModifiableSchema } from './modifiable.js';
-import { Schema } from './schema.js';
+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.
@@ -15,7 +15,7 @@ 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]>;
 }>> {
-    private shape;
+    readonly shape: Shape;
     private lax;
     constructor(shape: Shape, lax: boolean);
     parse(obj: unknown): MakeFieldsOptional<{

package/dist/validation/object.js

@@ -1,6 +1,6 @@
-import { Issue, ValidationError } from './error.js';
-import { ModifiableSchema } from './modifiable.js';
-import { Schema } from './schema.js';
+import { Issue, ValidationError } from "./error.js";
+import { ModifiableSchema } from "./modifiable.js";
+import { Schema } from "./schema.js";
 export class ObjectSchema extends ModifiableSchema {
     constructor(shape, lax) {
         super();
@@ -8,14 +8,14 @@ export class ObjectSchema extends ModifiableSchema {
         this.lax = lax;
     }
     parse(obj) {
-        if (typeof obj !== 'object') {
+        if (typeof obj !== "object") {
             throw new ValidationError([
                 new Issue([], `Expected object but got ${typeof obj}`),
             ]);
         }
         if (obj == null) {
             throw new ValidationError([
-                new Issue([], 'Expected object but got null'),
+                new Issue([], "Expected object but got null"),
             ]);
         }
         const result = {};
@@ -24,7 +24,7 @@ export class ObjectSchema extends ModifiableSchema {
             const propSchema = this.shape[prop];
             if (propSchema instanceof Schema) {
                 if (!(prop in obj || propSchema.isOptional())) {
-                    issues.push(new Issue([prop], 'Required'));
+                    issues.push(new Issue([prop], "Required"));
                     continue;
                 }
                 try {
@@ -45,7 +45,7 @@ export class ObjectSchema extends ModifiableSchema {
                 if (prop in this.shape) {
                     continue;
                 }
-                issues.push(new Issue([prop], 'Unrecognized'));
+                issues.push(new Issue([prop], "Unrecognized"));
             }
         }
         if (issues.length > 0) {
@@ -66,10 +66,10 @@ export class ObjectSchema extends ModifiableSchema {
             }
         }
         return {
-            type: 'object',
+            type: "object",
             properties,
-            required: required.length > 0 ? required : undefined,
-            additionalProperties: this.lax,
+            ...(required.length > 0 && { required }),
+            ...(this.lax && { additionalProperties: true }),
         };
     }
 }

package/dist/validation/schema.d.ts

@@ -1,10 +1,10 @@
-import type { Readable } from 'node:stream';
-import type { StandardSchemaV1 } from '@standard-schema/spec';
-import { BodyType } from './body.js';
+import type { Readable } from "node:stream";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import { BodyType } from "./body.js";
 /**
  * The base class for all schemas.
  */
-export declare abstract class Schema<T> extends BodyType<T, T> implements StandardSchemaV1<unknown, T> {
+export declare abstract class Schema<T> extends BodyType<T, T> implements StandardSchemaV1<T, T> {
     deserialize(stream: Readable, contentType: string): Promise<T>;
     bodyDocs(): object;
     /**
@@ -31,5 +31,5 @@ export declare abstract class Schema<T> extends BodyType<T, T> implements Standa
      *
      * @see https://standardschema.dev/
      */
-    get '~standard'(): StandardSchemaV1.Props<unknown, T>;
+    get "~standard"(): StandardSchemaV1.Props<T, T>;
 }

package/dist/validation/schema.js

@@ -1,5 +1,5 @@
-import { BodyType } from './body.js';
-import { Issue, ValidationError } from './error.js';
+import { BodyType } from "./body.js";
+import { Issue, ValidationError } from "./error.js";
 /**
  * The base class for all schemas.
  */
@@ -8,22 +8,22 @@ export class Schema extends BodyType {
         // Lazy import to keep this module browser-safe for yedra/schema.
         // deserialize() is only called server-side, so the Node-specific
         // stream utility is never resolved when bundled for the frontend.
-        const { readableToBuffer } = await import('../util/stream.js');
+        const { readableToBuffer } = await import("../util/stream.js");
         const buffer = await readableToBuffer(stream);
         if (buffer.length === 0) {
             return this.parse({});
         }
-        if (contentType !== 'application/json') {
+        if (contentType !== "application/json") {
             throw new ValidationError([
                 new Issue([], `Expected content type \`application/json\`, but got \`${contentType}\``),
             ]);
         }
-        const data = JSON.parse(Buffer.from(buffer).toString('utf8'));
+        const data = JSON.parse(Buffer.from(buffer).toString("utf8"));
         return this.parse(data);
     }
     bodyDocs() {
         return {
-            'application/json': {
+            "application/json": {
                 schema: this.documentation(),
             },
         };
@@ -44,10 +44,11 @@ export class Schema extends BodyType {
      *
      * @see https://standardschema.dev/
      */
-    get '~standard'() {
+    get "~standard"() {
         return {
             version: 1,
-            vendor: 'yedra',
+            vendor: "yedra",
+            types: {},
             // Wraps parse() to match Standard Schema's non-throwing convention:
             // returns { value } on success, { issues } on failure.
             validate: (value) => {

package/dist/validation/string.d.ts

@@ -1,16 +1,24 @@
-import { ModifiableSchema } from './modifiable.js';
+import { ModifiableSchema } from "./modifiable.js";
 declare class StringSchema extends ModifiableSchema<string> {
+    /**
+     * Set the minimum length the string is allowed to be.
+     * @param length - The minimum length.
+     */
+    min(length: number): import("./modifiable.js").RefinedSchema<string>;
+    /**
+     * Set the maximum length the string is allowed to be.
+     * @param length - The maximum length.
+     */
+    max(length: number): import("./modifiable.js").RefinedSchema<string>;
+    /**
+     * Require the string to be a valid email address.
+     */
+    email(): import("./modifiable.js").RefinedSchema<string>;
     /**
      * Require the string to match the specified pattern.
      * @param pattern - A regular expression.
      */
-    pattern(pattern: RegExp): PatternStringSchema;
-    parse(obj: unknown): string;
-    documentation(): object;
-}
-declare class PatternStringSchema extends ModifiableSchema<string> {
-    private readonly pattern;
-    constructor(pattern: RegExp);
+    pattern(pattern: RegExp): import("./modifiable.js").RefinedSchema<string>;
     parse(obj: unknown): string;
     documentation(): object;
 }

package/dist/validation/string.js

@@ -1,49 +1,47 @@
-import { Issue, ValidationError } from './error.js';
-import { ModifiableSchema } from './modifiable.js';
+import { Issue, ValidationError } from "./error.js";
+import { ModifiableSchema } from "./modifiable.js";
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 class StringSchema extends ModifiableSchema {
     /**
-     * Require the string to match the specified pattern.
-     * @param pattern - A regular expression.
+     * Set the minimum length the string is allowed to be.
+     * @param length - The minimum length.
      */
-    pattern(pattern) {
-        return new PatternStringSchema(pattern);
+    min(length) {
+        return this.refine((s) => s.length >= length || `Must be at least ${length} characters`, { minLength: length });
     }
-    parse(obj) {
-        if (typeof obj !== 'string') {
-            throw new ValidationError([
-                new Issue([], `Expected string but got ${typeof obj}`),
-            ]);
-        }
-        return obj;
+    /**
+     * Set the maximum length the string is allowed to be.
+     * @param length - The maximum length.
+     */
+    max(length) {
+        return this.refine((s) => s.length <= length || `Must be at most ${length} characters`, { maxLength: length });
     }
-    documentation() {
-        return {
-            type: 'string',
-        };
+    /**
+     * Require the string to be a valid email address.
+     */
+    email() {
+        return this.refine((s) => EMAIL_REGEX.test(s) || "Expected email address", {
+            format: "email",
+        });
     }
-}
-class PatternStringSchema extends ModifiableSchema {
-    constructor(pattern) {
-        super();
-        this.pattern = pattern;
+    /**
+     * Require the string to match the specified pattern.
+     * @param pattern - A regular expression.
+     */
+    pattern(pattern) {
+        return this.refine((s) => pattern.test(s) || `Does not match pattern /${pattern.source}/`, { pattern: pattern.source });
     }
     parse(obj) {
-        if (typeof obj !== 'string') {
+        if (typeof obj !== "string") {
             throw new ValidationError([
                 new Issue([], `Expected string but got ${typeof obj}`),
             ]);
         }
-        if (!obj.match(this.pattern)) {
-            throw new ValidationError([
-                new Issue([], `\`${obj}\` does not match pattern /${this.pattern.source}/`),
-            ]);
-        }
         return obj;
     }
     documentation() {
         return {
-            type: 'string',
-            pattern: this.pattern.source,
+            type: "string",
         };
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yedra",
-  "version": "0.20.2",
+  "version": "0.20.4",
   "repository": "github:0codekit/yedra",
   "main": "dist/index.js",
   "exports": {
@@ -14,9 +14,9 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.14",
-    "@types/bun": "^1.3.9",
-    "@types/node": "^25.2.3",
+    "@biomejs/biome": "^2.3.12",
+    "@types/bun": "^1.3.6",
+    "@types/node": "^25.0.10",
     "@types/uuid": "^11.0.0",
     "@types/ws": "^8.18.1",
     "typescript": "^5.9.3"