feat(#50): state — session-scoped mutable shared state

ofetch #435 (proposed by pi0, never built). New `state` option holds
a mutable object shared by every call on a Misina instance. Hooks
read AND write `ctx.options.state`:

  declare module 'misina' {
    interface MisinaState {
      token?: string
      requestCount?: number
    }
  }

  const session = createMisina({
    state: { token: 'v1', requestCount: 0 },
    hooks: {
      beforeRequest: (ctx) => {
        ctx.options.state.requestCount! += 1
        const headers = new Headers(ctx.request.headers)
        if (ctx.options.state.token)
          headers.set('authorization', `Bearer ${ctx.options.state.token}`)
        return new Request(ctx.request, { headers })
      },
    },
  })

  // Mutate state at runtime — next call uses the new token:
  // hook can do `ctx.options.state.token = newToken`

Semantics:
- Same reference returned to every call on the same instance
  (closure-captured at createMisina time)
- .extend() does NOT inherit — child gets its own state object
  (mutations don't leak across boundaries)
- Default: empty {} when no state supplied
- Type-safe via module augmentation of MisinaState

Audit pass 57 (test/state.test.ts, 5 tests):
  Reference identity across calls, token rotation, default empty,
  .extend() isolation, multiple-call same-reference.

Closes #50.

Suite: 469 / 469 (was 464). Lint+typecheck clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: productdevbook

src/_merge.ts

@@ -44,6 +44,10 @@ export function mergeOptions(a: MisinaOptions, b: MisinaOptions): MisinaOptions
     } else if (key === "meta") {
       // Shallow merge — child keys win, parent keys preserved.
       out.meta = { ...(a.meta as object), ...(value as object) }
+    } else if (key === "state") {
+      // State is per-instance — never inherit parent's state on .extend().
+      // Replace cleanly so child mutations don't leak across boundaries.
+      out.state = value as MisinaOptions["state"]
     } else {
       ;(out as Record<string, unknown>)[key] = value
     }

src/index.ts

@@ -50,6 +50,7 @@ export type {
   MisinaHooks,
   MisinaMeta,
   MisinaOptions,
+  MisinaState,
   MisinaRequestInit,
   MisinaResolvedOptions,
   MisinaResponse,

src/misina.ts

@@ -26,6 +26,7 @@ import type {
   MisinaResponse,
   MisinaResponsePromise,
   MisinaResult,
+  MisinaState,
   SafeMisina,
 } from "./types.ts"
 
@@ -39,12 +40,16 @@ const DEFAULT_TIMEOUT = 10_000
 export function createMisina(defaults: MisinaOptions = {}): Misina {
   const driver: MisinaDriver =
     defaults.driver ?? fetchDriverFactory({ fetch: defaults.fetch } as never)
+  // Per-instance shared state. Same reference returned to every call so
+  // hooks can read AND mutate. Initialize from defaults.state if provided
+  // (NOT cloned — caller owns the object lifecycle). Otherwise empty.
+  const sharedState: MisinaState = (defaults.state ?? {}) as MisinaState
 
   async function request<T = unknown>(
     input: string,
     init: MisinaRequestInit = {},
   ): Promise<MisinaResponse<T>> {
-    const options = resolveOptions(input, init, defaults)
+    const options = resolveOptions(input, init, defaults, sharedState)
     const startedAt = performance.now()
 
     for (const initHook of options.hooks.init) initHook(options)
@@ -392,6 +397,7 @@ function resolveOptions(
   input: string,
   init: MisinaRequestInit,
   defaults: MisinaOptions,
+  sharedState: MisinaState,
 ): MisinaResolvedOptions {
   const method = (init.method ?? "GET") as HttpMethod
   const baseURL = init.baseURL ?? defaults.baseURL
@@ -416,6 +422,7 @@ function resolveOptions(
     allowedProtocols,
     trailingSlash,
     meta: { ...defaults.meta, ...init.meta },
+    state: sharedState,
     method,
     headers,
     body,

src/types.ts

@@ -14,6 +14,14 @@ export type MaybeArray<T> = T | T[]
 // biome-ignore lint/complexity/noBannedTypes: empty interface is the augmentation surface
 export interface MisinaMeta {}
 
+/**
+ * Session-scoped mutable state shared by every call on a Misina instance.
+ * Hooks read and write `ctx.options.state` directly. Empty by default —
+ * augment in your project to add typed keys (matches MisinaMeta pattern).
+ */
+// biome-ignore lint/complexity/noBannedTypes: empty interface is the augmentation surface
+export interface MisinaState {}
+
 /**
  * Per-phase mutable context shared across hooks for a single request lifecycle.
  * `request` and `response` are populated as the lifecycle progresses.
@@ -175,6 +183,13 @@ export interface MisinaOptions {
    * Useful as a guardrail when a backend 404s on the wrong canonical form.
    */
   trailingSlash?: "preserve" | "strip" | "forbid"
+  /**
+   * Session-scoped mutable state — shared by every call on this instance.
+   * Hooks can read AND write `ctx.options.state` to coordinate auth tokens,
+   * counters, etc. NOT merged on `.extend()` — child instances get their
+   * own state object so a child mutation doesn't leak to the parent.
+   */
+  state?: MisinaState
   /**
    * Per-request user data — flows through every hook on `ctx.options.meta`.
    *
@@ -329,6 +344,12 @@ export interface MisinaResolvedOptions {
   allowedProtocols: readonly string[]
   trailingSlash: "preserve" | "strip" | "forbid"
   meta: MisinaMeta
+  /**
+   * Session state — same reference shared across every call on this
+   * instance. Hooks can mutate it freely. Type via module augmentation
+   * of `MisinaState` to add fields.
+   */
+  state: MisinaState
   method: HttpMethod
   headers: Record<string, string>
   body?: unknown

test/state.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from "vitest"
+import { createMisina } from "../src/index.ts"
+
+declare module "../src/types.ts" {
+  interface MisinaState {
+    counter?: number
+    token?: string
+  }
+}
+
+describe("state — session-scoped mutable shared object", () => {
+  it("hooks see the same state reference across calls", async () => {
+    const driver = {
+      name: "p",
+      request: async () => new Response("{}", { headers: { "content-type": "application/json" } }),
+    }
+    const m = createMisina({
+      driver,
+      retry: 0,
+      state: { counter: 0 },
+      hooks: {
+        beforeRequest: (ctx) => {
+          if (ctx.options.state.counter != null) {
+            ctx.options.state.counter++
+          }
+        },
+      },
+    })
+
+    await m.get("https://api.test/")
+    await m.get("https://api.test/")
+    await m.get("https://api.test/")
+
+    // The state object is mutated by every call — read back via a hook
+    // by triggering a final call and inspecting.
+    let observed: number | undefined
+    await m.get("https://api.test/", {
+      hooks: {
+        afterResponse: (ctx) => {
+          observed = ctx.options.state.counter
+        },
+      },
+    })
+    expect(observed).toBe(4)
+  })
+
+  it("token rotation in hooks affects subsequent calls", async () => {
+    let captured: (string | null)[] = []
+    const driver = {
+      name: "p",
+      request: async (req: Request) => {
+        captured.push(req.headers.get("authorization"))
+        return new Response("{}", { headers: { "content-type": "application/json" } })
+      },
+    }
+    const m = createMisina({
+      driver,
+      retry: 0,
+      state: { token: "v1" },
+      hooks: {
+        beforeRequest: (ctx) => {
+          const headers = new Headers(ctx.request.headers)
+          if (ctx.options.state.token)
+            headers.set("authorization", `Bearer ${ctx.options.state.token}`)
+          return new Request(ctx.request, { headers })
+        },
+      },
+    })
+
+    await m.get("https://api.test/")
+    expect(captured[0]).toBe("Bearer v1")
+
+    // Mutate state externally — next call uses the new token.
+    await m.get("https://api.test/", {
+      hooks: {
+        init: (opts) => {
+          opts.state.token = "v2"
+        },
+      },
+    })
+    expect(captured[1]).toBe("Bearer v2")
+  })
+
+  it("default empty {} when no state supplied", async () => {
+    let captured: object | undefined
+    const driver = {
+      name: "p",
+      request: async () => new Response("{}", { headers: { "content-type": "application/json" } }),
+    }
+    const m = createMisina({
+      driver,
+      retry: 0,
+      hooks: {
+        beforeRequest: (ctx) => {
+          captured = ctx.options.state
+        },
+      },
+    })
+
+    await m.get("https://api.test/")
+    expect(captured).toEqual({})
+  })
+
+  it(".extend() does NOT inherit parent state — child gets its own", async () => {
+    const driver = {
+      name: "p",
+      request: async () => new Response("{}", { headers: { "content-type": "application/json" } }),
+    }
+    const parent = createMisina({
+      driver,
+      retry: 0,
+      state: { counter: 100 },
+    })
+    const child = parent.extend({ state: { counter: 0 } })
+
+    let parentObserved: number | undefined
+    let childObserved: number | undefined
+    await parent.get("https://api.test/", {
+      hooks: {
+        beforeRequest: (ctx) => {
+          ctx.options.state.counter = (ctx.options.state.counter ?? 0) + 1
+          parentObserved = ctx.options.state.counter
+        },
+      },
+    })
+    await child.get("https://api.test/", {
+      hooks: {
+        beforeRequest: (ctx) => {
+          ctx.options.state.counter = (ctx.options.state.counter ?? 0) + 1
+          childObserved = ctx.options.state.counter
+        },
+      },
+    })
+
+    expect(parentObserved).toBe(101)
+    expect(childObserved).toBe(1) // child's state is fresh
+  })
+
+  it("state is the same reference across multiple calls on one instance", async () => {
+    const driver = {
+      name: "p",
+      request: async () => new Response("{}", { headers: { "content-type": "application/json" } }),
+    }
+    const captured: object[] = []
+    const m = createMisina({
+      driver,
+      retry: 0,
+      state: { counter: 0 },
+      hooks: {
+        beforeRequest: (ctx) => {
+          captured.push(ctx.options.state)
+        },
+      },
+    })
+
+    await m.get("https://api.test/")
+    await m.get("https://api.test/")
+    expect(captured[0]).toBe(captured[1]) // same reference
+  })
+})