@syncular/core 0.1.2 → 0.2.0

package/src/scopes/index.ts

@@ -1,237 +0,0 @@
-/**
- * @syncular/core - Scope types, patterns, and utilities
- *
- * Scope patterns define how data is partitioned for sync.
- * Scopes are stored as JSONB on changes for flexible filtering.
- * Patterns use `{placeholder}` syntax to extract or inject values.
- */
-
-// ── Types ────────────────────────────────────────────────────────────
-
-/**
- * Scope pattern string, e.g., 'user:{user_id}', 'project:{project_id}'
- */
-export type ScopePattern = string;
-
-/**
- * Scope value for a single scope key.
- */
-export type ScopeValue = string | string[];
-
-/**
- * Scope values - the actual values for scope variables.
- * Values can be single strings or arrays (for multi-value subscriptions).
- *
- * @example
- * { user_id: 'U1' }
- * { project_id: ['P1', 'P2'] }
- * { year: '2025', month: '03' }
- */
-export type ScopeValues = Record<string, ScopeValue>;
-
-/**
- * Stored scopes on a change - always single values (not arrays).
- * This is what gets stored in the JSONB column.
- *
- * @example
- * { user_id: 'U1', project_id: 'P1' }
- */
-export type StoredScopes = Record<string, string>;
-
-/**
- * Extract scope keys from a scope pattern at the type level.
- *
- * @example
- * ScopeKeysFromPattern<'user:{user_id}'> // 'user_id'
- * ScopeKeysFromPattern<'event:{year}:{month}'> // 'year' | 'month'
- */
-export type ScopeKeysFromPattern<Pattern extends ScopePattern> =
-  string extends Pattern
-    ? string
-    : Pattern extends `${string}{${infer Key}}${infer Rest}`
-      ? Key | ScopeKeysFromPattern<Rest>
-      : never;
-
-/**
- * Resolve the pattern string from a scope definition.
- */
-export type ScopePatternFromDefinition<Definition extends ScopeDefinition> =
-  Definition extends ScopePattern
-    ? Definition
-    : Definition extends { pattern: infer Pattern extends ScopePattern }
-      ? Pattern
-      : never;
-
-/**
- * Extract scope keys from a list of scope definitions.
- */
-export type ScopeKeysFromDefinitions<
-  Definitions extends readonly ScopeDefinition[],
-> = ScopeKeysFromPattern<ScopePatternFromDefinition<Definitions[number]>>;
-
-/**
- * Scope values constrained to known scope keys.
- *
- * Unknown keys are rejected at compile-time when literals are used.
- */
-export type ScopeValuesForKeys<ScopeKeys extends string> = Partial<
-  Record<ScopeKeys, ScopeValue>
->;
-
-/**
- * Scope values inferred from scope definitions.
- */
-export type ScopeValuesFromPatterns<
-  Definitions extends readonly ScopeDefinition[],
-> = ScopeValuesForKeys<ScopeKeysFromDefinitions<Definitions>>;
-
-/**
- * Stored scopes constrained to known scope keys.
- */
-export type StoredScopesForKeys<ScopeKeys extends string> = Partial<
-  Record<ScopeKeys, string>
->;
-
-/**
- * Simplified scope definition.
- * Can be a simple pattern string or an object with explicit column mapping.
- *
- * @example
- * ```typescript
- * // Simple: pattern column is auto-derived
- * scopes: ['user:{user_id}', 'org:{org_id}']
- *
- * // Explicit: when column differs from pattern variable
- * scopes: [
- *   { pattern: 'user:{user_id}', column: 'owner_id' }
- * ]
- * ```
- */
-export type ScopeDefinition =
-  | ScopePattern
-  | { pattern: ScopePattern; column: string };
-
-/**
- * Keep scope definitions as a typed tuple for downstream inference.
- *
- * @example
- * const scopes = defineScopePatterns(['user:{user_id}'] as const);
- */
-export function defineScopePatterns<
-  const Definitions extends readonly ScopeDefinition[],
->(scopes: Definitions): Definitions {
-  return scopes;
-}
-
-// ── Pattern parsing (internal helpers) ───────────────────────────────
-
-/**
- * Extract the placeholder name from a pattern.
- * Returns null if the pattern doesn't contain a valid placeholder.
- */
-function extractPlaceholder(pattern: string): {
-  prefix: string;
-  placeholder: string;
-  suffix: string;
-} | null {
-  const match = pattern.match(/^(.*?)\{(\w+)\}(.*)$/);
-  if (!match) return null;
-
-  return {
-    prefix: match[1]!,
-    placeholder: match[2]!,
-    suffix: match[3]!,
-  };
-}
-
-/**
- * Extract the placeholder name from a pattern.
- */
-function getPlaceholderName(pattern: string): string | null {
-  const parsed = extractPlaceholder(pattern);
-  return parsed?.placeholder ?? null;
-}
-
-/**
- * Normalize scope definitions to a pattern-to-column map.
- *
- * @example
- * normalizeScopes(['user:{user_id}'])
- * // → { 'user:{user_id}': 'user_id' }
- */
-export function normalizeScopes(
-  scopes: readonly ScopeDefinition[]
-): Record<ScopePattern, string> {
-  const result: Record<ScopePattern, string> = {};
-  for (const scope of scopes) {
-    if (typeof scope === 'string') {
-      const placeholder = getPlaceholderName(scope);
-      if (!placeholder) {
-        throw new Error(
-          `Scope pattern "${scope}" must contain a placeholder like {column_name}`
-        );
-      }
-      result[scope] = placeholder;
-    } else {
-      result[scope.pattern] = scope.column;
-    }
-  }
-  return result;
-}
-
-export function createSingleVariableScopeMetadata(
-  scopes: readonly ScopeDefinition[]
-): {
-  scopePatterns: ScopePattern[];
-  scopeColumnsByVariable: Record<string, string>;
-} {
-  const scopeColumnMap = normalizeScopes(scopes);
-  const scopePatterns = Object.keys(scopeColumnMap) as ScopePattern[];
-  const scopeColumnsByVariable: Record<string, string> = {};
-
-  for (const [pattern, columnName] of Object.entries(scopeColumnMap)) {
-    const vars = extractScopeVars(pattern);
-    if (vars.length !== 1) {
-      throw new Error(
-        `Scope pattern "${pattern}" must contain exactly one placeholder (got ${vars.length}).`
-      );
-    }
-    const variableName = vars[0]!;
-    const existingColumn = scopeColumnsByVariable[variableName];
-    if (existingColumn && existingColumn !== columnName) {
-      throw new Error(
-        `Scope variable "${variableName}" is mapped to multiple columns: "${existingColumn}" and "${columnName}".`
-      );
-    }
-    scopeColumnsByVariable[variableName] = columnName;
-  }
-
-  return { scopePatterns, scopeColumnsByVariable };
-}
-
-// ── Value operations (public) ────────────────────────────────────────
-
-/**
- * Extract variable names from a scope pattern.
- *
- * @example
- * extractScopeVars('project:{project_id}') // ['project_id']
- * extractScopeVars('event_date:{year}:{month}') // ['year', 'month']
- */
-export function extractScopeVars(pattern: ScopePattern): string[] {
-  const matches = pattern.match(/\{([^}]+)\}/g);
-  if (!matches) return [];
-  return matches.map((m) => m.slice(1, -1));
-}
-
-export function collectScopeVars(
-  scopePatterns: readonly ScopePattern[]
-): Set<string> {
-  const keys = new Set<string>();
-  for (const pattern of scopePatterns) {
-    for (const key of extractScopeVars(pattern)) {
-      keys.add(key);
-    }
-  }
-  return keys;
-}

package/src/sentry.ts

@@ -1,200 +0,0 @@
-import type {
-  SyncMetricOptions,
-  SyncMetrics,
-  SyncSpan,
-  SyncSpanOptions,
-  SyncTelemetry,
-  SyncTelemetryAttributes,
-  SyncTelemetryAttributeValue,
-  SyncTelemetryEvent,
-  SyncTelemetryLevel,
-  SyncTracer,
-} from '@syncular/core';
-
-interface SentryLoggerAdapter {
-  trace?(message: string, attributes?: Record<string, unknown>): void;
-  debug?(message: string, attributes?: Record<string, unknown>): void;
-  info?(message: string, attributes?: Record<string, unknown>): void;
-  warn?(message: string, attributes?: Record<string, unknown>): void;
-  error?(message: string, attributes?: Record<string, unknown>): void;
-  fatal?(message: string, attributes?: Record<string, unknown>): void;
-}
-
-interface SentrySpanAdapter {
-  setAttribute?(name: string, value: SyncTelemetryAttributeValue): void;
-  setAttributes?(attributes: SyncTelemetryAttributes): void;
-  setStatus?(status: 'ok' | 'error' | string): void;
-}
-
-interface SentryMetricsAdapter {
-  count?(name: string, value: number, options?: SyncMetricOptions): void;
-  gauge?(name: string, value: number, options?: SyncMetricOptions): void;
-  distribution?(name: string, value: number, options?: SyncMetricOptions): void;
-}
-
-export interface SentryTelemetryAdapter {
-  logger?: SentryLoggerAdapter;
-  startSpan?<T>(
-    options: SyncSpanOptions,
-    callback: (span: SentrySpanAdapter) => T
-  ): T;
-  metrics?: SentryMetricsAdapter;
-  captureException?(error: unknown): void;
-}
-
-const noopSpan: SyncSpan = {
-  setAttribute() {},
-  setAttributes() {},
-  setStatus() {},
-};
-
-function resolveLogLevel(event: SyncTelemetryEvent): SyncTelemetryLevel {
-  if (event.level) return event.level;
-  return event.error ? 'error' : 'info';
-}
-
-function resolveLogMethod(
-  logger: SentryLoggerAdapter | undefined,
-  level: SyncTelemetryLevel
-): ((message: string, attributes?: Record<string, unknown>) => void) | null {
-  if (!logger) return null;
-  switch (level) {
-    case 'trace':
-      return logger.trace ?? logger.debug ?? logger.info ?? null;
-    case 'debug':
-      return logger.debug ?? logger.info ?? null;
-    case 'info':
-      return logger.info ?? null;
-    case 'warn':
-      return logger.warn ?? logger.info ?? null;
-    case 'error':
-      return logger.error ?? logger.warn ?? logger.info ?? null;
-    case 'fatal':
-      return logger.fatal ?? logger.error ?? logger.warn ?? logger.info ?? null;
-    default:
-      return logger.info ?? null;
-  }
-}
-
-function toSpan(span: SentrySpanAdapter): SyncSpan {
-  return {
-    setAttribute(name, value) {
-      span.setAttribute?.(name, value);
-    },
-    setAttributes(attributes) {
-      if (span.setAttributes) {
-        span.setAttributes(attributes);
-        return;
-      }
-
-      for (const [key, value] of Object.entries(attributes)) {
-        span.setAttribute?.(key, value);
-      }
-    },
-    setStatus(status) {
-      span.setStatus?.(status);
-    },
-  };
-}
-
-function toLogAttributeValue(
-  value: unknown
-): SyncTelemetryAttributeValue | undefined {
-  if (typeof value === 'string') return value;
-  if (typeof value === 'number') {
-    return Number.isFinite(value) ? value : undefined;
-  }
-  if (typeof value === 'boolean') return value;
-  if (typeof value === 'bigint') {
-    const asNumber = Number(value);
-    if (Number.isFinite(asNumber)) return asNumber;
-    return value.toString();
-  }
-  if (value instanceof Date) return value.toISOString();
-  if (value === null || value === undefined) return undefined;
-
-  if (Array.isArray(value) || typeof value === 'object') {
-    try {
-      return JSON.stringify(value);
-    } catch {
-      return String(value);
-    }
-  }
-
-  return String(value);
-}
-
-function sanitizeLogAttributes(
-  attributes: Record<string, unknown>
-): Record<string, SyncTelemetryAttributeValue> | null {
-  const sanitized: Record<string, SyncTelemetryAttributeValue> = {};
-  for (const [name, value] of Object.entries(attributes)) {
-    const normalized = toLogAttributeValue(value);
-    if (normalized !== undefined) {
-      sanitized[name] = normalized;
-    }
-  }
-
-  return Object.keys(sanitized).length > 0 ? sanitized : null;
-}
-
-function createTracer(adapter: SentryTelemetryAdapter): SyncTracer {
-  return {
-    startSpan<T>(options: SyncSpanOptions, callback: (span: SyncSpan) => T): T {
-      if (!adapter.startSpan) return callback(noopSpan);
-      return adapter.startSpan(options, (span) => callback(toSpan(span)));
-    },
-  };
-}
-
-function createMetrics(adapter: SentryTelemetryAdapter): SyncMetrics {
-  return {
-    count(name, value, options) {
-      adapter.metrics?.count?.(name, value ?? 1, options);
-    },
-    gauge(name, value, options) {
-      adapter.metrics?.gauge?.(name, value, options);
-    },
-    distribution(name, value, options) {
-      adapter.metrics?.distribution?.(name, value, options);
-    },
-  };
-}
-
-/**
- * Create a Syncular telemetry adapter backed by Sentry primitives.
- */
-export function createSentrySyncTelemetry(
-  adapter: SentryTelemetryAdapter
-): SyncTelemetry {
-  return {
-    log(event) {
-      const level = resolveLogLevel(event);
-      const { event: message, ...attributes } = event;
-      const logMethod = resolveLogMethod(adapter.logger, level);
-      if (!logMethod) return;
-      const sanitizedAttributes = sanitizeLogAttributes(attributes);
-      if (!sanitizedAttributes) {
-        logMethod(message);
-        return;
-      }
-      logMethod(message, sanitizedAttributes);
-    },
-    tracer: createTracer(adapter),
-    metrics: createMetrics(adapter),
-    captureException(error, context) {
-      adapter.captureException?.(error);
-      if (!context) return;
-      const logMethod =
-        resolveLogMethod(adapter.logger, 'error') ??
-        resolveLogMethod(adapter.logger, 'info');
-      if (!logMethod) return;
-      const sanitizedContext = sanitizeLogAttributes(context);
-      if (!sanitizedContext) {
-        logMethod('sync.exception.context');
-        return;
-      }
-      logMethod('sync.exception.context', sanitizedContext);
-    },
-  };
-}