cojson 0.19.21 → 0.19.22

package/src/CojsonMessageChannel/types.ts

@@ -0,0 +1,200 @@
+/**
+ * Type definitions for JazzMessageChannel
+ *
+ * These types support cross-context communication via MessageChannel API
+ * and compatible implementations (e.g., Electron's MessageChannelMain).
+ */
+
+/**
+ * Duck-typed interface for any object that can receive messages via postMessage.
+ *
+ * Covers:
+ * - Worker
+ * - Window (including iframes via contentWindow)
+ * - MessagePort
+ * - ServiceWorker
+ * - Client (Service Worker clients)
+ * - Electron's WebContents (renderer windows)
+ */
+export interface PostMessageTarget {
+  postMessage(message: unknown, transfer?: MessagePortLike[]): void;
+  postMessage(
+    message: unknown,
+    targetOrigin: string,
+    transfer?: MessagePortLike[],
+  ): void;
+}
+
+/**
+ * MessagePort-like interface that covers browser MessagePort and Electron MessagePortMain.
+ *
+ * Note: Electron's MessagePortMain does not have a start() method,
+ * so it's optional here.
+ */
+export interface MessagePortLike {
+  postMessage(message: unknown): void;
+  addEventListener(
+    type: "message" | "messageerror",
+    listener: (event: unknown) => void,
+  ): void;
+  removeEventListener(
+    type: "message" | "messageerror",
+    listener: (event: unknown) => void,
+  ): void;
+  addEventListener(event: "close", listener: () => void): void;
+  removeEventListener(type: "close", listener: () => void): void;
+  /** Optional - not present on Electron's MessagePortMain */
+  start?(): void;
+  close(): void;
+}
+
+/**
+ * MessageChannel-like interface that covers browser MessageChannel
+ * and Electron MessageChannelMain.
+ */
+export interface MessageChannelLike {
+  port1: MessagePortLike;
+  port2: MessagePortLike;
+}
+
+/**
+ * Options for JazzMessageChannel.expose()
+ */
+export interface ExposeOptions {
+  /**
+   * Unique identifier for the peer connection, sent to the guest during handshake.
+   * Both sides will use this same ID for the Peer object.
+   * If not provided, a unique ID will be generated using `channel_${Math.random()}`.
+   */
+  id?: string;
+
+  /** Role of the peer in the sync topology */
+  role?: "client" | "server";
+
+  /** Target origin for Window targets (default: "*") */
+  targetOrigin?: string;
+
+  /**
+   * A pre-created MessageChannel to use instead of creating a new one.
+   * Use this for environments where the global MessageChannel is not available,
+   * e.g., Electron main process with MessageChannelMain.
+   * If not provided, a new MessageChannel will be created.
+   */
+  messageChannel?: MessageChannelLike;
+
+  /** Callback when the connection closes */
+  onClose?: () => void;
+}
+
+/**
+ * Options for CojsonMessageChannel.waitForConnection()
+ */
+export interface WaitForConnectionOptions {
+  /**
+   * Expected peer ID to accept.
+   * If provided, only handshakes with matching id will be accepted; others are ignored.
+   * If not provided, any connection will be accepted.
+   */
+  id?: string;
+
+  /** Role of the peer in the sync topology */
+  role?: "client" | "server";
+
+  /** Allowed origins for Window contexts (default: ["*"]) */
+  allowedOrigins?: string[];
+
+  /** Callback when the connection closes */
+  onClose?: () => void;
+}
+
+/**
+ * Options for CojsonMessageChannel.acceptFromPort()
+ * Note: No timeout option - acceptFromPort waits indefinitely.
+ */
+export interface AcceptFromPortOptions {
+  /**
+   * Expected peer ID to accept.
+   * If provided, only handshakes with matching id will be accepted; others are ignored.
+   * If not provided, any connection will be accepted.
+   */
+  id?: string;
+
+  /** Role of the peer in the sync topology */
+  role?: "client" | "server";
+
+  /** Callback when the connection closes */
+  onClose?: () => void;
+}
+
+/**
+ * Port transfer message sent via target.postMessage.
+ * The actual port is transferred via Transferable.
+ */
+export interface PortTransferMessage {
+  type: "jazz:port";
+  /** The peer ID for this connection */
+  id: string;
+}
+
+/**
+ * Ready signal sent from host to guest via MessagePort.
+ * Contains the peer ID that both sides will use.
+ */
+export interface ReadyMessage {
+  type: "jazz:ready";
+  /** The peer ID to use on both sides */
+  id: string;
+}
+
+/**
+ * Acknowledgment sent from guest to host via MessagePort.
+ * No id needed - guest uses the id from the host's ReadyMessage.
+ */
+export interface ReadyAckMessage {
+  type: "jazz:ready";
+}
+
+/**
+ * Union of all control messages used in the handshake protocol.
+ */
+export type ControlMessage =
+  | PortTransferMessage
+  | ReadyMessage
+  | ReadyAckMessage;
+
+/**
+ * Type guard to check if a message is a Jazz control message.
+ * Control messages are identified by having a "type" property starting with "jazz:".
+ */
+export function isControlMessage(msg: unknown): msg is ControlMessage {
+  return (
+    typeof msg === "object" &&
+    msg !== null &&
+    "type" in msg &&
+    typeof msg.type === "string" &&
+    msg.type.startsWith("jazz:")
+  );
+}
+
+/**
+ * Type guard to check if a message is a PortTransferMessage.
+ */
+export function isPortTransferMessage(
+  msg: unknown,
+): msg is PortTransferMessage {
+  return isControlMessage(msg) && msg.type === "jazz:port";
+}
+
+/**
+ * Type guard to check if a message is a ReadyMessage (with id).
+ */
+export function isReadyMessage(msg: unknown): msg is ReadyMessage {
+  return isControlMessage(msg) && msg.type === "jazz:ready" && "id" in msg;
+}
+
+/**
+ * Type guard to check if a message is a ReadyAckMessage (without id).
+ */
+export function isReadyAckMessage(msg: unknown): msg is ReadyAckMessage {
+  return isControlMessage(msg) && msg.type === "jazz:ready" && !("id" in msg);
+}

package/src/GarbageCollector.ts

@@ -2,13 +2,13 @@ import { CoValueCore } from "./coValueCore/coValueCore.js";
 import { GARBAGE_COLLECTOR_CONFIG } from "./config.js";
 import { RawCoID } from "./ids.js";
 
+/**
+ * TTL-based garbage collector for removing unused CoValues from memory.
+ */
 export class GarbageCollector {
   private readonly interval: ReturnType<typeof setInterval>;
 
-  constructor(
-    private readonly coValues: Map<RawCoID, CoValueCore>,
-    private readonly garbageCollectGroups: boolean,
-  ) {
+  constructor(private readonly coValues: Map<RawCoID, CoValueCore>) {
     this.interval = setInterval(() => {
       this.collect();
     }, GARBAGE_COLLECTOR_CONFIG.INTERVAL);
@@ -36,7 +36,7 @@ export class GarbageCollector {
       const timeSinceLastAccessed = currentTime - verified.lastAccessed;
 
       if (timeSinceLastAccessed > GARBAGE_COLLECTOR_CONFIG.MAX_AGE) {
-        coValue.unmount(this.garbageCollectGroups);
+        coValue.unmount();
       }
     }
   }

package/src/SyncStateManager.ts

@@ -4,14 +4,14 @@ import {
   areCurrentSessionsInSyncWith,
 } from "./knownState.js";
 import { PeerState } from "./PeerState.js";
-import { PeerID, SyncManager } from "./sync.js";
+import { Peer, PeerID, SyncManager } from "./sync.js";
 
 export type SyncState = {
   uploaded: boolean;
 };
 
 export type GlobalSyncStateListenerCallback = (
-  peerId: PeerID,
+  peer: Peer,
   knownState: CoValueKnownState,
   sync: SyncState,
 ) => void;
@@ -93,10 +93,10 @@ export class SyncStateManager {
     };
   }
 
-  triggerUpdate(peerId: PeerID, id: RawCoID, knownState: CoValueKnownState) {
+  triggerUpdate(peer: Peer, id: RawCoID, knownState: CoValueKnownState) {
     const globalListeners = this.listeners;
     const coValueListeners = this.listenersByCoValues.get(id);
-    const peerMap = this.listenersByPeersAndCoValues.get(peerId);
+    const peerMap = this.listenersByPeersAndCoValues.get(peer.id);
     const coValueAndPeerListeners = peerMap?.get(id);
 
     if (
@@ -113,12 +113,12 @@ export class SyncStateManager {
     };
 
     for (const listener of this.listeners) {
-      listener(peerId, knownState, syncState);
+      listener(peer, knownState, syncState);
     }
 
     if (coValueListeners) {
       for (const listener of coValueListeners) {
-        listener(peerId, knownState, syncState);
+        listener(peer, knownState, syncState);
       }
     }
 

package/src/coValueCore/coValueCore.ts

@@ -373,16 +373,26 @@ export class CoValueCore {
     }
   }
 
-  unmount(garbageCollectGroups = false) {
-    if (
-      !garbageCollectGroups &&
-      this.verified?.header.ruleset.type === "group"
-    ) {
+  /**
+   * Removes the CoValue from memory.
+   *
+   * @returns true if the coValue was successfully unmounted, false otherwise
+   */
+  unmount(): boolean {
+    if (this.listeners.size > 0) {
+      // The coValue is still in use
       return false;
     }
 
-    if (this.listeners.size > 0) {
-      return false; // The coValue is still in use
+    for (const dependant of this.dependant) {
+      if (this.node.hasCoValue(dependant)) {
+        // Another in-memory coValue depends on this coValue
+        return false;
+      }
+    }
+
+    if (!this.node.syncManager.isSyncedToServerPeers(this.id)) {
+      return false;
     }
 
     this.counter.add(-1, { state: this.loadingState });
@@ -1193,6 +1203,15 @@ export class CoValueCore {
     return matchingTransactions;
   }
 
+  /**
+   * The CoValues that this CoValue depends on.
+   * We currently track dependencies for:
+   * - Ownership (a CoValue depends on its account/group owner)
+   * - Group membership (a group depends on its direct account/group members)
+   * - Sessions (a CoValue depends on Accounts that made changes to it)
+   * - Branches (a branched CoValue depends on its branch source)
+   * See {@link dependant} for the CoValues that depend on this CoValue.
+   */
   dependencies: Set<RawCoID> = new Set();
   incompleteDependencies: Set<RawCoID> = new Set();
   private addDependency(dependency: RawCoID) {
@@ -1238,6 +1257,10 @@ export class CoValueCore {
     }
   }
 
+  /**
+   * The CoValues that depend on this CoValue.
+   * This is the inverse relationship of {@link dependencies}.
+   */
   dependant: Set<RawCoID> = new Set();
   private addDependant(dependant: RawCoID) {
     this.dependant.add(dependant);

package/src/exports.ts

@@ -206,6 +206,7 @@ export type {
 };
 
 export * from "./storage/index.js";
+export * from "./CojsonMessageChannel/index.js";
 
 // biome-ignore format: off
 // eslint-disable-next-line @typescript-eslint/no-namespace

package/src/localNode.ts

@@ -82,15 +82,12 @@ export class LocalNode {
     this.crypto = crypto;
   }
 
-  enableGarbageCollector(opts?: { garbageCollectGroups?: boolean }) {
+  enableGarbageCollector() {
     if (this.garbageCollector) {
       return;
     }
 
-    this.garbageCollector = new GarbageCollector(
-      this.coValues,
-      opts?.garbageCollectGroups ?? false,
-    );
+    this.garbageCollector = new GarbageCollector(this.coValues);
   }
 
   setStorage(storage: StorageAPI) {
@@ -133,6 +130,7 @@ export class LocalNode {
 
   internalDeleteCoValue(id: RawCoID) {
     this.coValues.delete(id);
+    this.storage?.onCoValueUnmounted(id);
   }
 
   getCurrentAccountOrAgentID(): RawAccountID | AgentID {

package/src/storage/storageAsync.ts

@@ -34,7 +34,11 @@ import type {
 export class StorageApiAsync implements StorageAPI {
   private readonly dbClient: DBClientInterfaceAsync;
 
-  private loadedCoValues = new Set<RawCoID>();
+  /**
+   * Keeps track of CoValues that are in memory, to avoid reloading them from storage
+   * when it isn't necessary
+   */
+  private inMemoryCoValues = new Set<RawCoID>();
 
   // Track pending loads to deduplicate concurrent requests
   private pendingKnownStateLoads = new Map<
@@ -153,7 +157,7 @@ export class StorageApiAsync implements StorageAPI {
       );
     }
 
-    this.loadedCoValues.add(coValueRow.id);
+    this.inMemoryCoValues.add(coValueRow.id);
 
     let contentMessage = createContentMessage(coValueRow.id, coValueRow.header);
 
@@ -224,7 +228,7 @@ export class StorageApiAsync implements StorageAPI {
     done?.(true);
   }
 
-  async pushContentWithDependencies(
+  private async pushContentWithDependencies(
     coValueRow: StoredCoValueRow,
     contentMessage: NewContentMessage,
     pushCallback: (data: NewContentMessage) => void,
@@ -237,7 +241,7 @@ export class StorageApiAsync implements StorageAPI {
     const promises = [];
 
     for (const dependedOnCoValue of dependedOnCoValuesList) {
-      if (this.loadedCoValues.has(dependedOnCoValue)) {
+      if (this.inMemoryCoValues.has(dependedOnCoValue)) {
         continue;
       }
 
@@ -364,6 +368,8 @@ export class StorageApiAsync implements StorageAPI {
       });
     }
 
+    this.inMemoryCoValues.add(id);
+
     this.knownStates.handleUpdate(id, knownState);
 
     if (invalidAssumptions) {
@@ -460,7 +466,12 @@ export class StorageApiAsync implements StorageAPI {
     this.dbClient.stopTrackingSyncState(id);
   }
 
+  onCoValueUnmounted(id: RawCoID): void {
+    this.inMemoryCoValues.delete(id);
+  }
+
   close() {
+    this.inMemoryCoValues.clear();
     return this.storeQueue.close();
   }
 }

package/src/storage/storageSync.ts

@@ -37,7 +37,11 @@ import { getPriorityFromHeader } from "../priority.js";
 
 export class StorageApiSync implements StorageAPI {
   private readonly dbClient: DBClientInterfaceSync;
-  private loadedCoValues = new Set<RawCoID>();
+  /**
+   * Keeps track of CoValues that are in memory, to avoid reloading them from storage
+   * when it isn't necessary
+   */
+  private inMemoryCoValues = new Set<RawCoID>();
 
   /**
    * Queue for streaming content that will be pulled by SyncManager.
@@ -138,7 +142,7 @@ export class StorageApiSync implements StorageAPI {
       );
     }
 
-    this.loadedCoValues.add(coValueRow.id);
+    this.inMemoryCoValues.add(coValueRow.id);
 
     const priority = getPriorityFromHeader(coValueRow.header);
     const contentMessage = createContentMessage(
@@ -244,7 +248,7 @@ export class StorageApiSync implements StorageAPI {
     });
   }
 
-  async pushContentWithDependencies(
+  private async pushContentWithDependencies(
     coValueRow: StoredCoValueRow,
     contentMessage: NewContentMessage,
     pushCallback: (data: NewContentMessage) => void,
@@ -255,7 +259,7 @@ export class StorageApiSync implements StorageAPI {
     );
 
     for (const dependedOnCoValue of dependedOnCoValuesList) {
-      if (this.loadedCoValues.has(dependedOnCoValue)) {
+      if (this.inMemoryCoValues.has(dependedOnCoValue)) {
         continue;
       }
 
@@ -353,6 +357,8 @@ export class StorageApiSync implements StorageAPI {
       });
     }
 
+    this.inMemoryCoValues.add(id);
+
     this.knownStates.handleUpdate(id, knownState);
 
     if (invalidAssumptions) {
@@ -450,7 +456,12 @@ export class StorageApiSync implements StorageAPI {
     this.dbClient.stopTrackingSyncState(id);
   }
 
+  onCoValueUnmounted(id: RawCoID): void {
+    this.inMemoryCoValues.delete(id);
+  }
+
   close() {
+    this.inMemoryCoValues.clear();
     return undefined;
   }
 }

package/src/storage/types.ts

@@ -67,6 +67,12 @@ export interface StorageAPI {
     callback: (knownState: CoValueKnownState | undefined) => void,
   ): void;
 
+  /**
+   * Called when a CoValue is unmounted from memory.
+   * Used to clean up the metadata associated with that CoValue.
+   */
+  onCoValueUnmounted(id: RawCoID): void;
+
   close(): Promise<unknown> | undefined;
 }
 

package/src/sync.ts

@@ -102,6 +102,10 @@ export interface Peer {
   persistent?: boolean;
 }
 
+function isPersistentServerPeer(peer: Peer | PeerState): boolean {
+  return peer.role === "server" && (peer.persistent ?? false);
+}
+
 export type ServerPeerSelector = (
   id: RawCoID,
   serverPeers: PeerState[],
@@ -354,7 +358,7 @@ export class SyncManager {
   }
 
   startPeerReconciliation(peer: PeerState) {
-    if (peer.role === "server" && peer.persistent) {
+    if (isPersistentServerPeer(peer)) {
       // Resume syncing unsynced CoValues asynchronously
       this.resumeUnsyncedCoValues().catch((error) => {
         logger.warn("Failed to resume unsynced CoValues:", error);
@@ -525,7 +529,7 @@ export class SyncManager {
 
     const unsubscribeFromKnownStatesUpdates =
       peerState.subscribeToKnownStatesUpdates((id, knownState) => {
-        this.syncState.triggerUpdate(peer.id, id, knownState.value());
+        this.syncState.triggerUpdate(peer, id, knownState.value());
       });
 
     if (!skipReconciliation && peerState.role === "server") {
@@ -711,8 +715,8 @@ export class SyncManager {
 
     peer.combineWith(msg.id, knownStateFrom(msg));
 
-    // The header is a boolean value that tells us if the other peer do have information about the header.
-    // If it's false in this point it means that the coValue is unavailable on the other peer.
+    // The header is a boolean value that tells us if the other peer has information about the header.
+    // If it's false at this point it means that the coValue is unavailable on the other peer.
     const availableOnPeer = peer.getOptimisticKnownState(msg.id)?.header;
 
     if (!availableOnPeer) {
@@ -1076,6 +1080,18 @@ export class SyncManager {
     const isSyncRequired = this.local.syncWhen !== "never";
     if (isSyncRequired && peers.length === 0) {
       this.unsyncedTracker.add(coValueId);
+
+      // Mark CoValue as synced once a persistent server peer is added and
+      // the CoValue is synced
+      const unsubscribe = this.syncState.subscribeToCoValueUpdates(
+        coValueId,
+        (peer, _knownState, syncState) => {
+          if (isPersistentServerPeer(peer) && syncState.uploaded) {
+            this.unsyncedTracker.remove(coValueId);
+            unsubscribe();
+          }
+        },
+      );
       return;
     }
 
@@ -1128,6 +1144,19 @@ export class SyncManager {
     });
   }
 
+  /**
+   * Returns true if the local CoValue changes have been synced to all persistent server peers.
+   *
+   * Used during garbage collection to determine if the coValue is pending sync.
+   */
+  isSyncedToServerPeers(id: RawCoID): boolean {
+    // If there are currently no server peers, go ahead with GC.
+    // The CoValue will be reloaded into memory and synced when a peer is added.
+    return this.getPersistentServerPeers(id).every((peer) =>
+      this.syncState.isSynced(peer, id),
+    );
+  }
+
   waitForSyncWithPeer(peerId: PeerID, id: RawCoID, timeout: number) {
     const peerState = this.peers[peerId];