@syncular/core 0.0.1 → 0.0.2-126

package/src/schemas/sync.ts

@@ -8,6 +8,10 @@
  */
 
 import { z } from 'zod';
+import {
+  SYNC_SNAPSHOT_CHUNK_COMPRESSION,
+  SYNC_SNAPSHOT_CHUNK_ENCODING,
+} from '../snapshot-chunks';
 
 // ============================================================================
 // Operation Types
@@ -117,7 +121,7 @@ export type SyncBootstrapState = z.infer<typeof SyncBootstrapStateSchema>;
 
 export const SyncSubscriptionRequestSchema = z.object({
   id: z.string().min(1),
-  shape: z.string().min(1),
+  table: z.string().min(1),
   scopes: ScopeValuesSchema,
   params: z.record(z.string(), z.unknown()).optional(),
   cursor: z.number().int(),
@@ -163,8 +167,8 @@ export const SyncSnapshotChunkRefSchema = z.object({
   id: z.string(),
   byteLength: z.number().int(),
   sha256: z.string(),
-  encoding: z.literal('ndjson'),
-  compression: z.literal('gzip'),
+  encoding: z.literal(SYNC_SNAPSHOT_CHUNK_ENCODING),
+  compression: z.literal(SYNC_SNAPSHOT_CHUNK_COMPRESSION),
 });
 
 export type SyncSnapshotChunkRef = z.infer<typeof SyncSnapshotChunkRefSchema>;
@@ -200,3 +204,23 @@ export const SyncPullResponseSchema = z.object({
 });
 
 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

@@ -13,6 +13,11 @@
  */
 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).
@@ -22,7 +27,7 @@ export type ScopePattern = string;
  * { project_id: ['P1', 'P2'] }
  * { year: '2025', month: '03' }
  */
-export type ScopeValues = Record<string, string | string[]>;
+export type ScopeValues = Record<string, ScopeValue>;
 
 /**
  * Stored scopes on a change - always single values (not arrays).
@@ -34,19 +39,57 @@ export type ScopeValues = Record<string, string | string[]>;
 export type StoredScopes = Record<string, string>;
 
 /**
- * Definition of shared scopes across server and client.
- * Maps scope patterns to their variable types.
+ * Extract scope keys from a scope pattern at the type level.
  *
  * @example
- * type SharedScopes = {
- *   'user:{user_id}': { user_id: string };
- *   'project:{project_id}': { project_id: string };
- *   'event_date:{year}:{month}': { year: string; month: string };
- * };
+ * 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 SharedScopesDefinition = Record<
-  ScopePattern,
-  Record<string, string>
+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>
 >;
 
 /**
@@ -64,7 +107,21 @@ export type SharedScopesDefinition = Record<
  * ]
  * ```
  */
-export type ScopeDefinition = string | { pattern: string; column: string };
+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) ───────────────────────────────
 
@@ -87,36 +144,6 @@ function extractPlaceholder(pattern: string): {
   };
 }
 
-/**
- * Match a scope string against a pattern and extract the value.
- */
-function matchScopePattern(pattern: string, scopeKey: string): string | null {
-  const parsed = extractPlaceholder(pattern);
-  if (!parsed) {
-    // No placeholder - exact match
-    return pattern === scopeKey ? '' : null;
-  }
-
-  const { prefix, suffix } = parsed;
-
-  if (!scopeKey.startsWith(prefix)) {
-    return null;
-  }
-
-  if (suffix && !scopeKey.endsWith(suffix)) {
-    return null;
-  }
-
-  const valueStart = prefix.length;
-  const valueEnd = suffix ? scopeKey.length - suffix.length : scopeKey.length;
-
-  if (valueStart >= valueEnd) {
-    return null;
-  }
-
-  return scopeKey.slice(valueStart, valueEnd);
-}
-
 /**
  * Extract the placeholder name from a pattern.
  */
@@ -125,33 +152,6 @@ function getPlaceholderName(pattern: string): string | null {
   return parsed?.placeholder ?? null;
 }
 
-// ── Pattern operations (public) ──────────────────────────────────────
-
-/**
- * Build a scope string from a pattern and value.
- *
- * @example
- * buildScopeKey('user:{user_id}', '123') // 'user:123'
- */
-export function buildScopeKey(pattern: string, value: string): string {
-  const parsed = extractPlaceholder(pattern);
-  if (!parsed) {
-    return pattern;
-  }
-
-  return `${parsed.prefix}${value}${parsed.suffix}`;
-}
-
-/**
- * Check if a scope string matches a pattern.
- */
-export function scopeKeyMatchesPattern(
-  pattern: string,
-  scopeKey: string
-): boolean {
-  return matchScopePattern(pattern, scopeKey) !== null;
-}
-
 /**
  * Normalize scope definitions to a pattern-to-column map.
  *
@@ -160,9 +160,9 @@ export function scopeKeyMatchesPattern(
  * // → { 'user:{user_id}': 'user_id' }
  */
 export function normalizeScopes(
-  scopes: ScopeDefinition[]
-): Record<string, string> {
-  const result: Record<string, string> = {};
+  scopes: readonly ScopeDefinition[]
+): Record<ScopePattern, string> {
+  const result: Record<ScopePattern, string> = {};
   for (const scope of scopes) {
     if (typeof scope === 'string') {
       const placeholder = getPlaceholderName(scope);
@@ -179,22 +179,6 @@ export function normalizeScopes(
   return result;
 }
 
-/**
- * Find the matching pattern and extract value from a scope string.
- */
-export function findMatchingPattern(
-  patterns: Record<string, string>,
-  scopeKey: string
-): { pattern: string; column: string; value: string } | null {
-  for (const [pattern, column] of Object.entries(patterns)) {
-    const value = matchScopePattern(pattern, scopeKey);
-    if (value !== null) {
-      return { pattern, column, value };
-    }
-  }
-  return null;
-}
-
 // ── Value operations (public) ────────────────────────────────────────
 
 /**
@@ -209,115 +193,3 @@ export function extractScopeVars(pattern: ScopePattern): string[] {
   if (!matches) return [];
   return matches.map((m) => m.slice(1, -1));
 }
-
-/**
- * Build scope values from a row based on a scope pattern.
- * Uses the pattern's variable names to extract values from the row.
- *
- * @example
- * buildScopeValuesFromRow('project:{project_id}', { id: '1', project_id: 'P1' })
- * // { project_id: 'P1' }
- */
-export function buildScopeValuesFromRow(
-  pattern: ScopePattern,
-  row: Record<string, unknown>
-): StoredScopes {
-  const vars = extractScopeVars(pattern);
-  const result: StoredScopes = {};
-
-  for (const varName of vars) {
-    const value = row[varName];
-    if (value === null || value === undefined) {
-      result[varName] = '';
-    } else {
-      result[varName] = String(value);
-    }
-  }
-
-  return result;
-}
-
-/**
- * Merge multiple scope value objects into one.
- * Later values override earlier ones.
- */
-export function mergeScopeValues(...sources: StoredScopes[]): StoredScopes {
-  const result: StoredScopes = {};
-  for (const source of sources) {
-    for (const [key, value] of Object.entries(source)) {
-      result[key] = value;
-    }
-  }
-  return result;
-}
-
-/**
- * Check if two stored scopes are equal.
- */
-export function scopesEqual(a: StoredScopes, b: StoredScopes): boolean {
-  const keysA = Object.keys(a).sort();
-  const keysB = Object.keys(b).sort();
-
-  if (keysA.length !== keysB.length) return false;
-
-  for (let i = 0; i < keysA.length; i++) {
-    if (keysA[i] !== keysB[i]) return false;
-    if (a[keysA[i]!] !== b[keysB[i]!]) return false;
-  }
-
-  return true;
-}
-
-/**
- * Check if stored scopes match a subscription's scope values.
- * Handles array values in subscription (OR semantics).
- * Missing keys in subscription are treated as wildcards (match any).
- *
- * @example
- * scopesMatchSubscription({ project_id: 'P1' }, { project_id: 'P1' }) // true
- * scopesMatchSubscription({ project_id: 'P1' }, { project_id: ['P1', 'P2'] }) // true
- * scopesMatchSubscription({ project_id: 'P1' }, { project_id: 'P2' }) // false
- */
-export function scopesMatchSubscription(
-  stored: StoredScopes,
-  subscription: ScopeValues
-): boolean {
-  for (const [key, subValue] of Object.entries(subscription)) {
-    const storedValue = stored[key];
-    if (storedValue === undefined) return false;
-
-    if (Array.isArray(subValue)) {
-      if (!subValue.includes(storedValue)) return false;
-    } else {
-      if (storedValue !== subValue) return false;
-    }
-  }
-
-  return true;
-}
-
-/**
- * Normalize scope values to always use arrays (for consistent handling).
- */
-export function normalizeScopeValues(
-  values: ScopeValues
-): Record<string, string[]> {
-  const result: Record<string, string[]> = {};
-  for (const [key, value] of Object.entries(values)) {
-    result[key] = Array.isArray(value) ? value : [value];
-  }
-  return result;
-}
-
-/**
- * Get all scope variable names from a set of patterns.
- */
-export function getAllScopeVars(patterns: ScopePattern[]): string[] {
-  const vars = new Set<string>();
-  for (const pattern of patterns) {
-    for (const v of extractScopeVars(pattern)) {
-      vars.add(v);
-    }
-  }
-  return Array.from(vars);
-}

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