@monlite/core 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,9 +1,134 @@
+/**
+ * A collection. In **document** mode (default) every document is stored as JSON
+ * in a `data` column — schema-free. In **structured** mode (when a `schema` is
+ * given) the listed fields become real, typed SQL columns (fast, indexable,
+ * joinable) while any other fields overflow into a JSON `data` column. The CRUD
+ * and query API is identical in both modes.
+ */
+declare class Collection<T = Doc> {
+    private readonly mon;
+    readonly name: string;
+    readonly mode: CollectionMode;
+    private initialized;
+    private readonly columnDefs;
+    private readonly columnOrder;
+    /** Declared native columns (empty in document mode). */
+    private readonly columns;
+    private readonly jsonColumns;
+    private insertSqlCache?;
+    private readonly trackPath;
+    constructor(mon: Monlite, name: string, options?: CollectionOptions);
+    private get db();
+    /** Run a DB operation, normalizing driver errors into typed MonliteErrors. */
+    private guard;
+    /** Native column names declared for this collection (structured mode). */
+    get columnNames(): string[];
+    private ensureTable;
+    private columnDdl;
+    /** Auto-additive migration: add declared columns missing from an existing table. */
+    private migrateColumns;
+    private rowToDoc;
+    private encodeColumn;
+    private insertColumns;
+    private insertSql;
+    /** Split an input document into a row aligned with `insertColumns()`. */
+    private buildInsert;
+    /** Build the `SET` clause + values to persist an updated document. */
+    private buildUpdateSet;
+    /** Sync store for recording local changes (both document and structured). */
+    private get recorder();
+    /** @internal Read a full document by id (mode-aware), synchronously. */
+    getRaw(id: string): WithId<T> | null;
+    /**
+     * @internal Apply a remote change to storage WITHOUT recording it to the
+     * change feed (the sync store records the `remote` feed row itself). Used by
+     * `@monlite/sync` so structured collections sync correctly through the same
+     * column/overflow split as local writes.
+     */
+    applyRemoteWrite(op: "upsert" | "delete", id: string, doc: Record<string, any> | undefined, ts: number): void;
+    /** @internal Notify reactivity watchers and plugins that documents changed. */
+    private afterWrite;
+    create(args: CreateArgs<T>): Promise<WithId<T>>;
+    createMany(args: CreateManyArgs<T>): Promise<{
+        count: number;
+    }>;
+    private buildFindSql;
+    /** @internal Synchronous core of findMany (used by reactivity). */
+    findManyCore(args?: FindManyArgs<T>): WithId<T>[];
+    /** @internal Synchronous core of exists (used by reactivity). */
+    existsCore(where: WhereInput<T> | undefined): boolean;
+    findMany(args?: FindManyArgs<T>): Promise<WithId<T>[]>;
+    findFirst(args?: FindFirstArgs<T>): Promise<WithId<T> | null>;
+    /** Alias of {@link findFirst} for Prisma familiarity. */
+    findUnique(args?: FindFirstArgs<T>): Promise<WithId<T> | null>;
+    /** Like {@link findFirst} but throws if no document matches. */
+    findFirstOrThrow(args?: FindFirstArgs<T>): Promise<WithId<T>>;
+    /** True if at least one document matches. */
+    exists(where?: WhereInput<T>): Promise<boolean>;
+    /**
+     * Subscribe to a live query. The callback fires immediately with the current
+     * results (`type: "init"`) and again whenever a change affects the result set
+     * (row-level: only relevant changes trigger a recompute). Includes changes
+     * applied by `@monlite/sync`.
+     */
+    watch(args: FindManyArgs<T> | undefined, cb: (event: LiveEvent<T>) => void): WatchHandle<T>;
+    /** Show SQLite's query plan for a `findMany`, and whether it uses an index. */
+    explain(args?: FindManyArgs<T>): Promise<ExplainResult>;
+    findById(id: string): Promise<WithId<T> | null>;
+    count(args?: CountArgs<T>): Promise<number>;
+    /**
+     * Return the distinct values of a field. Array fields stored in JSON are
+     * unwound (each element counts as a value), matching MongoDB's `distinct`.
+     */
+    distinct(field: string, where?: WhereInput<T>): Promise<any[]>;
+    private runUpdate;
+    update(args: UpdateArgs<T>): Promise<WithId<T> | null>;
+    updateMany(args: UpdateArgs<T>): Promise<{
+        count: number;
+    }>;
+    upsert(args: UpsertArgs<T>): Promise<WithId<T>>;
+    private runDelete;
+    delete(args: DeleteArgs<T>): Promise<WithId<T> | null>;
+    deleteMany(args?: DeleteArgs<T>): Promise<{
+        count: number;
+    }>;
+    aggregate(args?: AggregateArgs<T>): Promise<AggregateResult>;
+    groupBy(args: GroupByArgs<T>): Promise<GroupByResult[]>;
+}
+
+/** Documents that changed in a single write, delivered to `afterWrite`. */
+interface PluginChange {
+    collection: string;
+    ids: string[];
+}
+/**
+ * A monlite plugin. Plugins keep `@monlite/core` lean — heavier or optional
+ * capabilities (full-text search, vector, encryption) live in their own
+ * packages and hook in here.
+ */
+interface MonlitePlugin {
+    name: string;
+    /** Called once when the database opens (e.g. to create auxiliary tables). */
+    init?(db: Monlite): void;
+    /**
+     * Called synchronously after every committed write (including changes applied
+     * by `@monlite/sync`), so derived state like a search index stays in sync.
+     */
+    afterWrite?(db: Monlite, change: PluginChange): void;
+    /**
+     * Methods to attach to every collection handle (e.g. `search`). The impl
+     * receives the collection as its first argument, then the caller's arguments.
+     */
+    collectionMethods?: Record<string, (collection: Collection<any>, ...args: any[]) => any>;
+}
+
 /**
  * Public type surface for monlite.
  *
  * Documents are plain objects. monlite adds three system fields to every
  * stored document: `_id`, `created_at`, and `updated_at`.
  */
+
 /** A free-form document. */
 type Doc = Record<string, any>;
 /** System fields monlite manages on every document. */
@@ -49,6 +174,38 @@ interface ColumnInfo {
     notNull: boolean;
     primaryKey: boolean;
 }
+/** An update delivered to a `watch()` subscriber. */
+interface LiveEvent<T = Doc> {
+    /** `"init"` is the first delivery; `"change"` for every update after. */
+    type: "init" | "change";
+    /** The full current result set. */
+    results: WithId<T>[];
+    /** Documents that entered the result set since the last event. */
+    added: WithId<T>[];
+    /** Documents that left the result set. */
+    removed: WithId<T>[];
+    /** Documents still in the set whose contents changed. */
+    changed: WithId<T>[];
+}
+/** Handle returned by `collection.watch()`. */
+interface WatchHandle<T = Doc> {
+    /** The current result set (kept up to date). */
+    readonly results: WithId<T>[];
+    /** Stop receiving updates. */
+    stop(): void;
+}
+/** Result of `collection.explain()`. */
+interface ExplainResult {
+    sql: string;
+    /** Whether SQLite's planner uses an index (vs a full scan). */
+    usesIndex: boolean;
+    /** Raw EXPLAIN QUERY PLAN rows. */
+    plan: Array<{
+        id: number;
+        parent: number;
+        detail: string;
+    }>;
+}
 /** Per-field operators, Prisma-style (no `$` prefix). */
 interface FieldFilter<V = any> {
     equals?: V | null;
@@ -206,6 +363,8 @@ interface MonliteOptions {
      * when installed, otherwise the built-in `node:sqlite` (Node >= 22.5).
      */
     driver?: DriverName;
+    /** Opt-in plugins (e.g. `@monlite/fts`). */
+    plugins?: MonlitePlugin[];
     /**
      * Enable sync metadata (change feed, tombstones, version tracking) so the
      * database can replicate via `@monlite/sync`. Off by default — adds zero
@@ -231,85 +390,6 @@ interface MonliteOptions {
     verbose?: (sql: string) => void;
 }
 
-/**
- * A collection. In **document** mode (default) every document is stored as JSON
- * in a `data` column — schema-free. In **structured** mode (when a `schema` is
- * given) the listed fields become real, typed SQL columns (fast, indexable,
- * joinable) while any other fields overflow into a JSON `data` column. The CRUD
- * and query API is identical in both modes.
- */
-declare class Collection<T = Doc> {
-    private readonly mon;
-    readonly name: string;
-    readonly mode: CollectionMode;
-    private initialized;
-    private readonly columnDefs;
-    private readonly columnOrder;
-    /** Declared native columns (empty in document mode). */
-    private readonly columns;
-    private readonly jsonColumns;
-    private insertSqlCache?;
-    private readonly trackPath;
-    constructor(mon: Monlite, name: string, options?: CollectionOptions);
-    private get db();
-    /** Run a DB operation, normalizing driver errors into typed MonliteErrors. */
-    private guard;
-    /** Native column names declared for this collection (structured mode). */
-    get columnNames(): string[];
-    private ensureTable;
-    private rowToDoc;
-    private encodeColumn;
-    private insertColumns;
-    private insertSql;
-    /** Split an input document into a row aligned with `insertColumns()`. */
-    private buildInsert;
-    /** Build the `SET` clause + values to persist an updated document. */
-    private buildUpdateSet;
-    /** Sync store for recording local changes (both document and structured). */
-    private get recorder();
-    /** @internal Read a full document by id (mode-aware), synchronously. */
-    getRaw(id: string): WithId<T> | null;
-    /**
-     * @internal Apply a remote change to storage WITHOUT recording it to the
-     * change feed (the sync store records the `remote` feed row itself). Used by
-     * `@monlite/sync` so structured collections sync correctly through the same
-     * column/overflow split as local writes.
-     */
-    applyRemoteWrite(op: "upsert" | "delete", id: string, doc: Record<string, any> | undefined, ts: number): void;
-    create(args: CreateArgs<T>): Promise<WithId<T>>;
-    createMany(args: CreateManyArgs<T>): Promise<{
-        count: number;
-    }>;
-    findMany(args?: FindManyArgs<T>): Promise<WithId<T>[]>;
-    findFirst(args?: FindFirstArgs<T>): Promise<WithId<T> | null>;
-    /** Alias of {@link findFirst} for Prisma familiarity. */
-    findUnique(args?: FindFirstArgs<T>): Promise<WithId<T> | null>;
-    /** Like {@link findFirst} but throws if no document matches. */
-    findFirstOrThrow(args?: FindFirstArgs<T>): Promise<WithId<T>>;
-    /** True if at least one document matches. */
-    exists(where?: WhereInput<T>): Promise<boolean>;
-    findById(id: string): Promise<WithId<T> | null>;
-    count(args?: CountArgs<T>): Promise<number>;
-    /**
-     * Return the distinct values of a field. Array fields stored in JSON are
-     * unwound (each element counts as a value), matching MongoDB's `distinct`.
-     */
-    distinct(field: string, where?: WhereInput<T>): Promise<any[]>;
-    private runUpdate;
-    update(args: UpdateArgs<T>): Promise<WithId<T> | null>;
-    updateMany(args: UpdateArgs<T>): Promise<{
-        count: number;
-    }>;
-    upsert(args: UpsertArgs<T>): Promise<WithId<T>>;
-    private runDelete;
-    delete(args: DeleteArgs<T>): Promise<WithId<T> | null>;
-    deleteMany(args?: DeleteArgs<T>): Promise<{
-        count: number;
-    }>;
-    aggregate(args?: AggregateArgs<T>): Promise<AggregateResult>;
-    groupBy(args: GroupByArgs<T>): Promise<GroupByResult[]>;
-}
-
 /**
  * The minimal SQLite driver surface monlite needs. Implemented by both the
  * better-sqlite3 and the built-in node:sqlite backends so the rest of the
@@ -476,6 +556,46 @@ declare class SyncStore {
     private ensureCollTable;
 }
 
+/** Minimal query surface a {@link LiveQuery} needs (satisfied by Collection). */
+interface Queryable<T> {
+    readonly name: string;
+    findManyCore(args: FindManyArgs<T>): WithId<T>[];
+    existsCore(where: WhereInput<T> | undefined): boolean;
+}
+/**
+ * A live query. Holds the current result set and recomputes only when a changed
+ * row is actually relevant to it (row-level matching): either the row is already
+ * in the result set, or it now matches the filter.
+ */
+declare class LiveQuery<T = Doc> {
+    private readonly source;
+    private readonly args;
+    private readonly cb;
+    results: WithId<T>[];
+    stopped: boolean;
+    private ids;
+    constructor(source: Queryable<T>, args: FindManyArgs<T>, cb: (event: LiveEvent<T>) => void);
+    /** Called by the Reactor with the ids that changed this tick. */
+    notify(changedIds: Set<string>): void;
+    private isRelevant;
+    private recompute;
+}
+/**
+ * In-process reactivity hub. Collections emit `(collection, ids)` after each
+ * write; the reactor coalesces them per microtask and notifies live queries.
+ */
+declare class Reactor {
+    private readonly byCollection;
+    private readonly pending;
+    private flushScheduled;
+    hasWatchers(collection: string): boolean;
+    register(collection: string, lq: LiveQuery<any>): void;
+    unregister(collection: string, lq: LiveQuery<any>): void;
+    /** Record that documents changed; schedule a notification flush. */
+    emit(collection: string, ids: string[]): void;
+    private flush;
+}
+
 /**
  * A monlite database — a thin document layer over a single SQLite file.
  * Create one with {@link createDb}.
@@ -485,11 +605,16 @@ declare class Monlite {
     readonly driver: Driver;
     /** @internal */
     readonly autoIndexer: AutoIndexer;
+    /** @internal Reactivity hub for `collection.watch()`. */
+    readonly reactor: Reactor;
     /** @internal Sync metadata store; present only when `{ sync: true }`. */
     readonly $sync?: SyncStore;
     private readonly collections;
+    private readonly plugins;
     private closed;
     constructor(filename: string, options?: MonliteOptions);
+    /** @internal Notify plugins that documents changed (post-commit). */
+    firePluginAfterWrite(collection: string, ids: string[]): void;
     /** Stable node id for LWW tie-breaking (only when sync is enabled). */
     get nodeId(): string | undefined;
     /** The underlying native database handle (escape hatch). */
@@ -523,6 +648,11 @@ declare class Monlite {
     $drop(name: string): Promise<void>;
     /** Drop every collection in the database. */
     $dropAll(): Promise<void>;
+    /**
+     * Write a consistent on-disk snapshot of the database to `path` (via
+     * `VACUUM INTO`). The destination file must not already exist.
+     */
+    backup(path: string): Promise<void>;
     /** Close the underlying SQLite connection. */
     $disconnect(): Promise<void>;
     private assertOpen;
@@ -585,4 +715,4 @@ declare function objectId(): string;
 /** True when a value looks like a monlite/ObjectId id (24 hex chars). */
 declare function isObjectId(value: unknown): value is string;
 
-export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LocalChange, Monlite, MonliteConstraintError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PreparedStatement, type RemoteChange, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };
+export { type AggregateArgs, type AggregateResult, type ApplyResult, Collection, type CollectionMode, type CollectionOptions, type CollectionSchema, type ColumnDef, type ColumnInfo, type ColumnType, type ConflictResolver, type ConflictRow, type CountArgs, type CreateArgs, type CreateManyArgs, Monlite as Db, type DeleteArgs, type Doc, type Driver, type DriverName, type ExplainResult, type FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, type HavingComparison, type HavingInput, type LiveEvent, type LocalChange, Monlite, MonliteConstraintError, MonliteError, MonliteForeignKeyError, MonliteNotNullError, type MonliteOptions, type MonlitePlugin, MonliteQueryError, MonliteUniqueConstraintError, type OrderBy, type PluginChange, type PreparedStatement, type RemoteChange, type Select, type SortOrder, type SyncOp, type SyncStateRow, SyncStore, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type Version, type WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };