Add parseListQuery helper (todo §1); read a list URL into { q, filters, sort, page, pageSize }, defaults+clamp, zero-throw

src/list-query.ts

@@ -0,0 +1,72 @@
+// parseListQuery (todo §1): read a list-page URL into the state the building blocks render
+// from — search, filters, sort, pagination. The URL is the only list state (README
+// "Interactivity"), so this is the inverse of the filter-bar GET form, the sort links and the
+// pagination links: bookmarkable, shareable, reproducible. Pure; never throws.
+
+export interface ListSort {
+  dir: "asc" | "desc";
+  field: string;
+}
+
+export interface ListQuery {
+  filters: Record<string, string[]>; // every non-reserved param; multi-value kept, empties dropped
+  page: number; // ≥ 1
+  pageSize: number; // clamped to [1, maxPageSize]
+  q: string; // trimmed search text, "" when absent
+  sort: ListSort | null; // "field" ⇒ asc, "-field" ⇒ desc
+}
+
+export interface ListQueryOptions {
+  defaultPageSize?: number; // used when pageSize is absent/invalid (default 25)
+  maxPageSize?: number; // upper clamp (default 100)
+  pageParam?: string; // default "page"
+  pageSizeParam?: string; // default "pageSize"
+  qParam?: string; // default "q"
+  sortParam?: string; // default "sort"
+}
+
+export function parseListQuery(url: URL | URLSearchParams | string, options: ListQueryOptions = {}): ListQuery {
+  const params = toParams(url);
+  const qParam = options.qParam ?? "q";
+  const sortParam = options.sortParam ?? "sort";
+  const pageParam = options.pageParam ?? "page";
+  const pageSizeParam = options.pageSizeParam ?? "pageSize";
+  const reserved = new Set([pageParam, pageSizeParam, qParam, sortParam]);
+
+  const filters: Record<string, string[]> = {};
+  for (const key of new Set(params.keys())) {
+    if (reserved.has(key)) continue;
+    const values = params.getAll(key).filter((v) => v !== "");
+    if (values.length) filters[key] = values;
+  }
+
+  return {
+    filters,
+    page: positiveInt(params.get(pageParam)) ?? 1,
+    pageSize: Math.min(positiveInt(params.get(pageSizeParam)) ?? (options.defaultPageSize ?? 25), options.maxPageSize ?? 100),
+    q: (params.get(qParam) ?? "").trim(),
+    sort: parseSort(params.get(sortParam)),
+  };
+}
+
+function toParams(url: URL | URLSearchParams | string): URLSearchParams {
+  if (typeof url === "string") {
+    const i = url.indexOf("?");
+    return new URLSearchParams(i >= 0 ? url.slice(i + 1) : url);
+  }
+  return url instanceof URL ? url.searchParams : url;
+}
+
+// A strictly positive integer, else null so the caller falls back to a default.
+function positiveInt(raw: string | null): number | null {
+  if (raw == null || raw.trim() === "") return null;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 ? n : null;
+}
+
+function parseSort(raw: string | null): ListSort | null {
+  if (raw == null) return null;
+  const desc = raw.startsWith("-");
+  const field = (desc ? raw.slice(1) : raw).trim();
+  return field ? { dir: desc ? "desc" : "asc", field } : null;
+}