@syncular/core 0.0.1-100

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';

package/src/schemas/sync.ts

@@ -0,0 +1,226 @@
+/**
+ * @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';
+import {
+  SYNC_SNAPSHOT_CHUNK_COMPRESSION,
+  SYNC_SNAPSHOT_CHUNK_ENCODING,
+} from '../snapshot-chunks';
+
+// ============================================================================
+// 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(SYNC_SNAPSHOT_CHUNK_ENCODING),
+  compression: z.literal(SYNC_SNAPSHOT_CHUNK_COMPRESSION),
+});
+
+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/snapshot-chunks.ts

@@ -0,0 +1,112 @@
+/**
+ * @syncular/core - Snapshot chunk encoding helpers
+ */
+
+export const SYNC_SNAPSHOT_CHUNK_ENCODING = 'json-row-frame-v1';
+export type SyncSnapshotChunkEncoding = typeof SYNC_SNAPSHOT_CHUNK_ENCODING;
+
+export const SYNC_SNAPSHOT_CHUNK_COMPRESSION = 'gzip';
+export type SyncSnapshotChunkCompression =
+  typeof SYNC_SNAPSHOT_CHUNK_COMPRESSION;
+
+const SNAPSHOT_ROW_FRAME_MAGIC = new Uint8Array([0x53, 0x52, 0x46, 0x31]); // "SRF1"
+const FRAME_LENGTH_BYTES = 4;
+const MAX_FRAME_BYTE_LENGTH = 0xffff_ffff;
+
+function normalizeRowJson(row: unknown): string {
+  const serialized = JSON.stringify(row);
+  return serialized === undefined ? 'null' : serialized;
+}
+
+/**
+ * Encode rows as framed JSON bytes without the format header.
+ */
+export function encodeSnapshotRowFrames(rows: readonly unknown[]): Uint8Array {
+  const encoder = new TextEncoder();
+  const payloads: Uint8Array[] = [];
+  let totalByteLength = 0;
+
+  for (const row of rows) {
+    const payload = encoder.encode(normalizeRowJson(row));
+    if (payload.length > MAX_FRAME_BYTE_LENGTH) {
+      throw new Error(
+        `Snapshot row payload exceeds ${MAX_FRAME_BYTE_LENGTH} bytes`
+      );
+    }
+    payloads.push(payload);
+    totalByteLength += FRAME_LENGTH_BYTES + payload.length;
+  }
+
+  const encoded = new Uint8Array(totalByteLength);
+  const view = new DataView(encoded.buffer, encoded.byteOffset, encoded.length);
+  let offset = 0;
+  for (const payload of payloads) {
+    view.setUint32(offset, payload.length, false);
+    offset += FRAME_LENGTH_BYTES;
+    encoded.set(payload, offset);
+    offset += payload.length;
+  }
+
+  return encoded;
+}
+
+/**
+ * Encode rows as framed JSON bytes with a format header.
+ *
+ * Format:
+ * - 4-byte magic header ("SRF1")
+ * - repeated frames of:
+ *   - 4-byte big-endian payload byte length
+ *   - UTF-8 JSON payload
+ */
+export function encodeSnapshotRows(rows: readonly unknown[]): Uint8Array {
+  const framedRows = encodeSnapshotRowFrames(rows);
+  const totalByteLength = SNAPSHOT_ROW_FRAME_MAGIC.length + framedRows.length;
+
+  const encoded = new Uint8Array(totalByteLength);
+  encoded.set(SNAPSHOT_ROW_FRAME_MAGIC, 0);
+  encoded.set(framedRows, SNAPSHOT_ROW_FRAME_MAGIC.length);
+
+  return encoded;
+}
+
+/**
+ * Decode framed JSON bytes into rows.
+ */
+export function decodeSnapshotRows(bytes: Uint8Array): unknown[] {
+  if (bytes.length < SNAPSHOT_ROW_FRAME_MAGIC.length) {
+    throw new Error('Snapshot chunk payload is too small');
+  }
+
+  for (let index = 0; index < SNAPSHOT_ROW_FRAME_MAGIC.length; index += 1) {
+    const expected = SNAPSHOT_ROW_FRAME_MAGIC[index];
+    const actual = bytes[index];
+    if (actual !== expected) {
+      throw new Error('Unexpected snapshot chunk format');
+    }
+  }
+
+  const rows: unknown[] = [];
+  const decoder = new TextDecoder();
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);
+  let offset = SNAPSHOT_ROW_FRAME_MAGIC.length;
+
+  while (offset < bytes.length) {
+    if (offset + FRAME_LENGTH_BYTES > bytes.length) {
+      throw new Error('Snapshot chunk payload ended mid-frame header');
+    }
+
+    const payloadLength = view.getUint32(offset, false);
+    offset += FRAME_LENGTH_BYTES;
+
+    if (offset + payloadLength > bytes.length) {
+      throw new Error('Snapshot chunk payload ended mid-frame body');
+    }
+
+    const payload = bytes.subarray(offset, offset + payloadLength);
+    offset += payloadLength;
+    rows.push(JSON.parse(decoder.decode(payload)));
+  }
+
+  return rows;
+}