@syncular/server 0.0.6-96 → 0.1.0

package/src/d1.ts

@@ -0,0 +1,16 @@
+/**
+ * @syncular/server/d1 - Cloudflare D1 dialect for sync
+ *
+ * Provides a Kysely dialect for Cloudflare D1.
+ * SQLite-compatible — use with @syncular/server/sqlite.
+ */
+
+import type { D1Database } from '@cloudflare/workers-types';
+import { D1Dialect } from 'kysely-d1';
+
+/**
+ * Create the D1 dialect directly.
+ */
+export function createD1Dialect(database: D1Database): D1Dialect {
+  return new D1Dialect({ database });
+}

package/src/dialect/base.ts

@@ -8,9 +8,12 @@
 import type { ScopeValues, SqlFamily, StoredScopes } from '@syncular/core';
 import type { Kysely, RawBuilder, Transaction } from 'kysely';
 import { sql } from 'kysely';
+import { scopeKeysFromScopeValues } from '../helpers/scope-commit-index';
 import type { SyncChangeRow, SyncCommitRow, SyncCoreDb } from '../schema';
 import { coerceIsoString, coerceNumber, parseScopes } from './helpers';
 import type {
+  AuditRowHistoryArgs,
+  AuditRowHistoryRow,
   DbExecutor,
   IncrementalPullRow,
   IncrementalPullRowsArgs,
@@ -34,6 +37,7 @@ export abstract class BaseServerSyncDialect<F extends SqlFamily = SqlFamily>
   abstract readonly family: F;
   abstract readonly supportsForUpdate: boolean;
   abstract readonly supportsSavepoints: boolean;
+  abstract readonly supportsInsertReturning: boolean;
 
   // ===========================================================================
   // Abstract SQL fragment hooks
@@ -57,6 +61,40 @@ export abstract class BaseServerSyncDialect<F extends SqlFamily = SqlFamily>
     values: string[]
   ): RawBuilder<unknown>;
 
+  protected async readScopeIndexedCommitSeqsForPull<DB extends SyncCoreDb>(
+    db: Kysely<DB> | Transaction<DB>,
+    args: {
+      cursor: number;
+      limitCommits: number;
+      table: string;
+      scopes: ScopeValues;
+      partitionId?: string;
+    }
+  ): Promise<number[]> {
+    const partitionId = args.partitionId ?? 'default';
+    const scopeKeys = scopeKeysFromScopeValues(args.scopes);
+    if (scopeKeys.length === 0) return [];
+    const scopeKeysFilter = this.buildStringListFilter(scopeKeys);
+
+    const res = await sql<{ commit_seq: unknown }>`
+      SELECT DISTINCT commit_seq
+      FROM sync_scope_commits
+      WHERE partition_id = ${partitionId}
+        AND "table" = ${args.table}
+        AND scope_key ${scopeKeysFilter}
+        AND commit_seq > ${args.cursor}
+      ORDER BY commit_seq ASC
+      LIMIT ${args.limitCommits}
+    `.execute(db);
+
+    return res.rows
+      .map((r) => coerceNumber(r.commit_seq))
+      .filter(
+        (n): n is number =>
+          typeof n === 'number' && Number.isFinite(n) && n > args.cursor
+      );
+  }
+
   // ===========================================================================
   // Abstract methods (genuinely different implementations)
   // ===========================================================================
@@ -88,6 +126,11 @@ export abstract class BaseServerSyncDialect<F extends SqlFamily = SqlFamily>
     }
   ): Promise<SyncChangeRow[]>;
 
+  abstract readAuditRowHistory<DB extends SyncCoreDb>(
+    db: DbExecutor<DB>,
+    args: AuditRowHistoryArgs
+  ): Promise<AuditRowHistoryRow[]>;
+
   protected abstract readIncrementalPullRowsBatch<DB extends SyncCoreDb>(
     db: DbExecutor<DB>,
     args: Omit<IncrementalPullRowsArgs, 'batchSize'>
@@ -207,8 +250,10 @@ export abstract class BaseServerSyncDialect<F extends SqlFamily = SqlFamily>
       actor_id: string;
       created_at: unknown;
       result_json: unknown | null;
+      commit_digest: string | null;
+      commit_chain_root: string | null;
     }>`
-      SELECT commit_seq, actor_id, created_at, result_json
+      SELECT commit_seq, actor_id, created_at, result_json, commit_digest, commit_chain_root
       FROM sync_commits
       WHERE commit_seq ${seqsFilter}
         AND partition_id = ${partitionId}
@@ -220,6 +265,8 @@ export abstract class BaseServerSyncDialect<F extends SqlFamily = SqlFamily>
       actor_id: row.actor_id,
       created_at: coerceIsoString(row.created_at),
       result_json: row.result_json ?? null,
+      commit_digest: row.commit_digest ?? null,
+      commit_chain_root: row.commit_chain_root ?? null,
     }));
   }
 
@@ -231,19 +278,38 @@ export abstract class BaseServerSyncDialect<F extends SqlFamily = SqlFamily>
       actorId: string;
       cursor: number;
       effectiveScopes: ScopeValues;
+      realtimeSubscriptions?: unknown;
     }
   ): Promise<void> {
     const partitionId = args.partitionId ?? 'default';
     const now = new Date().toISOString();
     const scopesJson = JSON.stringify(args.effectiveScopes);
 
+    if (args.realtimeSubscriptions === undefined) {
+      await sql`
+        INSERT INTO sync_client_cursors (partition_id, client_id, actor_id, cursor, effective_scopes, updated_at)
+        VALUES (${partitionId}, ${args.clientId}, ${args.actorId}, ${args.cursor}, ${scopesJson}, ${now})
+        ON CONFLICT(partition_id, client_id) DO UPDATE SET
+          actor_id = ${args.actorId},
+          cursor = ${args.cursor},
+          effective_scopes = ${scopesJson},
+          updated_at = ${now}
+      `.execute(db);
+      return;
+    }
+
+    const realtimeSubscriptionsJson = JSON.stringify(
+      args.realtimeSubscriptions
+    );
+
     await sql`
-      INSERT INTO sync_client_cursors (partition_id, client_id, actor_id, cursor, effective_scopes, updated_at)
-      VALUES (${partitionId}, ${args.clientId}, ${args.actorId}, ${args.cursor}, ${scopesJson}, ${now})
+      INSERT INTO sync_client_cursors (partition_id, client_id, actor_id, cursor, effective_scopes, realtime_subscriptions, updated_at)
+      VALUES (${partitionId}, ${args.clientId}, ${args.actorId}, ${args.cursor}, ${scopesJson}, ${realtimeSubscriptionsJson}, ${now})
       ON CONFLICT(partition_id, client_id) DO UPDATE SET
         actor_id = ${args.actorId},
         cursor = ${args.cursor},
         effective_scopes = ${scopesJson},
+        realtime_subscriptions = ${realtimeSubscriptionsJson},
         updated_at = ${now}
     `.execute(db);
   }
@@ -252,10 +318,10 @@ export abstract class BaseServerSyncDialect<F extends SqlFamily = SqlFamily>
     db: DbExecutor<DB>,
     args: IncrementalPullRowsArgs
   ): AsyncGenerator<IncrementalPullRow> {
-    const limitCommits = Math.max(1, Math.min(500, args.limitCommits));
+    const limitCommits = Math.max(1, Math.min(1000, args.limitCommits));
     const batchSize = Math.max(
       1,
-      Math.min(limitCommits, args.batchSize ?? 100, 500)
+      Math.min(limitCommits, args.batchSize ?? limitCommits, 1000)
     );
 
     let processedCommits = 0;

package/src/dialect/helpers.ts

@@ -5,6 +5,19 @@
  */
 
 import type { StoredScopes } from '@syncular/core';
+import type { Kysely, Transaction } from 'kysely';
+import type { ServerSyncDialect } from './types';
+
+export function isActiveTransaction<DB>(
+  db: Kysely<DB>
+): db is Kysely<DB> & Transaction<DB> {
+  return (db as { isTransaction?: boolean }).isTransaction === true;
+}
+
+export function createSavepointName(): string {
+  const randomPart = Math.floor(Math.random() * 1_000_000_000).toString(36);
+  return `syncular_sp_${Date.now().toString(36)}_${randomPart}`;
+}
 
 export function coerceNumber(value: unknown): number | null {
   if (value === null || value === undefined) return null;
@@ -24,6 +37,24 @@ export function coerceIsoString(value: unknown): string {
   return String(value);
 }
 
+export function parseJsonValue(value: unknown): unknown {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+export function toDialectJsonValue(
+  dialect: Pick<ServerSyncDialect, 'family'>,
+  value: unknown
+): unknown {
+  if (value === null || value === undefined) return null;
+  if (dialect.family === 'sqlite') return JSON.stringify(value);
+  return value;
+}
+
 export function parseScopes(value: unknown): StoredScopes {
   if (value === null || value === undefined) return {};
   if (typeof value === 'object' && !Array.isArray(value)) {

package/src/dialect/types.ts

@@ -33,8 +33,36 @@ export interface IncrementalPullRowsArgs {
 
 export interface IncrementalPullRow {
   commit_seq: number;
+  scanned_max_commit_seq?: number | null;
   actor_id: string;
   created_at: string;
+  commit_digest: string | null;
+  commit_chain_root: string | null;
+  change_id: number;
+  table: string;
+  row_id: string;
+  op: SyncOp;
+  row_json: unknown | null;
+  row_version: number | null;
+  scopes: StoredScopes;
+}
+
+export interface AuditRowHistoryArgs {
+  table: string;
+  rowId: string;
+  scopes: ScopeValues;
+  limit: number;
+  partitionId?: string;
+  beforeCommitSeq?: number;
+  afterCommitSeq?: number;
+}
+
+export interface AuditRowHistoryRow {
+  commit_seq: number;
+  actor_id: string;
+  client_id: string;
+  client_commit_id: string;
+  created_at: string;
   change_id: number;
   table: string;
   row_id: string;
@@ -123,6 +151,17 @@ export interface ServerSyncDialect<F extends SqlFamily = SqlFamily> {
     args: IncrementalPullRowsArgs
   ): AsyncGenerator<IncrementalPullRow>;
 
+  /**
+   * Read redaction-ready row history for audit views.
+   *
+   * The query must apply the same partition, table, row id, and scope filtering
+   * rules as incremental pull before returning rows to the route layer.
+   */
+  readAuditRowHistory<DB extends SyncCoreDb>(
+    db: DbExecutor<DB>,
+    args: AuditRowHistoryArgs
+  ): Promise<AuditRowHistoryRow[]>;
+
   /**
    * Optional compaction of the change log to reduce storage.
    *
@@ -145,6 +184,7 @@ export interface ServerSyncDialect<F extends SqlFamily = SqlFamily> {
       actorId: string;
       cursor: number;
       effectiveScopes: ScopeValues;
+      realtimeSubscriptions?: unknown;
     }
   ): Promise<void>;
 
@@ -174,6 +214,13 @@ export interface ServerSyncDialect<F extends SqlFamily = SqlFamily> {
    */
   readonly supportsSavepoints: boolean;
 
+  /**
+   * Whether INSERT ... RETURNING is reliable for obtaining inserted rows.
+   * Postgres: true
+   * SQLite variants: false (keep insertId/fallback select for broad compatibility)
+   */
+  readonly supportsInsertReturning: boolean;
+
   /**
    * Read distinct tables from sync_changes for a given commit.
    * Used for realtime notifications.