@server/next 0.23.1 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@server/next",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "A fully-fledged web server with routing, file uploads, sessions, static files, schema validation, websockets, testing, etc.",
   "homepage": "https://server-js.com/",
   "repository": "https://github.com/franciscop/server-next.git",
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "start": "bun test --watch",
-    "lint": "npx @biomejs/biome lint ./src --skip=lint/style/noParameterAssign",
+    "lint": "npx @biomejs/biome lint ./src --skip=lint/style/noParameterAssign --skip=lint/suspicious/noExplicitAny --skip=lint/suspicious/noConfusingVoidType",
     "test": "bun test && check-dts ./src/**",
     "test:jest": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
   },

package/src/auth/index.js

@@ -15,17 +15,41 @@ const middle = async (ctx) => {
     if (ctx.options.auth.provider.includes("github")) {
       if (!env.GITHUB_ID) throw new Error("GITHUB_ID not defined");
       if (!env.GITHUB_SECRET) throw new Error("GITHUB_SECRET not defined");
-      ctx.app.get("/auth/logout", logout);
-      ctx.app.get("/auth/login/github", providers.github.login);
-      ctx.app.get("/auth/callback/github", providers.github.callback);
+      ctx.app.get(
+        "/auth/logout",
+        { tags: "Auth", title: "Github logout" },
+        logout,
+      );
+      ctx.app.get(
+        "/auth/login/github",
+        { tags: "Auth" },
+        providers.github.login,
+      );
+      ctx.app.get(
+        "/auth/callback/github",
+        { tags: "Auth", title: "Github callback" },
+        providers.github.callback,
+      );
     }
 
     if (ctx.options.auth.provider.includes("email")) {
-      ctx.app.post("/auth/logout", logout);
-      ctx.app.post("/auth/register/email", providers.email.register);
-      ctx.app.post("/auth/login/email", providers.email.login);
-      ctx.app.put("/auth/password/email", providers.email.password);
-      ctx.app.put("/auth/reset/email", providers.email.password);
+      ctx.app.post("/auth/logout", { tags: "Auth" }, logout);
+      ctx.app.post(
+        "/auth/register/email",
+        { tags: "Auth" },
+        providers.email.register,
+      );
+      ctx.app.post(
+        "/auth/login/email",
+        { tags: "Auth" },
+        providers.email.login,
+      );
+      ctx.app.put(
+        "/auth/password/email",
+        { tags: "Auth" },
+        providers.email.password,
+      );
+      ctx.app.put("/auth/reset/email", { tags: "Auth" }, providers.email.reset);
     }
   }
 };

package/src/auth/providers/email.js

@@ -61,7 +61,7 @@ const createSession = async (user, ctx) => {
   throw new Error("Unknown auth type");
 };
 
-async function login(ctx) {
+async function emailLogin(ctx) {
   const { email, password } = ctx.body;
   if (!email) throw ServerError.LOGIN_NO_EMAIL();
   if (!/@/.test(email)) throw ServerError.LOGIN_INVALID_EMAIL();
@@ -78,7 +78,7 @@ async function login(ctx) {
   return createSession(user, ctx);
 }
 
-async function register(ctx) {
+async function emailRegister(ctx) {
   const { email, password, ...data } = ctx.body;
   if (!email) throw ServerError.REGISTER_NO_EMAIL();
   if (!/@/.test(email)) throw ServerError.REGISTER_INVALID_EMAIL();
@@ -101,7 +101,7 @@ async function register(ctx) {
   return createSession(user, ctx);
 }
 
-async function reset(ctx) {
+async function emailResetPassword(ctx) {
   // const reset = ctx.options.store.prefix("reset:");
   // // Already resetting
   // if (ctx.body.token) {
@@ -123,7 +123,7 @@ async function reset(ctx) {
   // }
 }
 
-async function password(ctx) {
+async function emailUpdatePassword(ctx) {
   const { previous, updated } = ctx.body;
 
   const fullUser = await ctx.options.auth.store.get(ctx.auth.user);
@@ -137,4 +137,9 @@ async function password(ctx) {
   return 200;
 }
 
-export default { login, register, reset, password };
+export default {
+  login: emailLogin,
+  register: emailRegister,
+  reset: emailResetPassword,
+  password: emailUpdatePassword,
+};

package/src/auth/providers/github.js

@@ -25,7 +25,7 @@ const oauth = async (code) => {
   };
 };
 
-const login = (ctx) => {
+const login = function githubLogin(ctx) {
   return redirect(
     `https://github.com/login/oauth/authorize?client_id=${env.GITHUB_ID}&scope=user:email`,
   );

package/src/helpers/config.js

@@ -82,5 +82,12 @@ export default function config(options = {}) {
     }
   }
 
+  // OpenAPI
+  if (options.openapi) {
+    if (options.openapi === true) {
+      options.openapi = {};
+    }
+  }
+
   return options;
 }

package/src/index.d.ts

@@ -45,16 +45,48 @@ type ServerOptions = {
 };
 
 type ExtractPathParams<Path extends string> =
-  Path extends `${string}:${infer Param}/${infer Rest}`
-    ? Param | ExtractPathParams<`/${Rest}`>
-    : Path extends `${string}:${infer Param}`
-      ? Param
-      : never;
+  Path extends `${string}:${infer Param}(${infer Type})?/${infer Rest}`
+    ? `${Param}:${Type}?` | ExtractPathParams<`/${Rest}`>
+    : Path extends `${string}:${infer Param}(${infer Type})?`
+      ? `${Param}:${Type}?`
+      : Path extends `${string}:${infer Param}(${infer Type})/${infer Rest}`
+        ? `${Param}:${Type}` | ExtractPathParams<`/${Rest}`>
+        : Path extends `${string}:${infer Param}(${infer Type})`
+          ? `${Param}:${Type}`
+          : Path extends `${string}:${infer Param}?/${infer Rest}`
+            ? `${Param}?` | ExtractPathParams<`/${Rest}`>
+            : Path extends `${string}:${infer Param}?`
+              ? `${Param}?`
+              : Path extends `${string}:${infer Param}/${infer Rest}`
+                ? Param | ExtractPathParams<`/${Rest}`>
+                : Path extends `${string}:${infer Param}`
+                  ? Param
+                  : never;
+
+type ParamTypeMap = {
+  string: string;
+  number: number;
+  boolean: boolean;
+};
+
+type InferParamType<T extends string> = T extends keyof ParamTypeMap
+  ? ParamTypeMap[T]
+  : string;
 
 type ParamsToObject<Params extends string> = {
-  [K in Params as K extends `${infer Key}?`
+  [K in Params as K extends `${infer Key}:${infer Type}?`
     ? Key
-    : K]: K extends `${infer Key}?` ? string | undefined : string;
+    : K extends `${infer Key}:${infer Type}`
+      ? Key
+      : K extends `${infer Key}?`
+        ? Key
+        : K]: K extends `${infer Key}:${infer Type}?`
+    ? InferParamType<Type> | undefined
+    : K extends `${infer Key}:${infer Type}`
+      ? InferParamType<Type>
+      : K extends `${infer Key}?`
+        ? string | undefined
+        : string;
 };
 
 type PathToParams<Path extends string> = ParamsToObject<
@@ -96,11 +128,11 @@ type InlineReply =
   | { body: Body; headers?: Headers }
   | string
   | number
-  | void;
+  | undefined;
 
 type Middleware<Path extends string = string> = (
   ctx: Context<Path>,
-) => InlineReply;
+) => InlineReply | void;
 
 declare interface Router {
   get<Path extends string>(path: Path, ...middle: Middleware<Path>[]): this;

package/src/index.js

@@ -11,7 +11,7 @@ import {
   parseHeaders,
 } from "./helpers/index.js";
 
-import { assets, auth, timer } from "./middle/index.js";
+import { assets, auth, timer, openapi } from "./middle/index.js";
 
 // Export the reply helpers
 export * from "./reply.js";
@@ -75,6 +75,10 @@ export default function server(options = {}) {
 
   this.use(timer);
   this.use(assets);
+  if (this.opts.openapi) {
+    const path = this.opts.openapi.path || "/docs";
+    this.get(path, openapi);
+  }
   if (this.opts.auth) {
     this.use(auth({ options: this.opts, app: this }));
   }

package/src/middle/index.js

@@ -1,6 +1,7 @@
 import authMod from "../auth/index.js";
 import assets from "./assets.js";
 import timer from "./timer.js";
+import openapi from "./openapi.js";
 
 const auth = authMod.middle;
-export { assets, auth, timer };
+export { assets, auth, timer, openapi };

package/src/middle/openapi.js

@@ -0,0 +1,146 @@
+import fsp from "node:fs/promises";
+
+const entities = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" };
+const encode = (str = "") => {
+  if (typeof str === "number") str = String(str);
+  if (typeof str !== "string") return ""; // nullify not-strings
+  return str.replace(/[&<>"]/g, (tag) => entities[tag]);
+};
+
+const getConfig = (routes) => {
+  const config = routes.find(
+    (r) =>
+      typeof r !== "string" && typeof r !== "function" && typeof r === "object",
+  );
+  if (!config) return {};
+  if (config.tags) {
+    if (typeof config.tags === "string") {
+      config.tags = config.tags.split(/\s*\,\s*/g);
+    }
+    if (!Array.isArray(config.tags)) {
+      throw new Error("invalid tags", config.tags);
+    }
+    config.tags = config.tags.map((t) => t.trim());
+  }
+  return config;
+};
+
+const pkg = await fsp
+  .readFile("package.json", "utf-8")
+  .then((data) => JSON.parse(data))
+  .catch(() => ({}));
+
+const getTag = (name, fn) => {
+  const found = fn
+    .toString()
+    .split("\n")
+    .filter((l) => /\s+\/\/\s/.test(l))
+    .map((l) => l.trim().replace("// ", ""))
+    .find((l) => l.startsWith(name));
+  if (!found) return "";
+  return encode(found.replace(name, "").trim());
+};
+
+const getDescription = (fn) => getTag("@description", fn) || "";
+const getReturn = (fn) => getTag("@returns", fn) || "200 OK";
+
+const generateOpenApiPaths = (handlers) => {
+  const paths = {};
+
+  for (const [method, routes] of Object.entries(handlers)) {
+    for (const route of routes) {
+      const [_, path, fn, meta] = [
+        route[0],
+        route[1],
+        route.find((p) => typeof p === "function"),
+        route.find((p) => typeof p === "object"),
+      ];
+
+      const config = getConfig(route);
+
+      if (typeof path !== "string" || path === "*" || !fn) continue;
+
+      // Normalize path (convert ":id" to "{id}" for OpenAPI)
+      const normalizedPath = path.replace(/:([a-zA-Z0-9_]+)/g, "{$1}");
+
+      if (!paths[normalizedPath]) {
+        paths[normalizedPath] = {};
+      }
+
+      const getTitle = (fn) => {
+        if (!fn.name) return null;
+        // Well, we shouldn't really rely on these, e.g. automatic names from export default
+        const wrongNames = ["default"];
+        if (wrongNames.includes(fn.name)) return null;
+        if (fn.name.length <= 3) return null;
+        if (fn.name.includes("_")) return fn.name.replaceAll("_", " ");
+        const name = fn.name
+          .split(/(?=[A-Z])/)
+          .join(" ")
+          .toLowerCase();
+        return name[0].toUpperCase() + name.slice(1);
+      };
+
+      paths[normalizedPath][method] = {
+        tags: config.tags,
+        summary:
+          config.title ||
+          getTitle(fn) ||
+          getTag("@title", fn) ||
+          `${method.toUpperCase()} ${path}`,
+        description: getDescription(fn),
+        responses: {
+          200: {
+            description: getReturn(fn),
+          },
+        },
+        ...(meta
+          ? {
+              parameters: Object.entries(meta).map(([key, value]) => ({
+                name: key,
+                in: "query",
+                required: false,
+                schema: { type: typeof value },
+                example: value,
+              })),
+            }
+          : {}),
+      };
+    }
+  }
+
+  return paths;
+};
+
+export default async (ctx) => {
+  const domain = pkg.homepage || ctx.url.origin;
+  const openApi = {
+    openapi: "3.0.0",
+    info: {
+      title: pkg.name || "API Documentation",
+      version: pkg.version || "1.0.0",
+      description: pkg.description || "",
+    },
+    servers: domain ? [{ url: domain }] : [],
+    paths: generateOpenApiPaths(ctx.app.handlers),
+  };
+
+  const configuration = ctx.options.openapi.scalar || {};
+
+  return `
+<!doctype html>
+<html>
+  <head>
+    <title>API Reference</title>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1" />
+    <style>.open-api-client-button {display: none!important;}</style>
+  </head>
+  <body>
+    <script id="api-reference" type="application/json" data-configuration="${encode(JSON.stringify(configuration))}">${JSON.stringify(openApi, null, 2)}</script>
+    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+  </body>
+</html> `;
+};

package/src/pathPattern.js

@@ -15,11 +15,24 @@ export default function pathPattern(pattern, path) {
     const patt = pattParts[i] || "";
     const part = pathParts[i] || "";
     const last = pattParts[pattParts.length - 1];
-    const key = patt.replace(/^:/, "").replace(/\?$/, "");
+    const key = patt
+      .replace(/^:/, "")
+      .replace(/\?$/, "")
+      .replace(/\(\w*\)/, "");
     if (patt === part) continue;
     if (patt.endsWith("?") && !part) continue;
     if (patt.startsWith(":")) {
       params[key] = part;
+      if (/\(\w*\)/.test(patt)) {
+        if (patt.includes("(number)")) {
+          const value = Number(part);
+          params[key] = Number.isNaN(value) ? undefined : value;
+        }
+        if (patt.includes("(date)")) {
+          const value = new Date(part);
+          params[key] = Number.isNaN(value) ? undefined : value;
+        }
+      }
       continue;
     }
     if ((!patt && last === "*" && part) || (patt === "*" && part)) {

package/src/pathPattern.test.js

@@ -25,20 +25,45 @@ describe("pathPattern.js", () => {
     expect(pathPattern("/hello/", "/hello/John")).toEqual(null);
   });
 
-  it("can capture simple groups", () => {
+  it("can capture simple params", () => {
     expect(pathPattern("/:hello", "/john")).toEqual({ hello: "john" });
     expect(pathPattern("/hello/:there", "/hello/john")).toEqual({
       there: "john",
     });
   });
 
+  it("will parse the params as numbers", () => {
+    expect(pathPattern("/:id(number)", "/25")).toEqual({ id: 25 });
+    expect(pathPattern("/:id(number)", "/25.5")).toEqual({ id: 25.5 });
+    expect(pathPattern("/users/:id(number)", "/users/25")).toEqual({
+      id: 25,
+    });
+    expect(pathPattern("/:id(date)", "/2015-01-01")).toEqual({
+      id: new Date("2015-01-01"),
+    });
+    expect(pathPattern("/report/:id(date)", "/report/2015-01-01")).toEqual({
+      id: new Date("2015-01-01"),
+    });
+  });
+
+  it("will still match, but not parse it if it's an invalid number", () => {
+    expect(pathPattern("/:id(number)", "/hi")).toEqual({});
+    expect(pathPattern("/users/:id(number)", "/users/hi")).toEqual({});
+  });
+
   it("requires a part for the asterisk", () => {
     expect(pathPattern("/hello/:there/*", "/hello/John")).toEqual(null);
   });
 
   it("can make a part optional", () => {
-    // expect(pathPattern("/:name?", "/")).toEqual({});
+    expect(pathPattern("/:name?", "/")).toEqual({});
     expect(pathPattern("/hello/:name?", "/hello/")).toEqual({});
+    expect(pathPattern("/:id(number)?", "/")).toEqual({});
+    expect(pathPattern("/:id(date)?", "/")).toEqual({});
+    expect(pathPattern("/:id(number)?", "/25")).toEqual({ id: 25 });
+    expect(pathPattern("/:id(date)?", "/2015-01-01")).toEqual({
+      id: new Date("2015-01-01"),
+    });
     expect(pathPattern("/:name?", "/john")).toEqual({ name: "john" });
     expect(pathPattern("/:name/*?", "/john")).toEqual({ name: "john" });
   });