@zeroxsolutions/db 9.5.0 → 10.0.0

package/dist/utils/filter.d.ts

@@ -1,18 +1,15 @@
 import type { Column, SQL } from 'drizzle-orm';
-import type { FilterableOf, FilterTree, FilterTreeGroup, SortField } from '@zeroxsolutions/query';
-import type { TableConfig as PgTableConfig } from 'drizzle-orm/pg-core';
-import { PgTable } from 'drizzle-orm/pg-core';
-import type { SQLiteTable, TableConfig as SQLiteTableConfig } from 'drizzle-orm/sqlite-core';
+import type { FilterTree, FilterTreeGroup } from '@zeroxsolutions/query';
 import { z } from 'zod';
 /** The 15 comparison operators a filter clause may use; `filterOperatorSchema.enum.<op>` names one. */
 export declare const filterOperatorSchema: z.ZodEnum<{
-    endsWith: "endsWith";
-    startsWith: "startsWith";
     equals: "equals";
     notEquals: "notEquals";
     in: "in";
     notIn: "notIn";
     contains: "contains";
+    startsWith: "startsWith";
+    endsWith: "endsWith";
     gt: "gt";
     gte: "gte";
     lt: "lt";
@@ -26,11 +23,11 @@ export declare const filterOperatorSchema: z.ZodEnum<{
 export declare const filterValueSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     field: z.ZodString;
     operator: z.ZodEnum<{
-        endsWith: "endsWith";
-        startsWith: "startsWith";
         equals: "equals";
         notEquals: "notEquals";
         contains: "contains";
+        startsWith: "startsWith";
+        endsWith: "endsWith";
         gt: "gt";
         gte: "gte";
         lt: "lt";
@@ -79,70 +76,52 @@ export type FilterOperator = z.infer<typeof filterOperatorSchema>;
 /** A parsed filter clause, inferred from {@link filterValueSchema}. */
 export type FilterValue = z.infer<typeof filterValueSchema>;
 /**
- * The `filter`/`sort` fields a listable entity permits, keyed to its row (`$inferSelect`) type so a
- * renamed or removed column fails typecheck at the whitelist instead of silently going stale.
- */
-export interface QueryableFields<TSelect> {
-    filterable: readonly (keyof TSelect & string)[];
-    sortable: readonly (keyof TSelect & string)[];
-}
-/** Any table this toolkit builds conditions against. */
-export type FilterableTable = PgTable<PgTableConfig> | SQLiteTable<SQLiteTableConfig>;
-/**
- * A `filter` or `sort` named a field the table does not hold. Raised rather than skipped: skipping a
- * condition widens the result and skipping a sort reorders it, both answering a question nobody asked.
+ * A `filter` or an `orderBy` named a field the table does not hold. Raised rather than skipped: skipping a condition
+ * widens the result and skipping an order reorders it, both answering a question nobody asked.
  */
 export declare class UnknownQueryField extends Error {
     constructor(field: string);
 }
-/** An expression for one published path no column holds. `undefined` contributes no condition, like an empty `in`. */
-export type FilterResolver = (leaf: FilterValue) => SQL | undefined;
-/**
- * One resolver for each filter path the permit list `P` grants that is not a column of the table, and none for any
- * other name: a path permitted without an expression, or an expression for a path nobody permits, fails to compile.
- */
-export type FilterResolvers<TTable extends FilterableTable, P> = {
-    readonly [F in Exclude<keyof FilterableOf<P> & string, keyof TTable['_']['columns'] & string>]: FilterResolver;
-};
+/** What a `virtual` name is decided against: the instant the finder was handed. */
+export interface VirtualContext {
+    at: Date;
+}
 /**
- * The resolver for a relationship filter: the relationship's name is no column, and the id it compares is held in its
- * foreign-key column. `{ region: columnResolver(places.regionId) }` declares one.
- *
- * @throws Error on an operator other than `equals` and `in`, the only two a relationship filter grants
+ * A filter or an order name no column holds, as `READS` declares it: the expression a condition on it becomes, and the
+ * expression it orders by. A `filter` answering `undefined` contributes no condition, like an empty `in`.
  */
-export declare function columnResolver(column: Column): FilterResolver;
-/** What a filter may reach: the table to resolve fields against, the tree to build, and the paths no column holds. */
-export interface FilterQuery<TTable extends FilterableTable = FilterableTable> {
-    table: TTable;
-    filter?: FilterNode[] | undefined;
-    resolvers?: Readonly<Record<string, FilterResolver>> | undefined;
+export interface VirtualField {
+    filter?: (condition: FilterValue, context: VirtualContext) => SQL | undefined;
+    order?: (context: VirtualContext) => SQL | Column;
+}
+/** What resolving a field needs: the table's columns, its relations to one row by their key, and its `virtual` names. */
+export interface FieldContext {
+    columns: Readonly<Record<string, Column>>;
+    /** Each relation to one row, keyed by its name, mapped to the one column holding the related row's key. */
+    relationKeys: Readonly<Record<string, Column>>;
+    virtual: Readonly<Record<string, VirtualField>>;
+    at: Date;
+    /** Postgres matches text case-insensitively with `ILIKE`; SQLite has no `ILIKE`, and its `LIKE` already is. */
+    caseInsensitiveOperator: boolean;
 }
 /**
- * Builds one SQL condition from a filter tree. Nodes at the root join conjunctively; a group joins
- * its children by its own conjunction.
+ * One SQL condition from a filter tree. Nodes at the root join conjunctively; a group joins its children by its own
+ * conjunction. A field resolves to a `virtual` name first, then to a relation to one row, then to a column.
  *
- * @returns `undefined` when the tree contributes no condition - an absent or empty `filter`, an
- *   empty group, or an `in`/`notIn` over an empty array. A caller passes that straight to `.where()`.
- * @throws {@link UnknownQueryField} when a clause names a column the table does not hold
- * @example
- * ```ts
- * buildFilterConditions({ table: assessments, ...parsedQuery });
- * ```
+ * @returns `undefined` when the tree contributes no condition - an absent or empty `filter`, an empty group, or an
+ *   `in`/`notIn` over an empty array
+ * @throws {@link UnknownQueryField} when a clause names a field nothing resolves
  */
-export declare function buildFilterConditions<TTable extends FilterableTable>({ table, filter, resolvers, }: FilterQuery<TTable>): SQL | undefined;
+export declare function whereOf(context: FieldContext, filter: readonly FilterNode[] | undefined): SQL | undefined;
 /**
- * Builds the `order by` clauses for a parsed sort, in the order the clauses were given.
+ * The `order by` clauses for an order, followed by each primary key column it does not name, ascending: rows that tie
+ * on the requested order have none of their own, and two pages cut from two orders of the same rows repeat one and
+ * skip another. A field resolves to a `virtual` name first, then to a column.
  *
- * @param options.resolvers - an expression per sort path no column holds, tried before a column
- * @returns an empty array for an absent or empty `sort`, which orders nothing
- * @throws {@link UnknownQueryField} when a clause names a column the table does not hold and no
- *   resolver answers it
- * @example
- * ```ts
- * const orderClauses = buildOrderBy(users, [{ field: 'createdAt', direction: 'desc' }]);
- * ```
+ * @throws {@link UnknownQueryField} when an entry names a field nothing resolves
  */
-export declare function buildOrderBy<TTable extends PgTable<PgTableConfig> | SQLiteTable<SQLiteTableConfig>>(table: TTable, sort: SortField[] | undefined, options?: {
-    resolvers?: Readonly<Record<string, () => SQL | Column>>;
-}): SQL[];
+export declare function orderOf(context: FieldContext, orderBy: readonly {
+    field: string;
+    direction: 'asc' | 'desc';
+}[] | undefined, primaryKey: readonly string[]): SQL[];
 //# sourceMappingURL=filter.d.ts.map

package/dist/utils/filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/utils/filter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/utils/filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAmB/C,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,uGAAuG;AACvG,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;EAgB/B,CAAC;AAIH,iHAAiH;AACjH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAiC5B,CAAC;AAEH,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;AAEvD,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;AAEjD,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAKnD,CAAC;AAEH,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAmD,CAAC;AAEvG,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,IAAI,WAAW,CAEnE;AAED,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAW5D;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,KAAK,EAAE,MAAM;CAG1B;AAED,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,IAAI,CAAC;CACV;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,KAAK,GAAG,GAAG,SAAS,CAAC;IAC9E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,GAAG,GAAG,MAAM,CAAC;CACnD;AAED,yHAAyH;AACzH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1C,2GAA2G;IAC3G,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAChD,EAAE,EAAE,IAAI,CAAC;IACT,+GAA+G;IAC/G,uBAAuB,EAAE,OAAO,CAAC;CAClC;AA+FD;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,SAAS,GAAG,GAAG,GAAG,SAAS,CAIzG;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;CAAE,EAAE,GAAG,SAAS,EAC5E,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,GAAG,EAAE,CAeP"}

package/dist/utils/filter.js

@@ -1,5 +1,4 @@
-import { and, asc, desc, eq, getTableColumns, gt, gte, inArray, is, isNotNull, isNull, lt, lte, ne, notBetween, notInArray, or, sql } from 'drizzle-orm';
-import { PgTable } from 'drizzle-orm/pg-core';
+import { and, asc, desc, eq, gt, gte, inArray, isNotNull, isNull, lt, lte, ne, notBetween, notInArray, or, sql, } from 'drizzle-orm';
 import { z } from 'zod';
 /** The 15 comparison operators a filter clause may use; `filterOperatorSchema.enum.<op>` names one. */
 export const filterOperatorSchema = z.enum([
@@ -62,10 +61,7 @@ export const filterGroupSchema = z.object({
     },
 });
 /** A filter tree node: {@link filterValueSchema} or {@link filterGroupSchema}. */
-export const filterNodeSchema = z.union([
-    filterValueSchema,
-    filterGroupSchema,
-]);
+export const filterNodeSchema = z.union([filterValueSchema, filterGroupSchema]);
 /** Whether a node joins children rather than comparing a field. */
 export function isFilterGroup(node) {
     return 'conjunction' in node;
@@ -80,29 +76,14 @@ function coerceForColumn(column, value) {
     return value;
 }
 /**
- * A `filter` or `sort` named a field the table does not hold. Raised rather than skipped: skipping a
- * condition widens the result and skipping a sort reorders it, both answering a question nobody asked.
+ * A `filter` or an `orderBy` named a field the table does not hold. Raised rather than skipped: skipping a condition
+ * widens the result and skipping an order reorders it, both answering a question nobody asked.
  */
 export class UnknownQueryField extends Error {
     constructor(field) {
         super(`No column resolves the field "${field}".`);
     }
 }
-/**
- * The resolver for a relationship filter: the relationship's name is no column, and the id it compares is held in its
- * foreign-key column. `{ region: columnResolver(places.regionId) }` declares one.
- *
- * @throws Error on an operator other than `equals` and `in`, the only two a relationship filter grants
- */
-export function columnResolver(column) {
-    return (leaf) => {
-        if (leaf.operator === 'equals')
-            return eq(column, leaf.value);
-        if (leaf.operator === 'in')
-            return leaf.value.length > 0 ? inArray(column, leaf.value) : undefined;
-        throw new Error(`A relationship filter answers equals and in, not "${leaf.operator}".`);
-    };
-}
 /**
  * The character that makes the next one literal. It is its own escape, so the character class below
  * must list it first: escaping `%` before `\` would re-escape the backslash the first pass added.
@@ -111,24 +92,33 @@ const LIKE_ESCAPE = '\\';
 function escapeLikePattern(value) {
     return value.replace(/[\\%_]/g, (character) => `${LIKE_ESCAPE}${character}`);
 }
-/**
- * Case-insensitive text match on either dialect. Postgres `LIKE` is case-sensitive and needs `ILIKE`;
- * SQLite has no `ILIKE` at all and its `LIKE` is already case-insensitive for ASCII, so emitting one
- * operator for both made these three operators a syntax error on D1.
- */
 function textMatch(context, column, pattern) {
     return context.caseInsensitiveOperator
         ? sql `${column} ilike ${pattern} escape '\\'`
         : sql `${column} like ${pattern} escape '\\'`;
 }
+/** A relationship filter compares the related row's id, which the relation's key column holds. */
+function relationCondition(column, filter) {
+    if (filter.operator === 'equals')
+        return eq(column, filter.value);
+    if (filter.operator === 'in')
+        return filter.value.length > 0 ? inArray(column, filter.value) : undefined;
+    throw new Error(`A relationship filter answers equals and in, not "${filter.operator}".`);
+}
 function buildCondition(context, filter) {
-    // Parenthesized because a resolver may return a bare `a or b`, and `and()` joins its operands without
-    // grouping them: beside a sibling or a soft-delete scope it would read `a or (b and deleted_at is null)`.
-    if (Object.hasOwn(context.resolvers, filter.field)) {
-        const expression = context.resolvers[filter.field]?.(filter);
+    // Own keys only: the field is client-written, and `constructor` would otherwise answer from Object.prototype.
+    const virtual = Object.hasOwn(context.virtual, filter.field) ? context.virtual[filter.field] : undefined;
+    if (virtual?.filter) {
+        // Parenthesized because the expression may be a bare `a or b`, and `and()` joins its operands without grouping
+        // them: beside a sibling or the soft-delete condition it would read `a or (b and deleted_at is null)`.
+        const expression = virtual.filter(filter, { at: context.at });
         return expression === undefined ? undefined : sql `(${expression})`;
     }
-    // Own keys only: the field is client-written, and `constructor` would otherwise answer from Object.prototype.
+    const relationKey = Object.hasOwn(context.relationKeys, filter.field)
+        ? context.relationKeys[filter.field]
+        : undefined;
+    if (relationKey)
+        return relationCondition(relationKey, filter);
     const column = Object.hasOwn(context.columns, filter.field) ? context.columns[filter.field] : undefined;
     if (!column)
         throw new UnknownQueryField(filter.field);
@@ -156,12 +146,8 @@ function buildCondition(context, filter) {
         case 'lte':
             return lte(column, coerceForColumn(column, filter.value));
         case 'between': {
-            const from = filter.value.from !== undefined
-                ? gte(column, coerceForColumn(column, filter.value.from))
-                : undefined;
-            const to = filter.value.to !== undefined
-                ? lte(column, coerceForColumn(column, filter.value.to))
-                : undefined;
+            const from = filter.value.from !== undefined ? gte(column, coerceForColumn(column, filter.value.from)) : undefined;
+            const to = filter.value.to !== undefined ? lte(column, coerceForColumn(column, filter.value.to)) : undefined;
             return from && to ? and(from, to) : (from ?? to);
         }
         case 'notBetween':
@@ -175,9 +161,7 @@ function buildCondition(context, filter) {
 function buildNodes(context, nodes) {
     const conditions = [];
     for (const node of nodes) {
-        const condition = isFilterGroup(node)
-            ? buildGroup(context, node)
-            : buildCondition(context, node);
+        const condition = isFilterGroup(node) ? buildGroup(context, node) : buildCondition(context, node);
         if (condition)
             conditions.push(condition);
     }
@@ -190,57 +174,39 @@ function buildGroup(context, group) {
     return group.conjunction === 'or' ? or(...children) : and(...children);
 }
 /**
- * Builds one SQL condition from a filter tree. Nodes at the root join conjunctively; a group joins
- * its children by its own conjunction.
+ * One SQL condition from a filter tree. Nodes at the root join conjunctively; a group joins its children by its own
+ * conjunction. A field resolves to a `virtual` name first, then to a relation to one row, then to a column.
  *
- * @returns `undefined` when the tree contributes no condition - an absent or empty `filter`, an
- *   empty group, or an `in`/`notIn` over an empty array. A caller passes that straight to `.where()`.
- * @throws {@link UnknownQueryField} when a clause names a column the table does not hold
- * @example
- * ```ts
- * buildFilterConditions({ table: assessments, ...parsedQuery });
- * ```
+ * @returns `undefined` when the tree contributes no condition - an absent or empty `filter`, an empty group, or an
+ *   `in`/`notIn` over an empty array
+ * @throws {@link UnknownQueryField} when a clause names a field nothing resolves
  */
-export function buildFilterConditions({ table, filter, resolvers, }) {
+export function whereOf(context, filter) {
     if (!filter || filter.length === 0)
         return undefined;
-    const conditions = buildNodes({
-        columns: getTableColumns(table),
-        caseInsensitiveOperator: is(table, PgTable),
-        resolvers: resolvers ?? {},
-    }, filter);
+    const conditions = buildNodes(context, filter);
     return conditions.length > 0 ? and(...conditions) : undefined;
 }
 /**
- * Builds the `order by` clauses for a parsed sort, in the order the clauses were given.
+ * The `order by` clauses for an order, followed by each primary key column it does not name, ascending: rows that tie
+ * on the requested order have none of their own, and two pages cut from two orders of the same rows repeat one and
+ * skip another. A field resolves to a `virtual` name first, then to a column.
  *
- * @param options.resolvers - an expression per sort path no column holds, tried before a column
- * @returns an empty array for an absent or empty `sort`, which orders nothing
- * @throws {@link UnknownQueryField} when a clause names a column the table does not hold and no
- *   resolver answers it
- * @example
- * ```ts
- * const orderClauses = buildOrderBy(users, [{ field: 'createdAt', direction: 'desc' }]);
- * ```
+ * @throws {@link UnknownQueryField} when an entry names a field nothing resolves
  */
-export function buildOrderBy(table, sort, options = {}) {
-    if (!sort || sort.length === 0)
-        return [];
-    const columns = getTableColumns(table);
-    const clauses = [];
-    for (const item of sort) {
-        const resolvers = options.resolvers ?? {};
-        const expression = Object.hasOwn(resolvers, item.field)
-            ? resolvers[item.field]?.()
-            : Object.hasOwn(columns, item.field)
-                ? columns[item.field]
-                : undefined;
+export function orderOf(context, orderBy, primaryKey) {
+    const requested = orderBy ?? [];
+    const named = new Set(requested.map((entry) => entry.field));
+    const entries = [
+        ...requested,
+        ...primaryKey.filter((key) => !named.has(key)).map((key) => ({ field: key, direction: 'asc' })),
+    ];
+    return entries.map((entry) => {
+        const virtual = Object.hasOwn(context.virtual, entry.field) ? context.virtual[entry.field] : undefined;
+        const expression = virtual?.order?.({ at: context.at }) ??
+            (Object.hasOwn(context.columns, entry.field) ? context.columns[entry.field] : undefined);
         if (!expression)
-            throw new UnknownQueryField(item.field);
-        if (item.direction === 'desc')
-            clauses.push(desc(expression));
-        else
-            clauses.push(asc(expression));
-    }
-    return clauses;
+            throw new UnknownQueryField(entry.field);
+        return entry.direction === 'desc' ? desc(expression) : asc(expression);
+    });
 }

package/dist/utils/index.d.ts

@@ -1,8 +1,6 @@
-export * from './assert-queryable-fields.js';
-export * from './constants.js';
-export * from './filter.js';
-export * from './include.js';
+export { filterGroupSchema, filterNodeSchema, filterOperatorSchema, filterValueSchema, isFilterGroup, UnknownQueryField, type FilterGroup, type FilterNode, type FilterOperator, type FilterValue, type VirtualContext, type VirtualField, } from './filter.js';
 export * from './omit.js';
+export { UnknownReadName, type ColumnName, type MatchOptions, type OrderEntry, type Read, type RelationRead, } from './read.js';
+export * from './reads.js';
 export * from './relationships.js';
-export * from './table-query.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AACrB,cAAc,WAAW,CAAC;AAC1B,OAAO,EACL,eAAe,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,YAAY,GAClB,MAAM,WAAW,CAAC;AACnB,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}

package/dist/utils/index.js

@@ -1,7 +1,5 @@
-export * from './assert-queryable-fields.js';
-export * from './constants.js';
-export * from './filter.js';
-export * from './include.js';
+export { filterGroupSchema, filterNodeSchema, filterOperatorSchema, filterValueSchema, isFilterGroup, UnknownQueryField, } from './filter.js';
 export * from './omit.js';
+export { UnknownReadName, } from './read.js';
+export * from './reads.js';
 export * from './relationships.js';
-export * from './table-query.js';

package/dist/utils/read.d.ts

@@ -0,0 +1,86 @@
+import { type Column, type ExtractTablesWithRelations, type Relation, type SQL, type TablesRelationalConfig } from 'drizzle-orm';
+import type { FilterNode } from './filter.js';
+/** The tables-with-relations view a drizzle schema expands into. */
+type RelationalSchema<TSchema extends Record<string, unknown>> = ExtractTablesWithRelations<TSchema>;
+/**
+ * A column name of `TTableName`, offered by the editor and checked by the finder: any other string still compiles,
+ * because a read built from a client's query names its columns at run time, and the finder refuses one the table does
+ * not hold.
+ */
+export type ColumnName<TSchema extends Record<string, unknown>, TTableName extends keyof RelationalSchema<TSchema>> = (keyof RelationalSchema<TSchema>[TTableName]['columns'] & string) | (string & {});
+/** One order: a field, which a column or a `virtual` name of `READS` answers, and its direction. */
+export interface OrderEntry<TField extends string = string> {
+    field: TField;
+    direction: 'asc' | 'desc';
+}
+/**
+ * What one level of a read loads.
+ *
+ * - `columns` absent loads every column. On the root table, given columns load with its primary key beside them; on a
+ *   relation, exactly the given columns load.
+ * - `relations` names each relation to load, under its own read. A relation not named does not load.
+ */
+export interface Read<TColumn extends string = string> {
+    columns?: readonly TColumn[];
+    relations?: Readonly<Record<string, RelationRead>>;
+}
+/**
+ * A relation's read: its columns and relations, the order its rows load in where it holds many, and whether its
+ * soft-deleted rows load too. The order defaults to the one `READS` declares for its table, and its marked rows to
+ * left out.
+ */
+export interface RelationRead extends Read {
+    orderBy?: readonly OrderEntry[];
+    softDeleted?: boolean;
+}
+/** The finder options that change which rows match, which is all a count reads. */
+export interface MatchOptions {
+    /** The condition tree a row must match. Root nodes join by `and`. */
+    filter?: readonly FilterNode[];
+    /** Whether marked rows of the root table match. */
+    softDeleted?: boolean;
+    /** The instant a `virtual` name of `READS` is decided at; the moment of the call where absent. */
+    at?: Date;
+}
+/** A read naming a column or a relation its table does not hold. */
+export declare class UnknownReadName extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+/** One table as drizzle's relational config holds it. */
+type TableConfig = TablesRelationalConfig[string];
+/** The relational config `drizzle({ schema })` computed, and the map from a table's unique name to its export name. */
+export interface RelationalMetadata {
+    tables: TablesRelationalConfig;
+    tableNamesMap: Record<string, string>;
+}
+/** The order a table's rows load in as a relation, keyed by the table's export name. */
+export type RelationOrders = Readonly<Record<string, readonly OrderEntry[] | undefined>>;
+/** One level of drizzle's relational config, as a finder hands it to `findFirst` / `findMany`. */
+export interface RelationalConfig {
+    columns?: Record<string, true>;
+    with?: Record<string, RelationalConfig>;
+    where?: (fields: Record<string, Column>) => SQL | undefined;
+    orderBy?: (fields: Record<string, Column>) => SQL[];
+}
+/** The property keys of a table's primary key columns, in the order its relational config lists them. */
+export declare function primaryKeyOf(table: TableConfig): string[];
+/** The export name of the table a relation reaches, which is how the relational config keys it. */
+export declare function targetOf(metadata: RelationalMetadata, relation: Relation): string;
+/**
+ * A read resolved into drizzle's relational config for the table exported as `rootKey`: the root's columns with its
+ * primary key, and each relation under its own read, its marked rows left out unless it asks for them and, where it
+ * holds many, in its order.
+ *
+ * @throws {@link UnknownReadName} on a column or a relation the table it names does not hold
+ */
+export declare function relationalConfig(metadata: RelationalMetadata, orders: RelationOrders, rootKey: string, read: Read | undefined): Pick<RelationalConfig, 'columns' | 'with'>;
+/**
+ * The columns a read of a table with no relational config selects: those it names with the primary key beside them,
+ * or every column.
+ *
+ * @throws {@link UnknownReadName} on a column the table does not hold, and on any relation, which needs the config
+ */
+export declare function plainColumns<TSelectable extends Record<string, unknown>>(selectable: TSelectable, primaryKey: readonly string[], read: Read | undefined, name: string): TSelectable;
+export {};
+//# sourceMappingURL=read.d.ts.map

package/dist/utils/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/utils/read.ts"],"names":[],"mappings":"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"}

package/dist/utils/read.js

@@ -0,0 +1,124 @@
+import { asc, desc, getTableUniqueName, isNull, One, is, } from 'drizzle-orm';
+/** A read naming a column or a relation its table does not hold. */
+export class UnknownReadName extends Error {
+    path;
+    constructor(path) {
+        super(`No column or relation answers "${path}".`);
+        this.path = path;
+    }
+}
+/** The property keys of a table's primary key columns, in the order its relational config lists them. */
+export function primaryKeyOf(table) {
+    const names = new Set(table.primaryKey.map((column) => column.name));
+    return Object.keys(table.columns).filter((key) => names.has(table.columns[key]?.name ?? ''));
+}
+/** The export name of the table a relation reaches, which is how the relational config keys it. */
+export function targetOf(metadata, relation) {
+    const unique = getTableUniqueName(relation.referencedTable);
+    return metadata.tableNamesMap[unique] ?? relation.referencedTableName;
+}
+const selecting = (keys) => Object.fromEntries(keys.map((key) => [key, true]));
+/** The table at `key`, or the refusal naming the path that reached it. */
+function tableAt(metadata, key, path) {
+    const table = Object.hasOwn(metadata.tables, key) ? metadata.tables[key] : undefined;
+    if (!table)
+        throw new UnknownReadName(path);
+    return table;
+}
+/** Refuses a column the table does not hold, reading own keys only: the name may have come from a client. */
+function assertColumns(table, columns, path) {
+    for (const name of columns) {
+        if (!Object.hasOwn(table.columns, name))
+            throw new UnknownReadName(`${path}.${name}`);
+    }
+}
+/**
+ * The order entries of a relation that holds many, its own or the one `READS` declares for its table, with each primary
+ * key column it does not name appended, so two reads of one row load the set in one order.
+ */
+function relationOrder(table, entries, path) {
+    const requested = entries ?? [];
+    for (const entry of requested) {
+        if (!Object.hasOwn(table.columns, entry.field))
+            throw new UnknownReadName(`${path}.${entry.field}`);
+    }
+    const named = new Set(requested.map((entry) => entry.field));
+    const appended = primaryKeyOf(table)
+        .filter((key) => !named.has(key))
+        .map((key) => ({ field: key, direction: 'asc' }));
+    const all = [...requested, ...appended];
+    return (fields) => all.map((entry) => entry.direction === 'desc' ? desc(fields[entry.field]) : asc(fields[entry.field]));
+}
+/** A relation's level of the relational config, walked from its own read. */
+function relationLevel(metadata, orders, relation, read, path) {
+    const key = targetOf(metadata, relation);
+    const table = tableAt(metadata, key, path);
+    if (read.columns !== undefined)
+        assertColumns(table, read.columns, path);
+    if (read.columns !== undefined && read.columns.length === 0 && !read.relations)
+        return undefined;
+    const level = {};
+    if (read.columns !== undefined && read.columns.length > 0)
+        level.columns = selecting(read.columns);
+    if (!read.softDeleted && Object.hasOwn(table.columns, 'deletedAt')) {
+        level.where = (fields) => isNull(fields['deletedAt']);
+    }
+    if (!is(relation, One))
+        level.orderBy = relationOrder(table, read.orderBy ?? orders[key], path);
+    const nested = relationsOf(metadata, orders, table, read.relations, path);
+    if (nested)
+        level.with = nested;
+    return level;
+}
+function relationsOf(metadata, orders, table, relations, path) {
+    if (!relations)
+        return undefined;
+    const levels = {};
+    for (const [name, read] of Object.entries(relations)) {
+        const relation = Object.hasOwn(table.relations, name) ? table.relations[name] : undefined;
+        if (!relation)
+            throw new UnknownReadName(`${path}.${name}`);
+        const level = relationLevel(metadata, orders, relation, read, `${path}.${name}`);
+        if (level)
+            levels[name] = level;
+    }
+    return Object.keys(levels).length > 0 ? levels : undefined;
+}
+/**
+ * A read resolved into drizzle's relational config for the table exported as `rootKey`: the root's columns with its
+ * primary key, and each relation under its own read, its marked rows left out unless it asks for them and, where it
+ * holds many, in its order.
+ *
+ * @throws {@link UnknownReadName} on a column or a relation the table it names does not hold
+ */
+export function relationalConfig(metadata, orders, rootKey, read) {
+    const table = tableAt(metadata, rootKey, rootKey);
+    const config = {};
+    if (read?.columns !== undefined) {
+        assertColumns(table, read.columns, rootKey);
+        config.columns = selecting([...primaryKeyOf(table), ...read.columns]);
+    }
+    const nested = relationsOf(metadata, orders, table, read?.relations, rootKey);
+    if (nested)
+        config.with = nested;
+    return config;
+}
+/**
+ * The columns a read of a table with no relational config selects: those it names with the primary key beside them,
+ * or every column.
+ *
+ * @throws {@link UnknownReadName} on a column the table does not hold, and on any relation, which needs the config
+ */
+export function plainColumns(selectable, primaryKey, read, name) {
+    if (read?.relations && Object.keys(read.relations).length > 0) {
+        throw new UnknownReadName(`${name}.${Object.keys(read.relations)[0]}`);
+    }
+    if (read?.columns === undefined)
+        return selectable;
+    for (const column of read.columns) {
+        if (!Object.hasOwn(selectable, column))
+            throw new UnknownReadName(`${name}.${column}`);
+    }
+    const kept = new Set([...primaryKey, ...read.columns]);
+    return Object.fromEntries(Object.entries(selectable).filter(([key]) => kept.has(key)));
+}

package/dist/utils/reads.d.ts

@@ -0,0 +1,24 @@
+import { type ExtractTablesWithRelations } from 'drizzle-orm';
+import type { VirtualField } from './filter.js';
+import type { ColumnName, OrderEntry } from './read.js';
+/** What holds for one table whichever read reaches it. */
+export interface TableReads<TColumn extends string = string> {
+    /** The order its rows load in as a relation that holds many; a relation's own `orderBy` replaces it. */
+    orderBy?: readonly OrderEntry<TColumn>[];
+    /** The filter and order names no column of it holds, each with the expression it becomes. */
+    virtual?: Readonly<Record<string, VirtualField>>;
+}
+/** A context's reads, keyed by each table's EXPORT name in the schema. */
+export type Reads<TSchema extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly [K in keyof ExtractTablesWithRelations<TSchema> & string]?: TableReads<ColumnName<TSchema, K>>;
+};
+/**
+ * Declares, once per context, what holds for each table whichever read reaches it: the order its rows load in as a
+ * relation, and its `virtual` filter and order names. Every repository of the context hands the same value to its base.
+ *
+ * @param schema - the schema barrel the repositories are typed by; each key is checked against it
+ * @throws Error at declaration on a key that is no table export of `schema`, or an order naming a column its table
+ *   does not hold
+ */
+export declare function defineReads<TSchema extends Record<string, unknown>>(schema: TSchema, reads: Reads<TSchema>): Reads<TSchema>;
+//# sourceMappingURL=reads.d.ts.map