@marko/run 0.0.1-beta6 → 0.0.1-beta7

package/README.md

@@ -1,3 +1,6 @@
+> **Warning**
+> This project is in BETA - use at your own peril, but please do provide helpful feedback.
+
 <div align="center">
   <!-- Logo -->
   <h1>
@@ -51,9 +54,9 @@ The package provides a command line tool `marko-run` which can be run using scri
 > npx marko-run build
 ```
 
-**`preview`** - Create a production build and serve
+**`serve`** - Create a production build and serve
 ```bash
-> npx marko-run preview
+> npx marko-run serve
 ```
 or (default command)
 ```bash
@@ -76,38 +79,30 @@ export default defineConfig({
 
 ## Adapters
 
-*🎗 TODO: provide a quick overview*
+<!-- TODO: link to existing adapters>
+
+<!-- *🎗 TODO: provide a quick overview* -->
 
 ## Runtime
 
 Generally, when using an adapter, this runtime will be abstracted away.
 
+<!-- TODO: Add examples -->
+<!-- TODO: Split fetch and match + invoke in two sections and explain why you might use one or the other  -->
+
 ```ts
 import { router, matchRoute, invokeRoute } from '@marko/run/router`;
 ```
 
-### `router`
+### `fetch`
 
 ```ts
-interface RequestContext<T> {
-  url: URL;
-  method: string;
-  request: Request;
-  platform: T;
-}
-
-async function router(context: RequestContext) => Promise<Response | void>;
+async function fetch<T>(request: Request, platform: T) => Promise<Response | void>;
 ```
 
-This asynchronous function takes a context object and returns the [WHATWG `Response` object](https://fetch.spec.whatwg.org/#response-class) from executing any matched route files or undefined if the request was explicitly not handled. If no route matches the requested path, a `404` status code response will be returned. If an error occurs a `500` status code response will be returned.
+This asynchronous function takes a [WHATWG `Request` object](https://fetch.spec.whatwg.org/#request-class) object and an object containing any platform specific data you may want access to and returns the [WHATWG `Response` object](https://fetch.spec.whatwg.org/#response-class) from executing any matched route files or undefined if the request was explicitly not handled. If no route matches the requested path, a `404` status code response will be returned. If an error occurs a `500` status code response will be returned.
 
-The context object contains the following properties
-- `url`: The URL reprensting the requested resource
-- `method`: The HTTP method used
-- `request`: [WHATWG `Request` object](https://fetch.spec.whatwg.org/#request-class)
-- `platform`: An object containing any platform-specific data (eg Node request/response) and will vary between adapters.
-
-### `matchRoute`
+### `match`
 
 ```ts
 interface interface Route {
@@ -115,7 +110,7 @@ interface interface Route {
   meta: unknown;
 }
 
-function matchRoute(method: string, pathname: string) => Route | null;
+function match(method: string, pathname: string) => Route | null;
 ```
 
 This synchronous function takes an HTTP method and path name, then returns an object representing the best match — or `null` if no match is found.
@@ -123,20 +118,20 @@ This synchronous function takes an HTTP method and path name, then returns an ob
 - `params` - a `{ key: value }` collection of any path parameters for the route
 - `meta` - metadata for the route
 
-### `invokeRoute`
+### `invoke`
 
 ```ts
-function invokeRoute(route: Route, context: RequestContext) => Promise<Response | void>;
+async function invoke<T>(route: Route, request: Request, platform: T) => Promise<Response | void>;
 ```
-This asynchronous function takes a route object returned by [matchRoute](#matchRoute) and a context object and returns a response in the same way the [router](#router) does.
+This asynchronous function takes a route object returned by [match](#match) the request and platform data and returns a response in the same way the [fetch](#fetch) does.
 
 
 
 ## File-based Routing
 
-### Nested Routing
+<!-- ### Nested Routing
 
-*🎗 TODO: provide a quick overview*
+*🎗 TODO: provide a quick overview* -->
 
 ### Routes Directory
 
@@ -276,6 +271,8 @@ Responses with this page will have a `500` status code.
 
 ### Execution Order
 
+<!-- TODO: add file tree and update flow-chart with file names -->
+
 For a matched route, the routable files execute in the following order:
 
 1. Middlewares from root-most to leaf-most
@@ -315,16 +312,15 @@ Within the _routes directory_, the directory structure will determine the path t
   /projects
   ```
 
-2. **Pathless directories** - These directories do **not** contribute their name to the route's served path. Directory names that start with an underscore (`_`) or directories named `index` will be a pathless directory.
+2. **Pathless directories** - These directories do **not** contribute their name to the route's served path. Directory names that start with an underscore (`_`) will be a pathless directory.
 
   Examples:
   ```
   /_users
   /_public
-  /index
   ```
 
-3. **Dynamic directories** - These directories introduce a dynamic parameter to the route's served path and will match any value at that segment. Any directory name that starts with a single dollar sign (`$`) will be a dynamic directory, and the remaining directory name will be the parameter at runtime. If the directory name is exactly `$/`, the parameter will not exist at runtime but will be matched.
+3. **Dynamic directories** - These directories introduce a dynamic parameter to the route's served path and will match any value at that segment. Any directory name that starts with a single dollar sign (`$`) will be a dynamic directory, and the remaining directory name will be the parameter at runtime. If the directory name is exactly `$`, the parameter will not be captured but it will be matched.
 
   Examples:
   ```
@@ -333,7 +329,7 @@ Within the _routes directory_, the directory structure will determine the path t
   /$
   ```
 
-4. **Catch-all directories** - These directories are similar to dynamic directories and introduce a dynamic parameter, but instead of matching a single path segment, they match to the end of the path. Any directory that starts with two dollar signs (`$$`) will be a catch-all directory, and the remaining directory name will be the parameter at runtime. In the case of a directory named `$$/`, the parameter name at runtime will be `*`. Catch-all directories can be used to make `404` Not Found routes at any level, including the root.
+4. **Catch-all directories** - These directories are similar to dynamic directories and introduce a dynamic parameter, but instead of matching a single path segment, they match to the end of the path. Any directory that starts with two dollar signs (`$$`) will be a catch-all directory, and the remaining directory name will be the parameter at runtime. In the case of a directory named `$$`, the parameter name will not be captured but it will match. Catch-all directories can be used to make `404` Not Found routes at any level, including the root.
 
   Because catch-all directories match any path segment and consume the rest of the path, you cannot nest route files in them and no further directories will be traversed.
 
@@ -344,6 +340,10 @@ Within the _routes directory_, the directory structure will determine the path t
   /$$
   ```
 
-### Match Ranking
+<!-- ### Match Ranking
+
+*TODO: Write some things* -->
+
+
+## TypeScript
 
-*TODO: Write some things*

package/dist/adapter/default-entry.mjs

@@ -1,17 +1,20 @@
 import createStaticServe from "serve-static";
 import compression from "compression";
 import { createServer } from "http";
-import createMiddleware from "@marko/run/adapter/middleware";
-import { router } from "@marko/run/router";
+import { createMiddleware } from "@marko/run/adapter/middleware";
+import { fetch } from "@marko/run/router";
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const { PORT = 3456 } = process.env;
 
-const dir = process.cwd();
-const middleware = createMiddleware(router);
+const middleware = createMiddleware(fetch);
 const compress = compression({
   threshold: 500,
 });
-const staticServe = createStaticServe(dir, {
+const staticServe = createStaticServe(__dirname, {
   index: false,
   immutable: true,
   maxAge: "365 days",

package/dist/adapter/index.cjs

@@ -94,7 +94,7 @@ function getOrigin(req, protocol, host, trustProxy) {
   }
   return `${protocol}://${host}`;
 }
-function createMiddleware(router, options = {}) {
+function createMiddleware(fetch2, options = {}) {
   const { trustProxy = process.env.TRUST_PROXY === "1" } = options;
   let { origin = process.env.ORIGIN } = options;
   let protocol;
@@ -107,45 +107,28 @@ function createMiddleware(router, options = {}) {
     origin ?? (origin = getOrigin(req, protocol, host, trustProxy));
     const url = new URL(req.url, origin);
     const ip = req.ip || trustProxy && getForwardedHeader(req, "for") || req.socket.remoteAddress || "";
-    const requestContext = {
+    const headers = req.headers;
+    const body = req.method === "GET" || req.method === "HEAD" ? void 0 : req.socket ? req : new ReadableStream({
+      start(controller) {
+        req.on("data", (chunk) => controller.enqueue(chunk));
+        req.on("end", () => controller.close());
+        req.on("error", (err) => controller.error(err));
+      }
+    });
+    const request = new Request(url, {
       method: req.method,
-      url,
-      platform: {
-        ip,
-        request: req,
-        response: res,
-        setCookie(cookie) {
-          res.appendHeader("set-cookie", cookie);
-        }
+      headers,
+      body,
+      duplex: "half"
+    });
+    const response = await fetch2(request, {
+      ip,
+      request: req,
+      response: res,
+      setCookie(cookie) {
+        res.appendHeader("set-cookie", cookie);
       }
-    };
-    Object.defineProperty(requestContext, "request", {
-      get() {
-        const headers = req.headers;
-        const body = req.method === "GET" || req.method === "HEAD" ? void 0 : req.socket ? req : new ReadableStream({
-          start(controller) {
-            req.on("data", (chunk) => controller.enqueue(chunk));
-            req.on("end", () => controller.close());
-            req.on("error", (err) => controller.error(err));
-          }
-        });
-        const request = new Request(url, {
-          method: req.method,
-          headers,
-          body,
-          duplex: "half"
-        });
-        Object.defineProperty(this, "request", {
-          value: request,
-          enumerable: true,
-          configurable: true
-        });
-        return request;
-      },
-      enumerable: true,
-      configurable: true
     });
-    const response = await router(requestContext);
     if (!response) {
       if (next) {
         next();
@@ -250,8 +233,8 @@ async function createDevServer(configFile) {
   });
   const middleware = createViteDevMiddleware(
     devServer,
-    async () => (await devServer.ssrLoadModule("@marko/run/router")).router,
-    createMiddleware
+    async () => await devServer.ssrLoadModule("@marko/run/router"),
+    (module2) => createMiddleware(module2.fetch)
   );
   return devServer.middlewares.use(middleware);
 }
@@ -347,8 +330,8 @@ function adapter() {
         });
       });
     },
-    async startPreview(dir, entry, port, envFile) {
-      const server = await spawnServer(`node ${entry}`, port, envFile, dir);
+    async startPreview(_dir, entry, port, envFile) {
+      const server = await spawnServer(`node ${entry}`, port, envFile);
       console.log(`Preview server started: http://localhost:${server.port}`);
     }
   };

package/dist/adapter/index.js

@@ -62,7 +62,7 @@ function getOrigin(req, protocol, host, trustProxy) {
   }
   return `${protocol}://${host}`;
 }
-function createMiddleware(router, options = {}) {
+function createMiddleware(fetch2, options = {}) {
   const { trustProxy = process.env.TRUST_PROXY === "1" } = options;
   let { origin = process.env.ORIGIN } = options;
   let protocol;
@@ -75,45 +75,28 @@ function createMiddleware(router, options = {}) {
     origin ?? (origin = getOrigin(req, protocol, host, trustProxy));
     const url = new URL(req.url, origin);
     const ip = req.ip || trustProxy && getForwardedHeader(req, "for") || req.socket.remoteAddress || "";
-    const requestContext = {
+    const headers = req.headers;
+    const body = req.method === "GET" || req.method === "HEAD" ? void 0 : req.socket ? req : new ReadableStream({
+      start(controller) {
+        req.on("data", (chunk) => controller.enqueue(chunk));
+        req.on("end", () => controller.close());
+        req.on("error", (err) => controller.error(err));
+      }
+    });
+    const request = new Request(url, {
       method: req.method,
-      url,
-      platform: {
-        ip,
-        request: req,
-        response: res,
-        setCookie(cookie) {
-          res.appendHeader("set-cookie", cookie);
-        }
+      headers,
+      body,
+      duplex: "half"
+    });
+    const response = await fetch2(request, {
+      ip,
+      request: req,
+      response: res,
+      setCookie(cookie) {
+        res.appendHeader("set-cookie", cookie);
       }
-    };
-    Object.defineProperty(requestContext, "request", {
-      get() {
-        const headers = req.headers;
-        const body = req.method === "GET" || req.method === "HEAD" ? void 0 : req.socket ? req : new ReadableStream({
-          start(controller) {
-            req.on("data", (chunk) => controller.enqueue(chunk));
-            req.on("end", () => controller.close());
-            req.on("error", (err) => controller.error(err));
-          }
-        });
-        const request = new Request(url, {
-          method: req.method,
-          headers,
-          body,
-          duplex: "half"
-        });
-        Object.defineProperty(this, "request", {
-          value: request,
-          enumerable: true,
-          configurable: true
-        });
-        return request;
-      },
-      enumerable: true,
-      configurable: true
     });
-    const response = await router(requestContext);
     if (!response) {
       if (next) {
         next();
@@ -218,8 +201,8 @@ async function createDevServer(configFile) {
   });
   const middleware = createViteDevMiddleware(
     devServer,
-    async () => (await devServer.ssrLoadModule("@marko/run/router")).router,
-    createMiddleware
+    async () => await devServer.ssrLoadModule("@marko/run/router"),
+    (module) => createMiddleware(module.fetch)
   );
   return devServer.middlewares.use(middleware);
 }
@@ -314,8 +297,8 @@ function adapter() {
         });
       });
     },
-    async startPreview(dir, entry, port, envFile) {
-      const server = await spawnServer(`node ${entry}`, port, envFile, dir);
+    async startPreview(_dir, entry, port, envFile) {
+      const server = await spawnServer(`node ${entry}`, port, envFile);
       console.log(`Preview server started: http://localhost:${server.port}`);
     }
   };

package/dist/adapter/middleware.cjs

@@ -20,7 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/adapter/middleware.ts
 var middleware_exports = {};
 __export(middleware_exports, {
-  default: () => createMiddleware,
+  createMiddleware: () => createMiddleware,
   getOrigin: () => getOrigin
 });
 module.exports = __toCommonJS(middleware_exports);
@@ -82,7 +82,7 @@ function getOrigin(req, protocol, host, trustProxy) {
   }
   return `${protocol}://${host}`;
 }
-function createMiddleware(router, options = {}) {
+function createMiddleware(fetch2, options = {}) {
   const { trustProxy = process.env.TRUST_PROXY === "1" } = options;
   let { origin = process.env.ORIGIN } = options;
   let protocol;
@@ -95,45 +95,28 @@ function createMiddleware(router, options = {}) {
     origin ?? (origin = getOrigin(req, protocol, host, trustProxy));
     const url = new URL(req.url, origin);
     const ip = req.ip || trustProxy && getForwardedHeader(req, "for") || req.socket.remoteAddress || "";
-    const requestContext = {
+    const headers = req.headers;
+    const body = req.method === "GET" || req.method === "HEAD" ? void 0 : req.socket ? req : new ReadableStream({
+      start(controller) {
+        req.on("data", (chunk) => controller.enqueue(chunk));
+        req.on("end", () => controller.close());
+        req.on("error", (err) => controller.error(err));
+      }
+    });
+    const request = new Request(url, {
       method: req.method,
-      url,
-      platform: {
-        ip,
-        request: req,
-        response: res,
-        setCookie(cookie) {
-          res.appendHeader("set-cookie", cookie);
-        }
+      headers,
+      body,
+      duplex: "half"
+    });
+    const response = await fetch2(request, {
+      ip,
+      request: req,
+      response: res,
+      setCookie(cookie) {
+        res.appendHeader("set-cookie", cookie);
       }
-    };
-    Object.defineProperty(requestContext, "request", {
-      get() {
-        const headers = req.headers;
-        const body = req.method === "GET" || req.method === "HEAD" ? void 0 : req.socket ? req : new ReadableStream({
-          start(controller) {
-            req.on("data", (chunk) => controller.enqueue(chunk));
-            req.on("end", () => controller.close());
-            req.on("error", (err) => controller.error(err));
-          }
-        });
-        const request = new Request(url, {
-          method: req.method,
-          headers,
-          body,
-          duplex: "half"
-        });
-        Object.defineProperty(this, "request", {
-          value: request,
-          enumerable: true,
-          configurable: true
-        });
-        return request;
-      },
-      enumerable: true,
-      configurable: true
     });
-    const response = await router(requestContext);
     if (!response) {
       if (next) {
         next();
@@ -211,5 +194,6 @@ function createMiddleware(router, options = {}) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createMiddleware,
   getOrigin
 });

package/dist/adapter/middleware.d.ts

@@ -1,4 +1,4 @@
-import type { Router } from "../runtime";
+import type { Fetch } from "../runtime";
 import type { IncomingMessage, ServerResponse } from "http";
 declare module "net" {
     interface Socket {
@@ -52,4 +52,4 @@ export declare function getOrigin(req: IncomingMessage, protocol?: string, host?
  * Creates a request handler to be passed to http.createServer() or used as a
  * middleware in Connect-style frameworks like Express.
  */
-export default function createMiddleware(router: Router<NodePlatformInfo>, options?: NodeAdapterOptions): NodeMiddleware;
+export declare function createMiddleware(fetch: Fetch<NodePlatformInfo>, options?: NodeAdapterOptions): NodeMiddleware;

package/dist/adapter/middleware.js

@@ -55,7 +55,7 @@ function getOrigin(req, protocol, host, trustProxy) {
   }
   return `${protocol}://${host}`;
 }
-function createMiddleware(router, options = {}) {
+function createMiddleware(fetch2, options = {}) {
   const { trustProxy = process.env.TRUST_PROXY === "1" } = options;
   let { origin = process.env.ORIGIN } = options;
   let protocol;
@@ -68,45 +68,28 @@ function createMiddleware(router, options = {}) {
     origin ?? (origin = getOrigin(req, protocol, host, trustProxy));
     const url = new URL(req.url, origin);
     const ip = req.ip || trustProxy && getForwardedHeader(req, "for") || req.socket.remoteAddress || "";
-    const requestContext = {
+    const headers = req.headers;
+    const body = req.method === "GET" || req.method === "HEAD" ? void 0 : req.socket ? req : new ReadableStream({
+      start(controller) {
+        req.on("data", (chunk) => controller.enqueue(chunk));
+        req.on("end", () => controller.close());
+        req.on("error", (err) => controller.error(err));
+      }
+    });
+    const request = new Request(url, {
       method: req.method,
-      url,
-      platform: {
-        ip,
-        request: req,
-        response: res,
-        setCookie(cookie) {
-          res.appendHeader("set-cookie", cookie);
-        }
+      headers,
+      body,
+      duplex: "half"
+    });
+    const response = await fetch2(request, {
+      ip,
+      request: req,
+      response: res,
+      setCookie(cookie) {
+        res.appendHeader("set-cookie", cookie);
       }
-    };
-    Object.defineProperty(requestContext, "request", {
-      get() {
-        const headers = req.headers;
-        const body = req.method === "GET" || req.method === "HEAD" ? void 0 : req.socket ? req : new ReadableStream({
-          start(controller) {
-            req.on("data", (chunk) => controller.enqueue(chunk));
-            req.on("end", () => controller.close());
-            req.on("error", (err) => controller.error(err));
-          }
-        });
-        const request = new Request(url, {
-          method: req.method,
-          headers,
-          body,
-          duplex: "half"
-        });
-        Object.defineProperty(this, "request", {
-          value: request,
-          enumerable: true,
-          configurable: true
-        });
-        return request;
-      },
-      enumerable: true,
-      configurable: true
     });
-    const response = await router(requestContext);
     if (!response) {
       if (next) {
         next();
@@ -183,6 +166,6 @@ function createMiddleware(router, options = {}) {
   };
 }
 export {
-  createMiddleware as default,
+  createMiddleware,
   getOrigin
 };

package/dist/runtime/index.d.ts

@@ -1,11 +1,15 @@
 import type { HandlerLike, ParamsObject, Route, RouteContext } from "./types";
 declare global {
     namespace Marko {
-        interface Global {
-            context: RouteContext;
+        interface Global extends MarkoRun.CurrentContext {
+        }
+        interface Out {
+            global: Global;
         }
     }
     namespace MarkoRun {
+        const NotHandled: symbol;
+        const NotMatched: symbol;
         interface CurrentRoute extends Route {
         }
         interface CurrentContext extends RouteContext<CurrentRoute> {
@@ -14,4 +18,4 @@ declare global {
         function route<Params extends ParamsObject = {}, Meta = unknown>(handler: Handler<Params, Meta>): typeof handler;
     }
 }
-export type { HandlerLike, InputObject, InvokeRoute, MatchRoute, NextFunction, PathTemplate, RequestContext, Route, RouteContext, RouteContextExtensions, RouteHandler, RouteWithHandler, Router, ValidateHref, ValidatePath, } from "./types";
+export type { Fetch, HandlerLike, InputObject, Invoke, Match, NextFunction, PathTemplate, Route, RouteContext, RouteContextExtensions, RouteHandler, RouteWithHandler, RuntimeModule, ValidateHref, ValidatePath, } from "./types";

package/dist/runtime/internal.cjs

@@ -20,8 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/runtime/internal.ts
 var internal_exports = {};
 __export(internal_exports, {
-  RequestNotHandled: () => RequestNotHandled,
-  RequestNotMatched: () => RequestNotMatched,
+  NotHandled: () => NotHandled,
+  NotMatched: () => NotMatched,
   call: () => call,
   compose: () => compose,
   createInput: () => createInput,
@@ -31,17 +31,20 @@ __export(internal_exports, {
   notMatched: () => notMatched
 });
 module.exports = __toCommonJS(internal_exports);
-globalThis.MarkoRun ?? (globalThis.MarkoRun = {});
-globalThis.MarkoRun.route = (handler) => handler;
-var RequestNotHandled = Symbol();
-var RequestNotMatched = Symbol();
+var NotHandled = Symbol();
+var NotMatched = Symbol();
+globalThis.MarkoRun ?? (globalThis.MarkoRun = {
+  NotHandled,
+  NotMatched,
+  route(handler) {
+    return handler;
+  }
+});
 function createInput(context) {
   let existing;
   return (data) => {
     existing ?? (existing = {
-      $global: {
-        context
-      }
+      $global: context
     });
     return data ? Object.assign(existing, data) : existing;
   };
@@ -78,7 +81,7 @@ async function call(handler, next, context) {
       response = await handler(context, next);
     } catch (error) {
       if (error == null) {
-        throw RequestNotHandled;
+        throw NotHandled;
       } else if (error instanceof Response) {
         return error;
       }
@@ -86,7 +89,7 @@ async function call(handler, next, context) {
     }
   }
   if (response === null) {
-    throw RequestNotMatched;
+    throw NotMatched;
   }
   return response || next();
 }
@@ -136,8 +139,8 @@ function notMatched() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  RequestNotHandled,
-  RequestNotMatched,
+  NotHandled,
+  NotMatched,
   call,
   compose,
   createInput,

package/dist/runtime/internal.d.ts

@@ -1,6 +1,6 @@
 import type { InputObject, NextFunction, Route, RouteContext, RouteHandler } from "./types";
-export declare const RequestNotHandled: unique symbol;
-export declare const RequestNotMatched: unique symbol;
+export declare const NotHandled: unique symbol;
+export declare const NotMatched: unique symbol;
 export declare function createInput(context: RouteContext): (data: InputObject) => InputObject;
 export declare function call(handler: RouteHandler<Route>, next: NextFunction, context: RouteContext): Promise<Response>;
 export declare function compose(handlers: RouteHandler[]): RouteHandler;