@monlite/core 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -49,6 +49,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;
@@ -257,6 +289,9 @@ declare class Collection<T = Doc> {
     /** 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;
@@ -265,12 +300,28 @@ declare class Collection<T = Doc> {
     private buildInsert;
     /** Build the `SET` clause + values to persist an updated document. */
     private buildUpdateSet;
-    /** Sync store, but only for document collections (structured sync is future work). */
+    /** 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 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. */
@@ -279,6 +330,15 @@ declare class Collection<T = Doc> {
     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>;
     /**
@@ -421,9 +481,10 @@ interface ConflictRow {
  */
 declare class SyncStore {
     private readonly db;
+    private readonly mon?;
     readonly nodeId: string;
     private versionSeq;
-    constructor(db: Driver, nodeId?: string);
+    constructor(db: Driver, nodeId?: string, mon?: Monlite | undefined);
     private init;
     private resolveNodeId;
     /** True if this database tracks sync metadata (always, once constructed). */
@@ -462,9 +523,50 @@ declare class SyncStore {
     private recordConflict;
     conflicts(): ConflictRow[];
     private readDoc;
+    private tableExists;
     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}.
@@ -474,6 +576,8 @@ 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;
@@ -512,6 +616,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;
@@ -574,4 +683,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, 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 WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };

package/dist/index.d.ts

@@ -49,6 +49,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;
@@ -257,6 +289,9 @@ declare class Collection<T = Doc> {
     /** 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;
@@ -265,12 +300,28 @@ declare class Collection<T = Doc> {
     private buildInsert;
     /** Build the `SET` clause + values to persist an updated document. */
     private buildUpdateSet;
-    /** Sync store, but only for document collections (structured sync is future work). */
+    /** 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 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. */
@@ -279,6 +330,15 @@ declare class Collection<T = Doc> {
     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>;
     /**
@@ -421,9 +481,10 @@ interface ConflictRow {
  */
 declare class SyncStore {
     private readonly db;
+    private readonly mon?;
     readonly nodeId: string;
     private versionSeq;
-    constructor(db: Driver, nodeId?: string);
+    constructor(db: Driver, nodeId?: string, mon?: Monlite | undefined);
     private init;
     private resolveNodeId;
     /** True if this database tracks sync metadata (always, once constructed). */
@@ -462,9 +523,50 @@ declare class SyncStore {
     private recordConflict;
     conflicts(): ConflictRow[];
     private readDoc;
+    private tableExists;
     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}.
@@ -474,6 +576,8 @@ 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;
@@ -512,6 +616,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;
@@ -574,4 +683,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, 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 WatchHandle, type WhereInput as WhereClause, type WhereInput, type WithId, compareVersions, createDb, isObjectId, makeVersion, normalizeDriverError, objectId, versionTs };