bunsane 0.5.4 → 0.5.5

package/core/archetype/weaver.ts

@@ -5,6 +5,7 @@ import { printSchema } from "graphql";
 import { getMetadataStorage } from "../metadata";
 import { componentSchemaCache } from "./schemaBuilder";
 import { inputTypeRegistry, customTypeNameRegistry } from "./customTypes";
+import { logger } from "../Logger";
 
 export const archetypeSchemaCache = new Map<
     string,
@@ -37,9 +38,9 @@ export function weaveAllArchetypes() {
                 const instance = new ArchetypeClass();
                 instance.getZodObjectSchema();
             } catch (error) {
-                console.warn(
-                    `Could not generate schema for archetype ${archetypeName}:`,
-                    error
+                logger.warn(
+                    { scope: 'weaver', archetype: archetypeName, error },
+                    `Could not generate schema for archetype ${archetypeName}`
                 );
             }
         }
@@ -125,7 +126,7 @@ export function weaveAllArchetypes() {
                     }
                 }
             } catch (error) {
-                console.warn(`Could not process relations for archetype ${archetypeMetadata.name}:`, error);
+                logger.warn({ scope: 'weaver', archetype: archetypeMetadata.name, error }, `Could not process relations for archetype ${archetypeMetadata.name}`);
             }
 
             if (archetypeMetadata.functions) {
@@ -208,11 +209,24 @@ export function weaveAllArchetypes() {
 
         return schemaString;
     } catch (error) {
-        console.warn(
-            `Failed to weave all archetypes due to duplicate types.\n` +
-            `Archetypes being processed: ${archetypeNames.join(', ')}\n` +
-            `Error: ${error}`
-        );
+        const msg = error instanceof Error ? error.message : String(error);
+        // graphql-js rejects a schema carrying two same-named types
+        // ("...must contain uniquely named types but contains multiple types
+        // named 'X'..."). The DeduplicationVisitor drops the duplicate and the
+        // schema still weaves and serves downstream, so this is recovered noise
+        // — log at debug. Any OTHER weave failure stays at warn so real
+        // breakage remains visible.
+        if (/multiple types named|uniquely named types/i.test(msg)) {
+            logger.debug(
+                { scope: 'weaver', archetypes: archetypeNames },
+                `Duplicate GraphQL type during archetype weave — deduplicated, schema unaffected: ${msg}`
+            );
+        } else {
+            logger.warn(
+                { scope: 'weaver', archetypes: archetypeNames, error },
+                'Failed to weave all archetypes'
+            );
+        }
         return null;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bunsane",
-    "version": "0.5.4",
+    "version": "0.5.5",
     "author": {
         "name": "yaaruu"
     },

package/query/ComponentInclusionNode.ts

@@ -13,7 +13,7 @@ import { getMembershipSource, getMembershipTable } from "./membershipSource";
  * Check if a component property is numeric based on metadata
  * Used to apply proper casting in ORDER BY clauses for index usage
  */
-function isNumericProperty(componentName: string, propertyName: string): boolean {
+export function isNumericProperty(componentName: string, propertyName: string): boolean {
     const storage = getMetadataStorage();
     const typeId = storage.getComponentId(componentName);
 
@@ -135,6 +135,79 @@ export class ComponentInclusionNode extends QueryNode {
      * sort when the predicate is highly selective — unlike the correlated
      * subquery ORDER BY, which can never use an index for ordering.
      */
+    /**
+     * Build a composite keyset WHERE clause for a single-sort-key component query.
+     * Returns an empty string when no composite cursor is set.
+     *
+     * The ORDER BY shape is `sort_expr <dir> NULLS <x>, entity_id ASC` (Fix #1).
+     * For `cursorDirection='after'`:
+     *   - ASC sort: (sort_expr, entity_id) > ($v, $id)   → row comparison works
+     *   - DESC sort: sort_expr < $v OR (sort_expr = $v AND entity_id > $id)
+     * For `cursorDirection='before'` (reverse — rarely used): opposite operators.
+     *
+     * Null sort values: placed last by default (NULLS LAST). A NULL cursor value
+     * means "after all NULL-sorted rows" — we exclude them entirely (`IS NOT NULL`).
+     */
+    private buildCompositeCursorWhere(
+        context: QueryContext,
+        sortExpr: string,
+        isNumeric: boolean,
+        entityIdCol: string,
+        connective: 'WHERE' | 'AND'
+    ): string {
+        if (!context.compositeCursor) return '';
+        if (context.sortOrders.length !== 1) {
+            throw new Error(
+                'sortedCursor() requires exactly one sort key on a component sortBy(). ' +
+                'Multi-key component sort cursors are not supported.'
+            );
+        }
+        const sortOrder = context.sortOrders[0]!;
+        const isDesc = sortOrder.direction === 'DESC';
+        const isBefore = context.cursorDirection === 'before';
+
+        // 'before' direction for component sortBy cursors is not yet implemented:
+        // it requires reversing ORDER BY and post-reversing rows in JS.
+        // Throw rather than returning silently wrong pages.
+        if (isBefore) {
+            throw new Error(
+                "sortedCursor(token, 'before') is not supported for component sortBy(). " +
+                'Use OFFSET pagination or walk pages forward only.'
+            );
+        }
+
+        const { v, id } = context.compositeCursor;
+        const cast = isNumeric ? '::numeric' : '::text';
+        const nullsLast = !sortOrder.nullsFirst; // default is NULLS LAST
+
+        if (v === null) {
+            // Cursor is inside the NULL region (sort value was null on the last seen row).
+            // Under NULLS LAST (ASC): NULLs appear at the end; advance within them by id.
+            // Under NULLS FIRST (DESC): NULLs appear at the start; after a null cursor the
+            //   non-null region follows — but that case cannot arise for DESC NULLS FIRST
+            //   because NULLs come first (they'd be returned before any non-null values).
+            // Simplest correct behaviour: walk within the null region by id tiebreak.
+            const idIdx = context.addParam(id);
+            return ` ${connective} (${sortExpr} IS NULL AND ${entityIdCol} > $${idIdx}::uuid)`;
+        }
+
+        // ASC+after: (sort_expr, id) > ($v, $id), plus NULL-sorted rows which come
+        // AFTER all non-null rows under NULLS LAST (forward direction, not yet visited).
+        if (!isDesc) {
+            const vIdx = context.addParam(v);
+            const idIdx = context.addParam(id);
+            const nullInclude = nullsLast ? ` OR ${sortExpr} IS NULL` : '';
+            return ` ${connective} ((${sortExpr}, ${entityIdCol}) > ($${vIdx}${cast}, $${idIdx}::uuid)${nullInclude})`;
+        }
+
+        // DESC+after: values come in decreasing order; "after" (v,id) means smaller
+        // value, or same value and larger id (id is ASC within ties).
+        const vLtIdx = context.addParam(v);
+        const vEqIdx = context.addParam(v);
+        const idGtIdx = context.addParam(id);
+        return ` ${connective} (${sortExpr} < $${vLtIdx}${cast} OR (${sortExpr} = $${vEqIdx}${cast} AND ${entityIdCol} > $${idGtIdx}::uuid))`;
+    }
+
     private applySortDrivenScan(context: QueryContext): string | null {
         if (!ComponentInclusionNode.canUseSortDrivenScan(context)) return null;
 
@@ -220,26 +293,30 @@ export class ComponentInclusionNode extends QueryNode {
 
         const extraConditions = conditions.length > 0 ? `\n                AND ${conditions.join('\n                AND ')}` : '';
 
+        // Composite keyset predicate (AND because WHERE already has type_id check).
+        const cursorWhere = this.buildCompositeCursorWhere(context, sortExpr, isNumeric, 's.entity_id', 'AND');
+
         let sql: string;
         if (driveDirect || !getMembershipSource().isLegacy) {
             // Drive directly from the sort component (partition) table —
             // membership and component data are the same row.
             sql = `SELECT s.entity_id as id FROM ${sortTable} s
                 WHERE s.type_id = $${context.addParam(sortTypeId)}::text
-                AND s.deleted_at IS NULL${extraConditions}
-                ORDER BY ${sortExpr} ${sortOrder.direction} ${nullsClause}`;
+                AND s.deleted_at IS NULL${extraConditions}${cursorWhere}
+                ORDER BY ${sortExpr} ${sortOrder.direction} ${nullsClause}, s.entity_id ASC`;
         } else {
             sql = `SELECT s.entity_id as id FROM entity_components ec
                 JOIN ${sortTable} s ON s.id = ec.component_id AND s.deleted_at IS NULL
                 WHERE ec.type_id = $${context.addParam(sortTypeId)}::text
-                AND ec.deleted_at IS NULL${extraConditions}
-                ORDER BY ${sortExpr} ${sortOrder.direction} ${nullsClause}`;
+                AND ec.deleted_at IS NULL${extraConditions}${cursorWhere}
+                ORDER BY ${sortExpr} ${sortOrder.direction} ${nullsClause}, s.entity_id ASC`;
         }
 
         if (context.limit !== null) {
             sql += ` LIMIT $${context.addParam(context.limit)}`;
         }
-        if (context.offsetValue > 0 || context.limit !== null) {
+        // OFFSET is not used alongside composite cursor pagination.
+        if (!context.compositeCursor && (context.offsetValue > 0 || context.limit !== null)) {
             sql += ` OFFSET $${context.addParam(context.offsetValue)}`;
         }
 
@@ -520,6 +597,13 @@ export class ComponentInclusionNode extends QueryNode {
      * This ensures that sorting and pagination work together correctly
      */
     private applySortingWithComponentJoins(baseQuery: string, context: QueryContext): string {
+        if (context.compositeCursor && context.sortOrders.length !== 1) {
+            throw new Error(
+                'sortedCursor() requires exactly one sort key. ' +
+                'Multi-key component sort cursors are not supported.'
+            );
+        }
+
         // Check if we can use the optimized direct partition sort
         if (shouldUseDirectPartition() && context.sortOrders.length === 1) {
             const optimized = this.applySortingOptimized(baseQuery, context);
@@ -584,12 +668,70 @@ export class ComponentInclusionNode extends QueryNode {
             orderByClauses.push(`${subquery} ${sortOrder.direction} ${nullsClause}`);
         }
 
+        if (context.compositeCursor && orderByClauses.length === 1 && context.sortOrders.length === 1) {
+            // Composite keyset on single sort key via CTE: materialize sort value,
+            // filter by keyset predicate, then apply LIMIT.
+            const sortOrder = context.sortOrders[0]!;
+            const isNumericSv = isNumericProperty(sortOrder.component, sortOrder.property);
+            const nullsClauseSv = sortOrder.nullsFirst ? 'NULLS FIRST' : 'NULLS LAST';
+            const { v, id: cursorId } = context.compositeCursor;
+            const cast = isNumericSv ? '::numeric' : '::text';
+            const isDesc = sortOrder.direction === 'DESC';
+            const isBefore = context.cursorDirection === 'before';
+
+            // Strip the trailing " ASC|DESC NULLS FIRST|LAST" to get the raw scalar subquery.
+            const svExpr = orderByClauses[0]!.replace(/ (ASC|DESC) NULLS (FIRST|LAST)$/, '');
+
+            // 'before' for composite keyset is not implemented — throw instead of
+            // returning silently wrong pages.
+            if (isBefore) {
+                throw new Error(
+                    "sortedCursor(token, 'before') is not supported for component sortBy(). " +
+                    'Use OFFSET pagination or walk pages forward only.'
+                );
+            }
+
+            const nullsLast = !sortOrder.nullsFirst;
+            let keysetWhere: string;
+            if (v === null) {
+                // Cursor is inside the NULL region: advance within it by id tiebreak.
+                const idIdx = context.addParam(cursorId);
+                keysetWhere = `(_sorted._sv IS NULL AND _sorted.id > $${idIdx}::uuid)`;
+            } else if (!isDesc) {
+                // ASC+after: row-comparison + include NULL-sorted rows (NULLS LAST →
+                // they appear at the very end, after all non-null rows).
+                const vIdx = context.addParam(v);
+                const idIdx = context.addParam(cursorId);
+                const nullInclude = nullsLast ? ' OR _sorted._sv IS NULL' : '';
+                keysetWhere = `((_sorted._sv, _sorted.id) > ($${vIdx}${cast}, $${idIdx}::uuid)${nullInclude})`;
+            } else {
+                // DESC+after: smaller value, or same value and larger id.
+                const vLtIdx = context.addParam(v);
+                const vEqIdx = context.addParam(v);
+                const idGtIdx = context.addParam(cursorId);
+                keysetWhere = `(_sorted._sv < $${vLtIdx}${cast} OR (_sorted._sv = $${vEqIdx}${cast} AND _sorted.id > $${idGtIdx}::uuid))`;
+            }
+
+            let sql = `WITH _sorted AS (
+                SELECT base_entities.id, ${svExpr} AS _sv
+                FROM (${baseQuery}) AS base_entities
+            )
+            SELECT _sorted.id FROM _sorted
+            WHERE ${keysetWhere}
+            ORDER BY _sorted._sv ${sortOrder.direction} ${nullsClauseSv}, _sorted.id ASC`;
+
+            if (!context.paginationAppliedInCTE && context.limit !== null) {
+                sql += ` LIMIT $${context.addParam(context.limit)}`;
+            }
+            return sql;
+        }
+
         // Wrap the base query as a subquery to get entity ids
         let sql = `SELECT base_entities.id FROM (${baseQuery}) AS base_entities`;
 
         // Add ORDER BY clause
         if (orderByClauses.length > 0) {
-            sql += ` ORDER BY ${orderByClauses.join(', ')}`;
+            sql += ` ORDER BY ${orderByClauses.join(', ')}, base_entities.id ASC`;
         } else {
             // Fallback to entity id if no valid sort orders
             sql += ` ORDER BY base_entities.id`;
@@ -602,7 +744,7 @@ export class ComponentInclusionNode extends QueryNode {
                 sql += ` LIMIT $${context.addParam(context.limit)}`;
             }
             // Only add OFFSET when not using cursor-based pagination
-            if (context.cursorId === null && (context.offsetValue > 0 || context.limit !== null)) {
+            if (!context.compositeCursor && context.cursorId === null && (context.offsetValue > 0 || context.limit !== null)) {
                 sql += ` OFFSET $${context.addParam(context.offsetValue)}`;
             }
         }
@@ -692,6 +834,9 @@ export class ComponentInclusionNode extends QueryNode {
             ? `(c.data->>'${safeProperty}')::numeric`
             : `c.data->>'${safeProperty}'`;
 
+        // Composite keyset predicate (AND because WHERE already has other conditions).
+        const cursorWhere = this.buildCompositeCursorWhere(context, sortExpr, isNumeric, 'c.entity_id', 'AND');
+
         let sql: string;
         if (useDirectPartition || !getMembershipSource().isLegacy) {
             // Direct access on the component (partition) table - most efficient.
@@ -699,8 +844,8 @@ export class ComponentInclusionNode extends QueryNode {
             sql = `SELECT c.entity_id as id FROM ${componentTableName} c
                 WHERE c.type_id = $${context.addParam(sortTypeId)}::text
                 AND c.deleted_at IS NULL
-                AND ${filterConditions.join(' AND ')}
-                ORDER BY ${sortExpr} ${sortOrder.direction} ${nullsClause}`;
+                AND ${filterConditions.join(' AND ')}${cursorWhere}
+                ORDER BY ${sortExpr} ${sortOrder.direction} ${nullsClause}, c.entity_id ASC`;
         } else {
             // Use entity_components junction
             // No DISTINCT needed since each entity has one component of this type
@@ -708,8 +853,8 @@ export class ComponentInclusionNode extends QueryNode {
                 JOIN ${componentTableName} c ON c.id = ec.component_id AND c.deleted_at IS NULL
                 WHERE ec.type_id = $${context.addParam(sortTypeId)}::text
                 AND ec.deleted_at IS NULL
-                AND ${filterConditions.join(' AND ')}
-                ORDER BY ${sortExpr} ${sortOrder.direction} ${nullsClause}`;
+                AND ${filterConditions.join(' AND ')}${cursorWhere}
+                ORDER BY ${sortExpr} ${sortOrder.direction} ${nullsClause}, c.entity_id ASC`;
         }
 
         // Add pagination
@@ -717,7 +862,8 @@ export class ComponentInclusionNode extends QueryNode {
             if (context.limit !== null) {
                 sql += ` LIMIT $${context.addParam(context.limit)}`;
             }
-            if (context.cursorId === null && (context.offsetValue > 0 || context.limit !== null)) {
+            // OFFSET is not used alongside composite cursor pagination.
+            if (!context.compositeCursor && context.cursorId === null && (context.offsetValue > 0 || context.limit !== null)) {
                 sql += ` OFFSET $${context.addParam(context.offsetValue)}`;
             }
         }
@@ -759,8 +905,58 @@ export class ComponentInclusionNode extends QueryNode {
             LIMIT 1
         )`;
 
+        if (context.compositeCursor) {
+            // Composite keyset via CTE: materialize sort value, filter, then paginate.
+            const { v, id: cursorId } = context.compositeCursor;
+            const cast = isNumeric ? '::numeric' : '::text';
+            const isDesc = sortOrder.direction === 'DESC';
+            const isBefore = context.cursorDirection === 'before';
+
+            // 'before' for composite keyset is not implemented — throw instead of
+            // returning silently wrong pages.
+            if (isBefore) {
+                throw new Error(
+                    "sortedCursor(token, 'before') is not supported for component sortBy(). " +
+                    'Use OFFSET pagination or walk pages forward only.'
+                );
+            }
+
+            const nullsLast = !sortOrder.nullsFirst;
+            let keysetWhere: string;
+            if (v === null) {
+                // Cursor is inside the NULL region: advance within it by id tiebreak.
+                const idIdx = context.addParam(cursorId);
+                keysetWhere = `(_sorted._sv IS NULL AND _sorted.id > $${idIdx}::uuid)`;
+            } else if (!isDesc) {
+                // ASC+after: row-comparison + include NULL-sorted rows (NULLS LAST →
+                // they appear at the very end, after all non-null rows).
+                const vIdx = context.addParam(v);
+                const idIdx = context.addParam(cursorId);
+                const nullInclude = nullsLast ? ' OR _sorted._sv IS NULL' : '';
+                keysetWhere = `((_sorted._sv, _sorted.id) > ($${vIdx}${cast}, $${idIdx}::uuid)${nullInclude})`;
+            } else {
+                // DESC+after: smaller value, or same value and larger id.
+                const vLtIdx = context.addParam(v);
+                const vEqIdx = context.addParam(v);
+                const idGtIdx = context.addParam(cursorId);
+                keysetWhere = `(_sorted._sv < $${vLtIdx}${cast} OR (_sorted._sv = $${vEqIdx}${cast} AND _sorted.id > $${idGtIdx}::uuid))`;
+            }
+
+            let sql = `WITH _sorted AS (
+                SELECT base.id, ${sortSubquery} AS _sv FROM (${baseQuery}) AS base
+            )
+            SELECT _sorted.id FROM _sorted
+            WHERE ${keysetWhere}
+            ORDER BY _sorted._sv ${sortOrder.direction} ${nullsClause}, _sorted.id ASC`;
+
+            if (!context.paginationAppliedInCTE && context.limit !== null) {
+                sql += ` LIMIT $${context.addParam(context.limit)}`;
+            }
+            return sql;
+        }
+
         let sql = `SELECT base.id FROM (${baseQuery}) AS base
-            ORDER BY ${sortSubquery} ${sortOrder.direction} ${nullsClause}`;
+            ORDER BY ${sortSubquery} ${sortOrder.direction} ${nullsClause}, base.id ASC`;
 
         // Add LIMIT and OFFSET only if not already applied in CTE
         // When pagination is applied at CTE level, skip it here to avoid double pagination

package/query/OrNode.ts

@@ -178,8 +178,10 @@ export class OrNode extends QueryNode {
             sql += ` WHERE ${conditions.join(' AND ')}`;
         }
 
-        // Add ordering
-        sql += " ORDER BY id";
+        // Add ordering (skipped when an outer sort wrapper re-orders the set)
+        if (!context.suppressNodeOrdering) {
+            sql += " ORDER BY id";
+        }
 
         // Add pagination
         if (context.limit !== null) {
@@ -302,8 +304,10 @@ export class OrNode extends QueryNode {
             sql += ` AND ${conditions.join(' AND ')}`;
         }
 
-        // Add ordering
-        sql += " ORDER BY entity_id";
+        // Add ordering (skipped when an outer sort wrapper re-orders the set)
+        if (!context.suppressNodeOrdering) {
+            sql += " ORDER BY entity_id";
+        }
 
         // Add pagination
         if (context.limit !== null) {
@@ -529,8 +533,10 @@ export class OrNode extends QueryNode {
             sql += ` WHERE ${conditions.join(' AND ')}`;
         }
 
-        // Add ordering
-        sql += " ORDER BY entity_id";
+        // Add ordering (skipped when an outer sort wrapper re-orders the set)
+        if (!context.suppressNodeOrdering) {
+            sql += " ORDER BY entity_id";
+        }
 
         // Add pagination
         if (context.limit !== null) {
@@ -673,7 +679,10 @@ export class OrNode extends QueryNode {
             context.params.push(...excludedTypes);
         }
 
-        sql += " ORDER BY base.id";
+        // Add ordering (skipped when an outer sort wrapper re-orders the set)
+        if (!context.suppressNodeOrdering) {
+            sql += " ORDER BY base.id";
+        }
 
         if (context.limit !== null) {
             sql += ` LIMIT $${paramIndex++}`;

package/query/Query.ts

@@ -13,8 +13,9 @@ import { getMetadataStorage } from "../core/metadata";
 import { shouldUseDirectPartition } from "../core/Config";
 import type { SQL } from "bun";
 import type { ComponentConstructor, TypedEntity, ComponentRecord } from "../types/query.types";
-import { assertComponentTableName, assertFieldPath } from "./SqlIdentifier";
+import { assertComponentTableName, assertFieldPath, assertIdentifier } from "./SqlIdentifier";
 import { getMembershipSource } from "./membershipSource";
+import { isNumericProperty } from "./ComponentInclusionNode";
 
 // Parsed once at module load instead of on every exec() (process.env read +
 // parseInt was on the query hot path). 0 disables the default limit.
@@ -307,6 +308,64 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
         return this;
     }
 
+    /**
+     * Use composite keyset pagination for a SORTED query.
+     *
+     * Pass the opaque token returned by `Query.encodeSortedCursor(sortValue, entityId)`
+     * where `sortValue` is the sort column's raw value from the last row of the
+     * previous page, and `entityId` is that row's entity id. The query must have
+     * exactly one active sort key (sortByCreatedAt / sortByUpdatedAt / sortBy).
+     * Multi-key sort cursors are not supported — the method will throw at exec time.
+     *
+     * @example
+     * // Page 1
+     * const page1 = await new Query().with(MyComp).sortBy(MyComp, 'score', 'ASC').take(10).exec();
+     * const last = page1[page1.length - 1]!;
+     * // Build cursor from the last row's sort value.
+     * const token = Query.encodeSortedCursor(last.componentData['MyComp'].score, last.id);
+     *
+     * // Page 2
+     * const page2 = await new Query().with(MyComp).sortBy(MyComp, 'score', 'ASC').take(10).sortedCursor(token).exec();
+     */
+    public sortedCursor(token: string, direction: 'after' | 'before' = 'after'): this {
+        this.context.compositeCursor = Query.decodeSortedCursor(token);
+        this.context.cursorDirection = direction;
+        // A composite cursor supersedes plain cursorId and OFFSET.
+        this.context.cursorId = null;
+        this.context.offsetValue = 0;
+        return this;
+    }
+
+    /**
+     * Encode a composite sort cursor from the last row's sort value and entity id.
+     * The sort value is stored as a string; pass the raw JS value (string, number,
+     * Date, or null). Dates are converted to ISO strings for timestamptz comparison.
+     */
+    public static encodeSortedCursor(sortValue: string | number | Date | null, entityId: string): string {
+        let v: string | null;
+        if (sortValue === null || sortValue === undefined) {
+            v = null;
+        } else if (sortValue instanceof Date) {
+            v = sortValue.toISOString();
+        } else {
+            v = String(sortValue);
+        }
+        return Buffer.from(JSON.stringify({ v, id: entityId })).toString('base64');
+    }
+
+    /** Decode a composite sort cursor token. Returns `{v, id}`. */
+    public static decodeSortedCursor(token: string): { v: string | null; id: string } {
+        try {
+            const parsed = JSON.parse(Buffer.from(token, 'base64').toString('utf8'));
+            if (typeof parsed !== 'object' || parsed === null || typeof parsed.id !== 'string') {
+                throw new Error('malformed cursor');
+            }
+            return { v: parsed.v ?? null, id: parsed.id };
+        } catch {
+            throw new Error(`Invalid sorted cursor token: "${token}"`);
+        }
+    }
+
     public sortBy<T extends BaseComponent>(
         componentCtor: new (...args: any[]) => T,
         property: keyof ComponentDataType<T>,
@@ -335,6 +394,36 @@ class Query<TComponents extends readonly ComponentConstructor[] = []> {
         return this;
     }
 
+    /**
+     * Sort by a native `entities`-table timestamp column (created_at /
+     * updated_at). Needs no component and no `.with()` — the column always
+     * exists on every entity and is a real indexed `timestamptz`, so this is
+     * cheaper than duplicating the timestamp into a JSONB component and
+     * sorting `data->>'...'`.
+     *
+     * Applied as an outer ORDER BY over the resolved id-set in doExec, so it
+     * composes with any `.with()` / filter combination. Cursor pagination is
+     * ignored when an entity sort is active (use .take()/.offset()).
+     */
+    public sortByEntityField(
+        field: "created_at" | "updated_at",
+        direction: SortDirection = "ASC",
+        nullsFirst: boolean = false
+    ): this {
+        this.context.entitySortOrders.push({ field, direction, nullsFirst });
+        return this;
+    }
+
+    /** Sort by entity creation time (`entities.created_at`). */
+    public sortByCreatedAt(direction: SortDirection = "ASC", nullsFirst: boolean = false): this {
+        return this.sortByEntityField("created_at", direction, nullsFirst);
+    }
+
+    /** Sort by entity last-update time (`entities.updated_at`). */
+    public sortByUpdatedAt(direction: SortDirection = "ASC", nullsFirst: boolean = false): this {
+        return this.sortByEntityField("updated_at", direction, nullsFirst);
+    }
+
     public debugMode(enabled: boolean = true): this {
         this.debug = enabled;
         return this;
@@ -838,41 +927,322 @@ AND c.deleted_at IS NULL`;
         // Reset context for fresh execution
         this.context.reset();
 
-        // Build the DAG
-        const dag = new QueryDAG();
+        // Entity-column sort (sortByCreatedAt/sortByUpdatedAt) and component
+        // sortBy() cannot be combined: the outer wrapper re-orders solely by
+        // the entity column, silently overriding the component sort.
+        if (this.context.entitySortOrders.length > 0 && this.context.sortOrders.length > 0) {
+            throw new Error(
+                'sortByCreatedAt()/sortByUpdatedAt() cannot be combined with sortBy() in the same query. ' +
+                'Use one or the other.'
+            );
+        }
 
-        // Check if we have an OR query
-        if (this.orQuery) {
-            // For OR queries, we need to ensure entities have all required components first
-            if (this.context.componentIds.size > 0) {
-                // ComponentInclusionNode is the root, OrNode is the leaf
-                const componentNode = new ComponentInclusionNode();
-                dag.setRootNode(componentNode);
+        // Native entity-column sort (created_at/updated_at) is applied as an
+        // outer ORDER BY over the resolved id-set. The inner nodes must emit
+        // the FULL set with no ordering/pagination of their own, else their
+        // LIMIT would truncate the wrong rows before we re-order. Stash and
+        // neutralize pagination for the inner build; restore + re-apply in the
+        // wrapper below.
+        const entitySorts = this.context.entitySortOrders;
+        const useEntitySort = entitySorts.length > 0;
+        // Component sortBy() on an OR query is also resolved by an outer
+        // wrapper: OrNode produces an unordered id-set, then we JOIN the sort
+        // component's data table and ORDER BY it (mirrors the entity-sort
+        // wrapper). The non-OR component sort path lives inside
+        // ComponentInclusionNode/CTE and is untouched.
+        const componentSorts = this.context.sortOrders;
+        const useOrComponentSort = !!this.orQuery && componentSorts.length > 0;
+        const useOuterSortWrapper = useEntitySort || useOrComponentSort;
+
+        let savedLimit: number | null = null;
+        let savedOffset = 0;
+        let savedCursorId: string | null = null;
+        let savedCompositeCursor: { v: string | null; id: string } | null = null;
+        const savedSuppressNodeOrdering = this.context.suppressNodeOrdering;
+        // Captured by reference before any neutralization below, so the wrapper
+        // still sees the requested sort keys after we clear context.sortOrders.
+        const savedSortOrders = this.context.sortOrders;
+        if (useOuterSortWrapper) {
+            savedLimit = this.context.limit;
+            savedOffset = this.context.offsetValue;
+            savedCursorId = this.context.cursorId;
+            savedCompositeCursor = this.context.compositeCursor;
+            this.context.limit = null;
+            this.context.offsetValue = 0;
+            this.context.cursorId = null;
+            this.context.compositeCursor = null;
+            // Only OrNode honours this; the inner OR id-set need not self-sort
+            // because the wrapper re-orders the full set. Non-OR inner nodes
+            // ignore the flag.
+            this.context.suppressNodeOrdering = true;
+            // For OR + component sortBy, clear the component sort keys for the
+            // inner build so the OR base node (ComponentInclusionNode) emits a
+            // plain unordered id-set — the wrapper below owns all ordering and
+            // its keyset/param accounting. (Entity sorts leave sortOrders empty.)
+            if (useOrComponentSort) {
+                this.context.sortOrders = [];
+            }
+        }
 
-                // OrNode filters on top of the base requirements
-                const orNode = new OrNode(this.orQuery);
-                orNode.addDependency(componentNode);
-                dag.addNode(orNode);
+        // Inner DAG build + entity-sort wrapper run with pagination
+        // neutralized (above). Restore in `finally` so a throw mid-build —
+        // including the entity-sort guards below — can never leave a reused
+        // Query instance with limit/offset/cursor nulled.
+        let result: { sql: string; params: any[]; context: QueryContext };
+        try {
+            // Build the DAG
+            const dag = new QueryDAG();
+
+            // Check if we have an OR query
+            if (this.orQuery) {
+                // For OR queries, we need to ensure entities have all required components first
+                if (this.context.componentIds.size > 0) {
+                    // ComponentInclusionNode is the root, OrNode is the leaf
+                    const componentNode = new ComponentInclusionNode();
+                    dag.setRootNode(componentNode);
+
+                    // OrNode filters on top of the base requirements
+                    const orNode = new OrNode(this.orQuery);
+                    orNode.addDependency(componentNode);
+                    dag.addNode(orNode);
+                } else {
+                    // No base requirements, OrNode is both root and leaf
+                    const orNode = new OrNode(this.orQuery);
+                    dag.setRootNode(orNode);
+                }
             } else {
-                // No base requirements, OrNode is both root and leaf
-                const orNode = new OrNode(this.orQuery);
-                dag.setRootNode(orNode);
+                // Use buildBasicQuery for regular AND logic (includes CTE optimization)
+                const optimizedDag = QueryDAG.buildBasicQuery(this.context);
+                // Copy nodes from optimized DAG to our DAG
+                for (const node of optimizedDag.getNodes()) {
+                    dag.addNode(node);
+                }
+                if (optimizedDag.getRootNode()) {
+                    dag.setRootNode(optimizedDag.getRootNode()!);
+                }
             }
-        } else {
-            // Use buildBasicQuery for regular AND logic (includes CTE optimization)
-            const optimizedDag = QueryDAG.buildBasicQuery(this.context);
-            // Copy nodes from optimized DAG to our DAG
-            for (const node of optimizedDag.getNodes()) {
-                dag.addNode(node);
+
+            // Execute the DAG
+            result = dag.execute(this.context);
+
+            // Wrap the resolved id-set with an outer ORDER BY on the native
+            // entities column(s). result.params === this.context.params (same
+            // ref), so pushing pagination params keeps placeholders sequential.
+            if (useEntitySort) {
+                if (savedCompositeCursor && entitySorts.length > 1) {
+                    throw new Error(
+                        'sortedCursor() does not support multi-key entity sorts. ' +
+                        'Only a single sortByCreatedAt() or sortByUpdatedAt() is supported with composite keyset pagination.'
+                    );
+                }
+
+                const orderClauses = entitySorts.map(s => {
+                    // Hard-mapped allow-list — never interpolate raw input.
+                    const col = s.field === "updated_at" ? "updated_at" : "created_at";
+                    const nulls = s.nullsFirst ? "NULLS FIRST" : "NULLS LAST";
+                    const dir = s.direction === "DESC" ? "DESC" : "ASC";
+                    return `e.${col} ${dir} ${nulls}`;
+                }).join(", ");
+
+                let whereClause = '';
+                if (savedCompositeCursor) {
+                    const isBefore = this.context.cursorDirection === 'before';
+                    if (isBefore) {
+                        // 'before' for sorted entity-column cursors is not yet implemented:
+                        // it requires reversing ORDER BY and post-reversing rows in JS.
+                        // Throw a clear error rather than returning silently wrong pages.
+                        throw new Error(
+                            "sortedCursor(token, 'before') is not supported for sortByCreatedAt()/sortByUpdatedAt(). " +
+                            'Use OFFSET pagination or walk pages forward only.'
+                        );
+                    }
+
+                    // Composite keyset for native entity-column sort.
+                    // We truncate both sides to milliseconds so the JS Date (ms precision)
+                    // matches the stored TIMESTAMPTZ value. Without truncation, a stored
+                    // microsecond timestamp (e.g. 00:00:01.000123) always compares GREATER
+                    // than the ms-truncated cursor (00:00:01.000), causing already-seen
+                    // rows to re-qualify on every subsequent page.
+                    //
+                    // ORDER BY: date_trunc('milliseconds', col) <dir> NULLS x, base.id ASC
+                    // ASC+after:  (trunc_col, id) > ($v, $id)
+                    // DESC+after: trunc_col < $v OR (trunc_col = $v AND id > $id)
+                    const s = entitySorts[0]!;
+                    const rawCol = s.field === "updated_at" ? "e.updated_at" : "e.created_at";
+                    const col = `date_trunc('milliseconds', ${rawCol})`;
+                    const isDesc = s.direction === "DESC";
+                    const { v, id: cursorId } = savedCompositeCursor;
+
+                    if (v === null) {
+                        // After the last non-null row under NULLS LAST: for ASC the NULL
+                        // region follows all non-null rows — they've all been seen, so
+                        // nothing remains (entities.created_at is NOT NULL in practice,
+                        // but handle generically).
+                        whereClause = ' WHERE FALSE';
+                    } else if (!isDesc) {
+                        // ASC+after: row-comparison on truncated timestamp + id tiebreak.
+                        // Include NULL-timestamped rows too (NULLS LAST → they appear at
+                        // the very end, AFTER all non-null rows, so they have not yet been
+                        // visited when we are past a non-null cursor value).
+                        const vIdx = result.params.push(v);
+                        const idGtIdx = result.params.push(cursorId);
+                        whereClause = ` WHERE ((${col}, base.id) > ($${vIdx}::timestamptz, $${idGtIdx}::uuid) OR ${rawCol} IS NULL)`;
+                    } else {
+                        // DESC+after: values come in decreasing order; "after" the cursor
+                        // means smaller truncated timestamp, or same + larger id.
+                        const vLtIdx = result.params.push(v);
+                        const vEqIdx = result.params.push(v);
+                        const idGtIdx = result.params.push(cursorId);
+                        whereClause = ` WHERE (${col} < $${vLtIdx}::timestamptz OR (${col} = $${vEqIdx}::timestamptz AND base.id > $${idGtIdx}::uuid))`;
+                    }
+                }
+
+                // Mirror the ORDER BY truncation in the sort clause so the cursor
+                // comparison and the ORDER BY operate on the same precision.
+                const truncatedOrderClauses = entitySorts.map(s => {
+                    const rawCol = s.field === "updated_at" ? "e.updated_at" : "e.created_at";
+                    const col = `date_trunc('milliseconds', ${rawCol})`;
+                    const nulls = s.nullsFirst ? "NULLS FIRST" : "NULLS LAST";
+                    const dir = s.direction === "DESC" ? "DESC" : "ASC";
+                    return `${col} ${dir} ${nulls}`;
+                }).join(", ");
+                const effectiveOrderClauses = savedCompositeCursor ? truncatedOrderClauses : orderClauses;
+
+                let wrapped = `SELECT base.id FROM (${result.sql}) AS base
+                    JOIN entities e ON e.id = base.id${whereClause}
+                    ORDER BY ${effectiveOrderClauses}, base.id ASC`;
+
+                if (savedLimit !== null) {
+                    result.params.push(savedLimit);
+                    wrapped += ` LIMIT $${result.params.length}`;
+                }
+                // Only add OFFSET when not using cursor-based pagination
+                if (!savedCompositeCursor && (savedOffset > 0 || savedLimit !== null)) {
+                    result.params.push(savedOffset);
+                    wrapped += ` OFFSET $${result.params.length}`;
+                }
+
+                result.sql = wrapped;
+            } else if (useOrComponentSort) {
+                // OR + component sortBy(): wrap the unordered OR id-set with a
+                // JOIN to each sort component's data table and an outer ORDER
+                // BY. The sort component is always a required `.with()`
+                // component (sortBy validates this), and the OR base node
+                // guarantees every result entity has all required components,
+                // so the INNER JOIN never drops a row. Composite keyset
+                // pagination is supported for a single sort key; OFFSET for
+                // any number of keys.
+                if (savedCompositeCursor && componentSorts.length > 1) {
+                    throw new Error(
+                        'sortedCursor() does not support multi-key sorts. ' +
+                        'Only a single sortBy() key is supported with composite keyset pagination on OR queries.'
+                    );
+                }
+
+                const joins: string[] = [];
+                const orderClauses: string[] = [];
+                componentSorts.forEach((s, i) => {
+                    const sortTypeId = ComponentRegistry.getComponentId(s.component);
+                    if (!sortTypeId) {
+                        throw new Error(`Component ${s.component} is not registered.`);
+                    }
+                    const table = shouldUseDirectPartition()
+                        ? (ComponentRegistry.getPartitionTableName(sortTypeId) || 'components')
+                        : 'components';
+                    const safeTable = assertComponentTableName(table, 'orSort.componentTable');
+                    const alias = `s${i}`;
+                    const typeParamIdx = result.params.push(sortTypeId);
+                    joins.push(
+                        `JOIN ${safeTable} ${alias} ON ${alias}.entity_id = base.id ` +
+                        `AND ${alias}.type_id = $${typeParamIdx} AND ${alias}.deleted_at IS NULL`
+                    );
+                    const safeProp = assertIdentifier(s.property, 'sortOrder.property');
+                    const numeric = isNumericProperty(s.component, s.property);
+                    const expr = numeric
+                        ? `(${alias}.data->>'${safeProp}')::numeric`
+                        : `${alias}.data->>'${safeProp}'`;
+                    const dir = s.direction === "DESC" ? "DESC" : "ASC";
+                    const nulls = s.nullsFirst ? "NULLS FIRST" : "NULLS LAST";
+                    orderClauses.push(`${expr} ${dir} ${nulls}`);
+                });
+
+                let whereClause = '';
+                if (savedCompositeCursor) {
+                    const isBefore = this.context.cursorDirection === 'before';
+                    if (isBefore) {
+                        throw new Error(
+                            "sortedCursor(token, 'before') is not supported for OR + sortBy(). " +
+                            'Use OFFSET pagination or walk pages forward only.'
+                        );
+                    }
+                    // Single-key keyset (guarded above). Re-derive the sort
+                    // expression on alias s0; the keyset shape mirrors
+                    // ComponentInclusionNode.buildCompositeCursorWhere exactly.
+                    const s = componentSorts[0]!;
+                    // NULLS FIRST + keyset cannot advance past the leading
+                    // null-block onto non-null rows (the (expr,id) comparison
+                    // never re-admits the front nulls), silently dropping rows.
+                    // Throw a clear error instead of returning wrong pages.
+                    if (s.nullsFirst) {
+                        throw new Error(
+                            'sortedCursor() does not support NULLS FIRST sorts. ' +
+                            'Use the default (NULLS LAST) or OFFSET pagination.'
+                        );
+                    }
+                    const safeProp = assertIdentifier(s.property, 'sortOrder.property');
+                    const numeric = isNumericProperty(s.component, s.property);
+                    const expr = numeric
+                        ? `(s0.data->>'${safeProp}')::numeric`
+                        : `s0.data->>'${safeProp}'`;
+                    const cast = numeric ? '::numeric' : '::text';
+                    const isDesc = s.direction === "DESC";
+                    const nullsLast = !s.nullsFirst;
+                    const { v, id: cursorId } = savedCompositeCursor;
+
+                    if (v === null) {
+                        const idIdx = result.params.push(cursorId);
+                        whereClause = ` WHERE (${expr} IS NULL AND base.id > $${idIdx}::uuid)`;
+                    } else if (!isDesc) {
+                        const vIdx = result.params.push(v);
+                        const idIdx = result.params.push(cursorId);
+                        const nullInclude = nullsLast ? ` OR ${expr} IS NULL` : '';
+                        whereClause = ` WHERE ((${expr}, base.id) > ($${vIdx}${cast}, $${idIdx}::uuid)${nullInclude})`;
+                    } else {
+                        const vLtIdx = result.params.push(v);
+                        const vEqIdx = result.params.push(v);
+                        const idGtIdx = result.params.push(cursorId);
+                        whereClause = ` WHERE (${expr} < $${vLtIdx}${cast} OR (${expr} = $${vEqIdx}${cast} AND base.id > $${idGtIdx}::uuid))`;
+                    }
+                }
+
+                let wrapped = `SELECT base.id FROM (${result.sql}) AS base
+                    ${joins.join(' ')}${whereClause}
+                    ORDER BY ${orderClauses.join(', ')}, base.id ASC`;
+
+                if (savedLimit !== null) {
+                    result.params.push(savedLimit);
+                    wrapped += ` LIMIT $${result.params.length}`;
+                }
+                if (!savedCompositeCursor && (savedOffset > 0 || savedLimit !== null)) {
+                    result.params.push(savedOffset);
+                    wrapped += ` OFFSET $${result.params.length}`;
+                }
+
+                result.sql = wrapped;
             }
-            if (optimizedDag.getRootNode()) {
-                dag.setRootNode(optimizedDag.getRootNode()!);
+        } finally {
+            if (useOuterSortWrapper) {
+                // Restore so the Query instance stays reusable, even if the
+                // DAG build/execute or a sort guard threw above.
+                this.context.limit = savedLimit;
+                this.context.offsetValue = savedOffset;
+                this.context.cursorId = savedCursorId;
+                this.context.compositeCursor = savedCompositeCursor;
+                this.context.suppressNodeOrdering = savedSuppressNodeOrdering;
+                this.context.sortOrders = savedSortOrders;
             }
         }
 
-        // Execute the DAG
-        const result = dag.execute(this.context);
-
         // Get the database connection (transaction or default)
         const dbConn = this.getDb();
 

package/query/QueryContext.ts

@@ -15,6 +15,20 @@ export interface SortOrder {
     nullsFirst?: boolean;
 }
 
+/**
+ * Sort by a native column on the `entities` table (created_at / updated_at).
+ * Unlike SortOrder, this needs no component and no `.with()` — the column
+ * always exists and is indexed-friendly. Applied as an outer ORDER BY in
+ * Query.doExec, invisible to the SQL planner nodes.
+ */
+export type EntitySortField = "created_at" | "updated_at";
+
+export interface EntitySortOrder {
+    field: EntitySortField;
+    direction: "ASC" | "DESC";
+    nullsFirst?: boolean;
+}
+
 export class QueryContext {
     public params: any[] = [];
     public paramIndex: number = 1;
@@ -24,6 +38,10 @@ export class QueryContext {
     public excludedComponentIds: Set<string> = new Set();
     public componentFilters: Map<string, QueryFilter[]> = new Map();
     public sortOrders: SortOrder[] = [];
+    // Native entities-table sorts (created_at/updated_at). Separate channel:
+    // the SQL nodes never read it — Query.doExec wraps the id-set with a
+    // JOIN entities ... ORDER BY. Keeps the component sort paths untouched.
+    public entitySortOrders: EntitySortOrder[] = [];
     public excludedEntityIds: Set<string> = new Set();
     public withId: string | null = null;
     public limit: number | null = null;
@@ -32,6 +50,14 @@ export class QueryContext {
     // Cursor-based pagination (more efficient than OFFSET for large datasets)
     public cursorId: string | null = null;
     public cursorDirection: 'after' | 'before' = 'after';
+
+    /**
+     * Composite keyset cursor for sorted queries.
+     * Encodes both the last row's sort value and its entity_id so the
+     * predicate can be `(sort_expr, entity_id) > ($v, $id)` (or `<` for DESC).
+     * Only set via Query.sortedCursor(); plain .cursor() never sets this.
+     */
+    public compositeCursor: { v: string | null; id: string } | null = null;
     public hasCTE: boolean = false;
     public cteName: string = "";
     public eagerComponents: Set<string> = new Set();
@@ -42,6 +68,12 @@ export class QueryContext {
     // suppressed.
     public hasOrQuery: boolean = false;
 
+    // Set by Query.doExec while building an OR query whose final ordering is
+    // applied by an outer sort wrapper (entity-column or component sortBy).
+    // OrNode honours it by skipping its own `ORDER BY entity_id` so the inner
+    // id-set is not sorted twice (the outer wrapper re-orders the full set).
+    public suppressNodeOrdering: boolean = false;
+
     private trx: SQL | undefined;
     constructor(trx?: SQL) {
         this.trx = trx;
@@ -115,6 +147,9 @@ export class QueryContext {
             .map(s => `${s.component}.${s.property}:${s.direction}`)
             .sort()
             .join(',');
+        const entitySorts = this.entitySortOrders
+            .map(s => `@${s.field}:${s.direction}:${s.nullsFirst ? 'nf' : 'nl'}`)
+            .join(',');
 
         // Extract custom filter operators for cache key differentiation
         const customOperators = this.extractCustomOperators();
@@ -128,7 +163,7 @@ export class QueryContext {
         const excludedEntityCount = this.excludedEntityIds.size;
         const excludedEntitiesKey = excludedEntityCount > 0 ? `|excludedEntities:${excludedEntityCount}` : '';
 
-        const key = `${components}|${excludedComponents}|${filters}|${sorts}|${this.hasCTE}|${this.cteName}|${customOps}|${paginationKey}${excludedEntitiesKey}`;
+        const key = `${components}|${excludedComponents}|${filters}|${sorts}|${entitySorts}|${this.hasCTE}|${this.cteName}|${customOps}|${paginationKey}${excludedEntitiesKey}`;
         return key;
     }
 
@@ -160,17 +195,20 @@ export class QueryContext {
         clone.excludedComponentIds = new Set(this.excludedComponentIds);
         clone.componentFilters = new Map(this.componentFilters);
         clone.sortOrders = [...this.sortOrders];
+        clone.entitySortOrders = [...this.entitySortOrders];
         clone.excludedEntityIds = new Set(this.excludedEntityIds);
         clone.withId = this.withId;
         clone.limit = this.limit;
         clone.offsetValue = this.offsetValue;
         clone.cursorId = this.cursorId;
         clone.cursorDirection = this.cursorDirection;
+        clone.compositeCursor = this.compositeCursor ? { ...this.compositeCursor } : null;
         clone.hasCTE = this.hasCTE;
         clone.cteName = this.cteName;
         clone.eagerComponents = new Set(this.eagerComponents);
         clone.paginationAppliedInCTE = this.paginationAppliedInCTE;
         clone.hasOrQuery = this.hasOrQuery;
+        clone.suppressNodeOrdering = this.suppressNodeOrdering;
         return clone;
     }
 }