@korajs/store 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -4,6 +4,7 @@ import { Operation, KoraError, VersionVector, SchemaDefinition, MergeTrace, Coll
 export { ApplyResult } from '@korajs/core';
 import { R as RelationEnforcer, L as LocalMutationContext } from './types-CTr00g_d.cjs';
 export { C as Collection } from './types-CTr00g_d.cjs';
+import * as yjs from 'yjs';
 
 /**
  * In-memory materialized state at a causal cut in the operation log.
@@ -896,6 +897,62 @@ interface CollectionAccessor {
     where(conditions: Record<string, unknown>): QueryBuilder;
 }
 
+/**
+ * Bridges the async QueryBuilder.subscribe() API with synchronous snapshot reads
+ * required by React useSyncExternalStore, Vue composables, and Svelte stores.
+ *
+ * Uses lazy subscription: the underlying query subscription starts when the first
+ * listener attaches and stops when the last listener detaches.
+ */
+declare class QueryStore<T = CollectionRecord> {
+    private snapshot;
+    private listeners;
+    private unsubscribeQuery;
+    private active;
+    private readonly queryBuilder;
+    constructor(queryBuilder: QueryBuilder<T>);
+    /**
+     * Subscribe to snapshot changes.
+     *
+     * @returns Unsubscribe function
+     */
+    subscribe: (onStoreChange: () => void) => (() => void);
+    /** Synchronous read of the latest query results. */
+    getSnapshot: () => readonly T[];
+    /** Tear down listeners and the underlying query subscription. */
+    destroy(): void;
+    private startSubscription;
+    private stopSubscription;
+    private notifyListeners;
+}
+
+/**
+ * Ensures a query builder is backed by an open store (not a legacy pending placeholder).
+ */
+declare function assertQueryReady(query: QueryBuilder<unknown>): void;
+
+/**
+ * Reference-counted cache of {@link QueryStore} instances keyed by query descriptor.
+ * Identical queries from different components share one underlying subscription.
+ */
+declare class QueryStoreCache {
+    private readonly scopeKey;
+    private entries;
+    constructor(scopeKey?: string);
+    getOrCreate<T>(queryBuilder: QueryBuilder<T>): QueryStore<T>;
+    release(queryBuilder: QueryBuilder<unknown>): void;
+    clear(): void;
+    get size(): number;
+    private getKey;
+}
+/**
+ * Process-wide shared query store cache for framework bindings.
+ *
+ * @deprecated Prefer {@link KoraApp.getQueryStoreCache} via `KoraProvider` context
+ * so each app instance owns an isolated cache.
+ */
+declare function getSharedQueryStoreCache(): QueryStoreCache;
+
 /**
  * Bloom filter for subscription dependency tracking.
  *
@@ -1040,6 +1097,91 @@ declare function validateStateTransition(collectionName: string, recordId: strin
  */
 declare function validateUpdateStateMachine(collectionName: string, recordId: string, collectionDef: CollectionDefinition, currentRecord: Record<string, unknown>, updateData: Record<string, unknown>): Record<string, unknown>;
 
+/** User identity for collaborative cursor presence. */
+interface RichTextAwarenessUser {
+    name: string;
+    color: string;
+    avatar?: string;
+}
+/** Remote collaborator cursor for a richtext field. */
+interface RichTextCursorInfo {
+    clientId: number;
+    userName: string;
+    color: string;
+    anchor: number;
+    head: number;
+}
+/** Minimal sync surface required for richtext collaboration. */
+interface RichTextSyncEngine {
+    getRichtextDocChannel?(): RichTextDocChannel;
+    getAwarenessManager(): RichTextAwarenessManager;
+}
+interface RichTextDocChannel {
+    shouldUseChannel(snapshotBytes: number, useDocChannel?: boolean): boolean;
+    send(collection: string, recordId: string, field: string, update: Uint8Array): void;
+    subscribe(collection: string, recordId: string, field: string, listener: (update: Uint8Array) => void): () => void;
+}
+interface RichTextAwarenessManager {
+    clientId: number;
+    getLocalState(): RichTextAwarenessState | null;
+    setLocalState(state: RichTextAwarenessState): void;
+    getStates(): Map<number, RichTextAwarenessState>;
+    on(event: 'change', listener: () => void): () => void;
+}
+interface RichTextAwarenessState {
+    user: RichTextAwarenessUser;
+    cursor?: {
+        collection: string;
+        recordId: string;
+        field: string;
+        anchor: number;
+        head: number;
+    };
+}
+interface CreateRichTextControllerOptions {
+    collection: CollectionAccessor;
+    collectionName: string;
+    recordId: string;
+    fieldName: string;
+    store: {
+        collection(name: string): CollectionAccessor;
+    };
+    syncEngine?: RichTextSyncEngine | null;
+    useDocChannel?: boolean;
+    user?: RichTextAwarenessUser;
+}
+interface RichTextControllerSnapshot {
+    ready: boolean;
+    error: Error | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    cursors: readonly RichTextCursorInfo[];
+}
+interface RichTextController {
+    readonly doc: yjs.Doc;
+    readonly text: yjs.Text;
+    getSnapshot(): RichTextControllerSnapshot;
+    subscribe(listener: () => void): () => void;
+    undo(): void;
+    redo(): void;
+    setCursor(anchor: number, head: number): void;
+    clearCursor(): void;
+    setUser(user: RichTextAwarenessUser | undefined): void;
+    destroy(): void;
+}
+
+/**
+ * Framework-agnostic richtext binding: Yjs document lifecycle, persistence,
+ * incremental doc channel, and awareness cursors.
+ */
+declare function createRichTextController(options: CreateRichTextControllerOptions): RichTextController;
+
+/**
+ * Narrows a sync engine reference to the richtext controller surface.
+ * SyncEngine satisfies this interface at runtime; types live in different packages.
+ */
+declare function asRichTextSyncEngine(engine: unknown): RichTextSyncEngine | null;
+
 type RichtextInput = string | Uint8Array | ArrayBuffer | null | undefined;
 /**
  * Encodes richtext values into Yjs document updates.
@@ -1145,4 +1287,4 @@ declare function readAuditExportManifest(data: Uint8Array): AuditExportManifest;
  */
 declare function verifyAuditExportChecksum(data: Uint8Array): Promise<boolean>;
 
-export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };
+export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, type CreateRichTextControllerOptions, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, getSharedQueryStoreCache, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };

package/dist/index.d.ts

@@ -4,6 +4,7 @@ import { Operation, KoraError, VersionVector, SchemaDefinition, MergeTrace, Coll
 export { ApplyResult } from '@korajs/core';
 import { R as RelationEnforcer, L as LocalMutationContext } from './types-BMyHmwvn.js';
 export { C as Collection } from './types-BMyHmwvn.js';
+import * as yjs from 'yjs';
 
 /**
  * In-memory materialized state at a causal cut in the operation log.
@@ -896,6 +897,62 @@ interface CollectionAccessor {
     where(conditions: Record<string, unknown>): QueryBuilder;
 }
 
+/**
+ * Bridges the async QueryBuilder.subscribe() API with synchronous snapshot reads
+ * required by React useSyncExternalStore, Vue composables, and Svelte stores.
+ *
+ * Uses lazy subscription: the underlying query subscription starts when the first
+ * listener attaches and stops when the last listener detaches.
+ */
+declare class QueryStore<T = CollectionRecord> {
+    private snapshot;
+    private listeners;
+    private unsubscribeQuery;
+    private active;
+    private readonly queryBuilder;
+    constructor(queryBuilder: QueryBuilder<T>);
+    /**
+     * Subscribe to snapshot changes.
+     *
+     * @returns Unsubscribe function
+     */
+    subscribe: (onStoreChange: () => void) => (() => void);
+    /** Synchronous read of the latest query results. */
+    getSnapshot: () => readonly T[];
+    /** Tear down listeners and the underlying query subscription. */
+    destroy(): void;
+    private startSubscription;
+    private stopSubscription;
+    private notifyListeners;
+}
+
+/**
+ * Ensures a query builder is backed by an open store (not a legacy pending placeholder).
+ */
+declare function assertQueryReady(query: QueryBuilder<unknown>): void;
+
+/**
+ * Reference-counted cache of {@link QueryStore} instances keyed by query descriptor.
+ * Identical queries from different components share one underlying subscription.
+ */
+declare class QueryStoreCache {
+    private readonly scopeKey;
+    private entries;
+    constructor(scopeKey?: string);
+    getOrCreate<T>(queryBuilder: QueryBuilder<T>): QueryStore<T>;
+    release(queryBuilder: QueryBuilder<unknown>): void;
+    clear(): void;
+    get size(): number;
+    private getKey;
+}
+/**
+ * Process-wide shared query store cache for framework bindings.
+ *
+ * @deprecated Prefer {@link KoraApp.getQueryStoreCache} via `KoraProvider` context
+ * so each app instance owns an isolated cache.
+ */
+declare function getSharedQueryStoreCache(): QueryStoreCache;
+
 /**
  * Bloom filter for subscription dependency tracking.
  *
@@ -1040,6 +1097,91 @@ declare function validateStateTransition(collectionName: string, recordId: strin
  */
 declare function validateUpdateStateMachine(collectionName: string, recordId: string, collectionDef: CollectionDefinition, currentRecord: Record<string, unknown>, updateData: Record<string, unknown>): Record<string, unknown>;
 
+/** User identity for collaborative cursor presence. */
+interface RichTextAwarenessUser {
+    name: string;
+    color: string;
+    avatar?: string;
+}
+/** Remote collaborator cursor for a richtext field. */
+interface RichTextCursorInfo {
+    clientId: number;
+    userName: string;
+    color: string;
+    anchor: number;
+    head: number;
+}
+/** Minimal sync surface required for richtext collaboration. */
+interface RichTextSyncEngine {
+    getRichtextDocChannel?(): RichTextDocChannel;
+    getAwarenessManager(): RichTextAwarenessManager;
+}
+interface RichTextDocChannel {
+    shouldUseChannel(snapshotBytes: number, useDocChannel?: boolean): boolean;
+    send(collection: string, recordId: string, field: string, update: Uint8Array): void;
+    subscribe(collection: string, recordId: string, field: string, listener: (update: Uint8Array) => void): () => void;
+}
+interface RichTextAwarenessManager {
+    clientId: number;
+    getLocalState(): RichTextAwarenessState | null;
+    setLocalState(state: RichTextAwarenessState): void;
+    getStates(): Map<number, RichTextAwarenessState>;
+    on(event: 'change', listener: () => void): () => void;
+}
+interface RichTextAwarenessState {
+    user: RichTextAwarenessUser;
+    cursor?: {
+        collection: string;
+        recordId: string;
+        field: string;
+        anchor: number;
+        head: number;
+    };
+}
+interface CreateRichTextControllerOptions {
+    collection: CollectionAccessor;
+    collectionName: string;
+    recordId: string;
+    fieldName: string;
+    store: {
+        collection(name: string): CollectionAccessor;
+    };
+    syncEngine?: RichTextSyncEngine | null;
+    useDocChannel?: boolean;
+    user?: RichTextAwarenessUser;
+}
+interface RichTextControllerSnapshot {
+    ready: boolean;
+    error: Error | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    cursors: readonly RichTextCursorInfo[];
+}
+interface RichTextController {
+    readonly doc: yjs.Doc;
+    readonly text: yjs.Text;
+    getSnapshot(): RichTextControllerSnapshot;
+    subscribe(listener: () => void): () => void;
+    undo(): void;
+    redo(): void;
+    setCursor(anchor: number, head: number): void;
+    clearCursor(): void;
+    setUser(user: RichTextAwarenessUser | undefined): void;
+    destroy(): void;
+}
+
+/**
+ * Framework-agnostic richtext binding: Yjs document lifecycle, persistence,
+ * incremental doc channel, and awareness cursors.
+ */
+declare function createRichTextController(options: CreateRichTextControllerOptions): RichTextController;
+
+/**
+ * Narrows a sync engine reference to the richtext controller surface.
+ * SyncEngine satisfies this interface at runtime; types live in different packages.
+ */
+declare function asRichTextSyncEngine(engine: unknown): RichTextSyncEngine | null;
+
 type RichtextInput = string | Uint8Array | ArrayBuffer | null | undefined;
 /**
  * Encodes richtext values into Yjs document updates.
@@ -1145,4 +1287,4 @@ declare function readAuditExportManifest(data: Uint8Array): AuditExportManifest;
  */
 declare function verifyAuditExportChecksum(data: Uint8Array): Promise<boolean>;
 
-export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };
+export { AdapterError, ApplyRemoteOptions, type AuditExportManifest, type AuditExportOptions, type AuditExportPayload, type AuditExportProgress, type AuditTraceQuery, type BackupManifest, type BackupOptions, type BackupProgress, COMPACTION_BASELINE_META_KEY, type CollectionAccessor, CollectionRecord, type CompactionResult, type CompactionStrategy, type CreateRichTextControllerOptions, InvalidStateTransitionError, LAST_ACKED_SERVER_VECTOR_META_KEY, LocalMutationHandler, MaterializedRowSnapshot, OrderByDirection, type PersistedAuditTrace, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, QueryStore, QueryStoreCache, RecordNotFoundError, type ReplaySnapshot, type RestoreOptions, type RestoreResult, type RichTextAwarenessUser, type RichTextController, type RichTextControllerSnapshot, type RichTextCursorInfo, type RichTextSyncEngine, SequenceManager, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionBloomFilter, SubscriptionCallback, SubscriptionManager, type SubscriptionManagerOptions, type SubscriptionStats, type TransactionCollectionAccessor, TransactionContext, type TransactionContextConfig, WhereClause, WorkerInitError, WorkerTimeoutError, asRichTextSyncEngine, assertQueryReady, collectOperationsAheadOfServer, compactOperationLog, computeAckCompactionWatermark, createRichTextController, decodeAuditExport, decodeRichtext, deserializeVersionVectorFromMeta, encodeRichtext, exportBackup, getSharedQueryStoreCache, mergeVersionVectors, persistedAuditTraceFromEvent, pluralize, readAuditExportManifest, readBackupManifest, restoreBackup, richtextStatesEqual, richtextToPlainText, serializeVersionVectorToMeta, singularize, validateStateTransition, validateUpdateStateMachine, verifyAuditExportChecksum, verifyBackupChecksum };