primate 0.10.0 → 0.11.0

package/README.md

@@ -25,6 +25,7 @@ Add `{"type": "module"}` to your `package.json` and run `npx primate`.
 - [Routing](#routing)
   - [Basic](#basic)
   - [The request object](#the-request-object)
+  - [Accessing the request body](#accessing-the-request-body)
   - [Regular expressions](#regular-expressions)
   - [Named groups](#named-groups)
   - [Aliasing](#aliasing)
@@ -112,18 +113,16 @@ export default router => {
 
 Routes map requests to responses. They are loaded from `routes`.
 
-The order in which routes are declared is irrelevant. Redeclaring a route
-(same pathname and same HTTP verb) throws an error.
-
 ### Basic
 
-```js
-import html from "@primate/html";
+To start serving content, create a file in `routes` returning a function as its
+default export. This function has a `router` param used to configure HTTP
+routes.
 
+```js
 export default router => {
-  // accessing /site/login will serve the contents of
-  // `components/site-login.html` as HTML
-  router.get("/site/login", () => html`<site-login />`);
+  // accessing /site/login will serve the `Hello, world!` as plain text
+  router.get("/site/login", () => "Hello, world!");
 };
 
 ```

package/README.template.md

@@ -10,7 +10,7 @@ Create a route in `routes/hello.js`
 // getting-started/hello.js
 ```
 
-Add `{"type": "module"}` to your `package.json` and run `npx primate`.
+Add `{"type": "module"}` to your `package.json` and run `npx primate -y`.
 
 ## Table of Contents
 
@@ -22,10 +22,12 @@ Add `{"type": "module"}` to your `package.json` and run `npx primate`.
 - [Routing](#routing)
   - [Basic](#basic)
   - [The request object](#the-request-object)
+  - [Accessing the request body](#accessing-the-request-body)
   - [Regular expressions](#regular-expressions)
   - [Named groups](#named-groups)
   - [Aliasing](#aliasing)
   - [Sharing logic across requests](#sharing-logic-across-requests)
+- [Modules](#modules)
 - [Data persistance](#data-persistance)
   - [Short field notation](#short-field-notation)
   - [Predicates](#predicates)
@@ -70,9 +72,6 @@ Serve the component in your route
 
 Routes map requests to responses. They are loaded from `routes`.
 
-The order in which routes are declared is irrelevant. Redeclaring a route
-(same pathname and same HTTP verb) throws an error.
-
 ### Basic
 
 ```js
@@ -85,6 +84,17 @@ The order in which routes are declared is irrelevant. Redeclaring a route
 // routing/the-request-object.js
 ```
 
+### Accessing the request body
+
+For requests containing a body, Primate will attempt parsing the body according
+to the content type sent along the request. Currently supported are
+`application/x-www-form-urlencoded` (typically for form submission) and
+`application/json`.
+
+```js
+// routing/accessing-the-request-body.js
+```
+
 ### Regular expressions
 
 ```js
@@ -109,6 +119,37 @@ The order in which routes are declared is irrelevant. Redeclaring a route
 // routing/sharing-logic-across-requests.js
 ```
 
+### Modules
+
+Primate has optional additional modules published separately that enrich the
+core framework with functionality for common use cases.
+
+To add modules, create a `primate.js` configuration file in your project's
+root. This file exports a default export used to extend the framework.
+
+```js
+// modules/configure.js
+```
+
+#### Data
+
+Run `npm i @primate/domains` to install the data domains module, used for
+data persistance.
+
+Import and initialize this module in your configuration file
+
+```js
+// modules/domains/configure.js
+```
+
+#### Sessions
+
+The module `@primate/sessions` is used to maintain user sessions.
+
+
+
+#### Databases
+
 ## Data persistance 
 
 Primate domains (via [`@primate/domains`][primate-domains]) represent a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primate",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "author": "Terrablue <terrablue@proton.me>",
   "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",
@@ -15,7 +15,7 @@
     "@babel/core": "^7.21.0",
     "@babel/eslint-parser": "^7.19.1",
     "@babel/plugin-syntax-import-assertions": "^7.20.0",
-    "eslint": "^8.34.0",
+    "eslint": "^8.36.0",
     "eslint-plugin-json": "^3.1.0"
   },
   "scripts": {

package/readme/modules/configure.js

@@ -0,0 +1,3 @@
+export default {
+  modules: [],
+};

package/readme/modules/domains/configure.js

@@ -0,0 +1,5 @@
+import domains from "@primate/domains";
+
+export default {
+  modules: [domains()],
+};

package/readme/routing/accessing-the-request-body.js

@@ -0,0 +1,3 @@
+export default router => {
+  router.post("/site/login", ({body}) => `submitted user: ${body.username}`);
+};

package/readme/routing/basic.js

@@ -1,7 +1,4 @@
-import html from "@primate/html";
-
 export default router => {
-  // accessing /site/login will serve the contents of
-  // `components/site-login.html` as HTML
-  router.get("/site/login", () => html`<site-login />`);
+  // accessing /site/login will serve the `Hello, world!` as plain text
+  router.get("/site/login", () => "Hello, world!");
 };

package/src/bundle.js

@@ -1,8 +1,7 @@
 import {File} from "runtime-compat/filesystem";
 
-export default async conf => {
-  const {paths} = conf;
-
+export default async env => {
+  const {paths} = env;
   if (await paths.static.exists) {
     // remove public directory in case exists
     if (await paths.public.exists) {

package/src/conf.js

@@ -2,7 +2,9 @@ import {Path} from "runtime-compat/filesystem";
 import {EagerEither} from "runtime-compat/functional";
 import cache from "./cache.js";
 import extend from "./extend.js";
-import preset from "./preset/primate.js";
+import preset from "./preset/primate.conf.js";
+import log from "./log.js";
+import package_json from "../package.json" assert {type: "json"};
 
 const qualify = (root, paths) =>
   Object.keys(paths).reduce((sofar, key) => {
@@ -13,15 +15,16 @@ const qualify = (root, paths) =>
     return sofar;
   }, {});
 
-export default async (filename = "primate.js") => {
+export default async (filename = "primate.conf.js") => {
   const root = Path.resolve();
   const conffile = root.join(filename);
   const conf = await EagerEither
     .try(async () => extend(preset, (await import(conffile)).default))
     .match({left: () => preset})
     .get();
-  const paths = qualify(root, conf.paths);
-  return cache("conf", filename, () => {
-    return {...conf, paths, root};
-  });
+
+  const temp = {...conf, ...log, paths: qualify(root, conf.paths), root};
+  temp.info(`primate \x1b[34m${package_json.version}\x1b[0m`);
+  const modules = await Promise.all(conf.modules.map(module => module(temp)));
+  return cache("conf", filename, () => ({...temp, modules}));
 };

package/src/handlers/http404.js

@@ -1,7 +1,4 @@
-const response = {
-  body: "Page not found",
+export default () => () => ["Page not found", {
   status: 404,
   headers: {"Content-Type": "text/html"},
-};
-
-export default () => () => ({...response});
+}];

package/src/handlers/json.js

@@ -1,7 +1,4 @@
-const response = {
+export default (_, ...keys) => async () => [JSON.stringify(await keys[0]), {
   status: 200,
   headers: {"Content-Type": "application/json"},
-};
-
-export default (strings, ...keys) => async () =>
-  ({...response, body: JSON.stringify(await keys[0])});
+}];

package/src/handlers/stream.js

@@ -1,7 +1,4 @@
-const response = {
+export default (_, ...keys) => async () => [await keys[0], {
   status: 200,
   headers: {"Content-Type": "application/octet-stream"},
-};
-
-export default (strings, ...keys) => async () =>
-  ({...response, body: await keys[0]});
+}];

package/src/handlers/text.js

@@ -1,8 +1,4 @@
 const last = -1;
-const response = {
-  status: 200,
-  headers: {"Content-Type": "text/plain"},
-};
 
 export default (strings, ...keys) => async () => {
   const awaitedKeys = await Promise.all(keys);
@@ -10,5 +6,6 @@ export default (strings, ...keys) => async () => {
     .slice(0, last)
     .map((string, i) => string + awaitedKeys[i])
     .join("") + strings[strings.length + last];
-  return {...response, body};
+
+  return [body, {status: 200, headers: {"Content-Type": "text/plain"}}];
 };

package/src/log.js

@@ -19,4 +19,8 @@ const log = new Proxy(Log, {
     log.paint(colors[property] ?? reset, message).paint(reset, " ")),
 });
 
-export default log;
+export default {
+  info: (...args) => log.green("[info]").reset(...args).nl(),
+  warn: (...args) => log.yellow("[warn]").reset(...args).nl(),
+  error: (...args) => log.red("[error]").reset(...args).nl(),
+};

package/src/preset/{primate.js → primate.conf.js}

@@ -18,4 +18,5 @@ export default {
     routes: "routes",
     components: "components",
   },
+  modules: [],
 };

package/src/route.js

@@ -1,14 +1,18 @@
 import {ReadableStream} from "runtime-compat/streams";
 import {Path, File} from "runtime-compat/filesystem";
 import {is} from "runtime-compat/dyndef";
-import {http404} from "./handlers/http.js";
 import text from "./handlers/text.js";
 import json from "./handlers/json.js";
 import stream from "./handlers/stream.js";
 import RouteError from "./errors/Route.js";
 
-const isText = value => typeof value === "string" ? text`${value}` : http404``;
-const isObject = value => typeof value === "object" && value !== null 
+const isText = value => {
+  if (typeof value === "string") {
+    return text`${value}`;
+  }
+  throw new RouteError(`no handler found for ${value}`);
+};
+const isObject = value => typeof value === "object" && value !== null
   ? json`${value}` : isText(value);
 const isStream = value => value instanceof ReadableStream
   ? stream`${value}` : isObject(value);
@@ -48,7 +52,9 @@ export default async definitions => {
       const url = new URL(`https://primatejs.com${request.pathname}`);
       const {pathname, searchParams} = url;
       const params = Object.fromEntries(searchParams);
-      const verb = find(method, pathname, {handler: () => http404``});
+      const verb = find(method, pathname, {handler: () => {
+        throw new RouteError(`no ${method.toUpperCase()} route to ${pathname}`);
+      }});
       const path = pathname.split("/").filter(part => part !== "");
       const named = verb.path?.exec(pathname)?.groups ?? {};
 

package/src/run.js

@@ -1,22 +1,13 @@
 import serve from "./serve.js";
 import route from "./route.js";
 import bundle from "./bundle.js";
-import package_json from "../package.json" assert {type: "json"};
-import log from "./log.js";
 
 const extract = (modules, key) => modules.flatMap(module => module[key] ?? []);
 
-export default async conf => {
-  log.reset("Primate").yellow(package_json.version);
-
-  const {paths} = conf;
+export default async env => {
+  const {paths} = env;
   const router = await route(paths.routes);
-  await bundle(conf);
+  await bundle(env);
 
-  await serve({router,
-    paths: conf.paths,
-    from: conf.paths.public,
-    http: conf.http,
-    modules: extract(conf.modules ?? [], "serve"),
-  });
+  await serve({router, ...env, modules: extract(env.modules ?? [], "serve")});
 };

package/src/serve.js

@@ -3,7 +3,6 @@ import {serve, Response} from "runtime-compat/http";
 import statuses from "./http-statuses.json" assert {type: "json"};
 import mimes from "./mimes.json" assert {type: "json"};
 import {http404} from "./handlers/http.js";
-import log from "./log.js";
 
 const regex = /\.([a-z1-9]*)$/u;
 const mime = filename => mimes[filename.match(regex)[1]] ?? mimes.binary;
@@ -15,25 +14,23 @@ const contents = {
   "application/json": body => JSON.parse(body),
 };
 
-export default conf => {
+export default env => {
   const route = async request => {
     let result;
+    const csp = Object.keys(env.http.csp).reduce((policy_string, key) =>
+      `${policy_string}${key} ${env.http.csp[key]};`, "");
+    const headers = {
+      "Content-Security-Policy": csp,
+      "Referrer-Policy": "same-origin",
+    };
+
     try {
-      result = await (await conf.router.process(request))(conf);
+      result = await (await env.router.process(request))(env, headers);
     } catch (error) {
-      console.log(error);
-      result = http404()``;
+      env.error(error.message);
+      result = http404(env, headers)``;
     }
-    const csp = Object.keys(conf.http.csp).reduce((policy_string, key) =>
-      `${policy_string}${key} ${conf.http.csp[key]};`, "");
-    return new Response(result.body, {
-      status: result.status,
-      headers: {
-        ...result.headers,
-        "Content-Security-Policy": csp,
-        "Referrer-Policy": "same-origin",
-      },
-    });
+    return new Response(...result);
   };
 
   const resource = async file => new Response(file.readable, {
@@ -45,7 +42,7 @@ export default conf => {
   });
 
   const _serve = async request => {
-    const path = new Path(conf.from, request.pathname);
+    const path = new Path(env.paths.public, request.pathname);
     return await path.isFile ? resource(path.file) : route(request);
   };
 
@@ -53,7 +50,7 @@ export default conf => {
     try {
       return await _serve(request);
     } catch (error) {
-      console.log(error);
+      env.error(error.message);
       return new Response(null, {status: statuses.InternalServerError});
     }
   };
@@ -63,7 +60,7 @@ export default conf => {
     return type === undefined ? body : type(body);
   };
 
-  const {http, modules} = conf;
+  const {http, modules} = env;
 
   // handle is the last module to be executed
   const handlers = [...modules, handle].reduceRight((acc, handler) =>
@@ -87,8 +84,8 @@ export default conf => {
 
     const {pathname, search} = new URL(`https://example.com${request.url}`);
 
-    return await handlers({original: request, pathname: pathname + search, body});
+    return handlers({original: request, pathname: pathname + search, body});
   }, http);
 
-  log.reset("on").yellow(`${http.host}:${http.port}`).nl();
+  env.info(`running on ${http.host}:${http.port}`);
 };