primate 0.17.0 → 0.19.0

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "primate",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Expressive, minimal and extensible web framework",
   "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",
   "license": "MIT",
   "files": [
-    "src/**",
+    "src/**/*.js",
+    "src/defaults/index.html",
     "!src/**/*.spec.js"
   ],
   "bin": "src/bin.js",
@@ -16,7 +17,7 @@
     "directory": "packages/primate"
   },
   "dependencies": {
-    "runtime-compat": "^0.16.3"
+    "runtime-compat": "^0.17.0"
   },
   "type": "module",
   "exports": "./src/exports.js"

package/src/Logger.js

@@ -1,115 +1,123 @@
 import {assert, is} from "runtime-compat/dyndef";
+import {blue, bold, green, red, yellow, dim} from "runtime-compat/colors";
 
-const colors = {
-  black: msg => `\x1b[0m${msg}\x1b[0m`,
-  bold: msg => `\x1b[1m${msg}\x1b[0m`,
-  red: msg => `\x1b[31m${msg}\x1b[0m`,
-  green: msg => `\x1b[32m${msg}\x1b[0m`,
-  yellow: msg => `\x1b[33m${msg}\x1b[0m`,
-  blue: msg => `\x1b[34m${msg}\x1b[0m`,
-  gray: msg => `\x1b[2m${msg}\x1b[0m`,
+const errors = {
+  Error: 0,
+  Warn: 1,
+  Info: 2,
 };
 
-const error = 0;
-const warn = 1;
-const info = 2;
-
-const Abort = class Abort extends Error {};
-// Error natively provided
-const Warn = class Warn extends Error {};
-const Info = class Info extends Error {};
-
-const levels = new Map([
-  [Error, error],
-  [Warn, warn],
-  [Info, info],
-]);
+const print = (...messages) => process.stdout.write(messages.join(" "));
+const bye = () => print(dim(yellow("~~ bye\n")));
+const mark = (format, ...params) => params.reduce((formatted, param) =>
+  formatted.replace("%", bold(param)), format);
 
-const abort = message => {
-  throw new Abort(message);
-};
+const reference = "https://primatejs.com/reference/errors";
 
-const print = (...messages) => process.stdout.write(messages.join(" "));
+const hyphenate = classCased => classCased
+  .split("")
+  .map(character => character
+    .replace(/[A-Z]/u, capital => `-${capital.toLowerCase()}`))
+  .join("")
+  .slice(1);
 
 const Logger = class Logger {
   #level; #trace;
 
-  constructor({level = Error, trace = false} = {}) {
-    assert(level !== undefined && levels.get(level) <= info);
+  static throwable(type, name, module) {
+    return {
+      throw(args = {}) {
+        const {message, level, fix} = type(args);
+        const error = new Error(mark(...message));
+        error.level = level;
+        error.fix = mark(...fix);
+        error.name = name;
+        error.module = module;
+        throw error;
+      },
+      warn(logger, ...args) {
+        const {message, level, fix} = type(...args);
+        const error = {level, message: mark(...message), fix: mark(...fix)};
+        logger.auto({...error, name, module});
+      },
+    };
+  }
+
+  constructor({level = errors.Error, trace = false} = {}) {
+    assert(level !== undefined && level <= errors.Info);
     is(trace).boolean();
     this.#level = level;
     this.#trace = trace;
   }
 
-  static get colors() {
-    return colors;
-  }
-
   static print(...args) {
     print(...args);
   }
 
+  static get mark() {
+    return mark;
+  }
+
   static get Error() {
-    return Error;
+    return errors.Error;
   }
 
   static get Warn() {
-    return Warn;
+    return errors.Warn;
   }
 
   static get Info() {
-    return Info;
+    return errors.Info;
   }
 
   get class() {
     return this.constructor;
   }
 
-  #print(pre, error) {
-    if (error instanceof Error) {
-      print(colors.bold(pre), error.message, "\n");
-      if (this.#trace) {
-        console.log(error);
-      }
-    } else {
-      print(colors.bold(pre), error, "\n");
+  #print(pre, color, message, {fix, module, name} = {}, error) {
+    print(pre, `${module !== undefined ? `${color(module)} ` : ""}${message}`, "\n");
+    if (fix && this.level >= errors.Warn) {
+      print(blue("++"), fix);
+      name && print(dim(`\n   -> ${reference}/${module ?? "primate"}#${hyphenate(name)}`), "\n");
     }
+    this.#trace && error && console.log(error);
   }
 
   get level() {
-    return levels.get(this.#level);
+    return this.#level;
   }
 
-  info(message) {
-    if (this.level >= levels.get(Info)) {
-      this.#print(colors.green("--"), message);
+  info(message, args) {
+    if (this.level >= errors.Info) {
+      this.#print(green("--"), green, message, args);
     }
   }
 
-  warn(message) {
-    if (this.level >= levels.get(Warn)) {
-      this.#print(colors.yellow("??"), message);
+  warn(message, args) {
+    if (this.level >= errors.Warn) {
+      this.#print(yellow("??"), yellow, message, args);
     }
   }
 
-  error(message) {
-    if (this.level >= levels.get(Error)) {
-      this.#print(colors.red("!!"), message);
+  error(message, args, error) {
+    if (this.level >= errors.Warn) {
+      this.#print(red("!!"), red, message, args, error);
     }
   }
 
-  auto(message) {
-    if (message instanceof Info) {
-      return this.info(message.message);
+  auto(error) {
+    const {level, message, ...args} = error;
+    if (level === errors.Info) {
+      return this.info(message, args, error);
     }
-    if (message instanceof Warn) {
-      return this.warn(message.message);
+    if (level === errors.Warn) {
+      return this.warn(message, args, error);
     }
 
-    return this.error(message);
+    return this.error(message, args, error);
   }
 };
 
 export default Logger;
 
-export {colors, levels, print, abort, Abort};
+export {print, bye};

package/src/app.js

@@ -1,7 +1,10 @@
 import crypto from "runtime-compat/crypto";
 import {File, Path} from "runtime-compat/fs";
+import {bold, blue} from "runtime-compat/colors";
+import errors from "./errors.js";
 import * as handlers from "./handlers/exports.js";
-import {abort} from "./Logger.js";
+import * as hooks from "./hooks/exports.js";
+import dispatch from "./dispatch.js";
 
 const qualify = (root, paths) =>
   Object.keys(paths).reduce((sofar, key) => {
@@ -12,16 +15,17 @@ const qualify = (root, paths) =>
     return sofar;
   }, {});
 
-const src = new Path(import.meta.url).up(1);
+const base = new Path(import.meta.url).up(1);
+const defaultLayout = "index.html";
 
-const index = async app => {
-  const name = "index.html";
+const index = async (app, layout = defaultLayout) => {
+  const name = layout;
   try {
     // user-provided file
-    return await File.read(`${app.paths.static.join(name)}`);
+    return await File.read(`${app.paths.layouts.join(name)}`);
   } catch (error) {
     // fallback
-    return src.join("defaults", name).text();
+    return base.join("defaults", defaultLayout).text();
   }
 };
 
@@ -32,13 +36,20 @@ const hash = async (string, algorithm = "sha-384") => {
   return `${algo}-${btoa(String.fromCharCode(...new Uint8Array(bytes)))}`;
 };
 
+const attribute = attributes => Object.keys(attributes).length > 0 ?
+  " ".concat(Object.entries(attributes)
+    .map(([key, value]) => `${key}="${value}"`).join(" "))
+  : "";
+const tag = ({name, attributes = {}, code = "", close = true}) =>
+  `<${name}${attribute(attributes)}${close ? `>${code}</${name}>` : "/>"}`;
+
 export default async (config, root, log) => {
-  const {name, version} = await src.up(1).join("package.json").json();
+  const {http} = config;
 
   // if ssl activated, resolve key and cert early
-  if (config.http.ssl) {
-    config.http.ssl.key = root.join(config.http.ssl.key);
-    config.http.ssl.cert = root.join(config.http.ssl.cert);
+  if (http.ssl) {
+    http.ssl.key = root.join(http.ssl.key);
+    http.ssl.cert = root.join(http.ssl.cert);
   }
 
   const paths = qualify(root, config.paths);
@@ -50,25 +61,41 @@ export default async (config, root, log) => {
         `${route}`.replace(paths.routes, "").slice(1, -ending.length),
         (await import(route)).default,
       ]));
+  const types = Object.fromEntries(
+    paths.types === undefined ? [] : await Promise.all(
+      (await Path.collect(paths.types , /^.*.js$/u))
+        /* accept only lowercase-first files in type filename */
+        .filter(path => /^[a-z]/u.test(path.name))
+        .map(async type => [
+          `${type}`.replace(paths.types, "").slice(1, -ending.length),
+          (await import(type)).default,
+        ])));
+  Object.entries(types).some(([name, type]) =>
+    typeof type !== "function" && errors.InvalidType.throw({name}));
 
   const modules = config.modules === undefined ? [] : config.modules;
 
-  modules.every(module => module.name !== undefined ||
-    abort("all modules must have names"));
+  modules.every((module, n) => module.name !== undefined ||
+    errors.ModulesMustHaveNames.throw({n}));
 
-  if (new Set(modules.map(module => module.name)).size !== modules.length) {
-    abort("same module twice");
-  }
+  new Set(modules.map(({name}) => name)).size !== modules.length &&
+    errors.DoubleModule.throw({
+      modules: modules.map(({name}) => name),
+      config: root.join("primate.config.js"),
+    });
 
-  modules.every(module => Object.entries(module).length > 1) || (() => {
-    log.warn("some modules haven't subscribed to any hooks");
-  })();
+  const hookless = modules.filter(module =>
+    !Object.keys(module).some(key => Object.keys(hooks).includes(key)));
+  hookless.length > 0 && errors.ModuleHasNoHooks.warn(log, {hookless});
+
+  const {name, version} = await base.up(1).join("package.json").json();
 
   const app = {
     config,
     routes,
-    secure: config.http?.ssl !== undefined,
-    name, version,
+    secure: http?.ssl !== undefined,
+    name,
+    version,
     library: {},
     identifiers: {},
     replace(code) {
@@ -86,20 +113,44 @@ export default async (config, root, log) => {
     paths,
     root,
     log,
+    generateHeaders: () => {
+      const csp = Object.keys(http.csp).reduce((policy_string, key) =>
+        `${policy_string}${key} ${http.csp[key]};`, "");
+      const scripts = app.resources
+        .filter(({type}) => type !== "style")
+        .map(resource => `'${resource.integrity}'`).join(" ");
+      const _csp = scripts === "" ? csp : `${csp}script-src 'self' ${scripts};`;
+      // remove inline resources
+      for (let i = app.resources.length - 1; i >= 0; i--) {
+        const resource = app.resources[i];
+        if (resource.inline) {
+          app.resources.splice(i, 1);
+        }
+      }
+
+      return {
+        "Content-Security-Policy": _csp,
+        "Referrer-Policy": "same-origin",
+      };
+    },
     handlers: {...handlers},
-    render: async ({body = "", head = ""} = {}) => {
-      const html = await index(app);
-      const heads = app.resources.map(({src, code, type, inline, integrity}) => {
-        const tag = type === "style" ? "link" : "script";
-        const pre = type === "style"
-          ? `<${tag} rel="stylesheet"`
-          : `<${tag} type="${type}" integrity="${integrity}"`;
-        const middle = type === "style"
-          ? ` href="${src}">`
-          : ` src="${src}">`;
-        const post = type === "style" ? "" : `</${tag}>`;
-        return inline ? `${pre}>${code}${post}` : `${pre}${middle}${post}`;
-      }).join("\n");
+    render: async ({body = "", head = "", layout} = {}) => {
+      const html = await index(app, layout);
+      // inline: <script type integrity>...</script>
+      // outline: <script type integrity src></script>
+      const script = ({inline, code, type, integrity, src}) => inline
+        ? tag({name: "script", attributes: {type, integrity}, code})
+        : tag({name: "script", attributes: {type, integrity, src}});
+      // inline: <style>...</style>
+      // outline: <link rel="stylesheet" href/>
+      const style = ({inline, code, href, rel = "stylesheet"}) => inline
+        ? tag({name: "style", code})
+        : tag({name: "link", attributes: {rel, href}, close: false});
+      const heads = app.resources.map(({src, code, type, inline, integrity}) =>
+        type === "style"
+          ? style({inline, code, href: src})
+          : script({inline, code, type, integrity, src})
+      ).join("\n");
       return html
         .replace("%body%", () => body)
         .replace("%head%", () => `${head}${heads}`);
@@ -108,10 +159,8 @@ export default async (config, root, log) => {
       if (type === "module") {
         code = app.replace(code);
       }
-      // while integrity is only really needed for scripts, it is also later
-      // used for the etag header
       const integrity = await hash(code);
-      const _src = new Path(config.http.static.root).join(src ?? "");
+      const _src = new Path(http.static.root).join(src ?? "");
       app.resources.push({src: `${_src}`, code, type, inline, integrity});
       return integrity;
     },
@@ -128,12 +177,10 @@ export default async (config, root, log) => {
       app.identifiers = {...exports, ...app.identifiers};
     },
     modules,
+    types,
   };
-  const {print, colors} = log.class;
-  print(colors.blue(colors.bold(name)), colors.blue(version), "");
-  const type = app.secure ? "https" : "http";
-  const address = `${type}://${config.http.host}:${config.http.port}`;
-  print(colors.gray(`at ${address}`), "\n");
+  log.class.print(blue(bold(name)), blue(version),
+    `at http${app.secure ? "s" : ""}://${http.host}:${http.port}\n`);
   // modules may load other modules
   await Promise.all(app.modules
     .filter(module => module.load !== undefined)
@@ -141,5 +188,8 @@ export default async (config, root, log) => {
       app.modules.push(dependent);
     }})));
 
+  app.route = hooks.route({...app, dispatch: dispatch(types)});
+  app.parse = hooks.parse(dispatch(types));
+
   return app;
 };

package/src/commands/exports.js

@@ -1,11 +1,8 @@
 import {default as dev} from "./dev.js";
 import {default as serve} from "./serve.js";
-import {default as build} from "./build.js";
-import {default as create} from "./create.js";
-import {default as help} from "./help.js";
 
-const commands = {dev, serve, build, create, help};
+const commands = {dev, serve};
 
-const run = name => commands[name] ?? help;
+const run = name => commands[name] ?? dev;
 
 export default name => name === undefined ? dev : run(name);

package/src/defaults/primate.config.js

@@ -10,6 +10,7 @@ export default {
     port: 6161,
     csp: {
       "default-src": "'self'",
+      "style-src": "'self'",
       "object-src": "'none'",
       "frame-ancestors": "'none'",
       "form-action": "'self'",
@@ -21,6 +22,7 @@ export default {
     },
   },
   paths: {
+    layouts: "layouts",
     static: "static",
     public: "public",
     routes: "routes",
@@ -29,4 +31,7 @@ export default {
   },
   modules: [],
   dist: "app",
+  types: {
+    explicit: false,
+  },
 };

package/src/dispatch.js

@@ -0,0 +1,24 @@
+import {is, maybe} from "runtime-compat/dyndef";
+import errors from "./errors.js";
+
+export default (patches = {}) => value => {
+  is(patches.get).undefined();
+  return Object.assign(Object.create(null), {
+    ...Object.fromEntries(Object.entries(patches).map(([name, patch]) =>
+      [name, property => {
+        is(property).defined(`\`${name}\` called without property`);
+        try {
+          return patch(value[property], property);
+        } catch (error) {
+          errors.MismatchedType.throw({message: error.message});
+        }
+      }])),
+    get(property) {
+      maybe(property).string();
+      if (property !== undefined) {
+        return value[property];
+      }
+      return value;
+    },
+  });
+};

package/src/errors.js

@@ -0,0 +1,141 @@
+import Logger from "./Logger.js";
+
+export default Object.fromEntries(Object.entries({
+  CannotParseBody({body, contentType}) {
+    return {
+      message: ["cannot parse body % as %", body, contentType],
+      fix: ["use a different content type or fix body"],
+      level: Logger.Warn,
+    };
+  },
+  DoubleModule({modules, config}) {
+    const double = modules.find((module, i, array) =>
+      array.filter((_, j) => i !== j).includes(module));
+    return {
+      message: ["double module % in %", double, config],
+      fix: ["load % only once", double],
+      level: Logger.Error,
+    };
+  },
+  DoublePathParameter({path, double}) {
+    return {
+      message: ["double path parameter % in route %", double, path],
+      fix: ["disambiguate path parameters in route names"],
+      level: Logger.Error,
+    };
+  },
+  DoubleRoute({double}) {
+    return {
+      message: ["double route %", double],
+      fix: ["disambiguate route % and %", double, `${double}/index`],
+      level: Logger.Error,
+    };
+  },
+  EmptyRouteFile({config: {paths}, route}) {
+    return {
+      message: ["empty route file at %", `${paths.routes}/${route}.js`],
+      fix: ["add routes or remove file"],
+      level: Logger.Warn,
+    };
+  },
+  ErrorInConfigFile({config, message}) {
+    return {
+      message: ["error in config %", message],
+      fix: ["check errors in config file by running %", `node ${config}`],
+      level: Logger.Error,
+    };
+  },
+  InvalidPathParameter({named, path}) {
+    return {
+      message: ["invalid path parameter % in route %", named, path],
+      fix: ["use only latin letters and decimal digits in path parameters"],
+      level: Logger.Error,
+    };
+  },
+  InvalidRouteName({path}) {
+    return {
+      message: ["invalid route name %", path],
+      fix: ["do not use dots in route names"],
+      level: Logger.Error,
+    };
+  },
+  InvalidType({name}) {
+    return {
+      message: ["invalid type %", name],
+      fix: ["use only functions for the default export of types"],
+      level: Logger.Error,
+    };
+  },
+  InvalidTypeName({name}) {
+    return {
+      message: ["invalid type name %", name],
+      fix: ["use only latin letters and decimal digits in types"],
+      level: Logger.Error,
+    };
+  },
+  MismatchedPath({path, message}) {
+    return {
+      message: [`mismatched % path: ${message}`, path],
+      fix: ["if unintentional, fix the type or the caller"],
+      level: Logger.Info,
+    };
+  },
+  MismatchedType({message}) {
+    return {
+      message: [`mismatched type: ${message}`],
+      fix: ["if unintentional, fix the type or the caller"],
+      level: Logger.Info,
+    };
+  },
+  ModuleHasNoHooks({hookless}) {
+    const modules = hookless.map(({name}) => name).join(", ");
+    return {
+      message: ["module % has no hooks", modules],
+      fix: ["ensure every module uses at least one hook or deactivate it"],
+      level: Logger.Warn,
+    };
+  },
+  ModulesMustHaveNames({n}) {
+    return {
+      message: ["modules must have names"],
+      fix: ["update module at index % and inform maintainer", n],
+      level: Logger.Error,
+    };
+  },
+  EmptyConfigFile({config}) {
+    return {
+      message: ["empty config file at %", config],
+      fix: ["add configuration options or remove file"],
+      level: Logger.Warn,
+    };
+  },
+  NoFileForPath({pathname, config: {paths}}) {
+    return {
+      message: ["no file for %", pathname],
+      fix: ["if unintentional create a file at %%", paths.static, pathname],
+      level: Logger.Info,
+    };
+  },
+  NoHandlerForExtension({name, ending}) {
+    return {
+      message: ["no handler for % extension", ending],
+      fix: ["add handler module for % files or remove %", `.${ending}`, name],
+      level: Logger.Error,
+    };
+  },
+  NoRouteToPath({method, pathname, config: {paths}}) {
+    const route = `${paths.routes}${pathname === "" ? "index" : pathname}.js`;
+    return {
+      message: ["no % route to %", method, pathname],
+      fix: ["if unintentional create a route at %", route],
+      level: Logger.Info,
+    };
+  },
+  ReservedTypeName({name}) {
+    return {
+      message: ["type name % is reserved", name],
+      fix: ["do not use any reserved type names"],
+      level: Logger.Error,
+    };
+  },
+}).map(([name, error]) => [name, Logger.throwable(error, name, "primate")]));

package/src/handlers/error.js

@@ -1,8 +1,9 @@
-const _404 = "Not Found";
+import {NotFound} from "../http-statuses.js";
 
-export default (body = _404, {status = 404} = {}) => async (app, headers) => [
-  await app.render({body}), {
-    status,
-    headers: {...headers, "Content-Type": "text/html"},
-  },
-];
+export default (body = "Not Found", {status = NotFound} = {}) =>
+  async (app, headers) => [
+    await app.render({body}), {
+      status,
+      headers: {...headers, "Content-Type": "text/html"},
+    },
+  ];

package/src/handlers/html.js

@@ -1,11 +1,33 @@
-export default (component, flags = {}) => {
-  const {status = 200, partial = false, load = false} = flags;
+const script = /(?<=<script)>(?<code>.*?)(?=<\/script>)/gus;
+const style = /(?<=<style)>(?<code>.*?)(?=<\/style>)/gus;
+
+const integrate = async (html, publish, headers) => {
+  const scripts = await Promise.all([...html.matchAll(script)]
+    .map(({groups: {code}}) => publish({code, inline: true})));
+  for (const integrity of scripts) {
+    headers["Content-Security-Policy"] = headers["Content-Security-Policy"]
+      .replace("script-src 'self' ", `script-src 'self' '${integrity}' `);
+  }
+  const styles = await Promise.all([...html.matchAll(style)]
+    .map(({groups: {code}}) => publish({code, type: "style", inline: true})));
+  for (const integrity of styles) {
+    headers["Content-Security-Policy"] = headers["Content-Security-Policy"]
+      .replace("style-src 'self'", `style-src 'self' '${integrity}' `);
+  }
+  return html
+    .replaceAll(/<script>.*?<\/script>/gus, () => "")
+    .replaceAll(/<style>.*?<\/style>/gus, () => "");
+};
+
+export default (component, options = {}) => {
+  const {status = 200, partial = false, load = false, layout} = options;
 
   return async (app, headers) => {
-    const body = load ?
-      await app.paths.components.join(component).text() : component;
+    const body = await integrate(await load ?
+      await app.paths.components.join(component).text() : component,
+    app.publish, headers);
 
-    return [partial ? body : await app.render({body}), {
+    return [partial ? body : await app.render({body, layout}), {
       status,
       headers: {...headers, "Content-Type": "text/html"},
     }];