@syncular/core 0.0.1-100

package/src/blobs.ts

@@ -0,0 +1,202 @@
+/**
+ * @syncular/core - Blob types for media/binary handling
+ *
+ * Content-addressable blob storage with presigned URL support.
+ * Protocol types (BlobRef, BlobMetadata, etc.) live in ./schemas/blobs.ts
+ */
+
+import type { BlobRef } from './schemas/blobs';
+
+// ============================================================================
+// Client Transport Types
+// ============================================================================
+
+/**
+ * Transport interface for client-server blob communication.
+ * This is used by the client blob manager to communicate with the server.
+ */
+export interface BlobTransport {
+  /**
+   * Initiate a blob upload.
+   * Returns presigned URL info or indicates blob already exists (dedup).
+   */
+  initiateUpload(args: {
+    hash: string;
+    size: number;
+    mimeType: string;
+  }): Promise<{
+    exists: boolean;
+    uploadUrl?: string;
+    uploadMethod?: 'PUT' | 'POST';
+    uploadHeaders?: Record<string, string>;
+  }>;
+
+  /**
+   * Complete a blob upload.
+   * Call this after uploading to the presigned URL.
+   */
+  completeUpload(hash: string): Promise<{ ok: boolean; error?: string }>;
+
+  /**
+   * Get a presigned download URL.
+   */
+  getDownloadUrl(hash: string): Promise<{
+    url: string;
+    expiresAt: string;
+  }>;
+}
+
+// ============================================================================
+// Storage Adapter Types (Server-side)
+// ============================================================================
+
+/**
+ * Options for signing an upload URL.
+ */
+export interface BlobSignUploadOptions {
+  /** SHA-256 hash (for naming and checksum validation) */
+  hash: string;
+  /** Content size in bytes */
+  size: number;
+  /** MIME type */
+  mimeType: string;
+  /** URL expiration in seconds */
+  expiresIn: number;
+}
+
+/**
+ * Result of signing an upload URL.
+ */
+export interface BlobSignedUpload {
+  /** The URL to upload to */
+  url: string;
+  /** HTTP method */
+  method: 'PUT' | 'POST';
+  /** Required headers */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Options for signing a download URL.
+ */
+export interface BlobSignDownloadOptions {
+  /** SHA-256 hash */
+  hash: string;
+  /** URL expiration in seconds */
+  expiresIn: number;
+}
+
+/**
+ * Adapter for blob storage backends (S3, R2, custom).
+ * Implementations handle actual storage; the sync server orchestrates.
+ */
+export interface BlobStorageAdapter {
+  /** Adapter name for logging/debugging */
+  readonly name: string;
+
+  /**
+   * Generate a presigned URL for uploading a blob.
+   * The URL should enforce checksum validation if the backend supports it.
+   */
+  signUpload(options: BlobSignUploadOptions): Promise<BlobSignedUpload>;
+
+  /**
+   * Generate a presigned URL for downloading a blob.
+   */
+  signDownload(options: BlobSignDownloadOptions): Promise<string>;
+
+  /**
+   * Check if a blob exists in storage.
+   */
+  exists(hash: string): Promise<boolean>;
+
+  /**
+   * Delete a blob (for garbage collection).
+   */
+  delete(hash: string): Promise<void>;
+
+  /**
+   * Get blob metadata from storage (optional).
+   * Used to verify uploads completed successfully.
+   */
+  getMetadata?(
+    hash: string
+  ): Promise<{ size: number; mimeType?: string } | null>;
+
+  /**
+   * Store blob data directly (for adapters that support direct storage).
+   * Used for snapshot chunks and other internal data.
+   */
+  put?(
+    hash: string,
+    data: Uint8Array,
+    metadata?: Record<string, unknown>
+  ): Promise<void>;
+
+  /**
+   * Store blob data directly from a stream.
+   * Preferred for large payloads to avoid full buffering in memory.
+   */
+  putStream?(
+    hash: string,
+    stream: ReadableStream<Uint8Array>,
+    metadata?: Record<string, unknown>
+  ): Promise<void>;
+
+  /**
+   * Get blob data directly (for adapters that support direct retrieval).
+   */
+  get?(hash: string): Promise<Uint8Array | null>;
+
+  /**
+   * Get blob data directly as a stream (for adapters that support stream retrieval).
+   */
+  getStream?(hash: string): Promise<ReadableStream<Uint8Array> | null>;
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Create a BlobRef from upload metadata.
+ */
+export function createBlobRef(args: {
+  hash: string;
+  size: number;
+  mimeType: string;
+  encrypted?: boolean;
+  keyId?: string;
+}): BlobRef {
+  const ref: BlobRef = {
+    hash: args.hash,
+    size: args.size,
+    mimeType: args.mimeType,
+  };
+  if (args.encrypted) {
+    ref.encrypted = true;
+    if (args.keyId) {
+      ref.keyId = args.keyId;
+    }
+  }
+  return ref;
+}
+
+/**
+ * Parse a blob hash, validating format.
+ * @returns The hex hash without prefix, or null if invalid.
+ */
+export function parseBlobHash(hash: string): string | null {
+  if (!hash.startsWith('sha256:')) return null;
+  const hex = hash.slice(7);
+  if (hex.length !== 64) return null;
+  if (!/^[0-9a-f]+$/i.test(hex)) return null;
+  return hex.toLowerCase();
+}
+
+/**
+ * Create a blob hash string from hex.
+ */
+export function createBlobHash(hexHash: string): string {
+  return `sha256:${hexHash.toLowerCase()}`;
+}

package/src/conflict.ts

@@ -0,0 +1,92 @@
+/**
+ * @syncular/core - Pure conflict detection and field-level merge utilities
+ *
+ * These are pure functions with no database dependencies.
+ * Database-specific conflict detection (triggers, etc.) lives in @syncular/server.
+ */
+
+import type { MergeResult } from './types';
+
+/**
+ * Performs field-level merge between client changes and server state.
+ *
+ * Merge logic:
+ * - If only client changed a field -> use client's value
+ * - If only server changed a field -> keep server's value
+ * - If both changed same field to different values -> true conflict
+ *
+ * @param baseRow - The row state when client started editing (from base_version)
+ * @param serverRow - Current server row state
+ * @param clientPayload - Client's intended changes
+ * @returns MergeResult indicating if merge is possible and the result
+ */
+export function performFieldLevelMerge(
+  baseRow: Record<string, unknown> | null,
+  serverRow: Record<string, unknown>,
+  clientPayload: Record<string, unknown>
+): MergeResult {
+  // If no base row (new insert), client payload wins entirely
+  if (!baseRow) {
+    return { canMerge: true, mergedPayload: clientPayload };
+  }
+
+  const conflictingFields: string[] = [];
+  const mergedPayload: Record<string, unknown> = { ...serverRow };
+
+  // Check each field in the client payload
+  for (const [field, clientValue] of Object.entries(clientPayload)) {
+    const baseValue = baseRow[field];
+    const serverValue = serverRow[field];
+
+    const clientChanged = !deepEqual(baseValue, clientValue);
+    const serverChanged = !deepEqual(baseValue, serverValue);
+
+    if (clientChanged && serverChanged) {
+      // Both changed the same field
+      if (!deepEqual(clientValue, serverValue)) {
+        // Changed to different values - true conflict
+        conflictingFields.push(field);
+      }
+      // If they changed to the same value, no conflict - use either
+      mergedPayload[field] = clientValue;
+    } else if (clientChanged) {
+      // Only client changed - use client's value
+      mergedPayload[field] = clientValue;
+    }
+    // If only server changed or neither changed, keep server value (already in mergedPayload)
+  }
+
+  if (conflictingFields.length > 0) {
+    return { canMerge: false, conflictingFields };
+  }
+
+  return { canMerge: true, mergedPayload };
+}
+
+/**
+ * Deep equality check for values (handles primitives, arrays, objects)
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== typeof b) return false;
+
+  if (typeof a === 'object') {
+    if (Array.isArray(a) && Array.isArray(b)) {
+      if (a.length !== b.length) return false;
+      return a.every((item, index) => deepEqual(item, b[index]));
+    }
+
+    if (Array.isArray(a) || Array.isArray(b)) return false;
+
+    const aObj = a as Record<string, unknown>;
+    const bObj = b as Record<string, unknown>;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every((key) => deepEqual(aObj[key], bObj[key]));
+  }
+
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @syncular/core - Shared types and utilities for sync infrastructure
+ *
+ * This package contains:
+ * - Protocol types (commit-log + subscriptions)
+ * - Pure conflict detection and merge utilities
+ * - Logging utilities
+ * - Data transformation hooks (optional)
+ * - Blob types for media/binary handling
+ * - Zod schemas for runtime validation and OpenAPI
+ */
+
+// Blob transport/storage types and utilities (protocol types come from ./schemas)
+export * from './blobs';
+// Conflict detection utilities
+export * from './conflict';
+// Kysely plugin utilities
+export * from './kysely-serialize';
+// Logging utilities
+export * from './logger';
+// Proxy protocol types
+export * from './proxy';
+// Schemas (Zod)
+export * from './schemas';
+// Scope types, patterns, and utilities
+export * from './scopes';
+// Snapshot chunk encoding helpers
+export * from './snapshot-chunks';
+// Telemetry abstraction
+export * from './telemetry';
+// Data transformation hooks
+export * from './transforms';
+// Transport and conflict types (protocol types come from ./schemas)
+export * from './types';
+// Shared runtime utilities
+export * from './utils';

package/src/kysely-serialize.ts

@@ -0,0 +1,214 @@
+import {
+  type ColumnUpdateNode,
+  type KyselyPlugin,
+  OperationNodeTransformer,
+  type PluginTransformQueryArgs,
+  type PluginTransformResultArgs,
+  type PrimitiveValueListNode,
+  type QueryResult,
+  type RootOperationNode,
+  type UnknownRow,
+  type ValueNode,
+} from 'kysely';
+
+type Serializer = (parameter: unknown) => unknown;
+type Deserializer = (parameter: unknown) => unknown;
+
+const dateRegex = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?$/;
+
+function isBufferLike(value: object): value is { buffer: unknown } {
+  return 'buffer' in value;
+}
+
+function skipTransform(parameter: unknown): boolean {
+  if (
+    parameter === undefined ||
+    parameter === null ||
+    typeof parameter === 'bigint' ||
+    typeof parameter === 'number'
+  ) {
+    return true;
+  }
+
+  if (typeof parameter === 'object') {
+    return isBufferLike(parameter);
+  }
+
+  return false;
+}
+
+function maybeJson(parameter: string): boolean {
+  return (
+    (parameter.startsWith('{') && parameter.endsWith('}')) ||
+    (parameter.startsWith('[') && parameter.endsWith(']'))
+  );
+}
+
+const defaultSerializer: Serializer = (parameter) => {
+  if (skipTransform(parameter) || typeof parameter === 'string') {
+    return parameter;
+  }
+
+  if (typeof parameter === 'boolean') {
+    return String(parameter);
+  }
+
+  if (parameter instanceof Date) {
+    return parameter.toISOString();
+  }
+
+  try {
+    return JSON.stringify(parameter);
+  } catch {
+    return parameter;
+  }
+};
+
+const defaultDeserializer: Deserializer = (parameter) => {
+  if (skipTransform(parameter)) {
+    return parameter;
+  }
+
+  if (typeof parameter !== 'string') {
+    return parameter;
+  }
+
+  if (parameter === 'true') return true;
+  if (parameter === 'false') return false;
+  if (dateRegex.test(parameter)) return new Date(parameter);
+
+  if (maybeJson(parameter)) {
+    try {
+      return JSON.parse(parameter);
+    } catch {
+      return parameter;
+    }
+  }
+
+  return parameter;
+};
+
+class SerializeParametersTransformer extends OperationNodeTransformer {
+  readonly #serializer: Serializer;
+
+  constructor(serializer: Serializer) {
+    super();
+    this.#serializer = serializer;
+  }
+
+  protected override transformPrimitiveValueList(
+    node: PrimitiveValueListNode
+  ): PrimitiveValueListNode {
+    return {
+      ...node,
+      values: node.values.map((v) => this.#serializer(v)),
+    };
+  }
+
+  protected override transformColumnUpdate(
+    node: ColumnUpdateNode,
+    queryId?: { readonly queryId: string }
+  ): ColumnUpdateNode {
+    const valueNode = node.value;
+    if (valueNode.kind !== 'ValueNode') {
+      return super.transformColumnUpdate(node, queryId);
+    }
+
+    const currentValue = (valueNode as ValueNode).value;
+    const serializedValue = this.#serializer(currentValue);
+    if (currentValue === serializedValue) {
+      return super.transformColumnUpdate(node, queryId);
+    }
+
+    const updatedValue: ValueNode = {
+      ...(valueNode as ValueNode),
+      value: serializedValue,
+    };
+
+    return super.transformColumnUpdate(
+      { ...node, value: updatedValue },
+      queryId
+    );
+  }
+
+  protected override transformValue(node: ValueNode): ValueNode {
+    return { ...node, value: this.#serializer(node.value) };
+  }
+}
+
+class BaseSerializePlugin implements KyselyPlugin {
+  readonly #transformer: SerializeParametersTransformer;
+  readonly #deserializer: Deserializer;
+  readonly #skipNodeSet: Set<RootOperationNode['kind']> | null;
+  readonly #ctx: WeakSet<object> | null;
+
+  /**
+   * Base class for {@link SerializePlugin}, without default options.
+   */
+  constructor(
+    serializer: Serializer,
+    deserializer: Deserializer,
+    skipNodeKind: Array<RootOperationNode['kind']>
+  ) {
+    this.#transformer = new SerializeParametersTransformer(serializer);
+    this.#deserializer = deserializer;
+    if (skipNodeKind.length > 0) {
+      this.#skipNodeSet = new Set(skipNodeKind);
+      this.#ctx = new WeakSet<object>();
+    } else {
+      this.#skipNodeSet = null;
+      this.#ctx = null;
+    }
+  }
+
+  transformQuery({
+    node,
+    queryId,
+  }: PluginTransformQueryArgs): RootOperationNode {
+    if (this.#skipNodeSet?.has(node.kind)) {
+      this.#ctx?.add(queryId);
+      return node;
+    }
+    return this.#transformer.transformNode(node);
+  }
+
+  async transformResult({
+    result,
+    queryId,
+  }: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+    if (this.#ctx?.has(queryId)) {
+      return result;
+    }
+    return { ...result, rows: this.#parseRows(result.rows) };
+  }
+
+  #parseRows(rows: UnknownRow[]): UnknownRow[] {
+    const out: UnknownRow[] = [];
+    for (const row of rows) {
+      if (!row) continue;
+      const parsed: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(row)) {
+        parsed[key] = this.#deserializer(value);
+      }
+      out.push(parsed);
+    }
+    return out;
+  }
+}
+
+interface SerializePluginOptions {
+  serializer?: Serializer;
+  deserializer?: Deserializer;
+  skipNodeKind?: Array<RootOperationNode['kind']>;
+}
+
+export class SerializePlugin extends BaseSerializePlugin {
+  constructor(options: SerializePluginOptions = {}) {
+    const {
+      serializer = defaultSerializer,
+      deserializer = defaultDeserializer,
+      skipNodeKind = [],
+    } = options;
+    super(serializer, deserializer, skipNodeKind);
+  }
+}

package/src/logger.ts

@@ -0,0 +1,38 @@
+/**
+ * @syncular/core - Structured logging utilities for sync operations
+ *
+ * Uses the active telemetry backend configured via `configureSyncTelemetry()`.
+ */
+
+import { getSyncTelemetry, type SyncTelemetryEvent } from './telemetry';
+
+/**
+ * Sync log event structure.
+ */
+export type SyncLogEvent = SyncTelemetryEvent;
+
+/**
+ * Logger function type.
+ */
+export type SyncLogger = (event: SyncLogEvent) => void;
+
+/**
+ * Log a sync event using the currently configured telemetry backend.
+ */
+export const logSyncEvent: SyncLogger = (event) => {
+  getSyncTelemetry().log(event);
+};
+
+/**
+ * Create a timer for measuring operation duration.
+ * Returns the elapsed time in milliseconds when called.
+ *
+ * @example
+ * const elapsed = createSyncTimer();
+ * await doSomeWork();
+ * logSyncEvent({ event: 'work_complete', durationMs: elapsed() });
+ */
+export function createSyncTimer(): () => number {
+  const start = performance.now();
+  return () => Math.round(performance.now() - start);
+}

package/src/proxy/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @syncular/core - Proxy Protocol Exports
+ */
+
+export type {
+  ProxyHandshake,
+  ProxyHandshakeAck,
+  ProxyMessage,
+  ProxyResponse,
+} from './types';

package/src/proxy/types.ts

@@ -0,0 +1,57 @@
+/**
+ * @syncular/core - Proxy Protocol Types
+ *
+ * Shared protocol types between proxy client (Kysely dialect) and server (WebSocket handler).
+ */
+
+/**
+ * Message sent from proxy client to server.
+ */
+export interface ProxyMessage {
+  /** Correlation ID for matching request/response */
+  id: string;
+  /** Message type */
+  type: 'query' | 'begin' | 'commit' | 'rollback';
+  /** SQL query (for 'query' type) */
+  sql?: string;
+  /** Query parameters (for 'query' type) */
+  parameters?: readonly unknown[];
+}
+
+/**
+ * Response sent from server to proxy client.
+ */
+export interface ProxyResponse {
+  /** Correlation ID matching the request */
+  id: string;
+  /** Response type */
+  type: 'result' | 'error';
+  /** Query result rows (for SELECT queries) */
+  rows?: unknown[];
+  /** Number of affected rows (for mutations) */
+  rowCount?: number;
+  /** Error message (for 'error' type) */
+  error?: string;
+}
+
+/**
+ * Handshake message sent when connection is established.
+ */
+export interface ProxyHandshake {
+  type: 'handshake';
+  /** Actor ID for oplog tracking */
+  actorId: string;
+  /** Client ID for oplog tracking */
+  clientId: string;
+}
+
+/**
+ * Handshake acknowledgement from server.
+ */
+export interface ProxyHandshakeAck {
+  type: 'handshake_ack';
+  /** Whether handshake was successful */
+  ok: boolean;
+  /** Error message if handshake failed */
+  error?: string;
+}