@definitely-fine/hono 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 definitely-fine contributors
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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

@@ -0,0 +1,137 @@
+# @definitely-fine/hono
+
+`@definitely-fine/hono` connects `definitely-fine` scenario context to Hono request handling.
+
+It reads a scenario id from a request header and runs Hono handlers or middleware inside that active scenario context.
+
+## Installation
+
+```bash
+pnpm add definitely-fine @definitely-fine/hono hono
+```
+
+## Important
+
+> [!IMPORTANT]
+> Do not leave scenario activation enabled in production by accident.
+>
+> `@definitely-fine/hono` will activate scenario context whenever the request header is present.
+> In production, pair this package with `createRuntime({ enabled: false })` in your core runtime, or avoid installing the middleware and wrappers there entirely.
+
+Core runtime protection:
+
+```ts
+import { createRuntime } from "definitely-fine";
+
+const runtime = createRuntime<DemoContract>({
+  enabled: process.env.NODE_ENV !== "production",
+});
+```
+
+Optional middleware guard:
+
+```ts
+import { Hono } from "hono";
+import { definitelyFineScenarioMiddleware } from "@definitely-fine/hono";
+
+const app = new Hono();
+
+if (process.env.NODE_ENV !== "production") {
+  app.use("*", definitelyFineScenarioMiddleware());
+}
+```
+
+## What This Package Does
+
+This package does not replace the core runtime. You still create your scenarios and wrapped runtime with `definitely-fine`.
+
+Its job is narrower:
+
+- define the scenario header name constant
+- read that header from `Headers`, `Request`, or Hono `Context`
+- run Hono handlers or middleware inside `runWithRuntimeScenarioContext()`
+
+```mermaid
+flowchart LR
+  subgraph C[Client or browser process]
+    C1[request]
+    C2[x-definitely-fine-scenario-id header]
+  end
+
+  subgraph H[Hono server process]
+    H1[@definitely-fine/hono middleware or handler wrapper]
+    H2[runWithRuntimeScenarioContext]
+    H3[definitely-fine runtime]
+    H4[wrapped app service or function]
+  end
+
+  subgraph S[Shared scenario storage]
+    S1[(persisted scenario JSON)]
+  end
+
+  C1 --> C2 --> H1
+  H1 --> H2 --> H3 --> H4
+  H3 -- load active scenario --> S1
+```
+
+## App Middleware
+
+Use `definitelyFineScenarioMiddleware()` when you want one app-level middleware instead of wrapping every route.
+
+```ts
+import { Hono } from "hono";
+import { definitelyFineScenarioMiddleware } from "@definitely-fine/hono";
+
+const app = new Hono();
+
+app.use("*", definitelyFineScenarioMiddleware());
+```
+
+Downstream handlers then run inside the matching scenario automatically when the request includes the scenario header.
+
+## Route Handlers
+
+Use `withDefinitelyFineScenario()` when you want to scope scenario activation to a specific Hono handler.
+
+```ts
+import { Hono } from "hono";
+import { withDefinitelyFineScenario } from "@definitely-fine/hono";
+
+import { incrementCounter } from "../lib/demo-runtime";
+
+const app = new Hono();
+
+app.post(
+  "/api/counter",
+  withDefinitelyFineScenario((context) => {
+    return context.json(incrementCounter());
+  }),
+);
+```
+
+If the request does not include the scenario header, the handler runs normally.
+
+## Header Name
+
+The exported header constant is `DEFINITELY_FINE_SCENARIO_HEADER`.
+
+```ts
+import { DEFINITELY_FINE_SCENARIO_HEADER } from "@definitely-fine/hono";
+
+const headers = {
+  [DEFINITELY_FINE_SCENARIO_HEADER]: "scenario-id",
+};
+```
+
+## Typical Setup
+
+1. Create and save a scenario with `definitely-fine`.
+2. Add `definitelyFineScenarioMiddleware()` at app level, or wrap specific handlers with `withDefinitelyFineScenario()`.
+3. Send the scenario id in the request header.
+4. Let your core runtime wrappers decide which calls are intercepted.
+
+For safety, production apps should normally disable the core runtime with `enabled: false` and optionally skip this middleware or these wrappers entirely.
+
+## With Playwright
+
+This package pairs naturally with [`@definitely-fine/playwright`](../playwright/README.md), which can create browser contexts that already include the scenario header.

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import { Context, Env, Handler, Input, MiddlewareHandler } from "hono";
+import { HandlerResponse } from "hono/types";
+
+//#region src/index.d.ts
+/**
+* Header name used to carry the active definitely-fine scenario id.
+* @public
+*/
+/**
+ * Header name used to carry the active definitely-fine scenario id.
+ * @public
+ */
+declare const DEFINITELY_FINE_SCENARIO_HEADER = "x-definitely-fine-scenario-id";
+/**
+ * Returns the raw definitely-fine scenario header value from a `Headers` object.
+ * @public
+ *
+ * @example
+ * ```ts
+ * const scenarioId = getScenarioIdFromHeaders(
+ *   new Headers([[DEFINITELY_FINE_SCENARIO_HEADER, "checkout"]]),
+ * );
+ * ```
+ */
+declare function getScenarioIdFromHeaders(headers: Headers): string | undefined;
+/**
+ * Returns the raw definitely-fine scenario header value from a `Request`.
+ * @public
+ *
+ * @example
+ * ```ts
+ * const scenarioId = getScenarioIdFromRequest(
+ *   new Request("https://example.test", {
+ *     headers: {
+ *       [DEFINITELY_FINE_SCENARIO_HEADER]: "checkout",
+ *     },
+ *   }),
+ * );
+ * ```
+ */
+declare function getScenarioIdFromRequest(request: Request): string | undefined;
+/**
+ * Returns the raw definitely-fine scenario header value from a Hono `Context`.
+ * @public
+ *
+ * @example
+ * ```ts
+ * app.get("/demo", (context) => {
+ *   return context.text(getScenarioIdFromContext(context) ?? "none");
+ * });
+ * ```
+ */
+declare function getScenarioIdFromContext<TEnv extends Env, TPath extends string, TInput extends Input>(context: Context<TEnv, TPath, TInput>): string | undefined;
+/**
+ * Wraps a Hono handler or middleware so it runs inside definitely-fine scenario context.
+ * @public
+ *
+ * @example
+ * ```ts
+ * const handler = withDefinitelyFineScenario((context) => {
+ *   return context.json({ ok: true });
+ * });
+ * ```
+ */
+declare function withDefinitelyFineScenario<TEnv extends Env, TPath extends string, TInput extends Input, TResult extends HandlerResponse<unknown>>(handler: Handler<TEnv, TPath, TInput, TResult>): Handler<TEnv, TPath, TInput, TResult>;
+declare function withDefinitelyFineScenario<TEnv extends Env, TPath extends string, TInput extends Input, TResult extends HandlerResponse<unknown>>(handler: MiddlewareHandler<TEnv, TPath, TInput, TResult>): MiddlewareHandler<TEnv, TPath, TInput, TResult>;
+/**
+ * Creates Hono middleware that activates definitely-fine scenario context for downstream handlers.
+ * @public
+ *
+ * @example
+ * ```ts
+ * const app = new Hono();
+ *
+ * app.use("*", definitelyFineScenarioMiddleware());
+ * ```
+ */
+declare function definitelyFineScenarioMiddleware<TEnv extends Env, TPath extends string = string, TInput extends Input = Input>(): MiddlewareHandler<TEnv, TPath, TInput>;
+
+//#endregion
+//# sourceMappingURL=index.d.ts.map
+
+export { DEFINITELY_FINE_SCENARIO_HEADER, definitelyFineScenarioMiddleware, getScenarioIdFromContext, getScenarioIdFromHeaders, getScenarioIdFromRequest, withDefinitelyFineScenario };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"sourcesContent":null,"mappings":";;;;;;;;;;;;cAgBa,+BAAA;;AAAb;;;;;;;;;;iBAagB,wBAAA,UAAkC;;AAAlD;;;;;;;;;;;;;;iBAmBgB,wBAAA,UAAkC;;AAAlD;;;;;;;;;;iBAegB,sCACD,0CAEE,gBACN,QAAQ,MAAM,OAAO;;AAJhC;;;;;;;;AAIkB;;iBAeF,wCACD,0CAEE,uBACC,mCAEP,QAAQ,MAAM,OAAO,QAAQ,WACrC,QAAQ,MAAM,OAAO,QAAQ;iBAChB,wCACD,0CAEE,uBACC,mCAEP,kBAAkB,MAAM,OAAO,QAAQ,WAC/C,kBAAkB,MAAM,OAAO,QAAQ;;;;;;;;;AAf1C;;;AAGiB,iBAkDD,gCAlDC,CAAA,aAmDF,GAnDE,EAAA,cAAA,MAAA,GAAA,MAAA,EAAA,eAqDA,KArDA,GAqDQ,KArDR,CAAA,CAAA,CAAA,EAsDZ,iBAtDY,CAsDM,IAtDN,EAsDY,KAtDZ,EAsDmB,MAtDnB,CAAA"}

package/dist/index.js

@@ -0,0 +1,83 @@
+import { runWithRuntimeScenarioContext } from "definitely-fine";
+
+//#region src/index.ts
+/**
+* Header name used to carry the active definitely-fine scenario id.
+* @public
+*/
+const DEFINITELY_FINE_SCENARIO_HEADER = "x-definitely-fine-scenario-id";
+/**
+* Returns the raw definitely-fine scenario header value from a `Headers` object.
+* @public
+*
+* @example
+* ```ts
+* const scenarioId = getScenarioIdFromHeaders(
+*   new Headers([[DEFINITELY_FINE_SCENARIO_HEADER, "checkout"]]),
+* );
+* ```
+*/
+function getScenarioIdFromHeaders(headers) {
+	return headers.get(DEFINITELY_FINE_SCENARIO_HEADER) ?? void 0;
+}
+/**
+* Returns the raw definitely-fine scenario header value from a `Request`.
+* @public
+*
+* @example
+* ```ts
+* const scenarioId = getScenarioIdFromRequest(
+*   new Request("https://example.test", {
+*     headers: {
+*       [DEFINITELY_FINE_SCENARIO_HEADER]: "checkout",
+*     },
+*   }),
+* );
+* ```
+*/
+function getScenarioIdFromRequest(request) {
+	return getScenarioIdFromHeaders(request.headers);
+}
+/**
+* Returns the raw definitely-fine scenario header value from a Hono `Context`.
+* @public
+*
+* @example
+* ```ts
+* app.get("/demo", (context) => {
+*   return context.text(getScenarioIdFromContext(context) ?? "none");
+* });
+* ```
+*/
+function getScenarioIdFromContext(context) {
+	return getScenarioIdFromRequest(context.req.raw);
+}
+function withDefinitelyFineScenario(handler) {
+	return function definitelyFineHonoHandler(context, next) {
+		const scenarioId = getScenarioIdFromContext(context);
+		if (scenarioId === void 0) return handler(context, next);
+		return runWithRuntimeScenarioContext({ scenarioId }, () => {
+			return handler(context, next);
+		});
+	};
+}
+/**
+* Creates Hono middleware that activates definitely-fine scenario context for downstream handlers.
+* @public
+*
+* @example
+* ```ts
+* const app = new Hono();
+*
+* app.use("*", definitelyFineScenarioMiddleware());
+* ```
+*/
+function definitelyFineScenarioMiddleware() {
+	return withDefinitelyFineScenario(async (_context, next) => {
+		await next();
+	});
+}
+
+//#endregion
+export { DEFINITELY_FINE_SCENARIO_HEADER, definitelyFineScenarioMiddleware, getScenarioIdFromContext, getScenarioIdFromHeaders, getScenarioIdFromRequest, withDefinitelyFineScenario };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["headers: Headers","request: Request","context: Context<TEnv, TPath, TInput>","handler:\n    | Handler<TEnv, TPath, TInput, TResult>\n    | MiddlewareHandler<TEnv, TPath, TInput, TResult>","next: Next"],"sources":["../src/index.ts"],"sourcesContent":["import { runWithRuntimeScenarioContext } from \"definitely-fine\";\n\nimport type {\n  Context,\n  Env,\n  Handler,\n  Input,\n  MiddlewareHandler,\n  Next,\n} from \"hono\";\nimport type { HandlerResponse } from \"hono/types\";\n\n/**\n * Header name used to carry the active definitely-fine scenario id.\n * @public\n */\nexport const DEFINITELY_FINE_SCENARIO_HEADER = \"x-definitely-fine-scenario-id\";\n\n/**\n * Returns the raw definitely-fine scenario header value from a `Headers` object.\n * @public\n *\n * @example\n * ```ts\n * const scenarioId = getScenarioIdFromHeaders(\n *   new Headers([[DEFINITELY_FINE_SCENARIO_HEADER, \"checkout\"]]),\n * );\n * ```\n */\nexport function getScenarioIdFromHeaders(headers: Headers): string | undefined {\n  return headers.get(DEFINITELY_FINE_SCENARIO_HEADER) ?? undefined;\n}\n\n/**\n * Returns the raw definitely-fine scenario header value from a `Request`.\n * @public\n *\n * @example\n * ```ts\n * const scenarioId = getScenarioIdFromRequest(\n *   new Request(\"https://example.test\", {\n *     headers: {\n *       [DEFINITELY_FINE_SCENARIO_HEADER]: \"checkout\",\n *     },\n *   }),\n * );\n * ```\n */\nexport function getScenarioIdFromRequest(request: Request): string | undefined {\n  return getScenarioIdFromHeaders(request.headers);\n}\n\n/**\n * Returns the raw definitely-fine scenario header value from a Hono `Context`.\n * @public\n *\n * @example\n * ```ts\n * app.get(\"/demo\", (context) => {\n *   return context.text(getScenarioIdFromContext(context) ?? \"none\");\n * });\n * ```\n */\nexport function getScenarioIdFromContext<\n  TEnv extends Env,\n  TPath extends string,\n  TInput extends Input,\n>(context: Context<TEnv, TPath, TInput>): string | undefined {\n  return getScenarioIdFromRequest(context.req.raw);\n}\n\n/**\n * Wraps a Hono handler or middleware so it runs inside definitely-fine scenario context.\n * @public\n *\n * @example\n * ```ts\n * const handler = withDefinitelyFineScenario((context) => {\n *   return context.json({ ok: true });\n * });\n * ```\n */\nexport function withDefinitelyFineScenario<\n  TEnv extends Env,\n  TPath extends string,\n  TInput extends Input,\n  TResult extends HandlerResponse<unknown>,\n>(\n  handler: Handler<TEnv, TPath, TInput, TResult>,\n): Handler<TEnv, TPath, TInput, TResult>;\nexport function withDefinitelyFineScenario<\n  TEnv extends Env,\n  TPath extends string,\n  TInput extends Input,\n  TResult extends HandlerResponse<unknown>,\n>(\n  handler: MiddlewareHandler<TEnv, TPath, TInput, TResult>,\n): MiddlewareHandler<TEnv, TPath, TInput, TResult>;\nexport function withDefinitelyFineScenario<\n  TEnv extends Env,\n  TPath extends string,\n  TInput extends Input,\n  TResult extends HandlerResponse<unknown>,\n>(\n  handler:\n    | Handler<TEnv, TPath, TInput, TResult>\n    | MiddlewareHandler<TEnv, TPath, TInput, TResult>,\n) {\n  return function definitelyFineHonoHandler(\n    context: Context<TEnv, TPath, TInput>,\n    next: Next,\n  ): TResult | Promise<TResult | void> {\n    const scenarioId = getScenarioIdFromContext(context);\n\n    if (scenarioId === undefined) {\n      return handler(context, next);\n    }\n\n    return runWithRuntimeScenarioContext({ scenarioId }, () => {\n      return handler(context, next);\n    });\n  };\n}\n\n/**\n * Creates Hono middleware that activates definitely-fine scenario context for downstream handlers.\n * @public\n *\n * @example\n * ```ts\n * const app = new Hono();\n *\n * app.use(\"*\", definitelyFineScenarioMiddleware());\n * ```\n */\nexport function definitelyFineScenarioMiddleware<\n  TEnv extends Env,\n  TPath extends string = string,\n  TInput extends Input = Input,\n>(): MiddlewareHandler<TEnv, TPath, TInput> {\n  return withDefinitelyFineScenario(async (_context, next) => {\n    await next();\n  });\n}\n"],"mappings":";;;;;;;AAgBA,MAAa,kCAAkC;;;;;;;;;;;;AAa/C,SAAgB,yBAAyBA,SAAsC;AAC7E,QAAO,QAAQ,IAAI,gCAAgC;AACpD;;;;;;;;;;;;;;;;AAiBD,SAAgB,yBAAyBC,SAAsC;AAC7E,QAAO,yBAAyB,QAAQ,QAAQ;AACjD;;;;;;;;;;;;AAaD,SAAgB,yBAIdC,SAA2D;AAC3D,QAAO,yBAAyB,QAAQ,IAAI,IAAI;AACjD;AA6BD,SAAgB,2BAMdC,SAGA;AACA,QAAO,SAAS,0BACdD,SACAE,MACmC;EACnC,MAAM,aAAa,yBAAyB,QAAQ;AAEpD,MAAI,sBACF,QAAO,QAAQ,SAAS,KAAK;AAG/B,SAAO,8BAA8B,EAAE,WAAY,GAAE,MAAM;AACzD,UAAO,QAAQ,SAAS,KAAK;EAC9B,EAAC;CACH;AACF;;;;;;;;;;;;AAaD,SAAgB,mCAI4B;AAC1C,QAAO,2BAA2B,OAAO,UAAU,SAAS;AAC1D,QAAM,MAAM;CACb,EAAC;AACH"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@definitely-fine/hono",
+  "version": "0.1.0",
+  "description": "Hono adapter for definitely-fine.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "definitely-fine": "0.1.0"
+  },
+  "devDependencies": {
+    "hono": "^4.10.1"
+  },
+  "peerDependencies": {
+    "hono": ">=4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --publint",
+    "typecheck": "tsc --project tsconfig.json"
+  }
+}