@getstrata/core 2.2.2 → 2.2.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @getstrata/core changelog
 
+## 2.2.4
+
+-  perf(database): seek Postgres composite keyset bounds
+
+## 2.2.3
+
+- feat(database): add scoped composite keyset pagination
+
 ## 2.2.2
 
 - orm improvments

package/dist/core/database/baseRepository.d.ts

@@ -1,3 +1,4 @@
+import type { KeysetCursor, KeysetOptions } from "../pagination/index.ts";
 import { type CursorPaginatedResult, type PaginatedResult } from "../pagination/index.ts";
 import { type BelongsToManyRelation, type BelongsToRelation, type HasManyRelation, type HasManyThroughRelation, type MorphManyRelation, type MorphOneRelation, type MorphToRelation } from "./relationships.ts";
 import { RepositoryQuery } from "./repositoryQuery.ts";
@@ -37,6 +38,7 @@ declare class BaseRepository<TEntity extends object, PrimaryKey extends keyof TE
         cursorColumn?: PrimaryKey;
         direction?: "asc" | "desc";
     } & Omit<ExtendedQueryOptions<TEntity>, "limit" | "offset">): Promise<CursorPaginatedResult<TEntity, TEntity[PrimaryKey]>>;
+    keysetPaginate(options: KeysetOptions<TEntity> & Omit<ExtendedQueryOptions<TEntity>, "orderBy" | "limit" | "offset">): Promise<CursorPaginatedResult<TEntity, KeysetCursor>>;
     findById(id: TEntity[PrimaryKey]): Promise<TEntity | null>;
     findByIdOrThrow(id: TEntity[PrimaryKey], errorFactory?: ErrorFactory<TEntity[PrimaryKey]>): Promise<TEntity>;
     findByIds(ids: readonly TEntity[PrimaryKey][]): Promise<TEntity[]>;

package/dist/core/database/keyset.d.ts

@@ -0,0 +1,7 @@
+import type { KeysetCursor, KeysetOptions } from "../pagination/index.ts";
+import type { TableDefinition } from "./table.ts";
+import type { WhereNode } from "./whereBuilder.ts";
+declare const KEYSET_ALIAS_PREFIX = "__strata_keyset_";
+declare function validateKeyset<TEntity extends object, PK extends keyof TEntity & string>(table: TableDefinition<TEntity, PK>, options: KeysetOptions<TEntity>): KeysetCursor["order"];
+declare function keysetBoundary<TEntity extends object>(order: KeysetCursor["order"], cursor?: KeysetCursor): WhereNode<TEntity>[];
+export { KEYSET_ALIAS_PREFIX, keysetBoundary, validateKeyset };

package/dist/core/database/model.d.ts

@@ -1,3 +1,4 @@
+import type { CursorPaginatedResult, KeysetCursor, KeysetOptions } from "../pagination/index.ts";
 import BaseRepository from "./baseRepository.ts";
 import type { AnyRelationQuery, RelatedModelClass } from "./relationQuery.ts";
 import { BelongsToManyRelationQuery, BelongsToRelationQuery, HasManyRelationQuery, HasManyThroughRelationQuery, HasOneRelationQuery, MorphManyRelationQuery, MorphOneRelationQuery, MorphToRelationQuery } from "./relationQuery.ts";
@@ -55,7 +56,9 @@ declare function applyCasts(values: LoadedAttributes, casts: ModelCasts, directi
 /** Read-only plain records; partial selection never acquires model mutation methods. */
 declare class ModelProjection<TEntity extends object, K extends keyof TEntity & string> {
     private readonly load;
-    constructor(load: (limit?: number) => Promise<Array<Pick<TEntity, K>>>);
+    private readonly page;
+    constructor(load: (limit?: number) => Promise<Array<Pick<TEntity, K>>>, page: (options: KeysetOptions<TEntity>) => Promise<CursorPaginatedResult<Pick<TEntity, K>, KeysetCursor>>);
+    keysetPaginate(options: KeysetOptions<TEntity>): Promise<CursorPaginatedResult<Pick<TEntity, K>, KeysetCursor>>;
     get(): Promise<Array<Pick<TEntity, K>>>;
     first(): Promise<Pick<TEntity, K> | null>;
 }
@@ -106,6 +109,10 @@ declare class ModelQuery<TModel extends object = AnyModel, TCounts extends strin
     withTrashed(): this;
     onlyTrashed(): this;
     get(): Promise<ModelQueryResult<TModel, TCounts>[]>;
+    keysetPaginate(options: KeysetOptions<ModelAttributes<TModel>>): Promise<{
+        meta: import("../pagination/index.ts").CursorPaginationMeta<KeysetCursor>;
+        data: ModelQueryResult<TModel, TCounts>[];
+    }>;
     private hydrateRows;
     first(): Promise<ModelQueryResult<TModel, TCounts> | null>;
     count(): Promise<number>;
@@ -186,6 +193,12 @@ declare class Model<TEntity extends object, PrimaryKey extends keyof TEntity & s
     static chunk<TModel extends object>(this: {
         prototype: TModel;
     }, count: number, callback: (models: TModel[]) => Promise<boolean | void>): Promise<void>;
+    static keysetPaginate<TModel extends object>(this: {
+        prototype: TModel;
+    }, options: KeysetOptions<ModelAttributes<TModel>>): Promise<{
+        meta: import("../pagination/index.ts").CursorPaginationMeta<KeysetCursor>;
+        data: TModel[];
+    }>;
     static cursorPaginate<TModel extends object>(this: {
         prototype: TModel;
     }, options: {

package/dist/core/database/repositoryQuery.d.ts

@@ -1,4 +1,4 @@
-import type { PaginatedResult } from "../pagination/index.ts";
+import type { KeysetOptions, PaginatedResult } from "../pagination/index.ts";
 import type BaseRepository from "./baseRepository.ts";
 import type { BelongsToManyRelation, BelongsToRelation, HasManyRelation, HasManyThroughRelation, MorphManyRelation, MorphOneRelation, MorphToRelation } from "./relationships.ts";
 import type { QueryLockOptions, QueryOptions, QueryWhere, UpdateValues } from "./types.ts";
@@ -66,6 +66,14 @@ declare class RepositoryQuery<TEntity extends object, PrimaryKey extends keyof T
         meta: import("../pagination/index.ts").CursorPaginationMeta<TEntity[PrimaryKey]>;
         data: (TEntity & LoadedRow)[];
     }>;
+    keysetPaginate(options: KeysetOptions<TEntity>): Promise<{
+        meta: import("../pagination/index.ts").CursorPaginationMeta<import("../pagination/index.ts").KeysetCursor>;
+        data: (TEntity & LoadedRow)[];
+    }>;
+    projectKeyset<K extends keyof TEntity & string>(columns: readonly K[], options: KeysetOptions<TEntity>): Promise<{
+        meta: import("../pagination/index.ts").CursorPaginationMeta<import("../pagination/index.ts").KeysetCursor>;
+        data: Array<Pick<TEntity, K>>;
+    }>;
     /** Compiled query filters for batched relationship loaders. */
     getOptions(): QueryOptions<TEntity>;
     private buildOptions;

package/dist/core/database/types.d.ts

@@ -58,6 +58,11 @@ type QueryJoin = {
     on: QueryJoinOn[];
 };
 type QuerySelectItem = {
+    kind: "textColumn";
+    table: string;
+    column: string;
+    as: string;
+} | {
     kind: "column";
     table: string;
     column: string;

package/dist/core/database/whereBuilder.d.ts

@@ -13,6 +13,13 @@ type WhereNode<TEntity extends object> = {
 } | {
     kind: "and" | "or";
     exists: ExistsClause;
+} | {
+    kind: "and" | "or";
+    compareRow: {
+        columns: readonly string[];
+        operator: "lt" | "gt";
+        values: readonly unknown[];
+    };
 };
 declare class WhereBuilder<TEntity extends object, TWhere extends object = QueryWhere<TEntity>> {
     readonly nodes: WhereNode<TEntity>[];

package/dist/core/pagination/index.d.ts

@@ -25,3 +25,24 @@ declare function buildPaginationMeta(input: {
 }): PaginationMeta;
 export type { CursorPaginatedResult, CursorPaginationMeta, PaginatedResult, PaginationMeta };
 export { buildPaginationMeta };
+/** Ordering columns must be non-null scalar fields in the underlying schema. */
+type KeysetColumn<TEntity> = {
+    [K in keyof TEntity & string]: TEntity[K] extends string | number | bigint | Date ? K : never;
+}[keyof TEntity & string];
+interface KeysetCursor {
+    version: 1;
+    order: Array<{
+        column: string;
+        direction: "asc" | "desc";
+    }>;
+    values: string[];
+}
+interface KeysetOptions<TEntity> {
+    perPage: number;
+    orderBy: readonly {
+        column: KeysetColumn<TEntity>;
+        direction: "asc" | "desc";
+    }[];
+    cursor?: KeysetCursor;
+}
+export type { KeysetColumn, KeysetCursor, KeysetOptions };

package/dist/entries/database/query.js

@@ -149,6 +149,12 @@ function remapExistsSql(sql, existsParams, params) {
   return sql.replace(/\$(\d+)/g, (_match, index) => `$${offset + Number(index)}`);
 }
 function buildWhereNodeClause(tableName, node, params) {
+  if ("compareRow" in node) {
+    const { columns, operator, values } = node.compareRow;
+    if (!Array.isArray(columns) || !columns.length || !Array.isArray(values) || columns.length !== values.length || !["lt", "gt"].includes(operator) || Array.from(columns).some((column) => typeof column !== "string" || !column.length))
+      throw new TypeError("Invalid row comparison columns, values or operator.");
+    return `(${columns.map((column) => qualifyColumn(tableName, column)).join(", ")}) ${operator === "lt" ? "<" : ">"} (${values.map((value) => pushParam(params, value)).join(", ")})`;
+  }
   if ("exists" in node) {
     const body = remapExistsSql(node.exists.sql, node.exists.params, params);
     return `${node.exists.not ? "NOT " : ""}EXISTS (${body})`;
@@ -305,6 +311,12 @@ function buildSelectList(table, select, params = []) {
       const column = qualifyColumn(item.table, item.column);
       return item.as ? `${column} AS ${quoteIdentifier(item.as)}` : column;
     }
+    if (item.kind === "textColumn") {
+      const dialect = currentSqlDialect();
+      const column = qualifyColumn(item.table, item.column);
+      const text = dialect.driver === "sqlite" ? `CASE WHEN typeof(${column}) = 'real' THEN printf('%!.26g', ${column}) ELSE ${dialect.castToText(column)} END` : dialect.castToText(column);
+      return `${text} AS ${quoteIdentifier(item.as)}`;
+    }
     if (item.kind === "literalText") {
       return `${currentSqlDialect().castToText(pushParam(params, item.value))} AS ${quoteIdentifier(item.as)}`;
     }

package/dist/entries/database/repositoryQuery.js

@@ -173,6 +173,12 @@ function remapExistsSql(sql, existsParams, params) {
   return sql.replace(/\$(\d+)/g, (_match, index) => `$${offset + Number(index)}`);
 }
 function buildWhereNodeClause(tableName, node, params) {
+  if ("compareRow" in node) {
+    const { columns, operator, values } = node.compareRow;
+    if (!Array.isArray(columns) || !columns.length || !Array.isArray(values) || columns.length !== values.length || !["lt", "gt"].includes(operator) || Array.from(columns).some((column) => typeof column !== "string" || !column.length))
+      throw new TypeError("Invalid row comparison columns, values or operator.");
+    return `(${columns.map((column) => qualifyColumn(tableName, column)).join(", ")}) ${operator === "lt" ? "<" : ">"} (${values.map((value) => pushParam(params, value)).join(", ")})`;
+  }
   if ("exists" in node) {
     const body = remapExistsSql(node.exists.sql, node.exists.params, params);
     return `${node.exists.not ? "NOT " : ""}EXISTS (${body})`;
@@ -329,6 +335,12 @@ function buildSelectList(table, select, params = []) {
       const column = qualifyColumn(item.table, item.column);
       return item.as ? `${column} AS ${quoteIdentifier(item.as)}` : column;
     }
+    if (item.kind === "textColumn") {
+      const dialect = currentSqlDialect();
+      const column = qualifyColumn(item.table, item.column);
+      const text = dialect.driver === "sqlite" ? `CASE WHEN typeof(${column}) = 'real' THEN printf('%!.26g', ${column}) ELSE ${dialect.castToText(column)} END` : dialect.castToText(column);
+      return `${text} AS ${quoteIdentifier(item.as)}`;
+    }
     if (item.kind === "literalText") {
       return `${currentSqlDialect().castToText(pushParam(params, item.value))} AS ${quoteIdentifier(item.as)}`;
     }
@@ -1157,6 +1169,20 @@ class RepositoryQuery {
     const page = await this.repository.cursorPaginate({ ...this.buildOptions(), ...options });
     return { ...page, data: await this.attach(page.data) };
   }
+  async keysetPaginate(options) {
+    const page = await this.repository.keysetPaginate({ ...this.buildOptions(), ...options });
+    return { ...page, data: await this.attach(page.data) };
+  }
+  async projectKeyset(columns, options) {
+    if (!columns.length || columns.some((column) => !this.repository.getTable().columns.includes(column)))
+      throw new TypeError("Keyset projections require declared columns.");
+    const page = await this.repository.keysetPaginate({
+      ...this.buildOptions(),
+      ...options,
+      select: uniqueColumnSelect(this.repository.getTable().name, columns)
+    });
+    return { ...page, data: page.data };
+  }
   getOptions() {
     return this.buildOptions();
   }

package/dist/framework/public-api.d.ts

@@ -126,7 +126,7 @@ export type { MetricLabels } from "../core/metrics/prometheus.ts";
 export { PrometheusRegistry, prometheusRegistry } from "../core/metrics/prometheus.ts";
 export type { DatabaseNotificationPayload, DatabaseNotificationStore, MailNotificationMessage, Notifiable, NotificationChannelName, } from "../core/notifications/index.ts";
 export { createNotificationDispatcher, Notification, NotificationDispatcher, } from "../core/notifications/index.ts";
-export type { CursorPaginatedResult, PaginatedResult, PaginationMeta, } from "../core/pagination/index.ts";
+export type { CursorPaginatedResult, KeysetColumn, KeysetCursor, KeysetOptions, PaginatedResult, PaginationMeta, } from "../core/pagination/index.ts";
 export type { Queue, QueuePriority } from "../core/queue/index.ts";
 export { AsyncQueue, createQueue, Job, SyncQueue } from "../core/queue/index.ts";
 export { JobRegistry } from "../core/queue/jobRegistry.ts";

package/dist/index.js

@@ -4131,6 +4131,58 @@ function buildPaginationMeta(input) {
 init_connectionContext();
 init_dialect();
 
+// ../../src/core/database/keyset.ts
+init_dialect();
+var KEYSET_ALIAS_PREFIX = "__strata_keyset_";
+function validateKeyset(table, options) {
+  if (!Number.isInteger(options.perPage) || options.perPage < 1 || options.perPage > 1000)
+    throw new RangeError("Keyset page size must be between 1 and 1000.");
+  if (!Array.isArray(options.orderBy) || options.orderBy.length < 1 || options.orderBy.length > 8)
+    throw new TypeError("Keyset ordering requires between 1 and 8 columns.");
+  if (table.columns.some((column) => column.toLowerCase().startsWith(KEYSET_ALIAS_PREFIX)))
+    throw new TypeError("Table columns conflict with reserved keyset aliases.");
+  const seen = new Set;
+  const order = Array.from(options.orderBy).map(({ column, direction }) => {
+    if (!table.columns.includes(column) || seen.has(column) || !["asc", "desc"].includes(direction))
+      throw new TypeError("Invalid or duplicate keyset ordering column/direction.");
+    seen.add(column);
+    return { column, direction };
+  });
+  if (order.at(-1)?.column !== table.primaryKey)
+    throw new TypeError("Keyset ordering must end with the table primary key.");
+  if (options.cursor !== undefined) {
+    const cursor = options.cursor;
+    if (cursor?.version !== 1 || !Array.isArray(cursor.order) || cursor.order.length !== order.length || !Array.isArray(cursor.values) || cursor.values.length !== order.length || Array.from(cursor.order).some((item, i) => !item || item.column !== order[i]?.column || item.direction !== order[i]?.direction) || Array.from(cursor.values).some((value) => typeof value !== "string" || value.length > 4096))
+      throw new TypeError("Invalid keyset cursor or ordering mismatch.");
+  }
+  return order;
+}
+function keysetBoundary(order, cursor) {
+  if (!cursor)
+    return [];
+  if (currentSqlDialect().driver === "pgsql" && order.length > 1 && order.every((item) => item.direction === order[0]?.direction)) {
+    return [
+      {
+        kind: "and",
+        compareRow: {
+          columns: order.map((item) => item.column),
+          operator: order[0]?.direction === "asc" ? "gt" : "lt",
+          values: [...cursor.values]
+        }
+      }
+    ];
+  }
+  const branches = order.map((item, i) => {
+    const where = {};
+    order.slice(0, i).forEach((prefix, j) => {
+      where[prefix.column] = cursor.values[j];
+    });
+    where[item.column] = { [item.direction === "asc" ? "gt" : "lt"]: cursor.values[i] };
+    return { kind: i === 0 ? "and" : "or", where };
+  });
+  return [{ kind: "and", group: branches }];
+}
+
 // ../../src/core/database/query.ts
 init_dialect();
 function quoteIdentifier(identifier) {
@@ -4281,6 +4333,12 @@ function remapExistsSql(sql, existsParams, params) {
   return sql.replace(/\$(\d+)/g, (_match, index) => `$${offset + Number(index)}`);
 }
 function buildWhereNodeClause(tableName, node, params) {
+  if ("compareRow" in node) {
+    const { columns, operator, values } = node.compareRow;
+    if (!Array.isArray(columns) || !columns.length || !Array.isArray(values) || columns.length !== values.length || !["lt", "gt"].includes(operator) || Array.from(columns).some((column) => typeof column !== "string" || !column.length))
+      throw new TypeError("Invalid row comparison columns, values or operator.");
+    return `(${columns.map((column) => qualifyColumn(tableName, column)).join(", ")}) ${operator === "lt" ? "<" : ">"} (${values.map((value) => pushParam(params, value)).join(", ")})`;
+  }
   if ("exists" in node) {
     const body = remapExistsSql(node.exists.sql, node.exists.params, params);
     return `${node.exists.not ? "NOT " : ""}EXISTS (${body})`;
@@ -4437,6 +4495,12 @@ function buildSelectList(table, select, params = []) {
       const column = qualifyColumn(item.table, item.column);
       return item.as ? `${column} AS ${quoteIdentifier(item.as)}` : column;
     }
+    if (item.kind === "textColumn") {
+      const dialect = currentSqlDialect();
+      const column = qualifyColumn(item.table, item.column);
+      const text = dialect.driver === "sqlite" ? `CASE WHEN typeof(${column}) = 'real' THEN printf('%!.26g', ${column}) ELSE ${dialect.castToText(column)} END` : dialect.castToText(column);
+      return `${text} AS ${quoteIdentifier(item.as)}`;
+    }
     if (item.kind === "literalText") {
       return `${currentSqlDialect().castToText(pushParam(params, item.value))} AS ${quoteIdentifier(item.as)}`;
     }
@@ -5292,6 +5356,20 @@ class RepositoryQuery {
     const page = await this.repository.cursorPaginate({ ...this.buildOptions(), ...options });
     return { ...page, data: await this.attach(page.data) };
   }
+  async keysetPaginate(options) {
+    const page = await this.repository.keysetPaginate({ ...this.buildOptions(), ...options });
+    return { ...page, data: await this.attach(page.data) };
+  }
+  async projectKeyset(columns, options) {
+    if (!columns.length || columns.some((column) => !this.repository.getTable().columns.includes(column)))
+      throw new TypeError("Keyset projections require declared columns.");
+    const page = await this.repository.keysetPaginate({
+      ...this.buildOptions(),
+      ...options,
+      select: uniqueColumnSelect(this.repository.getTable().name, columns)
+    });
+    return { ...page, data: page.data };
+  }
   getOptions() {
     return this.buildOptions();
   }
@@ -5557,6 +5635,65 @@ class BaseRepository {
       }
     };
   }
+  async keysetPaginate(options) {
+    const order = validateKeyset(this.table, options);
+    if (options.joins?.length || options.groupBy || options.having || "offset" in options || "limit" in options)
+      throw new TypeError("Keyset pagination does not accept joined/grouped/offset/limited queries.");
+    if (options.select?.some((item) => item.as?.toLowerCase().startsWith(KEYSET_ALIAS_PREFIX)))
+      throw new TypeError("Projection conflicts with reserved keyset aliases.");
+    const filters = [...options.whereNodes ?? []];
+    if (options.where)
+      filters.push({ kind: "and", where: options.where });
+    const rows = await this.findAll({
+      ...options,
+      where: {},
+      whereNodes: [
+        { kind: "and", group: filters },
+        ...keysetBoundary(order, options.cursor)
+      ],
+      orderBy: order,
+      limit: options.perPage + 1,
+      select: [
+        ...options.select?.length ? options.select : this.table.columns.map((column) => ({
+          kind: "column",
+          table: this.table.name,
+          column
+        })),
+        ...order.map((item, i) => ({
+          kind: "textColumn",
+          table: this.table.name,
+          column: item.column,
+          as: `${KEYSET_ALIAS_PREFIX}${i}`
+        }))
+      ]
+    });
+    const entries = rows.map((row) => {
+      const record = { ...row };
+      const values = order.map((_, i) => {
+        const key = `${KEYSET_ALIAS_PREFIX}${i}`;
+        const value = record[key];
+        delete record[key];
+        if (typeof value !== "string" || value.length > 4096)
+          throw new TypeError("Keyset columns must contain non-null bounded scalar values.");
+        return value;
+      });
+      return { record, values };
+    });
+    const hasMore = entries.length > options.perPage;
+    const visible = entries.slice(0, options.perPage);
+    const last = visible.at(-1);
+    const nextCursor = hasMore && last ? { version: 1, order, values: last.values } : null;
+    const data = visible.map(({ record }) => record);
+    return {
+      data,
+      meta: {
+        per_page: options.perPage,
+        has_more: hasMore,
+        next_cursor: nextCursor,
+        prev_cursor: options.cursor ?? null
+      }
+    };
+  }
   async findById(id) {
     return await this.firstOrNull({
       [this.table.primaryKey]: id
@@ -7244,8 +7381,13 @@ function applyTimestampsOnUpdate(columns, values, enabled) {
 
 class ModelProjection {
   load;
-  constructor(load) {
+  page;
+  constructor(load, page) {
     this.load = load;
+    this.page = page;
+  }
+  keysetPaginate(options) {
+    return this.page(options);
   }
   get() {
     return this.load();
@@ -7295,6 +7437,12 @@ class ModelQuery {
     return new ModelProjection(async (limit) => {
       const rows = await this.query.project(columns, limit);
       return rows.map((row) => applyCasts(row, modelStatics(this.modelClass).$casts, "hydrate"));
+    }, async (options) => {
+      const page = await this.query.projectKeyset(columns, options);
+      return {
+        ...page,
+        data: page.data.map((row) => applyCasts(row, modelStatics(this.modelClass).$casts, "hydrate"))
+      };
     });
   }
   lockForUpdate(options = {}) {
@@ -7412,6 +7560,10 @@ class ModelQuery {
   async get() {
     return await this.hydrateRows(await this.query.get());
   }
+  async keysetPaginate(options) {
+    const page = await this.query.keysetPaginate(options);
+    return { ...page, data: await this.hydrateRows(page.data) };
+  }
   async hydrateRows(rows) {
     const statics = modelStatics(this.modelClass);
     const models = [];
@@ -7695,6 +7847,9 @@ class Model {
       return await callback(rows.map((row) => statics.newFromRecord(row, true)));
     });
   }
+  static keysetPaginate(options) {
+    return Model.query.call(this).keysetPaginate(options);
+  }
   static async cursorPaginate(options) {
     const statics = modelStatics(this);
     ensureBooted(this);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/core",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "Strata Bun framework public API",
   "type": "module",
   "license": "MIT",