@syncular/core 0.0.1-100

package/src/telemetry.ts

@@ -0,0 +1,238 @@
+/**
+ * @syncular/core - Runtime telemetry abstraction
+ *
+ * Provides vendor-neutral logging, tracing, and metrics interfaces so
+ * Syncular libraries can emit telemetry without coupling to a specific SDK.
+ */
+
+/**
+ * Supported log levels.
+ */
+export type SyncTelemetryLevel =
+  | 'trace'
+  | 'debug'
+  | 'info'
+  | 'warn'
+  | 'error'
+  | 'fatal';
+
+/**
+ * Primitive attribute value used by traces and metrics.
+ */
+export type SyncTelemetryAttributeValue = string | number | boolean;
+
+/**
+ * Attribute bag used by traces and metrics.
+ */
+export type SyncTelemetryAttributes = Record<
+  string,
+  SyncTelemetryAttributeValue
+>;
+
+/**
+ * Structured sync log event.
+ */
+export interface SyncTelemetryEvent {
+  event: string;
+  level?: SyncTelemetryLevel;
+  userId?: string;
+  durationMs?: number;
+  rowCount?: number;
+  resetRequired?: boolean;
+  error?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Span creation options.
+ */
+export interface SyncSpanOptions {
+  name: string;
+  op?: string;
+  attributes?: SyncTelemetryAttributes;
+}
+
+/**
+ * Span API exposed to Syncular internals.
+ */
+export interface SyncSpan {
+  setAttribute(name: string, value: SyncTelemetryAttributeValue): void;
+  setAttributes(attributes: SyncTelemetryAttributes): void;
+  setStatus(status: 'ok' | 'error'): void;
+}
+
+/**
+ * Tracing interface.
+ */
+export interface SyncTracer {
+  startSpan<T>(options: SyncSpanOptions, callback: (span: SyncSpan) => T): T;
+}
+
+/**
+ * Metric record options.
+ */
+export interface SyncMetricOptions {
+  attributes?: SyncTelemetryAttributes;
+  unit?: string;
+}
+
+/**
+ * Metrics interface.
+ */
+export interface SyncMetrics {
+  count(name: string, value?: number, options?: SyncMetricOptions): void;
+  gauge(name: string, value: number, options?: SyncMetricOptions): void;
+  distribution(name: string, value: number, options?: SyncMetricOptions): void;
+}
+
+/**
+ * Unified telemetry interface.
+ */
+export interface SyncTelemetry {
+  log(event: SyncTelemetryEvent): void;
+  tracer: SyncTracer;
+  metrics: SyncMetrics;
+  captureException(error: unknown, context?: Record<string, unknown>): void;
+}
+
+const noopSpan: SyncSpan = {
+  setAttribute() {},
+  setAttributes() {},
+  setStatus() {},
+};
+
+const noopTracer: SyncTracer = {
+  startSpan(_options, callback) {
+    return callback(noopSpan);
+  },
+};
+
+const noopMetrics: SyncMetrics = {
+  count() {},
+  gauge() {},
+  distribution() {},
+};
+
+function createConsoleLogger(): (event: SyncTelemetryEvent) => void {
+  const isNode =
+    typeof globalThis !== 'undefined' &&
+    typeof globalThis.setImmediate === 'function';
+
+  const defer = isNode
+    ? (fn: () => void) => globalThis.setImmediate(fn)
+    : (fn: () => void) => setTimeout(fn, 0);
+
+  return (event: SyncTelemetryEvent) => {
+    defer(() => {
+      const level = event.level ?? (event.error ? 'error' : 'info');
+      const payload = {
+        timestamp: new Date().toISOString(),
+        level,
+        ...event,
+      };
+      console.log(JSON.stringify(payload));
+    });
+  };
+}
+
+/**
+ * Create console-backed default telemetry (logs only; no-op tracing/metrics).
+ */
+export function createDefaultSyncTelemetry(): SyncTelemetry {
+  const logger = createConsoleLogger();
+  return {
+    log(event) {
+      logger(event);
+    },
+    tracer: noopTracer,
+    metrics: noopMetrics,
+    captureException(error, context) {
+      const message =
+        error instanceof Error
+          ? error.message
+          : `Unknown error: ${String(error)}`;
+      logger({
+        event: 'sync.exception',
+        level: 'error',
+        error: message,
+        ...(context ?? {}),
+      });
+    },
+  };
+}
+
+let activeSyncTelemetry: SyncTelemetry = createDefaultSyncTelemetry();
+
+/**
+ * Get currently configured telemetry backend.
+ */
+export function getSyncTelemetry(): SyncTelemetry {
+  return activeSyncTelemetry;
+}
+
+/**
+ * Replace active telemetry backend.
+ */
+export function configureSyncTelemetry(telemetry: SyncTelemetry): void {
+  activeSyncTelemetry = telemetry;
+}
+
+/**
+ * Reset telemetry backend to default console implementation.
+ */
+export function resetSyncTelemetry(): void {
+  activeSyncTelemetry = createDefaultSyncTelemetry();
+}
+
+/**
+ * Capture an exception through the active telemetry backend.
+ */
+export function captureSyncException(
+  error: unknown,
+  context?: Record<string, unknown>
+): void {
+  activeSyncTelemetry.captureException(error, context);
+}
+
+/**
+ * Start a span through the active telemetry backend.
+ */
+export function startSyncSpan<T>(
+  options: SyncSpanOptions,
+  callback: (span: SyncSpan) => T
+): T {
+  return activeSyncTelemetry.tracer.startSpan(options, callback);
+}
+
+/**
+ * Record a counter metric through the active telemetry backend.
+ */
+export function countSyncMetric(
+  name: string,
+  value?: number,
+  options?: SyncMetricOptions
+): void {
+  activeSyncTelemetry.metrics.count(name, value, options);
+}
+
+/**
+ * Record a gauge metric through the active telemetry backend.
+ */
+export function gaugeSyncMetric(
+  name: string,
+  value: number,
+  options?: SyncMetricOptions
+): void {
+  activeSyncTelemetry.metrics.gauge(name, value, options);
+}
+
+/**
+ * Record a distribution metric through the active telemetry backend.
+ */
+export function distributionSyncMetric(
+  name: string,
+  value: number,
+  options?: SyncMetricOptions
+): void {
+  activeSyncTelemetry.metrics.distribution(name, value, options);
+}

package/src/transforms.ts

@@ -0,0 +1,256 @@
+/**
+ * @syncular/core - Data transformation hooks
+ *
+ * Provides interfaces for field-level transformations (e.g., encryption/decryption)
+ * that can be applied during sync operations.
+ */
+
+/**
+ * Direction of the transformation.
+ * - 'toClient': Server → Client (e.g., decrypt for client)
+ * - 'toServer': Client → Server (e.g., encrypt for server)
+ */
+export type TransformDirection = 'toClient' | 'toServer';
+
+/**
+ * Context passed to transform functions.
+ */
+export interface TransformContext {
+  /** Direction of transformation */
+  direction: TransformDirection;
+  /** Scope name */
+  scope: string;
+  /** Table name */
+  table: string;
+  /** Row ID */
+  rowId: string;
+  /** User ID performing the operation */
+  userId: string;
+}
+
+/**
+ * A field transformer handles transformation of a single field.
+ *
+ * @example
+ * const secretNotesTransformer: FieldTransformer = {
+ *   field: 'secret_notes',
+ *   async transform(value, ctx) {
+ *     const key = await getUserEncryptionKey(ctx.userId);
+ *     return ctx.direction === 'toClient'
+ *       ? decrypt(value as string, key)
+ *       : encrypt(value as string, key);
+ *   }
+ * };
+ */
+export interface FieldTransformer {
+  /** Field name to transform */
+  field: string;
+  /**
+   * Transform the field value.
+   * @param value - Current field value
+   * @param ctx - Transform context
+   * @returns Transformed value
+   */
+  transform(value: unknown, ctx: TransformContext): Promise<unknown> | unknown;
+}
+
+/**
+ * Configuration for transforms on a scope.
+ */
+export interface ScopeTransformConfig {
+  /** Scope name this config applies to */
+  scope: string;
+  /** Field transformers for this scope */
+  fields?: FieldTransformer[];
+}
+
+/**
+ * Registry for managing data transforms.
+ *
+ * @example
+ * const transforms = new TransformRegistry();
+ *
+ * transforms.register({
+ *   scope: 'tasks',
+ *   fields: [{
+ *     field: 'secret_notes',
+ *     async transform(value, ctx) {
+ *       const key = await getUserEncryptionKey(ctx.userId);
+ *       return ctx.direction === 'toClient'
+ *         ? decrypt(value as string, key)
+ *         : encrypt(value as string, key);
+ *     }
+ *   }]
+ * });
+ *
+ * // Apply transforms to data
+ * const transformed = await transforms.apply(
+ *   [{ id: '1', secret_notes: 'encrypted...' }],
+ *   { direction: 'toClient', scope: 'tasks', ... }
+ * );
+ */
+export class TransformRegistry {
+  private configs: Map<string, ScopeTransformConfig> = new Map();
+
+  /**
+   * Register transform config for a scope.
+   * @throws If config for this scope is already registered
+   */
+  register(config: ScopeTransformConfig): void {
+    if (this.configs.has(config.scope)) {
+      throw new Error(
+        `Transform config for scope "${config.scope}" is already registered`
+      );
+    }
+    this.configs.set(config.scope, config);
+  }
+
+  /**
+   * Unregister transform config by scope.
+   * @returns true if config was found and removed
+   */
+  unregister(scope: string): boolean {
+    return this.configs.delete(scope);
+  }
+
+  /**
+   * Get config for a scope.
+   */
+  get(scope: string): ScopeTransformConfig | undefined {
+    return this.configs.get(scope);
+  }
+
+  /**
+   * Check if any transforms are registered for a scope.
+   */
+  hasTransforms(scope: string): boolean {
+    const config = this.configs.get(scope);
+    return config !== undefined && (config.fields?.length ?? 0) > 0;
+  }
+
+  /**
+   * Get all registered configs.
+   */
+  getAll(): ScopeTransformConfig[] {
+    return Array.from(this.configs.values());
+  }
+
+  /**
+   * Apply transforms to a single row.
+   *
+   * @param row - Row data to transform
+   * @param ctx - Transform context (without rowId, will be extracted from row)
+   * @param rowIdField - Field name for row ID (default: 'id')
+   * @returns Transformed row
+   */
+  async applyToRow<T extends Record<string, unknown>>(
+    row: T,
+    ctx: Omit<TransformContext, 'rowId'>,
+    rowIdField = 'id'
+  ): Promise<T> {
+    const config = this.configs.get(ctx.scope);
+    if (!config?.fields?.length) {
+      return row;
+    }
+
+    const rowId = String(row[rowIdField] ?? '');
+    const fullCtx: TransformContext = { ...ctx, rowId };
+    const result = { ...row };
+
+    for (const transformer of config.fields) {
+      if (transformer.field in result) {
+        try {
+          result[transformer.field as keyof T] = (await transformer.transform(
+            result[transformer.field],
+            fullCtx
+          )) as T[keyof T];
+        } catch (err) {
+          console.error(
+            `[transforms] Error transforming field "${transformer.field}" for ${ctx.scope}:${rowId}:`,
+            err
+          );
+          // Keep original value on error
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Apply transforms to multiple rows.
+   *
+   * @param rows - Array of rows to transform
+   * @param ctx - Transform context (without rowId)
+   * @param rowIdField - Field name for row ID (default: 'id')
+   * @returns Transformed rows
+   */
+  async apply<T extends Record<string, unknown>>(
+    rows: T[],
+    ctx: Omit<TransformContext, 'rowId'>,
+    rowIdField = 'id'
+  ): Promise<T[]> {
+    const config = this.configs.get(ctx.scope);
+    if (!config?.fields?.length) {
+      return rows;
+    }
+
+    return Promise.all(
+      rows.map((row) => this.applyToRow(row, ctx, rowIdField))
+    );
+  }
+
+  /**
+   * Apply transforms to a mutation payload.
+   *
+   * @param payload - Mutation payload (may be partial row)
+   * @param ctx - Full transform context
+   * @returns Transformed payload
+   */
+  async applyToPayload<T extends Record<string, unknown>>(
+    payload: T | null,
+    ctx: TransformContext
+  ): Promise<T | null> {
+    if (!payload) return null;
+
+    const config = this.configs.get(ctx.scope);
+    if (!config?.fields?.length) {
+      return payload;
+    }
+
+    const result = { ...payload };
+
+    for (const transformer of config.fields) {
+      if (transformer.field in result) {
+        try {
+          result[transformer.field as keyof T] = (await transformer.transform(
+            result[transformer.field],
+            ctx
+          )) as T[keyof T];
+        } catch (err) {
+          console.error(
+            `[transforms] Error transforming field "${transformer.field}" for ${ctx.scope}:${ctx.rowId}:`,
+            err
+          );
+          // Keep original value on error
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Clear all registered configs.
+   */
+  clear(): void {
+    this.configs.clear();
+  }
+}
+
+/**
+ * Create a new transform registry.
+ */
+export function createTransformRegistry(): TransformRegistry {
+  return new TransformRegistry();
+}

package/src/types.ts

@@ -0,0 +1,158 @@
+/**
+ * @syncular/core - Shared types for sync infrastructure
+ *
+ * Non-protocol types: conflict detection, transport interfaces.
+ * Protocol types (SyncOp, SyncPushRequest, etc.) live in ./schemas/sync.ts
+ */
+
+import type { SyncCombinedRequest, SyncCombinedResponse } from './schemas/sync';
+
+// ============================================================================
+// Conflict Detection Types
+// ============================================================================
+
+/**
+ * Result of a conflict check - no conflict
+ */
+interface ConflictCheckResultOk {
+  hasConflict: false;
+}
+
+/**
+ * Result of a conflict check - conflict detected
+ */
+interface ConflictCheckResultConflict {
+  hasConflict: true;
+  /** Fields with conflicting changes */
+  conflictingFields: string[];
+  /** Current server row state */
+  serverRow: Record<string, unknown>;
+  /** Current server version */
+  serverVersion: number;
+}
+
+/**
+ * Union type for conflict check results
+ */
+export type ConflictCheckResult =
+  | ConflictCheckResultOk
+  | ConflictCheckResultConflict;
+
+/**
+ * Result of a field-level merge - can merge
+ */
+export interface MergeResultOk {
+  canMerge: true;
+  /** Merged payload combining client and server changes */
+  mergedPayload: Record<string, unknown>;
+}
+
+/**
+ * Result of a field-level merge - cannot merge
+ */
+export interface MergeResultConflict {
+  canMerge: false;
+  /** Fields that cannot be auto-merged */
+  conflictingFields: string[];
+}
+
+/**
+ * Union type for merge results
+ */
+export type MergeResult = MergeResultOk | MergeResultConflict;
+
+// ============================================================================
+// Transport Types
+// ============================================================================
+
+/**
+ * Options for transport operations.
+ * Provides hooks for auth errors and cancellation support.
+ */
+export interface SyncTransportOptions {
+  /**
+   * Called when auth fails (401/403).
+   * Return true to retry the request after refreshing auth.
+   */
+  onAuthError?: () => Promise<boolean>;
+  /**
+   * Abort signal for cancellation support.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * Blob transport operations (optional extension to SyncTransport).
+ * When present, enables blob upload/download through the same transport.
+ */
+export interface SyncTransportBlobs {
+  /**
+   * 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;
+  }>;
+}
+
+/**
+ * Transport interface for sync operations.
+ */
+export interface SyncTransport {
+  /**
+   * Combined push+pull in a single round-trip.
+   */
+  sync(
+    request: SyncCombinedRequest,
+    options?: SyncTransportOptions
+  ): Promise<SyncCombinedResponse>;
+
+  /**
+   * Download an encoded bootstrap snapshot chunk.
+   */
+  fetchSnapshotChunk(
+    request: { chunkId: string },
+    options?: SyncTransportOptions
+  ): Promise<Uint8Array>;
+
+  /**
+   * Optional blob operations.
+   * When present, enables blob upload/download functionality.
+   */
+  blobs?: SyncTransportBlobs;
+}
+
+/**
+ * Transport error with additional context
+ */
+export class SyncTransportError extends Error {
+  constructor(
+    message: string,
+    public readonly status?: number,
+    public readonly code?: string
+  ) {
+    super(message);
+    this.name = 'SyncTransportError';
+  }
+}

package/src/utils/id.ts

@@ -0,0 +1,7 @@
+export function randomId(): string {
+  const cryptoObj = globalThis.crypto;
+  if (cryptoObj && typeof cryptoObj.randomUUID === 'function') {
+    return cryptoObj.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './id';
+export * from './object';

package/src/utils/object.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}