@korajs/store 0.4.0 → 0.5.0

package/dist/types-BMyHmwvn.d.ts

@@ -0,0 +1,163 @@
+import { OnDeleteAction, RelationDefinition, SchemaDefinition, HybridLogicalClock, Operation, CollectionDefinition, CausalTracker } from '@korajs/core';
+import { S as StorageAdapter, T as Transaction, L as LocalMutationHandler, C as CollectionRecord } from './types-DepnRDk_.js';
+
+/**
+ * A resolved relation reference: describes a relation that points TO a given collection.
+ * When a record in `targetCollection` is deleted, we must handle records in
+ * `sourceCollection` that reference it via `foreignKeyField`.
+ */
+interface IncomingRelation {
+    /** Name of the relation in the schema */
+    relationName: string;
+    /** Collection that holds the foreign key (the "from" side) */
+    sourceCollection: string;
+    /** Field in the source collection that references the target */
+    foreignKeyField: string;
+    /** What to do when the referenced record is deleted */
+    onDelete: OnDeleteAction;
+    /** The full relation definition */
+    relation: RelationDefinition;
+}
+
+/**
+ * Configuration for the RelationEnforcer.
+ */
+interface RelationEnforcerConfig {
+    schema: SchemaDefinition;
+    adapter: StorageAdapter;
+    clock: HybridLogicalClock;
+    nodeId: string;
+}
+/**
+ * Result of enforcing referential integrity on a delete operation.
+ * Contains all additional operations that were created as side effects
+ * (cascaded deletes and set-null updates).
+ */
+interface EnforcementResult {
+    /** Additional operations created by cascading deletes and set-null updates */
+    operations: Operation[];
+}
+/**
+ * Enforces referential integrity constraints during local delete operations.
+ *
+ * When a record is deleted, this enforcer checks all relations that reference
+ * the deleted record's collection and applies the appropriate onDelete policy:
+ *
+ * - **cascade**: Recursively deletes all referencing records
+ * - **set-null**: Sets the foreign key to null on all referencing records
+ * - **restrict**: Throws a ReferentialIntegrityError if any references exist
+ * - **no-action**: Does nothing (the foreign key is left dangling)
+ *
+ * The enforcer operates within a provided transaction to ensure atomicity.
+ * All generated operations (cascaded deletes, set-null updates) share a
+ * causal dependency chain through the original delete operation.
+ *
+ * @example
+ * ```typescript
+ * const enforcer = new RelationEnforcer({
+ *   schema, adapter, clock, nodeId,
+ *   allocateSequenceNumber: async () => ++seq,
+ * })
+ * const result = await enforcer.enforceDelete(
+ *   'projects', 'proj-1', tx, ['delete-op-id']
+ * )
+ * // result.operations contains any cascaded delete/update ops
+ * ```
+ */
+declare class RelationEnforcer {
+    private readonly lookup;
+    private readonly schema;
+    private readonly adapter;
+    private readonly clock;
+    private readonly nodeId;
+    constructor(config: RelationEnforcerConfig);
+    /**
+     * Enforce referential integrity after deleting a record.
+     *
+     * Must be called within a transaction. The transaction handle is used
+     * for all cascaded writes to ensure atomicity.
+     *
+     * @param collection - The collection the deleted record belongs to
+     * @param recordId - The ID of the deleted record
+     * @param tx - The active transaction handle
+     * @param causalDeps - Causal dependencies for generated operations
+     * @returns All additional operations created as side effects
+     * @throws {ReferentialIntegrityError} If a 'restrict' policy is violated
+     */
+    enforceDelete(collection: string, recordId: string, tx: Transaction, causalDeps: string[]): Promise<EnforcementResult>;
+    /**
+     * Enforce a single relation's onDelete policy.
+     */
+    private enforceRelation;
+    /**
+     * Cascade: delete all records in the source collection that reference
+     * the deleted record, then recursively cascade those deletes.
+     */
+    private enforceCascade;
+    /**
+     * Set-null: update all referencing records to set the foreign key to null.
+     */
+    private enforceSetNull;
+    /**
+     * Restrict: refuse the delete if any referencing records exist.
+     */
+    private enforceRestrict;
+    /**
+     * Get the relation lookup map for external use (e.g., by the merge engine).
+     */
+    getRelationLookup(): Map<string, IncomingRelation[]>;
+}
+
+/**
+ * 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.
+ * Delegates to {@link LocalMutationHandler} when configured (unified apply pipeline),
+ * otherwise uses shared mutation executors directly.
+ */
+declare class Collection {
+    private readonly name;
+    private readonly definition;
+    private readonly schema;
+    private readonly adapter;
+    private readonly clock;
+    private readonly nodeId;
+    private readonly allocateSequenceNumber;
+    private readonly onMutation;
+    private readonly relationEnforcer;
+    private mutationHandler;
+    private readonly causalTracker;
+    constructor(name: string, definition: CollectionDefinition, schema: SchemaDefinition, adapter: StorageAdapter, clock: HybridLogicalClock, nodeId: string, allocateSequenceNumber: () => Promise<number>, onMutation: MutationCallback, relationEnforcer: RelationEnforcer | null, mutationHandler: LocalMutationHandler | null, causalTracker: CausalTracker | null);
+    private mutationContext;
+    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>;
+    getName(): string;
+    getDefinition(): CollectionDefinition;
+    /** Replace the mutation handler (e.g. after ApplyPipeline is wired in createApp). */
+    setMutationHandler(handler: LocalMutationHandler | null): void;
+}
+
+/**
+ * Shared context for executing local collection mutations.
+ */
+interface LocalMutationContext {
+    readonly collection: string;
+    readonly definition: CollectionDefinition;
+    readonly schema: SchemaDefinition;
+    readonly adapter: StorageAdapter;
+    readonly clock: HybridLogicalClock;
+    readonly nodeId: string;
+    readonly allocateSequenceNumber: () => Promise<number>;
+    readonly onMutation: MutationCallback;
+    readonly relationEnforcer: RelationEnforcer | null;
+    readonly causalTracker: CausalTracker | null;
+    readonly inTransaction: boolean;
+    /** Additional parent op ids (e.g. referential cascade from a delete). */
+    readonly extraCausalDeps?: string[];
+}
+
+export { Collection as C, type LocalMutationContext as L, RelationEnforcer as R };

package/dist/types-CTr00g_d.d.cts

@@ -0,0 +1,163 @@
+import { OnDeleteAction, RelationDefinition, SchemaDefinition, HybridLogicalClock, Operation, CollectionDefinition, CausalTracker } from '@korajs/core';
+import { S as StorageAdapter, T as Transaction, L as LocalMutationHandler, C as CollectionRecord } from './types-DepnRDk_.cjs';
+
+/**
+ * A resolved relation reference: describes a relation that points TO a given collection.
+ * When a record in `targetCollection` is deleted, we must handle records in
+ * `sourceCollection` that reference it via `foreignKeyField`.
+ */
+interface IncomingRelation {
+    /** Name of the relation in the schema */
+    relationName: string;
+    /** Collection that holds the foreign key (the "from" side) */
+    sourceCollection: string;
+    /** Field in the source collection that references the target */
+    foreignKeyField: string;
+    /** What to do when the referenced record is deleted */
+    onDelete: OnDeleteAction;
+    /** The full relation definition */
+    relation: RelationDefinition;
+}
+
+/**
+ * Configuration for the RelationEnforcer.
+ */
+interface RelationEnforcerConfig {
+    schema: SchemaDefinition;
+    adapter: StorageAdapter;
+    clock: HybridLogicalClock;
+    nodeId: string;
+}
+/**
+ * Result of enforcing referential integrity on a delete operation.
+ * Contains all additional operations that were created as side effects
+ * (cascaded deletes and set-null updates).
+ */
+interface EnforcementResult {
+    /** Additional operations created by cascading deletes and set-null updates */
+    operations: Operation[];
+}
+/**
+ * Enforces referential integrity constraints during local delete operations.
+ *
+ * When a record is deleted, this enforcer checks all relations that reference
+ * the deleted record's collection and applies the appropriate onDelete policy:
+ *
+ * - **cascade**: Recursively deletes all referencing records
+ * - **set-null**: Sets the foreign key to null on all referencing records
+ * - **restrict**: Throws a ReferentialIntegrityError if any references exist
+ * - **no-action**: Does nothing (the foreign key is left dangling)
+ *
+ * The enforcer operates within a provided transaction to ensure atomicity.
+ * All generated operations (cascaded deletes, set-null updates) share a
+ * causal dependency chain through the original delete operation.
+ *
+ * @example
+ * ```typescript
+ * const enforcer = new RelationEnforcer({
+ *   schema, adapter, clock, nodeId,
+ *   allocateSequenceNumber: async () => ++seq,
+ * })
+ * const result = await enforcer.enforceDelete(
+ *   'projects', 'proj-1', tx, ['delete-op-id']
+ * )
+ * // result.operations contains any cascaded delete/update ops
+ * ```
+ */
+declare class RelationEnforcer {
+    private readonly lookup;
+    private readonly schema;
+    private readonly adapter;
+    private readonly clock;
+    private readonly nodeId;
+    constructor(config: RelationEnforcerConfig);
+    /**
+     * Enforce referential integrity after deleting a record.
+     *
+     * Must be called within a transaction. The transaction handle is used
+     * for all cascaded writes to ensure atomicity.
+     *
+     * @param collection - The collection the deleted record belongs to
+     * @param recordId - The ID of the deleted record
+     * @param tx - The active transaction handle
+     * @param causalDeps - Causal dependencies for generated operations
+     * @returns All additional operations created as side effects
+     * @throws {ReferentialIntegrityError} If a 'restrict' policy is violated
+     */
+    enforceDelete(collection: string, recordId: string, tx: Transaction, causalDeps: string[]): Promise<EnforcementResult>;
+    /**
+     * Enforce a single relation's onDelete policy.
+     */
+    private enforceRelation;
+    /**
+     * Cascade: delete all records in the source collection that reference
+     * the deleted record, then recursively cascade those deletes.
+     */
+    private enforceCascade;
+    /**
+     * Set-null: update all referencing records to set the foreign key to null.
+     */
+    private enforceSetNull;
+    /**
+     * Restrict: refuse the delete if any referencing records exist.
+     */
+    private enforceRestrict;
+    /**
+     * Get the relation lookup map for external use (e.g., by the merge engine).
+     */
+    getRelationLookup(): Map<string, IncomingRelation[]>;
+}
+
+/**
+ * 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.
+ * Delegates to {@link LocalMutationHandler} when configured (unified apply pipeline),
+ * otherwise uses shared mutation executors directly.
+ */
+declare class Collection {
+    private readonly name;
+    private readonly definition;
+    private readonly schema;
+    private readonly adapter;
+    private readonly clock;
+    private readonly nodeId;
+    private readonly allocateSequenceNumber;
+    private readonly onMutation;
+    private readonly relationEnforcer;
+    private mutationHandler;
+    private readonly causalTracker;
+    constructor(name: string, definition: CollectionDefinition, schema: SchemaDefinition, adapter: StorageAdapter, clock: HybridLogicalClock, nodeId: string, allocateSequenceNumber: () => Promise<number>, onMutation: MutationCallback, relationEnforcer: RelationEnforcer | null, mutationHandler: LocalMutationHandler | null, causalTracker: CausalTracker | null);
+    private mutationContext;
+    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>;
+    getName(): string;
+    getDefinition(): CollectionDefinition;
+    /** Replace the mutation handler (e.g. after ApplyPipeline is wired in createApp). */
+    setMutationHandler(handler: LocalMutationHandler | null): void;
+}
+
+/**
+ * Shared context for executing local collection mutations.
+ */
+interface LocalMutationContext {
+    readonly collection: string;
+    readonly definition: CollectionDefinition;
+    readonly schema: SchemaDefinition;
+    readonly adapter: StorageAdapter;
+    readonly clock: HybridLogicalClock;
+    readonly nodeId: string;
+    readonly allocateSequenceNumber: () => Promise<number>;
+    readonly onMutation: MutationCallback;
+    readonly relationEnforcer: RelationEnforcer | null;
+    readonly causalTracker: CausalTracker | null;
+    readonly inTransaction: boolean;
+    /** Additional parent op ids (e.g. referential cascade from a delete). */
+    readonly extraCausalDeps?: string[];
+}
+
+export { Collection as C, type LocalMutationContext as L, RelationEnforcer as R };

package/dist/types-DepnRDk_.d.cts

@@ -0,0 +1,212 @@
+import { SchemaDefinition, Operation, KoraEventEmitter } from '@korajs/core';
+
+/**
+ * Transaction interface for executing multiple operations atomically.
+ */
+interface Transaction {
+    execute(sql: string, params?: unknown[]): Promise<void>;
+    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/**
+ * Migration plan containing SQL statements and optional data transforms.
+ */
+interface MigrationPlan {
+    statements: string[];
+    transforms?: Array<(row: Record<string, unknown>) => Record<string, unknown>>;
+}
+/**
+ * Storage adapter interface. All storage backends must implement this.
+ * Operations are async to support both sync (better-sqlite3) and async (IndexedDB, WASM) backends.
+ */
+interface StorageAdapter {
+    /** Open or create the database */
+    open(schema: SchemaDefinition): Promise<void>;
+    /** Close the database and release resources */
+    close(): Promise<void>;
+    /** Execute a write query (INSERT, UPDATE, DELETE) within a transaction */
+    execute(sql: string, params?: unknown[]): Promise<void>;
+    /** Execute a read query (SELECT) */
+    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+    /** Execute multiple operations atomically */
+    transaction(fn: (tx: Transaction) => Promise<void>): Promise<void>;
+    /** Apply a schema migration */
+    migrate(from: number, to: number, migration: MigrationPlan): Promise<void>;
+}
+/**
+ * Buffered SQL + operation produced during a transaction (before commit).
+ */
+interface TransactionBufferedEntry {
+    operation: Operation;
+    commands: Array<{
+        sql: string;
+        params: unknown[];
+    }>;
+    collection: string;
+}
+/**
+ * Batch passed to {@link LocalMutationHandler.commitTransaction} on commit.
+ */
+interface TransactionCommitBatch {
+    entries: TransactionBufferedEntry[];
+    transactionId: string;
+    mutationName?: string;
+}
+interface TransactionCommitResult {
+    operations: Operation[];
+    affectedCollections: Set<string>;
+}
+interface LocalMutationHandler {
+    insert(collection: string, data: Record<string, unknown>): Promise<CollectionRecord>;
+    update(collection: string, id: string, data: Record<string, unknown>): Promise<CollectionRecord>;
+    delete(collection: string, id: string): Promise<void>;
+    /**
+     * Commit a buffered transaction through the unified apply pipeline.
+     * When omitted, the store uses the built-in SQL commit path.
+     */
+    commitTransaction?(batch: TransactionCommitBatch): Promise<TransactionCommitResult>;
+}
+type StoreIsolation = 'shared' | 'per-tab';
+interface StoreConfig {
+    schema: SchemaDefinition;
+    adapter: StorageAdapter;
+    /** Database name used for per-tab node id keys. Defaults to 'kora-db'. */
+    dbName?: string;
+    /**
+     * `shared` (default): one node id per database in `_kora_meta`.
+     * `per-tab`: unique node id per browser tab via sessionStorage.
+     */
+    isolation?: StoreIsolation;
+    /** Optional node ID. If omitted, one is generated or loaded from the database. */
+    nodeId?: string;
+    /** Optional event emitter. When provided, local mutations emit 'operation:created' events. */
+    emitter?: KoraEventEmitter;
+    /** Routes local mutations through a unified apply pipeline when provided. */
+    localMutationHandler?: LocalMutationHandler;
+    /** Called when a reactive query subscription is registered (for sync query subsets). */
+    onQuerySubscribed?: (descriptor: QueryDescriptor) => () => void;
+}
+/**
+ * Operators for where clause conditions.
+ */
+interface WhereOperators {
+    $eq?: unknown;
+    $ne?: unknown;
+    $gt?: number | string;
+    $gte?: number | string;
+    $lt?: number | string;
+    $lte?: number | string;
+    $in?: unknown[];
+}
+/**
+ * Where clause: field name to value (shorthand for $eq) or WhereOperators.
+ */
+type WhereClause = Record<string, unknown | WhereOperators>;
+/**
+ * Order direction for sorting query results.
+ */
+type OrderByDirection = 'asc' | 'desc';
+/**
+ * Order-by clause: field name and optional direction.
+ */
+interface OrderByClause {
+    field: string;
+    direction: OrderByDirection;
+}
+/**
+ * Internal representation of a query to be compiled to SQL.
+ */
+interface QueryDescriptor {
+    collection: string;
+    where: WhereClause;
+    orderBy: OrderByClause[];
+    limit?: number;
+    offset?: number;
+    /** Relation names to include in results (for relational queries). */
+    include?: string[];
+    /** Resolved collection names for included relations (for subscription tracking). */
+    includeCollections?: string[];
+}
+/**
+ * Callback for reactive subscriptions. Receives the current result set.
+ */
+type SubscriptionCallback<T> = (results: T[]) => void;
+/**
+ * Serialized row in the operations log table.
+ */
+interface OperationRow {
+    id: string;
+    node_id: string;
+    type: string;
+    record_id: string;
+    data: string | null;
+    previous_data: string | null;
+    timestamp: string;
+    sequence_number: number;
+    causal_deps: string;
+    schema_version: number;
+}
+/**
+ * Record type returned from collection queries.
+ * Includes the id and mapped metadata fields.
+ */
+interface CollectionRecord {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    [key: string]: unknown;
+}
+
+/**
+ * Internal row shape returned from SQL queries on collection tables.
+ */
+interface RawCollectionRow {
+    id: string;
+    _created_at: number;
+    _updated_at: number;
+    _version?: string;
+    _deleted: number;
+    [key: string]: unknown;
+}
+/**
+ * A registered subscription tracked by the SubscriptionManager.
+ */
+interface Subscription<T = CollectionRecord> {
+    id: string;
+    descriptor: QueryDescriptor;
+    callback: SubscriptionCallback<T>;
+    executeFn: () => Promise<T[]>;
+    lastResults: T[];
+}
+
+/**
+ * Options for applying a remote operation to materialized storage.
+ */
+interface ApplyRemoteOptions {
+    /** When true, a winning remote update clears soft-delete on the row. */
+    reactivateIfDeleted?: boolean;
+}
+/**
+ * Snapshot of a materialized row, including soft-deleted records.
+ */
+interface MaterializedRowSnapshot {
+    /** Deserialized application record (excludes tombstone metadata). */
+    record: CollectionRecord;
+    /** Whether the row is soft-deleted (_deleted = 1). */
+    deleted: boolean;
+}
+/**
+ * Metadata row from _kora_meta table.
+ */
+interface MetaRow {
+    key: string;
+    value: string;
+}
+/**
+ * Version vector row from _kora_version_vector table.
+ */
+interface VersionVectorRow {
+    node_id: string;
+    sequence_number: number;
+}
+
+export type { ApplyRemoteOptions as A, CollectionRecord as C, LocalMutationHandler as L, MigrationPlan as M, OperationRow as O, QueryDescriptor as Q, RawCollectionRow as R, StorageAdapter as S, Transaction as T, VersionVectorRow as V, WhereClause as W, MetaRow as a, Subscription as b, SubscriptionCallback as c, OrderByDirection as d, StoreConfig as e, MaterializedRowSnapshot as f, OrderByClause as g, StoreIsolation as h, TransactionBufferedEntry as i, TransactionCommitBatch as j, TransactionCommitResult as k, WhereOperators as l };