primate 0.8.0 → 0.9.0

package/LICENSE

@@ -1,27 +1,21 @@
-Copyright (c) 2022, Primate core team <core@primatejs.com>. All rights
-reserved.
+Primate JavaScript Framework
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+Copyright (c) Terrablue <terrablue@proton.me> and contributors.
 
-1. Redistributions of source code must retain the above copyright notice, this
-list of conditions and the following disclaimer.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-2. Redistributions in binary form must reproduce the above copyright notice,
-this list of conditions and the following disclaimer in the documentation
-and/or other materials provided with the distribution.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-3. Neither the name of the copyright holder nor the names of its contributors
-may be used to endorse or promote products derived from this software without
-specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,324 +1,314 @@
 # Primate 
 
-A full-stack Javascript framework with data verification and server-side HTML
-rendering.
-
-## Highlights
-
-* Flexible HTTP routing, returning HTML, JSON or a custom handler
-* Secure by default with HTTPS, hash-verified scripts and a strong CSP
-* Built-in support for sessions with secure cookies
-* Input verification using data domains
-* Many different data store modules: In-Memory (built-in),
-[File][primate-file-store], [JSON][primate-json-store],
-[MongoDB][primate-mongodb-store]
-* Easy modelling of`1:1`, `1:n` and `n:m` relationships
-* Minimally opinionated with sane, overrideable defaults
-* Supports both Node.js and Deno
+Primal JavaScript framework.
 
 ## Getting started
 
-### Prepare
-
-Lay out your app
+Lay out app
 
 ```sh
-$ mkdir -p primate-app/{routes,components,ssl} && cd primate-app
+mkdir -p app/{routes,components,ssl} && cd app
+
 ```
 
-Create a route for `/`
+Create a route for `/` in `routes/site.js`
 
 ```js
-// routes/site.js
+import html from "@primate/html";
 
-import {router, html} from "primate";
+export default router => {
+  router.get("/", () => html`<site-index date="${new Date()}" />`);
+};
 
-router.get("/", () => html`<site-index date="${new Date()}" />`);
 ```
 
-Create a component for your route (in `components/site-index.html`)
+Create a component in `components/site-index.html`
 
 ```html
-Today's date is <span value="${date}"></span>.
+Today's date is ${date}.
+
 ```
 
-Generate SSL key/certificate
+Generate SSL files
 
 ```sh
 openssl req -x509 -out ssl/default.crt -keyout ssl/default.key -newkey rsa:2048 -nodes -sha256 -batch
-```
 
-Add an entry file
+```
 
-```js
-// app.js
+Run
 
-import {app} from "primate";
-app.run();
+```sh
+npx primate
 ```
 
-### Run on Node.js
+## Table of contents
 
-Create a start script and enable ES modules (in `package.json`)
+* [Serving content](#serving-content)
+* [Routing](#routing)
+* [Domains](#domains)
+* [Stores](#stores)
+* [Components](#components)
 
-```json
-{
-  "scripts": {
-    "start": "node --experimental-json-modules app.js"
-  },
-  "type": "module"
-}
-```
+## Serving content
 
-Install Primate
+Create a file in `routes` that exports a default function
 
-```sh
-$ npm install primate
-```
+### Plain text
 
-Run app
+```js
+export default router => {
+  // strings will be served as plain text
+  router.get("/user", () => "Donald");
+};
 
-```sh
-$ npm start
 ```
 
-### Run on Deno
+### JSON
 
-Create an import map file (`import-map.json`)
+```js
+import {File} from "runtime-compat/filesystem";
 
-```json
-{
-  "imports": {
-    "runtime-compat": "https://deno.land/x/runtime_compat/exports.js",
-    "primate": "https:/deno.land/x/primate/exports.js"
-  }
-}
-```
+export default router => {
+  // any proper JavaScript object will be served as JSON
+  router.get("/users", () => [
+    {name: "Donald"},
+    {name: "Ryan"},
+  ]);
 
-Run app
+  // load from a file and serve as JSON
+  router.get("/users-from-file", () => File.json("users.json"));
+};
 
-```
-deno run --import-map=import-map.json app.js
 ```
 
-You will typically need the `allow-read`, `allow-write` and `allow-net`
-permissions.
+### Streams
 
-## Table of Contents
+```js
+import {File} from "runtime-compat/filesystem";
 
-* [Routes](#routes)
-* [Handlers](#handlers)
-* [Components](#components)
+export default router => {
+  // `File` implements `readable`, which is a ReadableStream
+  router.get("/users", () => new File("users.json"));
+};
+
+```
 
-## Routes
+### HTML
 
-Create routes in the `routes` directory by importing and using the `router`
-singleton. You can group your routes across several files or keep them
-in one file.
+Create an HTML component in `components/user-index.html`
 
-### `router[get|post](pathname, request => ...)`
+```html
+<div for="${users}">
+  User ${name}.
+  Email ${email}.
+</div>
 
-Routes are tied to a pathname and execute their callback when the pathname is 
-encountered.
+```
+
+Serve the component in your route
 
 ```js
-// in routes/some-file.js
-import {router, json} from "primate";
+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="${users}" />`;
+  });
+};
 
-// on matching the exact pathname /, returns {"foo": "bar"} as JSON
-router.get("/", () => json`${{"foo": "bar"}}`);
 ```
 
-All routes must return a template function handler. See the
-[section on handlers for common handlers](#handlers).
+## Routing
 
-The callback has one parameter, the request data.
+Routes map requests to responses. All routes are loaded from `routes`.
 
-### The `request` object
+The order in which routes are declared is irrelevant. Redeclaring a route
+(same pathname and same HTTP verb) throws a `RouteError`.
 
-The request contains the `path`, a `/` separated array of the pathname.
+### Basic GET route
 
 ```js
-import {router, html} from "primate";
+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 />`);
+};
 
-router.get("/site/login", request => json`${{"path": request.path}}`);
-// accessing /site/login -> {"path":["site","login"]}
 ```
 
-The HTTP request's body is available under `request.payload`. 
+### Working with the request path
+
+```js
+export default router => {
+  // accessing /site/login will serve `["site", "login"]` as JSON
+  router.get("/site/login", request => request.path);
+};
 
-### Regular expressions in routes
+```
 
-All routes are treated as regular expressions.
+### Regular expressions
 
 ```js
-import {router, json} from "primate";
+export default router => {
+  // accessing /user/view/1234 will serve `1234` as plain text
+  // accessing /user/view/abcd will show a 404 error
+  router.get("/user/view/([0-9])+", request => request[2]);
+};
 
-router.get("/user/view/([0-9])+", request => json`${{"path": request.path}}`);
-// accessing /user/view/1234 -> {"path":["site","login","1234"]}
-// accessing /user/view/abcd -> error 404
 ```
 
-### `router.alias(from, to)`
+### Named groups
+
+```js
+export default router => {
+  // named groups are mapped to properties of `request.named`
+  // accessing /user/view/1234 will serve `1234` as plain text
+  router.get("/user/view/(?<_id>[0-9])+", ({named}) => named._id);
+};
+
+```
 
-To reuse certain parts of a pathname, you can define aliases which will be
-applied before matching.
+### Aliasing
 
 ```js
-import {router, json} from "primate";
+export default router => {
+  // will replace `"_id"` in any path with `"([0-9])+"`
+  router.alias("_id", "([0-9])+");
 
-router.alias("_id", "([0-9])+");
+  // equivalent to `router.get("/user/view/([0-9])+", ...)`
+  // will return id if matched, 404 otherwise
+  router.get("/user/view/_id", request => request.path[2]);
 
-router.get("/user/view/_id", request => json`${{"path": request.path}}`);
+  // can be combined with named groups
+  router.alias("_name", "(<name>[a-z])+");
 
-router.get("/user/edit/_id", request => ...);
-```
+  // will return name if matched, 404 otherwise
+  router.get("/user/view/_name", request => request.named.name);
+};
 
-### `router.map(pathname, request => ...)`
+```
 
-You can reuse functionality across the same path but different HTTP verbs. This
-function has the same signature as `router[get|post]`.
+### Sharing logic across HTTP verbs
 
 ```js
-import {router, html, redirect} from "primate";
+import html from "@primate/html";
+import redirect from "@primate/redirect";
 
-router.alias("_id", "([0-9])+");
+export default router => {
+  // declare `"edit-user"` as alias of `"/user/edit/([0-9])+"`
+  router.alias("edit-user", "/user/edit/([0-9])+");
 
-router.map("/user/edit/_id", request => {
-  const user = {"name": "Donald"};
-  // return original request and user
-  return {...request, user};
-});
+  // pass user instead of request to all verbs with this route
+  router.map("edit-user", () => ({name: "Donald"}));
 
-router.get("/user/edit/_id", request => {
   // show user edit form
-  return html`<user-edit user="${request.user}" />`
-});
+  router.get("edit-user", user => html`<user-edit user="${user}" />`);
 
-router.post("/user/edit/_id", request => {
-  const {user} = request;
-  // verify form and save / show errors
-  return await user.save()
+  // verify form and save, or show errors
+  router.post("edit-user", async user => await user.save()
     ? redirect`/users`
-    : html`<user-edit user="${user}" />`
-});
+    : html`<user-edit user="${user}" />`);
+};
+
 ```
 
-## Handlers
+## Domains
 
-Handlers are tagged template functions usually associated with data.
+Domains represent a collection in a store. All domains are loaded from
+`domains`.
 
-### ``html`<component-name attribute="${value}" />` ``
+A collection is primarily described using the class `fields` property.
 
-Compiles and serves a component from the `components` directory and with the
-specified attributes and their values. Returns an HTTP 200 response with the
-`text/html` content type.
+### Fields
 
-### ``json`${{data}}` ``
+Field types delimit acceptable values for a field.
 
-Serves JSON `data`. Returns an HTTP 200 response with the `application/json`
-content type.
+```js
+import {Domain} from "@primate/domains";
+
+// A basic domain that contains two string 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,
+  };
+}
 
-### ``redirect`${url}` ``
 
-Redirects to `url`. Returns an HTTP 302 response.
+```
 
-## Components
+### Short notation
 
-Create HTML components in the `components` directory. Use attributes to expose
-passed data within your component.
+Field types may be any constructible JavaScript object, including other
+domains. When using other domains as types, data integrity (on saving) is
+ensured.
 
 ```js
-// in routes/user.js
-import {router, html, redirect} from "primate";
-
-router.alias("_id", "([0-9])+");
-
-router.map("/user/edit/_id", request => {
-  const user = {"name": "Donald", "email": "donald@was.here"};
-  // return original request and user
-  return {...request, user};
-});
+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,
+  };
+}
 
-router.get("/user/edit/_id", request => {
-  // show user edit form
-  return html`<user-edit user="${request.user}" />`
-});
-
-router.post("/user/edit/_id", request => {
-  const {user, payload} = request;
-  // verify form and save / show errors
-  // this assumes `user` has a method `save` to verify data
-  return await user.save(payload)
-    ? redirect`/users`
-    : html`<user-edit user="${user}" />`
-});
 ```
 
-```html
-<!-- components/edit-user.html -->
-<form method="post">
-  <h1>Edit user</h1>
-  <p>
-    <input name="name" value="${user.name}"></textarea>
-  </p>
-  <p>
-    <input name="email" value="${user.email}"></textarea>
-  </p>
-  <input type="submit" value="Save user" />
-</form>
-```
+### Predicates
 
-### Grouping objects with `for`
+Field types may also be specified as an array, to specify additional predicates
+aside from the type.
 
-You can use the special attribute `for` to group objects.
+```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"],
+  };
+}
 
-```html
-<!-- components/edit-user.html -->
-<form for="${user}" method="post">
-  <h1>Edit user</h1>
-  <p>
-    <input name="name" value="${name}" />
-  </p>
-  <p>
-    <input name="email" value="${email}" />
-  </p>
-  <input type="submit" value="Save user" />
-</form>
 ```
 
-### Expanding arrays
+## Stores
 
-`for` can also be used to expand arrays.
+Stores interface data. Primate comes with volatile in-memory store used as a
+default. Other stores can be imported as modules.
 
-```js
-// in routes/user.js
-import {router, html} from "primate";
-
-router.get("/users", request => {
-  const users = [
-   {"name": "Donald", "email": "donald@was.here"},
-   {"name": "Ryan", "email": "ryan@was.here"},
-  ];
-  return html`<user-index users="${users}" />`;
-});
-```
-
-```html
-<!-- in components/user-index.html -->
-<div for="${users}">
-  User <span value="${name}"></span>
-  Email <span value="${email}"></span>
-</div>
-```
+All stores are loaded from `stores`.
 
-## Resources
+### Resources
 
-* [Getting started guide][getting-started]
+* Website: https://primatejs.com
+* IRC: Join the `#primate` channel on `irc.libera.chat`.
 
 ## License
 
-BSD-3-Clause
+MIT
 
 [getting-started]: https://primatejs.com/getting-started
 [source-code]: https://github.com/primatejs/primate
@@ -326,3 +316,5 @@ BSD-3-Clause
 [primate-file-store]: https://npmjs.com/primate-file-store
 [primate-json-store]: https://npmjs.com/primate-json-store
 [primate-mongodb-store]: https://npmjs.com/primate-mongodb-store
+[primate-react]: https://github.com/primatejs/primate-react
+[primate-vue]: https://github.com/primatejs/primate-vue