@dabble/patches 0.8.8 → 0.8.10

package/dist/solid/primitives.js

@@ -7,14 +7,12 @@ import {
   createEffect,
   onCleanup
 } from "solid-js";
-import { JSONPatch } from "../json-patch/JSONPatch.js";
 import { usePatchesContext } from "./context.js";
 import { getDocManager } from "./doc-manager.js";
-function createDocReactiveState(options) {
-  const { initialLoading = true, hasSyncContext = false, transformState, changeBehavior } = options;
+function createDocReactiveState(hasSyncContext) {
   const [doc, setDoc] = createSignal(void 0);
   const [data, setData] = createSignal(void 0);
-  const [loading, setLoading] = createSignal(initialLoading);
+  const [loading, setLoading] = createSignal(false);
   const [error, setError] = createSignal();
   const [rev, setRev] = createSignal(0);
   const [hasPending, setHasPending] = createSignal(false);
@@ -34,9 +32,6 @@ function createDocReactiveState(options) {
       }
     }
     const unsubState = patchesDoc.subscribe((state) => {
-      if (transformState && state) {
-        state = transformState(state, patchesDoc);
-      }
       setData(() => state);
       setRev(patchesDoc.committedRev);
       setHasPending(patchesDoc.hasPending);
@@ -60,155 +55,60 @@ function createDocReactiveState(options) {
     setHasPending(false);
   }
   function change(mutator) {
-    if (changeBehavior === "throw") {
-      const currentDoc = doc();
-      if (!currentDoc) {
-        throw new Error("Cannot make changes: document not loaded yet");
-      }
-      currentDoc.change(mutator);
-    } else {
-      doc()?.change(mutator);
-    }
-  }
-  const baseReturn = {
-    data,
-    loading,
-    error,
-    rev,
-    hasPending,
-    change,
-    doc
-  };
-  return {
-    doc,
-    setDoc,
-    data,
-    setData,
-    loading,
-    setLoading,
-    error,
-    setError,
-    rev,
-    setRev,
-    hasPending,
-    setHasPending,
-    setupDoc,
-    resetSignals,
-    change,
-    baseReturn
-  };
-}
-function usePatchesDoc(docIdOrOptions, options) {
-  if (typeof docIdOrOptions === "string" || typeof docIdOrOptions === "function") {
-    return _usePatchesDocEager(docIdOrOptions, options ?? {});
+    doc()?.change(mutator);
   }
-  return _usePatchesDocLazy(docIdOrOptions ?? {});
+  const baseReturn = { data, loading, error, rev, hasPending, change, doc };
+  return { setupDoc, resetSignals, setError, baseReturn };
 }
-function _usePatchesDocEager(docId, options) {
+function usePatchesDoc(docId, options) {
   const { patches, sync } = usePatchesContext();
-  const { autoClose = false, algorithm, metadata } = options;
-  const shouldUntrack = autoClose === "untrack";
+  const { untrack: shouldUntrack = false, algorithm, metadata } = options ?? {};
   const openDocOpts = { algorithm, metadata };
   const manager = getDocManager(patches);
-  const { setupDoc, setError, setLoading, baseReturn } = createDocReactiveState({
-    initialLoading: !!autoClose,
-    hasSyncContext: !!sync,
-    changeBehavior: "throw"
+  const { setupDoc, resetSignals, setError, baseReturn } = createDocReactiveState(!!sync);
+  const source = typeof docId === "string" ? () => docId : () => docId() || null;
+  let currentId = null;
+  const [docResource] = createResource(source, async (id) => {
+    return await manager.openDoc(patches, id, openDocOpts);
   });
-  const docIdAccessor = toAccessor(docId);
-  if (autoClose) {
-    const [docResource] = createResource(docIdAccessor, async (id) => {
-      return await manager.openDoc(patches, id, openDocOpts);
-    });
-    createEffect(() => {
-      const loadedDoc = docResource();
-      if (loadedDoc) {
-        const unsub = setupDoc(loadedDoc);
-        onCleanup(() => unsub());
-      }
-      const resourceError = docResource.error;
-      if (resourceError) {
-        setError(resourceError);
-        setLoading(false);
-      }
-    });
-    onCleanup(() => {
-      const id = docIdAccessor();
-      manager.closeDoc(patches, id, shouldUntrack);
-    });
-  } else {
-    createEffect(() => {
-      const id = docIdAccessor();
-      const patchesDoc = patches.getOpenDoc(id);
-      if (!patchesDoc) {
-        throw new Error(
-          `Document "${id}" is not open. Either open it with patches.openDoc() first, or use { autoClose: true } option.`
-        );
-      }
-      manager.incrementRefCount(id);
-      const unsub = setupDoc(patchesDoc);
-      onCleanup(() => {
-        unsub();
-        manager.decrementRefCount(id);
-      });
-    });
-  }
-  return baseReturn;
-}
-function _usePatchesDocLazy(options) {
-  const { patches, sync } = usePatchesContext();
-  const { idProp } = options;
-  const { setupDoc, resetSignals, setError, setLoading, baseReturn } = createDocReactiveState({
-    initialLoading: false,
-    hasSyncContext: !!sync,
-    changeBehavior: "noop",
-    transformState: idProp ? (state, patchesDoc) => ({ ...state, [idProp]: patchesDoc.id }) : void 0
+  createEffect(() => {
+    const currentSource = source();
+    const loadedDoc = docResource();
+    if (currentSource && loadedDoc) {
+      currentId = currentSource;
+      const unsub = setupDoc(loadedDoc);
+      onCleanup(() => unsub());
+    } else {
+      resetSignals();
+    }
+    const resourceError = docResource.error;
+    if (resourceError) {
+      setError(resourceError);
+    }
   });
-  let unsubscribe = null;
-  const [path, setPath] = createSignal(null);
-  function teardown() {
-    unsubscribe?.();
-    unsubscribe = null;
-    resetSignals();
-  }
-  async function load(docPath, options2) {
-    if (path()) {
-      const prevPath = path();
-      teardown();
-      await patches.closeDoc(prevPath);
+  createEffect((prevId) => {
+    const id = source();
+    if (prevId && prevId !== id) {
+      currentId = null;
+      manager.closeDoc(patches, prevId, shouldUntrack);
     }
-    setPath(docPath);
-    setLoading(true);
-    try {
-      const patchesDoc = await patches.openDoc(docPath, options2);
-      unsubscribe = setupDoc(patchesDoc);
-    } catch (err) {
-      setError(err);
-      setLoading(false);
+    return id;
+  });
+  baseReturn.close = async () => {
+    if (currentId) {
+      const id = currentId;
+      currentId = null;
+      resetSignals();
+      await manager.closeDoc(patches, id, shouldUntrack);
     }
-  }
-  async function close() {
-    if (path()) {
-      const prevPath = path();
-      teardown();
-      setPath(null);
-      await patches.closeDoc(prevPath);
+  };
+  onCleanup(() => {
+    if (currentId) {
+      manager.closeDoc(patches, currentId, shouldUntrack);
+      currentId = null;
     }
-  }
-  async function create(docPath, initialState, options2) {
-    const newDoc = await patches.openDoc(docPath, options2);
-    newDoc.change((patch, root) => {
-      if (initialState instanceof JSONPatch) {
-        patch.ops = initialState.ops;
-      } else {
-        const state = { ...initialState };
-        if (idProp) delete state[idProp];
-        patch.replace(root, state);
-      }
-    });
-    await patches.closeDoc(docPath);
-  }
-  return { ...baseReturn, path, load, close, create };
+  });
+  return baseReturn;
 }
 function usePatchesSync() {
   const { sync } = usePatchesContext();
@@ -226,79 +126,16 @@ function usePatchesSync() {
   onCleanup(() => {
     unsubscribe();
   });
-  return {
-    connected,
-    syncing,
-    online
-  };
-}
-function toAccessor(value) {
-  return typeof value === "function" ? value : () => value;
+  return { connected, syncing, online };
 }
 function createPatchesDoc(name) {
   const Context = createContext();
   function Provider(props) {
-    const { patches, sync } = usePatchesContext();
-    const manager = getDocManager(patches);
-    const autoClose = props.autoClose ?? false;
-    const shouldUntrack = autoClose === "untrack";
-    const openDocOpts = { algorithm: props.algorithm, metadata: props.metadata };
-    const { setupDoc, setError, setLoading, baseReturn } = createDocReactiveState({
-      initialLoading: !!autoClose,
-      hasSyncContext: !!sync,
-      changeBehavior: "throw"
-    });
-    const docIdAccessor = toAccessor(props.docId);
-    if (autoClose) {
-      const [docResource] = createResource(docIdAccessor, async (id) => {
-        return await manager.openDoc(patches, id, openDocOpts);
-      });
-      createEffect(() => {
-        const loadedDoc = docResource();
-        if (loadedDoc) {
-          const unsub = setupDoc(loadedDoc);
-          onCleanup(() => unsub());
-        }
-        const resourceError = docResource.error;
-        if (resourceError) {
-          setError(resourceError);
-          setLoading(false);
-        }
-      });
-      createEffect((prevId) => {
-        const currentId = docIdAccessor();
-        if (prevId && prevId !== currentId) {
-          manager.closeDoc(patches, prevId, shouldUntrack);
-        }
-        return currentId;
-      });
-      onCleanup(() => {
-        const id = docIdAccessor();
-        manager.closeDoc(patches, id, shouldUntrack);
-      });
-    } else {
-      createEffect((prevId) => {
-        const id = docIdAccessor();
-        if (prevId && prevId !== id) {
-          manager.decrementRefCount(prevId);
-        }
-        const patchesDoc = patches.getOpenDoc(id);
-        if (!patchesDoc) {
-          throw new Error(
-            `Document "${id}" is not open. Either open it with patches.openDoc() first, or use autoClose option.`
-          );
-        }
-        manager.incrementRefCount(id);
-        const unsub = setupDoc(patchesDoc);
-        onCleanup(() => unsub());
-        return id;
-      });
-      onCleanup(() => {
-        const id = docIdAccessor();
-        manager.decrementRefCount(id);
-      });
-    }
-    return /* @__PURE__ */ React.createElement(Context.Provider, { value: baseReturn, children: props.children });
+    const result = usePatchesDoc(
+      typeof props.docId === "function" ? props.docId : props.docId,
+      { untrack: props.untrack, algorithm: props.algorithm, metadata: props.metadata }
+    );
+    return /* @__PURE__ */ React.createElement(Context.Provider, { value: result, children: props.children });
   }
   function useDoc() {
     const context = useContext(Context);
@@ -309,10 +146,7 @@ function createPatchesDoc(name) {
     }
     return context;
   }
-  return {
-    Provider,
-    useDoc
-  };
+  return { Provider, useDoc };
 }
 export {
   createPatchesDoc,

package/dist/types.d.ts

@@ -81,8 +81,6 @@ interface DocSyncState {
     syncError?: Error;
     isLoaded: boolean;
 }
-/** Status options for a branch */
-type BranchStatus = 'open' | 'closed' | 'merged' | 'archived' | 'abandoned';
 interface Branch {
     /** The ID of the branch document. */
     id: string;
@@ -92,10 +90,10 @@ interface Branch {
     branchedAtRev: number;
     /** Unix timestamp in milliseconds when the branch was created. */
     createdAt: number;
+    /** Unix timestamp in milliseconds when the branch was last modified. Updated on metadata changes. */
+    modifiedAt: number;
     /** Optional user-friendly name for the branch. */
     name?: string;
-    /** Current status of the branch. */
-    status: BranchStatus;
     /**
      * The first revision on the branch that contains user content (after initialization changes).
      * Initialization changes (e.g. the root-replace that seeds the branch with source state)
@@ -104,10 +102,41 @@ interface Branch {
      * across multiple changes due to size limits.
      */
     contentStartRev: number;
+    /**
+     * The branch-side revision through which changes have already been merged.
+     * Set after each merge so subsequent merges only pick up new changes.
+     * Undefined means the branch has never been merged.
+     */
+    lastMergedRev?: number;
+    /** The pending operation to sync to the server. Set by BranchClientStore methods. */
+    pendingOp?: 'create' | 'update' | 'delete';
+    /** True when this branch has been deleted. Stored as a tombstone for incremental sync. */
+    deleted?: true;
     /** Optional arbitrary metadata associated with the branch record. */
     [metadata: string]: any;
 }
-type EditableBranchMetadata = Disallowed<Branch, 'id' | 'docId' | 'branchedAtRev' | 'createdAt' | 'status' | 'contentStartRev'>;
+type EditableBranchMetadata = Disallowed<Branch, 'id' | 'docId' | 'branchedAtRev' | 'createdAt' | 'modifiedAt' | 'contentStartRev' | 'pendingOp' | 'deleted'>;
+/**
+ * Metadata for creating a new branch.
+ * Allows `id` and `contentStartRev` in addition to the fields allowed by `EditableBranchMetadata`.
+ * - `id`: Client-provided branch document ID. Required for offline branch creation.
+ * - `contentStartRev`: The first revision of user content. Set by the client when creating
+ *   initial changes offline (the server uses this to know where user content begins during merge).
+ */
+type CreateBranchMetadata = Omit<Disallowed<Branch, 'docId' | 'branchedAtRev' | 'createdAt' | 'modifiedAt' | 'pendingOp' | 'deleted'>, 'contentStartRev'> & {
+    contentStartRev?: number;
+};
+/**
+ * Options for listing branches.
+ */
+interface ListBranchesOptions {
+    /**
+     * Only return branches modified after this timestamp (Unix ms).
+     * Enables incremental sync: after the initial full list, subsequent calls can pass the
+     * most recent `modifiedAt` value to fetch only updates.
+     */
+    since?: number;
+}
 /**
  * Represents a tombstone for a deleted document.
  * Tombstones persist after deletion to inform late-connecting clients
@@ -247,4 +276,4 @@ type PathProxy<T = any> = IsAny<T> extends true ? DeepPathProxy : {
  */
 type ChangeMutator<T> = (patch: JSONPatch, root: PathProxy<T>) => void;
 
-export type { Branch, BranchStatus, Change, ChangeInput, ChangeMutator, CommitChangesOptions, DeleteDocOptions, DocSyncState, DocSyncStatus, DocumentTombstone, EditableBranchMetadata, EditableVersionMetadata, ListChangesOptions, ListVersionsOptions, PatchesSnapshot, PatchesState, PathProxy, VersionMetadata };
+export type { Branch, Change, ChangeInput, ChangeMutator, CommitChangesOptions, CreateBranchMetadata, DeleteDocOptions, DocSyncState, DocSyncStatus, DocumentTombstone, EditableBranchMetadata, EditableVersionMetadata, ListBranchesOptions, ListChangesOptions, ListVersionsOptions, PatchesSnapshot, PatchesState, PathProxy, VersionMetadata };

package/dist/vue/composables.d.ts

@@ -1,243 +1,102 @@
-import { ShallowRef, Ref, MaybeRef } from 'vue';
+import { ShallowRef, Ref, MaybeRef, MaybeRefOrGetter } from 'vue';
 import { OpenDocOptions } from '../client/Patches.js';
 import { P as PatchesDoc } from '../BaseDoc-BT18xPxU.js';
-import { JSONPatch } from '../json-patch/JSONPatch.js';
 import { ChangeMutator } from '../types.js';
 import 'easy-signal';
 import '../json-patch/types.js';
 import '../client/ClientAlgorithm.js';
 import '../client/PatchesStore.js';
+import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 
 /**
- * Options for usePatchesDoc composable (eager mode with docId).
+ * Options for usePatchesDoc composable.
  */
 interface UsePatchesDocOptions extends OpenDocOptions {
     /**
-     * Controls document lifecycle management on component unmount.
-     *
-     * - `false` (default): Explicit mode. Assumes doc is already open. Throws if not.
-     * - `true`: Opens doc on mount with ref counting, closes on unmount (doc stays tracked).
-     * - `'untrack'`: Opens doc on mount, closes AND untracks on unmount (removes from sync).
-     *
-     * @default false
+     * When true, the document is removed from sync tracking on close.
+     * By default documents stay tracked after closing.
      */
-    autoClose?: boolean | 'untrack';
+    untrack?: boolean;
 }
 /**
- * Options for usePatchesDoc composable (lazy mode without docId).
- */
-interface UsePatchesDocLazyOptions {
-    /**
-     * Inject doc.id into state under this key on every state update.
-     * Useful when the document ID is derived from the path but needed in the data.
-     */
-    idProp?: string;
-}
-/**
- * Return type for usePatchesDoc composable (eager mode).
+ * Return type for usePatchesDoc composable.
  */
 interface UsePatchesDocReturn<T extends object> {
-    /**
-     * Reactive reference to the document state.
-     * Updated whenever the document changes (local or remote).
-     */
+    /** Reactive reference to the document state. */
     data: ShallowRef<T | undefined>;
-    /**
-     * Whether the document is currently loading/syncing.
-     * - `true` during initial load or updates
-     * - `false` when fully synced
-     */
+    /** Whether the document is currently loading. */
     loading: Ref<boolean>;
-    /**
-     * Error that occurred during sync, if any.
-     */
+    /** Error that occurred during sync, if any. */
     error: Ref<Error | undefined>;
-    /**
-     * The committed revision number.
-     * Increments each time the server confirms changes.
-     */
+    /** The committed revision number. */
     rev: Ref<number>;
-    /**
-     * Whether there are pending local changes not yet committed by server.
-     */
+    /** Whether there are pending local changes not yet committed by server. */
     hasPending: Ref<boolean>;
-    /**
-     * Make changes to the document.
-     *
-     * @example
-     * ```typescript
-     * change((patch, root) => {
-     *   patch.replace(root.title!, 'New Title')
-     * })
-     * ```
-     */
+    /** Make changes to the document. No-ops if the document is not loaded. */
     change: (mutator: ChangeMutator<T>) => void;
-    /**
-     * The underlying PatchesDoc instance.
-     * Useful for advanced operations.
-     */
-    doc: ShallowRef<PatchesDoc<T> | undefined>;
-}
-/**
- * Return type for usePatchesDoc composable (lazy mode).
- * Extends the eager return type with lifecycle management methods.
- */
-interface UsePatchesDocLazyReturn<T extends object> extends UsePatchesDocReturn<T> {
-    /**
-     * Current document path. `null` when no document is loaded.
-     */
-    path: Ref<string | null>;
-    /**
-     * Open a document by path. Closes any previously loaded document first.
-     *
-     * @param docPath - The document path to open
-     * @param options - Optional algorithm and metadata overrides
-     */
-    load: (docPath: string, options?: OpenDocOptions) => Promise<void>;
-    /**
-     * Close the current document, unsubscribe, and reset all state.
-     * Calls `patches.closeDoc()` but does not untrack — tracking is managed separately.
-     */
+    /** Close the document and reset state. Useful for explicit cleanup without unmounting. */
     close: () => Promise<void>;
-    /**
-     * Create a new document: open it, set initial state, then close it.
-     * A one-shot operation that doesn't bind the document to this handle.
-     *
-     * @param docPath - The document path to create
-     * @param initialState - Initial state object or JSONPatch to apply
-     * @param options - Optional algorithm and metadata overrides
-     */
-    create: (docPath: string, initialState: T | JSONPatch, options?: OpenDocOptions) => Promise<void>;
+    /** The underlying PatchesDoc instance. */
+    doc: ShallowRef<PatchesDoc<T> | undefined>;
 }
 /**
  * Vue composable for reactive Patches document state.
  *
- * ## Eager Mode (with docId)
- *
- * Provides reactive access to an already-open Patches document.
- *
- * @example
- * ```typescript
- * // Explicit lifecycle — you control open/close
- * const { data, loading, change } = usePatchesDoc('doc-123')
- *
- * // Auto lifecycle — opens on mount, closes on unmount
- * const { data, loading, change } = usePatchesDoc('doc-123', { autoClose: true })
- * ```
- *
- * ## Lazy Mode (without docId)
- *
- * Returns a deferred handle with `load()`, `close()`, and `create()` methods.
- * Ideal for Pinia stores where the document path isn't known at creation time.
- * Does NOT use `onBeforeUnmount` — caller manages lifecycle.
+ * Opens the document automatically and closes it on unmount (or when the path
+ * changes). Accepts a static string, a ref, or a getter. When the value is
+ * `null` or `undefined`, no document is loaded.
  *
  * @example
  * ```typescript
- * // In a Pinia store
- * const { data, load, close, change, create } = usePatchesDoc<Project>()
+ * // Static
+ * const { data, change } = usePatchesDoc('doc-123')
  *
- * // Later, when the user navigates:
- * await load('projects/abc/content')
- *
- * // When leaving:
- * await close()
+ * // Reactive — swaps automatically
+ * const { data, change } = usePatchesDoc(() => currentId.value && `projects/${currentId.value}`)
  * ```
  */
 declare function usePatchesDoc<T extends object>(docId: string, options?: UsePatchesDocOptions): UsePatchesDocReturn<T>;
-declare function usePatchesDoc<T extends object>(options?: UsePatchesDocLazyOptions): UsePatchesDocLazyReturn<T>;
+declare function usePatchesDoc<T extends object>(docId: MaybeRefOrGetter<string | null | undefined>, options?: UsePatchesDocOptions): UsePatchesDocReturn<T>;
 /**
  * Return type for usePatchesSync composable.
  */
 interface UsePatchesSyncReturn {
-    /**
-     * Whether the WebSocket connection is established.
-     */
     connected: Ref<boolean>;
-    /**
-     * Whether documents are currently syncing with the server.
-     */
     syncing: Ref<boolean>;
-    /**
-     * Whether the client believes it has network connectivity.
-     */
     online: Ref<boolean>;
 }
 /**
  * Vue composable for reactive Patches sync state.
  *
- * Provides reactive access to PatchesSync connection and sync status.
- * Useful for showing "Offline" banners, global loading indicators, etc.
- *
  * @example
  * ```typescript
  * const { connected, syncing, online } = usePatchesSync()
- *
- * // Show offline banner
- * if (!connected) {
- *   // Display "You are offline"
- * }
  * ```
- *
- * @returns Reactive sync state
- * @throws Error if Patches context not provided
- * @throws Error if PatchesSync was not provided to context
  */
 declare function usePatchesSync(): UsePatchesSyncReturn;
 /**
  * Provides a Patches document in the component tree with a given name.
  *
- * This enables child components to access the document using `useCurrentDoc(name)`
- * without needing to pass the docId down through props. Supports both static and
- * reactive docIds.
- *
- * ## Use Cases
- *
- * **Static document (user settings):**
+ * @example
  * ```typescript
+ * // Static
  * providePatchesDoc('user', 'user-123')
- * ```
  *
- * **Reactive document (multi-tab with autoClose: false):**
- * ```typescript
- * const activeTabId = ref('design-1')
- * providePatchesDoc('whiteboard', activeTabId) // Keeps all docs open, switches between them
- * ```
- *
- * **Reactive document (single-doc with autoClose: true):**
- * ```typescript
+ * // Reactive
  * const currentDocId = ref('doc-1')
- * providePatchesDoc('document', currentDocId, { autoClose: true }) // Closes old, opens new
+ * providePatchesDoc('document', currentDocId)
  * ```
- *
- * @param name - Unique identifier for this document context (e.g., 'whiteboard', 'user')
- * @param docId - Document ID (static string or reactive ref)
- * @param options - Configuration options (autoClose, etc.)
- *
- * @throws Error if Patches context not provided
- * @throws Error if doc not open in explicit mode
  */
 declare function providePatchesDoc<T extends object>(name: string, docId: MaybeRef<string>, options?: UsePatchesDocOptions): UsePatchesDocReturn<T>;
 /**
  * Injects a Patches document provided by `providePatchesDoc`.
  *
- * Use this in child components to access a document provided higher up in the
- * component tree without passing the docId through props.
- *
  * @example
  * ```typescript
- * // Parent component
- * const whiteboardId = ref('whiteboard-123')
- * providePatchesDoc('whiteboard', whiteboardId)
- *
- * // Child component (anywhere in tree)
  * const { data, loading, change } = useCurrentDoc<WhiteboardDoc>('whiteboard')
  * ```
- *
- * @param name - The name used in providePatchesDoc
- * @returns Reactive document state and utilities
- * @throws Error if no document provided with that name
  */
 declare function useCurrentDoc<T extends object>(name: string): UsePatchesDocReturn<T>;
 
-export { type UsePatchesDocLazyOptions, type UsePatchesDocLazyReturn, type UsePatchesDocOptions, type UsePatchesDocReturn, type UsePatchesSyncReturn, providePatchesDoc, useCurrentDoc, usePatchesDoc, usePatchesSync };
+export { type UsePatchesDocOptions, type UsePatchesDocReturn, type UsePatchesSyncReturn, providePatchesDoc, useCurrentDoc, usePatchesDoc, usePatchesSync };