@syncular/core 0.0.1 → 0.0.2-127

package/src/__tests__/telemetry.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, test } from 'bun:test';
+import { logSyncEvent } from '../logger';
+import {
+  captureSyncException,
+  configureSyncTelemetry,
+  countSyncMetric,
+  distributionSyncMetric,
+  gaugeSyncMetric,
+  getSyncTelemetry,
+  resetSyncTelemetry,
+  type SyncMetricOptions,
+  type SyncSpan,
+  type SyncSpanOptions,
+  type SyncTelemetry,
+  type SyncTelemetryEvent,
+  startSyncSpan,
+} from '../telemetry';
+
+interface CapturedCountMetric {
+  name: string;
+  value: number | undefined;
+  options: SyncMetricOptions | undefined;
+}
+
+interface CapturedValueMetric {
+  name: string;
+  value: number;
+  options: SyncMetricOptions | undefined;
+}
+
+function createTestTelemetry(calls: {
+  logs: SyncTelemetryEvent[];
+  countMetrics: CapturedCountMetric[];
+  gaugeMetrics: CapturedValueMetric[];
+  distributionMetrics: CapturedValueMetric[];
+  spans: SyncSpanOptions[];
+  exceptions: Array<{
+    error: unknown;
+    context: Record<string, unknown> | undefined;
+  }>;
+}): SyncTelemetry {
+  return {
+    log(event) {
+      calls.logs.push(event);
+    },
+    tracer: {
+      startSpan(options, callback) {
+        calls.spans.push(options);
+        const span: SyncSpan = {
+          setAttribute() {},
+          setAttributes() {},
+          setStatus() {},
+        };
+        return callback(span);
+      },
+    },
+    metrics: {
+      count(name, value, options) {
+        calls.countMetrics.push({ name, value, options });
+      },
+      gauge(name, value, options) {
+        calls.gaugeMetrics.push({ name, value, options });
+      },
+      distribution(name, value, options) {
+        calls.distributionMetrics.push({ name, value, options });
+      },
+    },
+    captureException(error, context) {
+      calls.exceptions.push({ error, context });
+    },
+  };
+}
+
+describe('sync telemetry configuration', () => {
+  test('routes logger, metrics, spans, and exceptions to configured backend', () => {
+    const calls = {
+      logs: [] as SyncTelemetryEvent[],
+      countMetrics: [] as CapturedCountMetric[],
+      gaugeMetrics: [] as CapturedValueMetric[],
+      distributionMetrics: [] as CapturedValueMetric[],
+      spans: [] as SyncSpanOptions[],
+      exceptions: [] as Array<{
+        error: unknown;
+        context: Record<string, unknown> | undefined;
+      }>,
+    };
+    const telemetry = createTestTelemetry(calls);
+    const previous = getSyncTelemetry();
+
+    try {
+      configureSyncTelemetry(telemetry);
+
+      logSyncEvent({ event: 'sync.test.log', rowCount: 3 });
+
+      const spanResult = startSyncSpan(
+        {
+          name: 'sync.test.span',
+          op: 'sync.test',
+          attributes: { transport: 'ws' },
+        },
+        () => 'done'
+      );
+
+      countSyncMetric('sync.test.count', 2, {
+        attributes: { source: 'unit-test' },
+      });
+      gaugeSyncMetric('sync.test.gauge', 7, { unit: 'millisecond' });
+      distributionSyncMetric('sync.test.dist', 13);
+      captureSyncException(new Error('boom'), {
+        operation: 'unit-test',
+      });
+
+      expect(spanResult).toBe('done');
+      expect(calls.logs).toEqual([{ event: 'sync.test.log', rowCount: 3 }]);
+      expect(calls.spans).toEqual([
+        {
+          name: 'sync.test.span',
+          op: 'sync.test',
+          attributes: { transport: 'ws' },
+        },
+      ]);
+      expect(calls.countMetrics).toEqual([
+        {
+          name: 'sync.test.count',
+          value: 2,
+          options: { attributes: { source: 'unit-test' } },
+        },
+      ]);
+      expect(calls.gaugeMetrics).toEqual([
+        {
+          name: 'sync.test.gauge',
+          value: 7,
+          options: { unit: 'millisecond' },
+        },
+      ]);
+      expect(calls.distributionMetrics).toEqual([
+        {
+          name: 'sync.test.dist',
+          value: 13,
+          options: undefined,
+        },
+      ]);
+      expect(calls.exceptions).toHaveLength(1);
+      expect(calls.exceptions[0]?.context).toEqual({ operation: 'unit-test' });
+    } finally {
+      configureSyncTelemetry(previous);
+    }
+  });
+
+  test('resetSyncTelemetry swaps out custom telemetry backend', () => {
+    const calls = {
+      logs: [] as SyncTelemetryEvent[],
+      countMetrics: [] as CapturedCountMetric[],
+      gaugeMetrics: [] as CapturedValueMetric[],
+      distributionMetrics: [] as CapturedValueMetric[],
+      spans: [] as SyncSpanOptions[],
+      exceptions: [] as Array<{
+        error: unknown;
+        context: Record<string, unknown> | undefined;
+      }>,
+    };
+    const telemetry = createTestTelemetry(calls);
+
+    configureSyncTelemetry(telemetry);
+    resetSyncTelemetry();
+    logSyncEvent({ event: 'sync.default.logger' });
+
+    expect(calls.logs).toHaveLength(0);
+  });
+});

package/src/__tests__/utils.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'bun:test';
+import { isRecord, randomId } from '../utils';
+
+describe('isRecord', () => {
+  it('returns true for plain objects', () => {
+    expect(isRecord({ a: 1 })).toBe(true);
+  });
+
+  it('returns false for null and arrays', () => {
+    expect(isRecord(null)).toBe(false);
+    expect(isRecord([])).toBe(false);
+  });
+});
+
+describe('randomId', () => {
+  it('returns a non-empty string id', () => {
+    const id = randomId();
+    expect(typeof id).toBe('string');
+    expect(id.length > 0).toBe(true);
+  });
+
+  it('generates different ids across sequential calls', () => {
+    const first = randomId();
+    const second = randomId();
+    expect(first).not.toBe(second);
+  });
+});

package/src/blobs.ts

@@ -133,10 +133,25 @@ export interface BlobStorageAdapter {
     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>;
 }
 
 // ============================================================================
@@ -185,17 +200,3 @@ export function parseBlobHash(hash: string): string | null {
 export function createBlobHash(hexHash: string): string {
   return `sha256:${hexHash.toLowerCase()}`;
 }
-
-/**
- * Check if a value looks like a BlobRef.
- */
-export function isBlobRef(value: unknown): value is BlobRef {
-  if (typeof value !== 'object' || value === null) return false;
-  const obj = value as Record<string, unknown>;
-  return (
-    typeof obj.hash === 'string' &&
-    obj.hash.startsWith('sha256:') &&
-    typeof obj.size === 'number' &&
-    typeof obj.mimeType === 'string'
-  );
-}

package/src/column-codecs.ts

@@ -0,0 +1,228 @@
+export type ColumnCodecDialect = 'sqlite' | 'postgres';
+
+export interface ColumnCodecTypeImport {
+  name: string;
+  from: string;
+}
+
+export type ColumnCodecType =
+  | string
+  | { type: string; import?: ColumnCodecTypeImport };
+
+export interface ColumnCodec<App, Db> {
+  ts: ColumnCodecType;
+  toDb(value: App): Db;
+  fromDb(value: Db): App;
+  dialects?: Partial<
+    Record<
+      ColumnCodecDialect,
+      {
+        toDb?(value: App): Db;
+        fromDb?(value: Db): App;
+      }
+    >
+  >;
+}
+
+export type AnyColumnCodec = ColumnCodec<unknown, unknown>;
+
+export interface ColumnCodecColumn {
+  table: string;
+  column: string;
+  sqlType?: string;
+  nullable?: boolean;
+  isPrimaryKey?: boolean;
+  hasDefault?: boolean;
+  dialect?: ColumnCodecDialect;
+}
+
+export type TableColumnCodecs = Record<string, AnyColumnCodec>;
+
+export type ColumnCodecSource = (
+  column: ColumnCodecColumn
+) => AnyColumnCodec | undefined;
+
+function hasCodecs(tableCodecs: TableColumnCodecs): boolean {
+  return Object.keys(tableCodecs).length > 0;
+}
+
+function resolveCodecToDb(
+  codec: AnyColumnCodec,
+  dialect: ColumnCodecDialect
+): (value: unknown) => unknown {
+  return codec.dialects?.[dialect]?.toDb ?? codec.toDb;
+}
+
+function resolveCodecFromDb(
+  codec: AnyColumnCodec,
+  dialect: ColumnCodecDialect
+): (value: unknown) => unknown {
+  return codec.dialects?.[dialect]?.fromDb ?? codec.fromDb;
+}
+
+export function toTableColumnCodecs(
+  table: string,
+  codecSource: ColumnCodecSource | undefined,
+  columns: Iterable<string>,
+  options: {
+    dialect?: ColumnCodecDialect;
+    sqlTypes?: Record<string, string | undefined>;
+  } = {}
+): TableColumnCodecs {
+  if (!codecSource) return {};
+  const out: TableColumnCodecs = {};
+
+  for (const column of columns) {
+    if (column.length === 0) continue;
+    const codec = codecSource({
+      table,
+      column,
+      sqlType: options.sqlTypes?.[column],
+      dialect: options.dialect,
+    });
+    if (codec) out[column] = codec;
+  }
+
+  return out;
+}
+
+export function applyCodecToDbValue(
+  codec: AnyColumnCodec,
+  value: unknown,
+  dialect: ColumnCodecDialect = 'sqlite'
+): unknown {
+  if (value === null || value === undefined) return value;
+  const transform = resolveCodecToDb(codec, dialect);
+  return transform(value);
+}
+
+export function applyCodecFromDbValue(
+  codec: AnyColumnCodec,
+  value: unknown,
+  dialect: ColumnCodecDialect = 'sqlite'
+): unknown {
+  if (value === null || value === undefined) return value;
+  const transform = resolveCodecFromDb(codec, dialect);
+  return transform(value);
+}
+
+export function applyCodecsToDbRow(
+  row: Record<string, unknown>,
+  tableCodecs: TableColumnCodecs,
+  dialect: ColumnCodecDialect = 'sqlite'
+): Record<string, unknown> {
+  if (!hasCodecs(tableCodecs)) return { ...row };
+
+  const transformed: Record<string, unknown> = { ...row };
+  for (const [column, codec] of Object.entries(tableCodecs)) {
+    if (!(column in transformed)) continue;
+    transformed[column] = applyCodecToDbValue(
+      codec,
+      transformed[column],
+      dialect
+    );
+  }
+  return transformed;
+}
+
+export function applyCodecsFromDbRow(
+  row: Record<string, unknown>,
+  tableCodecs: TableColumnCodecs,
+  dialect: ColumnCodecDialect = 'sqlite'
+): Record<string, unknown> {
+  if (!hasCodecs(tableCodecs)) return { ...row };
+
+  const transformed: Record<string, unknown> = { ...row };
+  for (const [column, codec] of Object.entries(tableCodecs)) {
+    if (!(column in transformed)) continue;
+    transformed[column] = applyCodecFromDbValue(
+      codec,
+      transformed[column],
+      dialect
+    );
+  }
+  return transformed;
+}
+
+function parseBooleanValue(value: unknown): boolean {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return value === 1;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true';
+  }
+  return Boolean(value);
+}
+
+export function numberBoolean(): ColumnCodec<
+  boolean,
+  number | boolean | string
+> {
+  return {
+    ts: 'boolean',
+    toDb: (value) => (value ? 1 : 0),
+    fromDb: (value) => parseBooleanValue(value),
+    dialects: {
+      postgres: {
+        toDb: (value) => value,
+        fromDb: (value) => parseBooleanValue(value),
+      },
+    },
+  };
+}
+
+export interface StringJsonCodecOptions<T> {
+  ts?: ColumnCodecType;
+  import?: ColumnCodecTypeImport;
+  stringify?: (value: T) => string;
+  parse?: (value: string) => T;
+}
+
+export function stringJson<T = unknown>(
+  options: StringJsonCodecOptions<T> = {}
+): ColumnCodec<T, string | T> {
+  const stringify = options.stringify ?? ((value: T) => JSON.stringify(value));
+  const parse = options.parse ?? ((value: string) => JSON.parse(value) as T);
+
+  const ts: ColumnCodecType =
+    options.ts ??
+    (options.import
+      ? { type: options.import.name, import: options.import }
+      : 'unknown');
+
+  return {
+    ts,
+    toDb: (value) => stringify(value),
+    fromDb: (value) => {
+      if (typeof value === 'string') {
+        return parse(value);
+      }
+      return value as T;
+    },
+  };
+}
+
+export function timestampDate(): ColumnCodec<Date, string | Date> {
+  return {
+    ts: 'Date',
+    toDb: (value) => value.toISOString(),
+    fromDb: (value) =>
+      value instanceof Date ? value : new Date(String(value)),
+  };
+}
+
+export function dateString(): ColumnCodec<string, string | Date> {
+  return {
+    ts: 'string',
+    toDb: (value) => value,
+    fromDb: (value) =>
+      value instanceof Date ? value.toISOString().slice(0, 10) : String(value),
+  };
+}
+
+export const codecs = {
+  numberBoolean,
+  stringJson,
+  timestampDate,
+  dateString,
+};

package/src/index.ts

@@ -11,54 +11,28 @@
  */
 
 // Blob transport/storage types and utilities (protocol types come from ./schemas)
-export type {
-  BlobSignDownloadOptions,
-  BlobSignedUpload,
-  BlobSignUploadOptions,
-  BlobStorageAdapter,
-  BlobTransport,
-} from './blobs';
-export {
-  createBlobHash,
-  createBlobRef,
-  parseBlobHash,
-} from './blobs';
+export * from './blobs';
+// Column-level codecs shared by typegen and runtime paths
+export * from './column-codecs';
 // Conflict detection utilities
+export * from './conflict';
 // Kysely plugin utilities
-export { SerializePlugin } from './kysely-serialize';
+export * from './kysely-serialize';
 // Logging utilities
-export {
-  createSyncTimer,
-  logSyncEvent,
-} from './logger';
+export * from './logger';
 // Proxy protocol types
-export type {
-  ProxyHandshake,
-  ProxyHandshakeAck,
-  ProxyMessage,
-  ProxyResponse,
-} from './proxy';
+export * from './proxy';
 // Schemas (Zod)
 export * from './schemas';
 // Scope types, patterns, and utilities
-export type {
-  ScopeDefinition,
-  ScopePattern,
-  ScopeValues,
-  StoredScopes,
-} from './scopes';
-export { extractScopeVars, normalizeScopes } from './scopes';
+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 type {
-  ConflictCheckResult,
-  MergeResult,
-  MergeResultConflict,
-  MergeResultOk,
-  SyncTransport,
-  SyncTransportBlobs,
-  SyncTransportOptions,
-} from './types';
-export { SyncTransportError } from './types';
+export * from './types';
+// Shared runtime utilities
+export * from './utils';

package/src/kysely-serialize.ts

@@ -196,7 +196,7 @@ class BaseSerializePlugin implements KyselyPlugin {
   }
 }
 
-export interface SerializePluginOptions {
+interface SerializePluginOptions {
   serializer?: Serializer;
   deserializer?: Deserializer;
   skipNodeKind?: Array<RootOperationNode['kind']>;

package/src/logger.ts

@@ -1,69 +1,27 @@
 /**
  * @syncular/core - Structured logging utilities for sync operations
  *
- * Outputs JSON lines for easy parsing by log aggregation tools.
- * Each log event includes a timestamp and event type.
+ * Uses the active telemetry backend configured via `configureSyncTelemetry()`.
  */
 
-/**
- * Sync log event structure
- */
-interface SyncLogEvent {
-  /** Event type identifier */
-  event: string;
-  /** User ID (optional) */
-  userId?: string;
-  /** Operation duration in milliseconds (optional) */
-  durationMs?: number;
-  /** Number of rows affected (optional) */
-  rowCount?: number;
-  /** Whether a full reset was required (optional) */
-  resetRequired?: boolean;
-  /** Error message if operation failed (optional) */
-  error?: string;
-  /** Additional arbitrary properties */
-  [key: string]: unknown;
-}
+import { getSyncTelemetry, type SyncTelemetryEvent } from './telemetry';
 
 /**
- * Logger function type - allows custom logging implementations
+ * Sync log event structure.
  */
-type SyncLogger = (event: SyncLogEvent) => void;
+export type SyncLogEvent = SyncTelemetryEvent;
 
 /**
- * Default logger that outputs JSON lines to console.
- * Non-blocking - defers logging to avoid blocking the event loop.
- *
- * On server (Node.js), uses setImmediate.
- * On client (browser), uses setTimeout(0).
+ * Logger function type.
  */
-function createDefaultLogger(): SyncLogger {
-  // Detect environment
-  const isNode =
-    typeof globalThis !== 'undefined' &&
-    typeof globalThis.setImmediate === 'function';
-
-  const defer = isNode
-    ? (fn: () => void) => globalThis.setImmediate(fn)
-    : (fn: () => void) => setTimeout(fn, 0);
-
-  return (event: SyncLogEvent) => {
-    defer(() => {
-      console.log(
-        JSON.stringify({
-          timestamp: new Date().toISOString(),
-          ...event,
-        })
-      );
-    });
-  };
-}
+export type SyncLogger = (event: SyncLogEvent) => void;
 
 /**
- * Log a sync event using the default logger.
- * For custom logging, create your own logger with createDefaultLogger pattern.
+ * Log a sync event using the currently configured telemetry backend.
  */
-export const logSyncEvent: SyncLogger = createDefaultLogger();
+export const logSyncEvent: SyncLogger = (event) => {
+  getSyncTelemetry().log(event);
+};
 
 /**
  * Create a timer for measuring operation duration.
@@ -78,19 +36,3 @@ export function createSyncTimer(): () => number {
   const start = performance.now();
   return () => Math.round(performance.now() - start);
 }
-
-/**
- * Create a scoped logger that automatically adds context to all events.
- *
- * @example
- * const log = createScopedLogger({ userId: 'user123', shape: 'teams' });
- * log({ event: 'pull_start' }); // Includes userId and shape
- */
-export function createScopedLogger(
-  context: Record<string, unknown>,
-  baseLogger: SyncLogger = logSyncEvent
-): SyncLogger {
-  return (event: SyncLogEvent) => {
-    baseLogger({ ...context, ...event });
-  };
-}

package/src/proxy/types.ts

@@ -34,16 +34,6 @@ export interface ProxyResponse {
   error?: string;
 }
 
-/**
- * Options for establishing a proxy connection.
- */
-export interface ProxyConnectOptions {
-  /** Actor ID for oplog tracking */
-  actorId: string;
-  /** Client ID for oplog tracking */
-  clientId: string;
-}
-
 /**
  * Handshake message sent when connection is established.
  */