@korajs/sync 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -1195,4 +1195,37 @@ declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
  */
 declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array): Promise<VersionedKey>;
 
-export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, versionVectorToWire, wireToVersionVector };
+/** Default status when sync is not configured or the engine is unavailable. */
+declare const OFFLINE_SYNC_STATUS: SyncStatusInfo;
+interface SyncStatusControllerOptions {
+    syncEngine?: {
+        getStatus(): SyncStatusInfo;
+    } | null;
+    getSyncEngine?: () => {
+        getStatus(): SyncStatusInfo;
+    } | null;
+    subscribeSyncStatus: ((listener: (status: SyncStatusInfo) => void) => () => void) | null;
+    events: KoraEventEmitter | null;
+}
+interface SyncStatusController {
+    getSnapshot(): SyncStatusInfo;
+    subscribe(listener: () => void): () => void;
+    refresh(): void;
+    destroy(): void;
+}
+/**
+ * Framework-agnostic sync status subscription with live reads when no bridge exists.
+ */
+declare function createSyncStatusController(options: SyncStatusControllerOptions): SyncStatusController;
+
+/**
+ * Returns remote collaborators' awareness states (excludes the local client).
+ */
+declare function getRemoteAwarenessStates(awareness: AwarenessManager): AwarenessState[];
+/**
+ * Subscribes to awareness changes and invokes `listener` only when the remote
+ * collaborator set changes.
+ */
+declare function subscribeRemoteAwarenessStates(awareness: AwarenessManager, listener: (states: AwarenessState[]) => void): () => void;
+
+export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };

package/dist/index.d.ts

@@ -1195,4 +1195,37 @@ declare function deriveKey(passphrase: string, salt?: Uint8Array): Promise<{
  */
 declare function deriveVersionedKey(passphrase: string, version: number, salt?: Uint8Array): Promise<VersionedKey>;
 
-export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, versionVectorToWire, wireToVersionVector };
+/** Default status when sync is not configured or the engine is unavailable. */
+declare const OFFLINE_SYNC_STATUS: SyncStatusInfo;
+interface SyncStatusControllerOptions {
+    syncEngine?: {
+        getStatus(): SyncStatusInfo;
+    } | null;
+    getSyncEngine?: () => {
+        getStatus(): SyncStatusInfo;
+    } | null;
+    subscribeSyncStatus: ((listener: (status: SyncStatusInfo) => void) => () => void) | null;
+    events: KoraEventEmitter | null;
+}
+interface SyncStatusController {
+    getSnapshot(): SyncStatusInfo;
+    subscribe(listener: () => void): () => void;
+    refresh(): void;
+    destroy(): void;
+}
+/**
+ * Framework-agnostic sync status subscription with live reads when no bridge exists.
+ */
+declare function createSyncStatusController(options: SyncStatusControllerOptions): SyncStatusController;
+
+/**
+ * Returns remote collaborators' awareness states (excludes the local client).
+ */
+declare function getRemoteAwarenessStates(awareness: AwarenessManager): AwarenessState[];
+/**
+ * Subscribes to awareness changes and invokes `listener` only when the remote
+ * collaborator set changes.
+ */
+declare function subscribeRemoteAwarenessStates(awareness: AwarenessManager, listener: (states: AwarenessState[]) => void): () => void;
+
+export { type AwarenessChange, type AwarenessCursor, AwarenessManager, type AwarenessMessage, type AwarenessState, type AwarenessUser, type ChaosConfig, ChaosTransport, ConnectionMonitor, type ConnectionMonitorConfig, type CursorInfo, DEFAULT_RICHTEXT_DOC_CHANNEL_THRESHOLD, DecryptionError, DeltaCursor, EncryptionError, HttpLongPollingTransport, type HttpLongPollingTransportOptions, JsonMessageSerializer, KeyDerivationError, type MessageSerializer, NegotiatedMessageSerializer, OFFLINE_SYNC_STATUS, type OutboundBatch, OutboundQueue, ProtobufMessageSerializer, QueueStorage, type ReconnectionConfig, ReconnectionManager, RichtextDocChannel, type RichtextDocChannelOptions, type RichtextDocListener, SCHEMA_MISMATCH_PREFIX, SerializedOperation, SyncConfig, type SyncDiagnostics, SyncEncryptionConfig, SyncEncryptor, SyncEngine, type SyncEngineOptions, SyncMessage, SyncQuerySubset, SyncScopeMap, SyncState, SyncStatePersistence, type SyncStatusController, type SyncStatusControllerOptions, SyncStatusInfo, type SyncStore, SyncTransport, TransportCloseHandler, TransportErrorHandler, TransportMessageHandler, TransportOptions, VersionedKey, type WebSocketConstructor, type WebSocketLike, WebSocketTransport, type WebSocketTransportOptions, WireFormat, YjsDocUpdateMessage, createDeltaCursorFromBatch, createSyncStatusController, decodeDeltaCursor, decodeYjsUpdate, deriveKey, deriveVersionedKey, encodeDeltaCursor, encodeYjsUpdate, filterOperationsByScope, generateSalt, getRemoteAwarenessStates, isClientSchemaVersionSupported, isEncryptedPayload, isSchemaMismatchReject, operationMatchesScope, richtextDocKey, sliceOperationsAfterCursor, subscribeRemoteAwarenessStates, versionVectorToWire, wireToVersionVector };

package/dist/index.js

@@ -3793,6 +3793,158 @@ function fromBase642(str) {
   }
   return bytes;
 }
+
+// src/reactivity/sync-status-controller.ts
+var OFFLINE_SYNC_STATUS = Object.freeze({
+  status: "offline",
+  pendingOperations: 0,
+  lastSyncedAt: null,
+  lastSuccessfulPush: null,
+  lastSuccessfulPull: null,
+  conflicts: 0
+});
+var SYNC_STATUS_EVENT_TYPES = [
+  "sync:connected",
+  "sync:disconnected",
+  "sync:schema-mismatch",
+  "sync:auth-failed",
+  "sync:sent",
+  "sync:received",
+  "sync:acknowledged",
+  "sync:apply-failed",
+  "sync:diagnostics",
+  "sync:initial-sync-progress"
+];
+function createSyncStatusController(options) {
+  const useLiveSnapshot = options.subscribeSyncStatus === null && options.events === null;
+  let snapshot = OFFLINE_SYNC_STATUS;
+  let serialized = JSON.stringify(OFFLINE_SYNC_STATUS);
+  const listeners = /* @__PURE__ */ new Set();
+  let cleanup = null;
+  const resolveEngine = () => {
+    return options.getSyncEngine?.() ?? options.syncEngine ?? null;
+  };
+  const notify = () => {
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  const setSnapshot = (next) => {
+    const nextSerialized = JSON.stringify(next);
+    if (nextSerialized === serialized) {
+      return;
+    }
+    serialized = nextSerialized;
+    snapshot = next;
+    notify();
+  };
+  const refresh = () => {
+    const engine = resolveEngine();
+    const next = engine ? engine.getStatus() : OFFLINE_SYNC_STATUS;
+    setSnapshot(next);
+  };
+  const attach = () => {
+    cleanup?.();
+    if (options.subscribeSyncStatus) {
+      cleanup = options.subscribeSyncStatus(setSnapshot);
+      return;
+    }
+    if (!resolveEngine()) {
+      setSnapshot(OFFLINE_SYNC_STATUS);
+      cleanup = () => {
+      };
+      return;
+    }
+    if (options.events) {
+      const unsubs = SYNC_STATUS_EVENT_TYPES.map((type) => options.events?.on(type, refresh));
+      refresh();
+      cleanup = () => {
+        for (const unsub of unsubs) {
+          unsub?.();
+        }
+      };
+      return;
+    }
+    refresh();
+    cleanup = () => {
+    };
+  };
+  attach();
+  return {
+    getSnapshot() {
+      if (useLiveSnapshot) {
+        const engine = resolveEngine();
+        return engine ? engine.getStatus() : OFFLINE_SYNC_STATUS;
+      }
+      return snapshot;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      listener();
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    refresh,
+    destroy() {
+      cleanup?.();
+      cleanup = null;
+      listeners.clear();
+    }
+  };
+}
+
+// src/reactivity/collaborators-snapshot.ts
+var EMPTY_COLLABORATORS = [];
+function awarenessStatesEqual(left, right) {
+  if (left.length !== right.length) {
+    return false;
+  }
+  for (let index = 0; index < left.length; index++) {
+    const a = left[index];
+    const b = right[index];
+    if (!a || !b) {
+      return false;
+    }
+    if (a.user.name !== b.user.name || a.user.color !== b.user.color) {
+      return false;
+    }
+    const aCursor = a.cursor;
+    const bCursor = b.cursor;
+    if (aCursor === void 0 && bCursor === void 0) {
+      continue;
+    }
+    if (!aCursor || !bCursor) {
+      return false;
+    }
+    if (aCursor.collection !== bCursor.collection || aCursor.recordId !== bCursor.recordId || aCursor.field !== bCursor.field || aCursor.anchor !== bCursor.anchor || aCursor.head !== bCursor.head) {
+      return false;
+    }
+  }
+  return true;
+}
+function getRemoteAwarenessStates(awareness) {
+  const localClientId = awareness.clientId;
+  const remoteStates = [];
+  for (const [clientId, state] of awareness.getStates()) {
+    if (clientId === localClientId) continue;
+    remoteStates.push(state);
+  }
+  return remoteStates;
+}
+function subscribeRemoteAwarenessStates(awareness, listener) {
+  let snapshot = EMPTY_COLLABORATORS;
+  const emitIfChanged = () => {
+    const next = getRemoteAwarenessStates(awareness);
+    if (awarenessStatesEqual(snapshot, next)) {
+      return;
+    }
+    snapshot = next;
+    listener(snapshot);
+  };
+  emitIfChanged();
+  return awareness.on("change", emitIfChanged);
+}
 export {
   AwarenessManager,
   ChaosTransport,
@@ -3805,6 +3957,7 @@ export {
   JsonMessageSerializer,
   KeyDerivationError,
   NegotiatedMessageSerializer,
+  OFFLINE_SYNC_STATUS,
   OutboundQueue,
   ProtobufMessageSerializer,
   ReconnectionManager,
@@ -3817,6 +3970,7 @@ export {
   SyncEngine,
   WebSocketTransport,
   createDeltaCursorFromBatch,
+  createSyncStatusController,
   decodeDeltaCursor,
   decodeYjsUpdate,
   dedupeQuerySubsets,
@@ -3826,6 +3980,7 @@ export {
   encodeYjsUpdate,
   filterOperationsByScope,
   generateSalt,
+  getRemoteAwarenessStates,
   isAcknowledgmentMessage,
   isAwarenessUpdateMessage,
   isClientSchemaVersionSupported,
@@ -3841,6 +3996,7 @@ export {
   operationMatchesScope,
   richtextDocKey,
   sliceOperationsAfterCursor,
+  subscribeRemoteAwarenessStates,
   versionVectorToWire,
   wireToVersionVector
 };