@docukit/docsync 0.0.1-alpha.1

package/LICENSE.md

@@ -0,0 +1,20 @@
+# DocSync License 1.0
+
+Copyright (c) 2025 German Jablonski. All rights reserved.
+
+## Terms
+
+This software is proprietary. Without a valid license, you may:
+
+- View the source code for evaluation purposes
+- Use it for personal, non-production projects
+
+You may NOT:
+
+- Use this software in production
+- Modify, copy, or redistribute this software
+- Use this software for commercial purposes
+
+## Obtaining a License
+
+For production use, please obtain a license at: https://docukit.dev/license

package/README.md

@@ -0,0 +1 @@
+Visit [our website](https://docukit.dev) for documentation and more.

package/dist/src/client/index.d.ts

@@ -0,0 +1,158 @@
+import type { DocBinding } from "../shared/docBinding.js";
+import type { BroadcastMessage, ClientConfig, Provider, DocData, GetDocArgs, Identity, QueryResult, ConnectHandler, DisconnectHandler, ChangeHandler, SyncHandler, DocLoadHandler, DocUnloadHandler, ClientSocket, DocSyncEventName, DocSyncEvents, Presence, DeferredState } from "../shared/types.js";
+type LocalResolved<S, O> = {
+    provider: Provider<S, O, "client">;
+    identity: Identity;
+};
+type PushStatus = "idle" | "pushing" | "pushing-with-pending";
+export declare class DocSyncClient<D extends {} = {}, S extends {} = {}, O extends {} = {}> {
+    protected _docBinding: DocBinding<D, S, O>;
+    protected _docsCache: Map<string, {
+        promisedDoc: Promise<D | undefined>;
+        refCount: number;
+        presence: Presence;
+        presenceHandlers: Set<(presence: Presence) => void>;
+    }>;
+    protected _localPromise: Promise<LocalResolved<S, O>>;
+    protected _deviceId: string;
+    /** Client-generated id for presence (works offline; sent in auth so server uses same key) */
+    protected _clientId: string;
+    private _shouldBroadcast;
+    protected _broadcastChannel?: BroadcastChannel;
+    protected _socket: ClientSocket<S, O>;
+    protected _localOpsBatchState: Map<string, DeferredState<O[]>>;
+    protected _batchDelay: number;
+    protected _presenceDebounceState: Map<string, DeferredState<unknown>>;
+    protected _presenceDebounce: number;
+    protected _pushStatusByDocId: Map<string, PushStatus>;
+    protected _connectHandlers: Set<ConnectHandler>;
+    protected _disconnectHandlers: Set<DisconnectHandler>;
+    protected _changeHandlers: Set<ChangeHandler>;
+    protected _syncHandlers: Set<SyncHandler>;
+    protected _docLoadHandlers: Set<DocLoadHandler>;
+    protected _docUnloadHandlers: Set<DocUnloadHandler>;
+    constructor(config: ClientConfig<D, S, O>);
+    connect(): void;
+    disconnect(): void;
+    _applyOperations(operations: O, docId: string): Promise<void>;
+    private _applyPresencePatch;
+    /** Current presence for this client (debounce state or cache); does not clear the timer */
+    private _getOwnPresencePatch;
+    _replaceDocInCache({ docId, doc, serializedDoc, }: {
+        docId: string;
+        doc?: D;
+        serializedDoc?: S;
+    }): Promise<void>;
+    _applyServerOperations({ docId, operations, }: {
+        docId: string;
+        operations: O[];
+    }): Promise<void>;
+    /**
+     * Subscribe to a document with reactive state updates.
+     *
+     * The behavior depends on which fields are provided:
+     * - `{ type, id }` → Try to get an existing doc. Returns `undefined` if not found.
+     * - `{ type, createIfMissing: true }` → Create a new doc with auto-generated ID (ulid).
+     * - `{ type, id, createIfMissing: true }` → Get existing doc or create it if not found.
+     *
+     * The callback will be invoked with state updates:
+     * 1. `{ status: "loading" }` - Initial state while fetching
+     * 2. `{ status: "success", data: { doc, docId } }` - Document loaded successfully
+     * 3. `{ status: "error", error }` - Failed to load document
+     *
+     * To observe document content changes, use `doc.onChange()` directly on the returned doc.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = client.getDoc(
+     *   { type: "notes", id: "abc123" },
+     *   (result) => {
+     *     if (result.status === "loading") console.log("Loading...");
+     *     if (result.status === "success") console.log("Doc:", result.data.doc);
+     *     if (result.status === "error") console.error(result.error);
+     *   }
+     * );
+     *
+     * // Clean up when done
+     * unsubscribe();
+     * ```
+     */
+    getDoc<T extends GetDocArgs>(args: T, onChange: (result: QueryResult<T extends {
+        createIfMissing: true;
+    } ? DocData<D> : DocData<D> | undefined>) => void): () => void;
+    /**
+     * Subscribe to presence updates for a document.
+     * Multiple handlers can be registered for the same document.
+     * @param args - The arguments for the getPresence request.
+     * @param onChange - The callback to invoke when the presence changes.
+     * @returns A function to unsubscribe from presence updates.
+     */
+    getPresence(args: {
+        docId: string | undefined;
+    }, onChange: (presence: Presence) => void): () => void;
+    setPresence({ docId, presence }: {
+        docId: string;
+        presence: unknown;
+    }): Promise<void>;
+    private _setupChangeListener;
+    private _loadOrCreateDoc;
+    /**
+     * Decrease the reference count of a document and, if it is 0, delete the document from the cache.
+     */
+    protected _unloadDoc(docId: string): Promise<void>;
+    _sendMessage(message: BroadcastMessage<O>): void;
+    onLocalOperations({ docId, operations }: {
+        docId: string;
+        operations: O[];
+    }): void;
+    /**
+     * Push local operations to the server for a specific document.
+     * Uses a per-docId queue to prevent concurrent pushes for the same doc.
+     */
+    saveRemote({ docId }: {
+        docId: string;
+    }): void;
+    /**
+     * Unsubscribe from real-time updates for a document.
+     * Should be called when a document is unloaded (refCount 1 → 0).
+     */
+    unsubscribeDoc(docId: string): Promise<void>;
+    protected _doPush({ docId }: {
+        docId: string;
+    }): Promise<void>;
+    protected _request<E extends DocSyncEventName>(event: E, payload: DocSyncEvents<S, O>[E]["request"]): Promise<DocSyncEvents<S, O>[E]["response"]>;
+    /**
+     * Register a handler for connection events.
+     * @returns Unsubscribe function
+     */
+    onConnect(handler: ConnectHandler): () => void;
+    /**
+     * Register a handler for disconnection events.
+     * @returns Unsubscribe function
+     */
+    onDisconnect(handler: DisconnectHandler): () => void;
+    /**
+     * Register a handler for document change events.
+     * @returns Unsubscribe function
+     */
+    onChange(handler: ChangeHandler<O>): () => void;
+    /**
+     * Register a handler for sync events.
+     * @returns Unsubscribe function
+     */
+    onSync(handler: SyncHandler<O>): () => void;
+    /**
+     * Register a handler for document load events.
+     * @returns Unsubscribe function
+     */
+    onDocLoad(handler: DocLoadHandler): () => void;
+    /**
+     * Register a handler for document unload events.
+     * @returns Unsubscribe function
+     */
+    onDocUnload(handler: DocUnloadHandler): () => void;
+    protected _emit(handlers: Set<() => void>): void;
+    protected _emit<T>(handlers: Set<(event: T) => void>, event: T): void;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"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"}