@flaredev/cli 0.5.1 → 0.6.1

package/templates/app/lib/cache.ts

@@ -1,83 +1,83 @@
-import { revalidateTag, unstable_cache } from "next/cache";
-import type { ChangeEvent } from "@flaredev/core/server";
-
-/**
- * Caching for data you read far more often than you write.
- *
- * Only the **data cache** (Workers KV) is configured in `vite.config.ts`. It is
- * what `cached()` below, `fetch()` and `"use cache"` write to. Shared by every
- * colo and every isolate, so a value computed once is reused until it expires or
- * its tag is revalidated.
- *
- * vinext's page-level CDN cache (the Workers Cache `cdn` adapter) is off until a
- * vinext fix lands: in the current beta, pages that redirect break behind it.
- *
- * Nothing here caches per-user data: everything keyed by session belongs
- * outside the cache, since these entries are shared between visitors.
- */
-
-/** How long cached values stay fresh, in seconds. Pick the one that matches how stale you can stand. */
-export const TTL = {
-  /** Changes often, cheap to recompute: counts, dashboards. */
-  short: 60,
-  /** The usual case: lists and detail views behind a resource tag. */
-  medium: 5 * 60,
-  /** Rarely changes: settings, published content, reference tables. */
-  long: 60 * 60,
-} as const;
-
-/** Tag for everything derived from a resource, e.g. `resource/Deal`. */
-export const resourceTag = (resource: string) => `resource/${resource}`;
-
-/** Tag for one record, e.g. `resource/Deal/0f9…`. */
-export const recordTag = (resource: string, id: string) => `resource/${resource}/${id}`;
-
-/**
- * The KV data cache silently ignores tags containing `:`, `\` or control
- * characters — the entry is stored untagged, so no revalidation ever reaches
- * it. Refuse them here instead, where the mistake is still visible.
- */
-function checkTag(tag: string): string {
-  if (!tag || tag.length > 256 || /[\x00-\x1f\\:]/.test(tag)) {
-    throw new Error(`Cache tag "${tag}" can't be used: tags must be 1–256 characters without ":", "\\" or control characters.`);
-  }
-  return tag;
-}
-
-/**
- * Cache the result of an async function in the data cache.
- *
- * `keyParts` identify the value (include every argument the result depends on);
- * `tags` say what invalidates it. Cached functions must not read cookies,
- * headers, or anything else request-specific — the value is shared.
- *
- * ```ts
- * const openDeals = cached(
- *   () => getDb().select({ total: count() }).from(deals).where(eq(deals.stage, "open")),
- *   ["deals", "open-count"],
- *   { tags: [resourceTag("Deal")] },
- * );
- * ```
- */
-export function cached<Args extends unknown[], Value>(
-  fn: (...args: Args) => Promise<Value>,
-  keyParts: string[],
-  options: { tags?: string[]; revalidate?: number } = {},
-) {
-  return unstable_cache(fn, keyParts, {
-    revalidate: options.revalidate ?? TTL.medium,
-    tags: (options.tags ?? []).map(checkTag),
-  });
-}
-
-/**
- * Drop everything cached for a resource (and for the record that changed).
- * `lib/dashboard.ts` and `lib/api.ts` pass this to the store, so writes through the
- * admin or the REST API invalidate without anyone remembering to call it.
- */
-export function revalidateResource({ resource, action, id }: ChangeEvent) {
-  // { expire: 0 }: drop the entry now rather than serving it stale while it refreshes.
-  // A record someone just edited should never come back with its old values.
-  revalidateTag(resourceTag(resource), { expire: 0 });
-  if (action !== "create") revalidateTag(recordTag(resource, id), { expire: 0 });
-}
+import { revalidateTag, unstable_cache } from "next/cache";
+import type { ChangeEvent } from "@/lib/resource/store";
+
+/**
+ * Caching for data you read far more often than you write.
+ *
+ * Only the **data cache** (Workers KV) is configured in `vite.config.ts`. It is
+ * what `cached()` below, `fetch()` and `"use cache"` write to. Shared by every
+ * colo and every isolate, so a value computed once is reused until it expires or
+ * its tag is revalidated.
+ *
+ * vinext's page-level CDN cache (the Workers Cache `cdn` adapter) is off until a
+ * vinext fix lands: in the current beta, pages that redirect break behind it.
+ *
+ * Nothing here caches per-user data: everything keyed by session belongs
+ * outside the cache, since these entries are shared between visitors.
+ */
+
+/** How long cached values stay fresh, in seconds. Pick the one that matches how stale you can stand. */
+export const TTL = {
+  /** Changes often, cheap to recompute: counts, dashboards. */
+  short: 60,
+  /** The usual case: lists and detail views behind a resource tag. */
+  medium: 5 * 60,
+  /** Rarely changes: settings, published content, reference tables. */
+  long: 60 * 60,
+} as const;
+
+/** Tag for everything derived from a resource, e.g. `resource/Deal`. */
+export const resourceTag = (resource: string) => `resource/${resource}`;
+
+/** Tag for one record, e.g. `resource/Deal/0f9…`. */
+export const recordTag = (resource: string, id: string) => `resource/${resource}/${id}`;
+
+/**
+ * The KV data cache silently ignores tags containing `:`, `\` or control
+ * characters — the entry is stored untagged, so no revalidation ever reaches
+ * it. Refuse them here instead, where the mistake is still visible.
+ */
+function checkTag(tag: string): string {
+  if (!tag || tag.length > 256 || /[\x00-\x1f\\:]/.test(tag)) {
+    throw new Error(`Cache tag "${tag}" can't be used: tags must be 1–256 characters without ":", "\\" or control characters.`);
+  }
+  return tag;
+}
+
+/**
+ * Cache the result of an async function in the data cache.
+ *
+ * `keyParts` identify the value (include every argument the result depends on);
+ * `tags` say what invalidates it. Cached functions must not read cookies,
+ * headers, or anything else request-specific — the value is shared.
+ *
+ * ```ts
+ * const openDeals = cached(
+ *   () => getDb().select({ total: count() }).from(deals).where(eq(deals.stage, "open")),
+ *   ["deals", "open-count"],
+ *   { tags: [resourceTag("Deal")] },
+ * );
+ * ```
+ */
+export function cached<Args extends unknown[], Value>(
+  fn: (...args: Args) => Promise<Value>,
+  keyParts: string[],
+  options: { tags?: string[]; revalidate?: number } = {},
+) {
+  return unstable_cache(fn, keyParts, {
+    revalidate: options.revalidate ?? TTL.medium,
+    tags: (options.tags ?? []).map(checkTag),
+  });
+}
+
+/**
+ * Drop everything cached for a resource (and for the record that changed).
+ * `lib/dashboard.ts` and `lib/api.ts` pass this to the store, so writes through the
+ * admin or the REST API invalidate without anyone remembering to call it.
+ */
+export function revalidateResource({ resource, action, id }: ChangeEvent) {
+  // { expire: 0 }: drop the entry now rather than serving it stale while it refreshes.
+  // A record someone just edited should never come back with its old values.
+  revalidateTag(resourceTag(resource), { expire: 0 });
+  if (action !== "create") revalidateTag(recordTag(resource, id), { expire: 0 });
+}

package/templates/app/lib/dashboard.ts

@@ -3,7 +3,7 @@ import { notFound, redirect } from "next/navigation";
 import { allowedActions, can, type Policy, type PolicyAction, type Resource } from "@flaredev/core";
 import { count, sql } from "drizzle-orm";
 import type { SQLiteTable } from "drizzle-orm/sqlite-core";
-import { createResourceStore, type ResourceStore } from "@flaredev/core/server";
+import { createResourceStore, drizzleRows, type ResourceStore } from "@/lib/resource";
 import { getDb } from "@/db";
 import { policies } from "@/policies";
 import { resourceTables } from "@/resources/server";
@@ -66,7 +66,7 @@ export function dashboardStore(name: string): ResourceStore {
   if (!entry) notFound();
   let store = stores.get(name);
   if (!store) {
-    store = createResourceStore({ resource: entry.resource, table: entry.table, getDb, onChange: revalidateResource, currentUser });
+    store = createResourceStore({ resource: entry.resource, rows: drizzleRows(entry.table, getDb), onChange: revalidateResource, currentUser });
     stores.set(name, store);
   }
   return store;

package/templates/app/lib/resource/drizzle-rows.ts

@@ -0,0 +1,134 @@
+// This file is yours.
+//
+// Flare copies the code that turns a resource descriptor into a working endpoint into
+// your app rather than hiding it in node_modules, for the same reason shadcn/ui copies
+// a component: you cannot fix, read or reason about what you cannot see. Nothing here
+// is imported from the framework at runtime — change it, delete it, replace it.
+//
+// `flare diff` shows how your copy differs from the version Flare ships, and
+// `flare update` applies the parts you choose. Neither runs unless you ask.
+
+/**
+ * {@link ResourceRows} over Drizzle and SQLite — the Cloudflare stack's half.
+ *
+ * This is the query building that used to sit inside the store, moved out so the store
+ * itself has no dialect in it. Behaviour is unchanged on purpose: the same LIKE search,
+ * the same `(sort, id)` cursor comparison, the same capped count.
+ */
+import { and, asc, count, desc, eq, getTableColumns, inArray, isNull, or, sql, type SQL } from "drizzle-orm";
+import type { BaseSQLiteDatabase, SQLiteColumn, SQLiteTable } from "drizzle-orm/sqlite-core";
+import type { ConstraintHit, ResourceRows, Row, RowsQuery } from "./rows";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyDatabase = BaseSQLiteDatabase<"sync" | "async", any, any>;
+
+/** Walks an error and its causes (drizzle and D1 both wrap SQLite errors). */
+function errorText(error: unknown): string {
+  const parts: string[] = [];
+  for (let current = error, depth = 0; current && depth < 5; depth++) {
+    if (current instanceof Error) {
+      parts.push(current.message);
+      current = current.cause;
+    } else {
+      parts.push(String(current));
+      break;
+    }
+  }
+  return parts.join(" | ");
+}
+
+export function drizzleRows(table: SQLiteTable, getDb: () => AnyDatabase): ResourceRows & { columns: Record<string, SQLiteColumn> } {
+  const columns = getTableColumns(table) as Record<string, SQLiteColumn>;
+  const idColumn = columns.id!;
+  const byId = (id: string) => eq(idColumn, id);
+
+  /** The search and filter half of a where clause — everything but the cursor. */
+  function matching(query: Pick<RowsQuery, "search" | "filters">): SQL[] {
+    const conditions: SQL[] = [];
+    if (query.search && query.search.fields.length > 0) {
+      const pattern = `%${query.search.term.replace(/[\\%_]/g, (char) => `\\${char}`)}%`;
+      const searchable = query.search.fields.map((key) => columns[key]!);
+      conditions.push(or(...searchable.map((column) => sql`${column} LIKE ${pattern} ESCAPE '\\'`))!);
+    }
+    for (const [key, value] of Object.entries(query.filters)) {
+      conditions.push(value === null ? isNull(columns[key]!) : eq(columns[key]!, value));
+    }
+    return conditions;
+  }
+
+  return {
+    columns,
+    get db() {
+      return getDb();
+    },
+
+    async find(query) {
+      const conditions = matching(query);
+      const sortColumn = columns[query.sort.field]!;
+      const descending = query.sort.direction === "desc";
+      const order = descending ? [desc(sortColumn), desc(idColumn)] : [asc(sortColumn), asc(idColumn)];
+
+      if (query.cursor) {
+        // Compared as the column stores it: a date column's driver mapper expects a Date,
+        // and a cursor carries the milliseconds it was read as, so this stays raw SQL.
+        const { value, id, greaterThan } = query.cursor;
+        conditions.push(
+          greaterThan
+            ? or(sql`${sortColumn} > ${value}`, and(sql`${sortColumn} = ${value}`, sql`${idColumn} > ${id}`))!
+            : or(sql`${sortColumn} < ${value}`, and(sql`${sortColumn} = ${value}`, sql`${idColumn} < ${id}`))!,
+        );
+      }
+
+      const where = conditions.length ? and(...conditions) : undefined;
+      const statement = getDb().select().from(table).where(where).orderBy(...order).limit(query.limit);
+      const rows = query.offset ? await statement.offset(query.offset) : await statement;
+      return rows as Row[];
+    },
+
+    async countUpTo(query, limit) {
+      const conditions = matching(query);
+      const where = conditions.length ? and(...conditions) : undefined;
+      const db = getDb();
+      // Counting a subquery that stops at the cap, rather than the whole table.
+      const [counted] = await db
+        .select({ total: count() })
+        .from(db.select({ id: idColumn }).from(table).where(where).limit(limit).as("capped"));
+      return counted?.total ?? 0;
+    },
+
+    async byId(id) {
+      const [record] = await getDb().select().from(table).where(byId(id)).limit(1);
+      return (record as Row | undefined) ?? null;
+    },
+
+    async titles(ids, titleField) {
+      const titleColumn = columns[titleField] ?? idColumn;
+      const rows = await getDb().select({ id: idColumn, title: titleColumn }).from(table).where(inArray(idColumn, ids));
+      return rows as { id: string; title: unknown }[];
+    },
+
+    async insert(values) {
+      const [record] = await getDb().insert(table).values(values).returning();
+      return record as Row;
+    },
+
+    async update(id, values) {
+      const [record] = await getDb().update(table).set(values).where(byId(id)).returning();
+      return (record as Row | undefined) ?? null;
+    },
+
+    async remove(id) {
+      const deleted = await getDb().delete(table).where(byId(id)).returning({ id: idColumn });
+      return deleted.length > 0;
+    },
+
+    constraint(error): ConstraintHit | undefined {
+      const text = errorText(error);
+      const unique = /UNIQUE constraint failed: ([\w.]+(?:, [\w.]+)*)/.exec(text);
+      if (unique) return { kind: "unique", column: unique[1]!.split(", ")[0]!.split(".").pop() };
+      if (/FOREIGN KEY constraint failed/.test(text)) return { kind: "foreignKey" };
+      if (/CHECK constraint failed/.test(text)) return { kind: "check" };
+      return undefined;
+    },
+  };
+}

package/templates/app/lib/resource/handlers.ts

@@ -0,0 +1,157 @@
+// This file is yours.
+//
+// Flare copies the code that turns a resource descriptor into a working endpoint into
+// your app rather than hiding it in node_modules, for the same reason shadcn/ui copies
+// a component: you cannot fix, read or reason about what you cannot see. Nothing here
+// is imported from the framework at runtime — change it, delete it, replace it.
+//
+// `flare diff` shows how your copy differs from the version Flare ships, and
+// `flare update` applies the parts you choose. Neither runs unless you ask.
+
+import type { Resource } from "@flaredev/core";
+import type { ResourceRows } from "./rows";
+import {
+  createResourceStore,
+  type ChangeEvent,
+  type Failure,
+  type ResourceAction,
+  type ResourceStoreOptions,
+  type Result,
+} from "./store";
+
+export type { ResourceAction } from "./store";
+
+export interface AuthorizeContext {
+  request: Request;
+  resource: Resource;
+  action: ResourceAction;
+  id?: string;
+}
+
+/** Return a Response (e.g. 401/403) to deny the request; return nothing to allow it. */
+export type Authorize = (context: AuthorizeContext) => Response | void | Promise<Response | void>;
+
+export interface ResourceHandlerOptions {
+  resource: Resource;
+  /** Where rows come from. See {@link ResourceStoreOptions.rows}. */
+  rows: ResourceRows;
+  authorize: Authorize;
+  /** Who is making the request, for the descriptor's hooks. */
+  currentUser?: ResourceStoreOptions["currentUser"];
+  /** Called after a write succeeds, for cache invalidation. */
+  onChange?: (event: ChangeEvent) => void | Promise<void>;
+}
+
+type RouteContext = { params: Promise<{ id: string }> };
+
+const problem = (status: number, error: string, extra: object = {}) => Response.json({ error, ...extra }, { status });
+
+function failureResponse(failure: Failure): Response {
+  if (failure.queryIssues) return problem(failure.status, failure.error, { issues: failure.queryIssues });
+  const extra: Record<string, unknown> = {};
+  if (failure.issues) extra.issues = failure.issues;
+  if (failure.field) extra.field = failure.field;
+  return problem(failure.status, failure.error, extra);
+}
+
+const respond = <T>(result: Result<T>, init?: ResponseInit) =>
+  result.ok ? Response.json(result.data, init) : failureResponse(result);
+
+/** REST route handlers for a resource: thin HTTP wrappers over `createResourceStore`. */
+export function createResourceHandlers(options: ResourceHandlerOptions) {
+  const { resource, authorize } = options;
+  const store = createResourceStore(options);
+
+  /** Deny cross-site writes: browsers send Origin on POST/PATCH/PUT/DELETE. */
+  const crossOrigin = (request: Request) => {
+    const origin = request.headers.get("origin");
+    return origin !== null && origin !== new URL(request.url).origin;
+  };
+
+  async function readBody(request: Request): Promise<{ body: unknown } | { response: Response }> {
+    if (crossOrigin(request)) return { response: problem(403, "Cross-origin request blocked.") };
+    const type = request.headers.get("content-type") ?? "";
+    if (!/^application\/json\b/i.test(type)) return { response: problem(415, "Send JSON with Content-Type: application/json.") };
+    try {
+      return { body: await request.json() };
+    } catch {
+      return { response: problem(400, "Request body isn't valid JSON.") };
+    }
+  }
+
+  const guard = async (context: AuthorizeContext) => (await authorize(context)) ?? undefined;
+
+  /**
+   * Read and drop a body the handler didn't consume (a 401/403/415 answered early).
+   * Answering with it unread breaks the next request through wrangler's local dev
+   * proxy ("Network connection lost"). Streams, so memory stays flat.
+   */
+  async function drain(request: Request) {
+    if (!request.body || request.bodyUsed) return;
+    try {
+      const reader = request.body.getReader();
+      while (!(await reader.read()).done);
+    } catch {
+      // The client went away.
+    }
+  }
+  const draining =
+    <Rest extends unknown[]>(handler: (request: Request, ...rest: Rest) => Promise<Response>) =>
+    async (request: Request, ...rest: Rest): Promise<Response> => {
+      const response = await handler(request, ...rest);
+      await drain(request);
+      return response;
+    };
+
+  async function GET(request: Request): Promise<Response> {
+    const denied = await guard({ request, resource, action: "list" });
+    if (denied) return denied;
+    return respond(await store.list(new URL(request.url).searchParams));
+  }
+
+  async function POST(request: Request): Promise<Response> {
+    const denied = await guard({ request, resource, action: "create" });
+    if (denied) return denied;
+    const read = await readBody(request);
+    if ("response" in read) return read.response;
+    const result = await store.create(read.body);
+    if (!result.ok) return failureResponse(result);
+    const location = `${new URL(request.url).pathname.replace(/\/$/, "")}/${result.data.id as string}`;
+    return Response.json(result.data, { status: 201, headers: { location } });
+  }
+
+  async function item(request: Request, context: RouteContext, action: ResourceAction, work: (id: string) => Promise<Response>) {
+    const { id } = await context.params;
+    const denied = await guard({ request, resource, action, id });
+    if (denied) return denied;
+    return work(id);
+  }
+
+  const withBody = (request: Request, run: (body: unknown) => Promise<Response>) =>
+    readBody(request).then((read) => ("response" in read ? read.response : run(read.body)));
+
+  const itemHandlers = {
+    GET: (request: Request, context: RouteContext) => item(request, context, "read", async (id) => respond(await store.get(id))),
+    PATCH: (request: Request, context: RouteContext) =>
+      item(request, context, "update", (id) => withBody(request, async (body) => respond(await store.update(id, body)))),
+    PUT: (request: Request, context: RouteContext) =>
+      item(request, context, "update", (id) => withBody(request, async (body) => respond(await store.replace(id, body)))),
+    DELETE: (request: Request, context: RouteContext) =>
+      item(request, context, "delete", async (id) => {
+        if (crossOrigin(request)) return problem(403, "Cross-origin request blocked.");
+        const result = await store.delete(id);
+        return result.ok ? new Response(null, { status: 204 }) : failureResponse(result);
+      }),
+  };
+
+  return {
+    collection: { GET, POST: draining(POST) },
+    item: {
+      GET: itemHandlers.GET,
+      PATCH: draining(itemHandlers.PATCH),
+      PUT: draining(itemHandlers.PUT),
+      DELETE: draining(itemHandlers.DELETE),
+    },
+    store,
+  };
+}

package/templates/app/lib/resource/index.ts

@@ -0,0 +1,14 @@
+// The resource engine, in your app.
+//
+// Re-exported from one place so a route reads `from "@/lib/resource"`. Every file
+// behind it is in this folder and is yours to change.
+//
+// On the Cloudflare stack the row adapter is Drizzle over D1; a Next.js app has
+// prisma-rows.ts here instead. Both implement ResourceRows, which is the whole
+// contract — about fifty lines in rows.ts, and the reason a descriptor doesn't care
+// which database it is on.
+export * from "./rows";
+export * from "./query";
+export * from "./store";
+export * from "./handlers";
+export * from "./drizzle-rows";

package/templates/app/lib/resource/query.ts

@@ -0,0 +1,149 @@
+// This file is yours.
+//
+// Flare copies the code that turns a resource descriptor into a working endpoint into
+// your app rather than hiding it in node_modules, for the same reason shadcn/ui copies
+// a component: you cannot fix, read or reason about what you cannot see. Nothing here
+// is imported from the framework at runtime — change it, delete it, replace it.
+//
+// `flare diff` shows how your copy differs from the version Flare ships, and
+// `flare update` applies the parts you choose. Neither runs unless you ask.
+
+import { storedFields, type Resource } from "@flaredev/core";
+import type { StoredField } from "@flaredev/core";
+
+export interface ListQuery {
+  page: number;
+  perPage: number;
+  sort: { field: string; direction: "asc" | "desc" };
+  q?: string;
+  /** Field key → coerced value; `null` means IS NULL. */
+  filters: Record<string, string | number | boolean | null>;
+  /**
+   * Where to carry on from, instead of counting rows to skip. `OFFSET 500000` makes
+   * SQLite walk half a million index entries before it reads anything (8s at a million
+   * rows); a cursor turns that into a range scan (~100ms).
+   */
+  cursor?: Cursor;
+}
+
+/** The last row of the page you came from, and which way you're going. */
+export interface Cursor {
+  /** The sort field's value on that row. */
+  value: string | number | boolean | null;
+  id: string;
+  direction: "after" | "before";
+}
+
+/** Cursors travel in the URL, so they're base64url of the smallest JSON that works. */
+export function encodeCursor(cursor: Cursor): string {
+  const json = JSON.stringify([cursor.value, cursor.id, cursor.direction === "before" ? 0 : 1]);
+  return btoa(json).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function decodeCursor(raw: string): Cursor | undefined {
+  try {
+    const json = atob(raw.replace(/-/g, "+").replace(/_/g, "/"));
+    const parsed = JSON.parse(json) as [string | number | boolean | null, string, number];
+    if (!Array.isArray(parsed) || typeof parsed[1] !== "string") return undefined;
+    return { value: parsed[0], id: parsed[1], direction: parsed[2] === 0 ? "before" : "after" };
+  } catch {
+    return undefined;
+  }
+}
+
+export interface QueryIssue {
+  param: string;
+  message: string;
+}
+
+const TIMESTAMP_FIELDS = ["createdAt", "updatedAt"];
+const MAX_PER_PAGE = 100;
+const MAX_SEARCH_LENGTH = 200;
+
+export function isSortable(def: StoredField): boolean {
+  return def.sortable ?? !["text", "file"].includes(def.kind);
+}
+
+export function isFilterable(def: StoredField): boolean {
+  return def.filterable ?? ["enum", "boolean", "belongsTo"].includes(def.kind);
+}
+
+export function isSearchable(def: StoredField): boolean {
+  return def.searchable ?? def.kind === "string";
+}
+
+function coerce(def: StoredField, raw: string): string | number | boolean | null | undefined {
+  if (raw === "null") return def.required ? undefined : null;
+  switch (def.kind) {
+    case "boolean":
+      return raw === "true" || raw === "1" ? true : raw === "false" || raw === "0" ? false : undefined;
+    case "int":
+      return /^-?\d+$/.test(raw) ? Number(raw) : undefined;
+    case "float":
+      return raw.trim() !== "" && Number.isFinite(Number(raw)) ? Number(raw) : undefined;
+    case "enum":
+      return def.options.includes(raw) ? raw : undefined;
+    default:
+      return raw;
+  }
+}
+
+/**
+ * Parse `?page=2&perPage=50&sort=-createdAt&q=ada&filter[status]=lead` against a
+ * resource. Only fields the descriptor marks sortable/filterable/searchable are
+ * accepted, so clients can't probe arbitrary columns.
+ */
+export function parseListQuery(resource: Resource, params: URLSearchParams): { query: ListQuery } | { issues: QueryIssue[] } {
+  const issues: QueryIssue[] = [];
+  const fields = new Map(storedFields(resource));
+
+  const positiveInt = (name: string, fallback: number, max = Number.MAX_SAFE_INTEGER) => {
+    const raw = params.get(name);
+    if (raw === null) return fallback;
+    const value = Number(raw);
+    if (!/^\d+$/.test(raw) || value < 1 || value > max) {
+      issues.push({ param: name, message: `must be an integer from 1 to ${max === Number.MAX_SAFE_INTEGER ? "∞" : max}` });
+      return fallback;
+    }
+    return value;
+  };
+
+  const page = positiveInt("page", 1);
+  const perPage = positiveInt("perPage", resource.perPage, MAX_PER_PAGE);
+
+  let sort = resource.defaultSort;
+  const rawSort = params.get("sort");
+  if (rawSort) {
+    const direction = rawSort.startsWith("-") ? "desc" : "asc";
+    const field = rawSort.replace(/^-/, "");
+    const def = fields.get(field);
+    if (TIMESTAMP_FIELDS.includes(field) || (def && isSortable(def))) sort = { field, direction };
+    else issues.push({ param: "sort", message: `can't sort by "${field}"` });
+  }
+
+  const q = params.get("q")?.trim().slice(0, MAX_SEARCH_LENGTH) || undefined;
+
+  const rawCursor = params.get("cursor");
+  let cursor: Cursor | undefined;
+  if (rawCursor) {
+    cursor = decodeCursor(rawCursor);
+    if (!cursor) issues.push({ param: "cursor", message: "isn't a cursor this list handed out" });
+  }
+
+  const filters: ListQuery["filters"] = {};
+  for (const [name, raw] of params) {
+    const match = /^filter\[(.+)\]$/.exec(name);
+    if (!match) continue;
+    const key = match[1]!;
+    const def = fields.get(key);
+    if (!def || !isFilterable(def)) {
+      issues.push({ param: name, message: `can't filter by "${key}"` });
+      continue;
+    }
+    const value = coerce(def, raw);
+    if (value === undefined) issues.push({ param: name, message: `invalid value "${raw}"` });
+    else filters[key] = value;
+  }
+
+  return issues.length ? { issues } : { query: { page, perPage, sort, q, filters, cursor } };
+}