@mendylanda/ui 0.1.0

package/dist/filters/use-filter-options.js

@@ -0,0 +1,221 @@
+"use client";
+import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState } from "react";
+export const FilterOptionCache = createContext(null);
+function acquire(cache, key, load) {
+    let request = cache.get(key);
+    if (request?.settled && Date.now() - request.created > 30000) {
+        cache.delete(key);
+        request = undefined;
+    }
+    if (!request) {
+        const abort = new AbortController();
+        request = {
+            promise: Promise.resolve().then(() => load(abort.signal)),
+            abort,
+            users: 0,
+            settled: false,
+            created: Date.now(),
+        };
+        const current = request;
+        current.promise.then(() => {
+            current.settled = true;
+        }, () => {
+            current.settled = true;
+            if (cache.get(key) === current)
+                cache.delete(key);
+        });
+        cache.set(key, request);
+        if (cache.size > 100)
+            for (const [oldKey, old] of cache) {
+                if (old.settled && old.users === 0) {
+                    cache.delete(oldKey);
+                    if (cache.size <= 80)
+                        break;
+                }
+            }
+    }
+    request.users++;
+    const current = request;
+    let released = false;
+    return {
+        promise: current.promise,
+        release() {
+            if (released)
+                return;
+            released = true;
+            current.users--;
+            if (!current.settled && current.users === 0) {
+                current.abort.abort();
+                if (cache.get(key) === current)
+                    cache.delete(key);
+            }
+        },
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : "Options could not be loaded.";
+}
+export function selectedIds(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : typeof value === "string"
+            ? [value]
+            : [];
+}
+export function useFilterOptions(id, field, value, enabled) {
+    const sharedCache = useContext(FilterOptionCache);
+    const privateCache = useRef(new Map());
+    const cache = sharedCache ?? privateCache.current;
+    const source = field.source;
+    const latest = useRef(source);
+    useLayoutEffect(() => {
+        latest.current = source;
+    }, [source]);
+    const [localQuery, setLocalQuery] = useState("");
+    const query = source?.query ?? localQuery;
+    const [retryKey, retry] = useState(0);
+    const scopeKey = JSON.stringify([id, source?.scope, source?.params]);
+    const requestKey = JSON.stringify([scopeKey, query, retryKey]);
+    const identity = JSON.stringify([id, source?.scope]);
+    const ids = selectedIds(value);
+    const idsKey = JSON.stringify(ids);
+    const [page, setPage] = useState({ key: "", items: [], loading: false });
+    const [resolved, setResolved] = useState({ key: "", identity: "", choices: [], done: false });
+    const resolveKey = JSON.stringify([scopeKey, idsKey, retryKey]);
+    const currentRequest = useRef(requestKey);
+    useLayoutEffect(() => {
+        currentRequest.current = requestKey;
+    }, [requestKey]);
+    const moreRelease = useRef(undefined);
+    useEffect(() => {
+        if (latest.current?.kind !== "remote" || !enabled)
+            return;
+        const requestSource = latest.current;
+        let alive = true;
+        let release;
+        setPage({ key: requestKey, items: [], loading: true });
+        const timer = setTimeout(() => {
+            const request = acquire(cache, `search:${requestKey}`, (signal) => requestSource.search(query, undefined, signal));
+            release = request.release;
+            request.promise.then((result) => {
+                if (alive)
+                    setPage({
+                        key: requestKey,
+                        items: [...result.items],
+                        cursor: result.cursor,
+                        loading: false,
+                    });
+            }, (error) => {
+                if (alive)
+                    setPage({ key: requestKey, items: [], loading: false, error: errorMessage(error) });
+            });
+        }, query ? (latest.current.debounceMs ?? 200) : 0);
+        return () => {
+            alive = false;
+            clearTimeout(timer);
+            release?.();
+            moreRelease.current?.();
+        };
+    }, [requestKey, query, enabled, cache]);
+    useEffect(() => {
+        if (latest.current?.kind !== "remote" || ids.length === 0)
+            return;
+        const requestSource = latest.current;
+        let alive = true;
+        const currentIds = JSON.parse(idsKey);
+        const request = acquire(cache, `resolve:${resolveKey}`, async (signal) => ({
+            items: await requestSource.resolve(currentIds, signal),
+        }));
+        request.promise.then((result) => {
+            if (alive)
+                setResolved({ key: resolveKey, identity, choices: result.items, done: true });
+        }, (error) => {
+            if (alive)
+                setResolved((previous) => ({
+                    key: resolveKey,
+                    identity,
+                    choices: previous.identity === identity ? previous.choices : [],
+                    done: true,
+                    error: errorMessage(error),
+                }));
+        });
+        return () => {
+            alive = false;
+            request.release();
+        };
+    }, [resolveKey, idsKey, ids.length, cache, identity]);
+    const remote = source?.kind === "remote";
+    const currentPage = page.key === requestKey
+        ? page
+        : { items: [], loading: enabled, cursor: null, error: undefined };
+    const matchingResolved = resolved.key === resolveKey;
+    const items = remote ? currentPage.items : (source?.items ?? []);
+    const { selected, shown } = optionPresentation(source, items, ids, resolved, matchingResolved, resolved.identity === identity, remote, query);
+    return {
+        query,
+        setQuery(next) {
+            if (source?.onQueryChange)
+                source.onQueryChange(next);
+            else
+                setLocalQuery(next);
+        },
+        items: shown,
+        selected,
+        loading: remote ? currentPage.loading : (source?.loading ?? false),
+        resolving: remote && ids.length > 0 && !matchingResolved,
+        error: currentPage.error ?? (matchingResolved ? resolved.error : undefined) ?? source?.error,
+        retry() {
+            source?.retry?.();
+            retry((key) => key + 1);
+        },
+        hasMore: remote ? Boolean(currentPage.cursor) : (source?.hasMore ?? false),
+        loadMore() {
+            if (!remote) {
+                source?.loadMore?.();
+                return;
+            }
+            if (!currentPage.cursor || currentPage.loading)
+                return;
+            const cursor = currentPage.cursor;
+            setPage((previous) => ({ ...previous, loading: true, error: undefined }));
+            const request = acquire(cache, `search:${requestKey}:${cursor}`, (signal) => source.search(query, cursor, signal));
+            moreRelease.current = request.release;
+            request.promise
+                .then((result) => {
+                if (currentRequest.current !== requestKey)
+                    return;
+                setPage((previous) => ({
+                    key: requestKey,
+                    items: [
+                        ...new Map([...previous.items, ...result.items].map((item) => [item.value, item])).values(),
+                    ],
+                    cursor: result.cursor,
+                    loading: false,
+                }));
+            }, (error) => {
+                if (currentRequest.current === requestKey)
+                    setPage((previous) => ({ ...previous, loading: false, error: errorMessage(error) }));
+            })
+                .finally(request.release);
+        },
+    };
+}
+function optionPresentation(source, items, ids, resolved, matchingResolved, retainedLabels, remote, query) {
+    const known = new Map();
+    for (const item of [
+        ...(source?.selectedItems ?? []),
+        ...(retainedLabels ? resolved.choices : []),
+        ...items,
+    ])
+        known.set(item.value, item);
+    const selected = ids.map((id) => known.get(id) ?? {
+        value: id,
+        label: remote && matchingResolved && resolved.done && !resolved.error
+            ? `Unavailable (${id})`
+            : id,
+    });
+    const shown = remote || source?.onQueryChange
+        ? items
+        : items.filter((item) => item.label.toLocaleLowerCase().includes(query.toLocaleLowerCase()));
+    return { selected, shown };
+}

package/dist/filters/use-filters.d.ts

@@ -0,0 +1,78 @@
+import type { BoundDefinitions, FilterDefinitions, FilterValues } from "./filter-definition.js";
+import type { FilterEntry, PasteResult } from "./filter-state.js";
+export interface FilterChange {
+    source: "edit" | "remove" | "clear" | "paste" | "suggestion" | "search";
+}
+export interface FilterController<S = unknown> {
+    values: S;
+    search: string;
+    entries: FilterEntry[];
+    active: FilterEntry[];
+    menuOpen: boolean;
+    setMenuOpen(open: boolean): void;
+    openField: string | null;
+    setOpenField(id: string | null): void;
+    editField: string | null;
+    edit(id: string | null): void;
+    commit(id: string, value: unknown, source?: FilterChange["source"]): string | undefined;
+    batch(changes: Record<string, unknown>, search?: string, source?: FilterChange["source"]): string | undefined;
+    remove(id: string): void;
+    clear(): void;
+    setSearch(search: string): void;
+    paste(text: string, remainder?: {
+        before: string;
+        after: string;
+    }): PasteResult;
+    error: string | null;
+    shareable: boolean;
+    persistenceMessage?: string;
+}
+interface ControllerOptions<S> {
+    entries: FilterEntry[];
+    value: S;
+    search: string;
+    apply(changes: Record<string, unknown>, search: string | undefined, meta: FilterChange): void;
+    onChange?: (value: S, meta: FilterChange) => void;
+}
+export declare function useFilterController<S>(options: ControllerOptions<S>): FilterController<S>;
+export interface LocalFilterOptions<D extends FilterDefinitions> {
+    defaultValues?: Partial<FilterValues<D>>;
+    defaultSearch?: string;
+    onChange?: (values: FilterValues<D>, meta: FilterChange) => void;
+}
+export declare function useFilters<const D extends FilterDefinitions>(definitions: D, options?: LocalFilterOptions<D>): {
+    set<K extends keyof FilterValues<D> & string>(key: K, value: FilterValues<D>[K]): string | undefined;
+    values: FilterValues<D>;
+    search: string;
+    entries: FilterEntry[];
+    active: FilterEntry[];
+    menuOpen: boolean;
+    setMenuOpen(open: boolean): void;
+    openField: string | null;
+    setOpenField(id: string | null): void;
+    editField: string | null;
+    edit(id: string | null): void;
+    commit(id: string, value: unknown, source?: FilterChange["source"]): string | undefined;
+    batch(changes: Record<string, unknown>, search?: string, source?: FilterChange["source"]): string | undefined;
+    remove(id: string): void;
+    clear(): void;
+    setSearch(search: string): void;
+    paste(text: string, remainder?: {
+        before: string;
+        after: string;
+    }): PasteResult;
+    error: string | null;
+    shareable: boolean;
+    persistenceMessage?: string;
+};
+export interface ControlledFilterOptions<S> {
+    definitions: BoundDefinitions<S>;
+    value: S;
+    onPatch(patch: Partial<S>, meta: FilterChange): void;
+    search?: {
+        read(value: S): string;
+        write(search: string, current: S): Partial<S>;
+    };
+}
+export declare function useControlledFilters<S>(options: ControlledFilterOptions<S>): FilterController<S>;
+export {};

package/dist/filters/use-filters.js

@@ -0,0 +1,158 @@
+"use client";
+import { useLayoutEffect, useRef, useState } from "react";
+import { classifyPaste, initialValues } from "./filter-state.js";
+export function useFilterController(options) {
+    const [menuOpen, setMenuOpen] = useState(false);
+    const [openField, setOpenField] = useState(null);
+    const [editField, edit] = useState(null);
+    const [error, setError] = useState(null);
+    function batch(changes, search, source = "edit") {
+        const normalized = {};
+        const entriesById = new Map(options.entries.map((entry) => [entry.id, entry]));
+        for (const [id, value] of Object.entries(changes)) {
+            const entry = entriesById.get(id);
+            if (!entry || entry.field.disabled)
+                continue;
+            try {
+                const next = entry.field.normalize(value);
+                const message = source === "clear" || source === "remove" ? undefined : entry.field.validate(next);
+                if (message) {
+                    setError(message);
+                    return message;
+                }
+                normalized[id] = next;
+            }
+            catch {
+                const message = "This filter value is invalid.";
+                setError(message);
+                return message;
+            }
+        }
+        setError(null);
+        options.apply(normalized, search, { source });
+    }
+    return {
+        values: options.value,
+        search: options.search,
+        entries: options.entries,
+        active: options.entries.filter((entry) => !entry.field.hidden && entry.field.isActive(entry.value)),
+        menuOpen,
+        setMenuOpen: (open) => {
+            setMenuOpen(open);
+            if (!open) {
+                setOpenField(null);
+                setError(null);
+            }
+        },
+        openField,
+        setOpenField,
+        editField,
+        edit: (id) => {
+            edit(id);
+            if (!id)
+                setError(null);
+        },
+        batch,
+        commit: (id, value, source) => batch({ [id]: value }, undefined, source),
+        remove(id) {
+            const entry = options.entries.find((item) => item.id === id);
+            if (entry?.field.removable !== false) {
+                batch({ [id]: entry?.field.clearValue }, undefined, "remove");
+                edit(null);
+            }
+        },
+        clear() {
+            batch(Object.fromEntries(options.entries.flatMap((entry) => entry.field.removable !== false && !entry.field.hidden && !entry.field.disabled
+                ? [[entry.id, entry.field.clearValue]]
+                : [])), "", "clear");
+            edit(null);
+            setMenuOpen(false);
+            setOpenField(null);
+        },
+        setSearch: (search) => {
+            batch({}, search, "search");
+        },
+        paste(text, remainder) {
+            const result = classifyPaste(text, options.entries);
+            const unmatched = [...result.unmatched, ...result.ambiguous.map((item) => item.token)].join(" ");
+            const search = remainder
+                ? [remainder.before, unmatched, remainder.after].filter(Boolean).join(" ")
+                : [options.search, unmatched].filter(Boolean).join(" ");
+            let cursor = [remainder ? remainder.before : options.search, result.unmatched.join(" ")]
+                .filter(Boolean)
+                .join(" ").length;
+            for (const item of result.ambiguous) {
+                if (cursor)
+                    cursor++;
+                item.searchRange = { start: cursor, end: cursor + item.token.length };
+                cursor += item.token.length;
+            }
+            batch(result.changes, search, "paste");
+            return result;
+        },
+        error,
+        shareable: true,
+    };
+}
+export function useFilters(definitions, options = {}) {
+    const [state, setState] = useState(() => ({
+        values: { ...initialValues(definitions), ...options.defaultValues },
+        search: options.defaultSearch ?? "",
+    }));
+    const pending = useRef(state);
+    useLayoutEffect(() => {
+        pending.current = state;
+    }, [state]);
+    const controller = useFilterController({
+        entries: Object.entries(definitions).map(([id, field]) => ({
+            id,
+            field,
+            value: state.values[id] ?? (state.values[id] === null ? null : field.defaultValue),
+        })),
+        value: state.values,
+        search: state.search,
+        apply(changes, search, meta) {
+            const next = {
+                values: { ...pending.current.values, ...changes },
+                search: search ?? pending.current.search,
+            };
+            pending.current = next;
+            setState(next);
+            options.onChange?.(next.values, meta);
+        },
+    });
+    return {
+        ...controller,
+        set(key, value) {
+            return controller.commit(key, value);
+        },
+    };
+}
+export function useControlledFilters(options) {
+    const pending = useRef(options.value);
+    useLayoutEffect(() => {
+        pending.current = options.value;
+    }, [options.value]);
+    return useFilterController({
+        value: options.value,
+        search: options.search?.read(options.value) ?? "",
+        entries: Object.entries(options.definitions).map(([id, field]) => ({
+            id,
+            field: field,
+            value: field.read(options.value),
+        })),
+        apply(changes, search, meta) {
+            let next = pending.current;
+            let patch = {};
+            for (const [id, value] of Object.entries(changes)) {
+                const update = options.definitions[id].write(value, next);
+                patch = { ...patch, ...update };
+                next = { ...next, ...update };
+            }
+            if (search !== undefined && options.search)
+                patch = { ...patch, ...options.search.write(search, next) };
+            pending.current = { ...next, ...patch };
+            options.onPatch(patch, meta);
+        },
+    });
+}

package/dist/filters/use-url-filters.d.ts

@@ -0,0 +1,41 @@
+import type { FilterDefinitions, FilterValues } from "./filter-definition.js";
+import type { FilterChange } from "./use-filters.js";
+export interface UrlFilterOptions {
+    /** Include the current organization/user when remembering scoped data. */
+    scope: string;
+    searchKey?: string;
+    markerKey?: string;
+    remember?: "session" | false;
+    maxUrlLength?: number;
+    history?: "replace" | "push";
+    shallow?: boolean;
+    onPersistenceError?: (message: string) => void;
+}
+/** Uses nuqs as the applied state owner. Only overflow values live outside the URL. */
+export declare function useUrlFilters<const D extends FilterDefinitions>(definitions: D, options: UrlFilterOptions): {
+    ready: boolean;
+    shareable: boolean;
+    persistenceMessage: string | undefined;
+    set<K extends keyof FilterValues<D> & string>(key: K, value: FilterValues<D>[K]): string | undefined;
+    createLink(base: string): string | null;
+    values: FilterValues<D>;
+    search: string;
+    entries: import("./filter-state.js").FilterEntry[];
+    active: import("./filter-state.js").FilterEntry[];
+    menuOpen: boolean;
+    setMenuOpen(open: boolean): void;
+    openField: string | null;
+    setOpenField(id: string | null): void;
+    editField: string | null;
+    edit(id: string | null): void;
+    commit(id: string, value: unknown, source?: FilterChange["source"]): string | undefined;
+    batch(changes: Record<string, unknown>, search?: string, source?: FilterChange["source"]): string | undefined;
+    remove(id: string): void;
+    clear(): void;
+    setSearch(search: string): void;
+    paste(text: string, remainder?: {
+        before: string;
+        after: string;
+    }): import("./filter-state.js").PasteResult;
+    error: string | null;
+};

package/dist/filters/use-url-filters.js

@@ -0,0 +1,197 @@
+"use client";
+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import { parseAsString, useQueryStates } from "nuqs";
+import { decodeFilters, encodeFilters, validateDefinitions } from "./filter-state.js";
+import { useFilterController } from "./use-filters.js";
+const subscribeStorage = () => () => { };
+function useStoredQuery(key) {
+    return useSyncExternalStore(subscribeStorage, () => (key ? (readSnapshot(key)?.query ?? null) : null), () => null);
+}
+function readSnapshot(key) {
+    try {
+        const raw = sessionStorage.getItem(key);
+        if (!raw)
+            return null;
+        const value = JSON.parse(raw);
+        return typeof value === "object" &&
+            value !== null &&
+            "query" in value &&
+            typeof value.query === "string" &&
+            "savedAt" in value &&
+            typeof value.savedAt === "number"
+            ? value
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Uses nuqs as the applied state owner. Only overflow values live outside the URL. */
+export function useUrlFilters(definitions, options) {
+    const searchKey = options.searchKey ?? "q";
+    const markerKey = options.markerKey ?? "_filters";
+    validateDefinitions(definitions, searchKey, markerKey);
+    const keys = [
+        ...Object.entries(definitions).map(([id, field]) => field.urlKey ?? id),
+        searchKey,
+        markerKey,
+    ];
+    const parsers = Object.fromEntries(keys.map((key) => [key, parseAsString]));
+    const [raw, setRaw] = useQueryStates(parsers, {
+        history: options.history ?? "replace",
+        shallow: options.shallow ?? true,
+    });
+    const [overflow, setOverflow] = useState(null);
+    const [message, setMessage] = useState();
+    const [ready, setReady] = useState(false);
+    const latest = useRef({ definitions, options, raw });
+    useLayoutEffect(() => {
+        latest.current = { definitions, options, raw };
+    }, [definitions, options, raw]);
+    const path = typeof window === "undefined" ? "" : window.location.pathname;
+    const storageKey = `mendy-ui:filters:${path}:${searchKey}:${options.scope}`;
+    const marker = raw[markerKey];
+    const storedQuery = useStoredQuery(marker ? `${storageKey}:overflow:${marker}` : null);
+    const pending = useRef(null);
+    const fullParams = appliedParams(raw, keys, marker, overflow, storedQuery, options.scope);
+    const values = decodeFilters(definitions, fullParams);
+    const search = fullParams.get(searchKey) ?? "";
+    useLayoutEffect(() => {
+        pending.current = { values, search };
+    }, [values, search]);
+    function report(text) {
+        setMessage(text);
+        options.onPersistenceError?.(text);
+    }
+    function writeSnapshot(key, query) {
+        try {
+            sessionStorage.setItem(key, JSON.stringify({ query, savedAt: Date.now() }));
+            return true;
+        }
+        catch {
+            report("Filters could not be saved in this browser. Keep this page open to retain them.");
+            return false;
+        }
+    }
+    function update(values, search, source) {
+        pending.current = { values, search };
+        const full = encodeFilters(definitions, values, new URLSearchParams(window.location.search));
+        full.delete(markerKey);
+        if (search)
+            full.set(searchKey, search);
+        else
+            full.delete(searchKey);
+        const owned = new URLSearchParams();
+        for (const key of keys)
+            if (full.has(key))
+                owned.set(key, full.get(key));
+        const exceeds = `${window.location.origin}${window.location.pathname}?${full}`.length >
+            (options.maxUrlLength ?? 2000);
+        const next = Object.fromEntries(keys.map((key) => [key, full.get(key)]));
+        setMessage(undefined);
+        if (exceeds) {
+            const token = crypto.randomUUID();
+            writeSnapshot(`${storageKey}:overflow:${token}`, owned.toString());
+            setOverflow({ marker: token, scope: options.scope, query: owned.toString() });
+            for (const key of keys)
+                next[key] = null;
+            next[markerKey] = token;
+            // Bound saved history while retaining recent overflow states for browser navigation.
+            try {
+                const prefix = `${storageKey}:overflow:`;
+                const saved = Object.keys(sessionStorage)
+                    .flatMap((key) => key.startsWith(prefix) ? [{ key, time: readSnapshot(key)?.savedAt ?? 0 }] : [])
+                    .sort((a, b) => b.time - a.time);
+                for (const item of saved.slice(30))
+                    sessionStorage.removeItem(item.key);
+            }
+            catch {
+                /* Storage failure was already reported by writeSnapshot. */
+            }
+        }
+        else
+            setOverflow(null);
+        if (options.remember === "session") {
+            if (source === "clear") {
+                try {
+                    sessionStorage.removeItem(storageKey);
+                }
+                catch {
+                    report("Remembered filters could not be cleared in this browser.");
+                }
+            }
+            else
+                writeSnapshot(storageKey, owned.toString());
+        }
+        void setRaw(next).catch(() => report("The URL could not be updated. Filters may not survive a reload."));
+    }
+    useEffect(() => {
+        setReady(true);
+        const current = latest.current;
+        const address = new URLSearchParams(window.location.search);
+        const hasUrl = [
+            ...Object.entries(current.definitions).map(([id, field]) => field.urlKey ?? id),
+            searchKey,
+            markerKey,
+        ].some((key) => address.has(key));
+        if (!hasUrl && current.options.remember === "session") {
+            const saved = readSnapshot(storageKey);
+            if (saved) {
+                const params = new URLSearchParams(saved.query);
+                const restored = decodeFilters(current.definitions, params);
+                update(restored, params.get(searchKey) ?? "", "edit");
+            }
+        }
+        // Restoration runs once per storage scope. URL changes subsequently belong to nuqs.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [storageKey]);
+    const controller = useFilterController({
+        value: values,
+        search,
+        entries: Object.entries(definitions).map(([id, field]) => ({ id, field, value: values[id] })),
+        apply(changes, nextSearch, meta) {
+            update({ ...pending.current.values, ...changes }, nextSearch ?? pending.current.search, meta.source);
+        },
+    });
+    return {
+        ...controller,
+        ready,
+        shareable: !marker,
+        persistenceMessage: persistenceNotice(ready, marker, storedQuery, overflow?.marker, message),
+        set(key, value) {
+            return controller.commit(key, value);
+        },
+        createLink(base) {
+            if (marker)
+                return null;
+            const url = new URL(base, window.location.origin);
+            const params = encodeFilters(definitions, values, url.searchParams);
+            params.delete(markerKey);
+            if (search)
+                params.set(searchKey, search);
+            else
+                params.delete(searchKey);
+            url.search = params.toString();
+            return url.toString();
+        },
+    };
+}
+function persistenceNotice(ready, marker, storedQuery, memoryMarker, message) {
+    if (ready && marker && storedQuery === null && memoryMarker !== marker)
+        return "This link refers to filters saved in another browser session. The full selection is unavailable.";
+    if (message)
+        return message;
+    if (marker)
+        return "This selection is saved in this browser session. The URL does not contain the full filters.";
+}
+function appliedParams(raw, keys, marker, overflow, stored, scope) {
+    if (overflow && overflow.marker === marker && overflow.scope === scope)
+        return new URLSearchParams(overflow.query);
+    if (marker && stored !== null)
+        return new URLSearchParams(stored);
+    const params = new URLSearchParams();
+    for (const key of keys)
+        if (raw[key] != null)
+            params.set(key, raw[key]);
+    return params;
+}