yedra 0.20.6 → 0.20.7

package/dist/routing/app.js

@@ -8,6 +8,7 @@ import { context, propagation, SpanKind, trace } from '@opentelemetry/api';
 import mime from 'mime';
 import { WebSocketServer } from 'ws';
 import { Counter } from '../util/counter.js';
+import { collectLazySchemas } from '../validation/lazy.js';
 import { HttpError } from './errors.js';
 import { Path } from './path.js';
 import { RestEndpoint } from './rest.js';
@@ -380,18 +381,23 @@ export class Yedra {
     generateDocs(options) {
         // this set will be filled with the security schemes from all endpoints
         const securitySchemes = new Set();
-        const paths = {};
-        for (const route of this.restRoutes) {
-            if (route.endpoint.isHidden()) {
-                // do not include hidden endpoints in the documentation
-                continue;
+        // Wrap path generation in collectLazySchemas so that any LazySchema
+        // whose documentation() is called will register its full definition.
+        const { result: paths, schemas } = collectLazySchemas(() => {
+            const paths = {};
+            for (const route of this.restRoutes) {
+                if (route.endpoint.isHidden()) {
+                    // do not include hidden endpoints in the documentation
+                    continue;
+                }
+                const path = route.path.toString();
+                const methods = paths[path] ?? {};
+                methods[route.endpoint.method.toLowerCase()] =
+                    route.endpoint.documentation(path, securitySchemes);
+                paths[path] = methods;
             }
-            const path = route.path.toString();
-            const methods = paths[path] ?? {};
-            methods[route.endpoint.method.toLowerCase()] =
-                route.endpoint.documentation(path, securitySchemes);
-            paths[path] = methods;
-        }
+            return paths;
+        });
         return {
             openapi: '3.0.2',
             info: {
@@ -404,6 +410,7 @@ export class Yedra {
                 securitySchemes: Object.fromEntries(securitySchemes
                     .values()
                     .map((scheme) => [scheme.name, scheme.scheme])),
+                schemas: Object.fromEntries(schemas),
             },
             servers: options?.servers ?? [],
             paths,

package/dist/schema-lib.d.ts

@@ -4,6 +4,7 @@ export { date } from './validation/date.js';
 export { _enum as enum } from './validation/enum.js';
 export { ValidationError } from './validation/error.js';
 export { integer } from './validation/integer.js';
+export { lazy } from './validation/lazy.js';
 export { array } from './validation/modifiable.js';
 export { _null as null } from './validation/null.js';
 export { number } from './validation/number.js';

package/dist/schema-lib.js

@@ -7,6 +7,7 @@ export { date } from './validation/date.js';
 export { _enum as enum } from './validation/enum.js';
 export { ValidationError } from './validation/error.js';
 export { integer } from './validation/integer.js';
+export { lazy } from './validation/lazy.js';
 export { array } from './validation/modifiable.js';
 export { _null as null } from './validation/null.js';
 export { number } from './validation/number.js';

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();

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,7 +52,7 @@ class IntegerSchema extends ModifiableSchema {
     }
     documentation() {
         return {
-            type: "integer",
+            type: 'integer',
             ...(this.minValue !== undefined && { minimum: this.minValue }),
             ...(this.maxValue !== undefined && { maximum: this.maxValue }),
         };

package/dist/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: 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/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: 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/validation/modifiable.d.ts

@@ -1,6 +1,6 @@
-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.

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.
@@ -105,7 +105,7 @@ export class RefinedSchema extends ModifiableSchema {
      */
     min(value) {
         const docs = this.documentation();
-        const isArray = docs.type === "array";
+        const isArray = docs.type === 'array';
         return this.refine(((v) => {
             const len = v.length;
             return (len >= value ||
@@ -120,7 +120,7 @@ export class RefinedSchema extends ModifiableSchema {
      */
     max(value) {
         const docs = this.documentation();
-        const isArray = docs.type === "array";
+        const isArray = docs.type === 'array';
         return this.refine(((v) => {
             const len = v.length;
             return (len <= value ||
@@ -142,7 +142,7 @@ export class RefinedSchema extends ModifiableSchema {
         if (result === true) {
             return parsed;
         }
-        const message = typeof result === "string" ? result : "Validation failed";
+        const message = typeof result === 'string' ? result : 'Validation failed';
         throw new ValidationError([new Issue([], message)]);
     }
     documentation() {
@@ -210,7 +210,7 @@ export class ArraySchema extends ModifiableSchema {
     }
     documentation() {
         return {
-            type: "array",
+            type: 'array',
             items: this.itemSchema.documentation(),
         };
     }

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,7 +46,7 @@ class NumberSchema extends ModifiableSchema {
     }
     documentation() {
         return {
-            type: "number",
+            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.

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,7 +66,7 @@ export class ObjectSchema extends ModifiableSchema {
             }
         }
         return {
-            type: "object",
+            type: 'object',
             properties,
             additionalProperties: this.lax,
             ...(required.length > 0 && { required }),

package/dist/validation/schema.d.ts

@@ -1,6 +1,6 @@
-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.
  */
@@ -31,5 +31,5 @@ export declare abstract class Schema<T> extends BodyType<T, T> implements Standa
      *
      * @see https://standardschema.dev/
      */
-    get "~standard"(): StandardSchemaV1.Props<T, 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,10 @@ 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.

package/dist/validation/string.d.ts

@@ -1,4 +1,4 @@
-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.

package/dist/validation/string.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';
 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 class StringSchema extends ModifiableSchema {
     /**
@@ -20,8 +20,8 @@ class StringSchema extends ModifiableSchema {
      * Require the string to be a valid email address.
      */
     email() {
-        return this.refine((s) => EMAIL_REGEX.test(s) || "Expected email address", {
-            format: "email",
+        return this.refine((s) => EMAIL_REGEX.test(s) || 'Expected email address', {
+            format: 'email',
         });
     }
     /**
@@ -32,7 +32,7 @@ class StringSchema extends ModifiableSchema {
         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}`),
             ]);
@@ -41,7 +41,7 @@ class StringSchema extends ModifiableSchema {
     }
     documentation() {
         return {
-            type: "string",
+            type: 'string',
         };
     }
 }

package/package.json

@@ -1,53 +1,53 @@
 {
-  "name": "yedra",
-  "version": "0.20.6",
-  "repository": "github:0codekit/yedra",
-  "main": "dist/index.js",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./schema": {
-      "types": "./dist/schema.d.ts",
-      "default": "./dist/schema.js"
-    }
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.4.4",
-    "@types/bun": "^1.3.9",
-    "@types/node": "^25.3.0",
-    "@types/uuid": "^11.0.0",
-    "@types/ws": "^8.18.1",
-    "typescript": "^5.9.3"
-  },
-  "bugs": "https://github.com/0codekit/yedra/issues",
-  "contributors": [
-    "Justus Zorn <jzorn@wemakefuture.com>"
-  ],
-  "description": "A TypeScript web framework with OpenAPI generation.",
-  "keywords": [
-    "typescript",
-    "web",
-    "http",
-    "schema",
-    "validation",
-    "openapi"
-  ],
-  "license": "MIT",
-  "files": [
-    "./dist/**"
-  ],
-  "scripts": {
-    "check": "biome check src/*"
-  },
-  "types": "dist/index.d.ts",
-  "type": "module",
-  "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "@standard-schema/spec": "^1.1.0",
-    "mime": "^4.1.0",
-    "uuid": "^13.0.0",
-    "ws": "^8.19.0"
-  }
+	"name": "yedra",
+	"version": "0.20.7",
+	"repository": "github:0codekit/yedra",
+	"main": "dist/index.js",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./schema": {
+			"types": "./dist/schema.d.ts",
+			"default": "./dist/schema.js"
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.5",
+		"@types/bun": "^1.3.10",
+		"@types/node": "^25.3.3",
+		"@types/uuid": "^11.0.0",
+		"@types/ws": "^8.18.1",
+		"typescript": "^5.9.3"
+	},
+	"bugs": "https://github.com/0codekit/yedra/issues",
+	"contributors": [
+		"Justus Zorn <jzorn@wemakefuture.com>"
+	],
+	"description": "A TypeScript web framework with OpenAPI generation.",
+	"keywords": [
+		"typescript",
+		"web",
+		"http",
+		"schema",
+		"validation",
+		"openapi"
+	],
+	"license": "MIT",
+	"files": [
+		"./dist/**"
+	],
+	"scripts": {
+		"check": "biome check src/*"
+	},
+	"types": "dist/index.d.ts",
+	"type": "module",
+	"dependencies": {
+		"@opentelemetry/api": "^1.9.0",
+		"@standard-schema/spec": "^1.1.0",
+		"mime": "^4.1.0",
+		"uuid": "^13.0.0",
+		"ws": "^8.19.0"
+	}
 }