cojson 0.19.21 → 0.20.0

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/coValueContentMessage.ts

@@ -61,20 +61,6 @@ export function exceedsRecommendedSize(
   );
 }
 
-const cachedTextEncoder = new TextEncoder();
-
-export function validateTxSizeLimitInBytes(changes: JsonValue[]): void {
-  const serializedSize = cachedTextEncoder.encode(
-    JSON.stringify(changes),
-  ).length;
-  if (serializedSize > TRANSACTION_CONFIG.MAX_TX_SIZE_BYTES) {
-    throw new Error(
-      `Transaction is too large to be synced: ${serializedSize} > ${TRANSACTION_CONFIG.MAX_TX_SIZE_BYTES} bytes. ` +
-        `Consider breaking your transaction into smaller chunks.`,
-    );
-  }
-}
-
 export function knownStateFromContent(content: NewContentMessage) {
   const knownState = emptyKnownState(content.id);
   knownState.header = Boolean(content.header);

package/src/coValueCore/SessionMap.ts

@@ -7,7 +7,7 @@ import type {
   Signature,
   SignerID,
 } from "../crypto/crypto.js";
-import { RawCoID, SessionID } from "../ids.js";
+import { isDeleteSessionID, RawCoID, SessionID } from "../ids.js";
 import { parseJSON, Stringified } from "../jsonStringify.js";
 import { JsonObject, JsonValue } from "../jsonValue.js";
 import { TryAddTransactionsError } from "./coValueCore.js";
@@ -34,6 +34,7 @@ export type SessionLog = {
 };
 
 export class SessionMap {
+  private isDeleted: boolean = false;
   sessions: Map<SessionID, SessionLog> = new Map();
 
   // Known state related properies, mutated when adding transactions to the session map
@@ -60,7 +61,32 @@ export class SessionMap {
     }
   }
 
+  markAsDeleted() {
+    this.isDeleted = true;
+
+    // We reset the known state to report only the deleted session/transaction
+    this.knownState = { id: this.id, header: true, sessions: {} };
+
+    // We remove the streaming statuses, because once deleted we don't need
+    // to wait for any streaming to be completed
+    this.knownStateWithStreaming = undefined;
+    this.streamingKnownState = undefined;
+    this.invalidateKnownStateCache();
+
+    for (const [sessionID, sessionLog] of this.sessions.entries()) {
+      if (!isDeleteSessionID(sessionID)) {
+        continue;
+      }
+
+      this.knownState.sessions[sessionID] = sessionLog.transactions.length;
+    }
+  }
+
   setStreamingKnownState(streamingKnownState: KnownStateSessions) {
+    if (this.isDeleted) {
+      return;
+    }
+
     // if the streaming known state is a subset of the current known state, we can skip the update
     if (isKnownStateSubsetOf(streamingKnownState, this.knownState.sessions)) {
       return;
@@ -148,6 +174,10 @@ export class SessionMap {
     newSignature: Signature,
     skipVerify: boolean = false,
   ) {
+    if (this.isDeleted && !isDeleteSessionID(sessionID)) {
+      throw new Error("Cannot add transactions to a deleted coValue");
+    }
+
     const sessionLog = this.getOrCreateSessionLog(sessionID, signerID);
 
     sessionLog.impl.tryAdd(newTransactions, newSignature, skipVerify);
@@ -164,6 +194,12 @@ export class SessionMap {
     meta: JsonObject | undefined,
     madeAt: number,
   ): { signature: Signature; transaction: Transaction } {
+    if (this.isDeleted) {
+      throw new Error(
+        "Cannot make new private transaction on a deleted coValue",
+      );
+    }
+
     const sessionLog = this.getOrCreateSessionLog(
       sessionID,
       signerAgent.currentSignerID(),
@@ -194,6 +230,12 @@ export class SessionMap {
     meta: JsonObject | undefined,
     madeAt: number,
   ): { signature: Signature; transaction: Transaction } {
+    if (this.isDeleted) {
+      throw new Error(
+        "Cannot make new trusting transaction on a deleted coValue",
+      );
+    }
+
     const sessionLog = this.getOrCreateSessionLog(
       sessionID,
       signerAgent.currentSignerID(),