@hanzo/base 0.2.0

package/dist/crdt/index.d.ts

@@ -0,0 +1,372 @@
+/**
+ * Hybrid logical clock for CRDT operation ordering.
+ *
+ * Each operation is tagged with (timestamp, counter, siteId) to provide
+ * a total order across all sites. Compatible with the Go HLC implementation.
+ */
+interface HLCTimestamp {
+    /** Wall-clock milliseconds since epoch. */
+    ts: number;
+    /** Monotonic counter to break ties within the same ms. */
+    counter: number;
+    /** Unique site identifier (usually client session id). */
+    siteId: string;
+}
+declare class HybridLogicalClock {
+    private _ts;
+    private _counter;
+    readonly siteId: string;
+    constructor(siteId?: string);
+    /** Generate a new timestamp, guaranteed > any previous. */
+    now(): HLCTimestamp;
+    /** Receive a remote timestamp and merge with local clock. */
+    receive(remote: HLCTimestamp): HLCTimestamp;
+}
+/** Compare two HLC timestamps. Returns <0, 0, or >0. */
+declare function compareHLC(a: HLCTimestamp, b: HLCTimestamp): number;
+
+/**
+ * CRDT operation types -- wire format for sync between client and server.
+ *
+ * All operations are serializable to JSON and designed for
+ * eventual compatibility with a Go CRDT server.
+ */
+
+type OperationType = 'text.insert' | 'text.delete' | 'counter.increment' | 'set.add' | 'set.remove' | 'register.set';
+interface Operation {
+    /** Unique operation id: `{siteId}:{ts}:{counter}` */
+    id: string;
+    /** The CRDT document id this operation belongs to. */
+    documentId: string;
+    /** Which field within the document. */
+    field: string;
+    /** HLC timestamp for causal ordering. */
+    hlc: HLCTimestamp;
+    /** Operation type tag. */
+    type: OperationType;
+    /** Type-specific payload. */
+    payload: OperationPayload;
+}
+interface TextInsertPayload {
+    /** Position id of the character after which to insert (null = head). */
+    afterId: string | null;
+    /** The text content to insert. Each character gets its own positional id. */
+    content: string;
+    /** Assigned position ids for each character (same length as content). */
+    positionIds: string[];
+}
+interface TextDeletePayload {
+    /** Position ids of the characters to tombstone. */
+    positionIds: string[];
+}
+interface CounterIncrementPayload {
+    /** Delta (positive for increment, negative for decrement). */
+    delta: number;
+}
+interface SetAddPayload {
+    /** The value to add (JSON-serializable). */
+    value: unknown;
+    /** Unique tag for this add operation (for OR-Set semantics). */
+    tag: string;
+}
+interface SetRemovePayload {
+    /** The value to remove. */
+    value: unknown;
+    /** Tags being causally removed (observed tags at removal time). */
+    tags: string[];
+}
+interface RegisterSetPayload {
+    /** The new value. */
+    value: unknown;
+}
+type OperationPayload = TextInsertPayload | TextDeletePayload | CounterIncrementPayload | SetAddPayload | SetRemovePayload | RegisterSetPayload;
+declare function makeOpId(hlc: HLCTimestamp): string;
+declare function makePositionId(hlc: HLCTimestamp, charIndex: number): string;
+
+/**
+ * CRDTText -- collaborative text based on RGA (Replicated Growable Array).
+ *
+ * Each character has a unique position id. Insertions reference the position
+ * id of the character they follow. Deletions tombstone position ids.
+ * The structure resolves conflicts by using HLC comparison on concurrent
+ * inserts at the same position.
+ */
+
+type TextChangeCallback = (text: string) => void;
+declare class CRDTText {
+    private _nodes;
+    private readonly _clock;
+    private readonly _documentId;
+    private readonly _field;
+    private readonly _pendingOps;
+    private _listeners;
+    /** Index from position id to array index for O(1) lookup. */
+    private _index;
+    constructor(documentId: string, field: string, clock: HybridLogicalClock);
+    /** Insert text at a visible character position (0-based). */
+    insert(position: number, text: string): Operation;
+    /** Delete `length` visible characters starting at `position` (0-based). */
+    delete(position: number, length: number): Operation;
+    /** Apply a remote operation. */
+    applyRemote(op: Operation): void;
+    /** Get the current visible text. */
+    toString(): string;
+    /** Number of visible characters. */
+    get length(): number;
+    /** Drain pending local operations. */
+    drainOps(): Operation[];
+    onChange(callback: TextChangeCallback): () => void;
+    /**
+     * Insert a node into the correct position in the array.
+     * RGA rule: among siblings sharing the same afterId, order by HLC descending
+     * (newer inserts appear first, pushing older ones right).
+     */
+    private _insertNode;
+    /** Rebuild the id->index map from `startIdx` onward. */
+    private _rebuildIndex;
+    /** Get the position id of the visible character at position `pos`, or null for before-head. */
+    private _visibleIdAtPosition;
+    /** Get position ids for `length` visible characters starting at `position`. */
+    private _visibleIdsInRange;
+    private _notifyChange;
+}
+
+/**
+ * CRDTCounter -- PN-Counter (positive-negative counter).
+ *
+ * Each site tracks its own positive and negative totals.
+ * The value is sum(positives) - sum(negatives) across all sites.
+ * Merge is max() per-site per-direction.
+ */
+
+type CounterChangeCallback = (value: number) => void;
+declare class CRDTCounter {
+    /** Per-site positive accumulator. */
+    private _positive;
+    /** Per-site negative accumulator. */
+    private _negative;
+    private readonly _clock;
+    private readonly _documentId;
+    private readonly _field;
+    private readonly _pendingOps;
+    private _listeners;
+    constructor(documentId: string, field: string, clock: HybridLogicalClock);
+    get value(): number;
+    increment(amount?: number): Operation;
+    decrement(amount?: number): Operation;
+    /** Apply a remote increment operation. */
+    applyRemote(op: Operation): void;
+    /** Merge with a remote counter state (for full-state sync). */
+    mergeState(positives: Record<string, number>, negatives: Record<string, number>): void;
+    /** Export state for full-state sync. */
+    exportState(): {
+        positive: Record<string, number>;
+        negative: Record<string, number>;
+    };
+    drainOps(): Operation[];
+    onChange(callback: CounterChangeCallback): () => void;
+    private _notifyChange;
+}
+
+/**
+ * CRDTSet<T> -- Observed-Remove Set (OR-Set).
+ *
+ * Each add() generates a unique tag. A remove() records the set of tags
+ * observed for that value at removal time. The value is present iff it has
+ * any tag not covered by a remove.
+ *
+ * This gives add-wins semantics: a concurrent add and remove of the same
+ * value results in the value being present (the new add's tag survives).
+ */
+
+type SetChangeCallback<T> = (values: T[]) => void;
+declare class CRDTSet<T = unknown> {
+    /** Map from serialized value key to tagged entry. */
+    private _entries;
+    private readonly _clock;
+    private readonly _documentId;
+    private readonly _field;
+    private readonly _pendingOps;
+    private _listeners;
+    constructor(documentId: string, field: string, clock: HybridLogicalClock);
+    get values(): T[];
+    get size(): number;
+    has(item: T): boolean;
+    add(item: T): Operation;
+    remove(item: T): Operation;
+    /** Apply a remote operation. */
+    applyRemote(op: Operation): void;
+    drainOps(): Operation[];
+    onChange(callback: SetChangeCallback<T>): () => void;
+    private _keyOf;
+    private _notifyChange;
+}
+
+/**
+ * CRDTRegister<T> -- Last-Writer-Wins Register (LWW-Register).
+ *
+ * The value with the highest HLC timestamp wins.
+ * Ties are broken by site id comparison.
+ */
+
+type RegisterChangeCallback<T> = (value: T | undefined) => void;
+declare class CRDTRegister<T = unknown> {
+    private _value;
+    private _hlc;
+    private readonly _clock;
+    private readonly _documentId;
+    private readonly _field;
+    private readonly _pendingOps;
+    private _listeners;
+    constructor(documentId: string, field: string, clock: HybridLogicalClock);
+    get value(): T | undefined;
+    set(value: T): Operation;
+    /** Apply a remote set operation. LWW: only apply if remote HLC > current. */
+    applyRemote(op: Operation): void;
+    /** Export current state for full-state sync. */
+    exportState(): {
+        value: T | undefined;
+        hlc: HLCTimestamp | null;
+    };
+    /** Import state from full-state sync. LWW merge. */
+    importState(value: T, hlc: HLCTimestamp): void;
+    drainOps(): Operation[];
+    onChange(callback: RegisterChangeCallback<T>): () => void;
+    private _notifyChange;
+}
+
+/**
+ * CRDTDocument -- container for collaborative fields.
+ *
+ * A document holds named CRDT fields (text, counter, set, register) that
+ * share a single HLC clock and sync channel. Operations from all fields
+ * are collected and sent to the server together.
+ */
+
+type DocumentChangeCallback = (ops: Operation[]) => void;
+declare class CRDTDocument {
+    readonly id: string;
+    readonly clock: HybridLogicalClock;
+    private _texts;
+    private _counters;
+    private _sets;
+    private _registers;
+    private _listeners;
+    /** Buffer for ops not yet synced. */
+    private _unsyncedOps;
+    constructor(id: string, siteId?: string);
+    getText(field: string): CRDTText;
+    getCounter(field: string): CRDTCounter;
+    getSet<T = unknown>(field: string): CRDTSet<T>;
+    getRegister<T = unknown>(field: string): CRDTRegister<T>;
+    /**
+     * Collect all pending local operations from all fields.
+     * Drains the per-field op buffers and returns them.
+     */
+    collectOps(): Operation[];
+    /**
+     * Acknowledge that operations up to and including `opId` have been
+     * persisted by the server. Removes them from the unsynced buffer.
+     */
+    acknowledge(opId: string): void;
+    /** Get operations that have not been acknowledged by the server. */
+    getUnsyncedOps(): readonly Operation[];
+    /**
+     * Apply a batch of remote operations to the appropriate CRDT fields.
+     */
+    applyRemoteOps(ops: Operation[]): void;
+    private _applyRemoteOp;
+    /**
+     * Encode all pending operations as a Uint8Array (JSON wire format).
+     * Used for WebSocket transmission.
+     */
+    encode(): Uint8Array;
+    /**
+     * Decode and apply a remote message (Uint8Array or string).
+     */
+    decode(data: Uint8Array | string): void;
+    onChange(callback: DocumentChangeCallback): () => void;
+    private _notifyChange;
+}
+
+/**
+ * CRDTSync -- WebSocket-based sync protocol handler.
+ *
+ * Connects to the Base server's CRDT sync endpoint and manages
+ * bidirectional operation exchange. Handles:
+ *
+ * - Buffering and batching local operations
+ * - Applying remote operations to the CRDTDocument
+ * - Reconnection with exponential backoff
+ * - Acknowledgment tracking
+ * - Presence (peer awareness) via the same channel
+ */
+
+type SyncState = 'disconnected' | 'connecting' | 'connected' | 'syncing';
+interface PeerState {
+    siteId: string;
+    /** Arbitrary JSON-serializable state (cursor position, name, color, etc.). */
+    meta: Record<string, unknown>;
+    /** Last seen timestamp (local clock). */
+    lastSeen: number;
+}
+type SyncStateCallback = (state: SyncState) => void;
+type PeerCallback = (peers: Map<string, PeerState>) => void;
+type RemoteChangeCallback = (ops: Operation[]) => void;
+declare class CRDTSync {
+    private _ws;
+    private _state;
+    private _document;
+    private _wsUrl;
+    /** Flush interval for batching local ops. */
+    private _flushTimer;
+    private _flushIntervalMs;
+    /** Reconnection. */
+    private _reconnectTimer;
+    private _reconnectAttempts;
+    private _maxReconnectDelay;
+    private _baseReconnectDelay;
+    private _intentionalClose;
+    /** Presence. */
+    private _peers;
+    private _localPresence;
+    private _presenceTimer;
+    private _presenceIntervalMs;
+    private _peerTimeoutMs;
+    /** Listeners. */
+    private _stateListeners;
+    private _peerListeners;
+    private _remoteChangeListeners;
+    get state(): SyncState;
+    get peers(): ReadonlyMap<string, PeerState>;
+    /**
+     * Connect to the CRDT sync endpoint and start syncing a document.
+     *
+     * @param wsUrl - WebSocket URL, e.g. "wss://myapp.hanzo.ai/api/crdt"
+     * @param document - The CRDTDocument to sync.
+     * @param token - Optional auth token.
+     */
+    connect(wsUrl: string, document: CRDTDocument, token?: string): void;
+    disconnect(): void;
+    /** Update local presence metadata (cursor, name, etc.). */
+    updatePresence(meta: Record<string, unknown>): void;
+    onStateChange(cb: SyncStateCallback): () => void;
+    onPeersChange(cb: PeerCallback): () => void;
+    onRemoteChange(cb: RemoteChangeCallback): () => void;
+    private _handleMessage;
+    private _startFlush;
+    private _stopFlush;
+    private _flush;
+    private _sendOps;
+    private _startPresence;
+    private _stopPresence;
+    private _broadcastPresence;
+    private _pruneStalePresence;
+    private _scheduleReconnect;
+    private _clearReconnect;
+    private _send;
+    private _setState;
+    private _notifyPeers;
+}
+
+export { CRDTCounter, CRDTDocument, CRDTRegister, CRDTSet, CRDTSync, CRDTText, type CounterChangeCallback, type CounterIncrementPayload, type DocumentChangeCallback, type HLCTimestamp, HybridLogicalClock, type Operation, type OperationPayload, type OperationType, type PeerCallback, type PeerState, type RegisterChangeCallback, type RegisterSetPayload, type RemoteChangeCallback, type SetAddPayload, type SetChangeCallback, type SetRemovePayload, type SyncState, type SyncStateCallback, type TextChangeCallback, type TextDeletePayload, type TextInsertPayload, compareHLC, makeOpId, makePositionId };

package/dist/crdt/index.js

@@ -0,0 +1,3 @@
+export { CRDTCounter, CRDTDocument, CRDTRegister, CRDTSet, CRDTSync, CRDTText, HybridLogicalClock, compareHLC, makeOpId, makePositionId } from '../chunk-5NHFZRMO.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/crdt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/react/index.d.ts

@@ -0,0 +1,144 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { AuthStore, BaseClient, BaseRecord, ListOptions, ConnectionState, RealtimeEvent } from '../core/index.js';
+export { BaseClientError, ClientConfig, ListResult, StateVersion } from '../core/index.js';
+import { CRDTDocument, CRDTText, CRDTCounter, CRDTSet, CRDTRegister, CRDTSync, SyncState, PeerState } from '../crdt/index.js';
+
+interface BaseProviderProps {
+    /** Base URL for automatic client creation. */
+    url?: string;
+    /** Optional auth store override. */
+    authStore?: AuthStore;
+    /** Pre-created BaseClient (takes precedence over url). */
+    client?: BaseClient;
+    children: ReactNode;
+}
+declare function BaseProvider({ url, authStore, client: externalClient, children }: BaseProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Get the BaseClient from the nearest BaseProvider.
+ * Throws if used outside a provider.
+ */
+declare function useBase(): BaseClient;
+
+/**
+ * React hooks for Hanzo Base.
+ *
+ * All hooks use the BaseClient from the nearest BaseProvider context.
+ * They manage subscriptions, cleanup, and state transitions correctly
+ * with React 19 patterns (useEffect, useState, useCallback, useRef).
+ */
+
+interface UseQueryOptions extends ListOptions {
+    /** Whether to auto-subscribe to realtime updates. Default: true. */
+    realtime?: boolean;
+    /** Whether to run the query immediately. Default: true. */
+    enabled?: boolean;
+}
+interface UseQueryResult<T = BaseRecord> {
+    data: T[];
+    isLoading: boolean;
+    error: Error | null;
+    /** Manually refetch the query. */
+    refetch: () => Promise<void>;
+}
+/**
+ * Reactive query hook.
+ *
+ * Fetches records from a collection and subscribes to realtime updates.
+ * Results are cached in the QueryStore for deduplication across components.
+ */
+declare function useQuery<T extends BaseRecord = BaseRecord>(collection: string, options?: UseQueryOptions): UseQueryResult<T>;
+type MutationAction = 'create' | 'update' | 'delete';
+interface MutateOptions {
+    /** If true, apply an optimistic update to the QueryStore before the server responds. */
+    optimistic?: boolean;
+}
+interface UseMutationResult {
+    mutate: (data: Record<string, unknown>, options?: MutateOptions) => Promise<BaseRecord | void>;
+    isLoading: boolean;
+    error: Error | null;
+}
+/**
+ * Mutation hook.
+ *
+ * Performs a create, update, or delete mutation against a collection.
+ * Supports optimistic updates that are automatically rolled back on failure.
+ */
+declare function useMutation(collection: string, action: MutationAction): UseMutationResult;
+interface UseAuthResult {
+    user: BaseRecord | null;
+    token: string;
+    isValid: boolean;
+    signIn: (identity: string, password: string) => Promise<void>;
+    signUp: (data: Record<string, unknown>) => Promise<BaseRecord>;
+    signOut: () => void;
+    /** Subscribe to auth changes. Returns unsubscribe. */
+    onChange: AuthStore['onChange'];
+}
+/**
+ * Auth state hook.
+ *
+ * Returns the current auth state and provides sign-in, sign-up, and
+ * sign-out methods. Re-renders when auth state changes.
+ *
+ * @param collection - Auth collection name (default: "users").
+ */
+declare function useAuth(collection?: string): UseAuthResult;
+/**
+ * Low-level realtime subscription hook.
+ *
+ * Subscribes to SSE events for a collection topic on mount and
+ * unsubscribes on unmount.
+ */
+declare function useRealtime(collection: string, topic: string, callback: (event: RealtimeEvent) => void): void;
+declare function useConnectionState(): ConnectionState;
+interface UsePresenceResult {
+    /** Map of peer siteId to their state. */
+    peers: Map<string, PeerState>;
+    /** Our own presence metadata. */
+    myState: Record<string, unknown>;
+    /** Update our presence metadata. */
+    updateState: (meta: Record<string, unknown>) => void;
+}
+/**
+ * Presence tracking hook.
+ *
+ * Requires a CRDTSync instance (usually obtained from useCRDT).
+ * Tracks peers connected to the same document.
+ */
+declare function usePresence(sync: CRDTSync): UsePresenceResult;
+interface UseCRDTResult {
+    /** The CRDTDocument instance. */
+    doc: CRDTDocument;
+    /** Convenience accessor for text fields. */
+    text: (field: string) => CRDTText;
+    /** Convenience accessor for counter fields. */
+    counter: (field: string) => CRDTCounter;
+    /** Convenience accessor for set fields. */
+    set: <T = unknown>(field: string) => CRDTSet<T>;
+    /** Convenience accessor for register fields. */
+    register: <T = unknown>(field: string) => CRDTRegister<T>;
+    /** The CRDTSync instance for advanced usage (presence, state listeners). */
+    sync: CRDTSync;
+    /** Current sync state. */
+    syncState: SyncState;
+}
+/**
+ * CRDT document hook.
+ *
+ * Creates a CRDTDocument and CRDTSync, connects to the server via
+ * WebSocket, and auto-syncs all local operations.
+ *
+ * @param documentId - Unique document identifier.
+ * @param wsUrl - WebSocket URL for the CRDT sync endpoint. If not provided,
+ *                derives it from the BaseClient URL (http->ws, https->wss).
+ */
+declare function useCRDT(documentId: string, wsUrl?: string): UseCRDTResult;
+/**
+ * Subscribe to a specific CRDTText field's current string value.
+ * Re-renders whenever the text changes (local or remote).
+ */
+declare function useCRDTText(doc: CRDTDocument, field: string): string;
+declare function useCRDTCounter(doc: CRDTDocument, field: string): number;
+
+export { AuthStore, BaseClient, BaseProvider, type BaseProviderProps, BaseRecord, ConnectionState, ListOptions, type MutateOptions, type MutationAction, RealtimeEvent, type UseAuthResult, type UseCRDTResult, type UseMutationResult, type UsePresenceResult, type UseQueryOptions, type UseQueryResult, useAuth, useBase, useCRDT, useCRDTCounter, useCRDTText, useConnectionState, useMutation, usePresence, useQuery, useRealtime };