@protobase/query 0.54.6 → 0.55.0

package/dist/base-query.js

@@ -1,24 +1,14 @@
-import { columnRef, tableSource } from "./columns.js";
+import { tableSource } from "./columns.js";
 import { compileFilter } from "./compile-filter.js";
-import { fullModelOf, tenantCondition } from "./scope.js";
-import { sql } from "kysely";
+import { readConditions } from "./read-conditions.js";
 //#region src/base-query.ts
-const softDeleteColumn = (model, name) => {
-	const field = Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
-	return field ? columnRef(field) : sql`${sql.id("t", name)}`;
-};
 /**
-* The table aliased as `t`, minus soft-deleted rows, inside the tenant and the access rule's row filter,
-* narrowed by the user's filter. Every query starts here, so no query can see rows the scope hides.
+* The table aliased as `t`, minus soft-deleted rows, inside the tenant, the access rule's row filter and the parents the
+* caller reads, narrowed by the user's filter. Every query starts here, so no query can see rows the scope hides.
 */
 const baseQuery = (db, model, filter, scope) => {
-	const full = fullModelOf(model, scope);
-	const softDelete = full.softDelete ?? model.softDelete;
 	let query = db.selectFrom(tableSource(model));
-	if (softDelete) query = query.where(sql`${softDeleteColumn(full, softDelete)} is null`);
-	const tenant = tenantCondition(model, scope);
-	if (tenant) query = query.where(tenant);
-	if (scope?.rowFilter) query = query.where(compileFilter(full, scope.rowFilter));
+	for (const condition of readConditions(model, scope)) query = query.where(condition);
 	if (filter) query = query.where(compileFilter(model, filter));
 	return query;
 };

package/dist/estimate-count.js

@@ -27,7 +27,7 @@ const tableReltuples = async (db, model) => {
 */
 const estimateCount = async (db, model, filter, scope) => {
 	const full = fullModelOf(model, scope);
-	if (filter || scope?.rowFilter || full.softDelete || full.tenant || model.softDelete || model.tenant) return planEstimate(db, model, filter, scope);
+	if (filter || scope?.rowFilter || scope?.parents?.length || full.softDelete || full.tenant || model.softDelete || model.tenant) return planEstimate(db, model, filter, scope);
 	const reltuples = await tableReltuples(db, model);
 	return reltuples >= 0 ? Math.round(reltuples) : planEstimate(db, model);
 };

package/dist/index-coverage.d.ts

@@ -8,8 +8,11 @@ import { CheckedFilter, ResourceModel, SortSpec } from "@protobase/schema";
  * column's digits (`regexp_replace(column, '[^0-9]', '', 'g')`) for a `digitsEnd` search field; `gin` for JSON.
  */
 export type IndexNeed = 'btree' | 'trigram' | 'digits' | 'gin';
-/** Where a column is read: the caller's filter, the access rule's row filter, the sort, or a facet's grouping. */
-export type ColumnUse = 'filter' | 'access' | 'sort' | 'facet';
+/**
+ * Where a column is read: the caller's filter, the access rule's row filter, the relation to a parent the caller must
+ * read (`.parent(fk, 'read')`), the sort, or a facet's grouping.
+ */
+export type ColumnUse = 'filter' | 'access' | 'parent' | 'sort' | 'facet';
 /** A column read without an index that serves it, and a statement that adds one. */
 export type UncoveredColumn = {
   field: string;
@@ -29,8 +32,9 @@ export declare const indexServes: (index: TableIndex, column: string, need: Inde
 /**
  * The columns a read of the resource would read without an index serving them; empty when every one is served. The
  * filter's and the access row filter's columns each need an index of the kind their operator uses, the sort's first
- * field and a grouped field a btree index. Tenant, soft delete and `=` terms pin columns, so a later key of a btree
- * index serves under them. A plain view or a foreign table has no indexes of its own and is not judged.
+ * field, a grouped field and each relation to a parent the caller must read a btree index; the parent's own reads are
+ * judged against its table by a call of their own. Tenant, soft delete and `=` terms pin columns, so a later key of a
+ * btree index serves under them. A plain view or a foreign table has no indexes of its own and is not judged.
  */
 export declare const uncoveredColumns: (model: ResourceModel, table: TableIndexes, query: CoverageQuery, scope?: Scope) => UncoveredColumn[];
 //#endregion

package/dist/index-coverage.js

@@ -76,8 +76,9 @@ const unique = (columns) => columns.filter((column, i) => columns.findIndex((oth
 /**
 * The columns a read of the resource would read without an index serving them; empty when every one is served. The
 * filter's and the access row filter's columns each need an index of the kind their operator uses, the sort's first
-* field and a grouped field a btree index. Tenant, soft delete and `=` terms pin columns, so a later key of a btree
-* index serves under them. A plain view or a foreign table has no indexes of its own and is not judged.
+* field, a grouped field and each relation to a parent the caller must read a btree index; the parent's own reads are
+* judged against its table by a call of their own. Tenant, soft delete and `=` terms pin columns, so a later key of a
+* btree index serves under them. A plain view or a foreign table has no indexes of its own and is not judged.
 */
 const uncoveredColumns = (model, table, query, scope) => {
 	if (table.kind !== "table") return [];
@@ -98,6 +99,7 @@ const uncoveredColumns = (model, table, query, scope) => {
 	const groupField = query.groupBy !== void 0 ? model.fields[query.groupBy] : void 0;
 	return unique([
 		...scope?.rowFilter ? walk(ctx("access", full), scope.rowFilter, pinned, false) : [],
+		...(scope?.parents ?? []).flatMap((read) => need(ctx("parent", full), read.field, "btree", pinned)),
 		...query.filter ? walk(ctx("filter"), query.filter, pinned, false) : [],
 		...sortField ? need(ctx("sort"), sortField, "btree", pinned) : [],
 		...groupField ? need(ctx("facet"), groupField, "btree", pinned) : []

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { CompileOptions, compileFilter } from "./compile-filter.js";
 import { Db } from "./db.js";
-import { Scope, tenantCondition } from "./scope.js";
+import { ParentRead, Scope, tenantCondition } from "./scope.js";
 import { RelatedRowsQuery, buildRelatedRows, relatedRows } from "./related-rows.js";
 import { ExtraColumn, ListOptions, ListPlan, ListResult, buildListQuery, listQuery, maxLimit } from "./list-query.js";
 import { estimateCount } from "./estimate-count.js";
@@ -19,5 +19,7 @@ import { ScrollMode, scrollMode } from "./scroll-mode.js";
 import { IndexKey, TableIndex, TableIndexes, tableIndexes } from "./table-indexes.js";
 import { ColumnUse, CoverageQuery, IndexNeed, UncoveredColumn, indexServes, uncoveredColumns } from "./index-coverage.js";
 import { QueryError, QueryErrorCode } from "./fields/query-error.js";
+import { parentCondition } from "./read-conditions.js";
+import { readsParent } from "./reads-parent.js";
 import { SeekRequest, seekToPosition } from "./seek-to-position.js";
-export { type ColumnUse, type CompileOptions, type CoverageQuery, type Db, type ExtraColumn, type FacetCount, type FacetOptions, type Granularity, type GroupTotal, type GroupTotalsOptions, type Histogram, type HistogramBucket, type IndexKey, type IndexNeed, type ListOptions, type ListPlan, type ListResult, type MapBounds, type MapBucket, type MapBuckets, type MapPosition, type Measure, QueryError, type QueryErrorCode, type RelatedRowsQuery, type Scope, type ScrollMode, type SeekRequest, type SeriesOptions, type SeriesPoint, type SplitPoint, type SplitSeriesOptions, type TableIndex, type TableIndexes, type UncoveredColumn, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, facetCounts, groupTotals, histogram, indexServes, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, relatedRows, scrollMode, seekToPosition, series, splitSeries, tableIndexes, tenantCondition, uncoveredColumns, withoutField };
+export { type ColumnUse, type CompileOptions, type CoverageQuery, type Db, type ExtraColumn, type FacetCount, type FacetOptions, type Granularity, type GroupTotal, type GroupTotalsOptions, type Histogram, type HistogramBucket, type IndexKey, type IndexNeed, type ListOptions, type ListPlan, type ListResult, type MapBounds, type MapBucket, type MapBuckets, type MapPosition, type Measure, type ParentRead, QueryError, type QueryErrorCode, type RelatedRowsQuery, type Scope, type ScrollMode, type SeekRequest, type SeriesOptions, type SeriesPoint, type SplitPoint, type SplitSeriesOptions, type TableIndex, type TableIndexes, type UncoveredColumn, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, facetCounts, groupTotals, histogram, indexServes, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, parentCondition, readsParent, relatedRows, scrollMode, seekToPosition, series, splitSeries, tableIndexes, tenantCondition, uncoveredColumns, withoutField };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { QueryError } from "./fields/query-error.js";
 import { compileFilter } from "./compile-filter.js";
 import { tenantCondition } from "./scope.js";
+import { parentCondition } from "./read-conditions.js";
 import { buildListQuery, listQuery, maxLimit } from "./list-query.js";
 import { buildRelatedRows, relatedRows } from "./related-rows.js";
 import { estimateCount } from "./estimate-count.js";
@@ -16,5 +17,6 @@ import { cellsAcross, checkMapPosition, mapBuckets, mapCellPixels, maxMapBuckets
 import { scrollMode } from "./scroll-mode.js";
 import { tableIndexes } from "./table-indexes.js";
 import { indexServes, uncoveredColumns } from "./index-coverage.js";
+import { readsParent } from "./reads-parent.js";
 import { seekToPosition } from "./seek-to-position.js";
-export { QueryError, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, facetCounts, groupTotals, histogram, indexServes, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, relatedRows, scrollMode, seekToPosition, series, splitSeries, tableIndexes, tenantCondition, uncoveredColumns, withoutField };
+export { QueryError, buildListQuery, buildRelatedRows, cellsAcross, checkMapPosition, compileFilter, countUpTo, estimateCount, exactCount, facetCounts, groupTotals, histogram, indexServes, listQuery, mapBuckets, mapCellPixels, maxLimit, maxMapBuckets, maxMapZoom, parentCondition, readsParent, relatedRows, scrollMode, seekToPosition, series, splitSeries, tableIndexes, tenantCondition, uncoveredColumns, withoutField };

package/dist/read-conditions.d.ts

@@ -0,0 +1,11 @@
+import { ParentRead } from "./scope.js";
+import { Expression, SqlBool } from "kysely";
+import { ResourceModel } from "@protobase/schema";
+//#region src/read-conditions.d.ts
+/**
+ * `fk in (select key from parent where <the caller's scope on it>)`, or `false` when the caller reads no parent; a
+ * nullable `fk` also keeps the rows that name no parent. The subquery aliases the parent `t` too, so its conditions read
+ * the parent's columns and only `fk` reads the outer row.
+ */
+export declare const parentCondition: (read: ParentRead) => Expression<SqlBool>;
+//#endregion

package/dist/read-conditions.js

@@ -0,0 +1,35 @@
+import { columnRef, tableSource } from "./columns.js";
+import { compileFilter } from "./compile-filter.js";
+import { fullModelOf, tenantCondition } from "./scope.js";
+import { sql } from "kysely";
+//#region src/read-conditions.ts
+const softDeleteColumn = (model, name) => {
+	const field = Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
+	return field ? columnRef(field) : sql`${sql.id("t", name)}`;
+};
+/**
+* `fk in (select key from parent where <the caller's scope on it>)`, or `false` when the caller reads no parent; a
+* nullable `fk` also keeps the rows that name no parent. The subquery aliases the parent `t` too, so its conditions read
+* the parent's columns and only `fk` reads the outer row.
+*/
+const parentCondition = (read) => {
+	const column = columnRef(read.field);
+	const { parent } = read;
+	const within = parent ? sql`${column} in (select ${columnRef(parent.key)} from ${tableSource(parent.model)}${whereAll(readConditions(parent.model, parent.scope))})` : sql`false`;
+	return read.field.nullable ? sql`(${column} is null or ${within})` : within;
+};
+const whereAll = (conditions) => conditions.length === 0 ? sql`` : sql` where ${sql.join(conditions, sql` and `)}`;
+/** What the scope hides of the table aliased as `t`: soft-deleted rows, other tenants, the row filter and unread parents. */
+const readConditions = (model, scope) => {
+	const full = fullModelOf(model, scope);
+	const softDelete = full.softDelete ?? model.softDelete;
+	const tenant = tenantCondition(model, scope);
+	return [
+		...softDelete ? [sql`${softDeleteColumn(full, softDelete)} is null`] : [],
+		...tenant ? [tenant] : [],
+		...scope?.rowFilter ? [compileFilter(full, scope.rowFilter)] : [],
+		...(scope?.parents ?? []).map(parentCondition)
+	];
+};
+//#endregion
+export { parentCondition, readConditions };

package/dist/reads-parent.d.ts

@@ -0,0 +1,6 @@
+import { Db } from "./db.js";
+import { ParentRead } from "./scope.js";
+//#region src/reads-parent.d.ts
+/** Whether the caller reads the parent record whose key is `value`, by the same scope a read of its children keeps to. */
+export declare const readsParent: (db: Db, read: ParentRead, value: string | number) => Promise<boolean>;
+//#endregion

package/dist/reads-parent.js

@@ -0,0 +1,12 @@
+import { columnRef } from "./columns.js";
+import { baseQuery } from "./base-query.js";
+import { sql } from "kysely";
+//#region src/reads-parent.ts
+/** Whether the caller reads the parent record whose key is `value`, by the same scope a read of its children keeps to. */
+const readsParent = async (db, read, value) => {
+	if (!read.parent) return false;
+	const { model, key, scope } = read.parent;
+	return await baseQuery(db, model, void 0, scope).select(sql`1`.as("one")).where(sql`${columnRef(key)} = ${value}`).limit(1).executeTakeFirst() !== void 0;
+};
+//#endregion
+export { readsParent };

package/dist/scope.d.ts

@@ -1,5 +1,5 @@
 import { Expression, SqlBool } from "kysely";
-import { CheckedFilter, ResourceModel } from "@protobase/schema";
+import { CheckedFilter, FieldModel, ResourceModel } from "@protobase/schema";
 //#region src/scope.d.ts
 /**
  * Who is asking, and which rows they may see.
@@ -8,6 +8,8 @@ import { CheckedFilter, ResourceModel } from "@protobase/schema";
  *   each tenant to its own access. An empty list sees no rows.
  * - `rowFilter`: a filter from access rules, ANDed in before the user's filter. It is checked against the FULL model,
  *   so it may use hidden or non-filterable columns the user's own (restricted) model does not expose.
+ * - `parents`: the relations whose record each row belongs to (`.parent(fk, 'read')`), keeping the rows whose parent the
+ *   caller reads; ANDed in with `rowFilter`.
  * - `fullModel`: that full model. Soft delete, tenant and `rowFilter` resolve against it; everything the user
  *   supplies (filter, sort, columns, fields) resolves against the model argument. Defaults to the model argument.
  */
@@ -15,8 +17,21 @@ export type Scope = {
   tenantValue?: string | number;
   tenantValues?: readonly (string | number)[];
   rowFilter?: CheckedFilter;
+  parents?: readonly ParentRead[];
   fullModel?: ResourceModel;
 };
+/**
+ * A relation whose parent the caller must read for a row to be seen: `field` of the full model, and the parent's full
+ * model, key and the caller's scope on it; without `parent` the caller reads no parent, so only a null `field` is seen.
+ */
+export type ParentRead = {
+  field: FieldModel;
+  parent?: {
+    model: ResourceModel;
+    key: FieldModel;
+    scope: Scope;
+  };
+};
 /**
  * `tenant = value`, or `tenant in (values)`, for tenant models; throws when the scope is missing, so a forgotten scope
  * never leaks rows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/query",
-  "version": "0.54.6",
+  "version": "0.55.0",
   "description": "Kysely list, filter, count and aggregate queries over Protobase resources.",
   "license": "Apache-2.0",
   "repository": {
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@protobase/schema": "0.54.6",
+    "@protobase/schema": "0.55.0",
     "kysely": "^0.29.6"
   }
 }