primate 0.9.2 → 0.10.0

package/README.md

@@ -15,6 +15,24 @@ export default router => {
 
 Add `{"type": "module"}` to your `package.json` and run `npx primate`.
 
+## Table of Contents
+
+- [Serving content](#serving-content)
+  - [Plain text](#plain-text)
+  - [JSON](#json)
+  - [Streams](#streams)
+  - [HTML](#html)
+- [Routing](#routing)
+  - [Basic](#basic)
+  - [The request object](#the-request-object)
+  - [Regular expressions](#regular-expressions)
+  - [Named groups](#named-groups)
+  - [Aliasing](#aliasing)
+  - [Sharing logic across requests](#sharing-logic-across-requests)
+- [Data persistance](#data-persistance)
+  - [Short field notation](#short-field-notation)
+  - [Predicates](#predicates)
+
 ## Serving content
 
 Create a file in `routes` that exports a default function
@@ -97,7 +115,7 @@ 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 GET route
+### Basic
 
 ```js
 import html from "@primate/html";
@@ -110,7 +128,7 @@ export default router => {
 
 ```
 
-### Working with the request path
+### The request object
 
 ```js
 export default router => {
@@ -162,7 +180,7 @@ export default router => {
 
 ```
 
-### Sharing logic across HTTP verbs
+### Sharing logic across requests
 
 ```js
 import html from "@primate/html";
@@ -186,19 +204,15 @@ export default router => {
 
 ```
 
-## Domains
-
-Domains represent a collection in a store, primarily with the class `fields`
-property.
+## Data persistance 
 
-### Fields
-
-Field types delimit acceptable values for a field.
+Primate domains (via [`@primate/domains`][primate-domains]) represent a
+collection in a store using the class `fields` property.
 
 ```js
 import {Domain} from "@primate/domains";
 
-// A basic domain that contains two string properies
+// A basic domain that contains two properies
 export default class User extends Domain {
   static fields = {
     // a user's name must be a string
@@ -211,9 +225,9 @@ export default class User extends Domain {
 
 ```
 
-### Short notation
+### Short field notation
 
-Field types may be any constructible JavaScript object, including other
+Value types may be any constructible JavaScript object, including other
 domains. When using other domains as types, data integrity (on saving) is
 ensured.
 
@@ -265,3 +279,5 @@ export default class User extends Domain {
 ## License
 
 MIT
+
+[primate-domains]: https://github.com/primatejs/primate-domains

package/README.template.md

@@ -12,6 +12,24 @@ Create a route in `routes/hello.js`
 
 Add `{"type": "module"}` to your `package.json` and run `npx primate`.
 
+## Table of Contents
+
+- [Serving content](#serving-content)
+  - [Plain text](#plain-text)
+  - [JSON](#json)
+  - [Streams](#streams)
+  - [HTML](#html)
+- [Routing](#routing)
+  - [Basic](#basic)
+  - [The request object](#the-request-object)
+  - [Regular expressions](#regular-expressions)
+  - [Named groups](#named-groups)
+  - [Aliasing](#aliasing)
+  - [Sharing logic across requests](#sharing-logic-across-requests)
+- [Data persistance](#data-persistance)
+  - [Short field notation](#short-field-notation)
+  - [Predicates](#predicates)
+
 ## Serving content
 
 Create a file in `routes` that exports a default function
@@ -55,16 +73,16 @@ 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 GET route
+### Basic
 
 ```js
-// routing/basic-get-request.js
+// routing/basic.js
 ```
 
-### Working with the request path
+### The request object
 
 ```js
-// routing/working-with-the-request-path.js
+// routing/the-request-object.js
 ```
 
 ### Regular expressions
@@ -85,33 +103,29 @@ The order in which routes are declared is irrelevant. Redeclaring a route
 // routing/aliasing.js
 ```
 
-### Sharing logic across HTTP verbs
+### Sharing logic across requests
 
 ```js
-// routing/sharing-logic-across-http-verbs.js
+// routing/sharing-logic-across-requests.js
 ```
 
-## Domains
-
-Domains represent a collection in a store, primarily with the class `fields`
-property.
+## Data persistance 
 
-### Fields
-
-Field types delimit acceptable values for a field.
+Primate domains (via [`@primate/domains`][primate-domains]) represent a
+collection in a store using the class `fields` property.
 
 ```js
 // domains/fields.js
 ```
 
-### Short notation
+### Short field notation
 
-Field types may be any constructible JavaScript object, including other
+Value types may be any constructible JavaScript object, including other
 domains. When using other domains as types, data integrity (on saving) is
 ensured.
 
 ```js
-// domains/short-notation.js
+// domains/short-field-notation.js
 ```
 
 ### Predicates
@@ -131,3 +145,5 @@ aside from the type.
 ## License
 
 MIT
+
+[primate-domains]: https://github.com/primatejs/primate-domains

package/bin/primate.js

@@ -2,4 +2,4 @@
 
 import conf from "../src/conf.js";
 import run from "../src/run.js";
-await run(conf());
+await run(await conf());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primate",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "author": "Terrablue <terrablue@proton.me>",
   "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",
@@ -12,14 +12,14 @@
   },
   "bin": "bin/primate.js",
   "devDependencies": {
-    "@babel/core": "^7.20.12",
+    "@babel/core": "^7.21.0",
     "@babel/eslint-parser": "^7.19.1",
     "@babel/plugin-syntax-import-assertions": "^7.20.0",
-    "eslint": "^8.33.0",
+    "eslint": "^8.34.0",
     "eslint-plugin-json": "^3.1.0"
   },
   "scripts": {
-    "docs": "npx embedme --source-root examples --strip-embed-comment --stdout README.template.md > README.md"
+    "docs": "npx -y embedme --source-root readme --strip-embed-comment --stdout README.template.md > README.md"
   },
   "type": "module",
   "exports": "./exports.js",

package/readme/components/edit-user-for.html

@@ -0,0 +1,10 @@
+<form for="${user}" method="post">
+  <h1>Edit user</h1>
+  <p>
+    <input name="name" value="${name}" />
+  </p>
+  <p>
+    <input name="email" value="${email}" />
+  </p>
+  <input type="submit" value="Save user" />
+</form>

package/readme/components/edit-user.html

@@ -0,0 +1,10 @@
+<form method="post">
+  <h1>Edit user</h1>
+  <p>
+    <input name="name" value="${user.name}"></textarea>
+  </p>
+  <p>
+    <input name="email" value="${user.email}"></textarea>
+  </p>
+  <input type="submit" value="Save user" />
+</form>

package/readme/components/user-index.html

@@ -0,0 +1,4 @@
+<div for="${users}">
+  User ${name}.
+  Email ${email}.
+</div>

package/readme/components/users.html

@@ -0,0 +1,4 @@
+<div for="${users}">
+  User ${name}.
+  Email ${email}.
+</div>

package/readme/domains/fields.js

@@ -0,0 +1,12 @@
+import {Domain} from "@primate/domains";
+
+// A basic domain that contains two properies
+export default class User extends Domain {
+  static fields = {
+    // a user's name must be a string
+    name: String,
+    // a user's age must be a number
+    age: Number,
+  };
+}
+

package/readme/domains/predicates.js

@@ -0,0 +1,14 @@
+import {Domain} from "@primate/domains";
+import House from "./House.js";
+
+export default class User extends Domain {
+  static fields = {
+    // a user's name must be a string and unique across the user collection
+    name: [String, "unique"],
+    // a user's age must be a positive integer
+    age: [Number, "integer", "positive"],
+    // a user's house must have the foreign id of a house record and no two
+    // users may have the same house
+    house_id: [House, "unique"],
+  };
+}

package/readme/domains/short-field-notation.js

@@ -0,0 +1,13 @@
+import {Domain} from "@primate/domains";
+import House from "./House.js";
+
+export default class User extends Domain {
+  static fields = {
+    // a user's name must be a string
+    name: String,
+    // a user's age must be a number
+    age: Number,
+    // a user's house must have the foreign id of a house record
+    house_id: House,
+  };
+}

package/readme/getting-started/generate-ssl.sh

@@ -0,0 +1 @@
+openssl req -x509 -out ssl/default.crt -keyout ssl/default.key -newkey rsa:2048 -nodes -sha256 -batch

package/readme/getting-started/hello.js

@@ -0,0 +1,3 @@
+export default router => {
+  router.get("/", () => "Hello, world!");
+};

package/readme/getting-started/lay-out-app.sh

@@ -0,0 +1 @@
+mkdir -p app/{routes,components,ssl} && cd app

package/readme/getting-started/site-index.html

@@ -0,0 +1 @@
+Today's date is ${date}.

package/readme/getting-started/site.js

@@ -0,0 +1,3 @@
+export default router => {
+  router.get("/", () => "Hello, world!");
+};

package/readme/routing/aliasing.js

@@ -0,0 +1,14 @@
+export default router => {
+  // will replace `"_id"` in any path with `"([0-9])+"`
+  router.alias("_id", "([0-9])+");
+
+  // equivalent to `router.get("/user/view/([0-9])+", ...)`
+  // will return id if matched, 404 otherwise
+  router.get("/user/view/_id", request => request.path[2]);
+
+  // can be combined with named groups
+  router.alias("_name", "(?<name>[a-z])+");
+
+  // will return name if matched, 404 otherwise
+  router.get("/user/view/_name", request => request.named.name);
+};

package/readme/routing/basic.js

@@ -0,0 +1,7 @@
+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 />`);
+};

package/readme/routing/named-groups.js

@@ -0,0 +1,5 @@
+export default router => {
+  // named groups are mapped to properties of `request.named`
+  // accessing /user/view/1234 will serve `1234` as plain text
+  router.get("/user/view/(?<_id>[0-9])+", ({named}) => named._id);
+};

package/readme/routing/regular-expressions.js

@@ -0,0 +1,5 @@
+export default router => {
+  // accessing /user/view/1234 will serve `1234` as plain text
+  // accessing /user/view/abcd will show a 404 error
+  router.get("/user/view/([0-9])+", request => request[2]);
+};

package/readme/routing/sharing-logic-across-requests.js

@@ -0,0 +1,18 @@
+import html from "@primate/html";
+import redirect from "@primate/redirect";
+
+export default router => {
+  // declare `"edit-user"` as alias of `"/user/edit/([0-9])+"`
+  router.alias("edit-user", "/user/edit/([0-9])+");
+
+  // pass user instead of request to all verbs with this route
+  router.map("edit-user", () => ({name: "Donald"}));
+
+  // show user edit form
+  router.get("edit-user", user => html`<user-edit user="${user}" />`);
+
+  // verify form and save, or show errors
+  router.post("edit-user", async user => await user.save()
+    ? redirect`/users`
+    : html`<user-edit user="${user}" />`);
+};

package/readme/routing/the-request-object.js

@@ -0,0 +1,4 @@
+export default router => {
+  // accessing /site/login will serve `["site", "login"]` as JSON
+  router.get("/site/login", request => request.path);
+};

package/readme/serving-content/html.js

@@ -0,0 +1,13 @@
+import html from "@primate/html";
+
+export default router => {
+  // the HTML tagged template handler loads a component from the `components`
+  // directory and serves it as HTML, passing any given data as attributes
+  router.get("/users", () => {
+    const users = [
+      {name: "Donald", email: "donald@the.duck"},
+      {name: "Joe", email: "joe@was.absent"},
+    ];
+    return html`<user-index users="${users}" />`;
+  });
+};

package/readme/serving-content/json.js

@@ -0,0 +1,12 @@
+import {File} from "runtime-compat/filesystem";
+
+export default router => {
+  // any proper JavaScript object will be served as JSON
+  router.get("/users", () => [
+    {name: "Donald"},
+    {name: "Ryan"},
+  ]);
+
+  // load from a file and serve as JSON
+  router.get("/users-from-file", () => File.json("users.json"));
+};

package/readme/serving-content/plain-text.js

@@ -0,0 +1,4 @@
+export default router => {
+  // strings will be served as plain text
+  router.get("/user", () => "Donald");
+};

package/readme/serving-content/streams.js

@@ -0,0 +1,6 @@
+import {File} from "runtime-compat/filesystem";
+
+export default router => {
+  // `File` implements `readable`, which is a ReadableStream
+  router.get("/users", () => new File("users.json"));
+};

package/readme/serving-content/user-index.html

@@ -0,0 +1,4 @@
+<div for="${users}">
+  User ${name}.
+  Email ${email}.
+</div>

package/src/bundle.js

@@ -2,13 +2,13 @@ import {File} from "runtime-compat/filesystem";
 
 export default async conf => {
   const {paths} = conf;
-  // remove public directory in case exists
-  if (await paths.public.exists) {
-    await paths.public.file.remove();
-  }
-  await paths.public.file.create();
 
   if (await paths.static.exists) {
+    // remove public directory in case exists
+    if (await paths.public.exists) {
+      await paths.public.file.remove();
+    }
+    await paths.public.file.create();
     // copy static files to public
     await File.copy(paths.static, paths.public);
   }

package/src/conf.js

@@ -1,8 +1,8 @@
 import {Path} from "runtime-compat/filesystem";
-import {Either} from "runtime-compat/functional";
+import {EagerEither} from "runtime-compat/functional";
 import cache from "./cache.js";
 import extend from "./extend.js";
-import json from "./preset/primate.json" assert {type: "json"};
+import preset from "./preset/primate.js";
 
 const qualify = (root, paths) =>
   Object.keys(paths).reduce((sofar, key) => {
@@ -13,13 +13,15 @@ const qualify = (root, paths) =>
     return sofar;
   }, {});
 
-export default (filename = "primate.json") => cache("conf", filename, () => {
+export default async (filename = "primate.js") => {
   const root = Path.resolve();
-  const conf = Either
-    .try(() => extend(json, JSON.parse(root.join(filename).file.readSync())))
-    .match({left: () => json})
+  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 {...conf, paths, root};
-});
+  return cache("conf", filename, () => {
+    return {...conf, paths, root};
+  });
+};

package/src/handlers/http404.js

@@ -1,6 +1,6 @@
 const response = {
   body: "Page not found",
-  code: 404,
+  status: 404,
   headers: {"Content-Type": "text/html"},
 };
 

package/src/handlers/json.js

@@ -1,5 +1,5 @@
 const response = {
-  code: 200,
+  status: 200,
   headers: {"Content-Type": "application/json"},
 };
 

package/src/handlers/stream.js

@@ -1,5 +1,5 @@
 const response = {
-  code: 200,
+  status: 200,
   headers: {"Content-Type": "application/octet-stream"},
 };
 

package/src/handlers/text.js

@@ -1,8 +1,8 @@
 const last = -1;
 const response = {
-  code: 200,
+  status: 200,
   headers: {"Content-Type": "text/plain"},
-}
+};
 
 export default (strings, ...keys) => async () => {
   const awaitedKeys = await Promise.all(keys);

package/src/preset/primate.js

@@ -0,0 +1,21 @@
+export default {
+  base: "/",
+  debug: false,
+  http: {
+    host: "localhost",
+    port: 6161,
+    csp: {
+      "default-src": "'self'",
+      "object-src": "'none'",
+      "frame-ancestors": "'none'",
+      "form-action": "'self'",
+      "base-uri": "'self'",
+    },
+  },
+  paths: {
+    public: "public",
+    static: "static",
+    routes: "routes",
+    components: "components",
+  },
+};

package/src/route.js

@@ -16,6 +16,9 @@ const isFile = value => value instanceof File
   ? stream`${value}` : isStream(value);
 const guess = value => isFile(value);
 
+// insensitive-case equal
+const ieq = (left, right) => left.toLowerCase() === right.toLowerCase();
+
 export default async definitions => {
   const aliases = [];
   const routes = [];
@@ -33,7 +36,7 @@ export default async definitions => {
   };
   const find = (method, path, fallback = {handler: r => r}) =>
     routes.find(route =>
-      route.method === method && route.path.test(path)) ?? fallback;
+      ieq(route.method, method) && route.path.test(path)) ?? fallback;
 
   const router = {
     map: (path, callback) => add("map", path, callback),
@@ -41,7 +44,7 @@ export default async definitions => {
     post: (path, callback) => add("post", path, callback),
     alias: (key, value) => aliases.push({key, value}),
     process: async request => {
-      const {method} = request;
+      const {method} = request.original;
       const url = new URL(`https://primatejs.com${request.pathname}`);
       const {pathname, searchParams} = url;
       const params = Object.fromEntries(searchParams);

package/src/run.js

@@ -4,8 +4,11 @@ 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;
   const router = await route(paths.routes);
   await bundle(conf);
@@ -14,5 +17,6 @@ export default async conf => {
     paths: conf.paths,
     from: conf.paths.public,
     http: conf.http,
+    modules: extract(conf.modules ?? [], "serve"),
   });
 };

package/src/serve.js

@@ -1,6 +1,6 @@
 import {Path} from "runtime-compat/filesystem";
 import {serve, Response} from "runtime-compat/http";
-import codes from "./http-codes.json" assert {type: "json"};
+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";
@@ -8,83 +8,87 @@ import log from "./log.js";
 const regex = /\.([a-z1-9]*)$/u;
 const mime = filename => mimes[filename.match(regex)[1]] ?? mimes.binary;
 
-const Server = class Server {
-  constructor(conf) {
-    this.conf = conf;
-  }
-
-  async start() {
-    const {http} = this.conf;
-    const {csp, "same-site": same_site = "Strict"} = http;
-    this.csp = Object.keys(csp).reduce((policy_string, key) =>
-      `${policy_string}${key} ${csp[key]};`, "");
-
-    const decoder = new TextDecoder();
-    serve(async request => {
-      const reader = request.body.getReader();
-      const chunks = [];
-      let result;
-      do {
-        result = await reader.read();
-        if (result.value !== undefined) {
-          chunks.push(decoder.decode(result.value));
-        }
-      } while (!result.done);
-      const body = chunks.join();
-      const payload = Object.fromEntries(decodeURI(body).replaceAll("+", " ")
-        .split("&")
-        .map(part => part.split("=")));
-      const {pathname, search} = new URL(`https://example.com${request.url}`);
-      return this.try(pathname + search, request, payload);
-    }, http);
-    const {port, host} = this.conf.http;
-    log.reset("on").yellow(`${host}:${port}`).nl();
-  }
+const contents = {
+  "application/x-www-form-urlencoded": body =>
+    Object.fromEntries(body.split("&").map(part => part.split("=")
+      .map(subpart => decodeURIComponent(subpart).replaceAll("+", " ")))),
+  "application/json": body => JSON.parse(body),
+};
 
-  async try(url, request, payload) {
+export default conf => {
+  const route = async request => {
+    let result;
     try {
-      return await this.serve(url, request, payload);
+      result = await (await conf.router.process(request))(conf);
     } catch (error) {
       console.log(error);
-      return new Response(null, {status: codes.InternalServerError});
+      result = http404()``;
     }
-  }
-
-  async serve(url, request, payload) {
-    const path = new Path(this.conf.from, url);
-    return await path.isFile
-      ? this.resource(path.file)
-      : this.route(url, request, payload);
-  }
-
-  async resource(file) {
-    return new Response(file.readable, {
-      status: codes.OK,
+    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: {
-        "Content-Type": mime(file.name),
-        Etag: await file.modified,
+        ...result.headers,
+        "Content-Security-Policy": csp,
+        "Referrer-Policy": "same-origin",
       },
     });
-  }
+  };
 
-  async route(pathname, request, payload) {
-    const req = {pathname, method: request.method.toLowerCase(), payload};
-    let result;
+  const resource = async file => new Response(file.readable, {
+    status: statuses.OK,
+    headers: {
+      "Content-Type": mime(file.name),
+      Etag: await file.modified,
+    },
+  });
+
+  const _serve = async request => {
+    const path = new Path(conf.from, request.pathname);
+    return await path.isFile ? resource(path.file) : route(request);
+  };
+
+  const handle = async request => {
     try {
-      result = await (await this.conf.router.process(req))(this.conf);
+      return await _serve(request);
     } catch (error) {
       console.log(error);
-      result = http404``;
+      return new Response(null, {status: statuses.InternalServerError});
     }
-    return new Response(result.body, {
-      status: result.code,
-      headers: {
-        ...result.headers,
-        "Content-Security-Policy": this.csp,
-        "Referrer-Policy": "same-origin",
-      },
-    });
-  }
-};
+  };
+
+  const parseContent = (request, body) => {
+    const type = contents[request.headers.get("content-type")];
+    return type === undefined ? body : type(body);
+  };
+
+  const {http, modules} = conf;
 
-export default conf => new Server(conf).start();
+  // handle is the last module to be executed
+  const handlers = [...modules, handle].reduceRight((acc, handler) =>
+    input => handler(input, acc));
+
+  const decoder = new TextDecoder();
+  serve(async request => {
+    // preprocess request
+    const reader = request.body.getReader();
+    const chunks = [];
+    let result;
+    do {
+      result = await reader.read();
+      if (result.value !== undefined) {
+        chunks.push(decoder.decode(result.value));
+      }
+    } while (!result.done);
+
+    const body = chunks.length === 0 ? undefined
+      : parseContent(request, chunks.join());
+
+    const {pathname, search} = new URL(`https://example.com${request.url}`);
+
+    return await handlers({original: request, pathname: pathname + search, body});
+  }, http);
+
+  log.reset("on").yellow(`${http.host}:${http.port}`).nl();
+};

package/TODO

@@ -1,4 +0,0 @@
-remove ssl hint from documentation -> maybe add a "running an https server"
-add RouteError
-add the possibility to pass strings to attributes (rework internally data to
-hang at attributes)

package/src/preset/primate.json

@@ -1,25 +0,0 @@
-{
-  "base": "/",
-  "debug": false,
-  "files": {
-    "index": "index.html"
-  },
-  "http": {
-    "host": "localhost",
-    "port": 9999,
-    "csp": {
-      "default-src": "'self'",
-      "object-src": "'none'",
-      "frame-ancestors": "'none'",
-      "form-action": "'self'",
-      "base-uri": "'self'"
-    },
-    "same-site": "Strict"
-  },
-  "paths": {
-    "public": "public",
-    "static": "static",
-    "routes": "routes",
-    "components": "components"
-  }
-}