@afora/hono 0.0.0-stage → 0.0.3

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# @afora/hono
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [Hono](https://hono.dev) sink for [`@afora/core`](../../README.md) outputs. It turns the operations of an output into a Hono app: validated input, `200` with the response (sensitive values masked), RFC 9457 `application/problem+json` errors, and an OpenAPI document of the same routes. Outputs, stages and `statusOf` are described in [docs/outputs.md](../../docs/outputs.md).
+
+```bash
+bun add @afora/core @afora/hono hono typebox
+```
+
+`@afora/core`, `hono` (`^4.13.14`) and TypeBox (`^1`) are peer dependencies. The package uses only web APIs, so it runs on Bun, Node >= 22 and Workers.
+
+## Example
+
+```ts
+import { outputOf } from "@afora/core";
+import { hono } from "@afora/hono";
+
+const Api = outputOf({
+	name: "Blog",
+	commands: [Users, Posts], // commandOf(...) declarations
+	statuses: { InvalidCredentials: 401, Unauthorized: 401 },
+	pipe: [
+		hono({
+			basePath: "/api",
+			route: { "Posts.list": { method: "get" } },
+			docs: {
+				path: "/openapi.json",
+				info: { title: "Blog", version: "1.0.0" },
+			},
+			context: { headers: { authorization: "authorization" } },
+		}),
+	],
+});
+
+export default Api.build(); // a Hono app: Bun.serve, Workers and `app.request(...)` all take it
+```
+
+```
+POST /api/users/register  { "name": "Ana", "email": "ana@example.com", "plainPassword": "S3cret-pass!" }
+-> 200 { "user": { "name": "Ana", "email": "ana@example.com", "password": "********", ... } }
+
+POST /api/users/login  { "email": "ana@example.com", "plainPassword": "wrong" }
+-> 401 application/problem+json
+   { "type": "urn:afora:exception:InvalidCredentials", "title": "InvalidCredentials",
+     "status": 401, "detail": "Wrong email or password.", "layer": "use-case" }
+
+POST /api/users/register  { "email": "nope" }
+-> 400 application/problem+json  { ..., "issues": [{ "path": ["email"], "code": "...", "message": "..." }] }
+```
+
+## Options
+
+All options are JSON, so the stage can live in an `afora.json` (`{ "sink": "hono", "options": { ... } }`).
+
+| Option     | Meaning                                                                                                                                                                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `basePath` | Prefix of every route, e.g. `"/api"`.                                                                                                                                                                                                      |
+| `route`    | `{ [operationId]: { method?, path? } }`, as in the `openapi` sink.                                                                                                                                                                         |
+| `docs`     | `{ path, info: { title, version, description? }, servers? }`: serves the `openapi` document of the same operations, routes and `basePath` at `path` (not under `basePath`). A `path` that is also a GET route throws `InvalidOutputStage`. |
+| `debug`    | `true` adds the `trace` to problems and the real `detail` to 5xx ones. Off by default.                                                                                                                                                     |
+| `context`  | `{ headers: { [contextKey]: headerName } }`.                                                                                                                                                                                               |
+
+Invalid options throw `InvalidOutputStage` when the stage is made, and unknown operation ids in `route` or two operations on one method and path when the app is built.
+
+## Behavior
+
+- **Routes.** `POST {basePath}/{kebab(command)}/{kebab(operation)}` (`/users/change-password`); `route` changes the method and path. It is the routing of the `openapi` sink (`operationRoutes` in the core), so the served routes and the document agree.
+- **Input.** `post`, `put` and `patch` read a JSON body (an empty body is `{}`; invalid JSON is a 400 `InvalidRequestBody` problem). `get` and `delete` read the query string, converting a value to a number or boolean when the input field takes one rather than a string; anything else is kept for the blueprint to reject. The operation validates the input: a 400 problem with `issues` (`path`, `code`, `message`, no values).
+- **Context.** For an operation whose command or use case declares a `context`, each key listed in `context.headers` is read from its header; a missing header leaves the key out (so an optional key is `undefined`, a required one a 400 problem). Header values are converted like query values.
+- **Success.** `200` with `outputValueOf(response)`: records go through `toJSON`, so sensitive values (a `Password`) are `"********"`.
+- **Errors.** Status from `statusOf(error, operation, output.statuses)`: the output `statuses` first, then 400 for invalid input or context, 404 for a missing entity, 409 for a unique violation, 422 for an error the use case declares, else 500. The body is `problemOf` with `application/problem+json`; a 5xx says `"Internal error."` unless `debug` is on.
+- **Unknown routes** are a `404` problem (`urn:afora:exception:NotFound`) instead of Hono's plain text, and anything thrown outside an operation (your own middleware) is a problem too, through `app.onError`.
+
+## Authentication and custom context
+
+Options are JSON, so there is no callback for the context. Cross-cutting rules such as authentication are a `transform` stage that wraps `invoke`: it sees the context the sink built from headers and can reject the call, which then goes through `statuses` like any other error.
+
+```ts
+import {
+	ExceptionLayers,
+	exceptionOf,
+	operationOf,
+	outputOf,
+	transformOf,
+} from "@afora/core";
+import { hono } from "@afora/hono";
+
+const Unauthorized = exceptionOf({
+	layer: ExceptionLayers.UseCase,
+	name: "Unauthorized",
+	message: "Sign in first.",
+});
+
+// the operation's use case (or command) declares `context: blueprintOf((ctx) => ({ authorization: ctx.optional.string }))`
+export const requireAuth = transformOf({
+	name: "requireAuth",
+	apply: (operation) =>
+		operation.tags.includes("public")
+			? operation
+			: operationOf(operation, {
+					invoke: async (input, call) => {
+						const { authorization } = (call?.context ?? {}) as {
+							authorization?: string;
+						};
+						if (!authorization)
+							throw new Unauthorized({ source: operation.id });
+						// verify the token and put the user into the call, if the context declares it
+						return operation.invoke(input, call);
+					},
+				}),
+});
+
+outputOf({
+	name: "Blog",
+	commands: [Users, Posts],
+	statuses: { Unauthorized: 401 },
+	pipe: [
+		requireAuth(),
+		hono({ context: { headers: { authorization: "authorization" } } }),
+	],
+});
+```
+
+The context only reaches `invoke` for operations that declare one, so the key (`authorization` here) must be in the `context` blueprint of the command or use case.
+
+## Catalog
+
+`HonoStages` is `stageCatalogOf(hono)`, and `stages` are the entries codegen reads to resolve `{ "sink": "hono" }` in an `afora.json`:
+
+```ts
+import { stages } from "@afora/hono";
+// [{ name: "hono", module: "@afora/hono", export: "hono" }]
+```

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { type OpenAPISinkOptions } from "@afora/core";
+import { Hono } from "hono";
+/** The options of the `hono` sink. JSON, so the stage can live in an `afora.json`. */
+export interface HonoOptions {
+    /** Prefix of every route, e.g. `"/api"`. Empty by default. */
+    readonly basePath?: OpenAPISinkOptions["basePath"];
+    /** Method and path by operation id, as in the `openapi` sink. */
+    readonly route?: OpenAPISinkOptions["route"];
+    /** Serves the OpenAPI document of the same operations at `path`. */
+    readonly docs?: {
+        readonly path: string;
+        readonly info: OpenAPISinkOptions["info"];
+        readonly servers?: OpenAPISinkOptions["servers"];
+    };
+    /** Adds the `trace` to problems and the real `detail` to 5xx ones. Off by default. */
+    readonly debug?: boolean;
+    /** The context of an operation, from request headers: `{ headers: { token: "authorization" } }`. */
+    readonly context?: {
+        readonly headers?: {
+            readonly [contextKey: string]: string;
+        };
+    };
+}
+/**
+ * A Hono app that serves the operations: `POST {basePath}/{command}/{operation}`
+ * per operation (kebab-case; `route` changes the method and path as in the
+ * `openapi` sink, so the two documents agree).
+ *
+ * - Body methods read a JSON body, `get` and `delete` the query string, whose
+ *   scalars are coerced to numbers and booleans where the input takes them.
+ *   The input is validated by the operation (a 400 problem with `issues`).
+ * - The context comes from `context.headers` (`{ contextKey: headerName }`);
+ *   a missing header leaves the key out. Anything richer, such as
+ *   authentication, is a `transform` stage that wraps `invoke`.
+ * - Success is a `200` with the response as JSON (`outputValueOf`: sensitive
+ *   values masked). Errors are `application/problem+json`, with the status of
+ *   `statusOf` (the output `statuses` first). An unknown route is a 404
+ *   problem, and anything thrown outside an operation a 500 one.
+ * - `docs.path` serves the `openapi` document of the same operations.
+ */
+export declare const hono: import("@afora/core").SinkFactory<Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">, HonoOptions>;
+/** The runtime catalog of this package: the stage name `hono` resolves to the sink. */
+export declare const HonoStages: import("@afora/core").IStageCatalog<Readonly<Record<string, import("@afora/core").StageFactory>>>;
+/** The catalog entries codegen reads (`--stages @afora/hono`): `{ name, module, export }`. */
+export declare const stages: readonly [{
+    readonly name: "hono";
+    readonly module: "@afora/hono";
+    readonly export: "hono";
+}];

package/dist/index.js

@@ -0,0 +1,199 @@
+// src/index.ts
+import {
+  InvalidOutputStage,
+  openapi,
+  operationRoutes,
+  outputValueOf,
+  PROBLEM_MEDIA_TYPE,
+  problemOf,
+  routeOptionsIssue,
+  sinkOf,
+  stageCatalogOf,
+  statusOf,
+  toOpenAPI
+} from "@afora/core";
+import { Hono } from "hono";
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function onlyKeys(value, allowed, where) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key))
+      return `${where} has no option "${key}".`;
+  }
+  return;
+}
+function validate(options) {
+  const given = options;
+  const bad = onlyKeys(given, ["basePath", "route", "docs", "debug", "context"], "hono");
+  if (bad)
+    return bad;
+  const routing = routeOptionsIssue(options, "hono");
+  if (routing)
+    return routing;
+  if (given.debug !== undefined && typeof given.debug !== "boolean") {
+    return "Expected hono.debug to be a boolean.";
+  }
+  const { docs, context } = given;
+  if (docs !== undefined) {
+    if (!isObject(docs))
+      return "Expected hono.docs to be an object.";
+    const docsBad = onlyKeys(docs, ["path", "info", "servers"], "hono.docs");
+    if (docsBad)
+      return docsBad;
+    if (typeof docs.path !== "string" || !docs.path.startsWith("/") || /[{}?#\s:*]/.test(docs.path)) {
+      return 'Expected hono.docs.path to be a path such as "/openapi.json".';
+    }
+    try {
+      openapi({
+        info: docs.info,
+        ...docs.servers ? { servers: docs.servers } : {}
+      });
+    } catch (error) {
+      const reason = error.details?.reason;
+      return (reason ?? "Expected hono.docs to be valid.").replaceAll("openapi.", "hono.docs.");
+    }
+  }
+  if (context !== undefined) {
+    if (!isObject(context))
+      return "Expected hono.context to be an object.";
+    const contextBad = onlyKeys(context, ["headers"], "hono.context");
+    if (contextBad)
+      return contextBad;
+    const { headers } = context;
+    if (headers !== undefined) {
+      if (!isObject(headers)) {
+        return "Expected hono.context.headers to be an object.";
+      }
+      for (const [key, name] of Object.entries(headers)) {
+        if (typeof name !== "string" || !/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/.test(name)) {
+          return `Expected hono.context.headers["${key}"] to be a header name.`;
+        }
+      }
+    }
+  }
+  return;
+}
+function scalarTypesOf(blueprint) {
+  const schema = toOpenAPI(blueprint);
+  const types = {};
+  for (const [key, property] of Object.entries(schema.properties ?? {})) {
+    types[key] = [property.type ?? []].flat();
+  }
+  return types;
+}
+function coerce(text, types) {
+  if (!types || types.includes("string"))
+    return text;
+  const trimmed = text.trim();
+  if (types.includes("boolean") && (trimmed === "true" || trimmed === "false")) {
+    return trimmed === "true";
+  }
+  if (types.includes("integer") || types.includes("number")) {
+    const number = trimmed === "" ? Number.NaN : Number(trimmed);
+    if (Number.isFinite(number))
+      return number;
+  }
+  return text;
+}
+function coerceAll(values, types) {
+  const out = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (value !== undefined)
+      out[key] = coerce(value, types[key]);
+  }
+  return out;
+}
+function problemResponse(body, status) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": PROBLEM_MEDIA_TYPE }
+  });
+}
+function requestProblem(title, detail) {
+  return problemResponse({ type: `urn:afora:exception:${title}`, title, status: 400, detail }, 400);
+}
+var hono = sinkOf({
+  name: "hono",
+  validate,
+  build: (operations, options, { output }) => {
+    const routes = operationRoutes(operations, options, "hono");
+    const debug = options.debug === true;
+    const headers = options.context?.headers ?? {};
+    const app = new Hono;
+    const fail = (error, operation) => {
+      const status = statusOf(error, operation, output.statuses);
+      return problemResponse(problemOf(error, { status, debug }), status);
+    };
+    app.notFound(() => problemResponse({
+      type: "urn:afora:exception:NotFound",
+      title: "NotFound",
+      status: 404,
+      detail: "No operation is served at this method and path."
+    }, 404));
+    app.onError((error) => fail(error));
+    for (const operation of operations) {
+      const { method, path } = routes.get(operation.id);
+      const hasBody = method !== "get" && method !== "delete";
+      const inputTypes = hasBody ? {} : scalarTypesOf(operation.input);
+      const contextKeys = operation.context ? Object.keys(operation.context.properties).filter((key) => Object.hasOwn(headers, key)) : [];
+      const contextTypes = operation.context ? scalarTypesOf(operation.context) : {};
+      app.on(method.toUpperCase(), path, async (c) => {
+        let input;
+        if (hasBody) {
+          const text = await c.req.text();
+          try {
+            input = text.trim() === "" ? {} : JSON.parse(text);
+          } catch {
+            return requestProblem("InvalidRequestBody", "The request body is not valid JSON.");
+          }
+        } else {
+          input = coerceAll(c.req.query(), inputTypes);
+        }
+        const call = {};
+        if (operation.context) {
+          const raw = {};
+          for (const key of contextKeys) {
+            raw[key] = c.req.header(headers[key]) ?? undefined;
+          }
+          call.context = coerceAll(raw, contextTypes);
+        }
+        try {
+          const response = await operation.invoke(input, call);
+          return c.json(outputValueOf(response) ?? null, 200);
+        } catch (error) {
+          return fail(error, operation);
+        }
+      });
+    }
+    if (options.docs) {
+      const { path, info, servers } = options.docs;
+      const taken = [...routes.values()].some((route) => route.method === "get" && route.path === path);
+      if (taken) {
+        throw new InvalidOutputStage({
+          source: "hono",
+          details: {
+            reason: `hono.docs.path "${path}" collides with a GET operation route.`
+          }
+        });
+      }
+      const document = openapi({
+        info,
+        ...servers ? { servers } : {},
+        ...options.basePath ? { basePath: options.basePath } : {},
+        ...options.route ? { route: options.route } : {}
+      }).build(operations, { output });
+      app.get(path, (c) => c.json(document));
+    }
+    return app;
+  }
+});
+var HonoStages = stageCatalogOf(hono);
+var stages = [
+  { name: "hono", module: "@afora/hono", export: "hono" }
+];
+export {
+  HonoStages,
+  hono,
+  stages
+};

package/package.json

@@ -1,6 +1,60 @@
 {
-  "name": "@afora/hono",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@afora/hono",
+	"version": "0.0.3",
+	"description": "A Hono sink for afora outputs: one route per operation, problem+json errors, sensitive data masked and an optional OpenAPI document.",
+	"keywords": [
+		"afora",
+		"hono",
+		"openapi",
+		"problem-json",
+		"http",
+		"api"
+	],
+	"author": "Alan Reis <alanreisanjo@gmail.com> (https://github.com/Hoyasumii)",
+	"license": "MIT",
+	"homepage": "https://github.com/afora-framework/core/tree/main/packages/hono#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/afora-framework/core.git",
+		"directory": "packages/hono"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"bun": ">=1.4.4",
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"typecheck": "bun check",
+		"build": "rm -rf dist && bun build ./src/index.ts --outdir ./dist --target node --format esm --packages external --tsconfig-override tsconfig.build.json && tsc -p tsconfig.build.json && bun ../../scripts/add-dts-extensions.ts dist",
+		"test": "bun test"
+	},
+	"devDependencies": {
+		"@seriousme/openapi-schema-validator": "2.11.0",
+		"@types/bun": "^1.4.4",
+		"hono": "^4.13.14",
+		"typebox": "^1.4.3"
+	},
+	"peerDependencies": {
+		"@afora/core": ">=0.0.1",
+		"hono": "^4.13.14",
+		"typebox": "^1"
+	}
+}