cojson 0.19.22 → 0.20.0

package/src/crypto/NapiCrypto.ts

@@ -19,7 +19,6 @@ import { RawCoID, SessionID, TransactionID } from "../ids.js";
 import { Stringified, stableStringify } from "../jsonStringify.js";
 import { JsonObject, JsonValue } from "../jsonValue.js";
 import { logger } from "../logger.js";
-import { PureJSCrypto } from "./PureJSCrypto.js";
 import {
   CryptoProvider,
   Encrypted,
@@ -58,7 +57,7 @@ export class NapiCrypto extends CryptoProvider<Blake3State> {
     super();
   }
 
-  static async create(): Promise<NapiCrypto | PureJSCrypto | WasmCrypto> {
+  static async create(): Promise<NapiCrypto | WasmCrypto> {
     return new NapiCrypto();
   }
 
@@ -190,11 +189,24 @@ class SessionLogAdapter {
     newSignature: Signature,
     skipVerify: boolean,
   ): void {
-    this.sessionLog.tryAdd(
-      transactions.map((tx) => stableStringify(tx)),
-      newSignature,
-      skipVerify,
-    );
+    // Use direct calls instead of JSON.stringify for better performance
+    for (const tx of transactions) {
+      if (tx.privacy === "private") {
+        this.sessionLog.addExistingPrivateTransaction(
+          tx.encryptedChanges,
+          tx.keyUsed,
+          tx.madeAt,
+          tx.meta,
+        );
+      } else {
+        this.sessionLog.addExistingTrustingTransaction(
+          tx.changes,
+          tx.madeAt,
+          tx.meta,
+        );
+      }
+    }
+    this.sessionLog.commitTransactions(newSignature, skipVerify);
   }
 
   addNewPrivateTransaction(
@@ -206,12 +218,14 @@ class SessionLogAdapter {
     meta: JsonObject | undefined,
   ): { signature: Signature; transaction: PrivateTransaction } {
     const output = this.sessionLog.addNewPrivateTransaction(
-      stableStringify(changes),
+      // We can avoid stableStringify because it will be encrypted.
+      JSON.stringify(changes),
       signerAgent.currentSignerSecret(),
       keySecret,
       keyID,
       madeAt,
-      meta ? stableStringify(meta) : undefined,
+      // We can avoid stableStringify because it will be encrypted.
+      meta ? JSON.stringify(meta) : undefined,
     );
     const parsedOutput = JSON.parse(output);
     const transaction: PrivateTransaction = {
@@ -230,8 +244,10 @@ class SessionLogAdapter {
     madeAt: number,
     meta: JsonObject | undefined,
   ): { signature: Signature; transaction: TrustingTransaction } {
-    const stringifiedChanges = stableStringify(changes);
-    const stringifiedMeta = meta ? stableStringify(meta) : undefined;
+    // We can avoid stableStringify because the changes will be in a string format already.
+    const stringifiedChanges = JSON.stringify(changes);
+    // We can avoid stableStringify because the meta will be in a string format already.
+    const stringifiedMeta = meta ? JSON.stringify(meta) : undefined;
     const output = this.sessionLog.addNewTrustingTransaction(
       stringifiedChanges,
       signerAgent.currentSignerSecret(),
@@ -241,8 +257,8 @@ class SessionLogAdapter {
     const transaction: TrustingTransaction = {
       privacy: "trusting",
       madeAt,
-      changes: stringifiedChanges,
-      meta: stringifiedMeta,
+      changes: stringifiedChanges as Stringified<JsonValue[]>,
+      meta: stringifiedMeta as Stringified<JsonObject> | undefined,
     };
     return { signature: output as Signature, transaction };
   }

package/src/crypto/RNCrypto.ts

@@ -47,6 +47,7 @@ import {
   Blake3Hasher,
   SessionLog,
 } from "cojson-core-rn";
+import { WasmCrypto } from "./WasmCrypto.js";
 
 type Blake3State = Blake3Hasher;
 
@@ -221,11 +222,24 @@ class SessionLogAdapter implements SessionLogImpl {
     newSignature: Signature,
     skipVerify: boolean,
   ): void {
-    this.sessionLog.tryAdd(
-      transactions.map((tx) => stableStringify(tx)),
-      newSignature,
-      skipVerify,
-    );
+    // Use direct calls instead of JSON.stringify for better performance
+    for (const tx of transactions) {
+      if (tx.privacy === "private") {
+        this.sessionLog.addExistingPrivateTransaction(
+          tx.encryptedChanges,
+          tx.keyUsed,
+          tx.madeAt,
+          tx.meta,
+        );
+      } else {
+        this.sessionLog.addExistingTrustingTransaction(
+          tx.changes,
+          tx.madeAt,
+          tx.meta,
+        );
+      }
+    }
+    this.sessionLog.commitTransactions(newSignature, skipVerify);
   }
 
   addNewPrivateTransaction(
@@ -237,12 +251,14 @@ class SessionLogAdapter implements SessionLogImpl {
     meta: JsonObject | undefined,
   ) {
     const output = this.sessionLog.addNewPrivateTransaction(
-      stableStringify(changes),
+      // We can avoid stableStringify because it will be encrypted.
+      JSON.stringify(changes),
       signerAgent.currentSignerSecret(),
       keySecret,
       keyID,
       madeAt,
-      meta ? stableStringify(meta) : undefined,
+      // We can avoid stableStringify because it will be encrypted.
+      meta ? JSON.stringify(meta) : undefined,
     );
     const parsedOutput = JSON.parse(output);
     const transaction: PrivateTransaction = {
@@ -261,8 +277,10 @@ class SessionLogAdapter implements SessionLogImpl {
     madeAt: number,
     meta: JsonObject | undefined,
   ) {
-    const stringifiedChanges = stableStringify(changes);
-    const stringifiedMeta = meta ? stableStringify(meta) : undefined;
+    // We can avoid stableStringify because the changes will be in a string format already.
+    const stringifiedChanges = JSON.stringify(changes);
+    // We can avoid stableStringify because the meta will be in a string format already.
+    const stringifiedMeta = meta ? JSON.stringify(meta) : undefined;
     const output = this.sessionLog.addNewTrustingTransaction(
       stringifiedChanges,
       signerAgent.currentSignerSecret(),
@@ -272,8 +290,8 @@ class SessionLogAdapter implements SessionLogImpl {
     const transaction: TrustingTransaction = {
       privacy: "trusting",
       madeAt,
-      changes: stringifiedChanges,
-      meta: stringifiedMeta,
+      changes: stringifiedChanges as Stringified<JsonValue[]>,
+      meta: stringifiedMeta as Stringified<JsonObject> | undefined,
     };
     return { signature: output as Signature, transaction };
   }

package/src/crypto/WasmCrypto.ts

@@ -1,6 +1,7 @@
 import {
   SessionLog,
   initialize,
+  initializeSync,
   Blake3Hasher,
   blake3HashOnce,
   blake3HashOnceWithContext,
@@ -20,7 +21,6 @@ import { RawCoID, SessionID, TransactionID } from "../ids.js";
 import { Stringified, stableStringify } from "../jsonStringify.js";
 import { JsonObject, JsonValue } from "../jsonValue.js";
 import { logger } from "../logger.js";
-import { PureJSCrypto } from "./PureJSCrypto.js";
 import {
   CryptoProvider,
   Encrypted,
@@ -41,10 +41,34 @@ import {
   Transaction,
   TrustingTransaction,
 } from "../coValueCore/verifiedState.js";
+import { isCloudflare, isEvalAllowed } from "../platformUtils.js";
 
 type Blake3State = Blake3Hasher;
 
 let wasmInit = initialize;
+let wasmInitSync = initializeSync;
+
+const wasmCryptoErrorMessage = (
+  e: unknown,
+) => `Critical Error: Failed to load WASM module
+
+${!isEvalAllowed() ? `You need to add \`import "jazz-tools/load-edge-wasm";\` on top of your entry module to make Jazz work with ${isCloudflare() ? "Cloudflare workers" : "this runtime"}` : (e as Error).message}
+
+A native crypto module is required for Jazz to work. See https://jazz.tools/docs/react/reference/performance#use-the-best-crypto-implementation-for-your-platform for possible alternatives.`;
+
+/**
+ * Initializes the WasmCrypto module. This function can be used to initialize the WasmCrypto module in a worker or a browser.
+ * if you are using SSR and you want to initialize WASM crypto asynchronously you can use this function.
+ * @returns A promise that resolves when the WasmCrypto module is successfully initialized.
+ */
+export async function initWasmCrypto() {
+  try {
+    await wasmInit();
+  } catch (e) {
+    throw new Error(wasmCryptoErrorMessage(e), { cause: e });
+  }
+}
+
 /**
  * WebAssembly implementation of the CryptoProvider interface using cojson-core-wasm.
  * This provides the primary implementation using WebAssembly for optimal performance, offering:
@@ -54,7 +78,7 @@ let wasmInit = initialize;
  * - Hashing (BLAKE3)
  */
 export class WasmCrypto extends CryptoProvider<Blake3State> {
-  private constructor() {
+  protected constructor() {
     super();
   }
 
@@ -62,17 +86,23 @@ export class WasmCrypto extends CryptoProvider<Blake3State> {
     wasmInit = value;
   }
 
-  static async create(): Promise<WasmCrypto | PureJSCrypto> {
+  static setInitSync(value: typeof initializeSync) {
+    wasmInitSync = value;
+  }
+
+  static createSync(): WasmCrypto {
     try {
-      await wasmInit();
+      wasmInitSync();
     } catch (e) {
-      logger.warn(
-        "Failed to initialize WasmCrypto, falling back to PureJSCrypto",
-        { err: e },
-      );
-      return new PureJSCrypto();
+      throw new Error(wasmCryptoErrorMessage(e), { cause: e });
     }
+    return new WasmCrypto();
+  }
 
+  // TODO: Remove this method and use createSync instead, this is not necessary since we can use createSync in the browser and in the worker.
+  // @deprecated
+  static async create(): Promise<WasmCrypto> {
+    await initWasmCrypto();
     return new WasmCrypto();
   }
 
@@ -204,11 +234,24 @@ class SessionLogAdapter {
     newSignature: Signature,
     skipVerify: boolean,
   ): void {
-    this.sessionLog.tryAdd(
-      transactions.map((tx) => stableStringify(tx)),
-      newSignature,
-      skipVerify,
-    );
+    // Use direct calls instead of JSON.stringify for better performance
+    for (const tx of transactions) {
+      if (tx.privacy === "private") {
+        this.sessionLog.addExistingPrivateTransaction(
+          tx.encryptedChanges,
+          tx.keyUsed,
+          tx.madeAt,
+          tx.meta,
+        );
+      } else {
+        this.sessionLog.addExistingTrustingTransaction(
+          tx.changes,
+          tx.madeAt,
+          tx.meta,
+        );
+      }
+    }
+    this.sessionLog.commitTransactions(newSignature, skipVerify);
   }
 
   addNewPrivateTransaction(
@@ -220,12 +263,14 @@ class SessionLogAdapter {
     meta: JsonObject | undefined,
   ): { signature: Signature; transaction: PrivateTransaction } {
     const output = this.sessionLog.addNewPrivateTransaction(
-      stableStringify(changes),
+      // We can avoid stableStringify because it will be encrypted.
+      JSON.stringify(changes),
       signerAgent.currentSignerSecret(),
       keySecret,
       keyID,
       madeAt,
-      meta ? stableStringify(meta) : undefined,
+      // We can avoid stableStringify because it will be encrypted.
+      meta ? JSON.stringify(meta) : undefined,
     );
     const parsedOutput = JSON.parse(output);
     const transaction: PrivateTransaction = {
@@ -244,8 +289,10 @@ class SessionLogAdapter {
     madeAt: number,
     meta: JsonObject | undefined,
   ): { signature: Signature; transaction: TrustingTransaction } {
-    const stringifiedChanges = stableStringify(changes);
-    const stringifiedMeta = meta ? stableStringify(meta) : undefined;
+    // We can avoid stableStringify because the changes will be in a string format already.
+    const stringifiedChanges = JSON.stringify(changes);
+    // We can avoid stableStringify because the meta will be in a string format already.
+    const stringifiedMeta = meta ? JSON.stringify(meta) : undefined;
     const output = this.sessionLog.addNewTrustingTransaction(
       stringifiedChanges,
       signerAgent.currentSignerSecret(),
@@ -255,8 +302,8 @@ class SessionLogAdapter {
     const transaction: TrustingTransaction = {
       privacy: "trusting",
       madeAt,
-      changes: stringifiedChanges,
-      meta: stringifiedMeta,
+      changes: stringifiedChanges as Stringified<JsonValue[]>,
+      meta: stringifiedMeta as Stringified<JsonObject> | undefined,
     };
     return { signature: output as Signature, transaction };
   }

package/src/crypto/WasmCryptoEdge.ts

@@ -1,4 +1,4 @@
-import { initialize } from "cojson-core-wasm/edge-lite";
+import { initialize, initializeSync } from "cojson-core-wasm/edge-lite";
 import { WasmCrypto } from "./WasmCrypto.js";
 
 /**
@@ -12,3 +12,7 @@ import { WasmCrypto } from "./WasmCrypto.js";
 export const init = async () => {
   return initialize();
 };
+
+export const initSync = () => {
+  return initializeSync();
+};

package/src/crypto/crypto.ts

@@ -1,7 +1,13 @@
 import { base58 } from "@scure/base";
 import { ControlledAccountOrAgent, RawAccountID } from "../coValues/account.js";
-import { AgentID, RawCoID, TransactionID } from "../ids.js";
-import { SessionID } from "../ids.js";
+import {
+  AgentID,
+  RawCoID,
+  TransactionID,
+  SessionID,
+  ActiveSessionID,
+  DeleteSessionID,
+} from "../ids.js";
 import { Stringified, parseJSON, stableStringify } from "../jsonStringify.js";
 import { JsonObject, JsonValue } from "../jsonValue.js";
 import { logger } from "../logger.js";
@@ -246,8 +252,14 @@ export abstract class CryptoProvider<Blake3State = any> {
     )}`;
   }
 
-  newRandomSessionID(accountID: RawAccountID | AgentID): SessionID {
-    return `${accountID}_session_z${base58.encode(this.randomBytes(8))}`;
+  newRandomSessionID(accountID: RawAccountID | AgentID): ActiveSessionID {
+    const randomPart = base58.encode(this.randomBytes(8));
+    return `${accountID}_session_z${randomPart}`;
+  }
+
+  newDeleteSessionID(accountID: RawAccountID | AgentID): DeleteSessionID {
+    const randomPart = base58.encode(this.randomBytes(7));
+    return `${accountID}_session_d${randomPart}$`;
   }
 
   abstract createSessionLog(

package/src/exports.ts

@@ -77,6 +77,7 @@ import { emptyKnownState } from "./knownState.js";
 import {
   getContentMessageSize,
   getTransactionSize,
+  knownStateFromContent,
 } from "./coValueContentMessage.js";
 import { getDependedOnCoValuesFromRawData } from "./coValueCore/utils.js";
 import {
@@ -102,6 +103,7 @@ type Value = JsonValue | AnyRawCoValue;
 export { PriorityBasedMessageQueue } from "./queue/PriorityBasedMessageQueue.js";
 /** @hidden */
 export const cojsonInternals = {
+  knownStateFromContent,
   connectedPeers,
   rawCoIDtoBytes,
   rawCoIDfromBytes,

package/src/ids.ts

@@ -36,7 +36,17 @@ export function isAgentID(id: unknown): id is AgentID {
   );
 }
 
-export type SessionID = `${RawAccountID | AgentID}_session_z${string}`;
+export type ActiveSessionID = `${RawAccountID | AgentID}_session_z${string}`;
+export type DeleteSessionID = `${RawAccountID | AgentID}_session_d${string}$`;
+export type SessionID = ActiveSessionID | DeleteSessionID;
+
+const CHAR_DOLLAR = "$".charCodeAt(0);
+
+export function isDeleteSessionID(
+  sessionID: SessionID,
+): sessionID is DeleteSessionID {
+  return sessionID.charCodeAt(sessionID.length - 1) === CHAR_DOLLAR;
+}
 
 export function isParentGroupReference(
   key: string,

package/src/localNode.ts

@@ -101,6 +101,21 @@ export class LocalNode {
     this.syncManager.removeStorage();
   }
 
+  /**
+   * Enable background erasure of deleted coValues (space reclamation).
+   *
+   * Deleted coValues are immediately blocked from syncing via tombstones; this feature
+   * only reclaims local storage space by deleting historical content while preserving
+   * the tombstone (header + delete session).
+   *
+   * This is opt-in and affects only the currently configured storage (if any)
+   *
+   * @category 3. Low-level
+   */
+  enableDeletedCoValuesErasure() {
+    this.storage?.enableDeletedCoValuesErasure();
+  }
+
   hasCoValue(id: RawCoID) {
     const coValue = this.coValues.get(id);
 

package/src/platformUtils.ts

@@ -0,0 +1,26 @@
+export function isCloudflare() {
+  if (
+    // @ts-ignore
+    typeof navigator !== "undefined" &&
+    // @ts-ignore
+    navigator?.userAgent?.includes("Cloudflare")
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+export const isEvalAllowed = () => {
+  if (isCloudflare()) {
+    return false;
+  }
+
+  try {
+    const F = Function;
+    new F("");
+    return true;
+  } catch (_) {
+    return false;
+  }
+};

package/src/storage/DeletedCoValuesEraserScheduler.ts

@@ -0,0 +1,124 @@
+import { logger } from "../logger.js";
+
+export type DeletedCoValuesEraserSchedulerRunResult = {
+  hasMore: boolean;
+};
+
+export type DeletedCoValuesEraserSchedulerOpts = {
+  throttleMs: number;
+  startupDelayMs: number;
+  followUpDelayMs: number;
+};
+
+type SchedulerState =
+  | "idle"
+  | "startup_scheduled"
+  | "throttle_scheduled"
+  | "followup_scheduled"
+  | "running"
+  | "disposed";
+
+export const DEFAULT_DELETE_SCHEDULE_OPTS = {
+  throttleMs: 60_000,
+  startupDelayMs: 1_000,
+  followUpDelayMs: 1_000,
+} satisfies DeletedCoValuesEraserSchedulerOpts;
+
+export class DeletedCoValuesEraserScheduler {
+  private readonly runCallback: () => Promise<DeletedCoValuesEraserSchedulerRunResult>;
+  private readonly opts: DeletedCoValuesEraserSchedulerOpts;
+
+  private state: SchedulerState = "idle";
+
+  private isDisposed(): boolean {
+    return this.state === "disposed";
+  }
+
+  private scheduledTimeout: ReturnType<typeof setTimeout> | undefined;
+
+  constructor({
+    run,
+    opts,
+  }: {
+    run: () => Promise<DeletedCoValuesEraserSchedulerRunResult>;
+    opts?: DeletedCoValuesEraserSchedulerOpts;
+  }) {
+    this.runCallback = run;
+    this.opts = opts || DEFAULT_DELETE_SCHEDULE_OPTS;
+  }
+
+  scheduleStartupDrain() {
+    if (this.isDisposed()) return;
+
+    // Only schedule startup drain if nothing is already scheduled/running.
+    if (this.state !== "idle") return;
+
+    this.scheduleTimer("startup_scheduled", this.opts.startupDelayMs);
+  }
+
+  onEnqueueDeletedCoValue() {
+    if (this.isDisposed()) return;
+
+    // While we're already draining (or have a follow-up scheduled), ignore enqueue
+    // to avoid overlapping phases. The active drain loop will pick up new work.
+    if (this.state !== "idle") return;
+
+    // Only idle reaches here.
+    this.scheduleTimer("throttle_scheduled", this.opts.throttleMs);
+  }
+
+  dispose() {
+    if (this.isDisposed()) return;
+    this.state = "disposed";
+
+    if (this.scheduledTimeout) clearTimeout(this.scheduledTimeout);
+    this.scheduledTimeout = undefined;
+  }
+
+  private scheduleTimer(
+    state: Exclude<SchedulerState, "idle" | "running" | "disposed">,
+    delayMs: number,
+  ) {
+    if (this.isDisposed()) return;
+    if (this.scheduledTimeout) return;
+
+    this.state = state;
+    this.scheduledTimeout = setTimeout(() => {
+      this.scheduledTimeout = undefined;
+      void this.run();
+    }, delayMs);
+  }
+
+  private async run() {
+    if (this.isDisposed()) return;
+
+    // Clear any pre-run scheduled state and enter running state.
+    this.state = "running";
+
+    let result: DeletedCoValuesEraserSchedulerRunResult;
+    try {
+      result = await this.runCallback();
+    } catch (error) {
+      logger.error("Error running deleted co values eraser scheduler", {
+        err: error,
+      });
+      // If the run callback fails, recover to idle so future enqueues/startup drains
+      // can retry instead of getting stuck in "running".
+      if (!this.isDisposed()) {
+        this.state = "idle";
+      }
+      return;
+    }
+
+    if (this.isDisposed()) return;
+
+    if (result.hasMore) {
+      // One follow-up phase at a time. Further enqueues while follow-up is scheduled
+      // are ignored.
+      this.scheduleTimer("followup_scheduled", this.opts.followUpDelayMs);
+      return;
+    }
+
+    this.state = "idle";
+  }
+}

package/src/storage/sqlite/client.ts

@@ -16,6 +16,7 @@ import type {
   StoredSessionRow,
   TransactionRow,
 } from "../types.js";
+import { DeletedCoValueDeletionStatus } from "../types.js";
 import type { SQLiteDatabaseDriver } from "./types.js";
 
 export type RawCoValueRow = {
@@ -29,6 +30,10 @@ export type RawTransactionRow = {
   tx: string;
 };
 
+type DeletedCoValueQueueRow = {
+  id: RawCoID;
+};
+
 export function getErrorMessage(error: unknown) {
   return error instanceof Error ? error.message : "Unknown error";
 }
@@ -143,6 +148,78 @@ export class SQLiteClient
     return result.rowID;
   }
 
+  markCoValueAsDeleted(id: RawCoID) {
+    // Work queue entry. Table only stores the coValueID.
+    // Idempotent by design.
+    this.db.run(
+      `INSERT INTO deletedCoValues (coValueID) VALUES (?) ON CONFLICT(coValueID) DO NOTHING`,
+      [id],
+    );
+  }
+
+  eraseCoValueButKeepTombstone(coValueId: RawCoID) {
+    const coValueRow = this.db.get<{ rowID: number }>(
+      "SELECT rowID FROM coValues WHERE id = ?",
+      [coValueId],
+    );
+
+    if (!coValueRow) {
+      logger.warn(`CoValue ${coValueId} not found, skipping deletion`);
+      return;
+    }
+
+    this.transaction(() => {
+      this.db.run(
+        `DELETE FROM transactions
+       WHERE ses IN (
+         SELECT rowID FROM sessions
+         WHERE coValue = ?
+           AND sessionID NOT LIKE '%$'
+       )`,
+        [coValueRow.rowID],
+      );
+
+      this.db.run(
+        `DELETE FROM signatureAfter
+       WHERE ses IN (
+         SELECT rowID FROM sessions
+         WHERE coValue = ?
+           AND sessionID NOT LIKE '%$'
+       )`,
+        [coValueRow.rowID],
+      );
+
+      this.db.run(
+        `DELETE FROM sessions
+       WHERE coValue = ?
+         AND sessionID NOT LIKE '%$'`,
+        [coValueRow.rowID],
+      );
+
+      // Mark the delete as done
+      this.db.run(
+        `INSERT INTO deletedCoValues (coValueID, status) VALUES (?, ?)
+       ON CONFLICT(coValueID) DO UPDATE SET status=?`,
+        [
+          coValueId,
+          DeletedCoValueDeletionStatus.Done,
+          DeletedCoValueDeletionStatus.Done,
+        ],
+      );
+    });
+  }
+
+  getAllCoValuesWaitingForDelete(): RawCoID[] {
+    return this.db
+      .query<DeletedCoValueQueueRow>(
+        `SELECT coValueID as id
+         FROM deletedCoValues
+         WHERE status = ?`,
+        [DeletedCoValueDeletionStatus.Pending],
+      )
+      .map((r) => r.id);
+  }
+
   addSessionUpdate({ sessionUpdate }: { sessionUpdate: SessionRow }): number {
     const result = this.db.get<{ rowID: number }>(
       `INSERT INTO sessions (coValue, sessionID, lastIdx, lastSignature, bytesSinceLastSignature) VALUES (?, ?, ?, ?, ?)