definitely-fine 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,281 @@
+# definitely-fine
+
+`definitely-fine` is the core package for defining, saving, loading, and activating typed runtime scenarios.
+
+It is useful when you want your tests to steer selected application behavior by contract, while the application still executes its normal code paths.
+
+## Installation
+
+```bash
+pnpm add definitely-fine
+```
+
+## Important
+
+> [!IMPORTANT]
+> Disable runtime interception in production.
+>
+> If a production process should never honor saved scenarios, create the runtime with `enabled: false`.
+> This makes every wrapper fall through to the original implementation even if a scenario id is present.
+
+```ts
+import { createRuntime } from "definitely-fine";
+
+const runtime = createRuntime<DemoContract>({
+  enabled: process.env.NODE_ENV !== "production",
+});
+```
+
+Use this as the default recommendation for application code. Treat interception as test-only unless you have an explicit non-production use case.
+
+## Core Idea
+
+You define a contract for the behavior you want to intercept, create a scenario that targets specific function or service calls, save that scenario, then wrap your real implementation with a runtime.
+
+At execution time, an active scenario id decides whether the runtime should intercept a call or fall through to the real implementation.
+
+```mermaid
+flowchart LR
+  subgraph W[Writer process]
+    W1[createScenario]
+    W2[define rules]
+    W3[save scenario]
+    W4[scenario id]
+  end
+
+  subgraph S[Shared scenario storage]
+    S1[(persisted scenario JSON)]
+  end
+
+  subgraph R[Runtime process]
+    R1[runWithRuntimeScenarioContext]
+    R2[createRuntime wrappers]
+    R3[wrapped function or service]
+    R4[real implementation]
+    R5[scenario-defined return or throw]
+  end
+
+  W1 --> W2 --> W3
+  W3 --> S1
+  W3 --> W4
+  W4 --> R1
+  R1 --> R2 --> R3
+  R3 -- load active scenario --> S1
+  R3 --> R4
+  R3 --> R5
+```
+
+## Minimal Example
+
+```ts
+import {
+  createRuntime,
+  createScenario,
+  runWithRuntimeScenarioContext,
+} from "definitely-fine";
+
+type DemoContract = {
+  services: {
+    math: {
+      double(value: number): number;
+    };
+  };
+  functions: {
+    generateId(prefix: string): string;
+  };
+  errors: Record<string, never>;
+};
+
+const scenario = createScenario<DemoContract>();
+
+scenario.fn("generateId").onCall(1).returns("generated-1");
+scenario.service("math").method("double").onCall(2).returns(99);
+
+await scenario.save();
+
+const runtime = createRuntime<DemoContract>();
+
+const generateId = runtime.wrapSyncFunction("generateId", (prefix) => {
+  return `${prefix}-live`;
+});
+
+const math = runtime.wrapSyncService("math", {
+  double(value: number): number {
+    return value * 2;
+  },
+});
+
+const result = runWithRuntimeScenarioContext(
+  { scenarioId: scenario.id },
+  () => {
+    return {
+      id: generateId("user"),
+      firstDouble: math.double(2),
+      secondDouble: math.double(2),
+    };
+  },
+);
+
+console.log(result);
+// {
+//   id: "generated-1",
+//   firstDouble: 4,
+//   secondDouble: 99,
+// }
+```
+
+## Main APIs
+
+### `createScenario()`
+
+Creates a scenario builder with a stable id.
+
+Use `fn()` when targeting a standalone function:
+
+```ts
+import { createScenario } from "definitely-fine";
+
+const scenario = createScenario<DemoContract>();
+
+scenario.fn("generateId").onCall(1).returns("generated-1");
+scenario.fn("generateId").onCall(2).throwsMessage("blocked");
+
+await scenario.save();
+```
+
+Use `service().method()` when targeting methods on a wrapped service object:
+
+```ts
+import { createScenario } from "definitely-fine";
+
+const scenario = createScenario<DemoContract>();
+
+scenario.service("math").method("double").onCall(1).returns(10);
+
+await scenario.save();
+```
+
+### `createRuntime()`
+
+Creates a runtime that loads persisted scenarios and wraps implementations.
+
+```ts
+import { createRuntime } from "definitely-fine";
+
+const runtime = createRuntime<DemoContract>();
+
+const generateId = runtime.wrapSyncFunction("generateId", (prefix) => {
+  return `${prefix}-live`;
+});
+
+const math = runtime.wrapSyncService("math", {
+  double(value: number): number {
+    return value * 2;
+  },
+});
+```
+
+```mermaid
+sequenceDiagram
+  participant App as App process
+  participant Runtime as definitely-fine runtime
+  participant Store as Scenario storage
+
+  App->>Runtime: call wrapped function or service method
+  Runtime->>Runtime: resolve active scenario id
+  alt no active scenario id
+    Runtime-->>App: call original implementation
+  else active scenario id present
+    Runtime->>Store: load persisted scenario
+    Store-->>Runtime: scenario JSON or missing
+    alt matching rule for this call
+      Runtime-->>App: mocked return or configured throw
+    else no matching rule
+      Runtime-->>App: call original implementation
+    end
+  end
+```
+
+Disable interception explicitly when the runtime must never load or honor scenarios:
+
+```ts
+const runtime = createRuntime<DemoContract>({
+  enabled: false,
+});
+```
+
+### `runWithRuntimeScenarioContext()`
+
+Activates a scenario id for the current execution scope.
+
+```ts
+const result = runWithRuntimeScenarioContext(
+  { scenarioId: scenario.id },
+  () => {
+    return generateId("user");
+  },
+);
+```
+
+### `getRuntimeScenarioId()`
+
+Returns the active scenario id inside wrapped code.
+
+```ts
+import { getRuntimeScenarioId } from "definitely-fine";
+
+const generateId = runtime.wrapSyncFunction("generateId", (prefix) => {
+  return `${prefix}-${getRuntimeScenarioId() ?? "live"}`;
+});
+```
+
+## Storage
+
+By default, the built-in JSON adapter infers its storage directory automatically. When inference succeeds, scenarios are stored under `node_modules/.cache/definitely-fine/scenarios`.
+
+That means this is valid without providing any storage options:
+
+```ts
+import { createRuntime, createScenario } from "definitely-fine";
+
+const scenario = createScenario<DemoContract>();
+const runtime = createRuntime<DemoContract>();
+```
+
+```ts
+import { createRuntime, createScenario } from "definitely-fine";
+
+const scenario = createScenario<DemoContract>({
+  directory: ".definitely-fine",
+});
+
+const runtime = createRuntime<DemoContract>({
+  directory: ".definitely-fine",
+});
+```
+
+If you want full control over persistence, pass a custom `adapter` instead of relying on the built-in file-backed adapter.
+
+```ts
+import {
+  JsonScenarioStorageAdapter,
+  createRuntime,
+  createScenario,
+} from "definitely-fine";
+
+const adapter = new JsonScenarioStorageAdapter({});
+
+const scenario = createScenario<DemoContract>({ adapter });
+const runtime = createRuntime<DemoContract>({ adapter });
+```
+
+## When To Use It
+
+- You want typed, call-specific overrides such as "return this value on the third call".
+- You want browser tests to influence server-side behavior without adding test-only request plumbing everywhere.
+- You want app code to keep running through real route handlers, actions, and services.
+
+## Related Packages
+
+- [`@definitely-fine/nextjs`](../nextjs/README.md) propagates scenario ids through Next.js route handlers and server actions.
+- [`@definitely-fine/playwright`](../playwright/README.md) helps Playwright tests create browser contexts with the active scenario header already set.