primate 0.10.0 → 0.12.0

package/LICENSE

@@ -1,5 +1,3 @@
-Primate JavaScript Framework
-
 Copyright (c) Terrablue <terrablue@proton.me> and contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

package/README.md

@@ -1,6 +1,6 @@
 # Primate 
 
-An expressive, minimal and extensible framework for JavaScript.
+Expressive, minimal and extensible framework for JavaScript.
 
 ## Getting started
 
@@ -13,7 +13,7 @@ export default router => {
 
 ```
 
-Add `{"type": "module"}` to your `package.json` and run `npx primate`.
+Add `{"type": "module"}` to your `package.json` and run `npx -y primate@latest`.
 
 ## Table of Contents
 
@@ -21,21 +21,26 @@ Add `{"type": "module"}` to your `package.json` and run `npx primate`.
   - [Plain text](#plain-text)
   - [JSON](#json)
   - [Streams](#streams)
-  - [HTML](#html)
+  - [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)
-- [Data persistance](#data-persistance)
-  - [Short field notation](#short-field-notation)
-  - [Predicates](#predicates)
+- [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
+Create a file in `routes` that exports a default function.
 
 ### Plain text
 
@@ -71,39 +76,20 @@ export default router => {
 import {File} from "runtime-compat/filesystem";
 
 export default router => {
-  // `File` implements `readable`, which is a ReadableStream
+  // `File` implements `readable`, which is a `ReadableStream`
   router.get("/users", () => new File("users.json"));
 };
 
 ```
 
-### HTML
-
-Create an HTML component in `components/user-index.html`
-
-```html
-<div for="${users}">
-  User ${name}.
-  Email ${email}.
-</div>
-
-```
-
-Serve the component in your route
+### Response
 
 ```js
-import html from "@primate/html";
+import {Response} from "runtime-compat/http";
 
 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}" />`;
-  });
+  // use a generic response instance for a custom response status
+  router.get("/create", () => new Response("created!", {status: 201}));
 };
 
 ```
@@ -112,18 +98,12 @@ export default router => {
 
 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
 
 ```js
-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 />`);
+  // accessing /site/login will serve `Hello, world!` as plain text
+  router.get("/site/login", () => "Hello, world!");
 };
 
 ```
@@ -138,6 +118,20 @@ export default router => {
 
 ```
 
+### 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
+export default router => {
+  router.post("/site/login", ({body}) => `submitted user: ${body.username}`);
+};
+
+```
+
 ### Regular expressions
 
 ```js
@@ -204,54 +198,166 @@ export default router => {
 
 ```
 
-## Data persistance 
+## 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
+<div for="${users}">
+  User ${name}.
+  Email ${email}.
+</div>
+
+```
 
-Primate domains (via [`@primate/domains`][primate-domains]) represent a
-collection in a store using the class `fields` property.
+Create a route in `route/user.js` and serve the component in your route
 
 ```js
-import {Domain} from "@primate/domains";
+import html from "@primate/html";
 
-// 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,
-  };
-}
+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}" />`;
+  });
+};
+
+```
+
+#### Redirect
+
+*[`@primate/redirect`][primate-redirect]*
+
+Redirect the request.
+
+Create a route in `route/user.js`
+
+```js
+import redirect from "@primate/html";
+
+export default router => {
+  // redirect the request
+  router.get("/user", () => redirect`/users`);
+};
+
+```
+
+#### 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
+<div for="${users}" hx-get="/other-users" hx-swap="outerHTML">
+  User ${name}.
+  Email ${email}.
+</div>
+
+```
+
+Create a route in `route/user.js` and serve the component in your route
+
+```js
+import {default as htmx, partial} from "@primate/htmx";
 
+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 htmx`<user-index users="${users}" />`;
+  });
+
+  // this is the same as above, with support for partial rendering (without
+  // index.html)
+  router.get("/other-users", () => {
+    const users = [
+      {name: "Other Donald", email: "donald@the.goose"},
+      {name: "Other Joe", email: "joe@was.around"},
+    ];
+    return partial`<user-index users="${users}" />`;
+  });
+};
+
+```
+
+### 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
+export default {
+  modules: [],
+};
 
 ```
 
-### Short field notation
+#### 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
 
-Value types may be any constructible JavaScript object, including other
-domains. When using other domains as types, data integrity (on saving) is
-ensured.
+```js
+import domains from "@primate/domains";
+
+export default {
+  modules: [domains()],
+};
+
+```
+
+A domain represents a collection in a store using the static `fields` property
 
 ```js
 import {Domain} from "@primate/domains";
-import House from "./House.js";
 
+// A basic domain with two properies
 export default class User extends Domain {
   static fields = {
-    // a user's name must be a string
+    // a user's name is a string
     name: String,
-    // a user's age must be a number
+    // a user's age is a number
     age: Number,
-    // a user's house must have the foreign id of a house record
-    house_id: House,
   };
 }
 
 ```
 
-### Predicates
-
-Field types may also be specified as an array, to specify additional predicates
-aside from the type.
+Field types may also be specified as an array with additional predicates
+aside from the type
 
 ```js
 import {Domain} from "@primate/domains";
@@ -259,11 +365,11 @@ 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
+    // a user's name is a string unique across the user collection
     name: [String, "unique"],
-    // a user's age must be a positive integer
+    // a user's age is a positive integer
     age: [Number, "integer", "positive"],
-    // a user's house must have the foreign id of a house record and no two
+    // a user's house has the foreign id of a house record and no two
     // users may have the same house
     house_id: [House, "unique"],
   };
@@ -280,4 +386,8 @@ export default class User extends Domain {
 
 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/exports.js

@@ -1,5 +1,3 @@
-export {default as Bundler} from "./src/Bundler.js";
-
 export * from "./src/errors.js";
 
-export {default as extend} from "./src/extend.js";
+export {default} from "./src/run.js";

package/module.json

@@ -1,10 +1,10 @@
 {
   "name": "primate",
-  "version": "0.9.2",
-  "author": "Terrablue <terrablue@proton.me>",
+  "version": "0.11.0",
+  "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",
   "repository": "https://github.com/primatejs/primate",
-  "description": "Primal JavaScript framework",
+  "description": "Expressive, minimal and extensible framework for JavaScript",
   "license": "MIT",
-  "bin": "bin/primate.js"
+  "bin": "src/bin.js"
 }

package/package.json

@@ -1,25 +1,25 @@
 {
   "name": "primate",
-  "version": "0.10.0",
-  "author": "Terrablue <terrablue@proton.me>",
+  "version": "0.12.0",
   "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",
   "repository": "https://github.com/primatejs/primate",
-  "description": "Primal JavaScript framework",
+  "description": "Expressive, minimal and extensible framework for JavaScript",
   "license": "MIT",
+  "bin": "src/bin.js",
   "dependencies": {
-    "runtime-compat": "^0.12.3"
+    "runtime-compat": "^0.14.1"
   },
-  "bin": "bin/primate.js",
   "devDependencies": {
-    "@babel/core": "^7.21.0",
-    "@babel/eslint-parser": "^7.19.1",
+    "@babel/core": "^7.21.4",
+    "@babel/eslint-parser": "^7.21.3",
     "@babel/plugin-syntax-import-assertions": "^7.20.0",
-    "eslint": "^8.34.0",
+    "eslint": "^8.37.0",
     "eslint-plugin-json": "^3.1.0"
   },
   "scripts": {
-    "docs": "npx -y embedme --source-root readme --strip-embed-comment --stdout README.template.md > README.md"
+    "docs": "scripts/docs.sh",
+    "test": "npx debris"
   },
   "type": "module",
   "exports": "./exports.js",

package/readme/extensions/handlers/htmx/user-index.html

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

package/readme/extensions/handlers/htmx/user.js

@@ -0,0 +1,23 @@
+import {default as htmx, partial} from "@primate/htmx";
+
+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 htmx`<user-index users="${users}" />`;
+  });
+
+  // this is the same as above, with support for partial rendering (without
+  // index.html)
+  router.get("/other-users", () => {
+    const users = [
+      {name: "Other Donald", email: "donald@the.goose"},
+      {name: "Other Joe", email: "joe@was.around"},
+    ];
+    return partial`<user-index users="${users}" />`;
+  });
+};

package/readme/extensions/handlers/redirect/user.js

@@ -0,0 +1,6 @@
+import redirect from "@primate/html";
+
+export default router => {
+  // redirect the request
+  router.get("/user", () => redirect`/users`);
+};

package/readme/extensions/modules/configure.js

@@ -0,0 +1,3 @@
+export default {
+  modules: [],
+};

package/readme/extensions/modules/domains/configure.js

@@ -0,0 +1,5 @@
+import domains from "@primate/domains";
+
+export default {
+  modules: [domains()],
+};

package/readme/{domains → extensions/modules/domains}/fields.js

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

package/readme/{domains → extensions/modules/domains}/predicates.js

@@ -3,11 +3,11 @@ 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
+    // a user's name is a string unique across the user collection
     name: [String, "unique"],
-    // a user's age must be a positive integer
+    // a user's age is a positive integer
     age: [Number, "integer", "positive"],
-    // a user's house must have the foreign id of a house record and no two
+    // a user's house has the foreign id of a house record and no two
     // users may have the same house
     house_id: [House, "unique"],
   };

package/readme/{domains → extensions/modules/domains}/short-field-notation.js

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

package/readme/routing/accessing-the-request-body.js

@@ -0,0 +1,3 @@
+export default router => {
+  router.post("/site/login", ({body}) => `submitted user: ${body.username}`);
+};

package/readme/routing/basic.js

@@ -1,7 +1,4 @@
-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 />`);
+  // accessing /site/login will serve `Hello, world!` as plain text
+  router.get("/site/login", () => "Hello, world!");
 };

package/readme/serving-content/response.js

@@ -0,0 +1,6 @@
+import {Response} from "runtime-compat/http";
+
+export default router => {
+  // use a generic response instance for a custom response status
+  router.get("/create", () => new Response("created!", {status: 201}));
+};

package/readme/serving-content/streams.js

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