@derivesome/server 1.0.1

package/src/app.test.ts

@@ -0,0 +1,245 @@
+import { describe, it, beforeAll, afterAll, assert } from "vitest";
+import { shapes } from "shapedef";
+import http from "node:http";
+import { createApp } from "./app";
+
+function getPort(server: http.Server): number {
+  const addr = server.address();
+  if (!addr || typeof addr === "string") throw new Error("No port");
+  return addr.port;
+}
+
+function closeServer(server: http.Server): Promise<void> {
+  return new Promise((resolve, reject) =>
+    server.close((err) => (err ? reject(err) : resolve())),
+  );
+}
+
+async function request(
+  port: number,
+  path: string,
+  options: RequestInit = {},
+): Promise<{ status: number; body: unknown; text: string }> {
+  const res = await fetch(`http://localhost:${port}${path}`, options);
+  const text = await res.text();
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+  return { status: res.status, body, text };
+}
+
+// ---------------------------------------------------------------------------
+// Basic routes
+// ---------------------------------------------------------------------------
+describe("GET routes", () => {
+  let server: http.Server;
+  let port: number;
+
+  beforeAll(
+    () =>
+      new Promise<void>((resolve) => {
+        const app = createApp();
+        app.route({
+          method: "GET",
+          path: "/ping",
+          args: null,
+          handler: () => ({ pong: true }),
+        });
+        app.route({
+          method: "GET",
+          path: "/users/:id",
+          args: null,
+          handler: (ctx) => ({ id: ctx.params.id }),
+        });
+        server = app.listen(0, resolve);
+        port = getPort(server);
+      }),
+  );
+
+  afterAll(() => closeServer(server));
+
+  it("returns JSON for a plain-object handler return", async () => {
+    const { status, body } = await request(port, "/ping");
+    assert.equal(status, 200);
+    assert.deepEqual(body, { pong: true });
+  });
+
+  it("extracts URL params", async () => {
+    const { status, body } = await request(port, "/users/42");
+    assert.equal(status, 200);
+    assert.deepEqual(body, { id: "42" });
+  });
+
+  it("returns 404 for unknown routes", async () => {
+    const { status, body } = await request(port, "/does-not-exist");
+    assert.equal(status, 404);
+    assert.deepEqual(body, { error: "Not Found" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// POST routes with shapedef validation
+// ---------------------------------------------------------------------------
+describe("POST routes", () => {
+  let server: http.Server;
+  let port: number;
+
+  beforeAll(
+    () =>
+      new Promise<void>((resolve) => {
+        const app = createApp();
+        app.route({
+          method: "POST",
+          path: "/items",
+          args: shapes.mapping({ name: shapes.str(), qty: shapes.int() }),
+          handler: (ctx) => ({ received: ctx.args }),
+        });
+        server = app.listen(0, resolve);
+        port = getPort(server);
+      }),
+  );
+
+  afterAll(() => closeServer(server));
+
+  it("accepts a valid body and passes args to handler", async () => {
+    const { status, body } = await request(port, "/items", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "widget", qty: 5 }),
+    });
+    assert.equal(status, 200);
+    assert.deepEqual(body, { received: { name: "widget", qty: 5 } });
+  });
+
+  it("rejects an invalid body with 400", async () => {
+    const { status } = await request(port, "/items", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "widget", qty: "not-a-number" }),
+    });
+    assert.equal(status, 400);
+  });
+
+  it("rejects a missing required field with 400", async () => {
+    const { status } = await request(port, "/items", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: "widget" }),
+    });
+    assert.equal(status, 400);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ResponseBuilder — custom status codes and text responses
+// ---------------------------------------------------------------------------
+describe("ResponseBuilder", () => {
+  let server: http.Server;
+  let port: number;
+
+  beforeAll(
+    () =>
+      new Promise<void>((resolve) => {
+        const app = createApp();
+        app.route({
+          method: "GET",
+          path: "/not-found-custom",
+          args: null,
+          handler: (ctx) => ctx.R.json({ error: "custom" }).status(404),
+        });
+        app.route({
+          method: "GET",
+          path: "/html",
+          args: null,
+          handler: (ctx) => ctx.R.text("<p>hello</p>"),
+        });
+        server = app.listen(0, resolve);
+        port = getPort(server);
+      }),
+  );
+
+  afterAll(() => closeServer(server));
+
+  it("respects a custom 404 status from ResponseBuilder", async () => {
+    const { status, body } = await request(port, "/not-found-custom");
+    assert.equal(status, 404);
+    assert.deepEqual(body, { error: "custom" });
+  });
+
+  it("returns text/html content", async () => {
+    const { status, text } = await request(port, "/html");
+    assert.equal(status, 200);
+    assert.equal(text, "<p>hello</p>");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// MetaProvider — metadata accumulates across providers
+// ---------------------------------------------------------------------------
+describe("metaProvider", () => {
+  let server: http.Server;
+  let port: number;
+
+  beforeAll(
+    () =>
+      new Promise<void>((resolve) => {
+        const app = createApp()
+          .metaProvider(() => ({ userId: 99 }))
+          .metaProvider((ctx) => ({
+            role: ctx.meta.userId === 99 ? "admin" : "user",
+          }));
+
+        app.route({
+          method: "GET",
+          path: "/me",
+          args: null,
+          handler: (ctx) => ({ userId: ctx.meta.userId, role: ctx.meta.role }),
+        });
+
+        server = app.listen(0, resolve);
+        port = getPort(server);
+      }),
+  );
+
+  afterAll(() => closeServer(server));
+
+  it("accumulates metadata from all providers", async () => {
+    const { status, body } = await request(port, "/me");
+    assert.equal(status, 200);
+    assert.deepEqual(body, { userId: 99, role: "admin" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Array return value
+// ---------------------------------------------------------------------------
+describe("array return", () => {
+  let server: http.Server;
+  let port: number;
+
+  beforeAll(
+    () =>
+      new Promise<void>((resolve) => {
+        const app = createApp();
+        app.route({
+          method: "GET",
+          path: "/list",
+          args: null,
+          handler: () => [1, 2, 3],
+        });
+        server = app.listen(0, resolve);
+        port = getPort(server);
+      }),
+  );
+
+  afterAll(() => closeServer(server));
+
+  it("serialises an array return as JSON", async () => {
+    const { status, body } = await request(port, "/list");
+    assert.equal(status, 200);
+    assert.deepEqual(body, [1, 2, 3]);
+  });
+});

package/src/app.ts

@@ -0,0 +1,272 @@
+import { ShapeMapping, shapes, validate } from "shapedef";
+import { isPlainObject, LooseRecord, UnknownRecord } from "./common";
+import { MetaProvider } from "./meta-provider";
+import { RequestMethod } from "./request-method";
+import { Request, Response } from "./request-response";
+import { Route, RouteWithoutArgs } from "./route";
+import {
+  RouteHandler,
+  RouteHandlerContext,
+  RouteHandlerReturn,
+} from "./route-handler";
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { ResponseBuilder, ResponseMaker, ResponseFile } from "./response";
+
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".json": "application/json",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".txt": "text/plain",
+  ".pdf": "application/pdf",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+function mimeForFile(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] ?? "application/octet-stream";
+}
+
+function sendFile(res: Response, resp: ResponseFile): Promise<void> {
+  return new Promise((resolve, reject) => {
+    fs.stat(resp.filePath, (err, stat) => {
+      if (err) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not Found" }));
+        return resolve();
+      }
+      const contentType = resp.contentType ?? mimeForFile(resp.filePath);
+      res.writeHead(resp.statusCode, {
+        "Content-Type": contentType,
+        "Content-Length": stat.size,
+      });
+      const stream = fs.createReadStream(resp.filePath);
+      stream.on("error", reject);
+      stream.on("end", resolve);
+      stream.pipe(res);
+    });
+  });
+}
+
+type CompiledRoute = {
+  pattern: RegExp;
+  paramNames: string[];
+  route: Route<any, any, any, any, any>;
+};
+
+function compilePath(path: string): { pattern: RegExp; paramNames: string[] } {
+  const paramNames: string[] = [];
+  const regexStr = path.replace(/:([^/]+)/g, (_, name: string) => {
+    paramNames.push(name);
+    return "([^/]+)";
+  });
+  return { pattern: new RegExp(`^${regexStr}$`), paramNames };
+}
+
+export class App<Meta extends UnknownRecord = UnknownRecord> {
+  private _meta: Meta;
+  private _metaProviders: Array<MetaProvider<LooseRecord, LooseRecord>> = [];
+  private _routes: Map<RequestMethod, CompiledRoute[]> = new Map();
+  private _responseMaker: ResponseMaker = new ResponseMaker();
+
+  constructor(meta: Meta) {
+    this._meta = meta;
+  }
+
+  metaProvider<NextMeta extends UnknownRecord>(
+    provider: MetaProvider<NextMeta, Meta>,
+  ): App<Meta & NextMeta> {
+    const app = new App<Meta & NextMeta>(this._meta as Meta & NextMeta);
+    app._metaProviders.push(...this._metaProviders);
+    app._metaProviders.push(provider as MetaProvider<LooseRecord, LooseRecord>);
+    return app;
+  }
+
+  route<Method extends RequestMethod, Path extends string>(
+    route: RouteWithoutArgs<Meta, Method, Path>,
+  ): this;
+  route<
+    Args extends ShapeMapping<any>,
+    Method extends RequestMethod,
+    Path extends string,
+  >(route: Route<Meta, Args, Method, Path>): this;
+  route(route: Route<any, any, any, any, any>): this {
+    if (!this._routes.has(route.method)) {
+      this._routes.set(route.method, []);
+    }
+    const { pattern, paramNames } = compilePath(route.path);
+    this._routes.get(route.method)!.push({ pattern, paramNames, route });
+    return this;
+  }
+
+  get<
+    Path extends string,
+    Args extends ShapeMapping<any>,
+    Handler extends RouteHandler<Meta, Args>,
+  >(path: Path, args: Args | undefined | null, handler: Handler): this {
+    return this.route({
+      method: "GET",
+      path: path,
+      handler,
+      args: args || null,
+    });
+  }
+
+  private resolve(
+    method: RequestMethod,
+    url: string,
+  ): { route: Route; params: Record<string, string> } | null {
+    const routes = this._routes.get(method);
+    if (!routes) return null;
+    for (const { pattern, paramNames, route } of routes) {
+      const match = pattern.exec(url);
+      if (match) {
+        const params: Record<string, string> = {};
+        for (let i = 0; i < paramNames.length; i++) {
+          params[paramNames[i]!] = match[i + 1]!;
+        }
+        return { route, params };
+      }
+    }
+    return null;
+  }
+
+  private async sendReturn(ctx: RouteHandlerContext, ret: RouteHandlerReturn) {
+    if (ret instanceof ResponseBuilder) {
+      const resp = ret.resp;
+      switch (resp.type) {
+        case "json":
+          {
+            ctx.res.writeHead(resp.statusCode, {
+              "Content-Type": resp.contentType,
+            });
+            ctx.res.end(JSON.stringify(resp.payload));
+          }
+          break;
+        case "text":
+          {
+            ctx.res.writeHead(resp.statusCode, {
+              "Content-Type": resp.contentType,
+            });
+            ctx.res.end(resp.payload);
+          }
+          break;
+        case "stream":
+          {
+            await new Promise<void>((resolve, reject) => {
+              ctx.res.writeHead(resp.statusCode, {
+                "Content-Type": resp.contentType,
+              });
+              resp.stream.on("error", reject);
+              resp.stream.on("end", resolve);
+              resp.stream.pipe(ctx.res);
+            });
+          }
+          break;
+        case "binary":
+          {
+            ctx.res.writeHead(resp.statusCode, {
+              "Content-Type": resp.contentType,
+              "Content-Length": resp.payload.byteLength,
+            });
+            ctx.res.end(resp.payload);
+          }
+          break;
+        case "file":
+          {
+            await sendFile(ctx.res, resp);
+          }
+          break;
+      }
+    } else if (Array.isArray(ret) || isPlainObject(ret)) {
+      ctx.res.writeHead(200, { "Content-Type": "application/json" });
+      ctx.res.end(JSON.stringify(ret));
+    }
+  }
+
+  private async runRoute(
+    ctx: RouteHandlerContext<Request, Response, any, any, any>,
+    route: Route,
+  ) {
+    if (route.mergeParams !== false && isPlainObject(ctx.req.body)) {
+      ctx.args = {};
+      ctx.args = { ...ctx.args, ...ctx.req.body };
+    }
+    if (["POST", "PUT", "PATCH"].includes(route.method)) {
+      if (route.args) {
+        const validation = validate(ctx.req.body, route.args);
+        if (!validation.ok) {
+          return await this.sendReturn(ctx, ctx.R.json(validation).status(400));
+        }
+        ctx.args = ctx.req.body;
+      }
+    }
+
+    await this.sendReturn(ctx, await route.handler(ctx));
+  }
+
+  private async runPipeline(
+    req: Request,
+    res: Response,
+    method: RequestMethod,
+    path: string,
+  ) {
+    console.log(method, path);
+    const ctx: RouteHandlerContext<Request, Response, any, any, any> = {
+      req,
+      res,
+      meta: {},
+      args: {},
+      params: {},
+      R: this._responseMaker,
+    };
+
+    for (const metaProvider of this._metaProviders) {
+      const output = await metaProvider(ctx);
+      Object.assign(ctx.meta, output);
+    }
+
+    const pathname = path.split("?")[0]!;
+    const resolved = this.resolve(method, pathname);
+
+    if (!resolved) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Not Found" }));
+      return;
+    }
+
+    ctx.params = resolved.params;
+    await this.runRoute(ctx, resolved.route);
+  }
+
+  listen(port: number, cb?: () => void): http.Server {
+    const server = http.createServer(async (req, res) => {
+      const method = (req.method || "GET").toUpperCase() as RequestMethod;
+      const path = req.url || "/";
+
+      const wrappedRequest = new Request(req);
+      await wrappedRequest.run();
+
+      await this.runPipeline(wrappedRequest, res, method, path);
+    });
+
+    server.listen(port, cb);
+    return server;
+  }
+}
+
+export function createApp(): App<UnknownRecord> {
+  return new App({});
+}