@syncular/core 0.0.6-96 → 0.1.1

package/src/telemetry.ts

@@ -113,13 +113,18 @@ const noopMetrics: SyncMetrics = {
   distribution() {},
 };
 
+type DeferredRuntimeGlobals = typeof globalThis & {
+  setImmediate?: (callback: () => void) => void;
+};
+
 function createConsoleLogger(): (event: SyncTelemetryEvent) => void {
+  const runtimeGlobals = globalThis as DeferredRuntimeGlobals;
   const isNode =
     typeof globalThis !== 'undefined' &&
-    typeof globalThis.setImmediate === 'function';
+    typeof runtimeGlobals.setImmediate === 'function';
 
   const defer = isNode
-    ? (fn: () => void) => globalThis.setImmediate(fn)
+    ? (fn: () => void) => runtimeGlobals.setImmediate?.(fn)
     : (fn: () => void) => setTimeout(fn, 0);
 
   return (event: SyncTelemetryEvent) => {

package/src/types.ts

@@ -61,6 +61,17 @@ export interface MergeResultConflict {
  */
 export type MergeResult = MergeResultOk | MergeResultConflict;
 
+// ============================================================================
+// Identity Types
+// ============================================================================
+
+/**
+ * Canonical identity base shape used across Syncular auth-bound APIs.
+ */
+export interface SyncIdentityBase {
+  actorId: string;
+}
+
 // ============================================================================
 // Transport Types
 // ============================================================================
@@ -71,6 +82,7 @@ export type MergeResult = MergeResultOk | MergeResultConflict;
  */
 export type SyncAuthOperation =
   | 'sync'
+  | 'authLeaseIssue'
   | 'snapshotChunk'
   | 'snapshotChunkStream'
   | 'blobInitiateUpload'
@@ -107,12 +119,6 @@ export interface SyncAuthLifecycle {
 }
 
 export interface SyncTransportOptions {
-  /**
-   * Legacy per-call auth retry callback.
-   * Return true to retry once after refreshing auth.
-   * If provided, this takes precedence over `authLifecycle`.
-   */
-  onAuthError?: () => Promise<boolean>;
   /**
    * First-class auth lifecycle callbacks.
    * Use this to centralize auth refresh behavior.
@@ -124,6 +130,45 @@ export interface SyncTransportOptions {
   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.
@@ -163,6 +208,10 @@ export interface SyncTransportBlobs {
  * Transport interface for sync operations.
  */
 export interface SyncTransport {
+  /**
+   * Optional runtime/transport capabilities.
+   */
+  capabilities?: SyncTransportCapabilities;
   /**
    * Combined push+pull in a single round-trip.
    */
@@ -175,7 +224,10 @@ export interface SyncTransport {
    * Download an encoded bootstrap snapshot chunk.
    */
   fetchSnapshotChunk(
-    request: { chunkId: string },
+    request: {
+      chunkId: string;
+      scopeValues?: Record<string, string | string[]>;
+    },
     options?: SyncTransportOptions
   ): Promise<Uint8Array>;
 
@@ -186,7 +238,10 @@ export interface SyncTransport {
    * incrementally without materializing the entire chunk in memory.
    */
   fetchSnapshotChunkStream?(
-    request: { chunkId: string },
+    request: {
+      chunkId: string;
+      scopeValues?: Record<string, string | string[]>;
+    },
     options?: SyncTransportOptions
   ): Promise<ReadableStream<Uint8Array>>;
 

package/src/utils/bytes.ts

@@ -0,0 +1,75 @@
+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,68 +1,160 @@
-function bytesToReadableStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
-  return new ReadableStream<Uint8Array>({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    },
-  });
+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;
 }
 
-async function streamToBytes(
-  stream: ReadableStream<Uint8Array>
-): Promise<Uint8Array> {
-  const reader = stream.getReader();
-  const chunks: Uint8Array[] = [];
-  let total = 0;
+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 {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      if (!value) continue;
-      chunks.push(value);
-      total += value.length;
-    }
-  } finally {
-    reader.releaseLock();
+    return importNodeModule(specifier);
+  } catch {
+    return Promise.resolve(null);
   }
+}
 
-  if (chunks.length === 0) return new Uint8Array();
-  if (chunks.length === 1) return chunks[0] ?? new Uint8Array();
+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'
+  );
+}
 
-  const merged = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    merged.set(chunk, offset);
-    offset += chunk.length;
+function toUint8Array(value: CompressionResult): Uint8Array {
+  if (value instanceof Uint8Array) {
+    return value;
   }
-  return merged;
+  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 CompressionStream when available,
- * with node:zlib fallback for Node/Bun runtimes.
+ * Gzip-compress a byte array using the fastest native implementation available
+ * in the current runtime.
  */
-export async function gzipBytes(payload: Uint8Array): Promise<Uint8Array> {
+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 unknown as TransformStream<
-        Uint8Array,
-        Uint8Array
-      >
+      new CompressionStream('gzip') as TransformStream<Uint8Array, Uint8Array>
     );
-    return streamToBytes(stream);
+    return readAllBytesFromStream(stream);
   }
 
-  const nodeZlib = await import('node:zlib');
-  return await new Promise<Uint8Array>((resolve, reject) => {
-    nodeZlib.gzip(payload, (error, compressed) => {
-      if (error) {
-        reject(error);
-        return;
-      }
-      resolve(new Uint8Array(compressed));
+  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 }
+    );
+  }
 }
 
 /**
@@ -73,11 +165,15 @@ export async function gzipBytesToStream(payload: Uint8Array): Promise<{
   stream: ReadableStream<Uint8Array>;
   byteLength?: number;
 }> {
-  if (typeof CompressionStream !== 'undefined') {
+  const bun = getBunRuntime();
+  const nodeZlib = await getNodeZlibModule();
+
+  if (!bun?.gzipSync && !nodeZlib && typeof CompressionStream !== 'undefined') {
     const source = bytesToReadableStream(payload);
-    const gzipStream = new CompressionStream(
-      'gzip'
-    ) as unknown as TransformStream<Uint8Array, Uint8Array>;
+    const gzipStream = new CompressionStream('gzip') as TransformStream<
+      Uint8Array,
+      Uint8Array
+    >;
     return {
       stream: source.pipeThrough(gzipStream),
     };

package/src/utils/crypto.ts

@@ -1,32 +1,145 @@
+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 Web Crypto when available, with Node crypto fallback.
+ * 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',
-      payload.slice().buffer
+      toDigestBufferSource(payload)
     );
     return toHex(new Uint8Array(digestBuffer));
   }
 
-  try {
-    const nodeCrypto = await import('node:crypto');
-    return nodeCrypto.createHash('sha256').update(payload).digest('hex');
-  } catch {}
-
   throw new Error(
     'Failed to create SHA-256 hash, no crypto implementation available'
   );

package/src/utils/id.ts

@@ -1,5 +1,15 @@
 export function generateId(): string {
-  const cryptoObj = typeof crypto !== 'undefined' ? crypto : globalThis.crypto;
+  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();
   }

package/src/utils/index.ts

@@ -1,4 +1,9 @@
+export * from './bytes';
 export * from './compression';
 export * from './crypto';
 export * from './id';
 export * from './object';
+export * from './realtime-change-index';
+export * from './realtime-connection-registry';
+export * from './table-registry';
+export * from './url';

package/src/utils/internal-runtime.ts

@@ -0,0 +1,39 @@
+interface BunCryptoHasher {
+  update(data: string | Uint8Array): void;
+  digest(encoding: 'hex'): string;
+}
+
+interface BunRuntime {
+  CryptoHasher?: new (algorithm: string) => BunCryptoHasher;
+  gzipSync?: (data: Uint8Array, options?: { level?: number }) => Uint8Array;
+  gunzipSync?: (data: Uint8Array) => Uint8Array;
+  readableStreamToBytes?: (
+    stream: ReadableStream<Uint8Array>
+  ) => Promise<Uint8Array | ArrayBuffer>;
+}
+
+type RuntimeGlobals = typeof globalThis & {
+  Bun?: BunRuntime;
+  Deno?: object;
+  process?: {
+    versions?: {
+      node?: string;
+    };
+  };
+};
+
+function getRuntimeGlobals(): RuntimeGlobals {
+  return globalThis as RuntimeGlobals;
+}
+
+export function getBunRuntime(): BunRuntime | null {
+  return getRuntimeGlobals().Bun ?? null;
+}
+
+export function usesNodeRuntimeModules(): boolean {
+  const globals = getRuntimeGlobals();
+  if (globals.Deno !== undefined) {
+    return true;
+  }
+  return typeof globals.process?.versions?.node === 'string';
+}