primate 0.6.4 → 0.7.0

package/README.md

@@ -4,23 +4,30 @@ A full-stack Javascript framework, Primate relieves you of dealing with
 repetitive, error-prone tasks and lets you concentrate on writing effective,
 expressive code.
 
-## Installing
+## Highlights
 
-```
-$ npm install primate
-```
+* Flexible HTTP routing, returning HTML, JSON or a custom handler
+* Secure by default with HTTPS, hash-verified scripts and a strong CSP
+* Built-in support for sessions with secure cookies
+* Input verification using data domains
+* Many different data store modules: In-Memory (built-in),
+[File][primate-file-store], [JSON][primate-json-store],
+[MongoDB][primate-mongodb-store]
+* Easy modelling of`1:1`, `1:n` and `n:m` relationships
+* Minimally opinionated with sane, overrideable defaults
+* No dependencies
 
-## Quick start
+## Getting started
 
 Lay out your app
 
-```
+```sh
 $ mkdir -p primate-app/{routes,components,ssl} && cd primate-app
 ```
 
 Create a route for `/`
 
-```
+```js
 // routes/site.js
 
 import {router, html} from "primate";
@@ -28,34 +35,30 @@ import {router, html} from "primate";
 router.get("/", () => html`<site-index date=${new Date()} />`);
 ```
 
-Create component for your route
-
-```
-// components/site-index.html
+Create a component for your route (in `components/site-index.html`)
 
+```html
 Today's date is <span data-value="date"></span>.
 ```
 
 Generate SSL key/certificate
 
-```
+```sh
 openssl req -x509 -out ssl/default.crt -keyout ssl/default.key -newkey rsa:2048 -nodes -sha256 -batch
 ```
 
 Add an entry file
 
-```
+```js
 // app.js
 
 import {app} from "primate";
 app.run();
 ```
 
-Create and start script and enable ES modules
-
-```
-// package.json
+Create a start script and enable ES modules (in `package.json`)
 
+```json
 {
   "scripts": {
     "start": "node --experimental-json-modules app.js"
@@ -66,34 +69,227 @@ Create and start script and enable ES modules
 
 Install Primate
 
-```
+```sh
 $ npm install primate
 ```
 
 Run app
 
-```
+```sh
 $ npm start
 ```
 
 Visit `https://localhost:9999`
 
-## Highlights
+## Table of Contents
 
-* Flexible HTTP routing, returning HTML, JSON or a custom handler
-* Secure by default with HTTPS, hash-verified scripts and a strong CSP
-* Built-in support for sessions with secure cookies
-* Input verification using data domains
-* Many different data store modules: In-Memory (built-in),
-[File][primate-file-store], [JSON][primate-json-store],
-[MongoDB][primate-mongodb-store]
-* Easy modelling of`1:1`, `1:n` and `n:m` relationships
-* Minimally opinionated with sane, overrideable defaults
-* No dependencies
+* [Routes](#routes)
+* [Handlers](#handlers)
+* [Components](#components)
+* [Domains](#domains)
+* [Verification](#verification)
+
+## Routes
+
+Create routes in the `routes` directory by importing and using the `router`
+singleton. You can group your routes across several files or keep them
+in one file.
+
+### `router[get|post](pathname, request => ...)`
+
+Routes are tied to a pathname and execute their callback when the pathname is 
+encountered.
+
+```js
+// in routes/some-file.js
+import {router, json} from "primate";
+
+// on matching the exact pathname /, returns {"foo": "bar"} as JSON
+router.get("/", () => json`${{"foo": "bar"}}`);
+```
+
+All routes must return a template function handler. See the
+[section on handlers for common handlers](#handlers).
+
+The callback has one parameter, the request data.
+
+### The `request` object
+
+The request contains the `path`, a `/` separated array of the pathname.
+
+```js
+import {router, html} from "primate";
+
+router.get("/site/login", request => json`${{"path": request.path}}`);
+// accessing /site/login -> {"path":["site","login"]}
+```
+
+The HTTP request's body is available under `request.payload`. 
+
+### Regular expressions in routes
+
+All routes are treated as regular expressions.
+
+```js
+import {router, json} from "primate";
+
+router.get("/user/view/([0-9])+", request => json`${{"path": request.path}}`);
+// accessing /user/view/1234 -> {"path":["site","login","1234"]}
+// accessing /user/view/abcd -> error 404
+```
+
+### `router.alias(from, to)`
+
+To reuse certain parts of a pathname, you can define aliases which will be
+applied before matching.
+
+```js
+import {router, json} from "primate";
+
+router.alias("_id", "([0-9])+");
+
+router.get("/user/view/_id", request => json`${{"path": request.path}}`);
+
+router.get("/user/edit/_id", request => ...);
+```
+
+### `router.map(pathname, request => ...)`
+
+You can reuse functionality across the same path but different HTTP verbs. This
+function has the same signature as `router[get|post]`.
+
+```js
+import {router, html, redirect} from "primate";
+
+router.alias("_id", "([0-9])+");
+
+router.map("/user/edit/_id", request => {
+  const user = {"name": "Donald"};
+  // return original request and user
+  return {...request, user};
+});
+
+router.get("/user/edit/_id", request => {
+  // show user edit form
+  return html`<user-edit user=${request.user} />`
+});
+
+router.post("/user/edit/_id", request => {
+  const {user} = request;
+  // verify form and save / show errors
+  return await user.save() ? redirect`/users` : html`<user-edit user=${user} />`
+});
+```
+
+## Handlers
+
+Handlers are tagged template functions usually associated with data.
+
+### ``html`<component-name attribute=${value} />` ``
+
+Compiles and serves a component from the `components` directory and with the
+specified attributes and their values. Returns an HTTP 200 response with the
+`text/html` content type.
+
+### ``json`${{data}}` ``
+
+Serves JSON `data`. Returns an HTTP 200 response with the `application/json`
+content type.
+
+### ``redirect`${url}` ``
+
+Redirects to `url`. Returns an HTTP 302 response.
+
+## Components
+
+Create HTML components in the `components` directory. Use `data`-attributes to
+show data within your component.
+
+```js
+// in routes/user.js
+import {router, html, redirect} from "primate";
+
+router.alias("_id", "([0-9])+");
+
+router.map("/user/edit/_id", request => {
+  const user = {"name": "Donald", "email": "donald@was.here"};
+  // return original request and user
+  return {...request, user};
+});
+
+router.get("/user/edit/_id", request => {
+  // show user edit form
+  return html`<user-edit user=${request.user} />`
+});
+
+router.post("/user/edit/_id", request => {
+  const {user, payload} = request;
+  // verify form and save / show errors
+  // this assumes `user` has a method `save` to verify data
+  return await user.save(payload) ? redirect`/users` : html`<user-edit user=${user} />`
+});
+```
+
+```html
+<!-- components/edit-user.html -->
+<form method="post">
+  <h1>Edit user</h1>
+  <p>
+    <input name="user.name" data-value="user.name"></textarea>
+  </p>
+  <p>
+    <input name="user.email" data-value="user.email"></textarea>
+  </p>
+  <input type="submit" value="Save user" />
+</form>
+```
+
+### Grouping objects with `data-for`
+
+You can use the special attribute `data-for` to group objects.
+
+```html
+<!-- components/edit-user.html -->
+<form data-for="user" method="post">
+  <h1>Edit user</h1>
+  <p>
+    <input name="name" data-value="name" />
+  </p>
+  <p>
+    <input name="email" data-value="email" />
+  </p>
+  <input type="submit" value="Save user" />
+</form>
+```
+
+### Expanding arrays
+
+`data-for` can also be used to expand arrays.
+
+```js
+// in routes/user.js
+import {router, html} from "primate";
+
+router.get("/users", request => {
+  const users = [
+   {"name": "Donald", "email": "donald@was.here"},
+   {"name": "Ryan", "email": "ryan@was.here"},
+  ];
+  return html`<user-index users=${users} />`;
+});
+```
+
+```html
+<!-- in components/user-index.html -->
+<div data-for="users">
+  User <span data-value="name"></span>
+  Email <span data-value="email"></span>
+</div>
+```
 
 ## Resources
 
-* [Getting started guide]
+* [Getting started guide][getting-started]
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primate",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "author": "Primate core team <core@primatejs.com>",
   "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",
@@ -14,6 +14,9 @@
     "coverage": "npm run instrument && nyc npm run debris",
     "test": "npm run copy && npm run debris"
   },
+  "dependencies": {
+    "runtime-compat": "^0.1.0"
+  },
   "devDependencies": {
     "debris": "^0.2.2",
     "eslint": "^8.13.0",

package/source/App.js

@@ -1,10 +1,7 @@
-import {resolve} from "path";
+import {Path, File, log} from "runtime-compat";
 import Bundler from "./Bundler.js";
-import File from "./File.js";
-import Directory from "./Directory.js";
 import Router from "./Router.js";
 import Server from "./Server.js";
-import log from "./log.js";
 import package_json from "../package.json" assert {"type": "json"};
 
 export default class App {
@@ -14,8 +11,7 @@ export default class App {
 
   async run() {
     log.reset("Primate").yellow(package_json.version);
-
-    const routes = await Directory.list(this.conf.paths.routes);
+    const routes = await File.list(this.conf.paths.routes);
     for (const route of routes) {
       await import(`${this.conf.paths.routes}/${route}`);
     }
@@ -25,8 +21,10 @@ export default class App {
       "serve_from": this.conf.paths.public,
       "http": {
         ...this.conf.http,
-        "key": File.read_sync(resolve(this.conf.http.ssl.key)),
-        "cert": File.read_sync(resolve(this.conf.http.ssl.cert)),
+        "key": File.read_sync(Path.resolve(this.conf.http.ssl.key)),
+        "cert": File.read_sync(Path.resolve(this.conf.http.ssl.cert)),
+        "keyFile": Path.resolve(this.conf.http.ssl.key),
+        "certFile": Path.resolve(this.conf.http.ssl.cert),
       },
     };
     this.server = new Server(conf);

package/source/Bundler.js

@@ -1,9 +1,7 @@
-import {dirname} from "path";
-import {fileURLToPath} from "url";
-import File from "./File.js";
+import {Path, File} from "runtime-compat";
 
-const meta_url = fileURLToPath(import.meta.url);
-const directory = dirname(meta_url);
+const meta_url = new Path(import.meta.url).path;
+const directory = Path.dirname(meta_url);
 const preset = `${directory}/preset`;
 
 export default class Bundler {
@@ -22,7 +20,7 @@ export default class Bundler {
 
     // copy any user code over it, not recreating the folder
     try {
-      await File.copy(paths[subdirectory], to, false);
+      await File.copy(paths[subdirectory], to);
     } catch(error) {
       // directory doesn't exist
     }

package/source/Server.js

@@ -1,10 +1,5 @@
-import zlib from "zlib";
-import {createServer} from "https";
-import {join} from "path";
-import {parse} from "url";
+import {Path, File, WebServer, log} from "runtime-compat";
 import Session from "./Session.js";
-import File from "./File.js";
-import log from "./log.js";
 import codes from "./http-codes.json" assert {"type": "json"};
 import mimes from "./mimes.json" assert {"type": "json"};
 import {http404} from "./handlers/http.js";
@@ -13,11 +8,8 @@ const regex = /\.([a-z1-9]*)$/u;
 const mime = filename => mimes[filename.match(regex)[1]] ?? mimes.binary;
 
 const stream = (from, response) => {
-  response.setHeader("Content-Encoding", "br");
-  response.writeHead(codes.OK);
-  return from.pipe(zlib.createBrotliCompress())
-    .pipe(response)
-    .on("close", () => response.end());
+  response.setStatus(codes.OK);
+  return from.pipe(response).on("close", () => response.end());
 };
 
 export default class Server {
@@ -31,25 +23,20 @@ export default class Server {
     this.csp = Object.keys(csp).reduce((policy_string, key) =>
       policy_string + `${key} ${csp[key]};`, "");
 
-    this.server = await createServer(http, async (request, response) => {
+    this.server = new WebServer(http, async (request, response) => {
       const session = await Session.get(request.headers.cookie);
       if (!session.has_cookie) {
         const {cookie} = session;
         response.setHeader("Set-Cookie", `${cookie}; SameSite=${same_site}`);
       }
       response.session = session;
-      const buffers = [];
-
-      for await (const chunk of request) {
-        buffers.push(chunk);
-      }
-
-      const data = Buffer.concat(buffers).toString();
-      const payload = Object.fromEntries(decodeURI(data).replaceAll("+", " ")
+      const body = await request.body;
+      const payload = Object.fromEntries(decodeURI(body).replaceAll("+", " ")
         .split("&")
         .map(part => part.split("="))
         .filter(([, value]) => value !== ""));
-      this.try(parse(request.url).path, request, response, payload);
+      const {pathname, search} = new URL(`https://1${request.url}`);
+      return this.try(pathname + search, request, response, payload);
     });
   }
 
@@ -58,20 +45,20 @@ export default class Server {
       await this.serve(url, request, response, payload);
     } catch (error) {
       console.log(error);
-      response.writeHead(codes.InternalServerError);
+      response.setStatus(codes.InternalServerError);
       response.end();
     }
   }
 
   async serve_file(url, filename, file, response) {
     response.setHeader("Content-Type", mime(filename));
-    response.setHeader("Etag", file.modified);
-    await response.session.log("green", url);
+    response.setHeader("Etag", await file.modified);
+    //await response.session.log("green", url);
     return stream(file.read_stream, response);
   }
 
   async serve(url, request, response, payload) {
-    const filename = join(this.conf.serve_from, url);
+    const filename = Path.join(this.conf.serve_from, url);
     const file = await new File(filename);
     return await file.is_file
       ? this.serve_file(url, filename, file, response, payload)
@@ -93,8 +80,9 @@ export default class Server {
     const {body, code} = result;
     response.setHeader("Content-Security-Policy", this.csp);
     response.setHeader("Referrer-Policy", "same-origin");
-    response.writeHead(code);
-    response.end(body);
+    response.setStatus(code);
+    response.setBody(body);
+    response.end();
   }
 
   listen() {

package/source/conf.js

@@ -1,6 +1,5 @@
-import {join, resolve} from "path";
+import {Path, File} from "runtime-compat";
 import cache from "./cache.js";
-import File from "./File.js";
 import extend_object from "./extend_object.js";
 import primate_json from "./preset/primate.json" assert {"type": "json" };
 
@@ -8,16 +7,16 @@ const qualify = (root, paths) =>
   Object.keys(paths).reduce((sofar, key) => {
     const value = paths[key];
     sofar[key] = typeof value === "string"
-      ? join(root, value)
+      ? Path.join(root, value)
       : qualify(`${root}/${key}`, value);
     return sofar;
   }, {});
 
 export default (file = "primate.json") => cache("conf", file, () => {
   let conf = primate_json;
-  const root = resolve();
+  const root = Path.resolve();
   try {
-    conf = extend_object(conf, JSON.parse(File.read_sync(join(root, file))));
+    conf = extend_object(conf, JSON.parse(File.read_sync(Path.join(root, file))));
   } catch (error) {
     // local primate.json not required
   }

package/source/domain/Domain.js

@@ -1,10 +1,10 @@
+import {Crypto} from "runtime-compat";
 import Field from "./Field.js";
 import {PredicateError} from "../errors.js";
 import EagerPromise from "../EagerPromise.js";
 import Store from "../store/Store.js";
 import cache from "../cache.js";
 import DomainType from "../types/Domain.js";
-import {random} from "../crypto.js";
 
 const length = 12;
 
@@ -23,7 +23,7 @@ export default class Domain {
     this.define("_id", {
       "type": String,
       "predicates": ["unique"],
-      "in": value => value ?? random(length).toString("hex"),
+      "in": value => value ?? Crypto.random(length).toString("hex"),
     });
     return new Proxy(this, {"get": (target, property, receiver) =>
       Reflect.get(target, property, receiver) ?? target.#proxy(property),

package/source/exports.js

@@ -3,8 +3,6 @@ import App from "./App.js";
 
 export {App};
 export {default as Bundler} from "./Bundler.js";
-export {default as Directory} from "./Directory.js";
-export {default as File} from "./File.js";
 export {default as EagerPromise, eager} from "./EagerPromise.js" ;
 
 export {default as Domain} from "./domain/Domain.js";
@@ -16,7 +14,6 @@ export * from "./invariants.js";
 export {default as MemoryStore} from "./store/Memory.js";
 export {default as Store} from "./store/Store.js";
 
-export {default as log} from "./log.js";
 export {default as extend_object} from "./extend_object.js";
 export {default as sanitize} from "./sanitize.js";
 

package/source/handlers/html.js

@@ -1,6 +1,5 @@
+import {File} from "runtime-compat";
 import Parser from "./DOM/Parser.js";
-import Directory from "../Directory.js";
-import File from "../File.js";
 import {index} from "../Bundler.js";
 import _conf from "../conf.js";
 const conf = _conf();
@@ -9,7 +8,7 @@ const last = -1;
 const {"paths": {"components": path}} = conf;
 const components = {};
 if (await File.exists(path)) {
-  const names = await Directory.list(path);
+  const names = await File.list(path);
   for (const name of names) {
     components[name.slice(0, -5)] = await File.read(`${path}/${name}`);
   }

package/source/invariants.js

@@ -1,5 +1,4 @@
 import {constructible, nullish} from "./attributes.js";
-import map_entries from "./map_entries.js";
 
 const errored = error => {
   if (typeof error === "function") {

package/source/store/Store.js

@@ -1,4 +1,4 @@
-import {resolve} from "path";
+import {Path} from "runtime-compat";
 const preset = "../preset/stores";
 
 export default class Store {
@@ -21,7 +21,7 @@ export default class Store {
   static async get(directory, file) {
     let store;
     try {
-      store = await import(resolve(`${directory}/${file}`));
+      store = await import(Path.resolve(`${directory}/${file}`));
     } catch(error) {
       store = await import(`${preset}/${file}`);
     }

package/source/Directory.js

@@ -1,35 +0,0 @@
-import fs from "fs";
-import {join} from "path";
-
-const options = {"encoding": "utf8"};
-
-const readdir = path => new Promise((resolve, reject) =>
-  fs.readdir(path, options,
-    (error, files) => error === null ? resolve(files) : reject(error)
-  ));
-
-const rm = path => new Promise((resolve, reject) =>
-  fs.rm(path, {"recursive": true, "force": true},
-    error => error === null ? resolve(true) : reject(error)
-  ));
-
-const mkdir = path => new Promise((resolve, reject) =>
-  fs.mkdir(path, error => error === null ? resolve(true) : reject(error)));
-
-export default class Directory {
-  static list(...args) {
-    return readdir(join(...args));
-  }
-
-  static remove(...args) {
-    return rm(join(...args));
-  }
-
-  static make(...args) {
-    return mkdir(join(...args));
-  }
-
-  static async remake(...args) {
-    await this.remove(...args) && this.make(...args);
-  }
-}

package/source/File.js

@@ -1,121 +0,0 @@
-import fs from "fs";
-import {join} from "path";
-import Directory from "./Directory.js";
-import EagerPromise from "./EagerPromise.js";
-
-const array = maybe => Array.isArray(maybe) ? maybe : [maybe];
-
-const filter_files = (files, filter) =>
-  files.filter(file => array(filter).some(ending => file.endsWith(ending)));
-
-export default class File {
-  constructor(...args) {
-    this.path = join(...args);
-    return EagerPromise.resolve(new Promise(resolve => {
-      fs.lstat(this.path, (error, stats) => {
-        this.stats = stats;
-        resolve(this);
-      });
-    }));
-  }
-
-  get modified() {
-    return Math.round(this.stats.mtimeMs);
-  }
-
-  get exists() {
-    return this.stats !== undefined;
-  }
-
-  get is_file() {
-    return this.exists && !this.stats.isDirectory();
-  }
-
-  get stream() {
-    return this.read_stream;
-  }
-
-  get read_stream() {
-    return fs.createReadStream(this.path, {"flags": "r"});
-  }
-
-  get write_stream() {
-    return fs.createWriteStream(this.path);
-  }
-
-  remove() {
-    return new Promise((resolve, reject) => fs.rm(this.path,
-      {"recursive": true, "force": true},
-      error => error === null ? resolve(this) : reject(error)
-    ));
-  }
-
-  create() {
-    return new Promise((resolve, reject) => fs.mkdir(this.path, error =>
-      error === null ? resolve(this) : reject(error)
-    ));
-  }
-
-  async copy(to, recreate = true) {
-    if (this.stats.isDirectory()) {
-      if (recreate) {
-        await new File(`${to}`).recreate();
-      }
-      // copy all files
-      return Promise.all((await this.list()).map(file =>
-        new File(`${this.path}/${file}`).copy(`${to}/${file}`)
-      ));
-    } else {
-      return new Promise((resolve, reject) => fs.copyFile(this.path, to,
-        error => error === null ? resolve(this) : reject(error)));
-    }
-  }
-
-  async list(filter) {
-    if (!this.exists) {
-      return [];
-    }
-    const files = await Directory.list(this.path);
-    return filter !== undefined ? filter_files(files, filter) : files;
-  }
-
-  async recreate() {
-    return (await this.remove()).create();
-  }
-
-  read(options = {"encoding": "utf8"}) {
-    return new Promise((resolve, reject) =>
-      fs.readFile(this.path, options, (error, nonerror) =>
-        error === null ? resolve(nonerror) : reject(error)));
-  }
-
-  write(data, options = {"encoding": "utf8"}) {
-    return new Promise((resolve, reject) => fs.writeFile(this.path, data,
-      options,
-      error => error === null ? resolve(this) : reject(error)));
-  }
-
-  static read_sync(path, options = {"encoding": "utf8"}) {
-    return fs.readFileSync(path, options);
-  }
-
-  static exists(...args) {
-    return new File(...args).exists;
-  }
-
-  static read(...args) {
-    return new File(...args).read();
-  }
-
-  static write(path, data, options) {
-    return new File(path).write(data, options);
-  }
-
-  static remove(...args) {
-    return new File(...args).remove();
-  }
-
-  static copy(from, to, recreate) {
-    return new File(from).copy(to, recreate);
-  }
-}

package/source/crypto.js

@@ -1,8 +0,0 @@
-import {createHash, randomBytes} from "crypto";
-
-export const algorithm = "sha256";
-
-export const hash = (payload, digest = "base64") =>
-  createHash(algorithm).update(payload, "utf8").digest(digest);
-
-export const random = length => randomBytes(length);

package/source/log.js

@@ -1,22 +0,0 @@
-const colors = {
-  "red": 31,
-  "green": 32,
-  "yellow": 33,
-  "blue": 34,
-};
-const reset = 0;
-
-const Log = {
-  "paint": (color, message) => {
-    process.stdout.write(`\x1b[${color}m${message}\x1b[0m`);
-    return log;
-  },
-  "nl": () => log.paint(reset, "\n"),
-};
-
-const log = new Proxy(Log, {
-  "get": (target, property) => target[property] ?? (message =>
-    log.paint(colors[property] ?? reset, message).paint(reset, " ")),
-});
-
-export default log;