@server/next 0.17.2 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@server/next",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "An experimental reimplementation of server.js focused on the DX",
   "homepage": "https://node-server.com/",
   "repository": "https://github.com/franciscop/server-next.git",
@@ -10,9 +10,10 @@
   "license": "UNLICENSED",
   "scripts": {
     "demo": "nodemon ./demo/app.js",
-    "start": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
-    "size": "echo \"$(gzip -c index.js | wc -c) bytes\" # Only for Unix",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+    "build": "bun build src/index.js --outdir ./ --entry-naming server.js",
+    "start": "bun test --watch",
+    "size": "echo \"$(gzip -c server.js | wc -c) bytes\" # Only for Unix",
+    "test": "bun test"
   },
   "keywords": [
     "server",
@@ -25,14 +26,10 @@
     "src/"
   ],
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=20.0.0"
   },
   "engineStrict": true,
-  "dependencies": {
-    "dotenv": "^16.0.1",
-    "spinnies": "^0.5.1",
-    "urlpattern-polyfill": "^5.0.0"
-  },
+  "dependencies": {},
   "devDependencies": {
     "jest": "^26.0.1",
     "prettier": "^2.7.0"

package/readme.md

@@ -1,47 +1,53 @@
 # Server @ Next
 
-> **VERY EARLY WORK IN PROGRESS**
->
-> **I don't know what will come out of this, if anything! Treat as the most experimental thing you've ever seen**
+> **EXPERIMENTAL LIBRARY**
 
-A fully-fledged web server for Node.js, with all the basics covered for you:
+A fully-fledged web server for Bun and Node.js, with all the basics covered for you:
 
 ```js
-import server, { get, post, put, use } from "server";
+import server from "@server/next";
 
 // Create a running instance of the server
-const app = server(config, [pluginA, pluginB]);
-
-// Attach handlers to the instance
-app([
-  get("/users", getUsers),
-  post("/users", createUser),
-  put("/users/:id", editUser),
-  use("/admin/*", dashboard),
-]);
+export default server(options)
+  .router("/admin/", dashboard)
+  .get("/users", getUsers)
+  .post("/users", createUser)
+  .put("/users/:id", editUser);
 ```
 
 It includes all the things you would expect from a modern Server framework, like routing, static file serving, options\*, body+file parsing, gzip+brotli, streaming, server-timing, plugins\*, etc.
 
 > \* not yet available
 
+For testing it's also easy, since we are exporting our server throught the WinterCG API we can do:
+
+```js
+// index.test.js
+import app from "./";
+
+it("can retrieve the homepage", async () => {
+  const res = await app.fetch(new Request("http://localhost:3000/hello/"));
+  const data = await res.text();
+  expect(data).toBe("Hello world");
+});
+```
+
 ## Upgrading server
 
-Why? The ecosystem is moving out of server-rendered websites so we are as well. Now instead we treat APIs as first-class citizens. Desired improvements (WIP!):
+Why? We live in the era of multi-cloud (Heroku, Workers, Lambda, etc) and multi-runtimes (Node.js, Bun, WinterGC, etc). Desired improvements (WIP!):
 
-- Tiny footprint with no dependencies\*, all bundled in a single file. Installing and using the full library takes under 10kb (target limit).
+- Tiny footprint with few dependencies. Installing and using the full library takes under 10kb (target limit).
 - Faster! Reimplemented from scratch for speed. With raw ES6+ and a tiny code footprint, your server will fly.
 - Modern ES6+ESM syntax for both the library and examples.
-- Error handling improved greatly.
 - Not using express underneath anymore. Considering keeping the compatibility layer anyway (since Express itself is a thin layer).
 - Changed the reply logic greatly, including the removal of `render()`. This is the main reason express was removed. Many servers don't need render() at all.
-- **[security]** Removed mandatory CSRF token, since this is only useful for server-rendered pages and not for SPA. You can activate it with a single option as before.
+- **[security]** Removed mandatory CSRF token, since this is only useful for server-rendered pages and not for SPA. Now we provide an `auth` module instead.
 
 Major changes:
 
 - New fully fledged `ctx.url` that extends [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object inside `ctx` (also note: `ctx.url` is no longer a string):
   - `ctx.params` is now `ctx.url.params`, e.g. `ctx.url.params.id`.
-  - `ctx.query` is now `ctx.url.query`, e.g. `ctx.url.params.search`.
+  - `ctx.query` is now `ctx.url.query`, e.g. `ctx.url.query.search`.
   - `ctx.path` is now `ctx.url.path` (or `ctx.url.pathname`).
   - All URL properties are available, like `ctx.url.port`, `ctx.url.searchParams`, etc.
 
@@ -101,7 +107,6 @@ Creating a 100x100px thumbnail on the fly with Sharp:
 
 ```js
 // createThumbnail.js
-import { get } from "@server/next";
 import sharp from "sharp";
 
 export default function createThumbnail(ctx) {
@@ -109,3 +114,100 @@ export default function createThumbnail(ctx) {
   return sharp(ctx.url.params.name).resize(100, 100, { fit: "cover" }).png();
 }
 ```
+
+### Breaking Changes
+
+`import`, `export` and routing are the main changes from your point of view:
+
+```js
+import server, { status, type, ...reply } from 'server';
+
+export default server({ ...options })
+  .use(mid1)
+  .get('/', cb1)
+  .get('/b', mid2, cb2)
+  .routes({ get: [['/c', mid3, cb3]] });
+```
+
+`status()` now it's always partial:
+
+```js
+// OLD
+return 404;
+return status(404).send("Not here..."); // treated as partial
+return status(404); // treated as final
+
+// NEW
+return 404;
+return status(404).send("Not here..."); // GOOD
+return status(404).send(); // GOOD
+
+// DON'T DO:
+return status(404); // INVALID
+```
+
+```js
+import server from "server";
+
+export default server()
+  .get("/", () => "Hello world")
+  .post("/", (ctx) => {
+    console.log(ctx.body);
+    return 201;
+  });
+```
+
+```js
+import server, { jwtAuth } from "server";
+import BookRouter from "./BookRouter";
+import UserRouter from "./UserRouter";
+
+export default server({ port: 3000 })
+  .use(jwtAuth)
+  .route("/users", UserRouter)
+  .route("/books", BookRouter);
+```
+
+```js
+// UserRouter.js -> A custom router
+import server, { router } from "server";
+
+export default router()
+  .get("/", getUsers)
+  .get("/:id", getUser)
+  .post("/", createUser);
+```
+
+MAYBE?
+
+```js
+// BookRouter.js -> a REST API router
+import { RestRouter } from "server";
+
+export default class BookRouter extends RestRouter {
+  async create(ctx) {
+    // POST /
+  }
+  async list(ctx) {
+    // GET /
+  }
+  async get(ctx) {
+    // GET /:id
+  }
+  async search(ctx) {
+    // GET /?...
+  }
+  async update(ctx) {
+    // PUT /:id
+  }
+  async set(ctx) {
+    // PATCH /:id
+  }
+  async delete(ctx) {
+    // DELETE /:id
+  }
+  async error(ctx) {
+    // ctx.error
+  }
+}
+```

package/src/bucket.js

@@ -1,6 +1,7 @@
-import path from "node:path";
-import fs from "node:fs";
-import fsp from "node:fs/promises";
+import fs from "fs";
+import path from "path";
+
+import fsp from "fs/promises";
 
 // A fake tiny implementation of a generic bucket, it needs
 // at the very least a read(id) and write(id, value), both returning
@@ -12,6 +13,7 @@ export default function (root) {
   };
 
   return {
+    path: root,
     read: (name, type = "utf8") => {
       const fullPath = absolute(name);
       return fsp.readFile(fullPath, type);

package/src/context/node.js

@@ -0,0 +1,28 @@
+import { define } from "../helpers/index.js";
+import parseBody from "./parseBody.js";
+import parseCookies from "./parseCookies.js";
+
+export default async (request, options = {}) => {
+  const ctx = {};
+  ctx.req = request;
+  ctx.res = { status: null, headers: {}, cookies: {} };
+  ctx.method = request.method.toLowerCase();
+
+  ctx.headers = request.headers;
+  define(ctx, "cookies", () => parseCookies(request.headers.cookie));
+
+  const https = request.connection.encrypted ? "https" : "http";
+  const host = ctx.headers.host || "localhost" + options.port;
+  const path = request.url.replace(/\/$/, "") || "/";
+  ctx.url = new URL(path, `${https}://${host}`);
+  define(ctx.url, "query", (url) =>
+    Object.fromEntries(url.searchParams.entries())
+  );
+
+  if (request.body) {
+    const type = ctx.headers["content-type"];
+    ctx.body = await parseBody(request, type, options.uploads);
+  }
+
+  return ctx;
+};

package/src/{parseBody.js → context/parseBody.js}

@@ -21,18 +21,6 @@ function getMatching(string, regex) {
   return matches[1];
 }
 
-const getBody = async (req) => {
-  return await new Promise((done) => {
-    const buffers = [];
-    req.on("data", (chunk) => {
-      buffers.push(chunk);
-    });
-    req.on("end", () => {
-      done(Buffer.concat(buffers).toString("binary"));
-    });
-  });
-};
-
 const nanoid = (size = 12) => {
   let str = "";
   while (str.length < size + 2) {
@@ -48,12 +36,16 @@ const saveFile = async (name, value, bucket) => {
   return id;
 };
 
-export default async function Parse(req, contentType, bucket) {
-  const rawData = await (typeof req === "string" ? req : getBody(req));
-  if (!rawData) return null;
+export default async function parseBody(raw, contentType, bucket) {
+  const rawData = typeof raw === "string" ? raw : await raw.text();
+  if (!rawData) return {};
+
+  if (!contentType || /text\/plain/.test(contentType)) {
+    return rawData;
+  }
 
   if (/application\/json/.test(contentType)) {
-    return { body: JSON.parse(rawData), files: {} };
+    return JSON.parse(rawData);
   }
 
   const boundary = getBoundary(contentType);

package/src/{parseBody.test.js → context/parseBody.test.js}

@@ -36,9 +36,6 @@ const getBody = () => {
   return body;
 };
 
-const matchMd = expect.stringMatching(/^file-\w{12}.md$/);
-const matchTxt = expect.stringMatching(/^file-\w{12}.txt$/);
-
 describe("parseBody", () => {
   it("can parse the example body", async () => {
     const body = await parseBody(
@@ -50,6 +47,9 @@ describe("parseBody", () => {
       hello: "world",
       test: ["test message 123456", "test message number two"],
     });
+
+    const matchMd = expect.stringMatching(/^file-\w{12}.md$/);
+    const matchTxt = expect.stringMatching(/^file-\w{12}.txt$/);
     expect(body).toMatchObject({
       profile: matchMd,
       gallery: [matchTxt, matchTxt],

package/src/context/parseCookies.js

@@ -0,0 +1,9 @@
+export default function parseCookies(cookies) {
+  if (!cookies) return {};
+  return Object.fromEntries(
+    cookies.split(/;\s*/).map((part) => {
+      const [key, ...rest] = part.split("=");
+      return [key, decodeURIComponent(rest.join("="))];
+    })
+  );
+}

package/src/context/winter.js

@@ -0,0 +1,25 @@
+import { define } from "../helpers/index.js";
+import parseBody from "./parseBody.js";
+import parseCookies from "./parseCookies.js";
+
+export default async (request, options = {}) => {
+  const ctx = {};
+  ctx.req = request;
+  ctx.res = { status: null, headers: {}, cookies: {} };
+  ctx.method = request.method.toLowerCase();
+
+  define(ctx, "headers", () => Object.fromEntries(request.headers.entries()));
+  define(ctx, "cookies", () => parseCookies(request.headers.get("cookie")));
+
+  ctx.url = new URL(request.url.replace(/\/$/, ""));
+  define(ctx.url, "query", (url) =>
+    Object.fromEntries(url.searchParams.entries())
+  );
+
+  if (request.body) {
+    const type = ctx.headers["content-type"];
+    ctx.body = await parseBody(request, type, options.uploads);
+  }
+
+  return ctx;
+};

package/src/helpers/define.js

@@ -0,0 +1,18 @@
+// An amazing lazy-definition. It will _not_ parse these properties
+// until needed, and once it has parsed them, it'll replace itself
+// with the value at once, hence it's called 0-1 times even if the
+// properties are accessed 0-N times
+export default function define(obj, key, cb) {
+  Object.defineProperty(obj, key, {
+    configurable: true,
+    get() {
+      const value = cb(obj);
+      Object.defineProperty(obj, key, {
+        configurable: false,
+        writable: false,
+        value,
+      });
+      return obj[key];
+    },
+  });
+}

package/src/helpers/getMachine.js

@@ -0,0 +1,13 @@
+function getRuntime() {
+  if ("Bun" in globalThis) return "bun";
+  if ("Deno" in globalThis) return "deno";
+  if (globalThis.process?.versions?.node) return "node";
+  return "unknown";
+}
+
+export default function getMachine() {
+  return {
+    runtime: getRuntime(),
+    production: process.env.NODE_ENV === "production",
+  };
+}

package/src/helpers/handleRequest.js

@@ -0,0 +1,20 @@
+import parseResponse from "../parseResponse.js";
+import pathPattern from "../pathPattern.js";
+import define from "./define.js";
+
+export default async function handleRequest(handlers, ctx) {
+  for (let [matcher, ...cbs] of handlers[ctx.method]) {
+    const match = pathPattern(matcher, ctx.url.pathname || "/");
+    // Skip this whole middleware if there was no match
+    if (!match) continue;
+
+    define(ctx.url, "params", () => match);
+
+    for (let cb of cbs) {
+      const out = await parseResponse(cb, ctx);
+      if (out) return out;
+    }
+  }
+
+  return Response("Not Found", { status: 404 });
+}

package/src/helpers/index.js

@@ -0,0 +1,5 @@
+export { default as define } from "./define.js";
+export { default as getMachine } from "./getMachine.js";
+export { default as handleRequest } from "./handleRequest.js";
+export { default as iterate } from "./iterate.js";
+export { default as types } from "./types.js";

package/src/helpers/iterate.js

@@ -0,0 +1,8 @@
+export default async function iterate(stream, cb) {
+  const reader = stream.getReader();
+  while (true) {
+    const chunk = await reader.read();
+    if (chunk.done || !chunk.value) return;
+    cb(chunk.value);
+  }
+}

package/src/helpers/types.js

@@ -0,0 +1,79 @@
+// From https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
+export default {
+  aac: "audio/aac",
+  abw: "application/x-abiword",
+  arc: "application/x-freearc",
+  avif: "image/avif",
+  avi: "video/x-msvideo",
+  azw: "application/vnd.amazon.ebook",
+  bin: "application/octet-stream",
+  bmp: "image/bmp",
+  bz: "application/x-bzip",
+  bz2: "application/x-bzip2",
+  cda: "application/x-cdf",
+  csh: "application/x-csh",
+  css: "text/css",
+  csv: "text/csv",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  eot: "application/vnd.ms-fontobject",
+  epub: "application/epub+zip",
+  gz: "application/gzip",
+  gif: "image/gif",
+  htm: "text/html",
+  html: "text/html",
+  ico: "image/vnd.microsoft.icon",
+  ics: "text/calendar",
+  jar: "application/java-archive",
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
+  js: "text/javascript",
+  json: "application/json",
+  jsonld: "application/ld+json",
+  mid: "audio/midi",
+  midi: "audio/midi",
+  mjs: "text/javascript",
+  mp3: "audio/mpeg",
+  mp4: "video/mp4",
+  mpeg: "video/mpeg",
+  mpkg: "application/vnd.apple.installer+xml",
+  odp: "application/vnd.oasis.opendocument.presentation",
+  ods: "application/vnd.oasis.opendocument.spreadsheet",
+  odt: "application/vnd.oasis.opendocument.text",
+  oga: "audio/ogg",
+  ogv: "video/ogg",
+  ogx: "application/ogg",
+  opus: "audio/opus",
+  otf: "font/otf",
+  png: "image/png",
+  pdf: "application/pdf",
+  php: "application/x-httpd-php",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  rar: "application/vnd.rar",
+  rtf: "application/rtf",
+  sh: "application/x-sh",
+  svg: "image/svg+xml",
+  tar: "application/x-tar",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  ts: "video/mp2t",
+  ttf: "font/ttf",
+  txt: "text/plain",
+  vsd: "application/vnd.visio",
+  wav: "audio/wav",
+  weba: "audio/webm",
+  webm: "video/webm",
+  webp: "image/webp",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  xhtml: "application/xhtml+xml",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  xml: "application/xml",
+  xul: "application/vnd.mozilla.xul+xml",
+  zip: "application/zip",
+  "3gp": "video/3gpp",
+  "3g2": "video/3gpp2",
+  "7z": "application/x-7z-compressed",
+};