@server/next 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@server/next",
-  "version": "0.23.0",
+  "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,8 +19,8 @@
   },
   "scripts": {
     "start": "bun test --watch",
-    "lint": "npx @biomejs/biome lint ./src --skip=lint/style/noParameterAssign",
-    "test": "bun test",
+    "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"
   },
   "keywords": [
@@ -29,15 +29,15 @@
     "server.js"
   ],
   "type": "module",
-  "types": "index.d.ts",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "files": [
     "src/",
-    "index.d.ts",
     "jsx-dev-runtime.js"
   ],
   "devDependencies": {
     "argon2": "^0.40.3",
+    "check-dts": "^0.8.2",
     "jest": "^29.7.0",
     "polystore": "^0.14.1"
   },

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/helpers/createId.js

@@ -45,8 +45,7 @@ const randomId = (size = 16) => {
   return id;
 };
 
-export default function createId(source) {
-  const size = 16;
+export default function createId(source, size = 16) {
   if (source) return hash(source, size);
   return randomId(size);
 }

package/src/helpers/jsx.js

@@ -16,6 +16,7 @@ const altAttrs = {
 // "" and 0 are valid children, false and null and undefined are not
 const isValidChild = (child) => child || child === "" || child === 0;
 
+const escapeCSS = (value) => String(value).replace(/[<>&"'`]/g, "\\$&");
 const minifyCss = (str) =>
   str
     .replace(/\s+/g, " ")
@@ -42,7 +43,7 @@ export const jsx = (tag, { children, ...props }) => {
     children = () => src;
   }
   if (tag === "style" && children && typeof children === "string") {
-    const src = minifyCss(children);
+    const src = minifyCss(escapeCSS(children));
     children = () => src;
   }
   if (props.dangerouslySetInnerHTML)

package/{index.d.ts → src/index.d.ts}

@@ -1,5 +1,3 @@
-type Bucket = {};
-
 type Method =
   | "socket"
   | "get"
@@ -10,25 +8,85 @@ type Method =
   | "delete"
   | "options";
 
+type Store = {
+  get: (key: string) => Promise<any>;
+  set: (
+    key: string,
+    value: any,
+    { expires }?: { expires?: string | number },
+  ) => Promise<any>;
+};
+
+type Bucket = any;
+
+type Auth = {
+  type: "cookie" | "token";
+  provider: "github" | "email";
+};
+type AuthString = `${Auth["type"]}:${Auth["provider"]}`;
+
+type Domain = `https://${string}/`;
+type Origin = boolean | "*" | Domain | Domain[];
+type Cors = {
+  origin: Origin;
+  methods: string;
+  headers: string;
+  credentials?: boolean;
+};
+
 type ServerOptions = {
   port?: number;
   views?: string | Bucket;
   public?: string | Bucket;
   uploads?: string | Bucket;
-  auth?: string | { type: string; provider: string };
+  cors?: boolean | Origin | Cors;
+  auth?: AuthString | Auth;
+  store?: Store;
 };
 
 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<
@@ -44,7 +102,7 @@ type Context<Path extends string = string> = {
   body?: any;
   url: URL & {
     params: Simplify<PathToParams<Path>>; // Simplify here
-    query: {};
+    query: { [key: string]: string };
   };
   options: ServerOptions;
 };
@@ -55,18 +113,11 @@ type ContentType = "application/json" | "text/plain" | (string & {});
 
 // (src: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)
 type Headers = {
-  "Cache-Control"?: string;
-  "Content-Type"?: ContentType;
-  Server?: string;
-  "Set-Cookie"?: string;
-  "Content-Length"?: string;
-  Location?: string;
-
   "cache-control"?: string;
   "content-type"?: ContentType;
-  server?: string;
   "set-cookie"?: string;
   "content-length"?: string;
+  server?: string;
   location?: string;
 
   [key: string]: string | undefined;
@@ -77,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;
@@ -94,6 +145,21 @@ declare interface Router {
 }
 
 declare interface Server {
+  /**
+   * Launch the server with the optional configuration:
+   *
+   * ```js
+   * export default server({
+   *   port: 3000,
+   *   public: './public',
+   *   store: kv(new Map()),
+   * })
+   * ```
+   *
+   * **[→ Getting Started](https://react-test.dev/documentation#attr)**
+   *
+   * **[→ Options Docs](https://react-test.dev/documentation#attr)**
+   */
   (options?: ServerOptions): this;
 
   socket(path: string, ...middle: Middleware[]): 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";
@@ -21,7 +21,6 @@ export { default as ServerError } from "./ServerError.js";
 // Allow to create a sub-router
 export { default as router } from "./router.js";
 
-// #region server()
 export default function server(options = {}) {
   // Make it so that the exported one is a prototype of function()
   if (!(this instanceof server)) {
@@ -76,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/index.types.ts

@@ -0,0 +1,28 @@
+import server, { headers, router } from ".";
+
+const users = router
+  .post("/users", (ctx) => {
+    console.log(ctx.url.pathname);
+    console.log(ctx.url.query);
+    console.log(ctx.url.params); // No .id
+  })
+  .get("/users/:id?", (ctx) => {
+    console.log(ctx.url.params.id);
+  })
+  .del("/users/:id", (ctx) => {
+    console.log(ctx.url.params.id);
+  });
+
+server()
+  .get("/", (ctx) => {
+    console.log(ctx.method);
+    console.log(ctx.url);
+    console.log(ctx.headers);
+    console.log(ctx.cookies);
+    console.log(ctx.body);
+    return headers();
+  })
+  .router(users)
+  .post("/", () => {
+    return 201;
+  });

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/parseResponse.js

@@ -1,6 +1,4 @@
-// import { Readable } from "node:stream";
-
-import { cors, createCookies, createId } from "./helpers/index.js";
+import { cors, createId } from "./helpers/index.js";
 import { json } from "./reply.js";
 import ServerError from "./ServerError.js";
 

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" });
   });