@everystack/admin 0.4.6 → 0.4.8

package/src/utils/date-range.ts

@@ -0,0 +1,146 @@
+import { dayRangeBounds, instantToParts, parseDay, parseInstant } from '@everystack/ui/date-time';
+import { assertIanaTimeZone } from '@everystack/ui/time-zone';
+import type { DateRangeConfig, DateRangePreset } from '../types';
+
+export interface DateRange {
+  from: string;
+  to: string;
+}
+
+export interface DateRangeFilter {
+  gte: string;
+  lt: string;
+}
+
+export type CompiledDateRange =
+  | { kind: 'ok'; filter: DateRangeFilter }
+  | { kind: 'invalid'; reason: string };
+
+/** Inclusive calendar days become an inclusive start and an exclusive end in UTC. */
+export function compileDateRange(range: DateRange, timeZone: string): CompiledDateRange {
+  try {
+    assertIanaTimeZone(timeZone);
+    const bounds = dayRangeBounds(range.from, range.to, timeZone);
+    return { kind: 'ok', filter: { gte: bounds.from, lt: bounds.until } };
+  } catch (error) {
+    if (error instanceof RangeError) return { kind: 'invalid', reason: error.message };
+    throw error;
+  }
+}
+
+/** The adapter ANDs the two conditions on the configured field. */
+export function rangeFilter(field: string, bounds: DateRangeFilter): Record<string, string[]> {
+  return { [field]: [`gte.${bounds.gte}`, `lt.${bounds.lt}`] };
+}
+
+/** The caller supplies today in its display zone; arithmetic stays on calendar days. */
+export function presetRange(
+  preset: DateRangePreset,
+  todayInZone: string,
+  weekStartsOn: NonNullable<DateRangeConfig['weekStartsOn']> = 1,
+): DateRange {
+  const today = parseDay(todayInZone);
+  if (!today) throw new RangeError('Today must be a valid YYYY-MM-DD day.');
+  let from = today;
+  let to = today;
+  switch (preset) {
+    case 'today': break;
+    case 'yesterday': from = to = today.subtract({ days: 1 }); break;
+    case 'last7Days': from = today.subtract({ days: 6 }); break;
+    case 'last30Days': from = today.subtract({ days: 29 }); break;
+    case 'thisWeek':
+      from = today.subtract({ days: (today.dayOfWeek - weekStartsOn + 7) % 7 });
+      break;
+    case 'lastWeek': {
+      const start = today.subtract({ days: (today.dayOfWeek - weekStartsOn + 7) % 7 });
+      from = start.subtract({ days: 7 });
+      to = start.subtract({ days: 1 });
+      break;
+    }
+    case 'thisMonth': from = today.with({ day: 1 }); break;
+    case 'lastMonth':
+      to = today.with({ day: 1 }).subtract({ days: 1 });
+      from = to.with({ day: 1 });
+      break;
+  }
+  return { from: from.toString(), to: to.toString() };
+}
+
+export type OwnedRange =
+  | { kind: 'absent' }
+  | ({ kind: 'pair' } & DateRangeFilter)
+  | { kind: 'invalid'; reason: string };
+
+export type DateRangeConditions =
+  | { kind: 'ok'; values: string[] }
+  | { kind: 'invalid'; reason: string };
+
+const STRICT_INSTANT = /^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$/;
+
+function isStrictInstant(value: string): boolean {
+  // A year-0000 instant is refused because PostgreSQL has no year 0.
+  if (!STRICT_INSTANT.test(value) || value.startsWith('0000-')) return false;
+  const instant = new Date(value);
+  return Number.isFinite(instant.getTime()) && instant.toISOString() === value;
+}
+
+/** Validate all conditions on the owned field without a display zone or a clock. */
+export function parseOwnedRange(values: readonly string[]): OwnedRange {
+  if (values.length === 0) return { kind: 'absent' };
+  const invalidPair: OwnedRange = {
+    kind: 'invalid', reason: 'A date range requires exactly one gte condition and one lt condition.',
+  };
+  if (values.length !== 2) return invalidPair;
+  let gte: string | undefined;
+  let lt: string | undefined;
+  for (const value of values) {
+    if (typeof value !== 'string') return invalidPair;
+    if (value.startsWith('gte.') && gte === undefined) gte = value.slice(4);
+    else if (value.startsWith('lt.') && lt === undefined) lt = value.slice(3);
+    else return invalidPair;
+  }
+  if (gte === undefined || lt === undefined) return invalidPair;
+  if (!isStrictInstant(gte) || !isStrictInstant(lt)) {
+    return { kind: 'invalid', reason: 'Date range bounds must be valid UTC instants in YYYY-MM-DDTHH:mm:ss.sssZ format.' };
+  }
+  if (gte >= lt) return { kind: 'invalid', reason: 'The gte bound must be before the lt bound.' };
+  return { kind: 'pair', gte, lt };
+}
+
+function instantDay(value: string, timeZone: string): string | null {
+  const parts = instantToParts(value, timeZone);
+  if (!parts) return null;
+  return `${String(parts.year).padStart(4, '0')}-${String(parts.month + 1).padStart(2, '0')}-${String(parts.day).padStart(2, '0')}`;
+}
+
+/** Only exact calendar-day intervals project to days; invalid zones return null. */
+export function instantsToDays(pair: DateRangeFilter, timeZone: string): DateRange | null {
+  try {
+    assertIanaTimeZone(timeZone);
+    const end = parseInstant(pair.lt)?.epochMilliseconds;
+    if (end === undefined) return null;
+    const from = instantDay(pair.gte, timeZone);
+    // The exclusive end can follow a skipped day. Inspect the last included instant.
+    const to = instantDay(new Date(end - 1).toISOString(), timeZone);
+    if (!from || !to || from > to) return null;
+    const range = { from, to };
+    const compiled = compileDateRange(range, timeZone);
+    if (compiled.kind !== 'ok' || compiled.filter.gte !== pair.gte || compiled.filter.lt !== pair.lt) return null;
+    return range;
+  } catch (error) {
+    if (error instanceof RangeError) return null;
+    throw error;
+  }
+}
+
+/** Values for the field's repeated URL keys, using the existing calendar-day compiler. */
+export function daysToConditions(field: string, range: DateRange, timeZone: string): DateRangeConditions {
+  const compiled = compileDateRange(range, timeZone);
+  if (compiled.kind !== 'ok') return compiled;
+  // At the calendar extremes the compiler can emit year 0000 or +010000; the URL format cannot
+  // carry those, so refuse here instead of writing a URL that parseOwnedRange would reject.
+  if (!isStrictInstant(compiled.filter.gte) || !isStrictInstant(compiled.filter.lt)) {
+    return { kind: 'invalid', reason: 'That date range is outside the supported years 0001 to 9999.' };
+  }
+  return { kind: 'ok', values: rangeFilter(field, compiled.filter)[field] };
+}

package/src/utils/datetime-submission.ts

@@ -0,0 +1,25 @@
+import { parseInstant } from '@everystack/ui/date-time';
+import type { FieldDefinition } from '../types';
+import { toDateInputValue } from './format-cell-value';
+
+/** Normalize only values the form will send. Untouched edit fields never enter this body. */
+export function normalizeDateTimeSubmission(
+  fields: readonly FieldDefinition[],
+  values: Record<string, unknown>,
+): Record<string, unknown> {
+  const body = { ...values };
+  for (const field of fields) {
+    if (field.type !== 'datetime' || field.storage === 'wall' || !(field.name in body)) continue;
+    const value = body[field.name];
+    if (value == null || value === '') {
+      body[field.name] = null;
+      continue;
+    }
+    const raw = toDateInputValue(value);
+    const instant = parseInstant(raw);
+    if (!instant) throw new RangeError(`${field.label ?? field.name} is not a valid date and time.`);
+    // A picker already emits Z. Keep its precision; Temporal retains nanoseconds for other inputs.
+    body[field.name] = raw.endsWith('Z') ? raw.replace(' ', 'T') : instant.toString();
+  }
+  return body;
+}

package/src/utils/field-sortable.ts

@@ -0,0 +1,19 @@
+import type { FieldDefinition } from '../types';
+
+/** Whether this field can send a list order to the adapter. */
+export function isFieldSortable(field: FieldDefinition): boolean {
+  if (field.virtual === true) return false;
+  if (field.sortable === false) return false;
+  if (field.sortable === true) return true;
+  if (field.format === 'html' || field.format === 'markdown') return false;
+  switch (field.type) {
+    case 'json':
+    case 'tags':
+    case 'file':
+    case 'image':
+    case 'relation':
+      return false;
+    default:
+      return true;
+  }
+}

package/src/utils/format-cell-value.ts

@@ -6,6 +6,7 @@
  * through untouched — never hide data behind "Invalid Date".
  */
 
+import { parseInstant } from '@everystack/ui/date-time';
 import type { FieldDefinition } from '../types';
 import { tagLabel, tagValues } from './tags';
 import { formatWallClock, isWallClock } from './wall-clock';
@@ -51,23 +52,35 @@ export function toDateInputValue(value: unknown): string {
   return value == null ? '' : String(value);
 }
 
-/**
- * A datetime for display, on the list and the show page alike. A wall-clock field shows its
- * stored digits and its zone, whatever the viewer's zone; any other datetime is an instant shown
- * in the viewer's local time.
- */
-export function formatDateTime(field: FieldDefinition, value: unknown): string {
+/** A wall field retains literal digits; instants require an explicitly resolved display zone. */
+export function formatDateTime(field: FieldDefinition, value: unknown, timeZone?: string): string {
   if (isWallClock(field)) return formatWallClock(field, value);
-  const date = new Date(String(value));
-  return Number.isNaN(date.getTime()) ? String(value) : date.toLocaleString();
+  const instant = parseInstant(value instanceof Date && !Number.isNaN(value.getTime()) ? value.toISOString() : value);
+  if (!instant) return String(value);
+  if (!timeZone) return 'Resolving time zone…';
+  const display = new Intl.DateTimeFormat('en-US', {
+    timeZone, year: 'numeric', month: 'short', day: 'numeric',
+    hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23', timeZoneName: 'short',
+  }).format(new Date(instant.epochMilliseconds));
+  // The short name (PDT, GMT+9) sits beside the stamp; the zone's full name is not repeated in every cell.
+  return display;
+}
+
+/** Exact stored wall carrier or canonical UTC instant, including sub-millisecond precision. */
+export function dateTimeRawValue(field: FieldDefinition, value: unknown): string | null {
+  if (value == null) return null;
+  const raw = value instanceof Date && !Number.isNaN(value.getTime()) ? value.toISOString() : String(value);
+  if (isWallClock(field)) return `Stored digits: ${raw}`;
+  const instant = parseInstant(raw);
+  return instant ? `UTC: ${instant.toString()}` : `Raw value: ${raw}`;
 }
 
-export function formatCellValue(field: FieldDefinition, value: unknown): string {
+export function formatCellValue(field: FieldDefinition, value: unknown, timeZone?: string): string {
   if (value === null || value === undefined) return '—';
 
   switch (field.type) {
     case 'datetime':
-      return formatDateTime(field, value);
+      return formatDateTime(field, value, timeZone);
     case 'date':
       return formatDateOnly(value);
     case 'boolean':

package/src/utils/list-query.ts

@@ -125,15 +125,15 @@ export function mergeFilters(
   a?: Record<string, unknown>,
   b?: Record<string, unknown>,
 ): Record<string, unknown> | undefined {
-  const merged: Record<string, unknown> = {};
+  const merged = new Map<string, unknown>();
   for (const source of [a, b]) {
     if (!source) continue;
     for (const [key, value] of Object.entries(source)) {
       if (value == null) continue;
-      merged[key] = key in merged ? [...toArray(merged[key]), ...toArray(value)] : value;
+      merged.set(key, merged.has(key) ? [...toArray(merged.get(key)), ...toArray(value)] : value);
     }
   }
-  return Object.keys(merged).length ? merged : undefined;
+  return merged.size ? Object.fromEntries(merged) : undefined;
 }
 
 const toArray = (value: unknown): unknown[] => (Array.isArray(value) ? value : [value]);

package/src/utils/resource-query.ts

@@ -0,0 +1,318 @@
+/**
+ * `ResourceConfig.table` and `ResourceConfig.where`: which table a resource reads and writes, and
+ * which slice of it. Two resources may share a table, each with its own `where` (single-table
+ * inheritance). withResourceQuery() applies both once, on the adapter the providers hand to every
+ * screen; everything above the adapter (URL, nav, relations, scopes) keeps the resource name.
+ *
+ * `where` is a view filter and a forced default. It is not authorization. Any client with the same
+ * token can address any row through the API. For a boundary, use a role and an RLS policy (or a
+ * view).
+ *
+ * The name is SQL's: the option is an equality WHERE on the resource's table. Rails' `where(type:
+ * 'Adventure').new` presets the same attribute on a new record, and so does this on a create.
+ *
+ * It keeps staff from mistakes (a wrong type typed into a form, an id typed into the wrong URL):
+ * every adapter call for a resource with `where` is narrowed to its slice, and every write carries
+ * the `where` values.
+ */
+
+import type { DataAdapter, SubscriptionEvent } from '../adapters/types';
+import type {
+  AdminConfig,
+  AggregateParams,
+  AggregateResult,
+  DataRecord,
+  FieldDefinition,
+  ListParams,
+  ListResult,
+  ResourceConfig,
+  WhereValues,
+} from '../types';
+
+type Filter = Record<string, unknown>;
+
+/**
+ * The caller's filter with `where` ANDed in: each `where` key is replaced by an exact match and
+ * moved last, so `where` wins over a user or tab filter on the same key. `eq.` comes first, so the
+ * rest of the value is matched literally, operator-like text, dots, commas and parentheses included.
+ */
+export function whereFilter(filter: Filter | undefined, where: WhereValues): Filter {
+  const out: Filter = { ...filter };
+  for (const [key, value] of Object.entries(where)) {
+    delete out[key];
+    out[key] = `eq.${String(value)}`;
+  }
+  return out;
+}
+
+/**
+ * `params` carrying the resource name, for a resource whose `table` is not its name. The name is
+ * set last, so a caller cannot override it. For any other resource `params` is returned as is, so
+ * an adapter sees no new key.
+ */
+function named<P extends object>(resource: string, q: ResourceQuery, params: P): P {
+  return q.table === resource ? params : { ...params, resource };
+}
+
+/** What the wrapper does for one resource: the table it names, its `where`, if any, and its id column. */
+interface ResourceQuery {
+  table: string;
+  where?: WhereValues;
+  primaryKey: string;
+}
+
+/**
+ * Keyed by RESOURCE name, never by table: two resources on one table keep their own `where`, and a
+ * resource with no entry here passes through as is, even when its name is another resource's table.
+ */
+function queriesOf(config: AdminConfig): Map<string, ResourceQuery> {
+  const queries = new Map<string, ResourceQuery>();
+  for (const resource of config.resources ?? []) {
+    const table = resource.table ?? resource.name;
+    const where = resource.where && Object.keys(resource.where).length > 0 ? resource.where : undefined;
+    if (table !== resource.name || where) queries.set(resource.name, { table, where, primaryKey: resource.primaryKey ?? 'id' });
+  }
+  return queries;
+}
+
+/**
+ * A stable text form of everything withResourceQuery() reads from the config. Two configs with the
+ * same signature give wrappers that behave the same, so a caller can reuse one wrapper for both.
+ */
+export function resourceQuerySignature(config: AdminConfig): string {
+  return JSON.stringify([...queriesOf(config)].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}
+
+const NUMERIC_TEXT = /^-?(\d+\.?\d*|\.\d+)([eE][-+]?\d+)?$/;
+
+/**
+ * True when a returned value matches the `where` value the way the API returns it. A number
+ * compares numerically, so numeric(n,2) text "2.00" matches 2. A boolean accepts true or "true" or
+ * "t" (false or "false" or "f"). Anything else is exact text: case-sensitive, no trimming.
+ */
+function sameAsWhere(value: unknown, expected: WhereValues[string]): boolean {
+  if (typeof expected === 'number') {
+    if (typeof value === 'number') return value === expected;
+    if (typeof value === 'string' && NUMERIC_TEXT.test(value)) return Number(value) === expected;
+  }
+  if (typeof expected === 'boolean') {
+    return expected ? value === true || value === 'true' || value === 't' : value === false || value === 'false' || value === 'f';
+  }
+  return String(value) === String(expected);
+}
+
+/** `{ type: "Adventure", tier: 2 }`, for an error message. */
+function describeWhere(where: WhereValues): string {
+  return `{ ${Object.entries(where).map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(', ')} }`;
+}
+
+/**
+ * A write body that names a DIFFERENT value for a `where` column is not silently taken as if it
+ * applied: the `where` value is written (the body's is ignored) and, outside production, one warning
+ * names every column that disagreed. The admin's own forms never send these columns, so this fires
+ * for an adapter or custom code that passes the full record back.
+ */
+function warnOverridden(resource: string, data: unknown, where: WhereValues): void {
+  if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') return;
+  if (data === null || typeof data !== 'object') return;
+  const body = data as Record<string, unknown>;
+  const clashes = Object.entries(where).filter(([key, expected]) =>
+    Object.prototype.hasOwnProperty.call(body, key) && body[key] !== undefined && !sameAsWhere(body[key], expected));
+  if (clashes.length === 0) return;
+  const named = clashes.map(([key, expected]) => `${key}: the body has ${JSON.stringify(body[key])}, where forces ${JSON.stringify(expected)}`).join('; ');
+  // eslint-disable-next-line no-console
+  console.warn(`Resource "${resource}": the write names a value that disagrees with its where, so the where value was written and the body's was ignored (${named}).`);
+}
+
+/**
+ * Throws when a row the adapter returned is outside the resource's `where`. Only keys present in
+ * the row are compared: a hidden column or a narrow select leaves a key out, and that is no error.
+ * The row is returned as is. `saved` says the write already happened.
+ */
+function checkRow<T>(resource: string, q: ResourceQuery, where: WhereValues, row: T, saved: boolean): T {
+  if (row === null || typeof row !== 'object') return row;
+  const record = row as Record<string, unknown>;
+  for (const [key, expected] of Object.entries(where)) {
+    if (!Object.prototype.hasOwnProperty.call(record, key) || record[key] === undefined) continue;
+    if (sameAsWhere(record[key], expected)) continue;
+    const id = record[q.primaryKey];
+    const which = id === undefined || id === null ? '' : ` (id ${String(id)})`;
+    const rest = `${key} ${JSON.stringify(record[key])}, outside its where ${describeWhere(where)}.`;
+    throw new Error(saved
+      ? `Resource "${resource}": the row was saved${which} but has ${rest}`
+      : `Resource "${resource}": the row${which} has ${rest}`);
+  }
+  return row;
+}
+
+/**
+ * The adapter, with every call for a resource that sets `table` or `where` rewritten on the way in.
+ * The resource name becomes its table for fetchList, aggregate, fetchOne, create, update, delete and
+ * subscribe. When that table is not the name, the call also carries the resource name as
+ * `params.resource` (a third argument on create), so an adapter that serves two resources on one
+ * table can tell them apart. subscribe does not carry it: its events are delivered under the
+ * resource name already. `where` narrows the call to its slice: lists, counts and aggregates get it as a filter;
+ * fetchOne, update and delete get it as `params.filter` beside the id, in the one request they send;
+ * create and update bodies get the `where` values over the form's. The row that create, update or
+ * fetchOne returns is checked against `where`, and one outside it throws, naming it. subscribe
+ * drops events whose record is outside `where` and delivers the rest under the resource name.
+ * Everything else (rpc,
+ * supportsSearch, an adapter's own members) passes through, called on the adapter itself. With no
+ * `table` or `where` anywhere, the adapter is returned as is.
+ */
+export function withResourceQuery(adapter: DataAdapter, config: AdminConfig): DataAdapter {
+  const queries = queriesOf(config);
+  if (queries.size === 0) return adapter;
+
+  type FetchOneParams = Parameters<DataAdapter['fetchOne']>[2];
+  type UpdateParams = Parameters<DataAdapter['update']>[3];
+  type DeleteParams = Parameters<DataAdapter['delete']>[2];
+
+  const overrides: Partial<DataAdapter> = {
+    fetchList<T extends DataRecord = DataRecord>(resource: string, params: ListParams): Promise<ListResult<T>> {
+      const q = queries.get(resource);
+      if (!q) return adapter.fetchList<T>(resource, params);
+      return adapter.fetchList<T>(q.table, named(resource, q, q.where ? { ...params, filter: whereFilter(params.filter, q.where) } : params));
+    },
+    aggregate(resource: string, params: AggregateParams): Promise<AggregateResult> {
+      const q = queries.get(resource);
+      if (!q) return adapter.aggregate!(resource, params);
+      return adapter.aggregate!(q.table, named(resource, q, q.where ? { ...params, filter: whereFilter(params.filter, q.where) } : params));
+    },
+    fetchOne<T extends DataRecord = DataRecord>(resource: string, id: string | number, ...rest: [params?: FetchOneParams]): Promise<T> {
+      const q = queries.get(resource);
+      if (!q) return adapter.fetchOne<T>(resource, id, ...rest);
+      const [params] = rest;
+      // No where means the table differs from the name (queriesOf), so the name is always sent.
+      if (!q.where) return adapter.fetchOne<T>(q.table, id, named(resource, q, { ...params }));
+      const where = q.where;
+      return adapter
+        .fetchOne<T>(q.table, id, named(resource, q, { ...params, filter: whereFilter(params?.filter, where) }))
+        .then(row => checkRow(resource, q, where, row, false));
+    },
+    create<T extends DataRecord = DataRecord>(resource: string, data: Omit<T, 'id'>): Promise<T> {
+      const q = queries.get(resource);
+      if (!q) return adapter.create<T>(resource, data);
+      // A third argument only when the table is not the name: every other create keeps its two.
+      const rest: [params?: { resource?: string }] = q.table === resource ? [] : [{ resource }];
+      if (!q.where) return adapter.create<T>(q.table, data, ...rest);
+      const where = q.where;
+      warnOverridden(resource, data, where);
+      return adapter.create<T>(q.table, { ...data, ...where }, ...rest).then(row => checkRow(resource, q, where, row, true));
+    },
+    update<T extends DataRecord = DataRecord>(
+      resource: string,
+      id: string | number,
+      data: Partial<T>,
+      ...rest: [params?: UpdateParams]
+    ): Promise<T> {
+      const q = queries.get(resource);
+      if (!q) return adapter.update<T>(resource, id, data, ...rest);
+      const [params] = rest;
+      if (!q.where) return adapter.update<T>(q.table, id, data, named(resource, q, { ...params }));
+      const where = q.where;
+      warnOverridden(resource, data, where);
+      return adapter
+        .update<T>(q.table, id, { ...data, ...where } as Partial<T>, named(resource, q, { ...params, filter: whereFilter(params?.filter, where) }))
+        .then(row => checkRow(resource, q, where, row, true));
+    },
+    delete(resource: string, id: string | number, ...rest: [params?: DeleteParams]): Promise<void> {
+      const q = queries.get(resource);
+      if (!q) return adapter.delete(resource, id, ...rest);
+      const [params] = rest;
+      if (!q.where) return adapter.delete(q.table, id, named(resource, q, { ...params }));
+      return adapter.delete(q.table, id, named(resource, q, { ...params, filter: whereFilter(params?.filter, q.where) }));
+    },
+    subscribe<T extends DataRecord = DataRecord>(resource: string, callback: (event: SubscriptionEvent<T>) => void): () => void {
+      const q = queries.get(resource);
+      if (!q) return adapter.subscribe!<T>(resource, callback);
+      const where = q.where;
+      return adapter.subscribe!<T>(q.table, event => {
+        // An update that moves a row out of the slice still reaches the list, by its previousRecord.
+        if (where && !inSlice(event.record, where) && !(isObject(event.previousRecord) && inSlice(event.previousRecord, where))) return;
+        callback({ ...event, resource });
+      });
+    },
+  };
+
+  // One bound function per original, so a member read twice is the same function (stable deps).
+  const bound = new WeakMap<object, unknown>();
+  return new Proxy(adapter, {
+    get(target, prop) {
+      const value: unknown = Reflect.get(target, prop, target);
+      if (typeof value !== 'function') return value;
+      if (Object.prototype.hasOwnProperty.call(overrides, prop)) return overrides[prop as keyof DataAdapter];
+      let fn = bound.get(value);
+      if (!fn) {
+        fn = (value as (...args: unknown[]) => unknown).bind(target);
+        bound.set(value, fn);
+      }
+      return fn;
+    },
+  });
+}
+
+/**
+ * False only when the record has a `where` key with another value. No record, or a record without
+ * the key, passes: the slice cannot be told, and dropping it would hide a change.
+ */
+function inSlice(record: unknown, where: WhereValues): boolean {
+  if (!isObject(record)) return true;
+  const row = record as Record<string, unknown>;
+  return Object.entries(where).every(([key, expected]) =>
+    !Object.prototype.hasOwnProperty.call(row, key) || row[key] === undefined || sameAsWhere(row[key], expected));
+}
+
+function isObject(value: unknown): value is object {
+  return value !== null && typeof value === 'object';
+}
+
+/** The form's fields without the `where` columns: Create and Edit render no input for them. */
+export function withoutWhere(fields: FieldDefinition[], resource: ResourceConfig): FieldDefinition[] {
+  const where = resource.where;
+  return where ? fields.filter(f => !Object.prototype.hasOwnProperty.call(where, f.name)) : fields;
+}
+
+/** Checks every resource's `table` at setup, loudly: absent, or a non-empty string. Two resources may share one. */
+export function validateTable(config: AdminConfig): void {
+  for (const resource of config.resources ?? []) {
+    const table: unknown = resource.table;
+    if (table === undefined) continue;
+    if (typeof table !== 'string' || table.trim() === '') {
+      throw new TypeError(`Admin resource "${resource.name}", table: must be a non-empty string, got ${JSON.stringify(table)}`);
+    }
+  }
+}
+
+/**
+ * Checks every resource's `where` at setup, loudly: an object whose keys each name a field of the
+ * resource and whose values are a string, a finite number or a boolean. Config can arrive untyped.
+ */
+export function validateWhere(config: AdminConfig): void {
+  for (const resource of config.resources ?? []) {
+    const where: unknown = resource.where;
+    if (where === undefined) continue;
+    const at = `Admin resource "${resource.name}", where`;
+    if (where === null || typeof where !== 'object' || Array.isArray(where)) {
+      throw new TypeError(`${at}: must be an object of column → value, got ${JSON.stringify(where)}`);
+    }
+    const names = new Set((resource.fields ?? []).map(f => f.name));
+    for (const [key, value] of Object.entries(where)) {
+      if (!names.has(key)) {
+        throw new TypeError(`${at} "${key}": the resource has no field "${key}" (spell it like the field name)`);
+      }
+      // Both of these would look fine and do nothing: `where` overwrites the pick, and the tab shows the same slice.
+      if ((resource.fields ?? []).some(f => f.name === key && f.inlineEdit)) {
+        throw new TypeError(`${at} "${key}": the column is in where, so inlineEdit on it would be overwritten by where. Remove inlineEdit.`);
+      }
+      const scope = (resource.scopes ?? []).find(s => s.filter && Object.prototype.hasOwnProperty.call(s.filter, key));
+      if (scope) {
+        throw new TypeError(`${at} "${key}": scope "${scope.id}" filters the where column, so where overrides it. Remove that filter or the where entry.`);
+      }
+      const ok = typeof value === 'string' || typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value));
+      if (!ok) {
+        throw new TypeError(`${at} "${key}": the value must be a string, a finite number or a boolean, got ${typeof value === 'number' || value === undefined ? String(value) : JSON.stringify(value)}`);
+      }
+    }
+  }
+}

package/src/utils/validate-config.ts

@@ -0,0 +1,85 @@
+/**
+ * Setup is where a bad config fails: loudly, naming the resource and the field or key, not later on
+ * a screen that happens to read it. AdminConfigProvider runs this once per config.
+ */
+
+import { assertIanaTimeZone } from '@everystack/ui/time-zone';
+import type { AdminConfig } from '../types';
+import { validateTable, validateWhere } from './resource-query';
+import { validateWallClockFields } from './wall-clock';
+import { RESERVED_PARAMS } from './view-filters';
+import { isDashboardDimension } from './date-filter-fields';
+
+export function validateAdminConfig(config: AdminConfig): void {
+  validateResourceNames(config);
+  validateWallClockFields(config);
+  validateDateConfig(config);
+  validateTable(config);
+  validateWhere(config);
+  validateAssociations(config);
+}
+
+/**
+ * An association names its related rows by exactly one of `resource` (read through that resource's
+ * `table` and `where`) or `table` (the real table, as is). Both, or neither, would count the wrong rows.
+ */
+function validateAssociations(config: AdminConfig): void {
+  for (const resource of config.resources ?? []) {
+    for (const association of resource.associations ?? []) {
+      const at = `Admin resource "${resource.name}", association "${association.label}"`;
+      const named = (['resource', 'table'] as const).filter(key => association[key] !== undefined);
+      if (named.length !== 1) {
+        throw new TypeError(`${at}: set exactly one of resource or table, got ${named.length === 0 ? 'neither' : 'both'}`);
+      }
+      const value: unknown = association[named[0]];
+      if (typeof value !== 'string' || value.trim() === '') {
+        throw new TypeError(`${at}: ${named[0]} must be a non-empty string, got ${JSON.stringify(value)}`);
+      }
+    }
+  }
+}
+
+/** The resource name keys the URL, nav, relations, scopes and `where`, so it must be unique. A table may be shared. */
+function validateResourceNames(config: AdminConfig): void {
+  const seen = new Set<string>();
+  for (const resource of config.resources ?? []) {
+    if (seen.has(resource.name)) {
+      throw new TypeError(
+        `Admin resource "${resource.name}": the name is used by more than one resource. Give each its own name; two resources may share a table.`,
+      );
+    }
+    seen.add(resource.name);
+  }
+}
+
+/** Instant display zones and future list ranges fail at setup, including untyped config. */
+function validateDateConfig(config: AdminConfig): void {
+  if (config.timeZone !== undefined) {
+    try {
+      assertIanaTimeZone(config.timeZone);
+    } catch (error) {
+      throw new RangeError(`Admin timeZone: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  for (const resource of config.resources ?? []) {
+    const range = resource.dateRange;
+    if (range === undefined) continue;
+    const at = `Admin resource "${resource.name}", dateRange`;
+    if (range === null || typeof range !== 'object' || typeof range.field !== 'string' || range.field.trim() === '') {
+      throw new TypeError(`${at}: field must name a declared instant datetime field`);
+    }
+    if (RESERVED_PARAMS.has(range.field)) {
+      throw new TypeError(`${at} field "${range.field}": the URL reserves this name for list view state, so it cannot carry a range`);
+    }
+    const field = resource.fields?.find(candidate => candidate.name === range.field);
+    if (!field || field.type !== 'datetime' || field.virtual || field.storage === 'wall') {
+      throw new TypeError(`${at} field "${range.field}": must name a non-virtual instant datetime field (storage omitted or 'utc')`);
+    }
+    if (isDashboardDimension(resource, range.field)) {
+      throw new TypeError(`${at} field "${range.field}": a dashboard dimension owns its URL values and cannot also have a date range row`);
+    }
+    if (range.weekStartsOn !== undefined && (!Number.isInteger(range.weekStartsOn) || range.weekStartsOn < 0 || range.weekStartsOn > 6)) {
+      throw new TypeError(`${at}: weekStartsOn must be an integer from 0 to 6`);
+    }
+  }
+}