@owlmeans/postgres-resource 0.1.18-rc.4 → 0.1.18-rc.40

package/src/resource.ts

@@ -1,17 +1,14 @@
 import { appendContextual, assertContext } from '@owlmeans/context'
-import type { BasicContext, Contextual } from '@owlmeans/context'
 import {
-  MisshapedRecord, RecordExists, RecordUpdateFailed, UnknownRecordError,
-  UnsupportedArgumentError, prepareListOptions
+  MisshapedRecord, RecordExists, RecordUpdateFailed, UnknownRecordError, UnsupportedArgumentError
 } from '@owlmeans/resource'
 import type {
-  ListPager, MigrationStage, ResourceMaker, ResourceRecord
+  Criteria, FirstOptions, ListOptions, ListResult, MigrationStage, ResourceRecord, WriteOptions
 } from '@owlmeans/resource'
 import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
 import type { AnySchema, JSONSchemaType } from 'ajv'
 import { eq, sql } from 'drizzle-orm'
 import type { SQL } from 'drizzle-orm'
-import type { PgTable } from 'drizzle-orm/pg-core'
 import type { PoolClient, QueryResultRow } from 'pg'
 
 import { DEFAULT_DB_ALIAS, DEFAULT_PAGE_SIZE, ID_FIELD } from './consts.js'
@@ -31,29 +28,18 @@ import { refOf, resolvePlaceholders } from './utils/sql.js'
 type Config = ServerConfig
 type Context<C extends Config = Config> = ServerContext<C>
 
-type Getter = string | { field?: string, ttl?: number | Date | string }
-
-const fieldOf = (opts?: Getter): string | undefined =>
-  typeof opts === 'string' ? opts : opts?.field
-
-const ttlOf = (opts?: Getter): unknown =>
-  typeof opts === 'object' ? opts.ttl : undefined
-
-/**
- * Hand a runtime built table to Drizzle's query builder.
- *
- * {@link PgRuntimeTable} is deliberately untyped — the table is compiled from a JSON schema
- * at runtime, so there is no static shape to infer. Naming the erased `PgTable` here is what
- * keeps the builder's *result* types usable; casting the argument to `never` instead would
- * silently collapse every returned row to `never`.
- */
-const pgTable = (table: PgRuntimeTable): PgTable => table as unknown as PgTable
+/** Postgres has no row expiry — silently ignoring a TTL would lose data. */
+const refuseTtl = (opts?: WriteOptions): void => {
+  if (opts?.ttl != null) {
+    throw new UnsupportedArgumentError('ttl')
+  }
+}
 
 export const makePostgresResource = <
   R extends ResourceRecord, T extends PostgresResource<R> = PostgresResource<R>
 >(
   alias: string, dbAlias: string = DEFAULT_DB_ALIAS, serviceAlias: string = DEFAULT_DB_ALIAS,
-  makeCustomResource?: ResourceMaker<R, T>, tableName?: string
+  tableName?: string
 ): T => {
   const location = `postgres-resource:${alias}`
   const declaration = getDeclaration(alias)
@@ -103,11 +89,24 @@ export const makePostgresResource = <
     return column
   }
 
-  const identify = (table: TableSpec, property: string, value: unknown): SQL => {
-    const column = columnOf(table, property)
+  /** `WHERE <column> = <value>` for one property, by its schema name. */
+  const identify = (
+    table: TableSpec, from: PgRuntimeTable, property: string, value: unknown
+  ): SQL => eq(from[columnOf(table, property).property], value)
 
-    return eq(entity![column.property], value)
-  }
+  /**
+   * The condition a read or a write is keyed on. A string is the record's id; a criteria
+   * object is translated in full, so one call can ask by several fields at once.
+   */
+  const where = (
+    table: TableSpec, from: PgRuntimeTable, query: string | Criteria<R>
+  ): SQL | undefined => typeof query === 'string'
+    ? identify(table, from, ID_FIELD, query)
+    : criteriaToSql(query, table, from)
+
+  /** What an unknown record is called in the error — the id, or the query that missed. */
+  const describe = (query: string | Criteria<R>): string =>
+    typeof query === 'string' ? query : JSON.stringify(query)
 
   const raw = async <Row extends QueryResultRow = QueryResultRow>(
     text: string, params?: unknown[]
@@ -125,67 +124,68 @@ export const makePostgresResource = <
     }
   }
 
-  const resource: T = appendContextual<T>(alias, {
-    get: async (id, field, opts) => {
-      const record = await resource.load(id, field, opts)
+  /**
+   * The single-record read both `get` and `load` answer with. Standalone so neither closes over
+   * `resource` — a member that referenced it could not be inferred against the generic.
+   */
+  const loadOne = async (query: string | Criteria<R>, opts?: FirstOptions<R>): Promise<R | null> => {
+    const { db, spec: table, entity: from } = await ensure()
+
+    const rows = await db.drizzle.select().from(from).where(where(table, from, query))
+      .orderBy(...sortToSql(opts?.sort, table, from)).limit(1)
+
+    return rows.length < 1 ? null : resultToRecord<R>(rows[0] as Record<string, unknown>, table)
+  }
+
+  const members: Partial<PostgresResource<R>> = {
+    get: (async (query: string | Criteria<R>, opts?: FirstOptions<R>): Promise<R> => {
+      const record = await loadOne(query, opts)
       if (record == null) {
-        throw new UnknownRecordError(id)
+        throw new UnknownRecordError(describe(query))
       }
 
       return record
-    },
+    }) as T['get'],
 
-    load: async (id, field, opts) => {
-      if (typeof field === 'object') {
-        opts = field
-        field = field.field
-      }
-      if (ttlOf(opts) != null) {
-        /** Postgres has no row expiry — silently ignoring a TTL would lose data. */
-        throw new UnsupportedArgumentError('ttl')
-      }
-      const { db, spec: table, entity: from } = await ensure()
+    load: loadOne as T['load'],
 
-      const rows = await db.drizzle.select().from(pgTable(from))
-        .where(identify(table, field ?? ID_FIELD, id)).limit(1)
-
-      return rows.length < 1 ? null : resultToRecord(rows[0] as Record<string, unknown>, table)
-    },
-
-    list: async (criteria, opts) => {
+    list: async (criteria?: Criteria<R>, opts?: ListOptions<R>): Promise<ListResult<R>> => {
       const { db, spec: table, entity: from } = await ensure()
-      const options = prepareListOptions(DEFAULT_PAGE_SIZE, criteria, opts)
-      const pager: ListPager = options.pager ?? {}
-      const size = pager.size ?? DEFAULT_PAGE_SIZE
-      const where = criteriaToSql(options.criteria, table, from)
+      const condition = criteriaToSql(criteria, table, from)
+      const order = sortToSql(opts?.sort, table, from)
 
+      /** Counted separately, so `total` describes the whole match rather than the page. */
       const totals = await db.drizzle
-        .select({ total: sql<number>`count(*)::int` }).from(pgTable(from)).where(where)
+        .select({ total: sql<number>`count(*)::int` }).from(from).where(condition)
       const total = Number((totals[0] as { total: number } | undefined)?.total ?? 0)
-      pager.total = total
 
-      const skip = (pager.page ?? 0) * size
-      if (total === 0 || skip >= total) {
-        return { items: [], pager }
-      }
+      const marshal = (rows: unknown[]): R[] =>
+        rows.map(row => resultToRecord<R>(row as Record<string, unknown>, table))
 
-      const rows = await db.drizzle.select().from(pgTable(from)).where(where)
-        .orderBy(...sortToSql(pager.sort, table, from)).limit(size).offset(skip)
+      /** `size: 0` lifts the limit — the explicit, greppable way to read a whole table. */
+      const size = opts?.size ?? DEFAULT_PAGE_SIZE
+      if (size === 0) {
+        const all = total === 0
+          ? []
+          : await db.drizzle.select().from(from).where(condition).orderBy(...order)
 
-      return { pager, items: rows.map(row => resultToRecord(row as Record<string, unknown>, table)) }
-    },
+        return { items: marshal(all), total }
+      }
 
-    save: async (record, opts) => {
-      const field = fieldOf(opts)
-      const present = field != null
-        ? record[field as keyof typeof record] != null
-        : record.id != null
+      const page = opts?.page ?? 0
+      const skip = page * size
+      const rows = total === 0 || skip >= total
+        ? []
+        : await db.drizzle.select().from(from).where(condition).orderBy(...order)
+          .limit(size).offset(skip)
 
-      return present
-        ? resource.update(record, opts)
-        : resource.create(record, typeof opts !== 'string' ? opts : undefined)
+      return { items: marshal(rows), total, page, size }
     },
 
+    save: async (record, opts) => record.id != null
+      ? resource.update(record, opts)
+      : resource.create(record, opts),
+
     create: async (record, opts) => {
       if (ID_FIELD in record && record.id == null) {
         delete record.id
@@ -193,9 +193,7 @@ export const makePostgresResource = <
       if (record.id != null) {
         throw new RecordExists('id-present')
       }
-      if (opts?.ttl != null) {
-        throw new UnsupportedArgumentError('ttl')
-      }
+      refuseTtl(opts)
 
       return resource.insert(record)
     },
@@ -206,12 +204,12 @@ export const makePostgresResource = <
         { ...resource.getDefaults(), ...record } as Record<string, unknown>, table
       )
       try {
-        const rows = await db.drizzle.insert(pgTable(into)).values(values as never).returning()
+        const rows = await db.drizzle.insert(into).values(values as never).returning()
         if (rows.length < 1) {
           throw new RecordUpdateFailed('creation')
         }
 
-        return resultToRecord(rows[0] as Record<string, unknown>, table)
+        return resultToRecord<R>(rows[0] as Record<string, unknown>, table)
       } catch (error) {
         throw pgErrorToResourceError(error)
       }
@@ -240,47 +238,47 @@ export const makePostgresResource = <
       }
 
       try {
-        const rows = await db.drizzle.insert(pgTable(into)).values(values as never)
-          .onConflictDoUpdate({ target: target as never, set: set as never }).returning()
+        const rows = await db.drizzle.insert(into).values(values as never)
+          .onConflictDoUpdate({ target, set: set as never }).returning()
         if (rows.length < 1) {
           throw new RecordUpdateFailed('upsert')
         }
 
-        return resultToRecord(rows[0] as Record<string, unknown>, table)
+        return resultToRecord<R>(rows[0] as Record<string, unknown>, table)
       } catch (error) {
         throw pgErrorToResourceError(error)
       }
     },
 
     update: async (record, opts) => {
+      refuseTtl(opts)
       const { db, spec: table, entity: target } = await ensure()
-      const field = fieldOf(opts) ?? ID_FIELD
-      const key = record[field as keyof typeof record]
+      const key = record.id
       if (key == null) {
-        throw new MisshapedRecord(field === ID_FIELD ? ID_FIELD : 'no-field-value')
+        throw new MisshapedRecord(ID_FIELD)
       }
 
       /** Replace, not merge — the semantics mongo's `replaceOne` gives. `patch()` merges. */
       const values = recordToFullValues(record as Record<string, unknown>, table)
       try {
-        const rows = await db.drizzle.update(pgTable(target)).set(values as never)
-          .where(identify(table, field, key)).returning()
+        const rows = await db.drizzle.update(target).set(values as never)
+          .where(identify(table, target, ID_FIELD, key)).returning()
         if (rows.length < 1) {
-          throw new UnknownRecordError(`${field}:${key}`)
+          throw new UnknownRecordError(`${key}`)
         }
 
-        return resultToRecord(rows[0] as Record<string, unknown>, table)
+        return resultToRecord<R>(rows[0] as Record<string, unknown>, table)
       } catch (error) {
         throw pgErrorToResourceError(error)
       }
     },
 
     patch: async (record, opts) => {
+      refuseTtl(opts)
       const { db, spec: table, entity: target } = await ensure()
-      const field = (typeof opts === 'string' ? opts : opts?.field) ?? ID_FIELD
-      const key = record[field as keyof typeof record]
+      const key = record.id
       if (key == null) {
-        throw new MisshapedRecord(field === ID_FIELD ? ID_FIELD : 'no-field-value')
+        throw new MisshapedRecord(ID_FIELD)
       }
 
       const values = recordToValues(record as Record<string, unknown>, table)
@@ -288,41 +286,36 @@ export const makePostgresResource = <
         delete values[table.byColumn[column]?.property ?? column]
       }
       if (Object.keys(values).length < 1) {
-        return resource.get(`${key}`, field)
+        return resource.get(`${key}`)
       }
 
       try {
-        const rows = await db.drizzle.update(pgTable(target)).set(values as never)
-          .where(identify(table, field, key)).returning()
+        const rows = await db.drizzle.update(target).set(values as never)
+          .where(identify(table, target, ID_FIELD, key)).returning()
         if (rows.length < 1) {
-          throw new UnknownRecordError(`${field}:${key}`)
+          throw new UnknownRecordError(`${key}`)
         }
 
-        return resultToRecord(rows[0] as Record<string, unknown>, table)
+        return resultToRecord<R>(rows[0] as Record<string, unknown>, table)
       } catch (error) {
         throw pgErrorToResourceError(error)
       }
     },
 
-    delete: async (id, opts) => {
+    delete: async id => {
       const { db, spec: table, entity: from } = await ensure()
-      const field = fieldOf(opts) ?? ID_FIELD
-      const key = typeof id === 'object' ? id[field as keyof typeof id] : id
-      if (key == null) {
-        throw new MisshapedRecord(field === ID_FIELD ? ID_FIELD : 'no-field-value')
-      }
 
       /** One statement — mongo's read-then-delete can lose the record between the two. */
-      const rows = await db.drizzle.delete(pgTable(from))
-        .where(identify(table, field, key)).returning()
+      const rows = await db.drizzle.delete(from)
+        .where(identify(table, from, ID_FIELD, id)).returning()
 
-      return rows.length < 1 ? null : resultToRecord(rows[0] as Record<string, unknown>, table)
+      return rows.length < 1 ? null : resultToRecord<R>(rows[0] as Record<string, unknown>, table)
     },
 
-    pick: async (id, opts) => {
-      const record = await resource.delete(id, opts)
+    take: async id => {
+      const record = await resource.delete(id)
       if (record == null) {
-        throw new UnknownRecordError(typeof id === 'string' ? id : (id.id ?? 'unknown'))
+        throw new UnknownRecordError(id)
       }
 
       return record
@@ -330,25 +323,45 @@ export const makePostgresResource = <
 
     purge: async criteria => {
       const { db, spec: table, entity: from } = await ensure()
-      const where = criteriaToSql(criteria, table, from)
-      if (where == null) {
+      const condition = criteriaToSql(criteria, table, from)
+      if (condition == null) {
         /** An empty criteria object here would silently truncate the table. */
         throw new UnsupportedArgumentError('purge:no-criteria')
       }
-      const rows = await db.drizzle.delete(pgTable(from)).where(where).returning()
+      const rows = await db.drizzle.delete(from).where(condition).returning()
 
       return rows.length
     },
 
     count: async criteria => {
       const { db, spec: table, entity: from } = await ensure()
-      const options = prepareListOptions(DEFAULT_PAGE_SIZE, criteria)
       const rows = await db.drizzle.select({ total: sql<number>`count(*)::int` })
-        .from(pgTable(from)).where(criteriaToSql(options.criteria, table, from))
+        .from(from).where(criteriaToSql(criteria, table, from))
 
       return Number((rows[0] as { total: number } | undefined)?.total ?? 0)
     },
 
+    countBy: async (criteria, fields) => {
+      const { db, spec: table, entity: from } = await ensure()
+      if (fields.length < 1 || fields.some(field => field === 'count')) {
+        /** `count` names the answer's own tally; grouping by nothing is `count()`. */
+        throw new UnsupportedArgumentError(`count-by:${fields.join(',')}`)
+      }
+      const columns = fields.map(field => columnOf(table, field))
+      const selection: Record<string, SQL | PgRuntimeTable[string]> = Object.fromEntries(
+        columns.map(column => [column.property, from[column.property]])
+      )
+      const rows = await db.drizzle
+        .select({ ...selection, count: sql<number>`count(*)::int` } as never)
+        .from(from).where(criteriaToSql(criteria, table, from))
+        .groupBy(...columns.map(column => from[column.property]))
+
+      return (rows as Array<Record<string, unknown>>).map(row => {
+        const { count, ...group } = row
+        return { ...resultToRecord<Record<string, unknown>>(group, table), count: Number(count ?? 0) }
+      })
+    },
+
     getDefaults: () => {
       const schema = resource.schema as JSONSchemaType<unknown> | undefined
       if (schema == null) {
@@ -366,9 +379,9 @@ export const makePostgresResource = <
         }, {}) as Partial<R>
     },
 
-    query: async (text, params) => (await raw(text, params)).rows,
+    query: (async (text: string, params?: unknown[]) => (await raw(text, params)).rows) as T['query'],
 
-    queryOne: async (text, params) => (await raw(text, params)).rows[0] ?? null,
+    queryOne: (async (text: string, params?: unknown[]) => (await raw(text, params)).rows[0] ?? null) as T['queryOne'],
 
     execute: async (text, params) => (await raw(text, params)).count,
 
@@ -376,14 +389,14 @@ export const makePostgresResource = <
       const { spec: table } = await ensure()
       const result = await raw(text, params)
 
-      return result.rows.map(row => rowToRecord(row, table))
+      return result.rows.map(row => rowToRecord<R>(row, table))
     },
 
     selectOne: async (text, params) => {
       const { spec: table } = await ensure()
       const result = await raw(text, params)
 
-      return result.rows.length < 1 ? null : rowToRecord(result.rows[0], table)
+      return result.rows.length < 1 ? null : rowToRecord<R>(result.rows[0], table)
     },
 
     ref: resourceAlias => {
@@ -444,13 +457,14 @@ export const makePostgresResource = <
       return postgres.client(dbAlias)
     },
 
-    index: <Type extends PostgresResource<R>>(name: string, index: PgIndexSpec) => {
+    /** Chainable — the declaration store is keyed by alias, so this object is the whole state. */
+    index: (name: string, index: PgIndexSpec) => {
       declaration.indexes.push({ ...index, name })
 
-      return resource as unknown as Type
+      return resource
     },
 
-    /** `this`-returning in the interface — the implementation returns that very object. */
+    /** Self-returning in the interface — the implementation returns that very object. */
     migration: ((name: string, apply: (tx: PostgresTx) => Promise<void>, stage?: MigrationStage) => {
       declaration.migrations.register(name, apply, stage)
 
@@ -458,12 +472,14 @@ export const makePostgresResource = <
     }) as T['migration'],
 
     migrations: () => declaration.migrations
-  } as Partial<T>)
+  }
+
+  const resource: T = appendContextual<T>(alias, members as Partial<T>)
 
   /**
-   * The AJV schema is stored per alias rather than on the object, so it survives
-   * `reinitializeContext` — which rebuilds the resource and would otherwise drop a schema
-   * the app assigned after construction, silently taking the table's structure with it.
+   * The AJV schema is stored per alias rather than on the object, so a second maker run for
+   * the same alias (a custom maker, a repeated maker, a spec) picks up the schema the app
+   * assigned after construction instead of silently taking the table's structure with it.
    */
   Object.defineProperty(resource, 'schema', {
     enumerable: true,
@@ -483,8 +499,7 @@ export const makePostgresResource = <
 
   /**
    * Explicit table name override, decoupled from the registration alias — an alias may
-   * carry characters no identifier allows. Threaded back through the recursive maker call
-   * below so it survives a context switch.
+   * carry characters no identifier allows.
    */
   if (tableName != null) {
     resource.name = tableName
@@ -505,16 +520,5 @@ export const makePostgresResource = <
     entity = initialized.entity
   }
 
-  resource.reinitializeContext = <Type extends Contextual>(context: BasicContext<Config>) => {
-    const replacement = (makeCustomResource?.(dbAlias, serviceAlias)
-      ?? makePostgresResource<R, T>(
-        alias, dbAlias, serviceAlias, makeCustomResource, tableName
-      )) as unknown as Type
-
-    replacement.ctx = context
-
-    return replacement
-  }
-
   return resource
 }

package/src/types.ts

@@ -1,10 +1,11 @@
 import type {
-  DbLocker, ListCriteria, ListOptions, MigratableResource, Resource,
-  ResourceDbService, ResourceLocker, ResourceRecord
+  Criteria, DbLocker, LockableResource, MigratableResource, Resource,
+  ResourceDbService, ResourceRecord, WriteOptions
 } from '@owlmeans/resource'
 import type { AnySchema } from 'ajv'
 import type { Pool, PoolClient, QueryResultRow } from 'pg'
 import type { NodePgDatabase } from 'drizzle-orm/node-postgres'
+import type { PgColumn, PgTable } from 'drizzle-orm/pg-core'
 
 import type { PgAutoSync, PgIndexMethod, PgReferentialAction } from './consts.js'
 
@@ -17,9 +18,9 @@ export interface PostgresDb {
   /** Drizzle bound to this config alias' pool. */
   drizzle: NodePgDatabase<Record<string, never>>
   pool: Pool
-  /** The Postgres SCHEMA — i.e. `service.name(alias)`, layer suffixed. */
+  /** The Postgres SCHEMA this config alias' resources live in — i.e. `service.name(alias)`. */
   schema: string
-  /** The Postgres DATABASE — i.e. `config.meta.database`. Never layer suffixed. */
+  /** The Postgres DATABASE the pool is connected to — i.e. `config.meta.database`. */
   database: string
 }
 
@@ -72,7 +73,16 @@ export interface PostgresTx {
   ref: (resourceAlias?: string) => string
 }
 
-export interface PostgresResource<T extends ResourceRecord> extends Resource<T>, ResourceLocker<T>, MigratableResource<PostgresTx> {
+/**
+ * A `Resource<T>` over one Postgres table.
+ *
+ * Every method beyond the base contract exists because a table has structure a document
+ * store does not: identity supplied by the caller, conflict arbiters, partial writes, and
+ * SQL that no criteria object can express. Type the resource once —
+ * `context.resource<PostgresResource<Project>>(alias)` — rather than per call.
+ */
+export interface PostgresResource<T extends ResourceRecord>
+  extends Resource<T>, LockableResource<T>, MigratableResource<PostgresTx, PostgresResource<T>> {
   /** Physical table name override. Defaults to the resource alias, sanitized. */
   name?: string
   /** The AJV schema — single source of truth for the table structure. */
@@ -86,7 +96,7 @@ export interface PostgresResource<T extends ResourceRecord> extends Resource<T>,
   client: () => Promise<Pool>
 
   /** Declare an index the JSON schema can't express. Chainable. */
-  index: <Type extends PostgresResource<T>>(name: string, spec: PgIndexSpec) => Type
+  index: (name: string, spec: PgIndexSpec) => PostgresResource<T>
 
   getDefaults: () => Partial<T>
 
@@ -96,22 +106,26 @@ export interface PostgresResource<T extends ResourceRecord> extends Resource<T>,
   /** Returns the affected row count. */
   execute: (text: string, params?: unknown[]) => Promise<number>
   /** Rows marshalled back into `T` through the table spec. */
-  select: <Type extends T>(text: string, params?: unknown[]) => Promise<Type[]>
-  selectOne: <Type extends T>(text: string, params?: unknown[]) => Promise<Type | null>
+  select: (text: string, params?: unknown[]) => Promise<T[]>
+  selectOne: (text: string, params?: unknown[]) => Promise<T | null>
   /** Fully qualified `"schema"."table"`; pass an alias to reference another resource. */
   ref: (resourceAlias?: string) => string
 
   transaction: <R>(fn: (tx: PostgresTx) => Promise<R>) => Promise<R>
 
   /** Create with a caller supplied id — `create()` refuses one, mirroring mongo. */
-  insert: <Type extends T>(record: Partial<Type>) => Promise<Type>
+  insert: (record: Partial<T>) => Promise<T>
   /** `INSERT ... ON CONFLICT (...) DO UPDATE`. Defaults to conflicting on the primary key. */
-  upsert: <Type extends T>(record: Partial<Type>, conflict?: string[]) => Promise<Type>
+  upsert: (record: Partial<T>, conflict?: string[]) => Promise<T>
   /** Merge semantics — `update()` replaces the whole record, mirroring mongo's `replaceOne`. */
-  patch: <Type extends T>(record: Partial<Type>, opts?: string | { field?: string }) => Promise<Type>
-  /** Bulk delete by criteria. Returns the deleted row count. */
-  purge: (criteria: ListCriteria) => Promise<number>
-  count: (criteria?: ListCriteria | ListOptions) => Promise<number>
+  patch: (record: Partial<T>, opts?: WriteOptions) => Promise<T>
+  /**
+   * `count(*)` of the rows matching `criteria`, per distinct combination of `fields` — one
+   * `GROUP BY` round trip. Each answer carries the group's values (by property name) and `count`.
+   */
+  countBy: (
+    criteria: Criteria<T> | undefined, fields: Array<keyof T & string>
+  ) => Promise<Array<Record<string, unknown> & { count: number }>>
 }
 
 /** Compiled, database ready description of a resource's table. */
@@ -245,11 +259,15 @@ export interface PgReferenceSpec {
 }
 
 /**
- * The Drizzle table object. Deliberately opaque — tables are built at runtime from JSON
- * schemas, so Drizzle's compile time inference has nothing to infer from and every
- * column would be `any` anyway. Cast it at the call site when you need the typed builder.
+ * The Drizzle table `specToTable` compiles from a {@link TableSpec}.
+ *
+ * Both halves are load bearing. `PgTable` is what the query builder accepts and what keeps
+ * the rows it hands back usable — erasing it to `never` would collapse every result row.
+ * The index signature is how a column is reached: the columns are keyed by schema property
+ * name and only known at runtime, so `eq(entity[column.property], value)` is a plain lookup
+ * rather than a cast.
  */
-export type PgRuntimeTable = Record<string, any>
+export type PgRuntimeTable = PgTable & Record<string, PgColumn>
 
 /** One column as Postgres currently reports it. */
 export interface LiveColumn {