@syncular/server 0.1.2 → 0.2.0

package/src/libsql.ts

@@ -1,51 +0,0 @@
-/**
- * @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/migrate.ts

@@ -1,20 +0,0 @@
-/**
- * @syncular/server - Schema setup
- */
-
-import type { Kysely } from 'kysely';
-import type { ServerSyncDialect } from './dialect/types';
-import type { SyncCoreDb } from './schema';
-
-/**
- * Ensures the sync schema exists in the database.
- * Safe to call multiple times (idempotent).
- *
- * @typeParam DB - Your database type that extends SyncCoreDb
- */
-export async function ensureSyncSchema<DB extends SyncCoreDb>(
-  db: Kysely<DB>,
-  dialect: ServerSyncDialect
-): Promise<void> {
-  await dialect.ensureSyncSchema(db);
-}

package/src/neon.ts

@@ -1,28 +0,0 @@
-/**
- * @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

@@ -1,341 +0,0 @@
-/**
- * @syncular/server - External data change notification
- *
- * Creates synthetic commits to notify the sync framework about data changes
- * made outside the normal push flow (e.g., pipeline imports, direct DB writes).
- *
- * The synthetic commit forces affected subscriptions to re-bootstrap on next pull,
- * ensuring clients receive the updated data.
- */
-
-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';
-
-/**
- * Well-known client_id for external/synthetic commits.
- * Used by the pull handler to detect external data changes.
- */
-export const EXTERNAL_CLIENT_ID = '__external__';
-
-export interface NotifyExternalDataChangeArgs<DB extends SyncCoreDb> {
-  db: Kysely<DB>;
-  dialect: ServerSyncDialect;
-  /** Table names that were externally modified. */
-  tables: string[];
-  /** Partition key. Defaults to 'default'. */
-  partitionId?: string;
-  /** Actor identifier for the synthetic commit. Defaults to '__external__'. */
-  actorId?: string;
-}
-
-export interface NotifyExternalDataChangeResult {
-  /** The commit_seq of the synthetic commit. */
-  commitSeq: number;
-  /** Tables that were notified. */
-  tables: string[];
-  /** Number of snapshot chunks deleted. */
-  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.
- *
- * Inserts a synthetic commit (client_id = '__external__'), clears cached
- * snapshot chunks for the affected tables, and inserts sync_table_commits
- * entries so the pull handler can detect the change.
- *
- * On next pull, subscriptions for affected tables will trigger a re-bootstrap
- * instead of an incremental pull.
- */
-export async function notifyExternalDataChange<DB extends SyncCoreDb>(
-  args: NotifyExternalDataChangeArgs<DB>
-): Promise<NotifyExternalDataChangeResult> {
-  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 (uniqueTables.length === 0) {
-    throw new Error('notifyExternalDataChange: tables 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_${Date.now()}_${randomId()}`;
-
-    // 1. Insert synthetic commit
-    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: toDialectJsonValue(dialect, { ok: true, status: 'applied' }),
-      change_count: 0,
-      affected_tables: dialect.arrayToDb(uniqueTables) 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) {
-      // Fallback for dialects/drivers that don't provide insertId.
-      const inserted = await syncTrx
-        .selectFrom('sync_commits')
-        .select(['commit_seq'])
-        .where('partition_id', '=', partitionId)
-        .where('client_id', '=', EXTERNAL_CLIENT_ID)
-        .where('client_commit_id', '=', clientCommitId)
-        .executeTakeFirstOrThrow();
-      commitSeq = Number(inserted.commit_seq);
-    }
-
-    // 2. Insert sync_table_commits entries for each affected table
-    const tableCommits: Array<Insertable<SyncCoreDb['sync_table_commits']>> =
-      uniqueTables.map((table) => ({
-        partition_id: partitionId,
-        table,
-        commit_seq: commitSeq,
-      }));
-
-    await syncTrx
-      .insertInto('sync_table_commits')
-      .values(tableCommits)
-      .onConflict((oc) =>
-        oc.columns(['partition_id', 'table', 'commit_seq']).doNothing()
-      )
-      .execute();
-
-    // 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('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),
-      }));
-
-    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: affectedTables,
-      changeCount: normalizedChanges.length,
-    };
-  });
-}

package/src/pglite.ts

@@ -1,68 +0,0 @@
-/**
- * @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

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

package/src/plugins/types.ts

@@ -1,144 +0,0 @@
-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);
-}