gruber 0.7.0 → 0.9.0-beta.0

package/CHANGELOG.md

@@ -1,7 +1,65 @@
+---
+permalink: /changelog/
+layout: simple.njk
+---
+
 # Change log
 
 This file documents notable changes to the project
 
+## 0.9
+
+**features**
+
+- Add `config.external`
+- Set "dependencies" on HTTP routes that are evaluated on-demand per request
+- Revamp website
+- Start splitting code out into modules
+- [StandardSchema](https://standardschema.dev) support
+- Add `AuthorizationService#from`
+- Add `Structure.null`
+- Add `Structure.any`
+- Add `Structure.partial`
+- Add `Structure.date`
+- `assertRequestBody` can return a Promise if you pass a request,
+  where it will use `getRequestBody` to get the body then validate it
+- Add `createStoppable` to Node.js module and apply it to `serveHTTP`
+- Add `testing` module with utilities, stubs, fakes and a testing router
+
+**improved**
+
+- More test coverage
+- Better deprecation comments with `@link`
+- Add `SqlDependency#end` method
+- Export `SqlDependency`
+- Simplified `Structure` and `config` generics with nested structures
+- Update `urlpattern-polyfill` to 10.1.0
+- Move to erasable TypeScript code
+
+**fixes**
+
+- `AbstractAuthorizationService` includes assert's `options` parameter
+- Configuration correctly follows `flags > env > json > fallback`
+- `Structure.object` sets required fields in schema
+
+**deprecations**
+
+- `StructError` -> `Structure.Error`
+
+## 0.8.0
+
+**features**
+
+- Add optional `options` parameter to `authz.assert` to check the scope
+- Add experimental `authz.from` method to parse the authenticated user
+- Add experimental `CompositeTokens` to combine multiple TokenServices together
+- Add experimental `Cors` utility for addings CORS headers to responses
+- Add experimental `cors` option to `FetchRouter`
+
+**fixes**
+
+- Add optional `res` parameter to `getResponseReadable` to propagate stream cancellations
+
 ## 0.7.0
 
 **new**

package/README.md

@@ -1,3 +1,8 @@
+---
+permalink: /index.html
+layout: home.njk
+---
+
 # Gruber
 
 An isomorphic JavaScript library for creating web apps.
@@ -333,6 +338,13 @@ const struct = config.object({
 			fallback: "postgres://user:secret@localhost:5432/database",
 		}),
 	}),
+
+	auth: config.external(
+		new URL("./auth.json", import.meta.url),
+		config.object({
+			users: Structure.array(Structure.string()),
+		}),
+	),
 });
 
 // Load the configuration and parse it
@@ -867,6 +879,11 @@ Use it to get a `Response` from the provided request, based on the router's rout
 const response = await router.getResponse(new Request("http://localhost"));
 ```
 
+**experimental**
+
+- `options.log` turn on HTTP logging with `true` or a custom
+- `options.cors` apply CORS headers with a [Cors](#cors) instance
+
 #### unstable http
 
 There are some unstable internal methods too:
@@ -877,6 +894,31 @@ There are some unstable internal methods too:
 - `getRequestBody(request)` Get the JSON of FormData body of a request
 - `assertRequestBody(struct, body)` Assert the body matches a structure and return the parsed value
 
+#### Cors
+
+There is an unstable API for applying [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) headers to responses.
+
+```ts
+import { Cors } from "gruber";
+
+const cors = new Cors({
+	credentials: true,
+	origins: ["http://localhost:8080"],
+});
+
+const response = cors.apply(
+	new Request("http://localhsot:8000"),
+	new Response("ok"),
+);
+```
+
+It returns a clone of the response passed to it with CORS headers applied. You should no longer use the response passed into it. The headers it applies are:
+
+- `Access-Control-Allow-Methods` set to `GET, HEAD, PUT, PATCH, POST, DELETE`
+- `Access-Control-Allow-Headers` mirrors what is set on `Access-Control-Request-Headers` and adds that to `Vary`
+- `Access-Control-Allow-Origin` allows the `Origin` if it matches the `origins` parameter
+- `Access-Control-Allow-Credentials` is set to `true` if the `credentials` parameter is
+
 ### Postgres
 
 #### getPostgresMigratorOptions
@@ -1063,16 +1105,16 @@ const redis: RedisClientType;
 const store = new RedisStore(redis, { prefix: "/v2" });
 ```
 
-### JWT
+### Tokens
 
-An abstraction around signing a JWT for a user with an access scope.
+An abstraction around signing or storing a token for a user with an access scope.
 There is currently one implementation using [jose](https://github.com/panva/jose).
 
 ```ts
-import { JoseJwtService } from "gruber";
+import { JoseTokens } from "gruber";
 import * as jose from "jose";
 
-const jwt = new JoseJwtService(
+const jwt = new JoseTokens(
 	{
 		secret: "top_secret",
 		issuer: "myapp.io",
@@ -1091,6 +1133,22 @@ const token = await jwt.sign("user:books:read", {
 const parsed = await jwt.verify(token);
 ```
 
+There is also `CompositeTokens` which lets you combine multiple verifiers with one signer.
+For example, if your app has several methods a client might authenticate and one way it itself signs things,
+like a user token, or a static service or database app-token.
+
+> UNSTABLE
+
+```ts
+import { CompositeTokens, JoseTokens } from "gruber";
+import * as jose from "jose";
+
+const tokens = new CompositeTokens(new JoseTokens("..."), [
+	new JoseTokens("..."),
+	// Different token formats your app accepts
+]);
+```
+
 ### Authorization
 
 > UNSTABLE
@@ -1110,19 +1168,27 @@ const token = authz.getAuthorization(
 	}),
 );
 
-// { userId: number | undefined, scope: string }
+// { kind: 'user', userId: number , scope: string } | { kind: 'service', scope: string }
+const result = await authz.from(
+	new Request("https://example.com", {
+		headers: { Authorization: "Bearer some-long-secure-token" },
+	}),
+);
+
+// { kind: 'user', userId: number , scope: string } | { kind: 'service', scope: string }
 const { userId, scope } = await authz.assert(
 	new Request("https://example.com", {
 		headers: { Authorization: "Bearer some-long-secure-token" },
 	}),
+	{ scope: "repo:coffee-club" }, // optional
 );
 
-// { userId: number, scope: string }
+// { kind: 'user', userId: number, scope: string }
 const { userId, scope } = await authz.assertUser(
 	new Request("https://example.com", {
 		headers: { Cookie: "my_session=some-long-secure-token" },
 	}),
-	{ scope: "user:books:read" },
+	{ scope: "user:books:read" }, // optional
 );
 
 includesScope("user:books:read", "user:books:read"); // true
@@ -1520,11 +1586,18 @@ const server = http.createServer((req) => {
 `getResponseReadable` creates a [streams:Readable](https://nodejs.org/api/stream.html#class-streamreadable) from the body of a fetch Response.
 
 ```js
+import http from "node:http";
 import { getResponseReadable } from "gruber/node-router.js";
 
-const readable = getResponseReadable(new Response("some body"));
+const server = http.createServer((req, res) => {
+	const readable = getResponseReadable(new Response("some body"), res);
+});
 ```
 
+Pass in `res` if you want the readable to be cancelled if reading the response is aborted.
+
+> NOTE: This relies on the **experimental** [Readable.fromWeb](https://nodejs.org/api/stream.html#streamreadablefromwebreadablestream-options)
+
 ## Development
 
 WIP stuff
@@ -1537,6 +1610,7 @@ WIP stuff
    1. `cd bundle/node`
    2. `npm publish`
 4. Copy the deno source to the S3 bucket — `bundle/deno` → `esm.r0b.io/gruber@VERSION/`
+5. Push to GitHub and create a [release](https://github.com/robb-j/gruber/releases/new)
 
 ### nice snippets
 

package/config/README.md

@@ -0,0 +1,10 @@
+---
+permalink: /config/
+layout: simple.njk
+eleventyNavigation:
+  key: Config
+---
+
+# Configuration
+
+Detailled configuration documentation...

package/config/configuration.d.ts

@@ -0,0 +1,33 @@
+import { Structure } from "./structure.ts";
+import { ConfigurationDescription, PrimativeOptions } from "./specifications.ts";
+import { ConfigurationResult } from "./parsers.ts";
+import { StructContext } from "./struct-context.ts";
+export interface ConfigurationOptions {
+    readTextFile(url: URL | string): Promise<string | null>;
+    getEnvironmentVariable(key: string): string | undefined;
+    getCommandArgument(key: string): string | undefined;
+    stringify(value: any): string | Promise<string>;
+    parse(value: string): any;
+}
+export declare class Configuration {
+    static readonly spec: unique symbol;
+    options: ConfigurationOptions;
+    constructor(options: ConfigurationOptions);
+    _loadValue<T>(path: string | URL, structure: Structure<T>, context: StructContext): Promise<T | null>;
+    /** Wrap a primativ Structure with configuration logic */
+    _primative<T>(struct: Structure<T>, options: PrimativeOptions<T>, deconfigure: (result: ConfigurationResult) => unknown): Structure<T>;
+    object<T extends Record<string, unknown>>(fields: {
+        [K in keyof T]: Structure<T[K]>;
+    }): Structure<T>;
+    array<T extends unknown>(item: Structure<T>): Structure<T[]>;
+    external<T extends Record<string, unknown> | Array<unknown>>(path: string | URL, struct: Structure<T>): Structure<T>;
+    string(options: PrimativeOptions<string>): Structure<string>;
+    number(options: PrimativeOptions<number>): Structure<number>;
+    boolean(options: PrimativeOptions<boolean>): Structure<boolean>;
+    url(options: PrimativeOptions<string | URL>): Structure<URL>;
+    load<T>(url: URL | string, struct: Structure<T>): Promise<T>;
+    getUsage(struct: unknown, currentValue?: unknown): string;
+    describe(value: unknown, prefix?: string): ConfigurationDescription;
+    getJSONSchema(struct: Structure<any>): import("./structure.ts").Schema;
+}
+//# sourceMappingURL=configuration.d.ts.map

package/config/configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAS,MAAM,gBAAgB,CAAC;AAElD,OAAO,EAEN,wBAAwB,EAGxB,gBAAgB,EAEhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAKN,mBAAmB,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,WAAW,oBAAoB;IACpC,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACxD,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpD,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC;CAC1B;AAED,qBAAa,aAAa;IACzB,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgC;IAEpD,OAAO,EAAE,oBAAoB,CAAC;gBAElB,OAAO,EAAE,oBAAoB;IAOnC,UAAU,CAAC,CAAC,EACjB,IAAI,EAAE,MAAM,GAAG,GAAG,EAClB,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,aAAa,GACpB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAgBpB,yDAAyD;IACzD,UAAU,CAAC,CAAC,EACX,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EACpB,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,WAAW,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,OAAO;IActD,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE;SAChD,CAAC,IAAI,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;KAC/B,GAAG,SAAS,CAAC,CAAC,CAAC;IAgBhB,KAAK,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC;IAW5D,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,EAC1D,IAAI,EAAE,MAAM,GAAG,GAAG,EAClB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAClB,SAAS,CAAC,CAAC,CAAC;IAgCf,MAAM,CAAC,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;IAkB5D,MAAM,CAAC,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;IAgB5D,OAAO,CAAC,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC;IAgB/D,GAAG,CAAC,OAAO,EAAE,gBAAgB,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC;IAyBtD,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAyBlE,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,OAAO;IAwBhD,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,SAAK,GAAG,wBAAwB;IAM/D,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC;CAGpC"}

package/config/configuration.js

@@ -0,0 +1,181 @@
+import { Structure } from "./structure.js";
+import { formatMarkdownTable, PromiseList } from "../core/mod.js";
+import { arraySpec, getSpecification, objectSpec, primativeSpec, } from "./specifications.js";
+import { _parseBoolean, _parseFloat, _parsePrimative, _parseURL, } from "./parsers.js";
+export class Configuration {
+    static spec = Symbol("configuration.spec");
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    //
+    // Utilities
+    //
+    async _loadValue(path, structure, context) {
+        const text = await this.options.readTextFile(path);
+        // Catch missing files and return null instead, the consumer can decide what to do
+        if (!text)
+            return null;
+        // Parse the text file
+        const value = this.options.parse(text);
+        // Remove the JSON schema field if it is set
+        delete value.$schema;
+        // Process the contents
+        return structure.process(value, context);
+    }
+    /** Wrap a primativ Structure with configuration logic */
+    _primative(struct, options, deconfigure) {
+        return new Structure(struct.schema, (value, context) => {
+            return struct.process(deconfigure(_parsePrimative(this.options, options, value)), context);
+        });
+    }
+    //
+    // Types
+    //
+    object(fields) {
+        if (typeof fields !== "object" || fields === null) {
+            throw new TypeError("options must be a non-null object");
+        }
+        for (const key in fields) {
+            if (!(fields[key] instanceof Structure)) {
+                throw new TypeError(`options[${key}] is not a Structure`);
+            }
+        }
+        const struct = Structure.object(fields);
+        Object.defineProperty(struct, Configuration.spec, {
+            value: objectSpec(fields),
+        });
+        return struct;
+    }
+    array(item) {
+        if (!(item instanceof Structure)) {
+            throw new TypeError("options is not a Structure");
+        }
+        const struct = Structure.array(item);
+        Object.defineProperty(struct, Configuration.spec, {
+            value: arraySpec(item),
+        });
+        return struct;
+    }
+    external(path, struct) {
+        return new Structure(struct.schema, (value, context) => {
+            if (context.type !== "async") {
+                throw new SyntaxError("config.external must be used async");
+            }
+            // Create a dummy value to return for now
+            let internal = struct.schema.type === "array" ? [] : {};
+            // Register a promise to load the actual value
+            context.promises.push(async () => {
+                // Try loading the external value
+                let loaded = await this._loadValue(path, struct, context);
+                // If not found, try the inline value
+                if (loaded === null) {
+                    loaded = struct.process(value, context);
+                }
+                // Apply the value depending if its an array or not
+                // being carful to modifiy the existing reference
+                if (struct.schema.type === "array") {
+                    internal.push(...loaded);
+                }
+                else {
+                    Object.assign(internal, loaded);
+                }
+            });
+            return internal;
+        });
+    }
+    string(options) {
+        if (typeof options.fallback !== "string") {
+            throw new TypeError("options.fallback must be a string");
+        }
+        const struct = this._primative(Structure.string(), options, (result) => result.value);
+        Object.defineProperty(struct, Configuration.spec, {
+            value: primativeSpec("string", options),
+        });
+        return struct;
+    }
+    number(options) {
+        if (typeof options.fallback !== "number") {
+            throw new TypeError("options.fallback must be a number");
+        }
+        const struct = this._primative(Structure.number(), options, (result) => _parseFloat(result));
+        Object.defineProperty(struct, Configuration.spec, {
+            value: primativeSpec("number", options),
+        });
+        return struct;
+    }
+    boolean(options) {
+        if (typeof options?.fallback !== "boolean") {
+            throw new TypeError("options.fallback must be a boolean");
+        }
+        const struct = this._primative(Structure.boolean(), options, (result) => _parseBoolean(result));
+        Object.defineProperty(struct, Configuration.spec, {
+            value: primativeSpec("boolean", options),
+        });
+        return struct;
+    }
+    url(options) {
+        if (typeof options.fallback !== "string" &&
+            !(options.fallback instanceof URL)) {
+            throw new TypeError("options.fallback must be a string or URL");
+        }
+        const opts2 = { ...options, fallback: new URL(options.fallback) };
+        const struct = this._primative(Structure.url(), opts2, (result) => _parseURL(result));
+        Object.defineProperty(struct, Configuration.spec, {
+            value: primativeSpec("url", opts2),
+        });
+        return struct;
+    }
+    //
+    // Methods
+    //
+    async load(url, struct) {
+        const context = {
+            type: "async",
+            path: [],
+            promises: new PromiseList(),
+        };
+        // Fail outside the try-catch to surface structure errors
+        try {
+            let obj = await this._loadValue(url, struct, context);
+            if (!obj)
+                obj = struct.process({}, context);
+            await context.promises.all();
+            return obj;
+        }
+        catch (error) {
+            if (error instanceof Structure.Error) {
+                console.error(error.toFriendlyString());
+            }
+            else {
+                console.error("Configuration failed to parse");
+            }
+            throw error;
+        }
+    }
+    getUsage(struct, currentValue) {
+        const { fallback, fields } = this.describe(struct);
+        const lines = [
+            "Usage:",
+            "",
+            formatMarkdownTable(fields.sort((a, b) => a.name.localeCompare(b.name)), ["name", "type", "flag", "variable", "fallback"], "~"),
+            "",
+            "",
+            "Default:",
+            this.options.stringify(fallback),
+        ];
+        if (currentValue) {
+            lines.push("", "", "Current:", JSON.stringify(currentValue, null, 2));
+        }
+        return lines.join("\n");
+    }
+    describe(value, prefix = "") {
+        const spec = getSpecification(value);
+        if (!spec)
+            return { fallback: undefined, fields: [] };
+        return spec(prefix);
+    }
+    getJSONSchema(struct) {
+        return struct.getSchema();
+    }
+}