@server/next 0.20.32 → 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,6 +1,6 @@
 {
   "name": "@server/next",
-  "version": "0.20.32",
+  "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",
@@ -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

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

@@ -5,6 +5,7 @@ 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;
@@ -36,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/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", () => {