@monlite/core 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -67,6 +67,11 @@ interface FieldFilter<V = any> {
     has?: any;
     /** Field presence. `true` requires the field to exist, `false` requires absence. */
     exists?: boolean;
+    /**
+     * Case sensitivity for `contains`/`startsWith`/`endsWith`. Default is
+     * case-sensitive; `"insensitive"` matches case-insensitively (ASCII).
+     */
+    mode?: "default" | "insensitive";
 }
 /** A value used directly as a filter is shorthand for `{ equals: value }`. */
 type FilterInput<V> = V | FieldFilter<V>;
@@ -220,6 +225,8 @@ interface MonliteOptions {
     readonly?: boolean;
     /** Use SQLite WAL journal mode for better concurrency. Default `true`. */
     wal?: boolean;
+    /** Milliseconds to wait on a locked database before erroring. Default `5000`. */
+    busyTimeout?: number;
     /** Verbose logger for executed SQL (debugging). */
     verbose?: (sql: string) => void;
 }
@@ -245,6 +252,8 @@ declare class Collection<T = Doc> {
     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;
@@ -256,14 +265,29 @@ 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;
     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>;
     /**
@@ -338,7 +362,12 @@ declare class AutoIndexer {
  * the on-disk column is a plain string, so the format can evolve.)
  */
 type Version = string;
-declare function makeVersion(ts: number, nodeId: string): Version;
+/**
+ * Build a version token. The optional `seq` is a per-node monotonic counter
+ * that makes versions unique even within the same millisecond — important so
+ * that cursor-based pulls (`> version`) never skip a same-timestamp change.
+ */
+declare function makeVersion(ts: number, nodeId: string, seq?: number): Version;
 declare function compareVersions(a: Version, b: Version): number;
 declare function versionTs(v: Version): number;
 
@@ -401,8 +430,10 @@ interface ConflictRow {
  */
 declare class SyncStore {
     private readonly db;
+    private readonly mon?;
     readonly nodeId: string;
-    constructor(db: Driver, nodeId?: string);
+    private versionSeq;
+    constructor(db: Driver, nodeId?: string, mon?: Monlite | undefined);
     private init;
     private resolveNodeId;
     /** True if this database tracks sync metadata (always, once constructed). */
@@ -412,7 +443,7 @@ declare class SyncStore {
     /** Current (latest) version of a document, or null if never recorded. */
     currentVersion(collection: string, id: string): Version | null;
     /** Latest unpushed local change per document (the push queue). */
-    pending(collections?: string[]): LocalChange[];
+    pending(collections?: string[], limit?: number): LocalChange[];
     /** Mark the given changes (and any earlier local rows per doc) as pushed. */
     markPushed(changes: LocalChange[]): void;
     /**
@@ -427,7 +458,7 @@ declare class SyncStore {
      * as RemoteChanges (used when this database acts as a sync *source*, e.g. the
      * monlite-as-remote adapter). Returns the new watermark to resume from.
      */
-    changesSince(seq: number, collections?: string[]): {
+    changesSince(seq: number, collections?: string[], limit?: number): {
         changes: RemoteChange[];
         maxSeq: number;
     };
@@ -441,6 +472,7 @@ declare class SyncStore {
     private recordConflict;
     conflicts(): ConflictRow[];
     private readDoc;
+    private tableExists;
     private ensureCollTable;
 }
 
@@ -503,15 +535,54 @@ declare function createDb(filename: string, options?: MonliteOptions): Monlite;
 
 /** Base error for all monlite-originated failures. */
 declare class MonliteError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
 /** Thrown when a query/update payload is malformed. */
 declare class MonliteQueryError extends MonliteError {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A database constraint was violated (base class for the specific kinds). */
+declare class MonliteConstraintError extends MonliteError {
+    readonly collection?: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        collection?: string;
+    });
+}
+/** A UNIQUE (or primary-key) constraint was violated. */
+declare class MonliteUniqueConstraintError extends MonliteConstraintError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        collection?: string;
+    });
+}
+/** A NOT NULL constraint was violated. */
+declare class MonliteNotNullError extends MonliteConstraintError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        collection?: string;
+    });
+}
+/** A FOREIGN KEY constraint was violated. */
+declare class MonliteForeignKeyError extends MonliteConstraintError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        collection?: string;
+    });
 }
+/**
+ * Normalize a raw driver error (better-sqlite3 `SqliteError` or node:sqlite
+ * error) into a typed {@link MonliteError}. The two backends differ in error
+ * shape, so we sniff both the `code` and the message text.
+ */
+declare function normalizeDriverError(err: unknown, collection?: string): MonliteError;
 
 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, MonliteError, type MonliteOptions, MonliteQueryError, 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, 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 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 };

package/dist/index.d.ts

@@ -67,6 +67,11 @@ interface FieldFilter<V = any> {
     has?: any;
     /** Field presence. `true` requires the field to exist, `false` requires absence. */
     exists?: boolean;
+    /**
+     * Case sensitivity for `contains`/`startsWith`/`endsWith`. Default is
+     * case-sensitive; `"insensitive"` matches case-insensitively (ASCII).
+     */
+    mode?: "default" | "insensitive";
 }
 /** A value used directly as a filter is shorthand for `{ equals: value }`. */
 type FilterInput<V> = V | FieldFilter<V>;
@@ -220,6 +225,8 @@ interface MonliteOptions {
     readonly?: boolean;
     /** Use SQLite WAL journal mode for better concurrency. Default `true`. */
     wal?: boolean;
+    /** Milliseconds to wait on a locked database before erroring. Default `5000`. */
+    busyTimeout?: number;
     /** Verbose logger for executed SQL (debugging). */
     verbose?: (sql: string) => void;
 }
@@ -245,6 +252,8 @@ declare class Collection<T = Doc> {
     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;
@@ -256,14 +265,29 @@ 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;
     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>;
     /**
@@ -338,7 +362,12 @@ declare class AutoIndexer {
  * the on-disk column is a plain string, so the format can evolve.)
  */
 type Version = string;
-declare function makeVersion(ts: number, nodeId: string): Version;
+/**
+ * Build a version token. The optional `seq` is a per-node monotonic counter
+ * that makes versions unique even within the same millisecond — important so
+ * that cursor-based pulls (`> version`) never skip a same-timestamp change.
+ */
+declare function makeVersion(ts: number, nodeId: string, seq?: number): Version;
 declare function compareVersions(a: Version, b: Version): number;
 declare function versionTs(v: Version): number;
 
@@ -401,8 +430,10 @@ interface ConflictRow {
  */
 declare class SyncStore {
     private readonly db;
+    private readonly mon?;
     readonly nodeId: string;
-    constructor(db: Driver, nodeId?: string);
+    private versionSeq;
+    constructor(db: Driver, nodeId?: string, mon?: Monlite | undefined);
     private init;
     private resolveNodeId;
     /** True if this database tracks sync metadata (always, once constructed). */
@@ -412,7 +443,7 @@ declare class SyncStore {
     /** Current (latest) version of a document, or null if never recorded. */
     currentVersion(collection: string, id: string): Version | null;
     /** Latest unpushed local change per document (the push queue). */
-    pending(collections?: string[]): LocalChange[];
+    pending(collections?: string[], limit?: number): LocalChange[];
     /** Mark the given changes (and any earlier local rows per doc) as pushed. */
     markPushed(changes: LocalChange[]): void;
     /**
@@ -427,7 +458,7 @@ declare class SyncStore {
      * as RemoteChanges (used when this database acts as a sync *source*, e.g. the
      * monlite-as-remote adapter). Returns the new watermark to resume from.
      */
-    changesSince(seq: number, collections?: string[]): {
+    changesSince(seq: number, collections?: string[], limit?: number): {
         changes: RemoteChange[];
         maxSeq: number;
     };
@@ -441,6 +472,7 @@ declare class SyncStore {
     private recordConflict;
     conflicts(): ConflictRow[];
     private readDoc;
+    private tableExists;
     private ensureCollTable;
 }
 
@@ -503,15 +535,54 @@ declare function createDb(filename: string, options?: MonliteOptions): Monlite;
 
 /** Base error for all monlite-originated failures. */
 declare class MonliteError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
 }
 /** Thrown when a query/update payload is malformed. */
 declare class MonliteQueryError extends MonliteError {
-    constructor(message: string);
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A database constraint was violated (base class for the specific kinds). */
+declare class MonliteConstraintError extends MonliteError {
+    readonly collection?: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        collection?: string;
+    });
+}
+/** A UNIQUE (or primary-key) constraint was violated. */
+declare class MonliteUniqueConstraintError extends MonliteConstraintError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        collection?: string;
+    });
+}
+/** A NOT NULL constraint was violated. */
+declare class MonliteNotNullError extends MonliteConstraintError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        collection?: string;
+    });
+}
+/** A FOREIGN KEY constraint was violated. */
+declare class MonliteForeignKeyError extends MonliteConstraintError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        collection?: string;
+    });
 }
+/**
+ * Normalize a raw driver error (better-sqlite3 `SqliteError` or node:sqlite
+ * error) into a typed {@link MonliteError}. The two backends differ in error
+ * shape, so we sniff both the `code` and the message text.
+ */
+declare function normalizeDriverError(err: unknown, collection?: string): MonliteError;
 
 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, MonliteError, type MonliteOptions, MonliteQueryError, 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, 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 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 };