primate 0.15.0 → 0.15.2

package/README.md

@@ -4,16 +4,20 @@ Expressive, minimal and extensible framework for JavaScript.
 
 ## Getting started
 
-Create a route in `routes/hello.js`
+Run `npx -y primate@latest create` to create a project structure.
+
+Create a route in `routes/index.js`
 
 ```js
-export default router => {
-  router.get("/", () => "Hello, world!");
+export default {
+  get() {
+    return "Hello, world!";
+  },
 };
 
 ```
 
-Add `{"type": "module"}` to your `package.json` and run `npx -y primate@latest`.
+Run `npm i && npm start` and visit `localhost:6161` in your browser.
 
 ## Table of Contents
 
@@ -27,22 +31,22 @@ Add `{"type": "module"}` to your `package.json` and run `npx -y primate@latest`.
   - [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)
+  - [Parameterized routes](#parameterized-routes)
   - [Explicit handlers](#explicit-handlers)
 
 ## Serving content
 
-Create a file in `routes` that exports a default function.
+Create a file in `routes/index.js` to handle the special `/` route.
 
 ### Plain text
 
 ```js
-export default router => {
-  // Serve strings as plain text
-  router.get("/user", () => "Donald");
+// routes/index.js handles the `/` route
+export default {
+  get() {
+    // strings are served as plain text
+    return "Donald";
+  },
 };
 
 ```
@@ -50,17 +54,15 @@ export default router => {
 ### JSON
 
 ```js
-import {File} from "runtime-compat/filesystem";
-
-export default router => {
-  // Serve proper JavaScript objects as JSON
-  router.get("/users", () => [
-    {name: "Donald"},
-    {name: "Ryan"},
-  ]);
-
-  // Load from file and serve as JSON
-  router.get("/users-from-file", () => File.json("users.json"));
+// routes/index.js handles the `/` route
+export default {
+  get() {
+    // proper JavaScript objects are served as JSON
+    return [
+      {name: "Donald"},
+      {name: "Ryan"},
+    ];
+  },
 };
 
 ```
@@ -70,9 +72,12 @@ export default router => {
 ```js
 import {File} from "runtime-compat/filesystem";
 
-export default router => {
-  // `File` implements `readable`, which is a `ReadableStream`
-  router.get("/users", () => new File("users.json"));
+// routes/index.js handles the `/` route
+export default {
+  get() {
+    // ReadableStream or Blob objects are streamed to the client
+    return new File("users.json");
+  },
 };
 
 ```
@@ -82,9 +87,12 @@ export default router => {
 ```js
 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}));
+// routes/index.js handles the `/` route
+export default {
+  get() {
+    // use a Response object for custom response status
+    return new Response("created!", {status: 201});
+  },
 };
 
 ```
@@ -92,31 +100,43 @@ export default router => {
 ### HTML
 
 ```js
-// 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"));
-
-  // 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}));
+import {html} from "primate";
+
+// routes/index.js handles the `/` route
+export default {
+  get() {
+    // to serve HTML, import and use the html handler
+    return html("<p>Hello, world!</p>");
+  },
 };
 
 ```
 
 ## Routing
 
-Routes map requests to responses. They are loaded from `routes`.
+Primate uses filesystem-based routes. Every path a client accesses is mapped to 
+a route under `routes`.
+
+* `index.js` handles the root route (`/`)
+* `post.js` handles the `/post` route
+* `post/{postId}.js` handles a parameterized route where `{postId}` can
+  be mapped to anything, such as `/post/1`
 
 ### Basic
 
 ```js
-export default router => {
-  // accessing /site/login will serve `Hello, world!` as plain text
-  router.get("/site/login", () => "Hello, world!");
+import {redirect} from "primate";
+
+// routes/site/login.js handles the `/site/login` route
+export default {
+  get() {
+    // strings are served as plain text
+    return "Hello, world!";
+  },
+  // other HTTP verbs are also available
+  post() {
+    return redirect("/");
+  },
 };
 
 ```
@@ -124,9 +144,12 @@ export default router => {
 ### The request object
 
 ```js
-export default router => {
-  // accessing /site/login will serve `["site", "login"]` as JSON
-  router.get("/site/login", request => request.path);
+// routes/site/login.js handles the `/site/login` route
+export default {
+  get(request) {
+    // will serve `["site", "login"]` as JSON
+    return request.path;
+  },
 };
 
 ```
@@ -139,85 +162,41 @@ to the content type sent along the request. Currently supported are
 `application/json`.
 
 ```js
-export default router => {
-  router.post("/site/login", ({body}) => `submitted user: ${body.username}`);
-};
-
-```
-
-### Regular expressions
-
-```js
-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]);
-};
-
-```
-
-### 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);
-};
-
-```
-
-### Aliasing
-
-```js
-export default router => {
-  // will replace `"_id"` in any path with `"([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]);
-
-  // can be combined with named groups
-  router.alias("_name", "(?<name>[a-z])+");
-
-  // will return name if matched, 404 otherwise
-  router.get("/user/view/_name", request => request.named.name);
+// routes/site/login.js handles the `/site/login` route
+export default {
+  get(request) {
+    return `username submitted: ${request.body.username}`;
+  },
 };
 
 ```
 
-### Sharing logic across requests
+### Parameterized routes
 
 ```js
-export default router => {
-  // Declare `"edit-user"` as alias of `"/user/edit/([0-9])+"`
-  router.alias("edit-user", "/user/edit/([0-9])+");
-
-  // Pass user instead of request to all verbs on this route
-  router.map("edit-user", ({body}) => body?.name ?? "Donald");
-
-  // Show user as plain text
-  router.get("edit-user", user => user);
-
-  // Verify or show error
-  router.post("edit-user", user => user === "Donald"
-    ? "Hi Donald!"
-    : {message: "Error saving user"});
+// routes/user/{userId}.js handles all routes of the sort `/user/{userId}`
+// where {userId} can be anything
+export default {
+  get(request) {
+    return `user id: ${request.named.userId}`;
+  },
 };
 
 ```
 
 ### Explicit handlers
 
-Most often we can figure out 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.
+Often we can figure out the content type to respond with based on the return
+type from the handler. For other cases, we need to use an explicit handler.
 
 ```js
-export default (router, {redirect}) => {
-  // redirect from source to target
-  router.get("/source", () => redirect("/target"));
+import {redirect} from "primate";
+
+// routes/source.js handles the `/source` route
+export default {
+  get() {
+    return redirect("/target");
+  },
 };
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primate",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "Expressive, minimal and extensible framework for JavaScript",
   "homepage": "https://primatejs.com",
   "bugs": "https://github.com/primatejs/primate/issues",

package/eslint.config.js

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

package/module.json

@@ -1,15 +0,0 @@
-{
-  "name": "primate",
-  "version": "0.13.0",
-  "description": "Expressive, minimal and extensible framework for JavaScript",
-  "homepage": "https://primatejs.com",
-  "bugs": "https://github.com/primatejs/primate/issues",
-  "license": "MIT",
-  "bin": "src/bin.js",
-  "repository": "https://github.com/primatejs/primate",
-  "scripts": {
-    "docs": "scripts/docs.sh",
-    "test": "npx debris",
-    "lint": "npx eslint ."
-  }
-}

package/readme/components/edit-user-for.html

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

package/readme/components/edit-user.html

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

package/readme/components/user-index.html

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

package/readme/components/users.html

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

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

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

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

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

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

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

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

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

package/readme/extensions/modules/configure.js

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

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

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

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

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

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

@@ -1,14 +0,0 @@
-import {Domain} from "@primate/domains";
-import House from "./House.js";
-
-export default class User extends Domain {
-  static fields = {
-    // a user's name is a string unique across the user collection
-    name: [String, "unique"],
-    // a user's age is a positive integer
-    age: [Number, "integer", "positive"],
-    // 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/extensions/modules/domains/short-field-notation.js

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

package/readme/getting-started.js

@@ -1,3 +0,0 @@
-export default router => {
-  router.get("/", () => "Hello, world!");
-};

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

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

package/readme/routing/aliasing.js

@@ -1,14 +0,0 @@
-export default router => {
-  // will replace `"_id"` in any path with `"([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]);
-
-  // can be combined with named groups
-  router.alias("_name", "(?<name>[a-z])+");
-
-  // will return name if matched, 404 otherwise
-  router.get("/user/view/_name", request => request.named.name);
-};

package/readme/routing/basic.js

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

package/readme/routing/explicit-handlers.js

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

package/readme/routing/named-groups.js

@@ -1,5 +0,0 @@
-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);
-};

package/readme/routing/regular-expressions.js

@@ -1,5 +0,0 @@
-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]);
-};

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

@@ -1,15 +0,0 @@
-export default router => {
-  // Declare `"edit-user"` as alias of `"/user/edit/([0-9])+"`
-  router.alias("edit-user", "/user/edit/([0-9])+");
-
-  // Pass user instead of request to all verbs on this route
-  router.map("edit-user", ({body}) => body?.name ?? "Donald");
-
-  // Show user as plain text
-  router.get("edit-user", user => user);
-
-  // Verify or show error
-  router.post("edit-user", user => user === "Donald"
-    ? "Hi Donald!"
-    : {message: "Error saving user"});
-};

package/readme/routing/the-request-object.js

@@ -1,4 +0,0 @@
-export default router => {
-  // accessing /site/login will serve `["site", "login"]` as JSON
-  router.get("/site/login", request => request.path);
-};

package/readme/serving-content/html.js

@@ -1,12 +0,0 @@
-// 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"));
-
-  // 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 +0,0 @@
-import {File} from "runtime-compat/filesystem";
-
-export default router => {
-  // Serve proper JavaScript objects as JSON
-  router.get("/users", () => [
-    {name: "Donald"},
-    {name: "Ryan"},
-  ]);
-
-  // 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 +0,0 @@
-export default router => {
-  // Serve strings as plain text
-  router.get("/user", () => "Donald");
-};

package/readme/serving-content/response.js

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

package/readme/template.md

@@ -1,135 +0,0 @@
-# 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 out 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

package/scripts/docs.sh

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

package/src/extend.spec.js

@@ -1,103 +0,0 @@
-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("config enhancement", assert => {
-    const base = {
-      base: "/",
-      debug: false,
-      defaults: {
-        action: "index",
-        context: "guest",
-      },
-      paths: {
-        public: "public",
-        static: "static",
-        routes: "routes",
-        components: "components",
-      },
-    };
-
-    const additional = {
-      debug: true,
-      environment: "testing",
-      defaults: {
-        context: "user",
-        mode: "operational",
-      },
-      paths: {
-        client: "client",
-      },
-    };
-
-    const extended = {
-      base: "/",
-      debug: true,
-      environment: "testing",
-      defaults: {
-        action: "index",
-        context: "user",
-        mode: "operational",
-      },
-      paths: {
-        client: "client",
-        public: "public",
-        static: "static",
-        routes: "routes",
-        components: "components",
-      },
-    };
-
-    assert(extend(base, additional)).equals(extended);
-  });
-};