@syncular/server 0.0.1-100

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dialect/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/dialect/index.js

@@ -0,0 +1,7 @@
+/**
+ * @syncular/server - Dialect exports
+ */
+export * from './base.js';
+export * from './helpers.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/dialect/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dialect/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/dialect/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @syncular/server - Server Sync Dialect Interface
+ *
+ * Abstracts database-specific operations for commit-log sync.
+ * Supports the new JSONB scopes model.
+ */
+import type { ScopeValues, StoredScopes, SyncOp } from '@syncular/core';
+import type { Kysely, Transaction } from 'kysely';
+import type { SyncChangeRow, SyncCommitRow, SyncCoreDb } from '../schema';
+/**
+ * Common database executor type that works with both Kysely and Transaction.
+ * Generic version allows for extended database types that include sync tables.
+ */
+export type DbExecutor<DB extends SyncCoreDb = SyncCoreDb> = Kysely<DB> | Transaction<DB>;
+/**
+ * Supported dialect names.
+ */
+export type ServerSyncDialectName = string;
+export interface IncrementalPullRowsArgs {
+    table: string;
+    scopes: ScopeValues;
+    cursor: number;
+    limitCommits: number;
+    partitionId?: string;
+    batchSize?: number;
+}
+export interface IncrementalPullRow {
+    commit_seq: number;
+    actor_id: string;
+    created_at: string;
+    change_id: number;
+    table: string;
+    row_id: string;
+    op: SyncOp;
+    row_json: unknown | null;
+    row_version: number | null;
+    scopes: StoredScopes;
+}
+export interface ServerSyncDialect {
+    readonly name: ServerSyncDialectName;
+    /** Create sync tables + indexes (idempotent) */
+    ensureSyncSchema<DB extends SyncCoreDb>(db: Kysely<DB>): Promise<void>;
+    /** Create console-specific tables (e.g., sync_request_events) - optional */
+    ensureConsoleSchema?<DB extends SyncCoreDb>(db: Kysely<DB>): Promise<void>;
+    /** Execute callback in a transaction (or directly if transactions not supported). */
+    executeInTransaction<DB extends SyncCoreDb, T>(db: Kysely<DB>, fn: (executor: DbExecutor<DB>) => Promise<T>): Promise<T>;
+    /** Set REPEATABLE READ (or closest equivalent) */
+    setRepeatableRead<DB extends SyncCoreDb>(trx: DbExecutor<DB>): Promise<void>;
+    /** Read the maximum committed commit_seq (0 if none) */
+    readMaxCommitSeq<DB extends SyncCoreDb>(db: DbExecutor<DB>, options?: {
+        partitionId?: string;
+    }): Promise<number>;
+    /** Read the minimum committed commit_seq (0 if none) */
+    readMinCommitSeq<DB extends SyncCoreDb>(db: DbExecutor<DB>, options?: {
+        partitionId?: string;
+    }): Promise<number>;
+    /**
+     * Read the next commit sequence numbers that have changes for the given tables.
+     * Must return commit_seq values in ascending order.
+     */
+    readCommitSeqsForPull<DB extends SyncCoreDb>(db: DbExecutor<DB>, args: {
+        cursor: number;
+        limitCommits: number;
+        tables: string[];
+        partitionId?: string;
+    }): Promise<number[]>;
+    /** Read commit metadata for commit_seq values */
+    readCommits<DB extends SyncCoreDb>(db: DbExecutor<DB>, commitSeqs: number[], options?: {
+        partitionId?: string;
+    }): Promise<SyncCommitRow[]>;
+    /**
+     * Read changes for commit_seq values, filtered by table and scopes.
+     * Uses JSONB filtering for scope matching.
+     */
+    readChangesForCommits<DB extends SyncCoreDb>(db: DbExecutor<DB>, args: {
+        commitSeqs: number[];
+        table: string;
+        scopes: ScopeValues;
+        partitionId?: string;
+    }): Promise<SyncChangeRow[]>;
+    /**
+     * Incremental pull iterator for a subscription.
+     *
+     * Yields change rows joined with commit metadata and filtered by
+     * the subscription's table and scope values.
+     */
+    iterateIncrementalPullRows<DB extends SyncCoreDb>(db: DbExecutor<DB>, args: IncrementalPullRowsArgs): AsyncGenerator<IncrementalPullRow>;
+    /**
+     * Optional compaction of the change log to reduce storage.
+     *
+     * Keeps full history for the most recent N hours.
+     * For older history, keeps only the newest change per (table, row_id, scopes).
+     */
+    compactChanges<DB extends SyncCoreDb>(db: DbExecutor<DB>, args: {
+        fullHistoryHours: number;
+    }): Promise<number>;
+    /**
+     * Record/update a client cursor for tracking and pruning.
+     */
+    recordClientCursor<DB extends SyncCoreDb>(db: DbExecutor<DB>, args: {
+        partitionId?: string;
+        clientId: string;
+        actorId: string;
+        cursor: number;
+        effectiveScopes: ScopeValues;
+    }): Promise<void>;
+    /**
+     * Convert a StoredScopes object to database representation.
+     * For Postgres: returns as-is (native JSONB)
+     * For SQLite: returns JSON.stringify()
+     */
+    scopesToDb(scopes: StoredScopes): unknown;
+    /**
+     * Convert database scopes representation to StoredScopes.
+     */
+    dbToScopes(value: unknown): StoredScopes;
+    /**
+     * Whether the dialect supports SELECT ... FOR UPDATE row locking.
+     * Postgres: true
+     * SQLite: false (uses database-level locking)
+     */
+    readonly supportsForUpdate: boolean;
+    /**
+     * Whether the dialect supports SAVEPOINT / ROLLBACK TO SAVEPOINT.
+     * Postgres/SQLite: true
+     * D1 (Durable Object): false (blocks raw SAVEPOINT statements)
+     */
+    readonly supportsSavepoints: boolean;
+    /**
+     * Read distinct tables from sync_changes for a given commit.
+     * Used for realtime notifications.
+     */
+    readAffectedTablesFromChanges<DB extends SyncCoreDb>(db: DbExecutor<DB>, commitSeq: number, options?: {
+        partitionId?: string;
+    }): Promise<string[]>;
+    /**
+     * Convert database array representation to string[].
+     * For Postgres: returns as-is (native array)
+     * For SQLite: returns JSON.parse() or empty array if null
+     */
+    dbToArray(value: unknown): string[];
+    /**
+     * Convert string[] to database array representation.
+     * For Postgres: returns as-is (native array)
+     * For SQLite: returns JSON.stringify()
+     */
+    arrayToDb(values: string[]): unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/dialect/types.d.ts.map

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

package/dist/dialect/types.js

@@ -0,0 +1,8 @@
+/**
+ * @syncular/server - Server Sync Dialect Interface
+ *
+ * Abstracts database-specific operations for commit-log sync.
+ * Supports the new JSONB scopes model.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/dialect/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/dialect/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/helpers/conflict.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @syncular/server - Conflict result builder
+ *
+ * Helper for building conflict results in server table handlers.
+ */
+import type { ApplyOperationResult } from '../shapes/types';
+export interface BuildConflictResultArgs {
+    /** Index of the operation in the batch */
+    opIndex: number;
+    /** Current server row data */
+    serverRow: unknown;
+    /** Current server version */
+    serverVersion: number;
+    /** Client's base version (what they thought they were updating) */
+    baseVersion: number | null;
+}
+/**
+ * Build a conflict result for applyOperation.
+ *
+ * Use this when the client's base version doesn't match the server's current version,
+ * indicating a concurrent modification conflict.
+ *
+ * @example
+ * ```typescript
+ * const handler: ServerTableHandler = {
+ *   table: 'tasks',
+ *   async applyOperation(ctx, op, opIndex) {
+ *     const existing = await ctx.db
+ *       .selectFrom('tasks')
+ *       .selectAll()
+ *       .where('id', '=', op.row_id)
+ *       .executeTakeFirst();
+ *
+ *     // Check for version conflict
+ *     if (existing && op.base_version !== null && existing.version !== op.base_version) {
+ *       return {
+ *         result: buildConflictResult({
+ *           opIndex,
+ *           serverRow: existing,
+ *           serverVersion: existing.version,
+ *           baseVersion: op.base_version,
+ *         }),
+ *       };
+ *     }
+ *
+ *     // ... apply the operation
+ *   },
+ * };
+ * ```
+ */
+export declare function buildConflictResult(args: BuildConflictResultArgs): ApplyOperationResult['result'];
+//# sourceMappingURL=conflict.d.ts.map

package/dist/helpers/conflict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict.d.ts","sourceRoot":"","sources":["../../src/helpers/conflict.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,SAAS,EAAE,OAAO,CAAC;IACnB,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,uBAAuB,GAC5B,oBAAoB,CAAC,QAAQ,CAAC,CAQhC"}

package/dist/helpers/conflict.js

@@ -0,0 +1,49 @@
+/**
+ * @syncular/server - Conflict result builder
+ *
+ * Helper for building conflict results in server table handlers.
+ */
+/**
+ * Build a conflict result for applyOperation.
+ *
+ * Use this when the client's base version doesn't match the server's current version,
+ * indicating a concurrent modification conflict.
+ *
+ * @example
+ * ```typescript
+ * const handler: ServerTableHandler = {
+ *   table: 'tasks',
+ *   async applyOperation(ctx, op, opIndex) {
+ *     const existing = await ctx.db
+ *       .selectFrom('tasks')
+ *       .selectAll()
+ *       .where('id', '=', op.row_id)
+ *       .executeTakeFirst();
+ *
+ *     // Check for version conflict
+ *     if (existing && op.base_version !== null && existing.version !== op.base_version) {
+ *       return {
+ *         result: buildConflictResult({
+ *           opIndex,
+ *           serverRow: existing,
+ *           serverVersion: existing.version,
+ *           baseVersion: op.base_version,
+ *         }),
+ *       };
+ *     }
+ *
+ *     // ... apply the operation
+ *   },
+ * };
+ * ```
+ */
+export function buildConflictResult(args) {
+    return {
+        opIndex: args.opIndex,
+        status: 'conflict',
+        message: `Version conflict: server=${args.serverVersion}, base=${args.baseVersion}`,
+        server_version: args.serverVersion,
+        server_row: args.serverRow,
+    };
+}
+//# sourceMappingURL=conflict.js.map

package/dist/helpers/conflict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conflict.js","sourceRoot":"","sources":["../../src/helpers/conflict.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAA6B,EACG;IAChC,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,UAAU;QAClB,OAAO,EAAE,4BAA4B,IAAI,CAAC,aAAa,UAAU,IAAI,CAAC,WAAW,EAAE;QACnF,cAAc,EAAE,IAAI,CAAC,aAAa;QAClC,UAAU,EAAE,IAAI,CAAC,SAAS;KAC3B,CAAC;AAAA,CACH"}

package/dist/helpers/emitted-change.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @syncular/server - Emitted change builder
+ *
+ * Helper for creating emitted changes in server table handlers.
+ */
+import type { StoredScopes } from '@syncular/core';
+import type { EmittedChange } from '../shapes/types';
+export interface CreateEmittedChangeArgs {
+    /** Table name */
+    table: string;
+    /** Row primary key */
+    rowId: string;
+    /** Operation type */
+    op: 'upsert' | 'delete';
+    /** Row data (null for delete) */
+    row: unknown | null;
+    /** Row version (null if not versioned) */
+    version: number | null;
+    /**
+     * Scope values for this change (stored as JSONB).
+     * Example: { user_id: 'U1', project_id: 'P1' }
+     */
+    scopes: StoredScopes;
+}
+/**
+ * Create an emitted change for broadcasting to subscribed clients.
+ *
+ * @example
+ * ```typescript
+ * const handler: ServerTableHandler = {
+ *   table: 'tasks',
+ *   async applyOperation(ctx, op, opIndex) {
+ *     // ... apply the operation ...
+ *
+ *     const newVersion = await getTaskVersion(ctx.db, op.row_id);
+ *     const updatedRow = await getTask(ctx.db, op.row_id);
+ *
+ *     return {
+ *       result: { opIndex, status: 'applied', newVersion },
+ *       emittedChanges: [
+ *         createEmittedChange({
+ *           table: 'tasks',
+ *           rowId: op.row_id,
+ *           op: 'upsert',
+ *           row: updatedRow,
+ *           version: newVersion,
+ *           scopes: { user_id: updatedRow.user_id },
+ *         }),
+ *       ],
+ *     };
+ *   },
+ * };
+ * ```
+ */
+export declare function createEmittedChange(args: CreateEmittedChangeArgs): EmittedChange;
+//# sourceMappingURL=emitted-change.d.ts.map

package/dist/helpers/emitted-change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitted-change.d.ts","sourceRoot":"","sources":["../../src/helpers/emitted-change.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,uBAAuB;IACtC,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,EAAE,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACxB,iCAAiC;IACjC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACpB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,uBAAuB,GAC5B,aAAa,CASf"}

package/dist/helpers/emitted-change.js

@@ -0,0 +1,46 @@
+/**
+ * @syncular/server - Emitted change builder
+ *
+ * Helper for creating emitted changes in server table handlers.
+ */
+/**
+ * Create an emitted change for broadcasting to subscribed clients.
+ *
+ * @example
+ * ```typescript
+ * const handler: ServerTableHandler = {
+ *   table: 'tasks',
+ *   async applyOperation(ctx, op, opIndex) {
+ *     // ... apply the operation ...
+ *
+ *     const newVersion = await getTaskVersion(ctx.db, op.row_id);
+ *     const updatedRow = await getTask(ctx.db, op.row_id);
+ *
+ *     return {
+ *       result: { opIndex, status: 'applied', newVersion },
+ *       emittedChanges: [
+ *         createEmittedChange({
+ *           table: 'tasks',
+ *           rowId: op.row_id,
+ *           op: 'upsert',
+ *           row: updatedRow,
+ *           version: newVersion,
+ *           scopes: { user_id: updatedRow.user_id },
+ *         }),
+ *       ],
+ *     };
+ *   },
+ * };
+ * ```
+ */
+export function createEmittedChange(args) {
+    return {
+        table: args.table,
+        row_id: args.rowId,
+        op: args.op,
+        row_json: args.op === 'delete' ? null : args.row,
+        row_version: args.version,
+        scopes: args.scopes,
+    };
+}
+//# sourceMappingURL=emitted-change.js.map

package/dist/helpers/emitted-change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitted-change.js","sourceRoot":"","sources":["../../src/helpers/emitted-change.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAA6B,EACd;IACf,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EAAE,IAAI,CAAC,KAAK;QAClB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,QAAQ,EAAE,IAAI,CAAC,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG;QAChD,WAAW,EAAE,IAAI,CAAC,OAAO;QACzB,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC;AAAA,CACH"}

package/dist/helpers/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @syncular/server - Helper utilities
+ *
+ * Convenience helpers for implementing server table handlers.
+ */
+export * from './conflict';
+export * from './emitted-change';
+export * from './paginate';
+export * from './scope-strings';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/dist/helpers/index.js

@@ -0,0 +1,10 @@
+/**
+ * @syncular/server - Helper utilities
+ *
+ * Convenience helpers for implementing server table handlers.
+ */
+export * from './conflict.js';
+export * from './emitted-change.js';
+export * from './paginate.js';
+export * from './scope-strings.js';
+//# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/dist/helpers/paginate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @syncular/server - Pagination helper
+ *
+ * Simplifies cursor-based pagination for snapshot queries.
+ */
+import type { SelectQueryBuilder } from 'kysely';
+export interface PaginateOptions {
+    /** Cursor value to start from (null for first page) */
+    cursor: string | null;
+    /** Number of rows per page */
+    limit: number;
+    /** Column to use for cursor-based pagination (default: 'id') */
+    cursorColumn?: string;
+}
+export interface PaginateResult<T> {
+    /** Rows for this page */
+    rows: T[];
+    /** Cursor for next page (null if no more pages) */
+    nextCursor: string | null;
+}
+/**
+ * Apply cursor-based pagination to a Kysely query.
+ *
+ * This helper simplifies implementing snapshot pagination by:
+ * - Applying cursor filter if provided
+ * - Ordering by the cursor column
+ * - Fetching limit + 1 to determine if there's a next page
+ * - Computing the next cursor
+ *
+ * @example
+ * ```typescript
+ * const handler: ServerTableHandler = {
+ *   table: 'tasks',
+ *   async snapshot(ctx) {
+ *     const query = ctx.db
+ *       .selectFrom('tasks')
+ *       .selectAll()
+ *       .where('user_id', '=', ctx.actorId);
+ *
+ *     return paginate(query, {
+ *       cursor: ctx.cursor,
+ *       limit: ctx.limit,
+ *     });
+ *   },
+ * };
+ * ```
+ */
+export declare function paginate<T>(query: SelectQueryBuilder<any, any, T>, options: PaginateOptions): Promise<PaginateResult<T>>;
+//# sourceMappingURL=paginate.d.ts.map

package/dist/helpers/paginate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.d.ts","sourceRoot":"","sources":["../../src/helpers/paginate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,yBAAyB;IACzB,IAAI,EAAE,CAAC,EAAE,CAAC;IACV,mDAAmD;IACnD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,KAAK,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,EACtC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CA2B5B"}

package/dist/helpers/paginate.js

@@ -0,0 +1,54 @@
+/**
+ * @syncular/server - Pagination helper
+ *
+ * Simplifies cursor-based pagination for snapshot queries.
+ */
+/**
+ * Apply cursor-based pagination to a Kysely query.
+ *
+ * This helper simplifies implementing snapshot pagination by:
+ * - Applying cursor filter if provided
+ * - Ordering by the cursor column
+ * - Fetching limit + 1 to determine if there's a next page
+ * - Computing the next cursor
+ *
+ * @example
+ * ```typescript
+ * const handler: ServerTableHandler = {
+ *   table: 'tasks',
+ *   async snapshot(ctx) {
+ *     const query = ctx.db
+ *       .selectFrom('tasks')
+ *       .selectAll()
+ *       .where('user_id', '=', ctx.actorId);
+ *
+ *     return paginate(query, {
+ *       cursor: ctx.cursor,
+ *       limit: ctx.limit,
+ *     });
+ *   },
+ * };
+ * ```
+ */
+export async function paginate(query, options) {
+    const { cursor, limit, cursorColumn = 'id' } = options;
+    // Apply cursor filter if resuming from a previous page
+    let q = query;
+    if (cursor) {
+        q = q.where(cursorColumn, '>', cursor);
+    }
+    // Order by cursor column and fetch limit + 1 to check for more pages
+    const rows = await q
+        .orderBy(cursorColumn, 'asc')
+        .limit(limit + 1)
+        .execute();
+    // Determine if there are more pages
+    const hasMore = rows.length > limit;
+    const pageRows = hasMore ? rows.slice(0, limit) : rows;
+    // Compute next cursor from last row
+    const nextCursor = hasMore
+        ? (pageRows[pageRows.length - 1]?.[cursorColumn] ?? null)
+        : null;
+    return { rows: pageRows, nextCursor };
+}
+//# sourceMappingURL=paginate.js.map

package/dist/helpers/paginate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginate.js","sourceRoot":"","sources":["../../src/helpers/paginate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,KAAsC,EACtC,OAAwB,EACI;IAC5B,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAEvD,uDAAuD;IACvD,IAAI,CAAC,GAAG,KAAK,CAAC;IACd,IAAI,MAAM,EAAE,CAAC;QACX,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,MAAM,CAAa,CAAC;IACrD,CAAC;IAED,qEAAqE;IACrE,MAAM,IAAI,GAAG,MAAM,CAAC;SACjB,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC;SAC5B,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;SAChB,OAAO,EAAE,CAAC;IAEb,oCAAoC;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEvD,oCAAoC;IACpC,MAAM,UAAU,GAAG,OAAO;QACxB,CAAC,CAAC,CAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAA6B,EAAE,CAC5D,YAAY,CACF,IAAI,IAAI,CAAC;QACvB,CAAC,CAAC,IAAI,CAAC;IAET,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAAA,CACvC"}

package/dist/helpers/scope-strings.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @syncular/server - Scope string utilities
+ *
+ * Helpers for creating and parsing scope strings.
+ * Scope strings identify partitions of data for sync subscriptions.
+ */
+/**
+ * Result from parsing a scope key
+ */
+interface ParsedScopeKey {
+    /** The prefix (first segment) */
+    prefix: string;
+    /** The remaining values (segments after prefix) */
+    values: string[];
+}
+/**
+ * Create a scope string from a prefix and values.
+ *
+ * Scope strings use colon separators: `prefix:value1:value2`
+ *
+ * @example
+ * ```typescript
+ * // Simple scope string
+ * createScopeKey('user', 'alice')
+ * // => 'user:alice'
+ *
+ * // Multi-value scope string
+ * createScopeKey('user', 'alice', 'project', 'proj-1')
+ * // => 'user:alice:project:proj-1'
+ * ```
+ */
+export declare function createScopeKey(prefix: string, ...values: string[]): string;
+/**
+ * Parse a scope string into its prefix and values.
+ *
+ * Returns null if the key is invalid or doesn't match the expected prefix.
+ *
+ * @example
+ * ```typescript
+ * // Parse any scope string
+ * parseScopeKey('user:alice')
+ * // => { prefix: 'user', values: ['alice'] }
+ *
+ * // Parse with expected prefix
+ * parseScopeKey('user:alice', 'user')
+ * // => { prefix: 'user', values: ['alice'] }
+ *
+ * // Returns null if prefix doesn't match
+ * parseScopeKey('user:alice', 'project')
+ * // => null
+ *
+ * // Multi-value scope string
+ * parseScopeKey('user:alice:project:proj-1')
+ * // => { prefix: 'user', values: ['alice', 'project', 'proj-1'] }
+ * ```
+ */
+export declare function parseScopeKey(key: string, expectedPrefix?: string): ParsedScopeKey | null;
+/**
+ * Extract a specific value from a scope string by index.
+ *
+ * @example
+ * ```typescript
+ * // Get first value after prefix
+ * getScopeKeyValue('user:alice:project:proj-1', 0)
+ * // => 'alice'
+ *
+ * // Get second value
+ * getScopeKeyValue('user:alice:project:proj-1', 2)
+ * // => 'proj-1'
+ * ```
+ */
+export declare function getScopeKeyValue(key: string, valueIndex: number): string | null;
+export type { ParsedScopeKey };
+//# sourceMappingURL=scope-strings.d.ts.map

package/dist/helpers/scope-strings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-strings.d.ts","sourceRoot":"","sources":["../../src/helpers/scope-strings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,UAAU,cAAc;IACtB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAE1E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,cAAc,CAAC,EAAE,MAAM,GACtB,cAAc,GAAG,IAAI,CAWvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAIf;AAED,YAAY,EAAE,cAAc,EAAE,CAAC"}