/**
 * A browser-settable FHIR search page size - instrument.
 *
 * WHY THIS EXISTS
 *
 * swept ~40 unpaginated bundle reads SERVER-side. The class it fixed is *"read page one and call
 * it the answer"*: it returns **200 with fewer results**, every layer above reads that as "there are fewer
 * results", and it is invisible until a customer grows past a page. **The client was never swept.**
 *
 * Verifying that on the client needs a resource set with more than one page, and staging has 3 schedules
 * and 10 practitioners. The alternative to seeding thousands of rows is to make the PAGE smaller - but
 * hard-coding a small `_count` to run the test means shipping a number that silently truncates every
 * list in the product if it is ever merged and released. **That is the very defect being tested for**,
 * introduced by the test for it.
 *
 * So the size is read from `localStorage` at call time, and **the default is unchanged**. Nothing about
 * a normal session differs; a probe is one `localStorage.setItem` in the console and needs no build.
 *
 * WHAT IT DELIBERATELY IS NOT
 *
 * **NOT a fix, and not a step toward one.** own words: *"A bigger `_count` is NOT the fix...
 * It moves the cliff; it does not remove it. Follow the `next` link or accept that the handler breaks at
 * some customer size nobody chose."* The same is true downward: this makes the cliff observable, it does
 * not move it. The fix for a truncating client read is to follow `link[next]` - see
 * `utils/fetchAllBundlePages.ts`, which is what `AppointmentService`'s range fetcher already does.
 *
 * **NOT a way to widen a read.** It is clamped to 1-1000, so it cannot be used to ask for an unbounded
 * page and thereby paper over a missing paginator.
 */

/** The key a probe sets. Namespaced with the app's other dev keys so it is obvious where it came from. */
export const PAGE_SIZE_PROBE_KEY = 'akashic_page_size_probe';

/**
 * The page size a search should ask for: the caller's own default, unless a probe is deliberately set.
 *
 * Read at CALL TIME, never captured at module load - a probe set mid-session has to take effect on the
 * next fetch without a reload, or the person running it cannot tell "the override did nothing" from
 * "the read does not paginate", which are the two answers this instrument exists to separate.
 *
 * Any unusable value falls back to the caller's default rather than throwing. A malformed probe key
 * must never be able to break a clinical screen - and a silent fallback is safe here precisely because
 * the default is the shipping behaviour.
 */
export const searchPageSize = (fallback: string): string => {
    try {
        const raw = globalThis.localStorage?.getItem(PAGE_SIZE_PROBE_KEY);
        if (!raw) return fallback;

        const parsed = Number(raw);
        if (!Number.isInteger(parsed) || parsed < 1 || parsed > 1000) return fallback;

        return String(parsed);
    } catch {
        // localStorage can throw outright (Safari private mode, a sandboxed iframe). The product must not
        // care, so the shipping default wins.
        return fallback;
    }
};