primate 0.8.1 → 0.9.1

package/README.template.md

@@ -0,0 +1,170 @@
+# Primate 
+
+Primal JavaScript framework.
+
+## Getting started
+
+Lay out app
+
+```sh
+# getting-started/lay-out-app.sh
+```
+
+Create a route for `/` in `routes/site.js`
+
+```js
+// getting-started/site.js
+```
+
+Create a component in `components/site-index.html`
+
+```html
+<!-- getting-started/site-index.html -->
+```
+
+Generate SSL files
+
+```sh
+# getting-started/generate-ssl.sh
+```
+
+Run
+
+```sh
+npx primate
+```
+
+## Table of contents
+
+* [Serving content](#serving-content)
+* [Routing](#routing)
+* [Domains](#domains)
+* [Stores](#stores)
+* [Components](#components)
+
+## 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
+```
+
+### HTML
+
+Create an HTML component in `components/user-index.html`
+
+```html
+<!-- serving-content/user-index.html -->
+```
+
+Serve the component in your route
+
+```js
+// serving-content/html.js
+```
+
+## Routing
+
+Routes map requests to responses. Routes are loaded from `routes`.
+
+The order in which routes are declared is irrelevant. Redeclaring a route
+(same pathname and same HTTP verb) throws a `RouteError`.
+
+### Basic GET route
+
+```js
+// routing/basic-get-request.js
+```
+
+### Working with the request path
+
+```js
+// routing/working-with-the-request-path.js
+```
+
+### Regular expressions
+
+```js
+// routing/regular-expressions.js
+```
+
+### Named groups
+
+```js
+// routing/named-groups.js
+```
+
+### Aliasing
+
+```js
+// routing/aliasing.js
+```
+
+### Sharing logic across HTTP verbs
+
+```js
+// routing/sharing-logic-across-http-verbs.js
+```
+
+## Domains
+
+Domains represent a collection in a store, primarily with the class `fields`
+property.
+
+### Fields
+
+Field types delimit acceptable values for a field.
+
+```js
+// domains/fields.js
+```
+
+### Short notation
+
+Field 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
+```
+
+### Predicates
+
+Field types may also be specified as an array, to specify additional predicates
+aside from the type.
+
+```js
+// domains/predicates.js
+```
+
+## Stores
+
+Stores interface data. Primate comes with volatile in-memory store used as a
+default. Other stores can be imported as modules.
+
+Stores are loaded from `stores`.
+
+### Resources
+
+* Website: https://primatejs.com
+* IRC: Join the `#primate` channel on `irc.libera.chat`.
+
+## License
+
+MIT

package/bin/primate.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import conf from "../src/conf.js";
+import run from "../src/run.js";
+await run(conf());

package/exports.js

@@ -1,31 +1,5 @@
-import conf from "./source/conf.js";
-import App from "./source/App.js";
+export {default as Bundler} from "./src/Bundler.js";
 
-export {App};
-export {default as Bundler} from "./source/Bundler.js";
-export {default as EagerPromise, eager} from "./source/EagerPromise.js" ;
+export * from "./src/errors.js";
 
-export {default as Domain} from "./source/domain/Domain.js";
-export {default as Storeable} from "./source/types/Storeable.js";
-
-export * from "./source/errors.js";
-export * from "./source/invariants.js";
-
-export {default as MemoryStore} from "./source/store/Memory.js";
-export {default as Store} from "./source/store/Store.js";
-
-export {default as extend_object} from "./source/extend_object.js";
-export {default as sanitize} from "./source/sanitize.js";
-
-export {default as html} from "./source/handlers/html.js";
-export {default as json} from "./source/handlers/json.js";
-export {default as redirect} from "./source/handlers/redirect.js";
-export {http404} from "./source/handlers/http.js";
-
-export {default as DOMParser} from "./source/handlers/DOM/Parser.js";
-
-export {default as router} from "./source/Router.js";
-
-const app = new App(conf());
-
-export {app};
+export {default as extend} from "./src/extend.js";

package/html.js

@@ -0,0 +1,13 @@
+import html from "../src/handlers/html.js";
+const components = {
+  "custom-tag": "<ct></ct>",
+  "custom-with-attribute": "<cwa value=\"${foo}\"></cwa>",
+  "custom-with-object-attribute": "<cwoa value=\"${foo.bar}\"></cwoa>",
+  "custom-with-slot": "<cws><slot/></cws>",
+  "for-with-object": "<fwo for=\"${foo}\"><span value=\"${bar}\"></span></fwo>",
+  "slot-before-custom": "<slot/><custom-tag></custom-tag>",
+  "custom-before-slot": "<custom-tag></custom-tag><slot/>",
+};
+const index = "<body>";
+const conf = {components, index};
+export default () => (strings, ...keys) => html(strings, ...keys)(conf);

package/module.json

@@ -0,0 +1,10 @@
+{
+  "name": "primate",
+  "version": "0.9.0",
+  "author": "Terrablue <terrablue@proton.me>",
+  "bugs": "https://github.com/primatejs/primate/issues",
+  "repository": "https://github.com/primatejs/primate",
+  "description": "Primal JavaScript framework",
+  "license": "MIT",
+  "bin": "bin/primate.js"
+}

package/package.json

@@ -1,27 +1,25 @@
 {
   "name": "primate",
-  "version": "0.8.1",
-  "author": "Primate core team <core@primatejs.com>",
+  "version": "0.9.1",
+  "author": "Terrablue <terrablue@proton.me>",
   "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",
   "repository": "https://github.com/primatejs/primate",
-  "description": "Cross-runtime JavaScript framework",
-  "license": "BSD-3-Clause",
-  "scripts": {
-    "copy": "rm -rf output && mkdir output && cp source/* output -a",
-    "instrument": "nyc instrument source ./output",
-    "debris": "node --experimental-json-modules node_modules/debris debris.json",
-    "coverage": "npm run instrument && nyc npm run debris",
-    "test": "npm run copy && npm run debris"
-  },
+  "description": "Primal JavaScript framework",
+  "license": "MIT",
   "dependencies": {
-    "runtime-compat": "^0.1.6"
+    "runtime-compat": "^0.12.2"
   },
+  "bin": "bin/primate.js",
   "devDependencies": {
-    "debris": "^0.2.2",
-    "eslint": "^8.14.0",
-    "eslint-plugin-json": "^3.1.0",
-    "nyc": "^15.1.0"
+    "@babel/core": "^7.20.12",
+    "@babel/eslint-parser": "^7.19.1",
+    "@babel/plugin-syntax-import-assertions": "^7.20.0",
+    "eslint": "^8.33.0",
+    "eslint-plugin-json": "^3.1.0"
+  },
+  "scripts": {
+    "docs": "npx embedme --source-root examples --strip-embed-comment --stdout README.template.md > README.md"
   },
   "type": "module",
   "exports": "./exports.js",

package/{source → src}/Bundler.js

@@ -1,7 +1,7 @@
-import {Path, File} from "runtime-compat";
+import {Path, File} from "runtime-compat/filesystem";
 
 const meta_url = new Path(import.meta.url).path;
-const directory = Path.dirname(meta_url);
+const directory = Path.directory(meta_url);
 const preset = `${directory}/preset`;
 
 export default class Bundler {

package/src/conf.js

@@ -0,0 +1,25 @@
+import {Path} from "runtime-compat/filesystem";
+import {Either} from "runtime-compat/functional";
+import cache from "./cache.js";
+import extend from "./extend.js";
+import json from "./preset/primate.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;
+  }, {});
+
+export default (filename = "primate.json") => cache("conf", filename, () => {
+  const root = Path.resolve();
+  const conf = Either
+    .try(() => extend(json, JSON.parse(root.join(filename).file.readSync())))
+    .match({left: () => json})
+    .get();
+  const paths = qualify(root, conf.paths);
+
+  return {...conf, paths, root};
+});

package/src/errors/Route.js

@@ -0,0 +1 @@
+export default class RouteError extends Error {}

package/{source/extend_object.js → src/extend.js}

@@ -1,10 +1,10 @@
-const extend_object = (base = {}, extension = {}) =>
+const extend = (base = {}, extension = {}) =>
   Object.keys(extension).reduce((result, property) => {
     const value = extension[property];
     result[property] = value?.constructor === Object
-      ? extend_object(base[property], value)
+      ? extend(base[property], value)
       : value;
     return result;
   }, base);
 
-export default extend_object;
+export default extend;

package/src/extend.spec.js

@@ -0,0 +1,111 @@
+import extend from "./extend.js";
+
+export default test => {
+  test.case("no params", assert => {
+    assert(extend()).equals({});
+  });
+
+  test.case("no base", assert => {
+    const extension = {key: "value"};
+    assert(extend(undefined, extension)).equals(extension);
+  });
+
+  test.case("no extension", assert => {
+    const base = {keys: "values"};
+    assert(extend(base)).equals(base);
+  });
+
+  test.case("base and extension same", assert => {
+    const object = {key: "value"};
+    assert(extend(object, object)).equals(object);
+  });
+
+  test.case("one property", assert => {
+    const base = {key: "value"};
+    const extension = {key: "value2"};
+    assert(extend(base, extension)).equals(extension);
+  });
+
+  test.case("two properties, one replaced", assert => {
+    const base = {key: "value", key2: "value2"};
+    const extension = {key: "other value"};
+    const extended = {key: "other value", key2: "value2"};
+    assert(extend(base, extension)).equals(extended);
+  });
+
+  test.case("arrays overwritten", assert => {
+    const base = {key: ["value", "value2"]};
+    const extension = {key: ["value3", "value4"]};
+    assert(extend(base, extension)).equals(extension);
+  });
+
+  test.case("one property of a subobject", assert => {
+    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);
+    });
+
+  test.case("configuration enhancement", assert => {
+    const default_conf = {
+      base: "/",
+      debug: false,
+      defaults: {
+        action: "index",
+        context: "guest",
+      },
+      paths: {
+        client: "client",
+        data: {
+          domains: "domains",
+          stores: "stores",
+        },
+        public: "public",
+      },
+    };
+
+    const additional_conf = {
+      debug: true,
+      environment: "testing",
+      defaults: {
+        context: "user",
+        mode: "operational",
+      },
+      paths: {
+        client: "client_logic",
+        data: {
+          stores: "storage",
+          drivers: "drivers",
+        },
+      },
+    };
+
+    const extended = {
+      base: "/",
+      debug: true,
+      environment: "testing",
+      defaults: {
+        action: "index",
+        context: "user",
+        mode: "operational",
+      },
+      paths: {
+        client: "client_logic",
+        data: {
+          domains: "domains",
+          drivers: "drivers",
+          stores: "storage",
+        },
+        public: "public",
+      },
+    };
+
+    assert(extend(default_conf, additional_conf)).equals(extended);
+  });
+};

package/src/handlers/http.js

@@ -0,0 +1 @@
+export {default as http404} from "./http404.js";

package/src/handlers/http404.js

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

package/src/handlers/json.js

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

package/src/handlers/stream.js

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

package/src/handlers/text.js

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

package/src/log.js

@@ -0,0 +1,22 @@
+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;

package/src/route.js

@@ -0,0 +1,61 @@
+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 
+  ? 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);
+
+export default async definitions => {
+  const aliases = [];
+  const routes = [];
+  const expand = path => aliases.reduce((expanded, {key, value}) =>
+    expanded.replace(key, () => value), path);
+  const exists = (method, path) =>
+    routes.some(route => route.method === method && route.path === path);
+  const add = (method, path, handler) => {
+    is(path).string();
+    is(handler).function();
+    if (exists(method, path)) {
+      throw new RouteError(`a ${method} route for ${path} already exists`);
+    }
+    routes.push({method, path: new RegExp(`^${expand(path)}$`, "u"), handler});
+  };
+  const find = (method, path, fallback = {handler: r => r}) =>
+    routes.find(route =>
+      route.method === method && route.path.test(path)) ?? fallback;
+
+  const router = {
+    map: (path, callback) => add("map", path, callback),
+    get: (path, callback) => add("get", path, callback),
+    post: (path, callback) => add("post", path, callback),
+    alias: (key, value) => aliases.push({key, value}),
+    process: async request => {
+      const {method} = request;
+      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 path = pathname.split("/").filter(part => part !== "");
+      const named = verb.path?.exec(pathname)?.groups ?? {};
+
+      const result = await verb.handler(await find("map", pathname)
+        .handler({...request, pathname, params, path, named}));
+
+      return typeof result === "function" ? result : guess(result);
+    },
+  };
+  const files = (await Path.list(definitions)).map(route => import(route));
+  await Promise.all(files.map(async route => (await route).default(router)));
+  return router;
+};

package/src/run.js

@@ -0,0 +1,26 @@
+import {Path, File} from "runtime-compat/filesystem";
+import {default as Bundler, index} from "./Bundler.js";
+import serve from "./serve.js";
+import route from "./route.js";
+import package_json from "../package.json" assert {type: "json"};
+import log from "./log.js";
+
+export default async conf => {
+  log.reset("Primate").yellow(package_json.version);
+  const {paths} = conf;
+  const router = await route(paths.routes);
+  await new Bundler(conf).bundle();
+
+  await serve({router,
+    paths: conf.paths,
+    index: await index(conf),
+    from: conf.paths.public,
+    http: {
+      ...conf.http,
+      key: await File.read(Path.resolve(conf.http.ssl.key)),
+      cert: await File.read(Path.resolve(conf.http.ssl.cert)),
+      keyFile: Path.resolve(conf.http.ssl.key),
+      certFile: Path.resolve(conf.http.ssl.cert),
+    },
+  });
+};