@korajs/store 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,376 @@
+import { Q as QueryDescriptor, a as SubscriptionCallback, C as CollectionRecord, S as StorageAdapter, W as WhereClause, O as OrderByDirection, b as StoreConfig, A as ApplyResult } from './types-DF-KDSK1.js';
+export { M as MigrationPlan, c as OrderByClause, T as Transaction, d as WhereOperators } from './types-DF-KDSK1.js';
+import { KoraError, Operation, CollectionDefinition, SchemaDefinition, OperationLog, VersionVector, HybridLogicalClock } from '@korajs/core';
+
+/**
+ * Thrown when a query is invalid (bad field names, invalid operators, etc.).
+ */
+declare class QueryError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when a record is not found by ID (findById, update, delete on missing record).
+ */
+declare class RecordNotFoundError extends KoraError {
+    constructor(collection: string, recordId: string);
+}
+/**
+ * Thrown when a storage adapter operation fails.
+ */
+declare class AdapterError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when an operation is attempted on a store that has not been opened.
+ */
+declare class StoreNotOpenError extends KoraError {
+    constructor();
+}
+/**
+ * Thrown when the Web Worker fails to initialize (WASM load failure, OPFS unavailable, etc.).
+ */
+declare class WorkerInitError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when the Web Worker does not respond within the configured timeout.
+ */
+declare class WorkerTimeoutError extends KoraError {
+    constructor(operation: string, timeoutMs: number);
+}
+/**
+ * Thrown when IndexedDB persistence operations fail (serialize/deserialize).
+ */
+declare class PersistenceError extends KoraError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+
+/**
+ * Manages reactive subscriptions. When a mutation occurs on a collection,
+ * affected subscriptions are re-evaluated in a microtask batch and callbacks
+ * are invoked only if results actually changed.
+ */
+declare class SubscriptionManager {
+    private subscriptions;
+    private pendingCollections;
+    private flushScheduled;
+    /**
+     * Register a new subscription.
+     *
+     * @param descriptor - The query descriptor defining what this subscription watches
+     * @param callback - Called with results whenever they change
+     * @param executeFn - Function to re-execute the query and get current results
+     * @returns An unsubscribe function
+     */
+    register(descriptor: QueryDescriptor, callback: SubscriptionCallback<CollectionRecord>, executeFn: () => Promise<CollectionRecord[]>): () => void;
+    /**
+     * Register a subscription and immediately execute the query.
+     * The initial results are stored as lastResults so subsequent flushes
+     * correctly diff against the initial state.
+     *
+     * @returns An unsubscribe function
+     */
+    registerAndFetch(descriptor: QueryDescriptor, callback: SubscriptionCallback<CollectionRecord>, executeFn: () => Promise<CollectionRecord[]>): () => void;
+    /**
+     * Notify the manager that a mutation occurred on a collection.
+     * Schedules a microtask flush to batch multiple mutations in the same tick.
+     */
+    notify(collection: string, _operation: Operation): void;
+    /**
+     * Immediately flush all pending notifications.
+     * Useful for testing. In production, flushing happens via microtask.
+     */
+    flush(): Promise<void>;
+    /**
+     * Remove all subscriptions. Called on store close.
+     */
+    clear(): void;
+    /** Number of active subscriptions (for testing/debugging) */
+    get size(): number;
+    private scheduleFlush;
+    /**
+     * Compare two result sets. Uses length check + JSON comparison as pragmatic approach.
+     * Sufficient for typical query results. Can be optimized to id-based diffing if profiling shows need.
+     */
+    private resultsEqual;
+}
+
+/**
+ * Fluent query builder for constructing and executing collection queries.
+ * Supports where, orderBy, limit, offset, include, exec, count, and subscribe.
+ *
+ * The generic parameter `T` defaults to `CollectionRecord` for backward compatibility
+ * but can be narrowed to a specific record type for full type inference.
+ *
+ * @example
+ * ```typescript
+ * const todos = await app.todos
+ *   .where({ completed: false })
+ *   .orderBy('createdAt', 'desc')
+ *   .limit(10)
+ *   .exec()
+ * ```
+ */
+declare class QueryBuilder<T = CollectionRecord> {
+    private readonly collectionName;
+    private readonly definition;
+    private readonly adapter;
+    private readonly subscriptionManager;
+    private readonly schema?;
+    private descriptor;
+    constructor(collectionName: string, definition: CollectionDefinition, adapter: StorageAdapter, subscriptionManager: SubscriptionManager, initialWhere?: WhereClause, schema?: SchemaDefinition | undefined);
+    /**
+     * Add WHERE conditions (AND semantics, merged with existing conditions).
+     */
+    where(conditions: WhereClause): QueryBuilder<T>;
+    /**
+     * Add ORDER BY clause.
+     */
+    orderBy(field: string, direction?: OrderByDirection): QueryBuilder<T>;
+    /**
+     * Set result limit.
+     */
+    limit(n: number): QueryBuilder<T>;
+    /**
+     * Set result offset.
+     */
+    offset(n: number): QueryBuilder<T>;
+    /**
+     * Include related records in the query results.
+     * Follows relations defined in the schema to batch-fetch related data.
+     *
+     * @param targets - Relation target names (collection names or relation names)
+     * @returns A new QueryBuilder with include targets added
+     *
+     * @example
+     * ```typescript
+     * const todosWithProject = await app.todos
+     *   .where({ completed: false })
+     *   .include('project')
+     *   .exec()
+     * ```
+     */
+    include(...targets: string[]): QueryBuilder<T>;
+    /**
+     * Execute the query and return results.
+     */
+    exec(): Promise<T[]>;
+    /**
+     * Execute a COUNT query and return the count.
+     */
+    count(): Promise<number>;
+    /**
+     * Subscribe to query results. Callback is called immediately with current results,
+     * then again whenever the results change due to mutations.
+     *
+     * @returns An unsubscribe function
+     */
+    subscribe(callback: SubscriptionCallback<T>): () => void;
+    /** Get the internal descriptor (for testing/debugging) */
+    getDescriptor(): QueryDescriptor;
+    private clone;
+    /**
+     * Resolve include targets to their actual collection names for subscription tracking.
+     */
+    private resolveIncludeCollections;
+    /**
+     * Resolve includes after primary query, batch-fetching related records.
+     */
+    private resolveIncludes;
+    /**
+     * Many-to-one: collect FK values from primary results, batch-fetch related, attach as singular.
+     */
+    private resolveManyToOneInclude;
+    /**
+     * One-to-many: collect primary IDs, batch-fetch children, attach as array.
+     */
+    private resolveOneToManyInclude;
+    /**
+     * Find a relation definition matching the include target.
+     * Searches by relation name, target collection name, and singularized/pluralized variants.
+     */
+    private findRelation;
+}
+
+/**
+ * Store is the main orchestrator. It owns a schema, a storage adapter,
+ * a clock, and a subscription manager. It creates Collection instances
+ * for each schema collection, and provides the sync contract via
+ * applyRemoteOperation and getOperationRange.
+ *
+ * @example
+ * ```typescript
+ * const store = new Store({ schema, adapter })
+ * await store.open()
+ * const todo = await store.collection('todos').insert({ title: 'Hello' })
+ * await store.close()
+ * ```
+ */
+declare class Store implements OperationLog {
+    private opened;
+    private nodeId;
+    private sequenceNumber;
+    private versionVector;
+    private clock;
+    private collections;
+    private subscriptionManager;
+    private readonly schema;
+    private readonly adapter;
+    private readonly configNodeId;
+    private readonly emitter;
+    constructor(config: StoreConfig);
+    /**
+     * Open the store: initialize the database, load or generate a node ID,
+     * restore the sequence number and version vector, and create Collection instances.
+     */
+    open(): Promise<void>;
+    /**
+     * Close the store: clear subscriptions and close the adapter.
+     */
+    close(): Promise<void>;
+    /**
+     * Get a Collection instance for CRUD operations.
+     * @throws {StoreNotOpenError} If the store is not open
+     * @throws {Error} If the collection name is not in the schema
+     */
+    collection(name: string): CollectionAccessor;
+    /**
+     * Get the current version vector.
+     */
+    getVersionVector(): VersionVector;
+    /**
+     * Get the node ID for this store instance.
+     */
+    getNodeId(): string;
+    /**
+     * Apply a remote operation received from sync.
+     * Checks for duplicates, applies to the data table, persists the operation,
+     * and updates the version vector.
+     */
+    applyRemoteOperation(op: Operation): Promise<ApplyResult>;
+    /**
+     * Get operations from a node within a sequence number range.
+     * Implements the OperationLog interface for computeDelta.
+     */
+    getRange(nodeId: string, fromSeq: number, toSeq: number): Operation[];
+    /**
+     * Async version of getRange for use by the sync layer.
+     */
+    getOperationRange(nodeId: string, fromSeq: number, toSeq: number): Promise<Operation[]>;
+    /**
+     * Get the schema definition.
+     */
+    getSchema(): SchemaDefinition;
+    /** Expose the subscription manager for direct access (e.g., by QueryBuilder) */
+    getSubscriptionManager(): SubscriptionManager;
+    private nextSequenceNumber;
+    private loadOrGenerateNodeId;
+    private loadSequenceNumber;
+    private loadVersionVector;
+    private ensureOpen;
+}
+/**
+ * Public-facing collection accessor. Provides CRUD + where.
+ */
+interface CollectionAccessor {
+    insert(data: Record<string, unknown>): Promise<CollectionRecord>;
+    findById(id: string): Promise<CollectionRecord | null>;
+    update(id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
+    delete(id: string): Promise<void>;
+    where(conditions: Record<string, unknown>): QueryBuilder;
+}
+
+/**
+ * Callback invoked after a mutation so the Store can notify subscriptions.
+ */
+type MutationCallback = (collection: string, operation: Operation) => void;
+/**
+ * Collection provides CRUD operations on a single schema collection.
+ * Each mutation creates an Operation and persists both the data and the operation atomically.
+ */
+declare class Collection {
+    private readonly name;
+    private readonly definition;
+    private readonly schema;
+    private readonly adapter;
+    private readonly clock;
+    private readonly nodeId;
+    private readonly getSequenceNumber;
+    private readonly onMutation;
+    constructor(name: string, definition: CollectionDefinition, schema: SchemaDefinition, adapter: StorageAdapter, clock: HybridLogicalClock, nodeId: string, getSequenceNumber: () => number, onMutation: MutationCallback);
+    /**
+     * Insert a new record into the collection.
+     * Generates a UUID v7 for the id, validates data, and persists atomically.
+     *
+     * @param data - The record data (auto fields and defaults are applied automatically)
+     * @returns The inserted record with id, createdAt, updatedAt
+     */
+    insert(data: Record<string, unknown>): Promise<CollectionRecord>;
+    /**
+     * Find a record by its ID. Returns null if not found or soft-deleted.
+     */
+    findById(id: string): Promise<CollectionRecord | null>;
+    /**
+     * Update an existing record. Only the provided fields are changed.
+     *
+     * @param id - The record ID to update
+     * @param data - Partial data with only the fields to change
+     * @returns The updated record
+     * @throws {RecordNotFoundError} If the record doesn't exist or is deleted
+     */
+    update(id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
+    /**
+     * Soft-delete a record by its ID.
+     *
+     * @param id - The record ID to delete
+     * @throws {RecordNotFoundError} If the record doesn't exist or is already deleted
+     */
+    delete(id: string): Promise<void>;
+    /** Get the collection name */
+    getName(): string;
+    /** Get the collection definition */
+    getDefinition(): CollectionDefinition;
+}
+
+type RichtextInput = string | Uint8Array | ArrayBuffer | null | undefined;
+/**
+ * Encodes richtext values into Yjs document updates.
+ */
+declare function encodeRichtext(value: RichtextInput): Uint8Array | null;
+/**
+ * Decodes driver-provided richtext values into Uint8Array.
+ */
+declare function decodeRichtext(value: unknown): Uint8Array | null;
+/**
+ * Reads plain text from a richtext Yjs state update.
+ */
+declare function richtextToPlainText(value: RichtextInput): string;
+
+/**
+ * Minimal pluralization/singularization utilities for relation name resolution.
+ * Handles common English patterns — not meant to be exhaustive.
+ */
+/**
+ * Pluralize a word using common English rules.
+ *
+ * @example
+ * ```
+ * pluralize('project') // 'projects'
+ * pluralize('category') // 'categories'
+ * pluralize('match') // 'matches'
+ * ```
+ */
+declare function pluralize(word: string): string;
+/**
+ * Singularize a word using common English rules.
+ *
+ * @example
+ * ```
+ * singularize('projects') // 'project'
+ * singularize('categories') // 'category'
+ * singularize('matches') // 'match'
+ * ```
+ */
+declare function singularize(word: string): string;
+
+export { AdapterError, ApplyResult, Collection, type CollectionAccessor, CollectionRecord, OrderByDirection, PersistenceError, QueryBuilder, QueryDescriptor, QueryError, RecordNotFoundError, StorageAdapter, Store, StoreConfig, StoreNotOpenError, SubscriptionCallback, SubscriptionManager, WhereClause, WorkerInitError, WorkerTimeoutError, decodeRichtext, encodeRichtext, pluralize, richtextToPlainText, singularize };