@dabble/patches 0.5.6 → 0.5.7

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

package/dist/solid/primitives.d.ts

@@ -0,0 +1,235 @@
+import { Accessor } from 'solid-js';
+import { PatchesDoc } from '../client/PatchesDoc.js';
+import { ChangeMutator } from '../types.js';
+import '../event-signal.js';
+import '../algorithms/shared/changeBatching.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+
+/**
+ * Options for usePatchesDoc primitive.
+ */
+interface UsePatchesDocOptions {
+    /**
+     * Whether to automatically open/close the document based on component lifecycle.
+     *
+     * - `false` (default): Assumes doc is already open. Throws if not.
+     * - `true`: Opens doc on mount with ref counting, closes on cleanup.
+     *
+     * @default false
+     */
+    autoClose?: boolean;
+}
+/**
+ * Return type for usePatchesDoc primitive.
+ */
+interface UsePatchesDocReturn<T extends object> {
+    /**
+     * Accessor for the document state.
+     * Updated whenever the document changes (local or remote).
+     */
+    data: Accessor<T | undefined>;
+    /**
+     * Whether the document is currently loading/syncing.
+     * - `true` during initial load or updates
+     * - `false` when fully synced
+     */
+    loading: Accessor<boolean>;
+    /**
+     * Error that occurred during sync, if any.
+     */
+    error: Accessor<Error | null>;
+    /**
+     * The committed revision number.
+     * Increments each time the server confirms changes.
+     */
+    rev: Accessor<number>;
+    /**
+     * 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')
+     * })
+     * ```
+     */
+    change: (mutator: ChangeMutator<T>) => void;
+    /**
+     * The underlying PatchesDoc instance.
+     * Useful for advanced operations.
+     */
+    doc: Accessor<PatchesDoc<T> | undefined>;
+}
+/**
+ * Solid primitive for reactive Patches document state.
+ *
+ * Provides reactive access to a Patches document with automatic lifecycle management.
+ *
+ * ## Explicit Lifecycle (default)
+ *
+ * By default, assumes the document is already open and just adds Solid reactivity.
+ * You control when documents are opened and closed.
+ *
+ * @example
+ * ```tsx
+ * import { onMount, onCleanup } from 'solid-js';
+ * import { usePatchesContext, usePatchesDoc } from '@dabble/patches/solid';
+ *
+ * function MyComponent(props) {
+ *   const { patches } = usePatchesContext();
+ *
+ *   // You control lifecycle
+ *   onMount(() => patches.openDoc(props.docId));
+ *   onCleanup(() => patches.closeDoc(props.docId));
+ *
+ *   // Just adds reactivity
+ *   // For static: usePatchesDoc('doc-123')
+ *   // For reactive: usePatchesDoc(() => props.docId)
+ *   const { data, loading, change } = usePatchesDoc(() => props.docId);
+ *
+ *   return <div>{data()?.title}</div>;
+ * }
+ * ```
+ *
+ * ## Auto Lifecycle
+ *
+ * With `autoClose: true`, the primitive manages the document lifecycle with
+ * reference counting. Safe to use in multiple components with the same docId.
+ *
+ * @example
+ * ```tsx
+ * // Opens on mount, closes on cleanup (ref-counted)
+ * const { data, loading, change } = usePatchesDoc('doc-123', {
+ *   autoClose: true
+ * });
+ * ```
+ *
+ * @param docId - Document ID (static string or accessor function)
+ * @param options - Configuration options
+ * @returns Reactive document state and utilities
+ * @throws Error if Patches context not provided
+ * @throws Error if doc not open in explicit mode
+ */
+declare function usePatchesDoc<T extends object>(docId: MaybeAccessor<string>, 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();
+ *
+ * return (
+ *   <Show when={!connected()}>
+ *     <div>You are offline</div>
+ *   </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>;
+/**
+ * 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):**
+ * ```tsx
+ * const { Provider, useDoc } = createPatchesDoc<User>('user');
+ *
+ * <Provider docId="user-123">
+ *   <UserProfile />
+ * </Provider>
+ * ```
+ *
+ * **Reactive document (multi-tab):**
+ * ```tsx
+ * const { Provider, useDoc } = createPatchesDoc<Whiteboard>('whiteboard');
+ * 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
+ *
+ * @example
+ * ```tsx
+ * // Create the context
+ * const { Provider: WhiteboardProvider, useDoc: useWhiteboard } =
+ *   createPatchesDoc<WhiteboardDoc>('whiteboard');
+ *
+ * // Use in parent
+ * <WhiteboardProvider docId="whiteboard-123">
+ *   <Canvas />
+ * </WhiteboardProvider>
+ *
+ * // Use in child
+ * function Canvas() {
+ *   const { data, change } = useWhiteboard();
+ *   return <div>{data()?.title}</div>;
+ * }
+ * ```
+ */
+/**
+ * Props for the Provider component returned by createPatchesDoc.
+ */
+interface PatchesDocProviderProps {
+    docId: MaybeAccessor<string>;
+    autoClose?: boolean;
+    children: any;
+}
+declare function createPatchesDoc<T extends object>(name: string): {
+    Provider: (props: PatchesDocProviderProps) => any;
+    useDoc: () => UsePatchesDocReturn<T>;
+};
+
+export { type MaybeAccessor, type PatchesDocProviderProps, type UsePatchesDocOptions, type UsePatchesDocReturn, type UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync };