@dabble/patches 0.5.5 → 0.5.7

package/dist/algorithms/server/createVersion.js

@@ -3,8 +3,8 @@ import { createVersionMetadata } from "../../data/version.js";
 import { getISO } from "../../utils/dates.js";
 async function createVersion(store, docId, state, changes, metadata) {
   if (changes.length === 0) return;
-  const baseRev = changes[0].baseRev;
-  if (baseRev === void 0) {
+  const startRev = changes[0].baseRev;
+  if (startRev === void 0) {
     throw new Error(`Client changes must include baseRev for doc ${docId}.`);
   }
   const sessionMetadata = createVersionMetadata({
@@ -12,8 +12,8 @@ async function createVersion(store, docId, state, changes, metadata) {
     // Convert client timestamps to UTC for version metadata (enables lexicographic sorting)
     startedAt: getISO(changes[0].createdAt),
     endedAt: getISO(changes[changes.length - 1].createdAt),
-    rev: changes[changes.length - 1].rev,
-    baseRev,
+    endRev: changes[changes.length - 1].rev,
+    startRev,
     ...metadata
   });
   await store.createVersion(docId, sessionMetadata, state, changes);

package/dist/algorithms/server/getSnapshotAtRevision.js

@@ -5,11 +5,11 @@ async function getSnapshotAtRevision(store, docId, rev) {
     reverse: true,
     startAfter: rev ? rev + 1 : void 0,
     origin: "main",
-    orderBy: "rev"
+    orderBy: "endRev"
   });
   const latestMainVersion = versions[0];
   const versionState = latestMainVersion && await store.loadVersionState(docId, latestMainVersion.id) || null;
-  const versionRev = latestMainVersion?.rev ?? 0;
+  const versionRev = latestMainVersion?.endRev ?? 0;
   const changesSinceVersion = await store.listChanges(docId, {
     startAfter: versionRev,
     endBefore: rev ? rev + 1 : void 0

package/dist/algorithms/server/handleOfflineSessionsAndBatches.js

@@ -46,8 +46,8 @@ async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docI
             // Convert client timestamps to UTC for version metadata (enables lexicographic sorting)
             startedAt: getISO(sessionChanges[0].createdAt),
             endedAt: getISO(sessionChanges[sessionChanges.length - 1].createdAt),
-            rev: sessionChanges[sessionChanges.length - 1].rev,
-            baseRev
+            endRev: sessionChanges[sessionChanges.length - 1].rev,
+            startRev: baseRev
           });
           await store.createVersion(docId, sessionMetadata, offlineBaseState, sessionChanges);
           parentId = sessionMetadata.id;

package/dist/algorithms/shared/changeBatching.js

@@ -142,7 +142,10 @@ function breakTextOp(origChange, textOp, maxBytes, startRev, sizeCalculator) {
       testBatchOps.push({ retain: retainToPrefixCurrentPiece });
     }
     testBatchOps.push(op);
-    const testBatchSize = getSizeForStorage({ ...origChange, ops: [{ ...textOp, value: testBatchOps }] }, sizeCalculator);
+    const testBatchSize = getSizeForStorage(
+      { ...origChange, ops: [{ ...textOp, value: testBatchOps }] },
+      sizeCalculator
+    );
     if (currentOpsForNextChangePiece.length > 0 && testBatchSize > maxBytes) {
       flushCurrentChangePiece();
     }

package/dist/client/PatchesDoc.js

@@ -88,7 +88,13 @@ class PatchesDoc {
    * @returns The generated Change objects.
    */
   change(mutator) {
-    const changes = makeChange(this._snapshot, mutator, this._changeMetadata, this._maxStorageBytes, this._sizeCalculator);
+    const changes = makeChange(
+      this._snapshot,
+      mutator,
+      this._changeMetadata,
+      this._maxStorageBytes,
+      this._sizeCalculator
+    );
     if (changes.length === 0) {
       return changes;
     }

package/dist/net/PatchesSync.d.ts

@@ -1,17 +1,17 @@
-import { Signal } from '../event-signal.js';
-import { ConnectionState } from './protocol/types.js';
-import { SyncingState, Change } from '../types.js';
 import { JSONRPCClient } from './protocol/JSONRPCClient.js';
-import { PatchesWebSocket } from './websocket/PatchesWebSocket.js';
-import { WebSocketOptions } from './websocket/WebSocketTransport.js';
+import { Signal } from '../event-signal.js';
 import { SizeCalculator } from '../algorithms/shared/changeBatching.js';
 import { Patches } from '../client/Patches.js';
 import { PatchesStore } from '../client/PatchesStore.js';
+import { SyncingState, Change } from '../types.js';
+import { ConnectionState } from './protocol/types.js';
+import { PatchesWebSocket } from './websocket/PatchesWebSocket.js';
+import { WebSocketOptions } from './websocket/WebSocketTransport.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../json-patch/types.js';
-import './PatchesClient.js';
 import '../client/PatchesDoc.js';
+import './PatchesClient.js';
 
 interface PatchesSyncState {
     online: boolean;

package/dist/server/PatchesBranchManager.js

@@ -32,15 +32,15 @@ class PatchesBranchManager {
       throw new Error("Cannot create a branch from another branch.");
     }
     const stateAtRev = (await this.patchesServer.getStateAtRevision(docId, rev)).state;
-    const branchDocId = createId();
+    const branchDocId = this.store.createBranchId ? await Promise.resolve(this.store.createBranchId(docId)) : createId(22);
     const now = getISO();
     const initialVersionMetadata = createVersionMetadata({
       origin: "main",
       // Branch doc versions are 'main' until merged
       startedAt: now,
       endedAt: now,
-      rev,
-      baseRev: rev,
+      endRev: rev,
+      startRev: rev,
       name: metadata?.name,
       groupId: branchDocId,
       branchName: metadata?.name
@@ -49,8 +49,8 @@ class PatchesBranchManager {
     const branch = {
       ...metadata,
       id: branchDocId,
-      branchedFromId: docId,
-      branchedRev: rev,
+      docId,
+      branchedAtRev: rev,
       createdAt: now,
       status: "open"
     };
@@ -88,8 +88,8 @@ class PatchesBranchManager {
     if (branch.status !== "open") {
       throw new Error(`Branch ${branchId} is not open (status: ${branch.status}). Cannot merge.`);
     }
-    const sourceDocId = branch.branchedFromId;
-    const branchStartRevOnSource = branch.branchedRev;
+    const sourceDocId = branch.docId;
+    const branchStartRevOnSource = branch.branchedAtRev;
     const branchChanges = await this.store.listChanges(branchId, {});
     if (branchChanges.length === 0) {
       console.log(`Branch ${branchId} has no changes to merge.`);
@@ -107,7 +107,7 @@ class PatchesBranchManager {
       const newVersionMetadata = createVersionMetadata({
         ...v,
         origin: versionOrigin,
-        baseRev: branchStartRevOnSource,
+        startRev: branchStartRevOnSource,
         groupId: branchId,
         branchName: branch.name,
         // Keep branchName for traceability
@@ -149,7 +149,7 @@ class PatchesBranchManager {
     return committedMergeChanges;
   }
 }
-const nonModifiableMetadataFields = /* @__PURE__ */ new Set(["id", "branchedFromId", "branchedRev", "createdAt", "status"]);
+const nonModifiableMetadataFields = /* @__PURE__ */ new Set(["id", "docId", "branchedAtRev", "createdAt", "status"]);
 function assertBranchMetadata(metadata) {
   if (!metadata) return;
   for (const key in metadata) {

package/dist/server/types.d.ts

@@ -24,10 +24,10 @@ interface PatchesStoreBackend {
     /** Update a version's metadata. */
     updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
     /**
-     * Appends changes to an existing version, updating its state snapshot, endedAt, and rev.
+     * Appends changes to an existing version, updating its state snapshot, endedAt, and endRev.
      * Used when a session spans multiple batch submissions.
      */
-    appendVersionChanges(docId: string, versionId: string, changes: Change[], newEndedAt: string, newRev: number, newState: any): Promise<void>;
+    appendVersionChanges(docId: string, versionId: string, changes: Change[], newEndedAt: string, newEndRev: number, newState: any): Promise<void>;
     /** Lists version metadata based on filtering/sorting options. */
     listVersions(docId: string, options: ListVersionsOptions): Promise<VersionMetadata[]>;
     /** Loads the state snapshot for a specific version ID. */
@@ -41,6 +41,12 @@ interface PatchesStoreBackend {
  * Extends PatchesStoreBackend with methods specifically for managing branches.
  */
 interface BranchingStoreBackend extends PatchesStoreBackend {
+    /**
+     * Generates a unique ID for a new branch document.
+     * If not provided, a random 22-character ID is generated using createId().
+     * @param docId - The source document ID being branched from
+     */
+    createBranchId?(docId: string): Promise<string> | string;
     /** Lists metadata records for branches originating from a document. */
     listBranches(docId: string): Promise<Branch[]>;
     /** Loads the metadata record for a specific branch ID. */

package/dist/solid/context.d.ts

@@ -0,0 +1,67 @@
+import { JSX } from 'solid-js';
+import { Patches } from '../client/Patches.js';
+import { PatchesSync } from '../net/PatchesSync.js';
+import '../event-signal.js';
+import '../types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+import '../client/PatchesDoc.js';
+import '../algorithms/shared/changeBatching.js';
+import '../client/PatchesStore.js';
+import '../net/protocol/JSONRPCClient.js';
+import '../net/protocol/types.js';
+import '../net/websocket/PatchesWebSocket.js';
+import '../net/PatchesClient.js';
+import '../net/websocket/WebSocketTransport.js';
+
+/**
+ * Context value containing Patches and optional PatchesSync instances.
+ */
+interface PatchesContextValue {
+    patches: Patches;
+    sync?: PatchesSync;
+}
+/**
+ * Props for the PatchesProvider component.
+ */
+interface PatchesProviderProps {
+    patches: Patches;
+    sync?: PatchesSync;
+    children: JSX.Element;
+}
+/**
+ * Provider component for making Patches and PatchesSync available to child components.
+ *
+ * @example
+ * ```tsx
+ * import { PatchesProvider } from '@dabble/patches/solid';
+ * import { Patches, InMemoryStore } from '@dabble/patches/client';
+ *
+ * const patches = new Patches({ store: new InMemoryStore() });
+ *
+ * <PatchesProvider patches={patches}>
+ *   <App />
+ * </PatchesProvider>
+ * ```
+ */
+declare function PatchesProvider(props: PatchesProviderProps): any;
+/**
+ * Hook to access the Patches context.
+ *
+ * @throws Error if called outside of a PatchesProvider
+ * @returns PatchesContextValue containing patches and optional sync instances
+ *
+ * @example
+ * ```tsx
+ * import { usePatchesContext } from '@dabble/patches/solid';
+ *
+ * function MyComponent() {
+ *   const { patches, sync } = usePatchesContext();
+ *   // Use patches and sync...
+ * }
+ * ```
+ */
+declare function usePatchesContext(): PatchesContextValue;
+
+export { type PatchesContextValue, PatchesProvider, type PatchesProviderProps, usePatchesContext };

package/dist/solid/context.js

@@ -0,0 +1,20 @@
+import "../chunk-IZ2YBCUP.js";
+import { createContext, useContext } from "solid-js";
+const PatchesContext = createContext();
+function PatchesProvider(props) {
+  const value = { patches: props.patches, sync: props.sync };
+  return /* @__PURE__ */ React.createElement(PatchesContext.Provider, { value, children: props.children });
+}
+function usePatchesContext() {
+  const context = useContext(PatchesContext);
+  if (!context) {
+    throw new Error(
+      "usePatchesContext must be called within a PatchesProvider. Make sure your component is wrapped with <PatchesProvider>."
+    );
+  }
+  return context;
+}
+export {
+  PatchesProvider,
+  usePatchesContext
+};

package/dist/solid/doc-manager.d.ts

@@ -0,0 +1,88 @@
+import { Patches } from '../client/Patches.js';
+import { PatchesDoc } from '../client/PatchesDoc.js';
+import '../event-signal.js';
+import '../types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+import '../client/PatchesStore.js';
+import '../algorithms/shared/changeBatching.js';
+
+/**
+ * Reference counting manager for PatchesDoc instances.
+ *
+ * Tracks how many Solid components are using each document and only opens/closes
+ * documents when the reference count goes to/from zero.
+ *
+ * This prevents the footgun where multiple components open the same doc but the
+ * first one to unmount closes it for everyone else.
+ */
+declare class DocManager {
+    private refCounts;
+    private pendingOps;
+    /**
+     * Opens a document with reference counting.
+     *
+     * - If this is the first reference, calls patches.openDoc()
+     * - If doc is already open, returns existing instance and increments count
+     * - Handles concurrent opens to the same doc safely
+     *
+     * @param patches - Patches instance
+     * @param docId - Document ID to open
+     * @returns Promise resolving to PatchesDoc instance
+     */
+    openDoc<T extends object>(patches: Patches, docId: string): Promise<PatchesDoc<T>>;
+    /**
+     * Closes a document with reference counting.
+     *
+     * - Decrements the reference count
+     * - Only calls patches.closeDoc() when count reaches zero
+     * - Safe to call even if doc was never opened
+     *
+     * @param patches - Patches instance
+     * @param docId - Document ID to close
+     */
+    closeDoc(patches: Patches, docId: string): Promise<void>;
+    /**
+     * Increments the reference count for a document without opening it.
+     *
+     * Used in explicit mode to track usage and prevent premature closes
+     * from autoClose mode.
+     *
+     * @param docId - Document ID
+     */
+    incrementRefCount(docId: string): void;
+    /**
+     * Decrements the reference count for a document without closing it.
+     *
+     * Used in explicit mode to release usage tracking.
+     *
+     * @param docId - Document ID
+     */
+    decrementRefCount(docId: string): void;
+    /**
+     * Gets the current reference count for a document.
+     *
+     * Useful for debugging or advanced use cases.
+     *
+     * @param docId - Document ID
+     * @returns Current reference count (0 if not tracked)
+     */
+    getRefCount(docId: string): number;
+    /**
+     * Clears all reference counts without closing documents.
+     *
+     * Use with caution - this is mainly for testing or cleanup scenarios
+     * where you want to reset the manager state.
+     */
+    reset(): void;
+}
+/**
+ * Gets or creates a DocManager for a Patches instance.
+ *
+ * @param patches - Patches instance
+ * @returns DocManager for this Patches instance
+ */
+declare function getDocManager(patches: Patches): DocManager;
+
+export { DocManager, getDocManager };

package/dist/solid/doc-manager.js

@@ -0,0 +1,125 @@
+import "../chunk-IZ2YBCUP.js";
+class DocManager {
+  refCounts = /* @__PURE__ */ new Map();
+  pendingOps = /* @__PURE__ */ new Map();
+  /**
+   * Opens a document with reference counting.
+   *
+   * - If this is the first reference, calls patches.openDoc()
+   * - If doc is already open, returns existing instance and increments count
+   * - Handles concurrent opens to the same doc safely
+   *
+   * @param patches - Patches instance
+   * @param docId - Document ID to open
+   * @returns Promise resolving to PatchesDoc instance
+   */
+  async openDoc(patches, docId) {
+    const currentCount = this.refCounts.get(docId) || 0;
+    if (currentCount === 0 && this.pendingOps.has(docId)) {
+      const doc = await this.pendingOps.get(docId);
+      this.refCounts.set(docId, (this.refCounts.get(docId) || 0) + 1);
+      return doc;
+    }
+    if (currentCount > 0) {
+      this.refCounts.set(docId, currentCount + 1);
+      const doc = patches.getOpenDoc(docId);
+      if (!doc) {
+        throw new Error(`Document ${docId} has ref count ${currentCount} but is not open in Patches`);
+      }
+      return doc;
+    }
+    const openPromise = patches.openDoc(docId);
+    this.pendingOps.set(docId, openPromise);
+    try {
+      const doc = await openPromise;
+      this.refCounts.set(docId, 1);
+      return doc;
+    } catch (error) {
+      this.refCounts.delete(docId);
+      throw error;
+    } finally {
+      this.pendingOps.delete(docId);
+    }
+  }
+  /**
+   * Closes a document with reference counting.
+   *
+   * - Decrements the reference count
+   * - Only calls patches.closeDoc() when count reaches zero
+   * - Safe to call even if doc was never opened
+   *
+   * @param patches - Patches instance
+   * @param docId - Document ID to close
+   */
+  async closeDoc(patches, docId) {
+    const currentCount = this.refCounts.get(docId) || 0;
+    if (currentCount === 0) {
+      return;
+    }
+    if (currentCount === 1) {
+      this.refCounts.delete(docId);
+      await patches.closeDoc(docId);
+    } else {
+      this.refCounts.set(docId, currentCount - 1);
+    }
+  }
+  /**
+   * Increments the reference count for a document without opening it.
+   *
+   * Used in explicit mode to track usage and prevent premature closes
+   * from autoClose mode.
+   *
+   * @param docId - Document ID
+   */
+  incrementRefCount(docId) {
+    const currentCount = this.refCounts.get(docId) || 0;
+    this.refCounts.set(docId, currentCount + 1);
+  }
+  /**
+   * Decrements the reference count for a document without closing it.
+   *
+   * Used in explicit mode to release usage tracking.
+   *
+   * @param docId - Document ID
+   */
+  decrementRefCount(docId) {
+    const currentCount = this.refCounts.get(docId) || 0;
+    if (currentCount > 0) {
+      this.refCounts.set(docId, currentCount - 1);
+    }
+  }
+  /**
+   * Gets the current reference count for a document.
+   *
+   * Useful for debugging or advanced use cases.
+   *
+   * @param docId - Document ID
+   * @returns Current reference count (0 if not tracked)
+   */
+  getRefCount(docId) {
+    return this.refCounts.get(docId) || 0;
+  }
+  /**
+   * Clears all reference counts without closing documents.
+   *
+   * Use with caution - this is mainly for testing or cleanup scenarios
+   * where you want to reset the manager state.
+   */
+  reset() {
+    this.refCounts.clear();
+    this.pendingOps.clear();
+  }
+}
+const managers = /* @__PURE__ */ new WeakMap();
+function getDocManager(patches) {
+  let manager = managers.get(patches);
+  if (!manager) {
+    manager = new DocManager();
+    managers.set(patches, manager);
+  }
+  return manager;
+}
+export {
+  DocManager,
+  getDocManager
+};

package/dist/solid/index.d.ts

@@ -0,0 +1,19 @@
+export { PatchesContextValue, PatchesProvider, PatchesProviderProps, usePatchesContext } from './context.js';
+export { MaybeAccessor, UsePatchesDocOptions, UsePatchesDocReturn, UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync } from './primitives.js';
+export { DocManager, getDocManager } from './doc-manager.js';
+import 'solid-js';
+import '../client/Patches.js';
+import '../event-signal.js';
+import '../types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+import '../client/PatchesDoc.js';
+import '../algorithms/shared/changeBatching.js';
+import '../client/PatchesStore.js';
+import '../net/PatchesSync.js';
+import '../net/protocol/JSONRPCClient.js';
+import '../net/protocol/types.js';
+import '../net/websocket/PatchesWebSocket.js';
+import '../net/PatchesClient.js';
+import '../net/websocket/WebSocketTransport.js';

package/dist/solid/index.js

@@ -0,0 +1,17 @@
+import "../chunk-IZ2YBCUP.js";
+import { PatchesProvider, usePatchesContext } from "./context.js";
+import {
+  usePatchesDoc,
+  usePatchesSync,
+  createPatchesDoc
+} from "./primitives.js";
+import { getDocManager, DocManager } from "./doc-manager.js";
+export {
+  DocManager,
+  PatchesProvider,
+  createPatchesDoc,
+  getDocManager,
+  usePatchesContext,
+  usePatchesDoc,
+  usePatchesSync
+};