@syncular/core 0.0.1-60

package/src/schemas/sync.ts

@@ -0,0 +1,222 @@
+/**
+ * @syncular/core - Sync protocol Zod schemas
+ *
+ * These schemas define the sync protocol types and can be used for:
+ * - Runtime validation
+ * - OpenAPI spec generation
+ * - Type inference
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Operation Types
+// ============================================================================
+
+export const SyncOpSchema = z.enum(['upsert', 'delete']);
+export type SyncOp = z.infer<typeof SyncOpSchema>;
+
+// ============================================================================
+// Scope Schemas
+// ============================================================================
+
+/**
+ * Stored scopes on a change (single values only)
+ */
+const StoredScopesSchema = z.record(z.string(), z.string());
+
+/**
+ * Scope values in a subscription request (can be arrays)
+ */
+export const ScopeValuesSchema = z.record(
+  z.string(),
+  z.union([z.string(), z.array(z.string())])
+);
+
+// ============================================================================
+// Sync Operation Schema
+// ============================================================================
+
+export const SyncOperationSchema = z.object({
+  table: z.string(),
+  row_id: z.string(),
+  op: SyncOpSchema,
+  payload: z.record(z.string(), z.unknown()).nullable(),
+  base_version: z.number().int().nullable().optional(),
+});
+
+export type SyncOperation = z.infer<typeof SyncOperationSchema>;
+
+// ============================================================================
+// Push Request/Response Schemas
+// ============================================================================
+
+export const SyncPushRequestSchema = z.object({
+  clientId: z.string().min(1),
+  clientCommitId: z.string().min(1),
+  operations: z.array(SyncOperationSchema).min(1),
+  schemaVersion: z.number().int().min(1),
+});
+
+export type SyncPushRequest = z.infer<typeof SyncPushRequestSchema>;
+
+const SyncOperationResultAppliedSchema = z.object({
+  opIndex: z.number().int(),
+  status: z.literal('applied'),
+});
+
+const SyncOperationResultConflictSchema = z.object({
+  opIndex: z.number().int(),
+  status: z.literal('conflict'),
+  message: z.string(),
+  server_version: z.number().int(),
+  server_row: z.unknown(),
+});
+
+const SyncOperationResultErrorSchema = z.object({
+  opIndex: z.number().int(),
+  status: z.literal('error'),
+  error: z.string(),
+  code: z.string().optional(),
+  retriable: z.boolean().optional(),
+});
+
+export const SyncOperationResultSchema = z.union([
+  SyncOperationResultAppliedSchema,
+  SyncOperationResultConflictSchema,
+  SyncOperationResultErrorSchema,
+]);
+
+export type SyncOperationResult = z.infer<typeof SyncOperationResultSchema>;
+
+export const SyncPushResponseSchema = z.object({
+  ok: z.literal(true),
+  status: z.enum(['applied', 'cached', 'rejected']),
+  commitSeq: z.number().int().optional(),
+  results: z.array(SyncOperationResultSchema),
+});
+
+export type SyncPushResponse = z.infer<typeof SyncPushResponseSchema>;
+
+// ============================================================================
+// Bootstrap State Schema
+// ============================================================================
+
+export const SyncBootstrapStateSchema = z.object({
+  asOfCommitSeq: z.number().int(),
+  tables: z.array(z.string()),
+  tableIndex: z.number().int(),
+  rowCursor: z.string().nullable(),
+});
+
+export type SyncBootstrapState = z.infer<typeof SyncBootstrapStateSchema>;
+
+// ============================================================================
+// Pull Request/Response Schemas
+// ============================================================================
+
+export const SyncSubscriptionRequestSchema = z.object({
+  id: z.string().min(1),
+  shape: z.string().min(1),
+  scopes: ScopeValuesSchema,
+  params: z.record(z.string(), z.unknown()).optional(),
+  cursor: z.number().int(),
+  bootstrapState: SyncBootstrapStateSchema.nullable().optional(),
+});
+
+export type SyncSubscriptionRequest = z.infer<
+  typeof SyncSubscriptionRequestSchema
+>;
+
+export const SyncPullRequestSchema = z.object({
+  clientId: z.string().min(1),
+  limitCommits: z.number().int().min(1),
+  limitSnapshotRows: z.number().int().min(1).optional(),
+  maxSnapshotPages: z.number().int().min(1).optional(),
+  dedupeRows: z.boolean().optional(),
+  subscriptions: z.array(SyncSubscriptionRequestSchema),
+});
+
+export type SyncPullRequest = z.infer<typeof SyncPullRequestSchema>;
+
+export const SyncChangeSchema = z.object({
+  table: z.string(),
+  row_id: z.string(),
+  op: SyncOpSchema,
+  row_json: z.unknown().nullable(),
+  row_version: z.number().int().nullable(),
+  scopes: StoredScopesSchema,
+});
+
+export type SyncChange = z.infer<typeof SyncChangeSchema>;
+
+export const SyncCommitSchema = z.object({
+  commitSeq: z.number().int(),
+  createdAt: z.string(),
+  actorId: z.string(),
+  changes: z.array(SyncChangeSchema),
+});
+
+export type SyncCommit = z.infer<typeof SyncCommitSchema>;
+
+export const SyncSnapshotChunkRefSchema = z.object({
+  id: z.string(),
+  byteLength: z.number().int(),
+  sha256: z.string(),
+  encoding: z.literal('ndjson'),
+  compression: z.literal('gzip'),
+});
+
+export type SyncSnapshotChunkRef = z.infer<typeof SyncSnapshotChunkRefSchema>;
+
+export const SyncSnapshotSchema = z.object({
+  table: z.string(),
+  rows: z.array(z.unknown()),
+  chunks: z.array(SyncSnapshotChunkRefSchema).optional(),
+  isFirstPage: z.boolean(),
+  isLastPage: z.boolean(),
+});
+
+export type SyncSnapshot = z.infer<typeof SyncSnapshotSchema>;
+
+export const SyncPullSubscriptionResponseSchema = z.object({
+  id: z.string(),
+  status: z.enum(['active', 'revoked']),
+  scopes: ScopeValuesSchema,
+  bootstrap: z.boolean(),
+  bootstrapState: SyncBootstrapStateSchema.nullable().optional(),
+  nextCursor: z.number().int(),
+  commits: z.array(SyncCommitSchema),
+  snapshots: z.array(SyncSnapshotSchema).optional(),
+});
+
+export type SyncPullSubscriptionResponse = z.infer<
+  typeof SyncPullSubscriptionResponseSchema
+>;
+
+export const SyncPullResponseSchema = z.object({
+  ok: z.literal(true),
+  subscriptions: z.array(SyncPullSubscriptionResponseSchema),
+});
+
+export type SyncPullResponse = z.infer<typeof SyncPullResponseSchema>;
+
+// ============================================================================
+// Combined Sync Request/Response Schemas
+// ============================================================================
+
+export const SyncCombinedRequestSchema = z.object({
+  clientId: z.string().min(1),
+  push: SyncPushRequestSchema.omit({ clientId: true }).optional(),
+  pull: SyncPullRequestSchema.omit({ clientId: true }).optional(),
+});
+
+export type SyncCombinedRequest = z.infer<typeof SyncCombinedRequestSchema>;
+
+export const SyncCombinedResponseSchema = z.object({
+  ok: z.literal(true),
+  push: SyncPushResponseSchema.optional(),
+  pull: SyncPullResponseSchema.optional(),
+});
+
+export type SyncCombinedResponse = z.infer<typeof SyncCombinedResponseSchema>;

package/src/scopes/index.ts

@@ -0,0 +1,122 @@
+/**
+ * @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 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, string | string[]>;
+
+/**
+ * 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>;
+
+/**
+ * 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 = string | { pattern: string; column: string };
+
+// ── 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: ScopeDefinition[]
+): Record<string, string> {
+  const result: Record<string, 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;
+}
+
+// ── 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));
+}

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();
+}