@syncular/core 0.1.2 → 0.2.0

package/src/types.ts

@@ -1,267 +0,0 @@
-/**
- * @syncular/core - Shared types for sync infrastructure
- *
- * Non-protocol types: conflict detection, transport interfaces.
- * Protocol types (SyncOp, SyncPushRequest, etc.) live in ./schemas/sync.ts
- */
-
-import type { SyncCombinedRequest, SyncCombinedResponse } from './schemas/sync';
-
-// ============================================================================
-// Conflict Detection Types
-// ============================================================================
-
-/**
- * Result of a conflict check - no conflict
- */
-interface ConflictCheckResultOk {
-  hasConflict: false;
-}
-
-/**
- * Result of a conflict check - conflict detected
- */
-interface ConflictCheckResultConflict {
-  hasConflict: true;
-  /** Fields with conflicting changes */
-  conflictingFields: string[];
-  /** Current server row state */
-  serverRow: Record<string, unknown>;
-  /** Current server version */
-  serverVersion: number;
-}
-
-/**
- * Union type for conflict check results
- */
-export type ConflictCheckResult =
-  | ConflictCheckResultOk
-  | ConflictCheckResultConflict;
-
-/**
- * Result of a field-level merge - can merge
- */
-export interface MergeResultOk {
-  canMerge: true;
-  /** Merged payload combining client and server changes */
-  mergedPayload: Record<string, unknown>;
-}
-
-/**
- * Result of a field-level merge - cannot merge
- */
-export interface MergeResultConflict {
-  canMerge: false;
-  /** Fields that cannot be auto-merged */
-  conflictingFields: string[];
-}
-
-/**
- * Union type for merge results
- */
-export type MergeResult = MergeResultOk | MergeResultConflict;
-
-// ============================================================================
-// Identity Types
-// ============================================================================
-
-/**
- * Canonical identity base shape used across Syncular auth-bound APIs.
- */
-export interface SyncIdentityBase {
-  actorId: string;
-}
-
-// ============================================================================
-// Transport Types
-// ============================================================================
-
-/**
- * Options for transport operations.
- * Provides hooks for auth errors and cancellation support.
- */
-export type SyncAuthOperation =
-  | 'sync'
-  | 'authLeaseIssue'
-  | 'snapshotChunk'
-  | 'snapshotChunkStream'
-  | 'blobInitiateUpload'
-  | 'blobCompleteUpload'
-  | 'blobGetDownloadUrl';
-
-export interface SyncAuthErrorContext {
-  operation: SyncAuthOperation;
-  status: 401 | 403;
-}
-
-export interface SyncAuthRetryContext extends SyncAuthErrorContext {
-  refreshResult: boolean;
-}
-
-export interface SyncAuthLifecycle {
-  /**
-   * Called when a request receives 401/403.
-   * Useful for marking auth/session as stale in app state.
-   */
-  onAuthExpired?: (context: SyncAuthErrorContext) => Promise<void> | void;
-  /**
-   * Refresh credentials.
-   * Return true when refresh succeeded and a retry should be considered.
-   */
-  refreshToken?: (context: SyncAuthErrorContext) => Promise<boolean> | boolean;
-  /**
-   * Final retry decision after refresh completes.
-   * Defaults to `refreshResult` when omitted.
-   */
-  retryWithFreshToken?: (
-    context: SyncAuthRetryContext
-  ) => Promise<boolean> | boolean;
-}
-
-export interface SyncTransportOptions {
-  /**
-   * First-class auth lifecycle callbacks.
-   * Use this to centralize auth refresh behavior.
-   */
-  authLifecycle?: SyncAuthLifecycle;
-  /**
-   * Abort signal for cancellation support.
-   */
-  signal?: AbortSignal;
-}
-
-export type SyncSnapshotChunkReadMode = 'stream' | 'bytes';
-
-export type SyncGzipDecompressionMode = 'stream' | 'buffered';
-
-export type SyncBootstrapApplyMode = 'single-transaction' | 'per-subscription';
-
-/**
- * Declares transport/runtime capabilities that affect how the client should
- * fetch, decode, and apply bootstrap snapshots.
- */
-export interface SyncTransportCapabilities {
-  /**
-   * Preferred snapshot chunk download mode for this runtime.
-   * - `stream`: consume the response body as a stream when available
-   * - `bytes`: buffer the whole response body before decode/apply
-   */
-  snapshotChunkReadMode?: SyncSnapshotChunkReadMode;
-  /**
-   * Preferred gzip decode mode for this runtime.
-   * - `stream`: use `DecompressionStream`
-   * - `buffered`: gunzip a materialized byte buffer
-   */
-  gzipDecompressionMode?: SyncGzipDecompressionMode;
-  /**
-   * Hint that chunked bootstrap snapshots should be materialized into rows
-   * before plugin/app consumption.
-   */
-  preferMaterializedSnapshots?: boolean;
-  /**
-   * Preferred default transaction strategy for bootstrap apply.
-   */
-  preferredBootstrapApplyMode?: SyncBootstrapApplyMode;
-  /**
-   * Preferred scheduler yield delay (ms) between bootstrap snapshot apply
-   * batches. `0` yields on the next macrotask, `false` disables yielding.
-   */
-  preferredSnapshotApplyYieldMs?: number | false;
-}
-
-/**
- * Blob transport operations (optional extension to SyncTransport).
- * When present, enables blob upload/download through the same transport.
- */
-export interface SyncTransportBlobs {
-  /**
-   * Initiate a blob upload.
-   * Returns presigned URL info or indicates blob already exists (dedup).
-   */
-  initiateUpload(args: {
-    hash: string;
-    size: number;
-    mimeType: string;
-  }): Promise<{
-    exists: boolean;
-    uploadUrl?: string;
-    uploadMethod?: 'PUT' | 'POST';
-    uploadHeaders?: Record<string, string>;
-  }>;
-
-  /**
-   * Complete a blob upload.
-   * Call this after uploading to the presigned URL.
-   */
-  completeUpload(hash: string): Promise<{ ok: boolean; error?: string }>;
-
-  /**
-   * Get a presigned download URL.
-   */
-  getDownloadUrl(hash: string): Promise<{
-    url: string;
-    expiresAt: string;
-  }>;
-}
-
-/**
- * Transport interface for sync operations.
- */
-export interface SyncTransport {
-  /**
-   * Optional runtime/transport capabilities.
-   */
-  capabilities?: SyncTransportCapabilities;
-  /**
-   * Combined push+pull in a single round-trip.
-   */
-  sync(
-    request: SyncCombinedRequest,
-    options?: SyncTransportOptions
-  ): Promise<SyncCombinedResponse>;
-
-  /**
-   * Download an encoded bootstrap snapshot chunk.
-   */
-  fetchSnapshotChunk(
-    request: {
-      chunkId: string;
-      scopeValues?: Record<string, string | string[]>;
-    },
-    options?: SyncTransportOptions
-  ): Promise<Uint8Array>;
-
-  /**
-   * Optional streaming snapshot chunk download.
-   *
-   * When implemented, clients can decode and apply large bootstrap chunks
-   * incrementally without materializing the entire chunk in memory.
-   */
-  fetchSnapshotChunkStream?(
-    request: {
-      chunkId: string;
-      scopeValues?: Record<string, string | string[]>;
-    },
-    options?: SyncTransportOptions
-  ): Promise<ReadableStream<Uint8Array>>;
-
-  /**
-   * Optional blob operations.
-   * When present, enables blob upload/download functionality.
-   */
-  blobs?: SyncTransportBlobs;
-}
-
-/**
- * Transport error with additional context
- */
-export class SyncTransportError extends Error {
-  constructor(
-    message: string,
-    public readonly status?: number,
-    public readonly code?: string
-  ) {
-    super(message);
-    this.name = 'SyncTransportError';
-  }
-}

package/src/utils/bytes.ts

@@ -1,75 +0,0 @@
-import { getBunRuntime } from './internal-runtime';
-
-export function bytesToReadableStream(
-  bytes: Uint8Array
-): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    },
-  });
-}
-
-export function concatByteChunks(chunks: readonly Uint8Array[]): Uint8Array {
-  if (chunks.length === 0) {
-    return new Uint8Array();
-  }
-  if (chunks.length === 1) {
-    return chunks[0] ?? new Uint8Array();
-  }
-
-  let total = 0;
-  for (const chunk of chunks) {
-    total += chunk.length;
-  }
-
-  const merged = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    merged.set(chunk, offset);
-    offset += chunk.length;
-  }
-  return merged;
-}
-
-export async function readAllBytesFromStream(
-  stream: ReadableStream<Uint8Array>
-): Promise<Uint8Array> {
-  const bun = getBunRuntime();
-  if (bun?.readableStreamToBytes) {
-    const bytes = await bun.readableStreamToBytes(stream);
-    return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-  }
-
-  const reader = stream.getReader();
-  const chunks: Uint8Array[] = [];
-  let total = 0;
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      if (!value) continue;
-      chunks.push(value);
-      total += value.length;
-    }
-  } finally {
-    reader.releaseLock();
-  }
-
-  if (chunks.length === 0) {
-    return new Uint8Array();
-  }
-  if (chunks.length === 1) {
-    return chunks[0] ?? new Uint8Array();
-  }
-
-  const merged = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    merged.set(chunk, offset);
-    offset += chunk.length;
-  }
-  return merged;
-}

package/src/utils/compression.ts

@@ -1,187 +0,0 @@
-import { gunzipSync as gunzipSyncFflate } from 'fflate';
-import { bytesToReadableStream, readAllBytesFromStream } from './bytes';
-import { getBunRuntime, usesNodeRuntimeModules } from './internal-runtime';
-
-type CompressionResult = Uint8Array | ArrayBuffer | ArrayLike<number>;
-
-interface NodeZlibModule {
-  gzip(
-    payload: Uint8Array,
-    callback: (error: Error | null, compressed: CompressionResult) => void
-  ): void;
-  gzip(
-    payload: Uint8Array,
-    options: { level?: number },
-    callback: (error: Error | null, compressed: CompressionResult) => void
-  ): void;
-  gunzip(
-    payload: Uint8Array,
-    callback: (error: Error | null, decompressed: CompressionResult) => void
-  ): void;
-}
-
-let nodeZlibModulePromise: Promise<NodeZlibModule | null> | null = null;
-
-export interface GzipBytesOptions {
-  level?: number;
-}
-
-function importNodeModule(specifier: string): Promise<object> {
-  return new Function('specifier', 'return import(specifier);')(
-    specifier
-  ) as Promise<object>;
-}
-
-function tryImportNodeModule(specifier: string): Promise<object | null> {
-  try {
-    return importNodeModule(specifier);
-  } catch {
-    return Promise.resolve(null);
-  }
-}
-
-function isNodeZlibModule(module: object | null): module is NodeZlibModule {
-  if (!module) {
-    return false;
-  }
-
-  const candidate = module as Partial<NodeZlibModule>;
-  return (
-    typeof candidate.gzip === 'function' &&
-    typeof candidate.gunzip === 'function'
-  );
-}
-
-function toUint8Array(value: CompressionResult): Uint8Array {
-  if (value instanceof Uint8Array) {
-    return value;
-  }
-  if (value instanceof ArrayBuffer) {
-    return new Uint8Array(value);
-  }
-  return Uint8Array.from(value);
-}
-
-async function getNodeZlibModule(): Promise<NodeZlibModule | null> {
-  if (!usesNodeRuntimeModules()) {
-    return null;
-  }
-  if (!nodeZlibModulePromise) {
-    nodeZlibModulePromise = tryImportNodeModule('node:zlib')
-      .then((module) => (isNodeZlibModule(module) ? module : null))
-      .catch(() => null);
-  }
-  return nodeZlibModulePromise;
-}
-
-/**
- * Gzip-compress a byte array using the fastest native implementation available
- * in the current runtime.
- */
-export async function gzipBytes(
-  payload: Uint8Array,
-  options: GzipBytesOptions = {}
-): Promise<Uint8Array> {
-  const bun = getBunRuntime();
-  if (bun?.gzipSync) {
-    return bun.gzipSync(payload, options);
-  }
-
-  const nodeZlib = await getNodeZlibModule();
-  if (nodeZlib?.gzip) {
-    return await new Promise<Uint8Array>((resolve, reject) => {
-      const callback = (error: Error | null, compressed: CompressionResult) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve(toUint8Array(compressed));
-      };
-      if (options.level !== undefined) {
-        nodeZlib.gzip(payload, { level: options.level }, callback);
-      } else {
-        nodeZlib.gzip(payload, callback);
-      }
-    });
-  }
-
-  if (typeof CompressionStream !== 'undefined') {
-    const stream = bytesToReadableStream(payload).pipeThrough(
-      new CompressionStream('gzip') as TransformStream<Uint8Array, Uint8Array>
-    );
-    return readAllBytesFromStream(stream);
-  }
-
-  throw new Error(
-    'Failed to gzip bytes, no compression implementation available'
-  );
-}
-
-/**
- * Gzip-decompress a byte array using the fastest implementation available in
- * the current runtime, with a pure-JS fallback for runtimes like Expo/Hermes.
- */
-export async function gunzipBytes(payload: Uint8Array): Promise<Uint8Array> {
-  const bun = getBunRuntime();
-  if (bun?.gunzipSync) {
-    return bun.gunzipSync(payload);
-  }
-
-  const nodeZlib = await getNodeZlibModule();
-  if (nodeZlib?.gunzip) {
-    return await new Promise<Uint8Array>((resolve, reject) => {
-      nodeZlib.gunzip(payload, (error, decompressed) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve(toUint8Array(decompressed));
-      });
-    });
-  }
-
-  if (typeof DecompressionStream !== 'undefined') {
-    const stream = bytesToReadableStream(payload).pipeThrough(
-      new DecompressionStream('gzip') as TransformStream<Uint8Array, Uint8Array>
-    );
-    return readAllBytesFromStream(stream);
-  }
-
-  try {
-    return gunzipSyncFflate(payload);
-  } catch (error) {
-    throw new Error(
-      'Failed to gunzip bytes, no decompression implementation available',
-      { cause: error }
-    );
-  }
-}
-
-/**
- * Gzip-compress bytes and return a stream. When streaming compression is not
- * available, falls back to eager compression and includes byteLength metadata.
- */
-export async function gzipBytesToStream(payload: Uint8Array): Promise<{
-  stream: ReadableStream<Uint8Array>;
-  byteLength?: number;
-}> {
-  const bun = getBunRuntime();
-  const nodeZlib = await getNodeZlibModule();
-
-  if (!bun?.gzipSync && !nodeZlib && typeof CompressionStream !== 'undefined') {
-    const source = bytesToReadableStream(payload);
-    const gzipStream = new CompressionStream('gzip') as TransformStream<
-      Uint8Array,
-      Uint8Array
-    >;
-    return {
-      stream: source.pipeThrough(gzipStream),
-    };
-  }
-
-  const compressed = await gzipBytes(payload);
-  return {
-    stream: bytesToReadableStream(compressed),
-    byteLength: compressed.length,
-  };
-}

package/src/utils/crypto.ts

@@ -1,146 +0,0 @@
-import { concatByteChunks } from './bytes';
-import { getBunRuntime, usesNodeRuntimeModules } from './internal-runtime';
-
-const textEncoder = new TextEncoder();
-
-interface NodeHash {
-  update(data: string | Uint8Array): NodeHash;
-  digest(encoding: 'hex'): string;
-}
-
-interface NodeCryptoModule {
-  createHash(algorithm: string): NodeHash;
-}
-
-function toHex(bytes: Uint8Array): string {
-  return Array.from(bytes)
-    .map((byte) => byte.toString(16).padStart(2, '0'))
-    .join('');
-}
-
-function toDigestBufferSource(payload: Uint8Array): Uint8Array<ArrayBuffer> {
-  if (payload.buffer instanceof ArrayBuffer) {
-    return new Uint8Array(
-      payload.buffer,
-      payload.byteOffset,
-      payload.byteLength
-    );
-  }
-
-  const owned = new Uint8Array(payload.byteLength);
-  owned.set(payload);
-  return owned;
-}
-
-let nodeCryptoModulePromise: Promise<NodeCryptoModule | null> | null = null;
-
-function importNodeModule(specifier: string): Promise<object> {
-  return new Function('specifier', 'return import(specifier);')(
-    specifier
-  ) as Promise<object>;
-}
-
-function tryImportNodeModule(specifier: string): Promise<object | null> {
-  try {
-    return importNodeModule(specifier);
-  } catch {
-    return Promise.resolve(null);
-  }
-}
-
-function isNodeCryptoModule(module: object | null): module is NodeCryptoModule {
-  if (!module) {
-    return false;
-  }
-  return typeof (module as Partial<NodeCryptoModule>).createHash === 'function';
-}
-
-async function getNodeCryptoModule(): Promise<NodeCryptoModule | null> {
-  if (!usesNodeRuntimeModules()) {
-    return null;
-  }
-  if (!nodeCryptoModulePromise) {
-    nodeCryptoModulePromise = tryImportNodeModule('node:crypto')
-      .then((module) => (isNodeCryptoModule(module) ? module : null))
-      .catch(() => null);
-  }
-  return nodeCryptoModulePromise;
-}
-
-export interface IncrementalSha256 {
-  update(chunk: Uint8Array): void;
-  digestHex(): Promise<string>;
-}
-
-export async function createIncrementalSha256(): Promise<IncrementalSha256> {
-  const bun = getBunRuntime();
-  if (bun?.CryptoHasher) {
-    const hasher = new bun.CryptoHasher('sha256');
-    return {
-      update(chunk) {
-        hasher.update(chunk);
-      },
-      async digestHex() {
-        return hasher.digest('hex');
-      },
-    };
-  }
-
-  const nodeCrypto = await getNodeCryptoModule();
-  if (nodeCrypto?.createHash) {
-    const hasher = nodeCrypto.createHash('sha256');
-    return {
-      update(chunk) {
-        hasher.update(chunk);
-      },
-      async digestHex() {
-        return hasher.digest('hex');
-      },
-    };
-  }
-
-  const chunks: Uint8Array[] = [];
-  return {
-    update(chunk) {
-      if (chunk.length === 0) return;
-      chunks.push(chunk.slice());
-    },
-    async digestHex() {
-      return sha256Hex(concatByteChunks(chunks));
-    },
-  };
-}
-
-/**
- * Cross-runtime SHA-256 digest helper.
- *
- * Uses native Bun/Node implementations on server runtimes, with Web Crypto
- * fallback for browser and worker environments.
- */
-export async function sha256Hex(input: string | Uint8Array): Promise<string> {
-  const payload = typeof input === 'string' ? textEncoder.encode(input) : input;
-
-  const bun = getBunRuntime();
-  if (bun?.CryptoHasher) {
-    const hasher = new bun.CryptoHasher('sha256');
-    hasher.update(payload);
-    return hasher.digest('hex');
-  }
-
-  const nodeCrypto = await getNodeCryptoModule();
-  if (nodeCrypto?.createHash) {
-    return nodeCrypto.createHash('sha256').update(payload).digest('hex');
-  }
-
-  if (typeof crypto !== 'undefined' && crypto.subtle) {
-    const digestBuffer = await crypto.subtle.digest(
-      'SHA-256',
-      toDigestBufferSource(payload)
-    );
-    return toHex(new Uint8Array(digestBuffer));
-  }
-
-  throw new Error(
-    'Failed to create SHA-256 hash, no crypto implementation available'
-  );
-}

package/src/utils/id.ts

@@ -1,34 +0,0 @@
-export function generateId(): string {
-  type SyncularCryptoSource = {
-    randomUUID?: () => string;
-    getRandomValues?: <T extends ArrayBufferView>(array: T) => T;
-  };
-  const globalWithCrypto = globalThis as typeof globalThis & {
-    crypto?: SyncularCryptoSource;
-  };
-  const cryptoObj: SyncularCryptoSource | undefined =
-    typeof crypto !== 'undefined'
-      ? (crypto as SyncularCryptoSource)
-      : globalWithCrypto.crypto;
-  if (cryptoObj && typeof cryptoObj.randomUUID === 'function') {
-    return cryptoObj.randomUUID();
-  }
-
-  if (cryptoObj && typeof cryptoObj.getRandomValues === 'function') {
-    const bytes = new Uint8Array(16);
-    cryptoObj.getRandomValues(bytes);
-    // UUID v4 variant bits.
-    bytes[6] = (bytes[6]! & 0x0f) | 0x40;
-    bytes[8] = (bytes[8]! & 0x3f) | 0x80;
-    const hex = Array.from(bytes)
-      .map((byte) => byte.toString(16).padStart(2, '0'))
-      .join('');
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
-  }
-
-  return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
-}
-
-export function randomId(): string {
-  return generateId();
-}