@ultimat3/entity 29.4.0 → 30.0.0

package/src/memory-same-tenant.ts

@@ -0,0 +1,83 @@
+// Single responsibility: the memory driver's half of a same-tenant key. A target found under another
+// tenant is refused with the code Postgres answers the composite key with. A target not found stays
+// accepted: this driver enforces no foreign key at all, and starting would break every parent-less
+// fixture. Postgres answers absent and foreign identically, so nothing here can tell them apart.
+
+import { driverError, sameTenantKeyName } from '@ultimat3/db';
+import { keyOf } from './batch-read';
+import { kindOf, valueAt } from './cursor';
+import { describeReferences } from './describe';
+import type { EntityCore } from './entity';
+import type { ReferenceDescription } from './registry';
+
+/** One repository's rows as a neighbour may look at them: unscoped, because a guard is reading. */
+export interface MemoryTable {
+  readonly entity: EntityCore;
+  /** The stored row whose `property` holds `value`, or `undefined`. */
+  find(property: string, value: unknown): unknown;
+  /**
+   * A trigger's write, below every seam as the statement inside a Postgres trigger is: store `row`
+   * as given, or replace the stored `before` with `after`. `memory-lifecycle.ts` is the one caller.
+   */
+  readonly raw?: {
+    store(row: unknown, undo: (fn: () => void) => void): void;
+    replace(before: unknown, after: unknown, undo: (fn: () => void) => void): void;
+  };
+}
+
+/** One per driver, keyed by entity name: what a reference names (`Binding.table`). */
+export type MemoryTables = Map<string, MemoryTable>;
+
+/** Spelled the way Postgres would, so a uuid written in capitals is still the same row. */
+const sameCell = (kind: string | undefined, left: unknown, right: unknown): boolean =>
+  keyOf(kind ?? '', left) === keyOf(kind ?? '', right);
+
+const inBatch = (
+  batch: readonly unknown[],
+  owner: EntityCore,
+  property: string,
+  value: unknown,
+): unknown => batch.find((row) => sameCell(kindOf(owner, property), valueAt(row, property), value));
+
+/**
+ * The judge for one entity. The references are read on the first write and kept: a thunk cannot be
+ * answered at declaration, and a write is the one moment both schema modules have evaluated.
+ */
+export const sameTenantJudge = <Row>(
+  entity: EntityCore<Row>,
+  tables: MemoryTables,
+): ((row: Row, batch?: readonly Row[]) => void) => {
+  let edges: readonly ReferenceDescription[] | undefined;
+  const own = entity as EntityCore;
+  return (row, batch = []) => {
+    const tenant = entity.$tenantColumn;
+    if (tenant === null) return;
+    edges ??= describeReferences(entity.$name, Object.entries(entity.$columns)).filter(
+      (edge) => edge.sameTenant !== null,
+    );
+    const rowTenant = valueAt(row, tenant);
+    if (rowTenant === null || rowTenant === undefined) return;
+    for (const edge of edges) {
+      const value = valueAt(row, edge.property);
+      if (value === null || value === undefined) continue;
+      const table = tables.get(edge.targetEntity);
+      if (table === undefined) continue;
+      const target = table.entity;
+      const targetTenant = target.$tenantColumn;
+      if (targetTenant === null) continue;
+      const found =
+        table.find(edge.targetProperty, value) ??
+        (target.$name === entity.$name
+          ? inBatch(batch, own, edge.targetProperty, value)
+          : undefined);
+      if (found === undefined) continue;
+      if (sameCell(kindOf(target, targetTenant), valueAt(found, targetTenant), rowTenant)) continue;
+      const constraint = sameTenantKeyName(entity.$table, edge.column);
+      throw driverError(`memory write into ${entity.$table}`, {
+        code: '23503',
+        constraint,
+        message: `insert or update on table "${entity.$table}" violates foreign key constraint "${constraint}"`,
+      });
+    }
+  };
+};

package/src/memory-seek.ts

@@ -0,0 +1,44 @@
+// Single responsibility: where a cursor's next page starts among the memory driver's sorted rows.
+// Split from `memory-repo.ts` for its line ceiling.
+
+import { kindOf, seekFrom, valueAt } from './cursor';
+import type { EntityCore } from './entity';
+import { compareByKind } from './memory-match';
+import type { QueryPlan } from './tenancy';
+
+/** Lexicographic over the sort keys, direction applied. `> 0` means "after the cursor". */
+const compareToSeek = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  row: unknown,
+  seek: readonly unknown[],
+): number => {
+  for (const [index, entry] of plan.orderBy.entries()) {
+    // The COLUMN's kind, not the value's: the seek was revived from the same kind (`cursor.ts`),
+    // so a `bigint` column compares its stored decimal string against a revived `BigInt` as one
+    // number instead of as two pieces of text.
+    const order = compareByKind(
+      kindOf(entity, entry.column),
+      valueAt(row, entry.column),
+      seek[index],
+    );
+    if (order !== 0) return entry.direction === 'desc' ? -order : order;
+  }
+  return 0;
+};
+
+/**
+ * Where the next page starts. By sort position, not by the previous row's id: that row may have
+ * been deleted between the two requests, and an id that is no longer there would restart
+ * pagination at the top instead of continuing it.
+ */
+export const afterCursor = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  found: readonly Row[],
+): number => {
+  const seek = seekFrom(entity, plan);
+  if (seek === undefined) return 0;
+  const start = found.findIndex((row) => compareToSeek(entity, plan, row, seek) > 0);
+  return start === -1 ? found.length : start;
+};

package/src/memory-transactor.ts

@@ -0,0 +1,94 @@
+// Single responsibility: the in-memory `Transactor`. Undo closures a driver registered run on a
+// throw, commit effects after the ROOT succeeded, and a write that outlives the scope is refused as
+// `@ultimat3/db` refuses a statement on a finished transaction. Beside `memory-repo.ts` rather than
+// in it, because the lock needs a transaction and the repository needs the lock.
+
+import {
+  enrolMemoryTx,
+  inMemoryJournal,
+  type MemoryOutcome,
+  memoryJournal,
+  memoryOutcomeOf,
+  memoryRoot,
+  memoryTxClosed,
+  outsideMemoryJournal,
+  refuseIfMemoryTxClosed,
+} from './memory-journal';
+import type { Transactor, Tx } from './repo';
+
+let txCounter = 0;
+
+/** Best-effort and off the journal, as `@ultimat3/db` runs them: the work is already durable. */
+const runEffects = (effects: readonly (() => void)[]): void =>
+  outsideMemoryJournal(() => {
+    for (const effect of effects) {
+      try {
+        effect();
+      } catch {
+        // an effect is a report about a durable write; it may not fail the write
+      }
+    }
+  });
+
+/**
+ * In-memory transactor: undo closures registered by drivers run on failure. Ambient, as
+ * `withTransaction` is: a write inside `work` that names no `tx` joins this one. Nested, a commit is
+ * a savepoint's release — its undos and its effects move to the enclosing transaction, so an effect
+ * runs only once the root commits and never after the root rolls back.
+ *
+ * Ended, the scope still rides every promise `work` forgot to await. A write there is refused
+ * (`X_DB_TRANSACTION_CLOSED`) once the root has ended; on a nested handle while the root is open it
+ * is the enclosing transaction's, as a statement on a released savepoint's handle is in Postgres.
+ * An effect registered after the root ended runs at once after a COMMIT and never after a ROLLBACK.
+ */
+export const memoryTransactor = (): Transactor => ({
+  async run(work) {
+    const outer = memoryJournal();
+    refuseIfMemoryTxClosed(outer);
+    const outcome: MemoryOutcome = (outer && memoryOutcomeOf(outer)) ?? { value: 'open' };
+    const undos: (() => void)[] = [];
+    const commits: (() => void)[] = [];
+    let ended = false;
+    txCounter += 1;
+    const id = `tx-${txCounter}`;
+    const tx: Tx = {
+      id,
+      onRollback: (undo) => {
+        if (outcome.value !== 'open') throw memoryTxClosed(id, outcome.value);
+        if (!ended) undos.push(undo);
+        else outer?.onRollback(undo);
+      },
+      onCommit: (effect) => {
+        if (outcome.value === 'committed') runEffects([effect]);
+        else if (outcome.value === 'rolled-back') return;
+        else if (!ended) commits.push(effect);
+        else outer?.onCommit?.(effect);
+      },
+    };
+    enrolMemoryTx(tx, outer === undefined ? tx : memoryRoot(outer), outcome);
+    let result: Awaited<ReturnType<typeof work>>;
+    try {
+      result = await inMemoryJournal(tx, () => work(tx));
+    } catch (error) {
+      ended = true;
+      if (outer === undefined) outcome.value = 'rolled-back';
+      for (const undo of undos.reverse()) undo();
+      throw error;
+    }
+    ended = true;
+    if (outer === undefined) {
+      outcome.value = 'committed';
+      runEffects(commits);
+      return result;
+    }
+    // The root ended while this savepoint ran: its RELEASE is refused, and its rows went where the
+    // root went — kept by a commit, undone here after a rollback, whose undos never saw them.
+    if (outcome.value !== 'open') {
+      if (outcome.value === 'rolled-back') for (const undo of undos.reverse()) undo();
+      throw memoryTxClosed(id, outcome.value);
+    }
+    for (const undo of undos) outer.onRollback(undo);
+    for (const effect of commits) outer.onCommit?.(effect);
+    return result;
+  },
+});

package/src/memory-unique.ts

@@ -4,6 +4,8 @@
 // a quiet overwrite under `x dev` and in every app test.
 
 import { driverError } from '@ultimat3/db';
+import { keyOf } from './batch-read';
+import { columnName } from './column';
 import type { EntityCore } from './entity';
 import { bindValues } from './pg-row';
 import type { RowPatch } from './types';
@@ -17,14 +19,26 @@ export const uniqueViolation = (entity: EntityCore, constraint: string): Error =
     message: `duplicate key value violates unique constraint "${constraint}"`,
   });
 
+/** A number's kinds: `'2.5'` and `'2.50'` are one key to Postgres, and so are `7` and `'7'`. */
+const BY_VALUE: ReadonlySet<string> = new Set(['integer', 'bigint', 'numeric']);
+
 /** A value as a comparable token; `null` answers `undefined` — NULLS DISTINCT, as Postgres. */
-const cellOf = (value: unknown): string | undefined => {
+const cellOf = (kind: string | undefined, value: unknown): string | undefined => {
   if (value === null || value === undefined) return undefined;
   if (value instanceof Date) return `date:${value.getTime()}`;
-  if (typeof value === 'string') return `s:${value}`;
+  if (kind !== undefined && BY_VALUE.has(kind)) return `n:${keyOf(kind, value)}`;
+  if (typeof value === 'string') return `s:${kind === undefined ? value : keyOf(kind, value)}`;
   return `${typeof value}:${JSON.stringify(value)}`;
 };
 
+/** Physical column -> kind. A money part is absent: its cells compare as the values they hold. */
+const kindsOf = <Row>(entity: EntityCore<Row>): ReadonlyMap<string, string> =>
+  new Map(
+    Object.entries(entity.$columns)
+      .filter(([, column]) => column.$meta.kind !== 'money')
+      .map(([property, column]) => [columnName(property, column.$meta), column.$meta.kind]),
+  );
+
 /**
  * The first unique constraint `candidate` collides with among `others`, or `undefined`. Partial
  * ones are skipped: their predicate is SQL this driver cannot evaluate, and a guess would refuse
@@ -39,12 +53,13 @@ export const uniqueClash = <Row>(
   if (unique.length === 0) return undefined;
   const bound = (row: Row) => bindValues(entity, row as unknown as RowPatch<Row>);
   const incoming = bound(candidate);
+  const kinds = kindsOf(entity);
   for (const index of unique) {
-    const key = index.columns.map((name) => cellOf(incoming.get(name)));
+    const key = index.columns.map((name) => cellOf(kinds.get(name), incoming.get(name)));
     if (key.some((part) => part === undefined)) continue;
     for (const other of others) {
       const stored = bound(other);
-      if (index.columns.every((name, at) => cellOf(stored.get(name)) === key[at]))
+      if (index.columns.every((name, at) => cellOf(kinds.get(name), stored.get(name)) === key[at]))
         return index.name();
     }
   }

package/src/n-plus-one.ts

@@ -5,7 +5,8 @@
 // Nothing here counts anything. A ledger elsewhere decides that a shape repeated; this turns that
 // verdict into the one error the surfaces render.
 
-import type { EntityError, PreloadCandidate } from './errors';
+import { EntityError } from './entity-error';
+import type { PreloadCandidate } from './errors';
 import { nPlusOneQuery, nPlusOneWrite } from './errors';
 import type { RelationKind } from './relations';
 import { relationMap } from './relations';
@@ -105,18 +106,35 @@ const readLoop = (loop: StatementLoop): EntityError => {
   return nPlusOneQuery(loop.subject, loop.count, { form: 'preload', candidates: [first, ...rest] });
 };
 
+/**
+ * A write into the job queue's own tables — `@ultimat3/jobs`' outbox stage or its enqueue. The loop
+ * is a loop of `handle.enqueue`, the statement is the queue's and not the app's, and `insertAll` is a
+ * call no enqueuer can make: the batch is the handle's. Read off the statement text, the subject a
+ * hand-written statement carries; a word boundary, so `x_jobs_archive` is still the app's SQL.
+ */
+const QUEUE_INSERT = /\binsert\s+into\s+x_(?:outbox|jobs)\b(?!_)/i;
+
+const writeLoop = (loop: StatementLoop): EntityError => {
+  if (loop.entity === undefined && QUEUE_INSERT.test(loop.subject)) {
+    return new EntityError({
+      code: 'X_N_PLUS_ONE_WRITE',
+      cause: nPlusOneWrite(loop.subject, loop.count, { form: 'sql' }).cause,
+      fix: "handle.enqueueMany(inputs)   # one statement per 1,000 jobs, staged in the same transaction — or expectedQueryLoop('<why one enqueue per row is optimal>', fn) when the loop is deliberate",
+    });
+  }
+  return nPlusOneWrite(
+    loop.subject,
+    loop.count,
+    loop.entity === undefined
+      ? { form: 'sql' }
+      : { form: 'bulk', entity: loop.entity, op: loop.op },
+  );
+};
+
 /**
  * One repeated shape, as the error every surface renders. One entry point and not two, because the
  * caller already knows which of the two codes it holds and a second decision here is a second place
  * for the read and the write halves to disagree about what a loop is.
  */
 export const nPlusOne = (loop: StatementLoop): EntityError =>
-  loop.kind === 'read'
-    ? readLoop(loop)
-    : nPlusOneWrite(
-        loop.subject,
-        loop.count,
-        loop.entity === undefined
-          ? { form: 'sql' }
-          : { form: 'bulk', entity: loop.entity, op: loop.op },
-      );
+  loop.kind === 'read' ? readLoop(loop) : writeLoop(loop);

package/src/numeric-compare.ts

@@ -55,3 +55,46 @@ export const numericOrder = (
   if (!isNumber(value) || !isNumber(operand)) return undefined;
   return value < operand ? -1 : value > operand ? 1 : 0;
 };
+
+const INTEGER_TEXT = /^[+-]?\d+$/;
+const DECIMAL_PARTS = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/;
+
+/** Past this an exponent would have the padding below build a string nobody asked for. */
+const MAX_EXPONENT = 1000;
+
+const textOf = (value: unknown): string | undefined => {
+  if (typeof value === 'string') return value.trim();
+  return isNumber(value) ? plainDecimal(value) : undefined;
+};
+
+/**
+ * One spelling for the value an integer column compares by: `'007'`, `'+7'`, `7` and `7n` are one
+ * key to Postgres. `undefined` for what such a column cannot hold (`'7.0'`, `''`, which `BigInt`
+ * alone would read as `0`), so a caller keeps it as written and the server answers its own refusal.
+ */
+export const canonicalInteger = (value: unknown): string | undefined => {
+  const text = textOf(value);
+  return text !== undefined && INTEGER_TEXT.test(text) ? BigInt(text).toString() : undefined;
+};
+
+/**
+ * One spelling for the value a `numeric` compares by: `'2.5'`, `'2.50'` and `'+02.500'` are one
+ * value and one unique key, and a `numeric` has one zero. Answers what `numericOrder` calls equal,
+ * plus the literals Postgres also reads (`'.5'`, `'5.'`, `'1e3'`). `undefined` when it is no such
+ * literal, for the same reason as above.
+ */
+export const canonicalDecimal = (value: unknown): string | undefined => {
+  const parts = DECIMAL_PARTS.exec(textOf(value) ?? 'not a decimal');
+  if (parts === null) return undefined;
+  const [, sign = '', whole = '', fraction = '', exponent = '0'] = parts;
+  const shift = Number(exponent);
+  if (whole.length + fraction.length === 0 || Math.abs(shift) > MAX_EXPONENT) return undefined;
+  const digits = whole + fraction;
+  const point = whole.length + shift;
+  const integer = point <= 0 ? '' : digits.slice(0, point).padEnd(point, '0');
+  const rest = point <= 0 ? '0'.repeat(-point) + digits : digits.slice(point);
+  const before = integer.replace(/^0+/, '') || '0';
+  const after = rest.replace(/0+$/, '');
+  const unsigned = after === '' ? before : `${before}.${after}`;
+  return sign === '-' && unsigned !== '0' ? `-${unsigned}` : unsigned;
+};

package/src/pg-aggregates.ts

@@ -0,0 +1,185 @@
+// Single responsibility: the Postgres driver's aggregate reads — `countBy`, `aggregate`,
+// `approximateCount` and `series` — each one statement (money: two) under the read path's plan.
+// Split from `pg-driver.ts` at its line ceiling; the rules are the shared files' (`aggregate.ts`,
+// `count-by.ts`, `time-bucket.ts`), so memory and Postgres answer every one of these alike.
+
+import { type DbClient, withStatementAttribution } from '@ultimat3/db';
+import { aggregateColumnOf, aggregateMinor, assertOneUnit, type MoneyUnit } from './aggregate';
+import { decodeAggregate } from './aggregate-decode';
+import { moneyColumns } from './column';
+import { countsFrom, groupColumnOf, groupValue, MAX_GROUPS } from './count-by';
+import type { EntityCore } from './entity';
+import type { ReadShape } from './pg-sql';
+import {
+  type AggregateRow,
+  aggregateStatement,
+  countByStatement,
+  currenciesStatement,
+  estimateStatement,
+  type GroupRow,
+  type MoneyUnitRow,
+  type SeriesRow,
+  seriesStatement,
+} from './pg-sql-aggregate';
+import { readPlan } from './plan';
+import type { FindManyArgs, Repo } from './repo';
+import type { QueryPlan } from './tenancy';
+import { type SeriesPlan, seriesFrom, seriesPlanOf } from './time-bucket';
+import type { MoneyValue } from './types';
+
+type AggregateReads<Row> = Pick<
+  Required<Repo<Row>>,
+  'aggregate' | 'approximateCount' | 'countBy' | 'series'
+>;
+
+const shapeOf = (args: FindManyArgs): ReadShape => ({
+  includeDeleted: args.includeDeleted === true,
+});
+
+const unitOf = (row: MoneyUnitRow): MoneyUnit => ({
+  currency: String(row.group_value ?? '').trim(),
+  scale: row.group_scale === null || row.group_scale === undefined ? null : Number(row.group_scale),
+});
+
+export const postgresAggregates = <Row>(
+  entity: EntityCore<Row>,
+  client: () => DbClient,
+): AggregateReads<Row> => {
+  const attributed = <T>(op: string, send: () => Promise<T>): Promise<T> =>
+    withStatementAttribution(entity.$name, op, send);
+
+  /**
+   * Money is judged BEFORE the aggregate is asked for, in its own statement: `sum(minor)` over two
+   * currencies is a number in neither, and the refusal has to name them.
+   */
+  const moneyUnit = async (
+    op: string,
+    fn: 'sum' | 'avg' | 'min' | 'max',
+    column: string,
+    money: ReturnType<typeof moneyColumns>,
+    plan: QueryPlan,
+    shape: ReadShape,
+  ): Promise<MoneyUnit | undefined> =>
+    assertOneUnit(
+      entity,
+      fn,
+      column,
+      (
+        await attributed(op, () =>
+          client().query<MoneyUnitRow>(
+            currenciesStatement(entity, plan, shape, money.currency, money.scale),
+          ),
+        )
+      ).map(unitOf),
+    );
+
+  const moneyOf = (column: string, unit: MoneyUnit, text: string): MoneyValue => ({
+    minor: aggregateMinor(entity, 'sum', column, text),
+    currency: unit.currency,
+    ...(unit.scale === null ? {} : { scale: unit.scale }),
+  });
+
+  /** One bucket's value: the count, or the sum decoded as `sum()` decodes it. */
+  const pointValue = (plan: SeriesPlan, row: SeriesRow, unit: MoneyUnit | undefined): unknown => {
+    if (plan.sum === null) return Number(row.bucket_count);
+    const text = row.bucket_value;
+    if (text === null || text === undefined) return null;
+    const kind = plan.sum.column.$meta.kind;
+    if (kind !== 'money') return decodeAggregate('sum', kind, String(text));
+    return unit === undefined ? null : moneyOf(plan.sum.property, unit, String(text));
+  };
+
+  return {
+    async countBy(column, args = {}) {
+      const op = 'countBy';
+      const grouped = groupColumnOf(entity, column, op);
+      const plan = readPlan(entity, args, op);
+      // One group past the bound, for the same reason a page reads one row past its limit: the
+      // presence of that group is what says the answer was never going to fit, and `countsFrom`
+      // refuses it rather than hand back a breakdown missing its tail.
+      const rows = await attributed(op, () =>
+        client().query<GroupRow>(
+          countByStatement(entity, plan, shapeOf(args), column, MAX_GROUPS + 1),
+        ),
+      );
+      return countsFrom(
+        entity,
+        column,
+        op,
+        rows.map((row) => [groupValue(grouped, row.group_value), Number(row.group_count)] as const),
+      );
+    },
+
+    async aggregate(fn, column, args = {}) {
+      const op = fn;
+      const declared = aggregateColumnOf(entity, fn, column);
+      const plan = readPlan(entity, args, op);
+      const shape = shapeOf(args);
+      const money = declared.$meta.kind === 'money' ? moneyColumns(column, declared.$meta) : null;
+      const unit = money === null ? undefined : await moneyUnit(op, fn, column, money, plan, shape);
+      const row = await attributed(op, () =>
+        client().one<AggregateRow>(
+          aggregateStatement(entity, plan, shape, fn, money === null ? column : `${column}.minor`),
+        ),
+      );
+      const text = row?.agg_value;
+      if (text === null || text === undefined) return null;
+      if (money === null) return decodeAggregate(fn, declared.$meta.kind, String(text));
+      if (unit === undefined) return null;
+      return {
+        minor: aggregateMinor(entity, fn, column, String(text)),
+        currency: unit.currency,
+        ...(unit.scale === null ? {} : { scale: unit.scale }),
+      };
+    },
+
+    /**
+     * `reltuples`, the planner's own estimate — one row out of `pg_class`, constant time. `count(*)`
+     * walks every visible row, so past a few million it trips a web role's `statement_timeout`.
+     */
+    async approximateCount(args = {}) {
+      const op = 'approximateCount';
+      // Built and therefore GUARDED: tenancy still applies, and a filtered chain is refused here
+      // rather than answered with the whole table's estimate.
+      readPlan(entity, args, op);
+      const row = await attributed(op, () =>
+        client().one<{ estimate: unknown }>(estimateStatement(entity.$table)),
+      );
+      const estimate = Number(row?.estimate ?? -1);
+      // `-1` is what Postgres 14+ stores for a table nobody has analysed. That is an absence of an
+      // estimate, not an estimate of zero, and answering `0` would read exactly like an empty
+      // table to every caller.
+      return Number.isFinite(estimate) && estimate >= 0 ? estimate : null;
+    },
+
+    async series(spec, args = {}) {
+      const op = 'series';
+      const series = seriesPlanOf(entity, spec);
+      const plan = readPlan(entity, args, op);
+      const shape = shapeOf(args);
+      const sum = series.sum;
+      const money =
+        sum?.column.$meta.kind === 'money' ? moneyColumns(sum.property, sum.column.$meta) : null;
+      const unit =
+        money === null || sum === null
+          ? undefined
+          : await moneyUnit(op, 'sum', sum.property, money, plan, shape);
+      const target = sum === null ? null : money === null ? sum.property : `${sum.property}.minor`;
+      // One bucket past the bound, as `countBy` reads one group past it: its presence is the
+      // refusal, never a chart missing its tail.
+      const rows = await attributed(op, () =>
+        client().query<SeriesRow>(
+          seriesStatement(entity, plan, shape, series, target, MAX_GROUPS + 1),
+        ),
+      );
+      return seriesFrom(
+        entity,
+        series,
+        rows.map((row) => ({
+          bucket: new Date(Number(row.bucket_ms)),
+          value: pointValue(series, row, unit),
+        })),
+      );
+    },
+  };
+};