@dabble/patches 0.8.9 → 0.8.10

package/dist/solid/index.d.ts

@@ -1,5 +1,5 @@
 export { PatchesContextValue, PatchesProvider, PatchesProviderProps, usePatchesContext } from './context.js';
-export { MaybeAccessor, PatchesDocProviderProps, UsePatchesDocLazyOptions, UsePatchesDocLazyReturn, UsePatchesDocOptions, UsePatchesDocReturn, UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync } from './primitives.js';
+export { MaybeAccessor, PatchesDocProviderProps, UsePatchesDocOptions, UsePatchesDocReturn, UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync } from './primitives.js';
 export { CreateManagedDocsOptions, CreateManagedDocsReturn, createManagedDocs } from './managed-docs.js';
 export { fillPath } from '../shared/utils.js';
 export { DocManager, getDocManager } from '../shared/doc-manager.js';

package/dist/solid/primitives.d.ts

@@ -1,172 +1,78 @@
 import { Accessor } from 'solid-js';
 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 primitive (eager mode with docId).
+ * Options for usePatchesDoc primitive.
  */
 interface UsePatchesDocOptions extends OpenDocOptions {
     /**
-     * Controls document lifecycle management on cleanup.
-     *
-     * - `false` (default): Explicit mode. Assumes doc is already open. Throws if not.
-     * - `true`: Opens doc on mount with ref counting, closes on cleanup (doc stays tracked).
-     * - `'untrack'`: Opens doc on mount, closes AND untracks on cleanup (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 primitive (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 primitive (eager mode).
+ * Return type for usePatchesDoc primitive.
  */
 interface UsePatchesDocReturn<T extends object> {
-    /**
-     * Accessor for the document state.
-     * Updated whenever the document changes (local or remote).
-     */
+    /** Accessor for the document state. */
     data: Accessor<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: Accessor<boolean>;
-    /**
-     * Error that occurred during sync, if any.
-     */
+    /** Error that occurred during sync, if any. */
     error: Accessor<Error | undefined>;
-    /**
-     * The committed revision number.
-     * Increments each time the server confirms changes.
-     */
+    /** The committed revision number. */
     rev: Accessor<number>;
-    /**
-     * Whether there are pending local changes not yet committed by server.
-     */
+    /** Whether there are pending local changes not yet committed by server. */
     hasPending: Accessor<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.
-     */
+    /** Close the document and reset state. Useful for explicit cleanup. */
+    close: () => Promise<void>;
+    /** The underlying PatchesDoc instance. */
     doc: Accessor<PatchesDoc<T> | undefined>;
 }
 /**
- * Return type for usePatchesDoc primitive (lazy mode).
- * Extends the eager return type with lifecycle management methods.
+ * Type for document ID — can be a static string or accessor function.
  */
-interface UsePatchesDocLazyReturn<T extends object> extends UsePatchesDocReturn<T> {
-    /**
-     * Current document path. `null` when no document is loaded.
-     */
-    path: Accessor<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: () => 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>;
-}
+type MaybeAccessor<T> = T | Accessor<T>;
 /**
  * Solid primitive for reactive Patches document state.
  *
- * ## Eager Mode (with docId)
- *
- * Provides reactive access to an already-open Patches document.
+ * Opens the document automatically and closes it on cleanup (or when the
+ * accessor value changes). Accepts a static string or an accessor. When the
+ * value is falsy, no document is loaded.
  *
  * @example
  * ```tsx
- * // Explicit lifecycle — you control open/close
- * const { data, loading, change } = usePatchesDoc(() => props.docId)
+ * // Static
+ * const { data, change } = usePatchesDoc('doc-123')
  *
- * // Auto lifecycle — opens on mount, closes on cleanup
- * const { data, loading, change } = usePatchesDoc(() => props.docId, { autoClose: true })
- * ```
- *
- * ## Lazy Mode (without docId)
- *
- * Returns a deferred handle with `load()`, `close()`, and `create()` methods.
- * Does NOT register `onCleanup` — caller manages lifecycle.
- *
- * @example
- * ```tsx
- * const { data, load, close, change, create } = usePatchesDoc<Project>()
- *
- * // Later, when the user navigates:
- * await load('projects/abc/content')
- *
- * // When leaving:
- * await close()
+ * // Reactive — swaps automatically
+ * const [projectId, setProjectId] = createSignal<string | null>('abc')
+ * const { data, change } = usePatchesDoc(() => projectId() && `projects/${projectId()}`)
  * ```
  */
-declare function usePatchesDoc<T extends object>(docId: MaybeAccessor<string>, options?: UsePatchesDocOptions): UsePatchesDocReturn<T>;
-declare function usePatchesDoc<T extends object>(options?: UsePatchesDocLazyOptions): UsePatchesDocLazyReturn<T>;
+declare function usePatchesDoc<T extends object>(docId: MaybeAccessor<string | null | undefined | false>, options?: UsePatchesDocOptions): UsePatchesDocReturn<T>;
 /**
  * Return type for usePatchesSync primitive.
  */
 interface UsePatchesSyncReturn {
-    /**
-     * Whether the WebSocket connection is established.
-     */
     connected: Accessor<boolean>;
-    /**
-     * Whether documents are currently syncing with the server.
-     */
     syncing: Accessor<boolean>;
-    /**
-     * Whether the client believes it has network connectivity.
-     */
     online: Accessor<boolean>;
 }
 /**
  * Solid primitive for reactive Patches sync state.
  *
- * Provides reactive access to PatchesSync connection and sync status.
- * Useful for showing "Offline" banners, global loading indicators, etc.
- *
  * @example
  * ```tsx
  * const { connected, syncing, online } = usePatchesSync();
@@ -177,68 +83,37 @@ interface UsePatchesSyncReturn {
  *   </Show>
  * );
  * ```
- *
- * @returns Reactive sync state
- * @throws Error if Patches context not provided
- * @throws Error if PatchesSync was not provided to context
  */
 declare function usePatchesSync(): UsePatchesSyncReturn;
-/**
- * Type for document ID - can be static string or accessor function.
- */
-type MaybeAccessor<T> = T | Accessor<T>;
 /**
  * Props for the Provider component returned by createPatchesDoc.
  */
 interface PatchesDocProviderProps extends OpenDocOptions {
     docId: MaybeAccessor<string>;
-    autoClose?: boolean | 'untrack';
+    untrack?: boolean;
     children: any;
 }
 /**
  * Creates a named document context that can be provided to child components.
  *
- * This enables child components to access the document using the returned `useDoc` hook
- * without needing to pass the docId down through props. Supports both static and
- * reactive docIds.
- *
- * ## Use Cases
- *
- * **Static document (user settings):**
+ * @example
  * ```tsx
  * const { Provider, useDoc } = createPatchesDoc<User>('user');
  *
  * <Provider docId="user-123">
  *   <UserProfile />
  * </Provider>
- * ```
  *
- * **Reactive document (multi-tab):**
- * ```tsx
- * const { Provider, useDoc } = createPatchesDoc<Whiteboard>('whiteboard');
+ * // Reactive
  * const [activeTabId, setActiveTabId] = createSignal('design-1');
- *
  * <Provider docId={activeTabId}>
  *   <WhiteboardCanvas />
  * </Provider>
  * ```
- *
- * **With autoClose:**
- * ```tsx
- * const { Provider, useDoc } = createPatchesDoc<Doc>('document');
- * const [currentDocId, setCurrentDocId] = createSignal('doc-1');
- *
- * <Provider docId={currentDocId} autoClose>
- *   <DocumentEditor />
- * </Provider>
- * ```
- *
- * @param name - Unique identifier for this document context (e.g., 'whiteboard', 'user')
- * @returns Object with Provider component and useDoc hook
  */
 declare function createPatchesDoc<T extends object>(name: string): {
     Provider: (props: PatchesDocProviderProps) => any;
     useDoc: () => UsePatchesDocReturn<T>;
 };
 
-export { type MaybeAccessor, type PatchesDocProviderProps, type UsePatchesDocLazyOptions, type UsePatchesDocLazyReturn, type UsePatchesDocOptions, type UsePatchesDocReturn, type UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync };
+export { type MaybeAccessor, type PatchesDocProviderProps, type UsePatchesDocOptions, type UsePatchesDocReturn, type UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync };

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/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 };

package/dist/vue/composables.js

@@ -1,21 +1,19 @@
 import "../chunk-IZ2YBCUP.js";
 import {
-  ref,
-  shallowRef,
+  inject,
   onBeforeUnmount,
-  watch,
-  unref,
   provide,
-  inject
+  ref,
+  shallowRef,
+  toValue,
+  watch
 } from "vue";
-import { JSONPatch } from "../json-patch/JSONPatch.js";
-import { usePatchesContext } from "./provider.js";
 import { getDocManager } from "./doc-manager.js";
-function createDocReactiveState(options) {
-  const { initialLoading = true, hasSyncContext = false, transformState, changeBehavior } = options;
+import { usePatchesContext } from "./provider.js";
+function createDocReactiveState(hasSyncContext) {
   const doc = shallowRef(void 0);
   const data = shallowRef(void 0);
-  const loading = ref(initialLoading);
+  const loading = ref(false);
   const error = ref();
   const rev = ref(0);
   const hasPending = ref(false);
@@ -35,9 +33,6 @@ function createDocReactiveState(options) {
       }
     }
     const unsubState = patchesDoc.subscribe((state) => {
-      if (transformState && state) {
-        state = transformState(state, patchesDoc);
-      }
       data.value = state;
       rev.value = patchesDoc.committedRev;
       hasPending.value = patchesDoc.hasPending;
@@ -61,133 +56,70 @@ function createDocReactiveState(options) {
     hasPending.value = false;
   }
   function change(mutator) {
-    if (changeBehavior === "throw") {
-      if (!doc.value) {
-        throw new Error("Cannot make changes: document not loaded yet");
-      }
-      doc.value.change(mutator);
-    } else {
-      doc.value?.change(mutator);
-    }
+    doc.value?.change(mutator);
   }
-  const baseReturn = {
-    data,
-    loading,
-    error,
-    rev,
-    hasPending,
-    change,
-    doc
-  };
-  return { doc, data, loading, error, rev, hasPending, setupDoc, resetRefs, change, baseReturn };
-}
-function usePatchesDoc(docIdOrOptions, options) {
-  if (typeof docIdOrOptions === "string") {
-    return _usePatchesDocEager(docIdOrOptions, options ?? {});
-  }
-  return _usePatchesDocLazy(docIdOrOptions ?? {});
+  const baseReturn = { data, loading, error, rev, hasPending, change, doc };
+  return { setupDoc, resetRefs, 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, baseReturn } = createDocReactiveState({
-    initialLoading: !!autoClose,
-    hasSyncContext: !!sync,
-    changeBehavior: "throw"
-  });
+  const { setupDoc, resetRefs, baseReturn } = createDocReactiveState(!!sync);
   let unsubscribe = null;
-  if (autoClose) {
-    let unmounted = false;
-    manager.openDoc(patches, docId, openDocOpts).then((patchesDoc) => {
-      if (unmounted) {
-        manager.closeDoc(patches, docId, shouldUntrack);
+  let currentDocId = null;
+  let unmounted = false;
+  function teardown() {
+    unsubscribe?.();
+    unsubscribe = null;
+  }
+  async function openPath(id) {
+    currentDocId = id;
+    baseReturn.loading.value = true;
+    try {
+      const patchesDoc = await manager.openDoc(patches, id, openDocOpts);
+      if (unmounted || currentDocId !== id) {
+        manager.closeDoc(patches, id, shouldUntrack);
         return;
       }
       unsubscribe = setupDoc(patchesDoc);
-    }).catch((err) => {
-      if (!unmounted) {
+    } catch (err) {
+      if (!unmounted && currentDocId === id) {
         baseReturn.error.value = err;
         baseReturn.loading.value = false;
       }
-    });
-    onBeforeUnmount(() => {
-      unmounted = true;
-      unsubscribe?.();
-      manager.closeDoc(patches, docId, shouldUntrack);
-    });
-  } else {
-    const patchesDoc = patches.getOpenDoc(docId);
-    if (!patchesDoc) {
-      throw new Error(
-        `Document "${docId}" is not open. Either open it with patches.openDoc() first, or use { autoClose: true } option.`
-      );
     }
-    manager.incrementRefCount(docId);
-    unsubscribe = setupDoc(patchesDoc);
-    onBeforeUnmount(() => {
-      unsubscribe?.();
-      manager.decrementRefCount(docId);
-    });
   }
-  return baseReturn;
-}
-function _usePatchesDocLazy(options) {
-  const { patches, sync } = usePatchesContext();
-  const { idProp } = options;
-  const { setupDoc, resetRefs, loading, baseReturn } = createDocReactiveState({
-    initialLoading: false,
-    hasSyncContext: !!sync,
-    changeBehavior: "noop",
-    transformState: idProp ? (state, patchesDoc) => ({ ...state, [idProp]: patchesDoc.id }) : void 0
-  });
-  let unsubscribe = null;
-  const path = ref(null);
-  function teardown() {
-    unsubscribe?.();
-    unsubscribe = null;
+  async function closePath(id) {
+    teardown();
     resetRefs();
+    await manager.closeDoc(patches, id, shouldUntrack);
   }
-  async function load(docPath, options2) {
-    if (path.value) {
-      const prevPath = path.value;
-      teardown();
-      await patches.closeDoc(prevPath);
+  baseReturn.close = async () => {
+    if (currentDocId) {
+      await closePath(currentDocId);
+      currentDocId = null;
     }
-    path.value = docPath;
-    loading.value = true;
-    try {
-      const patchesDoc = await patches.openDoc(docPath, options2);
-      unsubscribe = setupDoc(patchesDoc);
-    } catch (err) {
-      baseReturn.error.value = err;
-      loading.value = false;
-    }
-  }
-  async function close() {
-    if (path.value) {
-      const prevPath = path.value;
-      teardown();
-      path.value = null;
-      await patches.closeDoc(prevPath);
+  };
+  const getter = typeof docId === "string" ? () => docId : () => toValue(docId) || null;
+  watch(
+    getter,
+    async (newId, oldId) => {
+      if (newId === oldId) return;
+      if (oldId) await closePath(oldId);
+      if (newId) await openPath(newId);
+    },
+    { immediate: true }
+  );
+  onBeforeUnmount(async () => {
+    unmounted = true;
+    if (currentDocId) {
+      await closePath(currentDocId);
+      currentDocId = 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();
@@ -205,89 +137,16 @@ function usePatchesSync() {
   onBeforeUnmount(() => {
     unsubscribe();
   });
-  return {
-    connected,
-    syncing,
-    online
-  };
+  return { connected, syncing, online };
 }
 function createDocInjectionKey(name) {
   return Symbol(`patches-doc-${name}`);
 }
-function providePatchesDoc(name, docId, options = {}) {
-  const { patches, sync } = usePatchesContext();
-  const { autoClose = false, algorithm, metadata } = options;
-  const shouldUntrack = autoClose === "untrack";
-  const openDocOpts = { algorithm, metadata };
-  const manager = getDocManager(patches);
-  const { setupDoc, baseReturn } = createDocReactiveState({
-    initialLoading: !!autoClose,
-    hasSyncContext: !!sync,
-    changeBehavior: "throw"
-  });
-  const currentDocId = ref(unref(docId));
-  let unsubscribe = null;
-  let providerUnmounted = false;
-  async function initDoc(id) {
-    currentDocId.value = id;
-    unsubscribe?.();
-    unsubscribe = null;
-    if (autoClose) {
-      try {
-        const patchesDoc = await manager.openDoc(patches, id, openDocOpts);
-        if (providerUnmounted || currentDocId.value !== id) {
-          manager.closeDoc(patches, id, shouldUntrack);
-          return;
-        }
-        unsubscribe = setupDoc(patchesDoc);
-      } catch (err) {
-        if (!providerUnmounted && currentDocId.value === id) {
-          baseReturn.error.value = err;
-          baseReturn.loading.value = false;
-        }
-      }
-    } else {
-      try {
-        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);
-        unsubscribe = setupDoc(patchesDoc);
-      } catch (err) {
-        baseReturn.error.value = err;
-        baseReturn.loading.value = false;
-      }
-    }
-  }
+function providePatchesDoc(name, docId, options) {
   const key = createDocInjectionKey(name);
-  provide(key, baseReturn);
-  initDoc(unref(docId));
-  if (typeof docId !== "string") {
-    watch(docId, async (newDocId, oldDocId) => {
-      if (newDocId === oldDocId) return;
-      unsubscribe?.();
-      unsubscribe = null;
-      if (autoClose) {
-        await manager.closeDoc(patches, oldDocId, shouldUntrack);
-      } else {
-        manager.decrementRefCount(oldDocId);
-      }
-      await initDoc(newDocId);
-    });
-  }
-  onBeforeUnmount(async () => {
-    providerUnmounted = true;
-    unsubscribe?.();
-    if (autoClose) {
-      await manager.closeDoc(patches, currentDocId.value, shouldUntrack);
-    } else {
-      manager.decrementRefCount(currentDocId.value);
-    }
-  });
-  return baseReturn;
+  const result = typeof docId === "string" ? usePatchesDoc(docId, options) : usePatchesDoc(() => docId.value, options);
+  provide(key, result);
+  return result;
 }
 function useCurrentDoc(name) {
   const key = createDocInjectionKey(name);

package/dist/vue/index.d.ts

@@ -1,5 +1,5 @@
 export { PATCHES_KEY, PATCHES_SYNC_KEY, PatchesContext, providePatches, providePatchesContext, usePatchesContext } from './provider.js';
-export { UsePatchesDocLazyOptions, UsePatchesDocLazyReturn, UsePatchesDocOptions, UsePatchesDocReturn, UsePatchesSyncReturn, providePatchesDoc, useCurrentDoc, usePatchesDoc, usePatchesSync } from './composables.js';
+export { UsePatchesDocOptions, UsePatchesDocReturn, UsePatchesSyncReturn, providePatchesDoc, useCurrentDoc, usePatchesDoc, usePatchesSync } from './composables.js';
 export { UseManagedDocsOptions, UseManagedDocsReturn, useManagedDocs } from './managed-docs.js';
 export { fillPath } from '../shared/utils.js';
 export { DocManager, getDocManager } from '../shared/doc-manager.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.8.9",
+  "version": "0.8.10",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {