@ultimat3/entity 11.2.0 → 12.0.0

package/src/entity.ts

@@ -4,6 +4,7 @@
 // this one call.
 
 import { renderThrowable } from '@ultimat3/core';
+import type { IndexMethod } from '@ultimat3/db';
 import { describeValue, type StandardSchemaV1 } from '@ultimat3/schema';
 import { entityNow } from './clock';
 import { assertColumnName, bindColumn, columnName, moneyColumns } from './column';
@@ -30,6 +31,21 @@ export interface IndexInit<C extends ColumnMap> {
   readonly unique?: boolean;
   /** Partial index predicate, written in the same language as an invariant. */
   readonly where?: (columns: InvariantColumns<C>) => Expr;
+  /**
+   * The access method. Omitted is `btree`, which is Postgres' own default and what every index
+   * declared before this existed is — so an entity that names none emits the statement it always
+   * emitted and nothing regenerates.
+   *
+   * `'gin'` is the one with a caller, and it is the whole point of the containment operators:
+   * measured on Postgres 16 over 20,000 rows, `tags @> …`, `tags <@ …`, `tags && …` and
+   * `data @> …` are each a Bitmap Index Scan with one and a Seq Scan without. The set is
+   * `@ultimat3/db`'s `INDEX_METHODS`, imported rather than restated — one declaration of one fact.
+   *
+   * Two Postgres rules ride with it and both are refused HERE, where the author is, rather than at
+   * `x db gen` or inside `ROLE=migrate` as the server's own syntax error: a GIN index cannot be
+   * unique and cannot order its keys.
+   */
+  readonly using?: IndexMethod;
 }
 
 export interface EntityInit<C extends ColumnMap> {
@@ -109,8 +125,87 @@ export type Entity<Row, C extends ColumnMap = ColumnMap> = EntityCore<Row, C> &
 
 const MONEY_PARTS = new Set(['minor', 'currency']);
 
-const indexName = (table: string, columns: readonly string[], unique: boolean): string =>
-  `${table}_${columns.join('_')}_${unique ? 'key' : 'idx'}`;
+/**
+ * What separates two indexes on the SAME columns: the predicate and the direction. Eight hex
+ * characters of sha256 over both — deterministic across processes, so a name is a property of the
+ * declaration and never of the run that generated it.
+ */
+/**
+ * What separates two indexes on the SAME columns: the predicate, the direction and the ACCESS
+ * METHOD. Eight hex characters of sha256 over all three — deterministic across processes, so a
+ * name is a property of the declaration and never of the run that generated it.
+ *
+ * The method belongs here for exactly the reason `where` does. A btree on an `arrayOf()` column
+ * answers `=` and an ordering; a GIN on the same column answers `@>` / `<@` / `&&`. They are two
+ * distinct indexes, and without the method in the name both are `<table>_<cols>_idx` — where the
+ * dedup below drops one in silence (the defect this discriminator was added for) or, since that
+ * dedup is now on the whole definition, two `create index` statements share one name and the
+ * migration is `42P07`.
+ */
+const indexDiscriminator = (
+  order: string | undefined,
+  where: string | null,
+  using: string | undefined,
+): string =>
+  new Bun.CryptoHasher('sha256')
+    // The method is APPENDED only when one was declared, never as an empty field: every name this
+    // function has ever minted for a partial or ordered index is therefore unchanged by the method
+    // existing, and an index that declares no method is byte-identical to the one it was.
+    .update(`${order ?? ''}|${where ?? ''}${using === undefined ? '' : `|${using}`}`)
+    .digest('hex')
+    .slice(0, 8);
+
+/**
+ * `<table>_<columns>_idx`, plus a discriminator when — and only when — the index carries a
+ * predicate, a direction or a non-default access method.
+ *
+ * Only then, because the plain name is load-bearing in two places: `unique()` on a column is an
+ * inline column clause and Postgres names the index it creates exactly `<table>_<column>_key`, so
+ * a discriminator there would make the generator emit a second `create unique index` for an index
+ * that already exists (`42P07`); and a foreign key's own index is deduped against a hand-declared
+ * one by this name.
+ *
+ * Without it, two DIFFERENT partial indexes on one column were one name — `posts_author_id_idx`
+ * for both `where status = 'published'` and `where status = 'draft'` — and the dedup below dropped
+ * the second with no error, no warning and no drift finding, since a declared index is matched by
+ * name.
+ */
+/**
+ * `NAMEDATALEN - 1`. Postgres truncates a longer identifier and says NOTHING, so two index names
+ * sharing their first 63 bytes become one index on the server — the same silent collapse the
+ * discriminator above exists to prevent, one layer down, and invisible to a drift check comparing
+ * DECLARED names because those still differ. Bytes and not characters: 63 is what the server
+ * counts, and `.length` would stop seeing the truncation the moment a name is not ASCII.
+ */
+const MAX_IDENTIFIER_BYTES = 63;
+
+const byteLength = (value: string): number => new TextEncoder().encode(value).length;
+
+const indexName = (
+  entityName: string,
+  table: string,
+  columns: readonly string[],
+  unique: boolean,
+  order?: string | undefined,
+  where: string | null = null,
+  using?: IndexMethod | undefined,
+): string => {
+  const suffix = unique ? 'key' : 'idx';
+  const base = `${table}_${columns.join('_')}`;
+  const plain = order === undefined && where === null && using === undefined;
+  const name = plain
+    ? `${base}_${suffix}`
+    : `${base}_${indexDiscriminator(order, where, using)}_${suffix}`;
+  const bytes = byteLength(name);
+  if (bytes <= MAX_IDENTIFIER_BYTES) return name;
+  throw invariantViolated(
+    entityName,
+    'index',
+    `the index on (${columns.join(', ')}) is named "${name}", which is ${bytes} bytes — ` +
+      `Postgres truncates an identifier at ${MAX_IDENTIFIER_BYTES} and does not say so, ` +
+      'so two indexes can silently become one',
+  );
+};
 
 const defaultValue = (meta: ColumnMeta): unknown => {
   const declared = meta.default;
@@ -127,7 +222,10 @@ export const entity = <const C extends ColumnMap>(
   const entries: readonly (readonly [string, AnyColumn])[] = Object.entries(init.columns);
   for (const [property, column] of entries) bindColumn(column, name, property);
 
-  const table = init.table === undefined ? name : assertColumnName(init.table);
+  // Both branches. The declared table was checked and the fallback — which is every entity that
+  // does not rename its table — was not, so an entity NAME closed the identifier in the same way a
+  // column name could: `entity('t" (x int); drop table u; --')` emitted that `drop table` verbatim.
+  const table = assertColumnName(init.table ?? name);
   const cacheTag = `entity:${name}`;
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
@@ -187,7 +285,11 @@ export const entity = <const C extends ColumnMap>(
         meta.kind === 'money' ? moneyColumns(property, meta).minor : columnName(property, meta),
       ];
       return [
-        { name: indexName(table, physical, meta.unique), columns: physical, unique: meta.unique },
+        {
+          name: indexName(name, table, physical, meta.unique),
+          columns: physical,
+          unique: meta.unique,
+        },
       ];
     }),
     ...(init.indexes ?? []).map((index) => {
@@ -206,18 +308,62 @@ export const entity = <const C extends ColumnMap>(
           'a partial index predicate must be expressible in SQL; a JS predicate cannot be one',
         );
       }
+      // Two rules Postgres has that a declaration can break, refused where the author wrote it.
+      // `@ultimat3/db` refuses both again at `createIndex` — that is not a duplicate, it is the
+      // guard for a description nobody built here — but its refusal lands at `x db gen` or, if a
+      // migration was already written, inside `ROLE=migrate` as the server's own syntax error with
+      // none of the entity's words in it.
+      if (index.using !== undefined && index.using !== 'btree') {
+        if (unique) {
+          throw invariantViolated(
+            name,
+            'index',
+            `the index on (${columns.join(', ')}) is unique and ${index.using}; ` +
+              `Postgres has no unique ${index.using} index — drop unique, or drop using`,
+          );
+        }
+        if (index.order !== undefined) {
+          throw invariantViolated(
+            name,
+            'index',
+            `the index on (${columns.join(', ')}) is ${index.using} and ${index.order}; ` +
+              'only a btree orders its keys — drop order, or drop using',
+          );
+        }
+      }
       return {
-        name: indexName(table, columns, unique),
+        name: indexName(name, table, columns, unique, index.order, where, index.using),
         columns,
         unique,
         ...(index.order === undefined ? {} : { order: index.order }),
         ...(where === null ? {} : { where }),
+        // Absent stays absent: `btree` written out would be a field every existing snapshot lacks,
+        // and `indexMethodOf` reads the two the same way precisely so nothing regenerates.
+        ...(index.using === undefined || index.using === 'btree' ? {} : { using: index.using }),
       };
     }),
   ];
-  // A foreign key already indexes its column; naming it again in `indexes` is not two indexes.
+  /**
+   * A foreign key already indexes its column; naming it again in `indexes` is not two indexes.
+   *
+   * On the WHOLE definition and not on the name. With the discriminator above the two rules agree
+   * exactly, so this is not a behaviour change on its own — it is which one FAILS LOUDLY if the
+   * naming is ever weakened again. Matching on the name drops the second index in silence, which
+   * is how two different partial indexes became one for three majors; matching on the definition
+   * keeps both, and two `create index` statements sharing a name is `42P07` on the next migration.
+   */
+  const identity = (index: IndexDef): string =>
+    [
+      index.name,
+      index.columns.join(','),
+      index.unique,
+      index.order ?? '',
+      index.where ?? '',
+      index.using ?? '',
+    ].join('|');
   const indexes: readonly IndexDef[] = declared.filter(
-    (index, position) => declared.findIndex((other) => other.name === index.name) === position,
+    (index, position) =>
+      declared.findIndex((other) => identity(other) === identity(index)) === position,
   );
 
   const tags = [cacheTag, ...(init.tags ?? [])];

package/src/errors.ts

@@ -18,6 +18,9 @@ export const ENTITY_OWNED_ERROR_CODES = [
   'X_N_PLUS_ONE_QUERY',
   'X_N_PLUS_ONE_WRITE',
   'X_REPO_CLIENT_PINNED',
+  'X_AGGREGATE_UNSUPPORTED',
+  'X_AGGREGATE_MIXED_CURRENCY',
+  'X_APPROXIMATE_COUNT_FILTERED',
 ] as const;
 
 /**
@@ -52,6 +55,9 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>>
   X_N_PLUS_ONE_QUERY: 'a read repeated once per row',
   X_N_PLUS_ONE_WRITE: 'a write repeated once per row',
   X_REPO_CLIENT_PINNED: 'a repository pinned to its own client cannot join the open transaction',
+  X_AGGREGATE_UNSUPPORTED: 'that column has no aggregate both drivers can answer alike',
+  X_AGGREGATE_MIXED_CURRENCY: 'an amount was aggregated across currencies',
+  X_APPROXIMATE_COUNT_FILTERED: 'an estimate was asked of a filtered chain',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the

package/src/index.ts

@@ -3,6 +3,8 @@
 /** Re-exported so an `entity` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
+export type { AggregateFn } from './aggregate';
+export { AVG_SCALE } from './aggregate';
 export type { BatchIterator } from './batch';
 export type { MoneyColumns } from './column';
 export { columnName, moneyColumns, snake } from './column';
@@ -72,6 +74,7 @@ export {
   MAX_ASSERTED_ROWS,
   toSql,
 } from './invariants';
+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 type { PostgresDriverOptions } from './pg-driver';
@@ -111,7 +114,6 @@ export type {
   Tx,
   UpsertArgs,
 } from './repo';
-export { memoryRepo, memoryTransactor } from './repo';
 export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-observer';
 export { observedRepo, rowObserver, setRowObserver } from './row-observer';
 export type {

package/src/instant.ts

@@ -0,0 +1,93 @@
+// Single responsibility: a `timestamptz` value at the precision the COLUMN stores it, rather than
+// the precision a JS `Date` holds. The column keeps microseconds and a `Date` keeps milliseconds,
+// so a page position minted from a decoded row ranks rows differently from the `order by` that
+// produced them. Microseconds since the epoch is the one form both sides can be exact in, and this
+// file is the only place the two representations meet.
+
+/** A `Date` is exactly this much coarser than the column it came out of. */
+const MICROS_PER_MILLI = 1000n;
+
+const MICROS_PER_SECOND = 1_000_000n;
+
+const FRACTION_DIGITS = 6;
+
+/**
+ * What `(col at time zone 'UTC')::text` prints: `2026-01-01 00:00:00.123456`, with the fraction
+ * omitted entirely when every digit of it is zero and TRUNCATED when the trailing ones are —
+ * `.1` is a tenth of a second, not one microsecond, which is why the fraction is padded on the
+ * right and never on the left.
+ *
+ * The year is `\d{4,}` because Postgres prints one wider than four digits unpadded; a `BC` suffix
+ * matches nothing here on purpose, and an unmatched text falls back to the decoded `Date`.
+ */
+const PG_INSTANT_TEXT = /^(\d{4,})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?$/;
+
+/**
+ * `Date.UTC` maps years 0–99 into the 1900s, so the epoch is built by assignment instead. Whole
+ * seconds only: the fraction is added in the microsecond domain, where it is exact.
+ */
+const utcSecondMillis = (parts: readonly number[]): number => {
+  const [year = 0, month = 1, day = 1, hour = 0, minute = 0, second = 0] = parts;
+  const at = new Date(0);
+  at.setUTCFullYear(year, month - 1, day);
+  at.setUTCHours(hour, minute, second, 0);
+  return at.getTime();
+};
+
+/** Floor division: `-1n / 2n` truncates toward zero, which would place a pre-1970 instant late. */
+const floorDiv = (value: bigint, by: bigint): bigint => {
+  const remainder = ((value % by) + by) % by;
+  return (value - remainder) / by;
+};
+
+/**
+ * The exact microsecond epoch of a `timestamptz` Postgres rendered as text, or `undefined` when
+ * the text is not one — a caller with nothing to read falls back to the decoded `Date`, which is
+ * the position it always had.
+ */
+export const pgInstantMicros = (text: unknown): bigint | undefined => {
+  if (typeof text !== 'string') return undefined;
+  const match = PG_INSTANT_TEXT.exec(text);
+  if (match === null) return undefined;
+  const [, year = '', month = '', day = '', hour = '', minute = '', second = '', fraction] = match;
+  const millis = utcSecondMillis([year, month, day, hour, minute, second].map(Number));
+  if (!Number.isFinite(millis)) return undefined;
+  // The fraction is always forward in time, so it ADDS even when the second boundary is negative.
+  return BigInt(millis) * MICROS_PER_MILLI + BigInt((fraction ?? '').padEnd(FRACTION_DIGITS, '0'));
+};
+
+/**
+ * The microsecond epoch of whatever a sort key is holding: a decoded row's `Date` (milliseconds,
+ * so the last three digits are zero), a value already counted in microseconds, or the decimal a
+ * cursor carries. `undefined` for anything else, so a caller decides rather than guessing at `0`.
+ */
+export const instantMicros = (value: unknown): bigint | undefined => {
+  if (typeof value === 'bigint') return value;
+  if (value instanceof Date) {
+    const millis = value.getTime();
+    return Number.isNaN(millis) ? undefined : BigInt(millis) * MICROS_PER_MILLI;
+  }
+  if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
+  return undefined;
+};
+
+/**
+ * The instant a seek binds, spelled so Postgres parses it back to the same microsecond. ISO 8601
+ * in UTC with all six fraction digits — `toISOString()` alone is milliseconds, which is the whole
+ * defect this file exists to close, so the fraction is written here rather than read off the
+ * `Date`.
+ */
+export const microsToIso = (micros: bigint): string => {
+  const second = floorDiv(micros, MICROS_PER_SECOND);
+  const fraction = micros - second * MICROS_PER_SECOND;
+  const whole = new Date(Number(second) * 1000).toISOString();
+  return `${whole.slice(0, whole.indexOf('.'))}.${String(fraction).padStart(FRACTION_DIGITS, '0')}Z`;
+};
+
+/**
+ * The output name the microsecond half of a sort key comes back under. Every physical column name
+ * in this framework is lower case — `columnName` is either `snake(property)`, which lower-cases,
+ * or a `.column()` name `assertColumnName` refuses unless it matches `[a-z_][a-z0-9_$]*` — so an
+ * UPPER-CASE suffix is a name no entity can declare and this alias can never shadow a column.
+ */
+export const seekAlias = (physicalColumn: string): string => `${physicalColumn}$US`;

package/src/memory-match.ts

@@ -6,9 +6,11 @@
 
 import { compareDecimalText } from '@ultimat3/core';
 import { keyOf } from './batch-read';
+import { arrayContains, arrayOverlaps, jsonContains, jsonHasKey } from './containment';
 import { kindOf, valueAt } from './cursor';
 import type { EntityCore } from './entity';
 import { EntityError } from './errors';
+import { instantMicros } from './instant';
 import type { Predicate } from './tenancy';
 import type { ColumnKind } from './types';
 
@@ -46,6 +48,25 @@ export const compareByKind = (
   left: unknown,
   right: unknown,
 ): number => {
+  // NULL is the LARGEST value, which is what `order by` means in Postgres and what `nulls last`
+  // ascending / `nulls first` descending spell out (`pg-sql.ts`'s `orderSql`, `@ultimat3/query`'s
+  // `compareValues`). Two absences are equal, so the next sort key decides — without this rule a
+  // NULL fell through to `String(left) < String(right)` and sorted as the four characters `null`,
+  // somewhere in the middle of the alphabet, which is a different listing from the one the
+  // database returns and a page boundary cut where the server cuts none.
+  if (isNull(left) || isNull(right)) {
+    return isNull(left) && isNull(right) ? 0 : isNull(left) ? 1 : -1;
+  }
+  // A `timestamptz` is compared in MICROSECONDS, which is what the column holds and what a cursor
+  // now carries (`cursor.ts`). The two sides are not the same shape and that is the point: a
+  // stored row here is a `Date` and a keyset position is a microsecond count, so a `Date`/`Date`
+  // test alone would fall through to `String(left) < String(right)` and order a page by the text
+  // of an ISO string against a decimal.
+  if (kind === 'timestamptz') {
+    const before = instantMicros(left);
+    const after = instantMicros(right);
+    if (before !== undefined && after !== undefined) return sign(before, after);
+  }
   if (left instanceof Date && right instanceof Date) return sign(left.getTime(), right.getTime());
   if (kind !== undefined && DECIMAL_TEXT.has(kind)) {
     // `undefined` when either side is not a plain decimal — that pair is not a numeric comparison,
@@ -199,5 +220,51 @@ export const matchesPredicate = <Row>(
       return isNull(actual);
     case 'is-not-null':
       return !isNull(actual);
+    // The containment half, decided by the column's DECLARED kind exactly as everything above it
+    // is: `@>` on a `jsonb` is recursive structural containment and `@>` on an array is plain
+    // element containment, and those are two different operators that happen to share a symbol.
+    // A NULL column value matches nothing, which is what the SQL answers too.
+    case 'contains':
+      return !isNull(actual) && containsBy(kind, actual, predicate.value);
+    case 'contained-by':
+      return !isNull(actual) && containsBy(kind, predicate.value, actual);
+    // `&&` is arrays only. A `jsonb` column reaching it is refused rather than guessed at: there
+    // is no `jsonb && jsonb` in Postgres, so any answer here would be one no statement can make.
+    case 'overlaps':
+      return (
+        !isNull(actual) &&
+        arrayOverlaps(
+          asArray(entity, predicate, actual),
+          asArray(entity, predicate, predicate.value),
+        )
+      );
+    case 'has-key':
+      return jsonHasKey(actual, predicate.value);
+  }
+};
+
+/** `left @> right`, under the rule the LEFT column's kind decides. */
+const containsBy = (kind: ColumnKind | undefined, left: unknown, right: unknown): boolean =>
+  kind === 'jsonb'
+    ? jsonContains(left, right)
+    : arrayContains(Array.isArray(left) ? left : [left], Array.isArray(right) ? right : [right]);
+
+/**
+ * The operand of an array-only operator. A `jsonb` column here is the caller asking for an
+ * operator Postgres does not have on that type, so it is refused where they wrote it rather than
+ * answered with something the database never would.
+ */
+const asArray = <Row>(
+  entity: EntityCore<Row>,
+  predicate: Predicate,
+  value: unknown,
+): readonly unknown[] => {
+  if (kindOf(entity, predicate.column) === 'jsonb') {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entity.$name}.${predicate.column} is jsonb, and Postgres has no && (overlaps) operator for jsonb`,
+      fix: `${entity.$name}.andWhere('${predicate.column}', 'contains', <value>)   # @> matches nested structure; && is for arrayOf() columns`,
+    });
   }
+  return Array.isArray(value) ? value : [value];
 };