@syncular/server 0.0.6-95 → 0.1.0

package/src/index.ts

@@ -9,20 +9,26 @@
  */
 export * from '@syncular/core';
 
+export * from './auth-leases';
 export * from './blobs';
 export * from './clients';
+export * from './commit-integrity';
 export * from './compaction';
 export * from './dialect';
+export * from './encrypted-crdt';
+export * from './errors';
 export * from './handlers';
 export * from './helpers';
 export * from './migrate';
 export * from './notify';
+export * from './plugins';
 export * from './proxy';
 export * from './prune';
 export * from './pull';
 export * from './push';
 export * from './realtime';
 export * from './schema';
+export * from './snapshot-artifacts';
 export * from './snapshot-chunks';
 export type { SnapshotChunkStorage } from './snapshot-chunks/types';
 export * from './stats';

package/src/libsql.ts

@@ -0,0 +1,51 @@
+/**
+ * @syncular/server/libsql - LibSQL/Turso dialect for sync
+ *
+ * Provides a Kysely dialect for LibSQL/Turso.
+ * SQLite-compatible — use with @syncular/server/sqlite.
+ */
+
+import { SqliteDialect } from 'kysely';
+import Database from 'libsql';
+
+type LibsqlNativeOptions = NonNullable<
+  ConstructorParameters<typeof Database>[1]
+>;
+
+export interface LibsqlOptions {
+  /** LibSQL URL or local SQLite filename (e.g. `:memory:` or `./data.db`). */
+  url: string;
+
+  /** Auth token for remote databases (e.g. Turso). */
+  authToken?: string;
+
+  /**
+   * Optional sync URL for embedded replicas.
+   *
+   * When set, `Database.sync()` is called once during initialization.
+   */
+  syncUrl?: string;
+
+  /** Pass-through options to libsql-js. */
+  nativeOptions?: LibsqlNativeOptions;
+}
+
+/**
+ * Create the LibSQL dialect directly.
+ */
+export function createLibsqlDialect(options: LibsqlOptions): SqliteDialect {
+  const { url, authToken, syncUrl, nativeOptions } = options;
+
+  const mergedOptions: LibsqlNativeOptions & { authToken?: string } = {
+    ...nativeOptions,
+    ...(syncUrl ? { syncUrl } : {}),
+    ...(authToken ? { authToken } : {}),
+  };
+
+  const database = new Database(url, mergedOptions);
+  if (syncUrl) {
+    database.sync();
+  }
+
+  return new SqliteDialect({ database });
+}

package/src/neon.ts

@@ -0,0 +1,28 @@
+/**
+ * @syncular/server/neon - Neon serverless Postgres dialect for sync
+ *
+ * Provides a Kysely dialect for Neon serverless Postgres (HTTP).
+ * Postgres-compatible — use with @syncular/server/postgres.
+ *
+ * Note: Uses Neon's HTTP driver for stateless queries — ideal for
+ * serverless/edge environments. Does not support interactive transactions.
+ * For transaction support, use Neon's WebSocket pool with Kysely's
+ * built-in PostgresDialect instead.
+ */
+
+import { neon } from '@neondatabase/serverless';
+import { NeonDialect } from 'kysely-neon';
+
+export interface NeonOptions {
+  /** Neon Postgres connection string */
+  connectionString: string;
+}
+
+/**
+ * Create the Neon dialect directly.
+ */
+export function createNeonDialect(options: NeonOptions): NeonDialect {
+  return new NeonDialect({
+    neon: neon(options.connectionString),
+  });
+}

package/src/notify.ts

@@ -8,9 +8,12 @@
  * ensuring clients receive the updated data.
  */
 
-import { randomId } from '@syncular/core';
+import { randomId, type StoredScopes } from '@syncular/core';
 import type { Insertable, Kysely } from 'kysely';
+import { finalizeCommitIntegrity } from './commit-integrity';
+import { coerceNumber, toDialectJsonValue } from './dialect/helpers';
 import type { ServerSyncDialect } from './dialect/types';
+import { createScopeCommitIndexEntries } from './helpers/scope-commit-index';
 import type { SyncCoreDb } from './schema';
 
 /**
@@ -19,31 +22,6 @@ import type { SyncCoreDb } from './schema';
  */
 export const EXTERNAL_CLIENT_ID = '__external__';
 
-function toDialectJsonValue(
-  dialect: ServerSyncDialect,
-  value: unknown
-): unknown {
-  if (value === null || value === undefined) return null;
-  if (dialect.family === 'sqlite') return JSON.stringify(value);
-  return value;
-}
-
-function coerceNumber(value: unknown): number | null {
-  if (value === null || value === undefined) return null;
-  if (typeof value === 'number') {
-    return Number.isFinite(value) ? value : null;
-  }
-  if (typeof value === 'bigint') {
-    const coerced = Number(value);
-    return Number.isFinite(coerced) ? coerced : null;
-  }
-  if (typeof value === 'string') {
-    const coerced = Number(value);
-    return Number.isFinite(coerced) ? coerced : null;
-  }
-  return null;
-}
-
 export interface NotifyExternalDataChangeArgs<DB extends SyncCoreDb> {
   db: Kysely<DB>;
   dialect: ServerSyncDialect;
@@ -64,6 +42,29 @@ export interface NotifyExternalDataChangeResult {
   deletedChunks: number;
 }
 
+export interface ExternalRowChange {
+  table: string;
+  rowId: string;
+  op: 'upsert' | 'delete';
+  rowJson: unknown | null;
+  rowVersion: number | null;
+  scopes: StoredScopes;
+}
+
+export interface NotifyExternalRowChangesArgs<DB extends SyncCoreDb> {
+  db: Kysely<DB>;
+  dialect: ServerSyncDialect;
+  changes: ExternalRowChange[];
+  partitionId?: string;
+  actorId?: string;
+}
+
+export interface NotifyExternalRowChangesResult {
+  commitSeq: number;
+  tables: string[];
+  changeCount: number;
+}
+
 /**
  * Notify the sync framework about external data changes.
  *
@@ -80,8 +81,11 @@ export async function notifyExternalDataChange<DB extends SyncCoreDb>(
   const { db, dialect, tables } = args;
   const partitionId = args.partitionId ?? 'default';
   const actorId = args.actorId ?? EXTERNAL_CLIENT_ID;
+  const uniqueTables = Array.from(
+    new Set(tables.filter((table) => typeof table === 'string'))
+  );
 
-  if (tables.length === 0) {
+  if (uniqueTables.length === 0) {
     throw new Error('notifyExternalDataChange: tables must not be empty');
   }
 
@@ -103,15 +107,25 @@ export async function notifyExternalDataChange<DB extends SyncCoreDb>(
       meta: null,
       result_json: toDialectJsonValue(dialect, { ok: true, status: 'applied' }),
       change_count: 0,
-      affected_tables: dialect.arrayToDb(tables) as string[],
+      affected_tables: dialect.arrayToDb(uniqueTables) as string[],
     };
 
-    const insertResult = await syncTrx
-      .insertInto('sync_commits')
-      .values(commitRow)
-      .executeTakeFirstOrThrow();
+    let commitSeq = 0;
+    if (dialect.supportsInsertReturning) {
+      const insertedCommit = await syncTrx
+        .insertInto('sync_commits')
+        .values(commitRow)
+        .returning(['commit_seq'])
+        .executeTakeFirstOrThrow();
+      commitSeq = coerceNumber(insertedCommit.commit_seq) ?? 0;
+    } else {
+      const insertResult = await syncTrx
+        .insertInto('sync_commits')
+        .values(commitRow)
+        .executeTakeFirstOrThrow();
+      commitSeq = coerceNumber(insertResult.insertId) ?? 0;
+    }
 
-    let commitSeq = coerceNumber(insertResult.insertId) ?? 0;
     if (commitSeq <= 0) {
       // Fallback for dialects/drivers that don't provide insertId.
       const inserted = await syncTrx
@@ -126,7 +140,7 @@ export async function notifyExternalDataChange<DB extends SyncCoreDb>(
 
     // 2. Insert sync_table_commits entries for each affected table
     const tableCommits: Array<Insertable<SyncCoreDb['sync_table_commits']>> =
-      tables.map((table) => ({
+      uniqueTables.map((table) => ({
         partition_id: partitionId,
         table,
         commit_seq: commitSeq,
@@ -140,22 +154,188 @@ export async function notifyExternalDataChange<DB extends SyncCoreDb>(
       )
       .execute();
 
-    // 3. Delete cached snapshot chunks for affected tables
-    let deletedChunks = 0;
-    for (const table of tables) {
-      const result = await syncTrx
-        .deleteFrom('sync_snapshot_chunks')
+    // 3. Delete cached snapshot chunks for affected tables.
+    const deletedResult = await syncTrx
+      .deleteFrom('sync_snapshot_chunks')
+      .where('partition_id', '=', partitionId)
+      .where('scope', 'in', uniqueTables)
+      .executeTakeFirst();
+    const deletedChunks = Number(deletedResult?.numDeletedRows ?? 0);
+
+    await finalizeCommitIntegrity({
+      db: trx,
+      dialect,
+      partitionId,
+      commitSeq,
+    });
+
+    return {
+      commitSeq,
+      tables: uniqueTables,
+      deletedChunks,
+    };
+  });
+}
+
+/**
+ * Notify the sync framework about external row-level changes without forcing
+ * affected subscriptions to re-bootstrap.
+ *
+ * Use this when the external writer knows the exact changed rows, versions, and
+ * scopes. It writes a synthetic incremental commit into the Syncular commit log
+ * so subsequent pulls can continue incrementally.
+ */
+export async function notifyExternalRowChanges<DB extends SyncCoreDb>(
+  args: NotifyExternalRowChangesArgs<DB>
+): Promise<NotifyExternalRowChangesResult> {
+  const { db, dialect, changes } = args;
+  const partitionId = args.partitionId ?? 'default';
+  const actorId = args.actorId ?? EXTERNAL_CLIENT_ID;
+  const normalizedChanges = changes.filter(
+    (change) =>
+      typeof change.table === 'string' &&
+      change.table.length > 0 &&
+      typeof change.rowId === 'string' &&
+      change.rowId.length > 0
+  );
+
+  if (normalizedChanges.length === 0) {
+    throw new Error('notifyExternalRowChanges: changes must not be empty');
+  }
+
+  return dialect.executeInTransaction(db, async (trx) => {
+    type SyncTrx = Pick<
+      Kysely<SyncCoreDb>,
+      'selectFrom' | 'insertInto' | 'updateTable' | 'deleteFrom'
+    >;
+    const syncTrx = trx as SyncTrx;
+    const clientCommitId = `ext_rows_${Date.now()}_${randomId()}`;
+
+    const commitRow: Insertable<SyncCoreDb['sync_commits']> = {
+      partition_id: partitionId,
+      actor_id: actorId,
+      client_id: EXTERNAL_CLIENT_ID,
+      client_commit_id: clientCommitId,
+      meta: null,
+      result_json: null,
+      change_count: normalizedChanges.length,
+      affected_tables: dialect.arrayToDb(
+        Array.from(
+          new Set(normalizedChanges.map((change) => change.table))
+        ).sort()
+      ) as string[],
+    };
+
+    let commitSeq = 0;
+    if (dialect.supportsInsertReturning) {
+      const insertedCommit = await syncTrx
+        .insertInto('sync_commits')
+        .values(commitRow)
+        .returning(['commit_seq'])
+        .executeTakeFirstOrThrow();
+      commitSeq = coerceNumber(insertedCommit.commit_seq) ?? 0;
+    } else {
+      const insertResult = await syncTrx
+        .insertInto('sync_commits')
+        .values(commitRow)
+        .executeTakeFirstOrThrow();
+      commitSeq = coerceNumber(insertResult.insertId) ?? 0;
+    }
+
+    if (commitSeq <= 0) {
+      const inserted = await syncTrx
+        .selectFrom('sync_commits')
+        .select(['commit_seq'])
         .where('partition_id', '=', partitionId)
-        .where('scope', '=', table)
-        .executeTakeFirst();
+        .where('client_id', '=', EXTERNAL_CLIENT_ID)
+        .where('client_commit_id', '=', clientCommitId)
+        .executeTakeFirstOrThrow();
+      commitSeq = Number(inserted.commit_seq);
+    }
+
+    const changeRows: Array<Insertable<SyncCoreDb['sync_changes']>> =
+      normalizedChanges.map((change) => ({
+        partition_id: partitionId,
+        commit_seq: commitSeq,
+        table: change.table,
+        row_id: change.rowId,
+        op: change.op,
+        row_json: toDialectJsonValue(dialect, change.rowJson),
+        row_version: change.rowVersion,
+        scopes: dialect.scopesToDb(change.scopes),
+      }));
 
-      deletedChunks += Number(result?.numDeletedRows ?? 0);
+    await syncTrx.insertInto('sync_changes').values(changeRows).execute();
+
+    const scopeEntries = createScopeCommitIndexEntries(
+      normalizedChanges.map((change) => ({
+        table: change.table,
+        scopes: change.scopes,
+      }))
+    );
+    if (scopeEntries.length > 0) {
+      await syncTrx
+        .insertInto('sync_scope_commits')
+        .values(
+          scopeEntries.map((entry) => ({
+            partition_id: partitionId,
+            table: entry.table,
+            scope_key: entry.scopeKey,
+            commit_seq: commitSeq,
+          }))
+        )
+        .onConflict((oc) =>
+          oc
+            .columns(['partition_id', 'table', 'scope_key', 'commit_seq'])
+            .doNothing()
+        )
+        .execute();
     }
 
+    const affectedTables = Array.from(
+      new Set(normalizedChanges.map((change) => change.table))
+    ).sort();
+
+    await syncTrx
+      .insertInto('sync_table_commits')
+      .values(
+        affectedTables.map((table) => ({
+          partition_id: partitionId,
+          table,
+          commit_seq: commitSeq,
+        }))
+      )
+      .onConflict((oc) =>
+        oc.columns(['partition_id', 'table', 'commit_seq']).doNothing()
+      )
+      .execute();
+
+    await syncTrx
+      .updateTable('sync_commits')
+      .set({
+        result_json: toDialectJsonValue(dialect, {
+          ok: true,
+          status: 'applied',
+          commitSeq,
+          results: [],
+        }),
+        change_count: normalizedChanges.length,
+        affected_tables: dialect.arrayToDb(affectedTables) as string[],
+      })
+      .where('commit_seq', '=', commitSeq)
+      .execute();
+
+    await finalizeCommitIntegrity({
+      db: trx,
+      dialect,
+      partitionId,
+      commitSeq,
+    });
+
     return {
       commitSeq,
-      tables,
-      deletedChunks,
+      tables: affectedTables,
+      changeCount: normalizedChanges.length,
     };
   });
 }

package/src/pglite.ts

@@ -0,0 +1,68 @@
+/**
+ * @syncular/server/pglite - PGlite dialect for sync
+ *
+ * Provides a Kysely dialect for PGlite (in-memory/browser Postgres).
+ * Uses kysely-pglite-dialect under the hood.
+ */
+
+import { PGlite } from '@electric-sql/pglite';
+import { live, type PGliteWithLive } from '@electric-sql/pglite/live';
+import { PGliteDialect } from 'kysely-pglite-dialect';
+
+export interface PgliteOptions {
+  /** Optional data directory for persistence */
+  dataDir?: string;
+
+  /** Preloaded PGlite fs bundle (avoids runtime network fetches in the browser). */
+  fsBundle?: Blob | File;
+
+  /** Precompiled wasm module (avoids runtime network fetches in the browser). */
+  wasmModule?: WebAssembly.Module;
+
+  /** Optional data dir archive to initialize from (tar). */
+  loadDataDir?: Blob | File;
+
+  /** Optional initial memory (bytes). */
+  initialMemory?: number;
+}
+
+/**
+ * Create the PGlite dialect directly.
+ */
+export function createPgliteDialect(options?: PgliteOptions): PGliteDialect {
+  const database = options ? new PGlite(options) : new PGlite();
+  return new PGliteDialect(database);
+}
+
+export interface PgliteDialectWithLive {
+  dialect: PGliteDialect;
+  pglite: PGliteWithLive;
+}
+
+/**
+ * Create a PGlite dialect with fully initialized live-enabled instance.
+ */
+export async function createPgliteDialectWithLive(
+  options?: PgliteOptions
+): Promise<PgliteDialectWithLive> {
+  const pglite = await PGlite.create({
+    ...options,
+    extensions: { live },
+  });
+  return {
+    dialect: new PGliteDialect(pglite),
+    pglite,
+  };
+}
+
+export function getPgliteAssetPaths(): {
+  fsBundlePath: string;
+  wasmPath: string;
+} {
+  const entry = import.meta.resolve('@electric-sql/pglite');
+
+  return {
+    fsBundlePath: new URL('./pglite.data', entry).pathname,
+    wasmPath: new URL('./pglite.wasm', entry).pathname,
+  };
+}

package/src/plugins/index.ts

@@ -0,0 +1 @@
+export * from './types';

package/src/plugins/types.ts

@@ -0,0 +1,144 @@
+import type {
+  ScopeValues,
+  SyncChange,
+  SyncCrdtStateVectorHint,
+  SyncOperation,
+} from '@syncular/core';
+import type {
+  ApplyOperationResult,
+  ServerApplyOperationContext,
+  ServerContext,
+  ServerTableHandler,
+  SyncServerAuth,
+} from '../handlers/types';
+import type { SyncCoreDb } from '../schema';
+
+/**
+ * Plugin priority levels for server push hooks.
+ * Lower numbers execute first.
+ */
+export const ServerPushPluginPriority = {
+  /** CRDT payload transforms should run early. */
+  CRDT: 40,
+  /** Default priority for general plugins. */
+  DEFAULT: 50,
+  /** Logging/telemetry should run last. */
+  TELEMETRY: 100,
+} as const;
+
+export interface ServerPushPluginBeforeApplyArgs<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> {
+  ctx: ServerApplyOperationContext<DB, Auth>;
+  tableHandler: ServerTableHandler<DB, Auth>;
+  op: SyncOperation;
+  opIndex: number;
+}
+
+export interface ServerPushPluginAfterApplyArgs<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> {
+  ctx: ServerApplyOperationContext<DB, Auth>;
+  tableHandler: ServerTableHandler<DB, Auth>;
+  op: SyncOperation;
+  opIndex: number;
+  applied: ApplyOperationResult;
+}
+
+export interface ServerPullPluginTransformChangesArgs<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> {
+  ctx: ServerContext<DB, Auth>;
+  tableHandler: ServerTableHandler<DB, Auth>;
+  subscription: {
+    id: string;
+    table: string;
+    scopes: ScopeValues;
+    params: Record<string, unknown> | undefined;
+    cursor: number;
+    crdtStateVectors: readonly SyncCrdtStateVectorHint[];
+  };
+  changes: readonly SyncChange[];
+}
+
+export interface SyncServerPlugin<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> {
+  name: string;
+
+  /**
+   * Plugin priority for execution order. Lower numbers execute first.
+   * @default ServerPushPluginPriority.DEFAULT (50)
+   */
+  priority?: number;
+
+  /**
+   * Called right before a table handler applies an operation.
+   * Use this to transform payloads (for example CRDT envelopes).
+   */
+  beforeApplyOperation?(
+    args: ServerPushPluginBeforeApplyArgs<DB, Auth>
+  ): Promise<SyncOperation> | SyncOperation;
+
+  /**
+   * Called after a table handler applies an operation.
+   * Use this to transform emitted changes / conflict rows.
+   */
+  afterApplyOperation?(
+    args: ServerPushPluginAfterApplyArgs<DB, Auth>
+  ): Promise<ApplyOperationResult> | ApplyOperationResult;
+
+  /**
+   * Called while building an incremental pull response for a single
+   * subscription/table, before wire integrity is calculated.
+   *
+   * Use this for scoped, protocol-level row payload transforms such as sending
+   * a CRDT update envelope instead of a full document state when the client
+   * advertised an applicable state vector.
+   */
+  transformPullChanges?(
+    args: ServerPullPluginTransformChangesArgs<DB, Auth>
+  ): Promise<readonly SyncChange[]> | readonly SyncChange[];
+}
+
+export type SyncServerPushPlugin<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> = SyncServerPlugin<DB, Auth>;
+
+export type SyncServerPullPlugin<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+> = SyncServerPlugin<DB, Auth>;
+
+export function sortServerPushPlugins<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+>(
+  plugins: readonly SyncServerPushPlugin<DB, Auth>[] | undefined
+): SyncServerPushPlugin<DB, Auth>[] {
+  if (!plugins || plugins.length === 0) return [];
+
+  return plugins
+    .map((plugin, index) => ({ plugin, index }))
+    .sort((a, b) => {
+      const aPriority = a.plugin.priority ?? ServerPushPluginPriority.DEFAULT;
+      const bPriority = b.plugin.priority ?? ServerPushPluginPriority.DEFAULT;
+      if (aPriority !== bPriority) return aPriority - bPriority;
+      return a.index - b.index;
+    })
+    .map((entry) => entry.plugin);
+}
+
+export function sortServerPullPlugins<
+  DB extends SyncCoreDb = SyncCoreDb,
+  Auth extends SyncServerAuth = SyncServerAuth,
+>(
+  plugins: readonly SyncServerPullPlugin<DB, Auth>[] | undefined
+): SyncServerPullPlugin<DB, Auth>[] {
+  return sortServerPushPlugins(plugins);
+}