primate 0.10.0 → 0.12.0

package/readme/template.md

@@ -0,0 +1,226 @@
+# Primate 
+
+Expressive, minimal and extensible framework for JavaScript.
+
+## Getting started
+
+Create a route in `routes/hello.js`
+
+```js
+// getting-started/hello.js
+```
+
+Add `{"type": "module"}` to your `package.json` and run `npx -y primate@latest`.
+
+## Table of Contents
+
+- [Serving content](#serving-content)
+  - [Plain text](#plain-text)
+  - [JSON](#json)
+  - [Streams](#streams)
+  - [Response](#response)
+- [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)
+- [Extensions](#extensions)
+- [Handlers](#handlers)
+  - [HTML](#html)
+  - [Redirect](#redirect)
+  - [HTMX](#htmx)
+- [Modules](#modules)
+  - [Data persistance](#data-persistance)
+
+## Serving content
+
+Create a file in `routes` that exports a default function.
+
+### Plain text
+
+```js
+// serving-content/plain-text.js
+```
+
+### JSON
+
+```js
+// serving-content/json.js
+```
+
+### Streams
+
+```js
+// serving-content/streams.js
+```
+
+### Response
+
+```js
+// serving-content/response.js
+```
+
+## Routing
+
+Routes map requests to responses. They are loaded from `routes`.
+
+### Basic
+
+```js
+// routing/basic.js
+```
+
+### The request object
+
+```js
+// routing/the-request-object.js
+```
+
+### Accessing the request body
+
+For requests containing a body, Primate will attempt to parse 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
+// routing/regular-expressions.js
+```
+
+### Named groups
+
+```js
+// routing/named-groups.js
+```
+
+### Aliasing
+
+```js
+// routing/aliasing.js
+```
+
+### Sharing logic across requests
+
+```js
+// routing/sharing-logic-across-requests.js
+```
+
+## Extensions
+
+There are two ways to extend Primate's core functionality. Handlers are used
+per route to serve new types of content not supported by core. Modules extend
+an app's entire scope.
+
+Handlers and modules listed here are officially developed and supported by
+Primate.
+
+### Handlers
+
+#### HTML
+
+*[`@primate/html`][primate-html]*
+
+Serve HTML tagged templates. This handler reads HTML component files from
+`components`.
+
+Create an HTML component in `components/user-index.html`
+
+```html
+<!-- extensions/handlers/html/user-index.html -->
+```
+
+Create a route in `route/user.js` and serve the component in your route
+
+```js
+// extensions/handlers/html/user.js
+```
+
+#### Redirect
+
+*[`@primate/redirect`][primate-redirect]*
+
+Redirect the request.
+
+Create a route in `route/user.js`
+
+```js
+// extensions/handlers/redirect/user.js
+```
+
+#### HTMX
+
+*[`@primate/htmx`][primate-htmx]*
+
+Serve HTML tagged templates with HTMX support. This handler reads HTML component
+files from `components`.
+
+Create an HTML component in `components/user-index.html`
+
+```html
+<!-- extensions/handlers/htmx/user-index.html -->
+```
+
+Create a route in `route/user.js` and serve the component in your route
+
+```js
+// extensions/handlers/htmx/user.js
+```
+
+### Modules
+
+To add modules, create a `primate.config.js` configuration file in your
+project's root. This file should export a default object with the property
+`modules` used for extending your app.
+
+```js
+// extensions/modules/configure.js
+```
+
+#### Data persistance
+
+*[`@primate/domains`][primate-domains]*
+
+Add data persistance in the form of ORM backed up by various drivers.
+
+Import and initialize this module in your configuration file
+
+```js
+// extensions/modules/domains/configure.js
+```
+
+A domain represents a collection in a store using the static `fields` property
+
+```js
+// extensions/modules/domains/fields.js
+```
+
+Field types may also be specified as an array with additional predicates
+aside from the type
+
+```js
+// extensions/modules/domains/predicates.js
+```
+
+## Resources
+
+* Website: https://primatejs.com
+* IRC: Join the `#primate` channel on `irc.libera.chat`.
+
+## License
+
+MIT
+
+[primate-html]: https://github.com/primatejs/primate-html
+[primate-redirect]: https://github.com/primatejs/primate-redirect
+[primate-htmx]: https://github.com/primatejs/primate-htmx
+[primate-domains]: https://github.com/primatejs/primate-domains
+[primate-sessions]: https://github.com/primatejs/primate-sessions

package/scripts/docs.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+npx -y embedme\
+  --source-root readme\
+  --strip-embed-comment\
+  --stdout readme/template.md\
+  > README.md
+

package/src/bin.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+(await import("./run.js")).default();

package/src/bundle.js

@@ -1,8 +1,7 @@
-import {File} from "runtime-compat/filesystem";
-
-export default async conf => {
-  const {paths} = conf;
+import {File} from "runtime-compat/fs";
 
+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/config.js

@@ -0,0 +1,48 @@
+import {Path} from "runtime-compat/fs";
+import {is} from "runtime-compat/dyndef";
+import cache from "./cache.js";
+import extend from "./extend.js";
+import defaults from "./primate.config.js";
+import * as log from "./log.js";
+import package_json from "../package.json" assert {type: "json"};
+
+const qualify = (root, paths) =>
+  Object.keys(paths).reduce((sofar, key) => {
+    const value = paths[key];
+    sofar[key] = typeof value === "string"
+      ? new Path(root, value)
+      : qualify(`${root}/${key}`, value);
+    return sofar;
+  }, {});
+
+const getConfig = async (root, filename) => {
+  try {
+    return extend(defaults, (await import(root.join(filename))).default);
+  } catch (error) {
+    return defaults;
+  }
+};
+
+export default async (filename = "primate.config.js") => {
+  is(filename).string();
+  let root;
+  try {
+    // use module root if possible
+    root = await Path.root();
+  } catch (error) {
+    // fall back to current directory
+    root = Path.resolve();
+  }
+  const config = await getConfig(root, filename);
+
+  const env = {
+    ...config,
+    paths: qualify(root, config.paths),
+    root,
+    log: {...log, error: error => log.error(error, config),
+    },
+  };
+  env.log.info(`${package_json.name} \x1b[34m${package_json.version}\x1b[0m`);
+  const modules = await Promise.all(config.modules.map(module => module(env)));
+  return cache("config", filename, () => ({...env, modules}));
+};

package/src/duck.js

@@ -0,0 +1,4 @@
+import {Headers} from "runtime-compat/http";
+
+export const isResponse = value =>
+  value.body !== undefined && value.headers instanceof Headers;

package/src/extend.spec.js

@@ -40,20 +40,20 @@ export default test => {
   });
 
   test.case("one property of a subobject", assert => {
-    const base = {key: {"subkey": "subvalue"}};
-    const extension = {key: {"subkey": "subvalue 2"}};
+    const base = {key: {subkey: "subvalue"}};
+    const extension = {key: {subkey: "subvalue 2"}};
     assert(extend(base, extension)).equals(extension);
   });
 
   test.case("two properties of a subobject, one replaced", assert => {
-      const base = {key: {subkey: "subvalue", subkey2: "subvalue2"}};
-      const extension = {key: {subkey: "subvalue 2"}};
-      const extended = {key: {subkey: "subvalue 2", subkey2: "subvalue2"}};
-      assert(extend(base, extension)).equals(extended);
-    });
+    const base = {key: {subkey: "subvalue", subkey2: "subvalue2"}};
+    const extension = {key: {subkey: "subvalue 2"}};
+    const extended = {key: {subkey: "subvalue 2", subkey2: "subvalue2"}};
+    assert(extend(base, extension)).equals(extended);
+  });
 
-  test.case("configuration enhancement", assert => {
-    const default_conf = {
+  test.case("config enhancement", assert => {
+    const base = {
       base: "/",
       debug: false,
       defaults: {
@@ -61,16 +61,14 @@ export default test => {
         context: "guest",
       },
       paths: {
-        client: "client",
-        data: {
-          domains: "domains",
-          stores: "stores",
-        },
         public: "public",
+        static: "static",
+        routes: "routes",
+        components: "components",
       },
     };
 
-    const additional_conf = {
+    const additional = {
       debug: true,
       environment: "testing",
       defaults: {
@@ -78,11 +76,7 @@ export default test => {
         mode: "operational",
       },
       paths: {
-        client: "client_logic",
-        data: {
-          stores: "storage",
-          drivers: "drivers",
-        },
+        client: "client",
       },
     };
 
@@ -96,16 +90,14 @@ export default test => {
         mode: "operational",
       },
       paths: {
-        client: "client_logic",
-        data: {
-          domains: "domains",
-          drivers: "drivers",
-          stores: "storage",
-        },
+        client: "client",
         public: "public",
+        static: "static",
+        routes: "routes",
+        components: "components",
       },
     };
 
-    assert(extend(default_conf, additional_conf)).equals(extended);
+    assert(extend(base, additional)).equals(extended);
   });
 };

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/http-statuses.js

@@ -0,0 +1,5 @@
+export default {
+  OK: 200,
+  Found: 302,
+  InternalServerError: 500,
+};

package/src/log.js

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

package/src/mimes.js

@@ -0,0 +1,12 @@
+export default {
+  binary: "application/octet-stream",
+  css: "text/css",
+  html: "text/html",
+  jpg: "image/jpeg",
+  js: "text/javascript",
+  json: "application/json",
+  png: "image/png",
+  svg: "image/svg+xml",
+  woff2: "font/woff2",
+  webp: "image/webp",
+};

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

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

package/src/respond.js

@@ -0,0 +1,24 @@
+import {Blob} from "runtime-compat/fs";
+import text from "./handlers/text.js";
+import json from "./handlers/json.js";
+import stream from "./handlers/stream.js";
+import {isResponse as isResponseDuck} from "./duck.js";
+import RouteError from "./errors/Route.js";
+
+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 isResponse = value => isResponseDuck(value)
+  ? () => value : isObject(value);
+const isStream = value => value instanceof ReadableStream
+  ? stream`${value}` : isResponse(value);
+const isBlob = value => value instanceof Blob
+  ? stream`${value}` : isStream(value);
+const guess = value => isBlob(value);
+
+export default result => typeof result === "function" ? result : guess(result);

package/src/route.js

@@ -1,21 +1,7 @@
-import {ReadableStream} from "runtime-compat/streams";
-import {Path, File} from "runtime-compat/filesystem";
+import {Path} from "runtime-compat/fs";
 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 
-  ? json`${value}` : isText(value);
-const isStream = value => value instanceof ReadableStream
-  ? stream`${value}` : isObject(value);
-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();
 
@@ -43,19 +29,19 @@ export default async definitions => {
     get: (path, callback) => add("get", path, callback),
     post: (path, callback) => add("post", path, callback),
     alias: (key, value) => aliases.push({key, value}),
-    process: async request => {
+    route: async request => {
       const {method} = request.original;
       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 ?? {};
 
-      const result = await verb.handler(await find("map", pathname)
+      return verb.handler(await find("map", pathname)
         .handler({...request, pathname, params, path, named}));
-
-      return typeof result === "function" ? result : guess(result);
     },
   };
   if (await definitions.exists) {

package/src/run.js

@@ -1,22 +1,13 @@
+import bundle from "./bundle.js";
+import config from "./config.js";
 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 () => {
+  const env = await config();
+  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"),
-  });
+  serve({router, ...env});
 };