@syncular/core 0.0.1-60

package/src/__tests__/conflict.test.ts

@@ -0,0 +1,325 @@
+/**
+ * Unit tests for conflict detection utilities.
+ *
+ * Tests the field-level merge logic for sync push operations.
+ * These are pure function tests that don't require database setup.
+ */
+import { describe, expect, test } from 'bun:test';
+import { performFieldLevelMerge } from '../conflict';
+
+describe('performFieldLevelMerge', () => {
+  describe('no base row (new insert)', () => {
+    test('client payload wins entirely when base row is null', () => {
+      const result = performFieldLevelMerge(
+        null, // no base row
+        { id: 'team-1', name: 'Server Name', type: 'praxis' }, // server row
+        { name: 'Client Name', type: 'op' } // client payload
+      );
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload).toEqual({
+          name: 'Client Name',
+          type: 'op',
+        });
+      }
+    });
+  });
+
+  describe('only client changed', () => {
+    test('uses client value when only client changed a field', () => {
+      const baseRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const serverRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const clientPayload = { name: 'Client Updated', type: 'praxis' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload.name).toBe('Client Updated');
+        expect(result.mergedPayload.type).toBe('praxis');
+      }
+    });
+
+    test('handles multiple fields changed by client only', () => {
+      const baseRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const serverRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const clientPayload = { name: 'New Name', type: 'op' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload.name).toBe('New Name');
+        expect(result.mergedPayload.type).toBe('op');
+      }
+    });
+  });
+
+  describe('only server changed', () => {
+    test('keeps server value when only server changed a field', () => {
+      const baseRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const serverRow = {
+        id: 'team-1',
+        name: 'Server Updated',
+        type: 'praxis',
+      };
+      const clientPayload = { name: 'Original', type: 'praxis' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        // Server's value is kept since client didn't change it
+        expect(result.mergedPayload.name).toBe('Server Updated');
+        expect(result.mergedPayload.type).toBe('praxis');
+      }
+    });
+  });
+
+  describe('both changed to same value', () => {
+    test('no conflict when both changed field to same value', () => {
+      const baseRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const serverRow = { id: 'team-1', name: 'Same Value', type: 'praxis' };
+      const clientPayload = { name: 'Same Value', type: 'praxis' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload.name).toBe('Same Value');
+      }
+    });
+  });
+
+  describe('both changed to different values (true conflict)', () => {
+    test('returns conflict when both changed same field to different values', () => {
+      const baseRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const serverRow = { id: 'team-1', name: 'Server Value', type: 'praxis' };
+      const clientPayload = { name: 'Client Value', type: 'praxis' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+      if (!result.canMerge) {
+        expect(result.conflictingFields).toContain('name');
+      }
+    });
+
+    test('reports multiple conflicting fields', () => {
+      const baseRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const serverRow = {
+        id: 'team-1',
+        name: 'Server Name',
+        type: 'server-type',
+      };
+      const clientPayload = { name: 'Client Name', type: 'client-type' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+      if (!result.canMerge) {
+        expect(result.conflictingFields).toContain('name');
+        expect(result.conflictingFields).toContain('type');
+        expect(result.conflictingFields.length).toBe(2);
+      }
+    });
+  });
+
+  describe('mixed changes', () => {
+    test('handles client changed one field, server changed another', () => {
+      const baseRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const serverRow = { id: 'team-1', name: 'Original', type: 'server-type' };
+      const clientPayload = { name: 'Client Name', type: 'praxis' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        // Client's name change is applied
+        expect(result.mergedPayload.name).toBe('Client Name');
+        // Server's type change is kept
+        expect(result.mergedPayload.type).toBe('server-type');
+      }
+    });
+
+    test('handles conflict in one field but not another', () => {
+      const baseRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const serverRow = { id: 'team-1', name: 'Server Name', type: 'praxis' };
+      const clientPayload = { name: 'Client Name', type: 'op' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+      if (!result.canMerge) {
+        // Only name conflicts (both changed from Original to different values)
+        expect(result.conflictingFields).toContain('name');
+        // Type was only changed by client, so no conflict
+        expect(result.conflictingFields).not.toContain('type');
+      }
+    });
+  });
+
+  describe('neither changed', () => {
+    test('returns server values when neither changed', () => {
+      const baseRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const serverRow = { id: 'team-1', name: 'Original', type: 'praxis' };
+      const clientPayload = { name: 'Original', type: 'praxis' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload.name).toBe('Original');
+        expect(result.mergedPayload.type).toBe('praxis');
+      }
+    });
+  });
+});
+
+describe('deepEqual (tested through performFieldLevelMerge)', () => {
+  describe('primitive equality', () => {
+    test('detects change in string values', () => {
+      const baseRow = { name: 'a' };
+      const serverRow = { name: 'b' };
+      const clientPayload = { name: 'c' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+    });
+
+    test('detects change in number values', () => {
+      const baseRow = { count: 1 };
+      const serverRow = { count: 2 };
+      const clientPayload = { count: 3 };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+    });
+
+    test('handles null values', () => {
+      const baseRow = { value: null };
+      const serverRow = { value: null };
+      const clientPayload = { value: 'not null' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload.value).toBe('not null');
+      }
+    });
+
+    test('detects null to value change', () => {
+      const baseRow = { value: null };
+      const serverRow = { value: 'server' };
+      const clientPayload = { value: 'client' };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+    });
+  });
+
+  describe('array equality', () => {
+    test('detects equal arrays', () => {
+      const baseRow = { tags: ['a', 'b'] };
+      const serverRow = { tags: ['a', 'b'] };
+      const clientPayload = { tags: ['a', 'b', 'c'] };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload.tags).toEqual(['a', 'b', 'c']);
+      }
+    });
+
+    test('detects array length difference', () => {
+      const baseRow = { tags: ['a'] };
+      const serverRow = { tags: ['a', 'b'] };
+      const clientPayload = { tags: ['a', 'c'] };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+    });
+
+    test('detects array element difference', () => {
+      const baseRow = { tags: ['a', 'b'] };
+      const serverRow = { tags: ['a', 'x'] };
+      const clientPayload = { tags: ['a', 'y'] };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+    });
+  });
+
+  describe('object equality', () => {
+    test('detects equal objects', () => {
+      const baseRow = { meta: { key: 'value' } };
+      const serverRow = { meta: { key: 'value' } };
+      const clientPayload = { meta: { key: 'new-value' } };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload.meta).toEqual({ key: 'new-value' });
+      }
+    });
+
+    test('detects object key count difference', () => {
+      const baseRow = { meta: { a: 1 } };
+      const serverRow = { meta: { a: 1, b: 2 } };
+      const clientPayload = { meta: { a: 1, c: 3 } };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+    });
+
+    test('detects object value difference', () => {
+      const baseRow = { meta: { key: 'original' } };
+      const serverRow = { meta: { key: 'server' } };
+      const clientPayload = { meta: { key: 'client' } };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(false);
+    });
+  });
+
+  describe('nested structures', () => {
+    test('handles deeply nested objects', () => {
+      const baseRow = { data: { nested: { deep: 'original' } } };
+      const serverRow = { data: { nested: { deep: 'original' } } };
+      const clientPayload = { data: { nested: { deep: 'updated' } } };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload.data).toEqual({
+          nested: { deep: 'updated' },
+        });
+      }
+    });
+
+    test('handles arrays within objects', () => {
+      const baseRow = { config: { items: [1, 2, 3] } };
+      const serverRow = { config: { items: [1, 2, 3] } };
+      const clientPayload = { config: { items: [1, 2, 3, 4] } };
+
+      const result = performFieldLevelMerge(baseRow, serverRow, clientPayload);
+
+      expect(result.canMerge).toBe(true);
+      if (result.canMerge) {
+        expect(result.mergedPayload.config).toEqual({ items: [1, 2, 3, 4] });
+      }
+    });
+  });
+});

package/src/blobs.ts

@@ -0,0 +1,187 @@
+/**
+ * @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>;
+
+  /**
+   * Get blob data directly (for adapters that support direct retrieval).
+   */
+  get?(hash: string): Promise<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,30 @@
+/**
+ * @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';
+// Data transformation hooks
+export * from './transforms';
+// Transport and conflict types (protocol types come from ./schemas)
+export * from './types';