@syncular/core 0.0.1-60

package/src/kysely-serialize.ts

@@ -0,0 +1,214 @@
+import {
+  type ColumnUpdateNode,
+  type KyselyPlugin,
+  OperationNodeTransformer,
+  type PluginTransformQueryArgs,
+  type PluginTransformResultArgs,
+  type PrimitiveValueListNode,
+  type QueryResult,
+  type RootOperationNode,
+  type UnknownRow,
+  type ValueNode,
+} from 'kysely';
+
+type Serializer = (parameter: unknown) => unknown;
+type Deserializer = (parameter: unknown) => unknown;
+
+const dateRegex = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?$/;
+
+function isBufferLike(value: object): value is { buffer: unknown } {
+  return 'buffer' in value;
+}
+
+function skipTransform(parameter: unknown): boolean {
+  if (
+    parameter === undefined ||
+    parameter === null ||
+    typeof parameter === 'bigint' ||
+    typeof parameter === 'number'
+  ) {
+    return true;
+  }
+
+  if (typeof parameter === 'object') {
+    return isBufferLike(parameter);
+  }
+
+  return false;
+}
+
+function maybeJson(parameter: string): boolean {
+  return (
+    (parameter.startsWith('{') && parameter.endsWith('}')) ||
+    (parameter.startsWith('[') && parameter.endsWith(']'))
+  );
+}
+
+const defaultSerializer: Serializer = (parameter) => {
+  if (skipTransform(parameter) || typeof parameter === 'string') {
+    return parameter;
+  }
+
+  if (typeof parameter === 'boolean') {
+    return String(parameter);
+  }
+
+  if (parameter instanceof Date) {
+    return parameter.toISOString();
+  }
+
+  try {
+    return JSON.stringify(parameter);
+  } catch {
+    return parameter;
+  }
+};
+
+const defaultDeserializer: Deserializer = (parameter) => {
+  if (skipTransform(parameter)) {
+    return parameter;
+  }
+
+  if (typeof parameter !== 'string') {
+    return parameter;
+  }
+
+  if (parameter === 'true') return true;
+  if (parameter === 'false') return false;
+  if (dateRegex.test(parameter)) return new Date(parameter);
+
+  if (maybeJson(parameter)) {
+    try {
+      return JSON.parse(parameter);
+    } catch {
+      return parameter;
+    }
+  }
+
+  return parameter;
+};
+
+class SerializeParametersTransformer extends OperationNodeTransformer {
+  readonly #serializer: Serializer;
+
+  constructor(serializer: Serializer) {
+    super();
+    this.#serializer = serializer;
+  }
+
+  protected override transformPrimitiveValueList(
+    node: PrimitiveValueListNode
+  ): PrimitiveValueListNode {
+    return {
+      ...node,
+      values: node.values.map((v) => this.#serializer(v)),
+    };
+  }
+
+  protected override transformColumnUpdate(
+    node: ColumnUpdateNode,
+    queryId?: { readonly queryId: string }
+  ): ColumnUpdateNode {
+    const valueNode = node.value;
+    if (valueNode.kind !== 'ValueNode') {
+      return super.transformColumnUpdate(node, queryId);
+    }
+
+    const currentValue = (valueNode as ValueNode).value;
+    const serializedValue = this.#serializer(currentValue);
+    if (currentValue === serializedValue) {
+      return super.transformColumnUpdate(node, queryId);
+    }
+
+    const updatedValue: ValueNode = {
+      ...(valueNode as ValueNode),
+      value: serializedValue,
+    };
+
+    return super.transformColumnUpdate(
+      { ...node, value: updatedValue },
+      queryId
+    );
+  }
+
+  protected override transformValue(node: ValueNode): ValueNode {
+    return { ...node, value: this.#serializer(node.value) };
+  }
+}
+
+class BaseSerializePlugin implements KyselyPlugin {
+  readonly #transformer: SerializeParametersTransformer;
+  readonly #deserializer: Deserializer;
+  readonly #skipNodeSet: Set<RootOperationNode['kind']> | null;
+  readonly #ctx: WeakSet<object> | null;
+
+  /**
+   * Base class for {@link SerializePlugin}, without default options.
+   */
+  constructor(
+    serializer: Serializer,
+    deserializer: Deserializer,
+    skipNodeKind: Array<RootOperationNode['kind']>
+  ) {
+    this.#transformer = new SerializeParametersTransformer(serializer);
+    this.#deserializer = deserializer;
+    if (skipNodeKind.length > 0) {
+      this.#skipNodeSet = new Set(skipNodeKind);
+      this.#ctx = new WeakSet<object>();
+    } else {
+      this.#skipNodeSet = null;
+      this.#ctx = null;
+    }
+  }
+
+  transformQuery({
+    node,
+    queryId,
+  }: PluginTransformQueryArgs): RootOperationNode {
+    if (this.#skipNodeSet?.has(node.kind)) {
+      this.#ctx?.add(queryId);
+      return node;
+    }
+    return this.#transformer.transformNode(node);
+  }
+
+  async transformResult({
+    result,
+    queryId,
+  }: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>> {
+    if (this.#ctx?.has(queryId)) {
+      return result;
+    }
+    return { ...result, rows: this.#parseRows(result.rows) };
+  }
+
+  #parseRows(rows: UnknownRow[]): UnknownRow[] {
+    const out: UnknownRow[] = [];
+    for (const row of rows) {
+      if (!row) continue;
+      const parsed: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(row)) {
+        parsed[key] = this.#deserializer(value);
+      }
+      out.push(parsed);
+    }
+    return out;
+  }
+}
+
+interface SerializePluginOptions {
+  serializer?: Serializer;
+  deserializer?: Deserializer;
+  skipNodeKind?: Array<RootOperationNode['kind']>;
+}
+
+export class SerializePlugin extends BaseSerializePlugin {
+  constructor(options: SerializePluginOptions = {}) {
+    const {
+      serializer = defaultSerializer,
+      deserializer = defaultDeserializer,
+      skipNodeKind = [],
+    } = options;
+    super(serializer, deserializer, skipNodeKind);
+  }
+}

package/src/logger.ts

@@ -0,0 +1,80 @@
+/**
+ * @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.
+ */
+
+/**
+ * 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;
+}
+
+/**
+ * Logger function type - allows custom logging implementations
+ */
+type SyncLogger = (event: SyncLogEvent) => void;
+
+/**
+ * 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).
+ */
+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,
+        })
+      );
+    });
+  };
+}
+
+/**
+ * Log a sync event using the default logger.
+ * For custom logging, create your own logger with createDefaultLogger pattern.
+ */
+export const logSyncEvent: SyncLogger = createDefaultLogger();
+
+/**
+ * Create a timer for measuring operation duration.
+ * Returns the elapsed time in milliseconds when called.
+ *
+ * @example
+ * const elapsed = createSyncTimer();
+ * await doSomeWork();
+ * logSyncEvent({ event: 'work_complete', durationMs: elapsed() });
+ */
+export function createSyncTimer(): () => number {
+  const start = performance.now();
+  return () => Math.round(performance.now() - start);
+}

package/src/proxy/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @syncular/core - Proxy Protocol Exports
+ */
+
+export type {
+  ProxyHandshake,
+  ProxyHandshakeAck,
+  ProxyMessage,
+  ProxyResponse,
+} from './types';

package/src/proxy/types.ts

@@ -0,0 +1,57 @@
+/**
+ * @syncular/core - Proxy Protocol Types
+ *
+ * Shared protocol types between proxy client (Kysely dialect) and server (WebSocket handler).
+ */
+
+/**
+ * Message sent from proxy client to server.
+ */
+export interface ProxyMessage {
+  /** Correlation ID for matching request/response */
+  id: string;
+  /** Message type */
+  type: 'query' | 'begin' | 'commit' | 'rollback';
+  /** SQL query (for 'query' type) */
+  sql?: string;
+  /** Query parameters (for 'query' type) */
+  parameters?: readonly unknown[];
+}
+
+/**
+ * Response sent from server to proxy client.
+ */
+export interface ProxyResponse {
+  /** Correlation ID matching the request */
+  id: string;
+  /** Response type */
+  type: 'result' | 'error';
+  /** Query result rows (for SELECT queries) */
+  rows?: unknown[];
+  /** Number of affected rows (for mutations) */
+  rowCount?: number;
+  /** Error message (for 'error' type) */
+  error?: string;
+}
+
+/**
+ * Handshake message sent when connection is established.
+ */
+export interface ProxyHandshake {
+  type: 'handshake';
+  /** Actor ID for oplog tracking */
+  actorId: string;
+  /** Client ID for oplog tracking */
+  clientId: string;
+}
+
+/**
+ * Handshake acknowledgement from server.
+ */
+export interface ProxyHandshakeAck {
+  type: 'handshake_ack';
+  /** Whether handshake was successful */
+  ok: boolean;
+  /** Error message if handshake failed */
+  error?: string;
+}

package/src/schemas/blobs.ts

@@ -0,0 +1,101 @@
+/**
+ * @syncular/core - Blob Zod schemas
+ *
+ * Runtime validation schemas for blob types.
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Blob Reference Schema
+// ============================================================================
+
+export const BlobRefSchema = z.object({
+  hash: z.string().regex(/^sha256:[0-9a-f]{64}$/i, 'Invalid blob hash format'),
+  size: z.number().int().min(0),
+  mimeType: z.string().min(1),
+  encrypted: z.boolean().optional(),
+  keyId: z.string().optional(),
+});
+
+export type BlobRef = z.infer<typeof BlobRefSchema>;
+
+// ============================================================================
+// Blob Metadata Schema
+// ============================================================================
+
+export const BlobMetadataSchema = z.object({
+  hash: z.string().regex(/^sha256:[0-9a-f]{64}$/i),
+  size: z.number().int().min(0),
+  mimeType: z.string().min(1),
+  createdAt: z.string(),
+  expiresAt: z.string().optional(),
+  uploadComplete: z.boolean(),
+});
+
+export type BlobMetadata = z.infer<typeof BlobMetadataSchema>;
+
+// ============================================================================
+// Upload Request/Response Schemas
+// ============================================================================
+
+export const BlobUploadInitRequestSchema = z.object({
+  hash: z.string().regex(/^sha256:[0-9a-f]{64}$/i, 'Invalid blob hash format'),
+  size: z.number().int().min(0),
+  mimeType: z.string().min(1),
+});
+
+export type BlobUploadInitRequest = z.infer<typeof BlobUploadInitRequestSchema>;
+
+export const BlobUploadInitResponseSchema = z.object({
+  exists: z.boolean(),
+  uploadId: z.string().optional(),
+  uploadUrl: z.string().url().optional(),
+  uploadMethod: z.enum(['PUT', 'POST']).optional(),
+  uploadHeaders: z.record(z.string(), z.string()).optional(),
+  chunkSize: z.number().int().optional(),
+});
+
+export type BlobUploadInitResponse = z.infer<
+  typeof BlobUploadInitResponseSchema
+>;
+
+export const BlobUploadCompleteRequestSchema = z.object({
+  hash: z.string().regex(/^sha256:[0-9a-f]{64}$/i),
+});
+
+export type BlobUploadCompleteRequest = z.infer<
+  typeof BlobUploadCompleteRequestSchema
+>;
+
+export const BlobUploadCompleteResponseSchema = z.object({
+  ok: z.boolean(),
+  metadata: BlobMetadataSchema.optional(),
+  error: z.string().optional(),
+});
+
+export type BlobUploadCompleteResponse = z.infer<
+  typeof BlobUploadCompleteResponseSchema
+>;
+
+// ============================================================================
+// Download URL Request/Response Schemas
+// ============================================================================
+
+export const BlobDownloadUrlRequestSchema = z.object({
+  hash: z.string().regex(/^sha256:[0-9a-f]{64}$/i),
+});
+
+export type BlobDownloadUrlRequest = z.infer<
+  typeof BlobDownloadUrlRequestSchema
+>;
+
+export const BlobDownloadUrlResponseSchema = z.object({
+  url: z.string().url(),
+  expiresAt: z.string(),
+  metadata: BlobMetadataSchema,
+});
+
+export type BlobDownloadUrlResponse = z.infer<
+  typeof BlobDownloadUrlResponseSchema
+>;

package/src/schemas/common.ts

@@ -0,0 +1,45 @@
+/**
+ * @syncular/core - Common Zod schemas
+ */
+
+import { z } from 'zod';
+
+// ============================================================================
+// Error Response Schemas
+// ============================================================================
+
+export const ErrorResponseSchema = z.object({
+  error: z.string(),
+  message: z.string().optional(),
+  code: z.string().optional(),
+});
+
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+
+// ============================================================================
+// Pagination Schemas
+// ============================================================================
+
+export const PaginationQuerySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export type PaginationQuery = z.infer<typeof PaginationQuerySchema>;
+
+export const PaginatedResponseSchema = <T extends z.ZodTypeAny>(
+  itemSchema: T
+) =>
+  z.object({
+    items: z.array(itemSchema),
+    total: z.number().int(),
+    offset: z.number().int(),
+    limit: z.number().int(),
+  });
+
+export type PaginatedResponse<T> = {
+  items: T[];
+  total: number;
+  offset: number;
+  limit: number;
+};

package/src/schemas/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @syncular/core - Schema exports
+ */
+
+export * from './blobs';
+export * from './common';
+export * from './sync';