@ultimat3/entity 27.13.0 → 27.13.1

package/README.md

@@ -465,6 +465,16 @@ visibility, never its page.
 | Refused | `min`/`max` on `text` (ordering is the database's collation there and JS code-unit order here); `avg` over money (every answer would be a silent rounding of a fraction of a minor unit — `sum()` and `count()` instead, dividing where the rounding is a decision); an amount covering more than one currency **or scale**; a money total past ±2^53 minor units |
 | `approximateCount()` | `reltuples` out of `pg_class`, constant time, because `count(*)` walks every visible row and no index can make it cheaper. The whole **table** — a filtered chain and every tenant-scoped entity are `X_APPROXIMATE_COUNT_FILTERED`, and `null` means the table has never been analysed |
 
+## The operator vocabulary
+
+`andWhere(column, op, value)` takes one of `OPERATORS` — `eq`, `neq`, `in`, `gt`, `gte`, `lt`,
+`lte`, `like`, `is-null`, `is-not-null`, `contains`, `contained-by`, `overlaps`, `has-key`,
+`matches` — and the `Operator` type is derived from that one list. An op outside it (`'>'`, `'GT'`)
+is `X_ENTITY_OPERATOR_UNKNOWN` on the `andWhere` line, and in both drivers for a hand-built plan —
+never an empty result. The `fix` names the operator meant: `>`→`gt`, `>=`→`gte`, `<`→`lt`,
+`<=`→`lte`, `=`→`eq`, `!=`/`<>`→`neq`. `isOperator(value)` is the same test, for an op read off
+the wire.
+
 ## Filtering inside a json() or arrayOf() column
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "27.13.0",
+  "version": "27.13.1",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -33,9 +33,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.13.0",
-    "@ultimat3/db": "27.13.0",
-    "@ultimat3/schema": "27.13.0",
-    "@ultimat3/time": "27.13.0"
+    "@ultimat3/core": "27.13.1",
+    "@ultimat3/db": "27.13.1",
+    "@ultimat3/schema": "27.13.1",
+    "@ultimat3/time": "27.13.1"
   }
 }

package/src/entity-error.ts

@@ -39,6 +39,7 @@ export const ENTITY_ERROR_CODES = [
   'X_ENTITY_SEALED_PREDICATE',
   'X_ENTITY_SEALED_IN_VIEW',
   'X_ENTITY_APPEND_ONLY',
+  'X_ENTITY_OPERATOR_UNKNOWN',
 ] as const;
 
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
@@ -72,6 +73,7 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
     'a sealed column is read by a predicate, an order or a rule the database evaluates',
   X_ENTITY_SEALED_IN_VIEW: 'a sealed column is named in a view',
   X_ENTITY_APPEND_ONLY: 'an append-only entity was asked to rewrite or remove a row',
+  X_ENTITY_OPERATOR_UNKNOWN: 'a predicate names an operator outside the vocabulary',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the
@@ -82,8 +84,8 @@ registerErrorCodes(
 );
 
 /**
- * How the codes here that are worth classifying are retried. The two sealed-column refusals and
- * the append-only refusal: each is the app's own declaration or call, so attempt five answers what attempt one did — and
+ * How the codes here that are worth classifying are retried. The two sealed-column refusals, the
+ * append-only refusal and the unknown operator: each is the app's own declaration or call, so attempt five answers what attempt one did — and
  * left unclassified, `classifyThrown` reads them as undecided and a job spends its whole retry
  * policy re-proving it. Listed although `terminal` is the default, for the reason core's own table
  * gives for `X_NOT_IMPLEMENTED`. The rest of this package's codes are unclassified, as they were.
@@ -92,6 +94,7 @@ export const ENTITY_ERROR_RETRY = {
   X_ENTITY_SEALED_PREDICATE: 'terminal',
   X_ENTITY_SEALED_IN_VIEW: 'terminal',
   X_ENTITY_APPEND_ONLY: 'terminal',
+  X_ENTITY_OPERATOR_UNKNOWN: 'terminal',
 } as const satisfies Readonly<Partial<Record<EntityErrorCode, ErrorRetry>>>;
 
 registerErrorRetry(ENTITY_ERROR_RETRY);

package/src/index.ts

@@ -87,6 +87,7 @@ export { compareByKind, sameValueOfKind } from './memory-match';
 export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
+export { isOperator, OPERATORS } from './operator';
 export { persistedRecordTypes } from './persisted-types';
 // For a change feed holding a table name and raw columns: `entityForTable` + `decodeRow` is the row
 // the app declared, money and all. Exported for `@ultimat3/realtime` (plan 101, 06 i).

package/src/memory-match.ts

@@ -14,6 +14,7 @@ import { instantMicros } from './instant';
 import { isNullish as isNull } from './is-null';
 import { likeMatches } from './like';
 import { DECIMAL_TEXT, numericOrder } from './numeric-compare';
+import { operatorUnknown } from './operator';
 import type { Predicate } from './tenancy';
 import type { ColumnKind } from './types';
 
@@ -188,6 +189,11 @@ export const matchesPredicate = <Row>(
       );
     case 'has-key':
       return jsonHasKey(actual, predicate.value);
+    // Unreachable for a typed call — and that is the case it exists for: an operator built from a
+    // string or cast past the type fell out of this switch as `undefined`, every row failed the
+    // filter and the read answered an empty list with no error. `pg-sql.ts` refuses identically.
+    default:
+      throw operatorUnknown(entity.$name, predicate.column, predicate.op);
   }
 };
 

package/src/operator.ts

@@ -0,0 +1,121 @@
+// The predicate vocabulary as ONE runtime list, the `Operator` type derived from it, and the one
+// refusal for anything outside it. Both drivers and the chain's `andWhere` raise the same error, so
+// an operator the type would have rejected cannot become "no rows" in one driver and a misleading
+// SQL refusal in the other just because nothing typechecked the call.
+
+import { EntityError } from './entity-error';
+import type { Predicate } from './tenancy';
+
+/**
+ * The predicate vocabulary, closed. The four after `is-not-null` are the CONTAINMENT half, added
+ * 2026-08-24: a `json()` or `arrayOf()` column was declared, written and then unfilterable — the ten
+ * operators before them could compare a column to a scalar and nothing else — so an app storing
+ * either had to leave the query language for hand-written SQL, which is the one read path in this
+ * framework with no tenancy guard on it. Their meaning is Postgres', written once in
+ * `containment.ts` and read by both drivers.
+ *
+ * There is deliberately no jsonpath EXPRESSION operator beside them: `contains` already matches
+ * nested structure (`data @> '{"a":{"b":1}}'`), and a path language inside the query language
+ * would be a second way to ask one question.
+ *
+ * `matches` is the FULL-TEXT half, added 2026-08-24. Its `column` is not a column: it is
+ * `SEARCH_PROPERTY`, and both drivers branch on the OPERATOR and read the entity's own `$search` —
+ * a `tsvector` is a physical column no row carries. The operand is a search TERM, always bound.
+ */
+export const OPERATORS = [
+  'eq',
+  'neq',
+  'in',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'like',
+  'is-null',
+  'is-not-null',
+  'contains',
+  'contained-by',
+  'overlaps',
+  'has-key',
+  'matches',
+] as const;
+
+export type Operator = (typeof OPERATORS)[number];
+
+const KNOWN: ReadonlySet<unknown> = new Set<unknown>(OPERATORS);
+
+export const isOperator = (op: unknown): op is Operator => KNOWN.has(op);
+
+/** The SQL spellings an author reaches for first, each to the operator it means here. */
+const SQL_SYMBOLS: ReadonlyMap<string, Operator> = new Map<string, Operator>([
+  ['>', 'gt'],
+  ['>=', 'gte'],
+  ['<', 'lt'],
+  ['<=', 'lte'],
+  ['=', 'eq'],
+  ['==', 'eq'],
+  ['===', 'eq'],
+  ['!=', 'neq'],
+  ['!==', 'neq'],
+  ['<>', 'neq'],
+]);
+
+/**
+ * The operator a near miss meant: a SQL symbol, or a known word in another case or with `_` or a
+ * space for `-` (`'GT'`, `'is_null'`, `'is not null'`). `undefined` when nothing is close enough
+ * to name — a guess there would be a fix that changes the question.
+ */
+export const operatorMeant = (op: unknown): Operator | undefined => {
+  if (typeof op !== 'string') return undefined;
+  const trimmed = op.trim();
+  const symbol = SQL_SYMBOLS.get(trimmed);
+  if (symbol !== undefined) return symbol;
+  const word = trimmed.toLowerCase().replaceAll(/[\s_]+/g, '-');
+  return isOperator(word) ? word : undefined;
+};
+
+/** A value from an app, rendered so building the message can never throw instead of refusing. */
+const shown = (op: unknown): string =>
+  typeof op === 'string' ? `'${op}'` : typeof op === 'symbol' ? String(op) : `a ${typeof op}`;
+
+/** A column name as the single-quoted literal the call is written with. */
+const quoted = (text: string): string =>
+  `'${text.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+
+/**
+ * An operator outside `OPERATORS`. The fix OPENS with the call to paste — the operator meant
+ * substituted when there is one, a placeholder when nothing is close — and carries the whole list
+ * after it; the sentence about what went wrong is the cause's. The call is written as `andWhere(…)`,
+ * never `<entity>.andWhere(…)`: the entity name is not the variable the author's chain hangs off
+ * (`describeCommand`'s rule).
+ */
+export const operatorUnknown = (entityName: string, column: string, op: unknown): EntityError => {
+  const meant = operatorMeant(op);
+  const list = OPERATORS.join(', ');
+  return new EntityError({
+    code: 'X_ENTITY_OPERATOR_UNKNOWN',
+    cause:
+      meant === undefined
+        ? `${entityName}: the predicate on ${quoted(column)} names ${shown(op)}, which is not an operator — read as "no row matches" it would answer an empty list with no error`
+        : `${entityName}: the predicate on ${quoted(column)} names ${shown(op)}, which is not an operator — the operator for it is '${meant}'. Read as "no row matches" it would answer an empty list with no error`,
+    fix:
+      meant === undefined
+        ? `andWhere(${quoted(column)}, '<operator>', value)   # one of: ${list}`
+        : `andWhere(${quoted(column)}, '${meant}', value)   # operators: ${list}`,
+  });
+};
+
+/**
+ * The predicate `andWhere` appends, refused on the line the author wrote and before any driver sees
+ * the plan: an operator that is not one (`'>'` for `'gt'`) reaches it whenever the call is not
+ * typechecked. The drivers refuse it too, identically, for a plan built by hand.
+ */
+export const checkedPredicate = (
+  entityName: string,
+  column: string,
+  op: unknown,
+  value: unknown,
+): Predicate => {
+  if (!isOperator(op)) throw operatorUnknown(entityName, column, op);
+  return { column, op, value };
+};

package/src/pg-sql.ts

@@ -10,6 +10,7 @@ import type { EntityCore } from './entity';
 import { SOFT_DELETE_COLUMN } from './entity';
 import { searchUndeclared } from './feature-errors';
 import { microsToIso, seekAlias } from './instant';
+import { operatorUnknown } from './operator';
 import { allColumns, arrayLiteral, columnsOf, physicalName } from './pg-row';
 import type { Predicate, QueryPlan, SortKey } from './tenancy';
 import type { ColumnKind } from './types';
@@ -129,6 +130,11 @@ const predicateSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFr
     // answered rows the memory driver never did.
     case 'has-key':
       return typeof value === 'string' ? sql`${column} operator(pg_catalog.?) ${value}` : NEVER;
+    // An operator outside the vocabulary, cast past the type: the statement used to be built around
+    // an `undefined` fragment and refused as `X_SQL_UNSAFE`, which names the wrong mistake. The
+    // memory driver's refusal, word for word (`memory-match.ts`).
+    default:
+      throw operatorUnknown(entity.$name, predicate.column, predicate.op);
   }
 };
 

package/src/query.ts

@@ -6,18 +6,18 @@
 
 import type { Page } from '@ultimat3/core';
 import { pageOf } from '@ultimat3/core';
-import type { BatchIterator } from './batch';
-import { assertBatchable, batchIterator } from './batch';
+import { assertBatchable, type BatchIterator, batchIterator } from './batch';
 import { entityNow } from './clock';
 import type { EntityCore } from './entity';
 import { searchUndeclared } from './feature-errors';
+import { checkedPredicate, type Operator } from './operator';
 import { assertFinitePageSize, DEFAULT_PAGE_SIZE, namedColumns } from './plan';
 import { preloaded, type RelatedTables } from './preload';
 import { type PreloadOptions, type PreloadRelation, preloadsWith } from './preload-ceiling';
 import type { Repo, RepoOptions, UpsertArgs } from './repo';
 import { copyRow, pickRow } from './sealed';
 import { SEARCH_PROPERTY } from './search';
-import type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
+import type { Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
 import { type Move, transitionRow } from './transition';
 import type {
   ColumnMap,
@@ -320,7 +320,7 @@ const builder = <Source, Row>(
       }),
 
     andWhere: (column: string, op: Operator, value?: unknown) =>
-      next({ where: [...state.where, { column, op, value }] }),
+      next({ where: [...state.where, checkedPredicate(entity.$name, column, op, value)] }),
 
     // Refused HERE as well as at the statement, because this is the line the author wrote: a chain
     // over an entity that declares nothing searchable can never produce a match, and the repair is

package/src/tenancy.ts

@@ -11,40 +11,11 @@ import {
   tenancyRowMismatch,
   tenancyUnscoped,
 } from './errors';
+import type { Operator } from './operator';
 import type { ColumnMap } from './types';
 
-/**
- * The predicate vocabulary, closed. The last four are the CONTAINMENT half, added 2026-08-24: a
- * `json()` or `arrayOf()` column was declared, written and then unfilterable — the ten operators
- * before them could compare a column to a scalar and nothing else — so an app storing either had
- * to leave the query language for hand-written SQL, which is the one read path in this framework
- * with no tenancy guard on it. Their meaning is Postgres', written once in `containment.ts` and
- * read by both drivers.
- *
- * There is deliberately no jsonpath EXPRESSION operator beside them: `contains` already matches
- * nested structure (`data @> '{"a":{"b":1}}'`), and a path language inside the query language
- * would be a second way to ask one question.
- */
-export type Operator =
-  | 'eq'
-  | 'neq'
-  | 'in'
-  | 'gt'
-  | 'gte'
-  | 'lt'
-  | 'lte'
-  | 'like'
-  | 'is-null'
-  | 'is-not-null'
-  | 'contains'
-  | 'contained-by'
-  | 'overlaps'
-  | 'has-key'
-  // The FULL-TEXT half, added 2026-08-24. `column` is not a column: it is `SEARCH_PROPERTY`, and
-  // both drivers branch on the OPERATOR and read the entity's own `$search` — a `tsvector` is a
-  // physical column no row carries, so resolving it as a property would be a lie in two places.
-  // The operand is a search TERM, always bound, never parsed as tsquery syntax.
-  | 'matches';
+/** The vocabulary is `OPERATORS` (`operator.ts`) — one list, and this type is derived from it. */
+export type { Operator } from './operator';
 
 export interface Predicate {
   readonly column: string;