@voltro/database 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1251,7 +1251,15 @@ export declare type DatabaseHandle<Tables extends Record<string, Table<string, R
 export declare const databaseHandle: <Tables extends Record<string, Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>>>(tables: Tables) => DatabaseHandle<Tables>;
 
 export declare interface DataStore {
-    /** Execute a typed query descriptor and return matching rows. */
+    /**
+     * Execute a typed query descriptor and return matching rows.
+     *
+     * Deliberately NOT generic: `DataStore` is the driver SPI, implemented by
+     * every dialect store and its transactional / namespace views. Threading a
+     * phantom row type through all of them would be pure churn — they genuinely
+     * do return untyped rows off the wire. The row type is re-applied one layer
+     * up, on `FluentStore.query`, which is what handlers actually call.
+     */
     query(descriptor: QueryDescriptor): Promise<ReadonlyArray<Row>>;
     /** Insert a row. Emits an insert ChangeEvent (deferred if inside `transactional()`). */
     insert(table: string, row: Row): Promise<Row>;
@@ -2829,6 +2837,29 @@ export declare interface OrPredicate {
     readonly or: ReadonlyArray<Predicate>;
 }
 
+/**
+ * Keyset pagination on ANY orderable column — the general form of
+ * `paginateById`.
+ *
+ * `paginateById` hardcodes `id`, which is correct for a stable typeid/uuidv7
+ * key and useless for the case real feeds actually need: "the next page by
+ * `createdAt`". Apps hit that immediately and fell back to hand-rolled
+ * `limit + 1` / slice / `hasMore` triples — often on a timestamp cursor the
+ * helper could not express at all.
+ *
+ * The column MUST be unique, or monotonic enough that ties do not straddle a
+ * page boundary; otherwise a keyset cursor can skip or repeat rows at the seam.
+ * For a non-unique column (a timestamp with collisions) pass a composite order
+ * on the descriptor first — `.orderBy('createdAt').orderBy('id')` — and
+ * paginate by the tie-breaker.
+ *
+ * `direction` controls both the comparison and the ORDER BY, so a `desc` feed
+ * ("newest first") pages with `<` instead of `>`. Getting that pairing wrong is
+ * the classic keyset bug: an ascending comparison under a descending sort
+ * silently returns the same page forever.
+ */
+export declare const paginateBy: (descriptor: QueryDescriptor, column: string, cursor: string | number | Date | undefined, limit: number, direction?: "asc" | "desc") => QueryDescriptor;
+
 /**
  * Cursor pagination by primary key — `WHERE id > cursor ORDER BY id ASC LIMIT n`.
  *
@@ -2968,7 +2999,8 @@ export declare interface Query<RowOf, IxNames extends string = string,
 * `'alias.column'` → value type. Unjoined queries default to `{}`.
 */
 Joins extends JoinsMap = {}> {
-    readonly descriptor: QueryDescriptor;
+    /** Carries `RowOf` through to `store.query()` — see `QueryDescriptor<R>`. */
+    readonly descriptor: QueryDescriptor<RowOf>;
     /** Refine the predicate. Multiple `.where(...)` calls combine with AND. */
     where: (predicate: Predicate) => Query<RowOf, IxNames, Joins>;
     orderBy: <K extends keyof RowOf & string>(column: K, direction?: 'asc' | 'desc') => Query<RowOf, IxNames, Joins>;
@@ -3338,9 +3370,30 @@ Joins extends JoinsMap = {}> {
     }, IxNames, Joins>;
 }
 
-export declare interface QueryDescriptor {
+/**
+ * The runtime-facing materialized query — a plain bag of strings the store and
+ * the matcher consume.
+ *
+ * `R` is a PHANTOM row type. It exists so the row shape the typed builder
+ * already knows survives the trip through `.descriptor` into `store.query()`,
+ * which is where it used to be thrown away: `store.query(database.notes...)`
+ * returned `Row` (`Record<string, unknown>`), so every field read needed a
+ * hand-written cast. One downstream app wrote 2,032 of them. The type was
+ * always available — it was just dropped at this boundary.
+ *
+ * It is an OPTIONAL field, never set at runtime. That matters for two reasons:
+ * a plain object literal still satisfies `QueryDescriptor` (dispatcher, matcher
+ * and store code build and forward these structurally), and `R` stays
+ * covariant, so a `QueryDescriptor<Note>` is still assignable to the bare
+ * `QueryDescriptor` that generic infrastructure passes around. Defaulting to
+ * `Row` keeps every existing annotation meaning exactly what it meant before.
+ */
+export declare interface QueryDescriptor<R = Row> {
     readonly table: string;
     readonly predicate: Predicate | undefined;
+    /** Phantom — carries the row type through to `store.query()`. Never set at
+     *  runtime; erased entirely by the compiler. */
+    readonly __row?: R;
     /**
      * Opt OUT of the runtime's automatic `deletedAt IS NULL` scope on
      * `softDelete()` tables. Set by `.withDeleted()`. The query builder is