@server/next 0.20.31 → 0.20.33

package/index.d.ts

@@ -27,7 +27,37 @@ type Context = {
   options: ServerOptions;
 };
 
-type Middleware = (ctx: Context) => any;
+type Body = string;
+
+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;
+  location?: string;
+
+  [key: string]: string | undefined;
+};
+
+type InlineReply =
+  | Response
+  | { body: Body; headers?: Headers }
+  | string
+  | number
+  | void;
+
+type Middleware = (ctx: Context) => InlineReply;
 
 type Router = {};
 
@@ -47,5 +77,8 @@ declare interface Server {
   router(router: Router): this;
 }
 
+type headers = (obj?: Headers) => any;
+
 declare const server: Server;
+export const headers: headers;
 export default server;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@server/next",
-  "version": "0.20.31",
-  "description": "An experimental reimplementation of server.js focused on the DX",
-  "homepage": "https://node-server.com/",
+  "version": "0.20.33",
+  "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",
   "bugs": "https://github.com/franciscop/server-next/issues",
   "funding": "https://www.paypal.me/franciscopresencia/19",
@@ -25,18 +25,18 @@
     "src/",
     "index.d.ts"
   ],
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "engineStrict": true,
+  "dependencies": {},
   "devDependencies": {
     "argon2": "^0.40.3",
     "jest": "^29.7.0",
     "polystore": "^0.8.0"
   },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "engineStrict": true,
   "jest": {
     "testEnvironment": "jest-environment-node",
     "transform": {}
-  },
-  "dependencies": {}
+  }
 }

package/readme.md

@@ -104,6 +104,117 @@ export default server({ bucket, store })
 
 ### File handling
 
+To manage files, you need to install and use the library [`bucket`](http://bucketjs.com/), which is a very thin wrapper for file management systems. It is also created by the makers of Server.js.
+
+The easiest and default is to set a folder in your filesystem:
+
+```js
+import FileSystem from "bucket/fs";
+
+const uploads = FileSystem("./uploads");
+
+// All paths are relative to the CWD
+export default server({ uploads })
+  .get("/", () => "Hello")
+  .put("/users/:id", async (ctx) => {
+    // This is the plain string as the file name, already in our FS
+    const fileName = ctx.body.profile;
+    // 'yOuZEdSsNLq8PgZyLhSz0Llh.jpg'
+
+    // Convert it into a File instance
+    const file = ctx.uploads.file(fileName);
+
+    // Now we can use other methods if we want
+    // .info(), .read(), .write(), .pipe(), .pipeTo(), etc
+    const info = await file.info();
+    // {
+    //    id: "yOuZEdSsNLq8PgZyLhSz0Llh.jpg",
+    //    type: "jpg",
+    //    size: 435435,
+    //    timestamp: "2024-08-07T14:26:37Z",
+    //    // Note: this can be customized providing the option "domain"
+    //    url: "file:///Users/me/my-project/uploads/yOuZEdSsNLq8PgZyLhSz0Llh.jpg",
+    // }
+
+    return 200;
+  });
+```
+
+To upload the files to a 3rd party system, you just need to use the corresponding `bucket` implementation (or write a thin compatibility layer). Let's see an example with Backblaze's B2:
+
+```js
+import server from "@server/next";
+import Backblaze from "bucket/b2";
+
+const uploads = Backblaze("bucket-name", {
+  id: process.env.BACKBLAZE_ID,
+  key: process.env.BACKBLAZE_KEY,
+});
+
+export default server({ uploads })
+  .put("/users/:id", async (ctx) => {
+    const fileName = ctx.body.profile;
+    // 'yOuZEdSsNLq8PgZyLhSz0Llh.jpg'
+
+    // Convert it into a File instance
+    const file = ctx.uploads.file(fileName);
+
+    // Now we can use other methods if we want
+    const info = await file.info();
+    // {
+    //    id: "yOuZEdSsNLq8PgZyLhSz0Llh.jpg",
+    //    type: "jpg",
+    //    size: 435435,
+    //    timestamp: "2024-08-07T14:26:37Z",
+    //    url: "https://f???.backblazeb2.com/???/yOuZEdSsNLq8PgZyLhSz0Llh.jpg",
+    // }
+
+    return 200;
+  });
+  .;
+```
+
+#### Example: resizing the user profile picture
+
+Let's see a complete example of uploading and resizing a user profile picture:
+
+```js
+import server, { status } from "@server/next";
+import sharp from "sharp";
+import FileSystem from "bucket/fs";
+
+const uploads = FileSystem("./uploads");
+
+// All paths are relative to the CWD
+export default server({ uploads })
+  .get("/", () => "Hello")
+  .put("/users/:id", async (ctx) => {
+    // Create the instance of the file to read and write
+    const src = ctx.uploads.file(ctx.body.profile);
+    const dst = ctx.uploads.file("/profile/" + ctx.url.params.id + ".jpg");
+
+    const ext = src.id.split(".").pop();
+    if (!["jpg", "jpeg", "png", "webp", "avif"].includes(ext)) {
+      await src.remove(); // Don't store it
+      return status(400).json({ error: "Invalid file format" });
+    }
+
+    // Create the Readable, Transform and Writable Node streams
+    await pipeline(
+      src.readable("node"),
+      sharp().resize(200, 200).jpg(),
+      dst.writable("node")
+    );
+
+    // We no longer need the original file
+    await src.remove();
+
+    return status(200).json({ updated: true });
+  });
+```
+
+Note that the option `uploads` gets converted into a `Bucket` instance and passed as `ctx.uploads`. Th
+
 ## Options
 
 Options docs here
@@ -119,3 +230,46 @@ Context docs here
 ## Reply
 
 Reply docs here
+
+## Runtimes
+
+There are many runtimes where Server works! We put a lot of work to make sure it works the same way with minimal changes in them, this includes:
+
+- Node.js of course, including everywhere that Node is supported (VPS, Heroku, Render, etc).
+- Bun, and it will be even faster!
+- Cloudflare Worker
+- Netlify Function + Edge function
+
+## FAQ
+
+#### How is it different from Hono?
+
+Server.js attempts to run your code unmodified in all runtimes. With Hono, despite the claims in their homepage, you need to change the code for different runtimes:
+
+```js
+// Server.js code for Node.js, Bun and Netlify
+import server from "@server/next";
+export default server().get("/", () => "Hello server!");
+```
+
+```js
+// Hono code for Node.js
+import { serve } from '@hono/node-server'
+import { Hono } from 'hono'
+const app = new Hono()
+app.get('/', (c) => c.text('Hello Node.js!'))
+serve(app)
+
+// Hono code for Bun
+import { Hono } from 'hono'
+const app = new Hono()
+app.get('/', (c) => c.text('Hello Bun!'))
+export default app
+
+// Hono code for Netlify
+import { Hono } from 'jsr:@hono/hono'
+import { handle } from 'jsr:@hono/hono/netlify'
+const app = new Hono()
+app.get('/', (c) => c.text('Hello Hono!'))
+export default handle(app)
+```

package/src/helpers/config.js

@@ -0,0 +1,68 @@
+import Bucket from "./bucket.js";
+import createId from "./createId.js";
+
+// Big mess; parse all of the options for server, which can be at launch time
+// or dynamically per-request for the functions (so have to read ENV inside)
+export default function config(options) {
+  const env = globalThis.env;
+
+  // Basic options
+  options.port = options.port || env.PORT || 3000;
+  options.secret = options.secret || env.SECRET || "unsafe-" + createId();
+
+  // CORS
+  options.cors = options.cors || env.CORS || null;
+  if (options.cors === true) {
+    options.cors = { origin: options.domain || "*" };
+  }
+  if (typeof options.cors === "string") {
+    options.cors = { origin: options.cors };
+  }
+  if (options.cors && !options.cors.methods) {
+    options.cors.methods = "GET,HEAD,POST,PUT,PATCH";
+  }
+
+  // Bucket
+  options.views = options.views ? Bucket(options.views) : null;
+  options.public = options.public ? Bucket(options.public) : null;
+  options.uploads = options.uploads ? Bucket(options.uploads) : null;
+
+  // Stores
+  options.store = options.store ?? null;
+  options.cookies = options.cookies ?? {};
+  if (options.store && options.cookies) {
+    options.session = { store: options.store.prefix("session:") };
+  }
+
+  // AUTH
+  options.auth = options.auth || env.AUTH || null;
+  if (options.auth) {
+    if (typeof options.auth !== "object") {
+      const [type, provider] = options.auth.split(":");
+      options.auth = { type, provider };
+    }
+    if (typeof options.auth.provider === "string") {
+      options.auth.provider === options.auth.provider.split("|");
+    }
+    if (!options.auth.type) {
+      throw new Error("Auth options needs a type");
+    }
+    if (!options.auth.provider) {
+      throw new Error("Auth options needs a provider");
+    }
+    if (!options.auth.session && options.store) {
+      options.auth.session = options.store.prefix("auth:");
+    }
+    if (!options.auth.store && options.store) {
+      options.auth.store = options.store.prefix("user:");
+    }
+    if (!options.auth.cleanUser) {
+      options.auth.cleanUser = (fullUser) => {
+        const { password, ...user } = fullUser;
+        return user;
+      };
+    }
+  }
+
+  return options;
+}

package/src/helpers/getMachine.js

@@ -1,12 +1,23 @@
+function getProvider() {
+  if ("Netlify" in globalThis) return "netlify";
+  return null;
+}
+
+function getService() {
+  return null;
+}
+
 function getRuntime() {
   if ("Bun" in globalThis) return "bun";
   if ("Deno" in globalThis) return "deno";
   if (globalThis.process?.versions?.node) return "node";
-  return "unknown";
+  return null;
 }
 
 export default function getMachine() {
   return {
+    provider: getProvider(),
+    service: getService(),
     runtime: getRuntime(),
     production: process.env.NODE_ENV === "production",
   };

package/src/helpers/handleRequest.js

@@ -1,9 +1,21 @@
+import middle from "../middle/index.js";
 import parseResponse from "../parseResponse.js";
 import pathPattern from "../pathPattern.js";
 import define from "./define.js";
 import validate from "./validate.js";
 
+const extendWithDefaults = (ctx) => {
+  // TODO: find a better way of doing this FFS
+  // Only want to execute it once; it needs to happen on a per-request
+  // basis since we only have full access to the options there
+  if (ctx.app.extended) return;
+  middle(ctx);
+  ctx.app.extended = true;
+};
+
 export default async function handleRequest(handlers, ctx) {
+  extendWithDefaults(ctx);
+
   for (let [method, matcher, ...cbs] of handlers[ctx.method]) {
     const match = pathPattern(matcher, ctx.url.pathname || "/");
     // Skip this whole middleware if there was no match
@@ -25,5 +37,10 @@ export default async function handleRequest(handlers, ctx) {
     if (method !== "*") break;
   }
 
+  // In Netlify, a non-response is perfectly valid, which would indicate
+  // the edge function to just go ahead and consume the original resource
+  if (ctx.machine.provider === "netlify") return;
+
+  // In other environments, a non-response is wrong and we should 404 then
   return new Response("Not Found", { status: 404 });
 }

package/src/helpers/index.js

@@ -1,5 +1,6 @@
 export { default as createCookies } from "./createCookies.js";
 export { default as createId } from "./createId.js";
+export { default as config } from "./config.js";
 export { default as define } from "./define.js";
 export { default as getMachine } from "./getMachine.js";
 export { default as handleRequest } from "./handleRequest.js";

package/src/index.js

@@ -1,18 +1,15 @@
 import "./polyfill.js";
-// Define the errors for ServerError
 import "./errors/index.js";
 
-import Bucket from "./bucket.js";
 import createNodeContext from "./context/node.js";
 import createWinterContext from "./context/winter.js";
 import {
-  createId,
+  config,
   getMachine,
   handleRequest,
   iterate,
   parseHeaders,
 } from "./helpers/index.js";
-import middle from "./middle/index.js";
 
 // Export the reply helpers
 export * from "./reply.js";
@@ -22,103 +19,20 @@ export { default as ServerError } from "./ServerError.js";
 // Allow to create a sub-router
 export { default as router } from "./router.js";
 
-const createNodeServer = async (app, options) => {
-  const http = await import("http");
-  http
-    .createServer(async (request, response) => {
-      try {
-        const ctx = await createNodeContext(request, options, app);
-        extendWithDefaults(ctx);
-        const out = await handleRequest(app.handlers, ctx);
-
-        response.writeHead(out.status || 200, parseHeaders(out.headers));
-        if (out.body instanceof ReadableStream) {
-          await iterate(out.body, (chunk) => response.write(chunk));
-        } else {
-          response.write(out.body || "");
-        }
-        response.end();
-      } catch (error) {
-        response.writeHead(error.status || 500);
-        response.write(error.message || "");
-        response.end();
-      }
-    })
-    .listen(options.port);
-};
-
-const validateOptions = (options, env = {}) => {
-  options.port = options.port || env.PORT || 3000;
-  options.secret = options.secret || env.SECRET || "unsafe-" + createId();
-  options.cors = options.cors || env.CORS || null;
-  if (options.cors === true) {
-    options.cors = { origin: options.domain || "*" };
-  }
-  if (typeof options.cors === "string") {
-    options.cors = { origin: options.cors };
-  }
-  if (options.cors && !options.cors.methods) {
-    options.cors.methods = "GET,HEAD,POST,PUT,PATCH";
-  }
-
-  options.views = options.views ? Bucket(options.views) : null;
-  options.public = options.public ? Bucket(options.public) : null;
-  options.uploads = options.uploads ? Bucket(options.uploads) : null;
-
-  options.store = options.store ?? null;
-  options.cookies = options.cookies ?? {};
-  if (options.store && options.cookies) {
-    options.session = { store: options.store.prefix("session:") };
-  }
-
-  // AUTH
-  options.auth = options.auth || env.AUTH || null;
-  if (options.auth) {
-    if (typeof options.auth !== "object") {
-      const [type, provider] = options.auth.split(":");
-      options.auth = { type, provider };
-    }
-    if (typeof options.auth.provider === "string") {
-      options.auth.provider === options.auth.provider.split("|");
-    }
-    if (!options.auth.type) {
-      throw new Error("Auth options needs a type");
-    }
-    if (!options.auth.provider) {
-      throw new Error("Auth options needs a provider");
-    }
-    if (!options.auth.session && options.store) {
-      options.auth.session = options.store.prefix("auth:");
-    }
-    if (!options.auth.store && options.store) {
-      options.auth.store = options.store.prefix("user:");
-    }
-    if (!options.auth.cleanUser) {
-      options.auth.cleanUser = (fullUser) => {
-        const { password, ...user } = fullUser;
-        return user;
-      };
-    }
-  }
-
-  return options;
-};
-
-const extendWithDefaults = (ctx) => {
-  // Only want to execute it once; it needs to happen on a per-request
-  // basis since we only have full access to the options there
-  if (ctx.app.extended) return;
-  middle(ctx);
-  ctx.app.extended = true;
-};
-
-// Export the main server()
+// #region server()
 export default function server(options = {}) {
   // Make it so that the exported one is a prototype of function()
   if (!(this instanceof server)) {
     return new server(options).self();
   }
 
+  // Keep a copy of the options in the instance
+  this.opts = options;
+  this.platform = getMachine();
+
+  // TODO: find a way to remove this hack
+  this.extended = false;
+
   // Skip "forbidden methods" https://fetch.spec.whatwg.org/#concept-method
   this.handlers = {
     socket: [],
@@ -131,71 +45,93 @@ export default function server(options = {}) {
     options: [],
   };
 
-  this.extended = false;
-
-  this.platform = getMachine();
-
-  // WEBSOCKETS stuff
-  const sockets = [];
+  this.sockets = [];
+  // Note: required by Bun
   this.websocket = {
     message: async (socket, body) => {
       this.handlers.socket
         ?.filter((s) => s[0] === "message")
-        ?.map((s) => s[1]({ socket, sockets, body }));
+        ?.map((s) => s[1]({ socket, sockets: this.sockets, body }));
     },
-    open: (ws) => sockets.push(ws),
-    close: (ws) => sockets.splice(sockets.indexOf(ws), 1),
+    open: (ws) => this.sockets.push(ws),
+    close: (ws) => this.sockets.splice(this.sockets.indexOf(ws), 1),
   };
 
-  // Starting stuff
+  // Initialize it right away for Node.js
   if (this.platform.runtime === "node") {
-    options = validateOptions(options, process.env);
-
-    createNodeServer(this, options);
+    this.node();
   }
+}
 
-  this.fetch = async (request, env, fetchCtx) => {
-    if (env?.upgrade(request)) return;
-
-    try {
-      options = validateOptions(options, env);
-      const ctx = await createWinterContext(request, options, this);
-      extendWithDefaults(ctx);
-      return await handleRequest(this.handlers, ctx);
-    } catch (error) {
-      return new Response(error.message, { status: error.status || 500 });
+server.prototype.self = function () {
+  const cb = this.callback.bind(this);
+  const proto = Object.getPrototypeOf(this);
+  for (let key in { ...proto, ...this }) {
+    if (typeof this[key] === "function") {
+      cb[key] = this[key].bind(this);
+    } else {
+      cb[key] = this[key];
     }
-  };
+  }
+  return cb;
+};
 
-  this.netlify = async (request) => {
-    try {
-      if (typeof Netlify === "undefined") {
-        throw new Error("Netlify doesn't exist");
-      }
-      if (typeof import.meta === "undefined") {
-        throw new Error("import.meta.env doesn't exist");
+// #region Runtimes
+// Node.js
+server.prototype.node = async function () {
+  const http = await import("http");
+  http
+    .createServer(async (request, response) => {
+      try {
+        const options = config(this.opts);
+        const ctx = await createNodeContext(request, options, this);
+        const out = await handleRequest(this.handlers, ctx);
+
+        response.writeHead(out.status || 200, parseHeaders(out.headers));
+        if (out.body instanceof ReadableStream) {
+          await iterate(out.body, (chunk) => response.write(chunk));
+        } else {
+          response.write(out.body || "");
+        }
+        response.end();
+      } catch (error) {
+        response.writeHead(error.status || 500);
+        response.write(error.message || "");
+        response.end();
       }
-      options = validateOptions(options, import.meta.env);
-      const ctx = await createWinterContext(request, options, this);
-      extendWithDefaults(ctx);
-      return await handleRequest(this.handlers, ctx);
-    } catch (error) {
-      return new Response(error.message, { status: error.status || 500 });
+    })
+    .listen(this.opts.port);
+};
+
+// Netlify
+server.prototype.callback = async function (request) {
+  try {
+    if (typeof Netlify === "undefined") {
+      throw new Error("Netlify doesn't exist");
     }
-  };
-}
+    const options = config(this.opts);
+    const ctx = await createWinterContext(request, options, this);
+    return await handleRequest(this.handlers, ctx);
+  } catch (error) {
+    return new Response(error.message, { status: error.status || 500 });
+  }
+};
 
-server.prototype.self = function () {
-  const cb = this.netlify;
-  const keys = Object.keys(Object.getPrototypeOf(this)).concat(
-    Object.keys(this)
-  );
-  keys.forEach((key) => {
-    cb[key] = this[key];
-  });
-  return cb;
+// WinterCG, Bun, Cloudflare Workers
+server.prototype.fetch = async function (request, env) {
+  if (env?.upgrade(request)) return;
+  Object.assign(globalThis.env, env); // Extend env with the passed vars
+
+  try {
+    const options = config(this.opts);
+    const ctx = await createWinterContext(request, options, this);
+    return await handleRequest(this.handlers, ctx);
+  } catch (error) {
+    return new Response(error.message, { status: error.status || 500 });
+  }
 };
 
+// #region HTTP methods
 // INTERNAL
 server.prototype.handle = function (method, path, ...middleware) {
   if (method === "*") {
@@ -248,6 +184,7 @@ server.prototype.use = function (...middleware) {
   return this.handle("*", "*", ...middleware);
 };
 
+// Unwind the children routers into the main router
 server.prototype.router = function (basePath, router) {
   basePath = ("/" + basePath + "/").replace(/^\/+/, "/").replace(/\/+$/, "/");
   for (const method in router.handlers) {
@@ -258,6 +195,7 @@ server.prototype.router = function (basePath, router) {
   return this.self();
 };
 
+// #region Testing helper
 server.prototype.test = function () {
   let cookie = "";
   const fetch = async (path, options = {}) => {

package/src/index.test.js

@@ -13,6 +13,21 @@ describe("exports", () => {
 
   it("export has a fetch", () => {
     expect(typeof server().fetch).toBe("function");
+    expect(typeof server().get().fetch).toBe("function");
+  });
+
+  it("export has the basic methods", () => {
+    expect(typeof server().get).toBe("function");
+    expect(typeof server().post).toBe("function");
+    expect(typeof server().use).toBe("function");
+    expect(typeof server().router).toBe("function");
+  });
+
+  it("export has the basic nested methods", () => {
+    expect(typeof server().get().get).toBe("function");
+    expect(typeof server().post().post).toBe("function");
+    expect(typeof server().use().use).toBe("function");
+    expect(typeof server().get().router).toBe("function");
   });
 
   it("nested is also a function", () => {

package/src/pathPattern.js

@@ -30,5 +30,5 @@ export default function pathPattern(pattern, path) {
     allSame = false;
   }
   if (allSame) return params;
-  return false;
+  return null;
 }

package/src/pathPattern.test.js

@@ -2,6 +2,8 @@ import pathPattern from "./pathPattern.js";
 
 describe("pathPattern.js", () => {
   it("matches the same string", () => {
+    expect(pathPattern("/", "/hello")).toEqual(null);
+    expect(pathPattern("/hello", "/")).toEqual(null);
     expect(pathPattern("/hello", "/hello")).toEqual({});
     expect(pathPattern("/hello/world", "/hello/world")).toEqual({});
   });
@@ -19,8 +21,8 @@ describe("pathPattern.js", () => {
   });
 
   it("doesn't do partial matches", () => {
-    expect(pathPattern("/hello", "/hello/John")).toEqual(false);
-    expect(pathPattern("/hello/", "/hello/John")).toEqual(false);
+    expect(pathPattern("/hello", "/hello/John")).toEqual(null);
+    expect(pathPattern("/hello/", "/hello/John")).toEqual(null);
   });
 
   it("can capture simple groups", () => {
@@ -31,7 +33,7 @@ describe("pathPattern.js", () => {
   });
 
   it("requires a part for the asterisk", () => {
-    expect(pathPattern("/hello/:there/*", "/hello/John")).toEqual(false);
+    expect(pathPattern("/hello/:there/*", "/hello/John")).toEqual(null);
   });
 
   it("can make a part optional", () => {

package/src/polyfill.js

@@ -6,7 +6,13 @@ if (typeof Response === "undefined") {
 }
 
 // Polyfill Netlify's environment variables
-if (typeof Netlify !== "undefined" && typeof import.meta !== "undefined") {
-  if (!import.meta.env) import.meta.env = {};
-  Object.assign(import.meta.env, Netlify.env.toObject());
+globalThis.env = {};
+if (typeof Netlify !== "undefined") {
+  Object.assign(env, Netlify.env.toObject());
+}
+if (typeof process !== "undefined") {
+  Object.assign(env, process.env);
+}
+if (typeof import.meta.env !== "undefined") {
+  Object.assign(env, import.meta.env);
 }