@vepler/sdk 2.164.0 → 3.0.0

package/src/address-search/__tests__/controller.test.ts

@@ -0,0 +1,395 @@
+import { describe, expect, it } from "vitest";
+import { createAddressSearch } from "../controller.js";
+import type {
+  AddressSearchOptions,
+  AddressSearchTimers,
+  AddressSuggestion,
+  RetrieveRequest,
+  RetrieveResult,
+  SuggestRequest,
+  SuggestResult,
+  SuggestTransport,
+  TimerHandle,
+} from "../types.js";
+
+/** Deterministic clock + timer harness injected in place of real timers. */
+function createTimerHarness(): { timers: AddressSearchTimers; advance(ms: number): void } {
+  let now = 0;
+  let nextId = 1;
+  const scheduled = new Map<number, { at: number; callback: () => void }>();
+  return {
+    timers: {
+      now: (): number => now,
+      setTimeout: (callback: () => void, ms: number): TimerHandle => {
+        const id = nextId++;
+        scheduled.set(id, { at: now + ms, callback });
+        return id;
+      },
+      clearTimeout: (handle: TimerHandle): void => {
+        scheduled.delete(handle as number);
+      },
+    },
+    advance(ms: number): void {
+      now += ms;
+      for (const [id, task] of [...scheduled]) {
+        if (task.at <= now) {
+          scheduled.delete(id);
+          task.callback();
+        }
+      }
+    },
+  };
+}
+
+/** Let promise continuations queued by the transports run. */
+function flush(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+function suggestion(uprn: string, title: string): AddressSuggestion {
+  return { id: `addr-${uprn}`, title, uprn, source: "address", matchedSubstrings: [], raw: { uprn, title } };
+}
+
+/** Same rows the server's candidate-set narrowing tests use. */
+const FIXTURE_ROWS: readonly AddressSuggestion[] = [
+  suggestion("100", "31 Christopher Court, Cherry Lane, Beverley, HU17 9TB"),
+  suggestion("101", "31 Christie Avenue, Beverley, HU17 9TB"),
+  suggestion("102", "112 Green Lane, York, YO42 2RW"),
+];
+
+const COMPLETE_SET: SuggestResult = {
+  suggestions: FIXTURE_ROWS,
+  searchId: "set-1",
+  setComplete: true,
+  billing: null,
+};
+
+const TIERED_RESULT: SuggestResult = {
+  suggestions: [suggestion("900", "Beverley, East Riding of Yorkshire")],
+  searchId: null,
+  setComplete: false,
+  billing: null,
+};
+
+function createSuggestMock(handler: (request: SuggestRequest) => SuggestResult | Promise<SuggestResult>): {
+  calls: SuggestRequest[];
+  transport: SuggestTransport;
+} {
+  const calls: SuggestRequest[] = [];
+  const transport: SuggestTransport = async (request): Promise<SuggestResult> => {
+    calls.push(request);
+    return handler(request);
+  };
+  return { calls, transport };
+}
+
+function createRetrieveMock<TRecord>(handler: (request: RetrieveRequest) => RetrieveResult<TRecord>): {
+  calls: RetrieveRequest[];
+  transport: (request: RetrieveRequest) => Promise<RetrieveResult<TRecord>>;
+} {
+  const calls: RetrieveRequest[] = [];
+  return {
+    calls,
+    transport: async (request): Promise<RetrieveResult<TRecord>> => {
+      calls.push(request);
+      return handler(request);
+    },
+  };
+}
+
+interface Setup {
+  controller: ReturnType<typeof createAddressSearch<{ uprn: string }>>;
+  suggestCalls: SuggestRequest[];
+  retrieveCalls: RetrieveRequest[];
+  advance(ms: number): void;
+}
+
+function setup(
+  suggestHandler: (request: SuggestRequest) => SuggestResult | Promise<SuggestResult>,
+  overrides: Partial<AddressSearchOptions<{ uprn: string }>> = {},
+): Setup {
+  const harness = createTimerHarness();
+  const suggest = createSuggestMock(suggestHandler);
+  const retrieve = createRetrieveMock<{ uprn: string }>(({ suggestion: picked }) => ({
+    record: { uprn: picked.uprn ?? "" },
+  }));
+  const controller = createAddressSearch<{ uprn: string }>({
+    suggest: suggest.transport,
+    retrieve: retrieve.transport,
+    timers: harness.timers,
+    ...overrides,
+  });
+  return { controller, suggestCalls: suggest.calls, retrieveCalls: retrieve.calls, advance: harness.advance };
+}
+
+describe("debounce and minimum length", () => {
+  it("coalesces a fast typing burst into one fetch for the final query", async () => {
+    const { controller, suggestCalls, advance } = setup(() => COMPLETE_SET);
+    for (const text of ["31 c", "31 ch", "31 chr", "31 chri"]) {
+      controller.input(text);
+      advance(100); // faster than the 250ms debounce
+    }
+    advance(250);
+    await flush();
+    expect(suggestCalls).toHaveLength(1);
+    expect(suggestCalls[0]?.query).toBe("31 chri");
+    expect(controller.getState().status).toBe("ready");
+  });
+
+  it("never fetches below three characters and clears suggestions", async () => {
+    const { controller, suggestCalls, advance } = setup(() => COMPLETE_SET);
+    controller.input("31 chri");
+    advance(300);
+    await flush();
+    expect(controller.getState().suggestions.length).toBeGreaterThan(0);
+
+    controller.input("31");
+    advance(1000);
+    await flush();
+    expect(suggestCalls).toHaveLength(1); // no second fetch
+    expect(controller.getState().status).toBe("idle");
+    expect(controller.getState().suggestions).toEqual([]);
+  });
+});
+
+describe("candidate-set protocol", () => {
+  it("holds a complete set and narrows extending keystrokes locally — zero further fetches", async () => {
+    const { controller, suggestCalls, advance } = setup(() => COMPLETE_SET);
+    controller.input("31 chri");
+    advance(300);
+    await flush();
+    expect(suggestCalls).toHaveLength(1);
+
+    controller.input("31 chris");
+    expect(controller.getState().status).toBe("ready");
+    expect(controller.getState().suggestions.map((s) => s.uprn)).toEqual(["100", "101"]);
+
+    controller.input("31 christo");
+    expect(controller.getState().suggestions.map((s) => s.uprn)).toEqual(["100"]);
+    expect(controller.getState().searchId).toBe("set-1");
+    expect(controller.getState().setComplete).toBe(true);
+
+    advance(1000);
+    await flush();
+    expect(suggestCalls).toHaveLength(1); // both narrows were local
+  });
+
+  it("re-queries WITHOUT a search_id when the local narrow empties (set exhaustion)", async () => {
+    const { controller, suggestCalls, advance } = setup(() => COMPLETE_SET);
+    controller.input("31 chri");
+    advance(300);
+    await flush();
+
+    controller.input("31 christopher zzz"); // extends the trigger but matches nothing held
+    expect(controller.getState().status).toBe("debouncing");
+    advance(250);
+    await flush();
+    expect(suggestCalls).toHaveLength(2);
+    expect(suggestCalls[1]?.query).toBe("31 christopher zzz");
+    expect(suggestCalls[1]?.searchId).toBeNull();
+  });
+
+  it("re-queries when the input no longer extends the trigger prefix (backspace past it)", async () => {
+    const { controller, suggestCalls, advance } = setup(() => COMPLETE_SET);
+    controller.input("31 chri");
+    advance(300);
+    await flush();
+
+    controller.input("31 ch"); // backspace past the trigger
+    advance(250);
+    await flush();
+    expect(suggestCalls).toHaveLength(2);
+    expect(suggestCalls[1]?.query).toBe("31 ch");
+    expect(suggestCalls[1]?.searchId).toBeNull();
+  });
+
+  it("issues at most 2 data fetches across a 10-keystroke chain", async () => {
+    const { controller, suggestCalls, advance } = setup(({ query }) =>
+      query.startsWith("31 chri") ? COMPLETE_SET : TIERED_RESULT,
+    );
+    const chain = [
+      "31 c",
+      "31 ch",
+      "31 chr",
+      "31 chri", // pause here → fetch 1 returns the complete set
+      "31 chris",
+      "31 christ",
+      "31 christo",
+      "31 christop",
+      "31 christoph",
+      "31 christophz", // typo exhausts the set → fetch 2
+    ];
+    for (const text of chain) {
+      controller.input(text);
+      advance(text === "31 chri" || text === "31 christophz" ? 300 : 100);
+      await flush();
+    }
+    expect(suggestCalls.length).toBeLessThanOrEqual(2);
+    expect(suggestCalls.map((c) => c.query)).toEqual(["31 chri", "31 christophz"]);
+  });
+
+  it("serves a repeated query from the cache without a fetch and re-adopts its set", async () => {
+    const { controller, suggestCalls, advance } = setup(({ query }) =>
+      query.startsWith("31 chri") ? COMPLETE_SET : TIERED_RESULT,
+    );
+    controller.input("31 chri");
+    advance(300);
+    await flush();
+    controller.input("beverley town"); // unrelated query displaces the held set context
+    advance(300);
+    await flush();
+    expect(suggestCalls).toHaveLength(2);
+
+    controller.input("31 chri"); // cache hit — instant, no fetch
+    expect(controller.getState().status).toBe("ready");
+    expect(controller.getState().searchId).toBe("set-1");
+    controller.input("31 christo"); // and the re-adopted set narrows locally
+    expect(controller.getState().suggestions.map((s) => s.uprn)).toEqual(["100"]);
+    advance(1000);
+    await flush();
+    expect(suggestCalls).toHaveLength(2);
+  });
+});
+
+describe("cancellation and stale responses", () => {
+  it("aborts the in-flight request when a new fetch supersedes it", async () => {
+    let release: ((result: SuggestResult) => void) | undefined;
+    const { controller, suggestCalls, advance } = setup(({ query }) =>
+      query === "31 chri"
+        ? new Promise<SuggestResult>((resolve) => {
+            release = resolve;
+          })
+        : TIERED_RESULT,
+    );
+    controller.input("31 chri");
+    advance(250); // fetch 1 in flight, unresolved
+    controller.input("112 green");
+    advance(250); // fetch 2 supersedes
+    await flush();
+
+    expect(suggestCalls).toHaveLength(2);
+    expect(suggestCalls[0]?.signal.aborted).toBe(true);
+    expect(controller.getState().query).toBe("112 green");
+    expect(controller.getState().status).toBe("ready");
+
+    release?.(COMPLETE_SET); // the stale response finally lands…
+    await flush();
+    expect(controller.getState().suggestions).toEqual(TIERED_RESULT.suggestions); // …and is ignored
+  });
+});
+
+describe("select", () => {
+  it("fires the retrieve exactly once per selection, with the session id attached", async () => {
+    const { controller, retrieveCalls, advance } = setup(() => COMPLETE_SET);
+    controller.input("31 chri");
+    advance(300);
+    await flush();
+
+    const picked = controller.getState().suggestions[0];
+    expect(picked).toBeDefined();
+    if (picked === undefined) return;
+
+    const [first, second] = await Promise.all([controller.select(picked), controller.select(picked)]);
+    expect(retrieveCalls).toHaveLength(1);
+    expect(retrieveCalls[0]?.searchId).toBe("set-1");
+    expect(retrieveCalls[0]?.suggestion.uprn).toBe("100");
+    expect(first).toEqual(second);
+
+    await controller.select(picked); // later re-selects also reuse the settled retrieve
+    expect(retrieveCalls).toHaveLength(1);
+  });
+
+  it("clears the idempotency guard when a retrieve fails, so it can be retried", async () => {
+    const harness = createTimerHarness();
+    const suggest = createSuggestMock(() => COMPLETE_SET);
+    let attempts = 0;
+    const controller = createAddressSearch<{ uprn: string }>({
+      suggest: suggest.transport,
+      retrieve: async ({ suggestion: picked }): Promise<RetrieveResult<{ uprn: string }>> => {
+        attempts += 1;
+        if (attempts === 1) throw new Error("transient");
+        return { record: { uprn: picked.uprn ?? "" } };
+      },
+      timers: harness.timers,
+    });
+    controller.input("31 chri");
+    harness.advance(300);
+    await flush();
+
+    const picked = controller.getState().suggestions[0];
+    expect(picked).toBeDefined();
+    if (picked === undefined) return;
+
+    await expect(controller.select(picked)).rejects.toThrow("transient");
+    await expect(controller.select(picked)).resolves.toEqual({ record: { uprn: "100" } }.record);
+    expect(attempts).toBe(2);
+  });
+});
+
+describe("billing metadata", () => {
+  it("surfaces suggest billing headers on the state and the billing property", async () => {
+    const billing = { creditsCharged: 0, creditsBalance: 4200, alreadyCharged: false };
+    const { controller, advance } = setup(() => ({ ...COMPLETE_SET, billing }));
+    controller.input("31 chri");
+    advance(300);
+    await flush();
+    expect(controller.getState().billing).toEqual({ ...billing, receivedAt: 300 });
+    expect(controller.billing).toEqual({ ...billing, receivedAt: 300 });
+  });
+
+  it("updates billing from the retrieve response after a selection", async () => {
+    const harness = createTimerHarness();
+    const suggest = createSuggestMock(() => COMPLETE_SET);
+    const controller = createAddressSearch<{ uprn: string }>({
+      suggest: suggest.transport,
+      retrieve: async ({ suggestion: picked }): Promise<RetrieveResult<{ uprn: string }>> => ({
+        record: { uprn: picked.uprn ?? "" },
+        billing: { creditsCharged: 4, creditsBalance: 4196, alreadyCharged: false },
+      }),
+      timers: harness.timers,
+    });
+    controller.input("31 chri");
+    harness.advance(300);
+    await flush();
+
+    const picked = controller.getState().suggestions[0];
+    expect(picked).toBeDefined();
+    if (picked === undefined) return;
+    await controller.select(picked);
+    expect(controller.billing).toEqual({
+      creditsCharged: 4,
+      creditsBalance: 4196,
+      alreadyCharged: false,
+      receivedAt: 300,
+    });
+  });
+});
+
+describe("subscription surface", () => {
+  it("notifies subscribers on every state change and stops after unsubscribe", async () => {
+    const { controller, advance } = setup(() => COMPLETE_SET);
+    const statuses: string[] = [];
+    const unsubscribe = controller.subscribe((state) => statuses.push(state.status));
+
+    controller.input("31 chri");
+    advance(300);
+    await flush();
+    expect(statuses).toEqual(["debouncing", "loading", "ready"]);
+
+    unsubscribe();
+    controller.input("31 christo");
+    expect(statuses).toHaveLength(3);
+  });
+
+  it("dispose cancels pending work and ignores further input", async () => {
+    const { controller, suggestCalls, advance } = setup(() => COMPLETE_SET);
+    controller.input("31 chri");
+    controller.dispose();
+    advance(1000);
+    await flush();
+    controller.input("31 christo");
+    advance(1000);
+    await flush();
+    expect(suggestCalls).toHaveLength(0);
+  });
+});

package/src/address-search/__tests__/default-transports.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from "vitest";
+import type { SDKCore } from "../../core.js";
+import type { UprnLookupResponse } from "../../sdk/models/shared/uprnlookupresponse.js";
+import type { Result } from "../../sdk/types/fp.js";
+import {
+  createSuggestTransport,
+  createUprnRetrieveTransport,
+  type FetchLike,
+  parseBillingHeaders,
+  type SuggestHttpResponse,
+} from "../default-transports.js";
+import { AddressSearchError } from "../errors.js";
+
+interface CapturedRequest {
+  url: string;
+  headers: Record<string, string>;
+  signal: AbortSignal;
+}
+
+function fakeFetch(
+  body: unknown,
+  options: { status?: number; headers?: Record<string, string> } = {},
+): { fetch: FetchLike; captured: CapturedRequest[] } {
+  const captured: CapturedRequest[] = [];
+  const status = options.status ?? 200;
+  const headerMap = new Map(Object.entries(options.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
+  const response: SuggestHttpResponse = {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: { get: (name: string): string | null => headerMap.get(name.toLowerCase()) ?? null },
+    json: async (): Promise<unknown> => body,
+  };
+  return {
+    captured,
+    fetch: async (url, init): Promise<SuggestHttpResponse> => {
+      captured.push({ url, headers: init.headers, signal: init.signal });
+      return response;
+    },
+  };
+}
+
+const SERVER_ROW = {
+  id: "addr-100023336956",
+  title: "10 Downing Street, London, SW1A 2AA",
+  main_text: "10 Downing Street, London, SW1A 2AA",
+  type: "address",
+  source: "address",
+  score: 5,
+  relevanceScore: 1,
+  uprn: "100023336956",
+  matched_substrings: [{ offset: 0, length: 10 }],
+  main_text_matched_substrings: [{ offset: 0, length: 10 }],
+};
+
+describe("createSuggestTransport", () => {
+  it("requests /v1/search/suggest with the query, page cap, version header and api key", async () => {
+    const { fetch, captured } = fakeFetch({ object: "list", data: [], search_id: null, set_complete: false });
+    const transport = createSuggestTransport({ baseUrl: "https://api.example.com/", apiKey: "sk-test", fetch });
+    await transport({ query: "10 downing", searchId: null, signal: new AbortController().signal });
+
+    expect(captured).toHaveLength(1);
+    const request = captured[0];
+    expect(request?.url).toBe("https://api.example.com/v1/search/suggest?q=10+downing&limit=100");
+    expect(request?.headers["X-API-Version"]).toBe("2");
+    expect(request?.headers["x-api-key"]).toBe("sk-test");
+  });
+
+  it("passes search_id through when the caller narrows server-side", async () => {
+    const { fetch, captured } = fakeFetch({ data: [], search_id: "s-1", set_complete: true });
+    const transport = createSuggestTransport({ fetch });
+    await transport({ query: "10 downing st", searchId: "s-1", signal: new AbortController().signal });
+    expect(captured[0]?.url).toContain("search_id=s-1");
+  });
+
+  it("lifts rows, search_id, set_complete and billing headers out of the response", async () => {
+    const { fetch } = fakeFetch(
+      { object: "list", data: [SERVER_ROW], search_id: "s-9", set_complete: true },
+      { headers: { "X-Credits-Charged": "0", "X-Credits-Balance": "4200", "X-Already-Charged": "false" } },
+    );
+    const transport = createSuggestTransport({ fetch });
+    const result = await transport({ query: "10 downing", searchId: null, signal: new AbortController().signal });
+
+    expect(result.searchId).toBe("s-9");
+    expect(result.setComplete).toBe(true);
+    expect(result.suggestions).toHaveLength(1);
+    expect(result.suggestions[0]).toMatchObject({
+      id: "addr-100023336956",
+      title: "10 Downing Street, London, SW1A 2AA",
+      uprn: "100023336956",
+      source: "address",
+      matchedSubstrings: [{ offset: 0, length: 10 }],
+    });
+    expect(result.suggestions[0]?.raw).toBe(SERVER_ROW);
+    expect(result.billing).toEqual({ creditsCharged: 0, creditsBalance: 4200, alreadyCharged: false });
+  });
+
+  it("parses the legacy envelope's result array and rows without a UPRN", async () => {
+    const { fetch } = fakeFetch({
+      success: true,
+      result: [{ id: "street-1", title: "Cherry Lane", source: "address" }],
+    });
+    const transport = createSuggestTransport({ fetch });
+    const result = await transport({ query: "cherry", searchId: null, signal: new AbortController().signal });
+    expect(result.suggestions).toEqual([
+      {
+        id: "street-1",
+        title: "Cherry Lane",
+        uprn: null,
+        source: "address",
+        matchedSubstrings: [],
+        raw: expect.anything(),
+      },
+    ]);
+    expect(result.searchId).toBeNull();
+    expect(result.setComplete).toBe(false);
+  });
+
+  it("throws an AddressSearchError on a non-2xx response", async () => {
+    const { fetch } = fakeFetch({ error: "nope" }, { status: 429 });
+    const transport = createSuggestTransport({ fetch });
+    await expect(
+      transport({ query: "10 downing", searchId: null, signal: new AbortController().signal }),
+    ).rejects.toThrow(AddressSearchError);
+  });
+});
+
+describe("parseBillingHeaders", () => {
+  const headersOf = (entries: Record<string, string>): { get(name: string): string | null } => {
+    const map = new Map(Object.entries(entries).map(([k, v]) => [k.toLowerCase(), v]));
+    return { get: (name): string | null => map.get(name.toLowerCase()) ?? null };
+  };
+
+  it("returns null when no billing header is present", () => {
+    expect(parseBillingHeaders(headersOf({}))).toBeNull();
+  });
+
+  it("parses partial header sets, leaving absent values null", () => {
+    expect(parseBillingHeaders(headersOf({ "X-Credits-Charged": "3" }))).toEqual({
+      creditsCharged: 3,
+      creditsBalance: null,
+      alreadyCharged: null,
+    });
+  });
+
+  it("accepts both boolean spellings of X-Already-Charged", () => {
+    expect(parseBillingHeaders(headersOf({ "X-Already-Charged": "true" }))?.alreadyCharged).toBe(true);
+    expect(parseBillingHeaders(headersOf({ "X-Already-Charged": "1" }))?.alreadyCharged).toBe(true);
+    expect(parseBillingHeaders(headersOf({ "X-Already-Charged": "false" }))?.alreadyCharged).toBe(false);
+  });
+
+  it("parses non-numeric header values to null rather than NaN", () => {
+    expect(parseBillingHeaders(headersOf({ "X-Credits-Balance": "unlimited" }))?.creditsBalance).toBeNull();
+  });
+});
+
+describe("createUprnRetrieveTransport", () => {
+  const fakeClient = {} as unknown as SDKCore;
+  const record = { uprn: "100023336956" } as unknown as UprnLookupResponse;
+  const pickedSuggestion = {
+    id: "addr-100023336956",
+    title: "10 Downing Street, London, SW1A 2AA",
+    uprn: "100023336956",
+    source: "address",
+    matchedSubstrings: [],
+    raw: null,
+  };
+
+  it("resolves the suggestion's UPRN through the injected lookup", async () => {
+    const requests: string[] = [];
+    const transport = createUprnRetrieveTransport(fakeClient, {
+      lookup: async (_client, request): Promise<Result<UprnLookupResponse, unknown>> => {
+        requests.push(request.uprn);
+        return { ok: true, value: record };
+      },
+    });
+    const result = await transport({ suggestion: pickedSuggestion, searchId: "s-1" });
+    expect(requests).toEqual(["100023336956"]);
+    expect(result.record).toBe(record);
+  });
+
+  it("throws the lookup's error when the lookup fails", async () => {
+    const transport = createUprnRetrieveTransport(fakeClient, {
+      lookup: async (): Promise<Result<UprnLookupResponse, unknown>> => ({ ok: false, error: new Error("boom") }),
+    });
+    await expect(transport({ suggestion: pickedSuggestion, searchId: null })).rejects.toThrow("boom");
+  });
+
+  it("rejects suggestions without a UPRN before any request is made", async () => {
+    let called = false;
+    const transport = createUprnRetrieveTransport(fakeClient, {
+      lookup: async (): Promise<Result<UprnLookupResponse, unknown>> => {
+        called = true;
+        return { ok: true, value: record };
+      },
+    });
+    await expect(transport({ suggestion: { ...pickedSuggestion, uprn: null }, searchId: null })).rejects.toThrow(
+      AddressSearchError,
+    );
+    expect(called).toBe(false);
+  });
+});

package/src/address-search/__tests__/narrow.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { extendsTriggerPrefix, narrowSuggestions, normaliseQuery } from "../narrow.js";
+
+/**
+ * Client-side narrowing must agree with the server's candidate-set narrowing
+ * (apps/api search suggest, `narrowCandidates`) on the same fixtures — a
+ * divergence would make client and server disagree about which rows survive
+ * a keystroke. Fixture rows and expectations are copied verbatim from the
+ * server's candidate-set unit tests.
+ */
+
+const ROWS = [
+  { uprn: "100", title: "31 Christopher Court, Cherry Lane, Beverley, HU17 9TB" },
+  { uprn: "101", title: "31 Christie Avenue, Beverley, HU17 9TB" },
+  { uprn: "102", title: "112 Green Lane, York, YO42 2RW" },
+] as const;
+
+describe("narrowSuggestions — mirrors the server's narrowing semantics", () => {
+  it("keeps rows where every query token prefix-matches a title token, case-insensitively", () => {
+    const narrowed = narrowSuggestions(ROWS, "31 chri");
+    expect(narrowed.map((r) => r.uprn)).toEqual(["100", "101"]);
+  });
+
+  it("narrows further as the prefix grows (monotone: longer prefix, never more rows)", () => {
+    const narrowed = narrowSuggestions(ROWS, "31 christo");
+    expect(narrowed.map((r) => r.uprn)).toEqual(["100"]);
+  });
+
+  it("requires EVERY query token to match — one stray token empties the result", () => {
+    expect(narrowSuggestions(ROWS, "31 christopher zzz")).toEqual([]);
+  });
+
+  it("treats punctuation as separators on both sides (commas in titles never block a match)", () => {
+    expect(narrowSuggestions(ROWS, "cherry lane beverley").map((r) => r.uprn)).toEqual(["100"]);
+  });
+
+  it("matches mid-title tokens (a postcode prefix narrows to that postcode's rows)", () => {
+    expect(narrowSuggestions(ROWS, "hu17").map((r) => r.uprn)).toEqual(["100", "101"]);
+  });
+
+  it("returns the whole set for an empty or separator-only query", () => {
+    expect(narrowSuggestions(ROWS, "")).toHaveLength(3);
+    expect(narrowSuggestions(ROWS, " , ")).toHaveLength(3);
+  });
+
+  it("preserves the served order", () => {
+    const narrowed = narrowSuggestions(ROWS, "beverley");
+    expect(narrowed.map((r) => r.uprn)).toEqual(["100", "101"]);
+  });
+});
+
+describe("extendsTriggerPrefix — when local narrowing stays sound", () => {
+  it("accepts a query that extends the trigger prefix", () => {
+    expect(extendsTriggerPrefix("31 chris", "31 chri")).toBe(true);
+  });
+
+  it("accepts case and whitespace variants of the trigger itself", () => {
+    expect(extendsTriggerPrefix("31  CHRI", "31 chri")).toBe(true);
+  });
+
+  it("rejects a backspace past the trigger prefix", () => {
+    expect(extendsTriggerPrefix("31 ch", "31 chri")).toBe(false);
+  });
+
+  it("rejects an edit inside the trigger prefix", () => {
+    expect(extendsTriggerPrefix("32 chri", "31 chri")).toBe(false);
+  });
+});
+
+describe("normaliseQuery — the cache and prefix key form", () => {
+  it("lower-cases, collapses whitespace runs and trims", () => {
+    expect(normaliseQuery("  31  Christopher   Court ")).toBe("31 christopher court");
+  });
+});