yedra 0.13.15 → 0.14.0

package/README.md

@@ -111,9 +111,7 @@ export const loginEndpoint = new Post({
     password: y.string(),
   }),
   res: y.object({
-    token: y.string().doc({
-      description: "The session token.",
-    }),
+    token: y.string().describe("The session token."),
   }),
   async do(req) {
     if (await isValid(req.body.username, req.body.password)) {

package/dist/lib.d.ts

@@ -7,14 +7,14 @@ export { boolean } from './validation/boolean.js';
 export { date } from './validation/date.js';
 export { _enum as enum } from './validation/enum.js';
 export { ValidationError } from './validation/error.js';
-export { intersection } from './validation/intersection.js';
 export { number } from './validation/number.js';
 export { integer } from './validation/integer.js';
-export { object } from './validation/object.js';
+export { object, laxObject } from './validation/object.js';
 export { record } from './validation/record.js';
 export { Schema } from './validation/schema.js';
 export { BodyType, type Typeof } from './validation/body.js';
 export { raw } from './validation/raw.js';
+export { stream } from './validation/stream.js';
 export { either } from './validation/either.js';
 export { string } from './validation/string.js';
 export { union } from './validation/union.js';

package/dist/lib.js

@@ -12,14 +12,14 @@ export { boolean } from './validation/boolean.js';
 export { date } from './validation/date.js';
 export { _enum as enum } from './validation/enum.js';
 export { ValidationError } from './validation/error.js';
-export { intersection } from './validation/intersection.js';
 export { number } from './validation/number.js';
 export { integer } from './validation/integer.js';
-export { object } from './validation/object.js';
+export { object, laxObject } from './validation/object.js';
 export { record } from './validation/record.js';
 export { Schema } from './validation/schema.js';
 export { BodyType } from './validation/body.js';
 export { raw } from './validation/raw.js';
+export { stream } from './validation/stream.js';
 export { either } from './validation/either.js';
 export { string } from './validation/string.js';
 export { union } from './validation/union.js';

package/dist/routing/app.d.ts

@@ -1,39 +1,21 @@
-import { type Server } from 'node:http';
-import { URL } from 'node:url';
+import type { Server } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { Counter } from '../util/counter.js';
 import type { SecurityScheme } from '../util/security.js';
 import { RestEndpoint } from './rest.js';
 import { WsEndpoint } from './websocket.js';
 declare class Context {
-    private server;
-    constructor(server: Server);
+    private readonly server;
+    private readonly wss;
+    private readonly counter;
+    constructor(server: Server, wss: WebSocketServer, counter: Counter);
     stop(): Promise<void>;
 }
-type MetricsConfig = {
-    port: number;
-    path: string;
-    get?: () => Promise<string>;
-};
 export declare class Yedra {
     private restRoutes;
     private wsRoutes;
-    private staticFiles;
     private requestData;
-    private readonly metricsEndpoint;
-    constructor(options?: {
-        metrics: MetricsConfig;
-    });
     use(path: string, endpoint: RestEndpoint | WsEndpoint | Yedra): Yedra;
-    static(dir: string, fallback?: string): Promise<void>;
-    /**
-     * Handle an HTTP request.
-     * @param req - The HTTP request.
-     * @returns The HTTP response.
-     */
-    fetch(url: URL | string, options?: {
-        method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
-        body?: string | Buffer;
-        headers?: Record<string, string>;
-    }): Promise<Response>;
     /**
      * Generate OpenAPI documentation for the app.
      */
@@ -49,12 +31,27 @@ export declare class Yedra {
             url: string;
         }[];
     }): object;
+    private static loadStatic;
+    private performRequest;
     listen(port: number, options?: {
         tls?: {
             key: string;
             cert: string;
         };
-    }): Context;
+        metrics?: {
+            port: number;
+            path: string;
+            get?: () => Promise<string> | string;
+        };
+        static?: {
+            dir: string;
+            fallback?: string;
+        };
+        /**
+         * Prevents all normal output from Yedra. Mostly useful for tests.
+         */
+        quiet?: boolean;
+    }): Promise<Context>;
     private static errorResponse;
     private matchRestRoute;
     private matchWsRoute;

package/dist/routing/app.js

@@ -5,27 +5,38 @@ import { extname, join } from 'node:path';
 import { URL } from 'node:url';
 import mime from 'mime';
 import { WebSocketServer } from 'ws';
+import { Counter } from '../util/counter.js';
 import { HttpError } from './errors.js';
 import { Path } from './path.js';
 import { RestEndpoint } from './rest.js';
 import { WsEndpoint } from './websocket.js';
 class Context {
-    constructor(server) {
+    constructor(server, wss, counter) {
         this.server = server;
+        this.wss = wss;
+        this.counter = counter;
     }
     stop() {
         return new Promise((resolve) => {
-            this.server.close(() => resolve());
+            // don't accept any new connections
+            this.wss.close();
+            this.server.close();
+            for (const client of this.wss.clients) {
+                // send shutdown message to all WebSocket clients
+                client.close(1000, 'Server Shutdown');
+            }
+            // wait until all connections are done
+            this.counter.wait().then(() => {
+                resolve();
+            });
         });
     }
 }
 export class Yedra {
-    constructor(options) {
+    constructor() {
         this.restRoutes = [];
         this.wsRoutes = [];
-        this.staticFiles = new Map();
         this.requestData = {};
-        this.metricsEndpoint = options?.metrics;
     }
     use(path, endpoint) {
         if (endpoint instanceof Yedra) {
@@ -49,62 +60,94 @@ export class Yedra {
         }
         return this;
     }
-    async static(dir, fallback) {
-        const files = await readdir(dir, { recursive: true });
+    /**
+     * Generate OpenAPI documentation for the app.
+     */
+    docs(options) {
+        const paths = {};
+        for (const route of this.restRoutes) {
+            const path = route.path.toString();
+            const methods = paths[path] ?? {};
+            methods[route.endpoint.method.toLowerCase()] =
+                route.endpoint.documentation(options.security ?? {});
+            paths[path] = methods;
+        }
+        return {
+            openapi: '3.0.2',
+            info: options.info,
+            components: {
+                securitySchemes: options.security,
+            },
+            servers: options.servers,
+            paths,
+        };
+    }
+    static async loadStatic(options) {
+        if (options === undefined) {
+            return new Map();
+        }
+        const staticFiles = new Map();
+        const files = await readdir(options.dir, { recursive: true });
         await Promise.all(files.map(async (file) => {
-            const absolute = join(dir, file);
+            const absolute = join(options.dir, file);
             if (!(await stat(absolute)).isFile()) {
                 return;
             }
             const data = await readFile(absolute);
-            this.staticFiles.set(`/${file}`, {
+            staticFiles.set(`/${file}`, {
                 data,
                 mime: mime.getType(extname(file)) ?? 'application/octet-stream',
             });
         }));
-        if (fallback) {
-            const data = await readFile(fallback);
-            this.staticFiles.set('__fallback', {
+        if (options.fallback) {
+            const data = await readFile(options.fallback);
+            staticFiles.set('__fallback', {
                 data,
-                mime: mime.getType(extname(fallback)) ?? 'application/octet-stream',
+                mime: mime.getType(extname(options.fallback)) ?? 'application/octet-stream',
             });
         }
+        return staticFiles;
     }
-    /**
-     * Handle an HTTP request.
-     * @param req - The HTTP request.
-     * @returns The HTTP response.
-     */
-    async fetch(url, options) {
-        const parsedUrl = typeof url === 'string' ? new URL(url, 'http://localhost') : url;
-        const method = options?.method ?? 'GET';
-        if (method !== 'GET' &&
-            method !== 'POST' &&
-            method !== 'PUT' &&
-            method !== 'DELETE') {
-            return Yedra.errorResponse(405, `Method '${method}' not allowed.`);
+    async performRequest(staticFiles, req) {
+        if (req.method !== 'GET' &&
+            req.method !== 'POST' &&
+            req.method !== 'PUT' &&
+            req.method !== 'DELETE') {
+            return Yedra.errorResponse(405, `Method \`${req.method}\` not allowed.`);
         }
-        const match = this.matchRestRoute(parsedUrl.pathname, method);
+        const match = this.matchRestRoute(req.url.pathname, req.method);
         if (!match.result) {
-            if (method === 'GET') {
-                // try returning a static file
-                const staticFile = this.staticFiles.get(parsedUrl.pathname) ??
-                    this.staticFiles.get('__fallback');
+            // no matching route found
+            if (req.method === 'GET') {
+                // look for a static file
+                const staticFile = staticFiles.get(req.url.pathname) ?? staticFiles.get('__fallback');
                 if (staticFile !== undefined) {
-                    return new Response(staticFile.data, {
+                    return {
+                        status: 200,
+                        body: staticFile.data,
                         headers: {
                             'content-type': staticFile.mime,
                         },
-                    });
+                    };
                 }
             }
             if (match.invalidMethod) {
-                return Yedra.errorResponse(405, `Method '${method}' not allowed for path '${parsedUrl.pathname}'.`);
+                // we found a route, but it did not match the request method
+                return Yedra.errorResponse(405, `Method ${req.method} not allowed for path \`${req.url.pathname}\`.`);
             }
-            return Yedra.errorResponse(404, `Path '${parsedUrl.pathname}' not found.`);
+            return Yedra.errorResponse(404, `Path \`${req.url.pathname}\` not found.`);
         }
         try {
-            return await match.result.endpoint.handle(parsedUrl.pathname, options?.body ?? '', match.result.params, Object.fromEntries(parsedUrl.searchParams), options?.headers ?? {});
+            return await match.result.endpoint.handle({
+                url: req.url.pathname,
+                body: req.body,
+                params: match.result.params,
+                query: Object.fromEntries(req.url.searchParams),
+                headers: Object.fromEntries(Object.entries(req.headers).map(([key, value]) => [
+                    key,
+                    Array.isArray(value) ? value.join(',') : (value ?? ''),
+                ])),
+            });
         }
         catch (error) {
             if (error instanceof HttpError) {
@@ -114,58 +157,45 @@ export class Yedra {
             return Yedra.errorResponse(500, 'Internal Server Error.');
         }
     }
-    /**
-     * Generate OpenAPI documentation for the app.
-     */
-    docs(options) {
-        const paths = {};
-        for (const route of this.restRoutes) {
-            const path = route.path.toString();
-            const methods = paths[path] ?? {};
-            methods[route.endpoint.method.toLowerCase()] =
-                route.endpoint.documentation(options.security ?? {});
-            paths[path] = methods;
-        }
-        return {
-            openapi: '3.0.2',
-            info: options.info,
-            components: {
-                securitySchemes: options.security,
-            },
-            servers: options.servers,
-            paths,
-        };
-    }
-    listen(port, options) {
+    async listen(port, options) {
+        const staticFiles = await Yedra.loadStatic(options?.static);
         const server = options?.tls === undefined
             ? createHttpServer()
             : createHttpsServer({
                 key: options.tls.key,
                 cert: options.tls.cert,
             });
-        server.on('request', (req, res) => {
+        const counter = new Counter();
+        server.on('request', async (req, res) => {
+            counter.increment();
             const url = new URL(req.url, 'http://localhost');
             const begin = Date.now();
-            const chunks = [];
-            req.on('data', (chunk) => {
-                chunks.push(chunk);
-            });
-            req.on('end', async () => {
-                const body = chunks.length > 0 ? Buffer.concat(chunks) : undefined;
-                const response = await this.fetch(url, {
-                    method: req.method,
-                    body: req.method === 'POST' || req.method === 'PUT' ? body : undefined,
-                    headers: Object.fromEntries(Object.entries(req.headers).map(([key, value]) => [
-                        key,
-                        Array.isArray(value) ? value.join(',') : (value ?? ''),
-                    ])),
-                });
-                res.writeHead(response.status, Object.fromEntries(response.headers));
-                res.end(Buffer.from(await response.arrayBuffer()));
-                const duration = Date.now() - begin;
-                console.log(`${req.method} ${url.pathname} -> ${response.status} (${duration}ms)`);
-                this.track(req.method, response.status, duration / 1000);
+            const response = await this.performRequest(staticFiles, {
+                method: req.method ?? 'GET',
+                url,
+                body: req,
+                headers: req.headers,
             });
+            const status = response.status ?? 200;
+            res.writeHead(status, response.headers);
+            if (response.body instanceof ReadableStream) {
+                for await (const chunk of response.body) {
+                    res.write(chunk);
+                }
+            }
+            else {
+                const buffer = response.body instanceof Uint8Array
+                    ? response.body
+                    : JSON.stringify(response.body);
+                res.write(buffer);
+            }
+            res.end();
+            const duration = Date.now() - begin;
+            if (options?.quiet !== true) {
+                console.log(`${req.method} ${url.pathname} -> ${status} (${duration}ms)`);
+            }
+            this.track(req.method, status, duration / 1000);
+            counter.decrement();
         });
         const wss = new WebSocketServer({ server });
         wss.on('connection', async (ws, req) => {
@@ -183,15 +213,18 @@ export class Yedra {
                     ws.close(4000 + error.status, error.message);
                 }
                 else {
-                    ws.close(1011, 'Internal Server Error');
+                    console.error(error);
+                    ws.close(1011, 'Internal Error');
                 }
             }
         });
         server.listen(port, () => {
-            console.log(`yedra listening on http://localhost:${port}`);
+            if (options?.quiet !== true) {
+                console.log(`yedra listening on http://localhost:${port}`);
+            }
         });
-        const metricsEndpoint = this.metricsEndpoint;
-        if (metricsEndpoint !== undefined) {
+        if (options?.metrics !== undefined) {
+            const metricsEndpoint = options.metrics;
             const metricsServer = createHttpServer();
             metricsServer.on('request', async (req, res) => {
                 if (req.method === 'GET' && req.url === metricsEndpoint.path) {
@@ -208,18 +241,21 @@ export class Yedra {
                 }
             });
             metricsServer.listen(metricsEndpoint.port, () => {
-                console.log(`yedra metrics on http://localhost:${metricsEndpoint.port}${metricsEndpoint.path}`);
+                if (options.quiet !== true) {
+                    console.log(`yedra metrics on http://localhost:${metricsEndpoint.port}${metricsEndpoint.path}`);
+                }
             });
         }
-        return new Context(server);
+        return new Context(server, wss, counter);
     }
     static errorResponse(status, errorMessage) {
-        return Response.json({
-            status,
-            errorMessage,
-        }, {
+        return {
             status,
-        });
+            body: {
+                status,
+                errorMessage,
+            },
+        };
     }
     matchRestRoute(url, method) {
         let invalidMethod = false;

package/dist/routing/path.js

@@ -58,7 +58,10 @@ export class Path {
      */
     match(path) {
         const params = {};
-        const actual = path.substring(1).split('/');
+        const actual = path
+            .substring(1)
+            .split('/')
+            .filter((segment) => segment !== '');
         if (this.expected.length < actual.length && !this.expected.includes('*')) {
             // path cannot be longer than expected, unless it contains a wildcard
             return undefined;

package/dist/routing/rest.d.ts

@@ -1,3 +1,4 @@
+import type { Readable } from 'node:stream';
 import type { SecurityScheme } from '../util/security.js';
 import type { BodyType, Typeof } from '../validation/body.js';
 import { NoneBody } from '../validation/none.js';
@@ -33,7 +34,17 @@ type EndpointOptions<Params extends Record<string, Schema<unknown>>, Query exten
 };
 export declare abstract class RestEndpoint {
     abstract get method(): 'GET' | 'POST' | 'PUT' | 'DELETE';
-    abstract handle(pathname: string, body: string | Buffer, params: Record<string, string>, query: Record<string, string>, headers: Record<string, string>): Promise<Response>;
+    abstract handle(req: {
+        url: string;
+        body: Readable;
+        params: Record<string, string>;
+        query: Record<string, string>;
+        headers: Record<string, string>;
+    }): Promise<{
+        status?: number;
+        body: unknown;
+        headers?: Record<string, string>;
+    }>;
     abstract documentation(securitySchemes: Record<string, SecurityScheme>): object;
 }
 declare class ConcreteRestEndpoint<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>, Req extends BodyType<unknown>, Res extends BodyType<unknown>> extends RestEndpoint {
@@ -44,7 +55,17 @@ declare class ConcreteRestEndpoint<Params extends Record<string, Schema<unknown>
     private headersSchema;
     constructor(method: 'GET' | 'POST' | 'PUT' | 'DELETE', options: EndpointOptions<Params, Query, Headers, Req, Res>);
     get method(): 'GET' | 'POST' | 'PUT' | 'DELETE';
-    handle(url: string, body: string | Buffer, params: Record<string, string>, query: Record<string, string>, headers: Record<string, string>): Promise<Response>;
+    handle(req: {
+        url: string;
+        body: Readable;
+        params: Record<string, string>;
+        query: Record<string, string>;
+        headers: Record<string, string>;
+    }): Promise<{
+        status?: number;
+        body: unknown;
+        headers?: Record<string, string>;
+    }>;
     documentation(securitySchemes: Record<string, SecurityScheme>): object;
 }
 export declare class Get<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>, Res extends BodyType<unknown>> extends ConcreteRestEndpoint<Params, Query, Headers, NoneBody, Res> {

package/dist/routing/rest.js

@@ -1,7 +1,7 @@
 import { paramDocs } from '../util/docs.js';
 import { Issue, ValidationError } from '../validation/error.js';
 import { NoneBody, none } from '../validation/none.js';
-import { object } from '../validation/object.js';
+import { laxObject, object } from '../validation/object.js';
 import { BadRequestError } from './errors.js';
 export class RestEndpoint {
 }
@@ -12,23 +12,24 @@ class ConcreteRestEndpoint extends RestEndpoint {
         this.options = options;
         this.paramsSchema = object(options.params);
         this.querySchema = object(options.query);
-        this.headersSchema = object(options.headers);
+        // headers need to be lax, since there are lots of them
+        this.headersSchema = laxObject(options.headers);
     }
     get method() {
         return this._method;
     }
-    async handle(url, body, params, query, headers) {
+    async handle(req) {
         let parsedBody;
         let parsedParams;
         let parsedQuery;
         let parsedHeaders;
         const issues = [];
         try {
-            parsedBody = this.options.req.deserialize(typeof body === 'string' ? Buffer.from(body) : body, headers['content-type'] ?? 'application/octet-stream');
+            parsedBody = await this.options.req.deserialize(req.body, req.headers['content-type'] ?? 'application/octet-stream');
         }
         catch (error) {
             if (error instanceof SyntaxError) {
-                issues.push(new Issue('invalidSyntax', ['body'], 'JSON', error.message));
+                issues.push(new Issue(['body'], error.message));
             }
             else if (error instanceof ValidationError) {
                 issues.push(...error.withPrefix('body'));
@@ -38,7 +39,7 @@ class ConcreteRestEndpoint extends RestEndpoint {
             }
         }
         try {
-            parsedParams = this.paramsSchema.parse(params);
+            parsedParams = this.paramsSchema.parse(req.params);
         }
         catch (error) {
             if (error instanceof ValidationError) {
@@ -49,7 +50,7 @@ class ConcreteRestEndpoint extends RestEndpoint {
             }
         }
         try {
-            parsedQuery = this.querySchema.parse(query);
+            parsedQuery = this.querySchema.parse(req.query);
         }
         catch (error) {
             if (error instanceof ValidationError) {
@@ -60,7 +61,7 @@ class ConcreteRestEndpoint extends RestEndpoint {
             }
         }
         try {
-            parsedHeaders = this.headersSchema.parse(headers);
+            parsedHeaders = this.headersSchema.parse(req.headers);
         }
         catch (error) {
             if (error instanceof ValidationError) {
@@ -74,8 +75,8 @@ class ConcreteRestEndpoint extends RestEndpoint {
             const error = new ValidationError(issues);
             throw new BadRequestError(error.format());
         }
-        const response = await this.options.do({
-            url,
+        return await this.options.do({
+            url: req.url,
             // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
             params: parsedParams,
             // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
@@ -85,16 +86,6 @@ class ConcreteRestEndpoint extends RestEndpoint {
             // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
             body: parsedBody,
         });
-        if (response.body instanceof Uint8Array) {
-            return new Response(response.body, {
-                status: response.status,
-                headers: response.headers,
-            });
-        }
-        return Response.json(response.body, {
-            status: response.status,
-            headers: response.headers,
-        });
     }
     documentation(securitySchemes) {
         const parameters = [

package/dist/util/counter.d.ts

@@ -0,0 +1,7 @@
+export declare class Counter {
+    private count;
+    private resolve;
+    wait(): Promise<void>;
+    increment(): void;
+    decrement(): void;
+}

package/dist/util/counter.js

@@ -0,0 +1,24 @@
+export class Counter {
+    constructor() {
+        this.count = 0;
+    }
+    wait() {
+        return new Promise((resolve) => {
+            if (this.count === 0) {
+                resolve();
+            }
+            else {
+                this.resolve = resolve;
+            }
+        });
+    }
+    increment() {
+        this.count += 1;
+    }
+    decrement() {
+        this.count -= 1;
+        if (this.count === 0 && this.resolve !== undefined) {
+            this.resolve();
+        }
+    }
+}

package/dist/util/stream.d.ts

@@ -0,0 +1,2 @@
+import type { Readable } from 'node:stream';
+export declare const readableToBuffer: (stream: Readable) => Promise<Buffer>;

package/dist/util/stream.js

@@ -0,0 +1,7 @@
+export const readableToBuffer = async (stream) => {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+};

package/dist/validation/array.d.ts

@@ -1,7 +1,7 @@
 import type { Typeof } from './body.js';
 import { ModifiableSchema } from './modifiable.js';
 import type { Schema } from './schema.js';
-declare class ArraySchema<ItemSchema extends Schema<unknown>> extends ModifiableSchema<Typeof<ItemSchema>[]> {
+export declare class ArraySchema<ItemSchema extends Schema<unknown>> extends ModifiableSchema<Typeof<ItemSchema>[]> {
     private readonly itemSchema;
     private readonly minItems?;
     private readonly maxItems?;
@@ -28,6 +28,6 @@ declare class ArraySchema<ItemSchema extends Schema<unknown>> extends Modifiable
 /**
  * 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 {};