primate 0.11.0 → 0.13.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,6 +21,7 @@ Add `{"type": "module"}` to your `package.json` and run `npx primate`.
   - [Plain text](#plain-text)
   - [JSON](#json)
   - [Streams](#streams)
+  - [Response](#response)
   - [HTML](#html)
 - [Routing](#routing)
   - [Basic](#basic)
@@ -30,19 +31,17 @@ Add `{"type": "module"}` to your `package.json` and run `npx primate`.
   - [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)
+  - [Explicit handlers](#explicit-handlers)
 
 ## Serving content
 
-Create a file in `routes` that exports a default function
+Create a file in `routes` that exports a default function.
 
 ### Plain text
 
 ```js
 export default router => {
-  // strings will be served as plain text
+  // Serve strings as plain text
   router.get("/user", () => "Donald");
 };
 
@@ -54,13 +53,13 @@ export default router => {
 import {File} from "runtime-compat/filesystem";
 
 export default router => {
-  // any proper JavaScript object will be served as JSON
+  // Serve proper JavaScript objects as JSON
   router.get("/users", () => [
     {name: "Donald"},
     {name: "Ryan"},
   ]);
 
-  // load from a file and serve as JSON
+  // Load from file and serve as JSON
   router.get("/users-from-file", () => File.json("users.json"));
 };
 
@@ -72,39 +71,38 @@ 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
+### Response
 
-Create an HTML component in `components/user-index.html`
+```js
+import {Response} from "runtime-compat/http";
 
-```html
-<div for="${users}">
-  User ${name}.
-  Email ${email}.
-</div>
+export default router => {
+  // Use a Response object for custom response status
+  router.get("/create", () => new Response("created!", {status: 201}));
+};
 
 ```
 
-Serve the component in your route
+### HTML
 
 ```js
-import html from "@primate/html";
+// Use an explicit handler as we can't detect HTML by the return value type
+export default (router, {html}) => {
+  // Embed components/hello-world.html into static/index.html and serve it. In
+  // case a user-provided index.html doesn't exist, use a fallback index.html
+  router.get("/hello", () => html("hello-world"));
 
-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}" />`;
-  });
+  // Same as above, but without embedding
+  router.get("/hello-partial", () => html("hello-world", {partial: true}));
+
+  // Serve directly from string instead of loading a component
+  router.get("/hello-adhoc", () => html("<p>Hello, world!</p>", {adhoc: true}));
 };
 
 ```
@@ -115,13 +113,9 @@ Routes map requests to responses. They are loaded from `routes`.
 
 ### Basic
 
-To start serving content, create a file in `routes` returning a function as its
-default export. This function has a `router` param used to configure HTTP
-routes.
-
 ```js
 export default router => {
-  // accessing /site/login will serve the `Hello, world!` as plain text
+  // accessing /site/login will serve `Hello, world!` as plain text
   router.get("/site/login", () => "Hello, world!");
 };
 
@@ -137,6 +131,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
@@ -193,80 +201,27 @@ export default router => {
   router.map("edit-user", () => ({name: "Donald"}));
 
   // show user edit form
-  router.get("edit-user", user => html`<user-edit user="${user}" />`);
+  router.get("edit-user", user => html("user-edit", {user}));
 
   // verify form and save, or show errors
   router.post("edit-user", async user => await user.save()
-    ? redirect`/users`
+    ? redirect("/users")
     : html`<user-edit user="${user}" />`);
 };
 
 ```
 
-## Data persistance 
+### Explicit handlers
 
-Primate domains (via [`@primate/domains`][primate-domains]) represent a
-collection in a store using the class `fields` property.
+Most often we can figure the content type to respond with based on the return
+type from the handler. To handle content not automatically detected, use the
+second argument of the exported function.
 
 ```js
-import {Domain} from "@primate/domains";
-
-// 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,
-  };
-}
-
-
-```
-
-### Short field notation
-
-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 {Domain} from "@primate/domains";
-import House from "./House.js";
-
-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,
-    // 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.
-
-```js
-import {Domain} from "@primate/domains";
-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
-    name: [String, "unique"],
-    // a user's age must be a positive integer
-    age: [Number, "integer", "positive"],
-    // a user's house must have the foreign id of a house record and no two
-    // users may have the same house
-    house_id: [House, "unique"],
-  };
-}
+export default (router, {redirect}) => {
+  // redirect from source to target
+  router.get("/source", () => redirect("/target"));
+};
 
 ```
 
@@ -278,5 +233,3 @@ export default class User extends Domain {
 ## License
 
 MIT
-
-[primate-domains]: https://github.com/primatejs/primate-domains

package/eslint.config.js

@@ -0,0 +1 @@
+export {default} from "maximin";

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,15 @@
 {
   "name": "primate",
-  "version": "0.9.2",
-  "author": "Terrablue <terrablue@proton.me>",
+  "version": "0.13.0",
+  "description": "Expressive, minimal and extensible framework for JavaScript",
+  "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",
-  "repository": "https://github.com/primatejs/primate",
-  "description": "Primal JavaScript framework",
   "license": "MIT",
-  "bin": "bin/primate.js"
+  "bin": "src/bin.js",
+  "repository": "https://github.com/primatejs/primate",
+  "scripts": {
+    "docs": "scripts/docs.sh",
+    "test": "npx debris",
+    "lint": "npx eslint ."
+  }
 }

package/package.json

@@ -1,29 +1,26 @@
 {
   "name": "primate",
-  "version": "0.11.0",
-  "author": "Terrablue <terrablue@proton.me>",
+  "version": "0.13.0",
+  "description": "Expressive, minimal and extensible framework for JavaScript",
   "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",
-  "repository": "https://github.com/primatejs/primate",
-  "description": "Primal JavaScript framework",
   "license": "MIT",
+  "bin": "src/bin.js",
+  "repository": "https://github.com/primatejs/primate",
+  "scripts": {
+    "docs": "scripts/docs.sh",
+    "test": "npx debris",
+    "lint": "npx eslint ."
+  },
   "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/plugin-syntax-import-assertions": "^7.20.0",
-    "eslint": "^8.36.0",
-    "eslint-plugin-json": "^3.1.0"
+    "maximin": "^0.1.2"
   },
-  "scripts": {
-    "docs": "npx -y embedme --source-root readme --strip-embed-comment --stdout README.template.md > README.md"
-  },
-  "type": "module",
-  "exports": "./exports.js",
   "engines": {
     "node": ">=17.9.0"
-  }
+  },
+  "type": "module",
+  "exports": "./exports.js"
 }

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

@@ -0,0 +1,13 @@
+import html from "@primate/html";
+
+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});
+  });
+};

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});
+  });
+
+  // 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});
+  });
+};

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/{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/basic.js

@@ -1,4 +1,4 @@
 export default router => {
-  // accessing /site/login will serve the `Hello, world!` as plain text
+  // accessing /site/login will serve `Hello, world!` as plain text
   router.get("/site/login", () => "Hello, world!");
 };

package/readme/routing/explicit-handlers.js

@@ -0,0 +1,4 @@
+export default (router, {redirect}) => {
+  // redirect from source to target
+  router.get("/source", () => redirect("/target"));
+};

package/readme/routing/sharing-logic-across-requests.js

@@ -9,10 +9,10 @@ export default router => {
   router.map("edit-user", () => ({name: "Donald"}));
 
   // show user edit form
-  router.get("edit-user", user => html`<user-edit user="${user}" />`);
+  router.get("edit-user", user => html("user-edit", {user}));
 
   // verify form and save, or show errors
   router.post("edit-user", async user => await user.save()
-    ? redirect`/users`
+    ? redirect("/users")
     : html`<user-edit user="${user}" />`);
 };

package/readme/serving-content/html.js

@@ -1,13 +1,12 @@
-import html from "@primate/html";
+// Use an explicit handler as we can't detect HTML by the return value type
+export default (router, {html}) => {
+  // Embed components/hello-world.html into static/index.html and serve it. In
+  // case a user-provided index.html doesn't exist, use a fallback index.html
+  router.get("/hello", () => html("hello-world"));
 
-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}" />`;
-  });
+  // Same as above, but without embedding
+  router.get("/hello-partial", () => html("hello-world", {partial: true}));
+
+  // Serve directly from string instead of loading a component
+  router.get("/hello-adhoc", () => html("<p>Hello, world!</p>", {adhoc: true}));
 };

package/readme/serving-content/json.js

@@ -1,12 +1,12 @@
 import {File} from "runtime-compat/filesystem";
 
 export default router => {
-  // any proper JavaScript object will be served as JSON
+  // Serve proper JavaScript objects as JSON
   router.get("/users", () => [
     {name: "Donald"},
     {name: "Ryan"},
   ]);
 
-  // load from a file and serve as JSON
+  // Load from file and serve as JSON
   router.get("/users-from-file", () => File.json("users.json"));
 };

package/readme/serving-content/plain-text.js

@@ -1,4 +1,4 @@
 export default router => {
-  // strings will be served as plain text
+  // Serve strings as plain text
   router.get("/user", () => "Donald");
 };

package/readme/serving-content/response.js

@@ -0,0 +1,6 @@
+import {Response} from "runtime-compat/http";
+
+export default router => {
+  // Use a Response object for 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"));
 };

package/readme/template.md

@@ -0,0 +1,135 @@
+# Primate 
+
+Expressive, minimal and extensible framework for JavaScript.
+
+## Getting started
+
+Create a route in `routes/hello.js`
+
+```js
+// getting-started.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)
+  - [HTML](#html)
+- [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)
+  - [Explicit handlers](#explicit-handlers)
+
+## 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
+```
+
+### HTML
+
+```js
+// serving-content/html.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
+```
+
+### Explicit handlers
+
+Most often we can figure the content type to respond with based on the return
+type from the handler. To handle content not automatically detected, use the
+second argument of the exported function.
+
+```js
+// routing/explicit-handlers.js
+```
+
+## Resources
+
+* Website: https://primatejs.com
+* IRC: Join the `#primate` channel on `irc.libera.chat`.
+
+## License
+
+MIT