@everystack/api 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.7] - 2026-10-18
+
+### BREAKING CHANGES
+
+- date filters no longer throw; refuse impossible calendar dates; map 22007 and 22008 to 422
+- list fields sort by default; the API refuses an order it cannot apply (#92)
+- datetimes show in the viewer's zone and edit round-trip in it (#94)
+
+### Added
+
+- HandlerError carries a machine-readable code and column on RPC answers
+
+### Fixed
+
+- hiddenColumns accepts the camelCase of a column's SQL name; an ambiguous alias refuses at init
+
+### Changed
+
+- move HandlerError to its own import-free module, @everystack/api/errors
+
 ## [0.4.6] - 2026-10-16
 
 ### BREAKING CHANGES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -27,6 +27,11 @@
       "types": "./src/handler/index.ts",
       "default": "./src/handler/index.ts"
     },
+    "./errors": {
+      "source": "./src/handler/errors.ts",
+      "types": "./src/handler/errors.ts",
+      "default": "./src/handler/errors.ts"
+    },
     "./client": {
       "source": "./src/client/index.ts",
       "types": "./src/client/index.ts",

package/src/handler/errors.ts

@@ -0,0 +1,39 @@
+/**
+ * HandlerError lives in its own module with no imports, so code that only needs to throw one
+ * (the admin's RPC factory) does not pull the whole server handler into its bundle.
+ */
+
+/** An application error code: lower-case words, never a Postgres SQLSTATE or a system errno. */
+const APP_ERROR_CODE = /^[a-z][a-z0-9_]{0,63}$/;
+const isAppErrorCode = (value: unknown): value is string => typeof value === 'string' && APP_ERROR_CODE.test(value);
+const isAppErrorColumn = (value: unknown): value is string =>
+  typeof value === 'string' && value.length >= 1 && value.length <= 128 && !/[\u0000-\u001f\u007f-\u009f]/.test(value);
+
+const appErrorMetadata = new WeakMap<object, { readonly code?: string; readonly column?: string }>();
+const EMPTY_METADATA: { readonly code?: string; readonly column?: string } = Object.freeze(Object.create(null));
+
+/** Throw from hooks or RPCs to return a custom status and message; RPCs also expose optional metadata. */
+export class HandlerError extends Error {
+  status: number;
+  constructor(status: number, message: string, options?: { code?: string; column?: string }) {
+    super(message);
+    const code = options?.code;
+    const column = options?.column;
+    if (code !== undefined && !isAppErrorCode(code)) {
+      throw new TypeError('HandlerError code must match /^[a-z][a-z0-9_]{0,63}$/');
+    }
+    if (column !== undefined && !isAppErrorColumn(column)) {
+      throw new TypeError('HandlerError column must be 1 to 128 characters with no control characters');
+    }
+    this.status = status;
+    this.name = 'HandlerError';
+    // Held outside the instance: only what the author passed here is ever sent, and no property
+    // or getter on the error can change it afterwards.
+    appErrorMetadata.set(this, Object.freeze({ code, column }));
+  }
+
+  /** The `code` and `column` given to the constructor. Anything assigned to the error later is not here. */
+  static metadataOf(error: HandlerError): { code?: string; column?: string } {
+    return appErrorMetadata.get(error) ?? EMPTY_METADATA;
+  }
+}

package/src/handler/index.ts

@@ -7,7 +7,8 @@
  *   // Mount as Expo Router API route or any Web Standard handler
  */
 
-import { eq, ne, gt, gte, lt, lte, like, ilike, isNull, isNotNull, inArray, arrayContains, arrayContained, arrayOverlaps, and, or, not, asc, desc, sql, getTableColumns, Param, type SQL } from 'drizzle-orm';
+import { eq, ne, gt, gte, lt, lte, like, ilike, isNull, isNotNull, inArray, arrayContains, arrayContained, arrayOverlaps, and, or, not, asc, desc, sql, getTableColumns, is, Param, type SQL } from 'drizzle-orm';
+import { getTableConfig, PgTable } from 'drizzle-orm/pg-core';
 import { parseArrayLiteral, ARRAY_LITERAL_MAX_ELEMENTS, ARRAY_LITERAL_MAX_ELEMENT_LENGTH } from './array-literal';
 import { emitAudit, resolvePrincipal, type AuditConfig, type RequestContext } from './audit';
 import { isServiceUnavailable, SERVICE_UNAVAILABLE_MESSAGE } from './service-unavailable';
@@ -25,15 +26,8 @@ type Schema = Record<string, DrizzleTable>;
 
 type Handler = (request: Request) => Promise<Response>;
 
-/** Throw from hooks to return a custom status code and message to the client. */
-export class HandlerError extends Error {
-  status: number;
-  constructor(status: number, message: string) {
-    super(message);
-    this.status = status;
-    this.name = 'HandlerError';
-  }
-}
+export { HandlerError } from './errors';
+import { HandlerError } from './errors';
 
 /**
  * A 5xx system fault surfaced to the observability sink. Distinct from a 4xx
@@ -177,13 +171,18 @@ function describeError(error: unknown): Pick<HandlerFault, 'message' | 'stack' |
 }
 
 /** Replace schema-revealing error details with a generic message when hideSchemaErrors is enabled. */
-function sanitizeError(message: string, status: number, options?: HandlerOptions): Response {
+function sanitizeError(
+  message: string,
+  status: number,
+  options?: HandlerOptions,
+  extra?: { code: string; column: string },
+): Response {
   if (options?.hideSchemaErrors) {
     if (status === 404) return json({ message: 'Not found' }, 404);
     if (status === 403) return json({ message: 'Forbidden' }, 403);
-    if (status === 400) return json({ message: 'Bad request' }, 400);
+    if (status === 400) return json({ message: 'Bad request', ...extra }, 400);
   }
-  return json({ message }, status);
+  return json({ message, ...extra }, status);
 }
 
 export interface AuthConfig {
@@ -718,6 +717,48 @@ function transformBodyKeys(body: unknown, table: DrizzleTable): unknown {
  */
 const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2}))?$/;
 
+/**
+ * The one date rule, shared by a write body and a query-string filter so the two cannot
+ * drift: the Date for `value`, or the 400 message naming `key`.
+ */
+function parseDateValue(key: string, value: string | number): Date | { error: string } {
+  if (typeof value === 'string' && !ISO_DATE_RE.test(value)) {
+    return { error: `Invalid date value for "${key}": expected ISO 8601, got ${JSON.stringify(value)}` };
+  }
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    return { error: `Invalid date value for "${key}": ${JSON.stringify(value)}` };
+  }
+  if (typeof value === 'string' && !isCalendarDate(value.slice(0, 10))) {
+    return { error: `Invalid date value for "${key}": ${value.slice(0, 10)} is not a calendar date` };
+  }
+  return parsed;
+}
+
+/**
+ * The YYYY-MM-DD digits as written name a real day. `new Date('2026-02-29')` rolls over to
+ * 1 March with no error, which would match or store the wrong day; PostgreSQL refuses it.
+ * Checked on the digits before any offset is applied.
+ */
+function isCalendarDate(ymd: string): boolean {
+  const [year, month, day] = ymd.split('-').map(Number);
+  const probe = new Date(0);
+  probe.setUTCFullYear(year, month - 1, day);
+  return probe.getUTCFullYear() === year && probe.getUTCMonth() === month - 1 && probe.getUTCDate() === day;
+}
+
+/**
+ * A JSON boolean, array or plain object: never a date, and the date encoder throws on it.
+ * A Date or a drizzle SQL/Param a hook set has a class prototype and is not one of these.
+ */
+function isJsonShape(value: unknown): boolean {
+  if (typeof value === 'boolean' || Array.isArray(value)) return true;
+  if (value === null || typeof value !== 'object') return false;
+  // Plain from any realm: a parsed body's Object.prototype need not be this module's.
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || Object.getPrototypeOf(proto) === null;
+}
+
 function coerceDateColumnValues(body: unknown, table: DrizzleTable): unknown {
   if (Array.isArray(body)) return body.map(row => coerceDateColumnValues(row, table));
   if (body === null || typeof body !== 'object') {
@@ -726,16 +767,14 @@ function coerceDateColumnValues(body: unknown, table: DrizzleTable): unknown {
 
   const result: Record<string, unknown> = { ...(body as Record<string, unknown>) };
   for (const [key, value] of Object.entries(result)) {
-    if (typeof value !== 'string' && typeof value !== 'number') continue;
+    if (typeof value !== 'string' && typeof value !== 'number' && !isJsonShape(value)) continue;
     const column = getColumn(table, key);
     if (!column || column.dataType !== 'date') continue;
-    if (typeof value === 'string' && !ISO_DATE_RE.test(value)) {
+    if (isJsonShape(value)) {
       throw new HandlerError(400, `Invalid date value for "${key}": expected ISO 8601, got ${JSON.stringify(value)}`);
     }
-    const parsed = new Date(value);
-    if (Number.isNaN(parsed.getTime())) {
-      throw new HandlerError(400, `Invalid date value for "${key}": ${JSON.stringify(value)}`);
-    }
+    const parsed = parseDateValue(key, value as string | number);
+    if (!(parsed instanceof Date)) throw new HandlerError(400, parsed.error);
     result[key] = parsed;
   }
   return result;
@@ -952,7 +991,16 @@ function resolveHiddenColumns(schema: Schema, options?: HandlerOptions): Handler
     const table = schema[tableName];
     const hidden = byTable.get(table) ?? new Set<string>();
     for (const name of names) {
-      const property = columnPropertyName(table, name);
+      let property = columnPropertyName(table, name);
+      if (property === undefined && table) {
+        const matches = Object.entries(getTableColumns(table))
+          .filter(([, column]) => toCamelCase((column as DrizzleColumn).name) === name);
+        if (matches.length > 1) {
+          const candidates = matches.map(([key]) => JSON.stringify(key)).join(' and ');
+          throw new Error(`[everystack/api] hiddenColumns.${tableName}: "${name}" is ambiguous: it is the camelCase of columns ${candidates}; name one by its property or SQL name`);
+        }
+        property = matches[0]?.[0];
+      }
       if (property === undefined) {
         throw new Error(`[everystack/api] hiddenColumns.${tableName}: "${name}" does not resolve to a column`);
       }
@@ -979,6 +1027,8 @@ const INTEGRITY_ERRORS: Record<string, { status: number; message: string }> = {
   '22P02': { status: 422, message: 'Invalid value format' },
   '22001': { status: 422, message: 'Value is too long' },
   '22003': { status: 422, message: 'Value is out of range' },
+  '22007': { status: 422, message: 'Invalid date or time format' },
+  '22008': { status: 422, message: 'Date or time value is out of range' },
 };
 
 type IntegrityAnswer = { status: number; body: {
@@ -1297,7 +1347,12 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
             });
           }
           if (error instanceof HandlerError) {
-            return json({ message: error.message }, error.status);
+            const { code, column } = HandlerError.metadataOf(error);
+            return json({
+              message: error.message,
+              ...(code !== undefined ? { code } : {}),
+              ...(column !== undefined ? { column } : {}),
+            }, error.status);
           }
           if (unavailable) return serviceUnavailableResponse();
           if (hostile) return json({ message: options?.hideSchemaErrors ? 'Internal Server Error' : 'RPC execution failed' }, 500);
@@ -1720,6 +1775,9 @@ async function handleGet(
     }
 
     const groupColumns = columns || [];
+    const order = orderParam === null ? { expressions: [] } : buildOrderBy(table, orderParam, false, groupColumns);
+    if ('error' in order) return sanitizeError(order.error, 400, options, { code: order.code, column: order.column });
+
     const selectObj = buildAggregateSelect(table, aggregates, groupColumns);
 
     let query: any = db.select(selectObj).from(table);
@@ -1737,10 +1795,7 @@ async function handleGet(
       }
     }
 
-    if (orderParam) {
-      const orderExpr = buildOrderBy(table, orderParam);
-      if (orderExpr) query = query.orderBy(orderExpr);
-    }
+    if (order.expressions.length > 0) query = query.orderBy(...order.expressions);
 
     query = query.limit(limitVal).offset(offsetVal);
 
@@ -1775,8 +1830,12 @@ async function handleGet(
     && (db as any).query?.[tableName];
 
   let rows: unknown[];
+  const isHidden = (column: string): boolean => isHiddenColumn(schema, tableName, column, options);
 
   if (useRelationalQuery) {
+    const order = orderParam === null ? { expressions: [] } : buildOrderBy(table, orderParam, true, undefined, isHidden);
+    if ('error' in order) return sanitizeError(order.error, 400, options, { code: order.code, column: order.column });
+
     // JOIN path — single query via Drizzle relational API (db.query.findMany)
     const queryOptions: Record<string, any> = {
       limit: limitVal,
@@ -1798,14 +1857,14 @@ async function handleGet(
       queryOptions.where = and(...conditions);
     }
 
-    if (orderParam) {
-      const orderExpr = buildOrderBy(table, orderParam);
-      if (orderExpr) queryOptions.orderBy = orderExpr;
-    }
+    if (order.expressions.length > 0) queryOptions.orderBy = order.expressions;
 
     rows = await (db as any).query[tableName].findMany(queryOptions);
   } else {
     // Batch path — standard select + separate relation queries
+    const order = orderParam === null ? { expressions: [] } : buildOrderBy(table, orderParam, true, undefined, isHidden);
+    if ('error' in order) return sanitizeError(order.error, 400, options, { code: order.code, column: order.column });
+
     let query: any = db.select().from(table);
 
     if (conditions.length === 1) {
@@ -1814,12 +1873,7 @@ async function handleGet(
       query = query.where(and(...conditions));
     }
 
-    if (orderParam) {
-      const orderExpr = buildOrderBy(table, orderParam);
-      if (orderExpr) {
-        query = query.orderBy(orderExpr);
-      }
-    }
+    if (order.expressions.length > 0) query = query.orderBy(...order.expressions);
 
     query = query.limit(limitVal).offset(offsetVal);
     rows = await query;
@@ -2042,6 +2096,34 @@ function splitSelectParam(param: string): string[] {
   return parts;
 }
 
+/** Check a reference against the resolved hidden policy, including related tables. */
+function isHiddenColumn(
+  schema: Schema,
+  sourceTable: string,
+  reference: string,
+  options?: HandlerOptions,
+): boolean {
+  if (!options?.hiddenColumns) return false;
+
+  // A resolved SQL name can contain path syntax; match the literal name first.
+  if (ownEntry(options.hiddenColumns, sourceTable)?.includes(reference)) return true;
+
+  let targetName = sourceTable;
+  let columnName = parseJsonPath(reference)?.baseColumn ?? reference;
+  // Prefer a real source column. The relation fallback only rejects hidden
+  // references; the filter and order builders do not support relation paths.
+  if (!getColumn(schema[targetName], columnName)) {
+    const parts = columnName.split('.');
+    while (parts.length > 1) {
+      const relation = ownEntry(ownEntry(options.relations, targetName), parts.shift()!);
+      if (!relation || !schema[relation.table]) return false;
+      targetName = relation.table;
+    }
+    columnName = parts[0];
+  }
+  return (ownEntry(options.hiddenColumns, targetName) ?? []).includes(columnName);
+}
+
 /** Check explicit query references, including each related table's own policy. */
 function requestUsesHiddenColumn(
   schema: Schema,
@@ -2051,22 +2133,7 @@ function requestUsesHiddenColumn(
 ): boolean {
   if (!options?.hiddenColumns) return false;
 
-  const isHidden = (sourceTable: string, reference: string): boolean => {
-    let targetName = sourceTable;
-    let columnName = parseJsonPath(reference)?.baseColumn ?? reference;
-    // Prefer a real source column. The relation fallback only rejects hidden
-    // references; the filter and order builders do not support relation paths.
-    if (!getColumn(schema[targetName], columnName)) {
-      const parts = columnName.split('.');
-      while (parts.length > 1) {
-        const relation = ownEntry(ownEntry(options.relations, targetName), parts.shift()!);
-        if (!relation || !schema[relation.table]) return false;
-        targetName = relation.table;
-      }
-      columnName = parts[0];
-    }
-    return (options.hiddenColumns?.[targetName] ?? []).includes(columnName);
-  };
+  const isHidden = (sourceTable: string, reference: string): boolean => isHiddenColumn(schema, sourceTable, reference, options);
 
   const selectUsesHidden = (sourceTable: string, select: string): boolean => {
     // Walk the raw selection: parseSelectParam collapses `*,secret` to a
@@ -2942,6 +3009,33 @@ function buildArrayCondition(column: DrizzleColumn, filter: Filter): any {
   return filter.negated ? not(condition) : condition;
 }
 
+/** PostgREST format: in.(val1,val2,val3) */
+function parseInList(value: string): string[] {
+  return value.replace(/^\(/, '').replace(/\)$/, '').split(',');
+}
+
+const DATE_FILTER_OPERATORS = new Set(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in']);
+
+/**
+ * A date-mode column's driver encoder calls `value.toISOString()`, so a filter value must
+ * reach drizzle as a Date: a string throws a TypeError out of the handler. Each value goes
+ * through the write path's rule (parseDateValue); `in` yields one Date per member. An
+ * operator with no date meaning (like, ilike) is refused, never handed a Date.
+ */
+function dateFilterOperand(filter: Filter): Date | Date[] | { __filterError: string } {
+  if (!DATE_FILTER_OPERATORS.has(filter.operator)) {
+    return { __filterError: `Operator '${filter.operator}' is not supported on date column "${filter.column}"` };
+  }
+  const raw = filter.operator === 'in' ? parseInList(filter.value) : [filter.value];
+  const dates: Date[] = [];
+  for (const member of raw) {
+    const parsed = parseDateValue(filter.column, member);
+    if (!(parsed instanceof Date)) return { __filterError: parsed.error };
+    dates.push(parsed);
+  }
+  return filter.operator === 'in' ? dates : dates[0];
+}
+
 function buildCondition(table: DrizzleTable, filter: Filter): any {
   if (filter.jsonPath) {
     return buildJsonCondition(table, filter);
@@ -2955,26 +3049,35 @@ function buildCondition(table: DrizzleTable, filter: Filter): any {
   }
   if (ARRAY_OPERATORS.has(filter.operator)) return buildArrayCondition(column, filter);
 
+  let value: unknown = filter.value;
+  let values: unknown[] | null = null;
+  if (column.dataType === 'date' && filter.operator !== 'is') {
+    const dated = dateFilterOperand(filter);
+    if (isFilterError(dated)) return dated;
+    if (Array.isArray(dated)) values = dated;
+    else value = dated;
+  }
+
   let condition: any = null;
 
   switch (filter.operator) {
     case 'eq':
-      condition = eq(column, filter.value);
+      condition = eq(column, value);
       break;
     case 'neq':
-      condition = ne(column, filter.value);
+      condition = ne(column, value);
       break;
     case 'gt':
-      condition = gt(column, filter.value);
+      condition = gt(column, value);
       break;
     case 'gte':
-      condition = gte(column, filter.value);
+      condition = gte(column, value);
       break;
     case 'lt':
-      condition = lt(column, filter.value);
+      condition = lt(column, value);
       break;
     case 'lte':
-      condition = lte(column, filter.value);
+      condition = lte(column, value);
       break;
     case 'like':
       // PostgREST uses * for wildcard, SQL uses %
@@ -2987,12 +3090,9 @@ function buildCondition(table: DrizzleTable, filter: Filter): any {
       if (filter.value === 'null') condition = isNull(column);
       else if (filter.value === 'not.null') condition = isNotNull(column);
       break;
-    case 'in': {
-      // PostgREST format: in.(val1,val2,val3)
-      const values = filter.value.replace(/^\(/, '').replace(/\)$/, '').split(',');
-      condition = inArray(column, values);
+    case 'in':
+      condition = inArray(column, values ?? parseInList(filter.value));
       break;
-    }
     default:
       return null;
   }
@@ -3009,18 +3109,51 @@ function buildCondition(table: DrizzleTable, filter: Filter): any {
   return condition;
 }
 
-function buildOrderBy(table: DrizzleTable, orderParam: string): any {
-  // Format: column.direction (e.g., created_at.desc)
-  const dotIndex = orderParam.lastIndexOf('.');
-  if (dotIndex === -1) return null;
-
-  const columnName = orderParam.substring(0, dotIndex);
-  const direction = orderParam.substring(dotIndex + 1);
-
-  const column = getColumn(table, columnName);
-  if (!column) return null;
-
-  return direction === 'desc' ? desc(column) : asc(column);
+function buildOrderBy(
+  table: DrizzleTable,
+  orderParam: string,
+  tieBreak: boolean,
+  groupColumns?: string[],
+  isHidden?: (column: string) => boolean,
+): { expressions: SQL[] } | { error: string; code: 'invalid_order'; column: string } {
+  const columns = Object.values(getTableColumns(table)) as DrizzleColumn[];
+  const expressions: SQL[] = [];
+  const named = new Set<string>();
+
+  for (const part of orderParam.split(',')) {
+    const dotIndex = part.lastIndexOf('.');
+    const columnName = (dotIndex < 0 ? part : part.slice(0, dotIndex)).trim();
+    const direction = dotIndex < 0 ? '' : part.slice(dotIndex + 1).trim();
+    const column = getColumn(table, columnName);
+    // getColumn also sees table properties and inherited names; only real columns can order rows.
+    if (!column || !columns.includes(column)) {
+      return { error: `Unknown order column: ${columnName}`, code: 'invalid_order', column: columnName };
+    }
+    if (direction !== 'asc' && direction !== 'desc') {
+      return { error: `Invalid order direction for ${columnName}: expected asc or desc`, code: 'invalid_order', column: columnName };
+    }
+    if (groupColumns && !groupColumns.some(name => getColumn(table, name) === column)) {
+      return { error: `Order column must be grouped: ${columnName}`, code: 'invalid_order', column: columnName };
+    }
+    expressions.push(direction === 'desc' ? desc(column) : asc(column));
+    named.add(column.name);
+  }
+
+  // Aggregate groups do not represent individual rows, so their order cannot use the row key.
+  if (tieBreak && is(table, PgTable)) {
+    const config = getTableConfig(table);
+    const primaryColumns = [
+      ...config.columns.filter(column => column.primary),
+      ...config.primaryKeys.flatMap(key => key.columns),
+    ];
+    for (const column of primaryColumns) {
+      if (!named.has(column.name) && !isHidden?.(column.name)) {
+        expressions.push(asc(column));
+        named.add(column.name);
+      }
+    }
+  }
+  return { expressions };
 }
 
 const RESERVED_QUERY_PARAMS = new Set(['limit', 'offset', 'order', 'select', 'deleted', 'or', 'and']);