@monlite/core 0.3.0 → 0.6.0

package/dist/index.d.cts

@@ -16,6 +16,39 @@ interface SystemFields {
 }
 /** A stored document: the user's shape plus monlite's system fields. */
 type WithId<T> = T & SystemFields;
+/** SQLite column affinity for a structured-collection field. */
+type ColumnType = "TEXT" | "INTEGER" | "REAL" | "BLOB" | "JSON";
+/** Rich column definition for a structured collection. */
+interface ColumnDef {
+    type: ColumnType;
+    /** Create a secondary index on this column. */
+    index?: boolean;
+    unique?: boolean;
+    notNull?: boolean;
+    /** Default value (string/number literal, or null). */
+    default?: string | number | null;
+    /** Foreign-key target, e.g. `"users(_id)"` or `"users"`. */
+    references?: string;
+}
+/** Map of field name to column type (or full definition). */
+type CollectionSchema = Record<string, ColumnType | ColumnDef>;
+interface CollectionOptions {
+    /**
+     * Declare native SQL columns ("structured" mode). Listed fields become real
+     * typed columns — fast, indexable, joinable — and any other fields overflow
+     * into a JSON column. Omit for schema-free document mode. The CRUD/query API
+     * is identical either way.
+     */
+    schema?: CollectionSchema;
+}
+type CollectionMode = "document" | "structured";
+/** A column as reported by {@link Monlite.$schema}. */
+interface ColumnInfo {
+    name: string;
+    type: string;
+    notNull: boolean;
+    primaryKey: boolean;
+}
 /** Per-field operators, Prisma-style (no `$` prefix). */
 interface FieldFilter<V = any> {
     equals?: V | null;
@@ -34,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>;
@@ -168,6 +206,17 @@ interface MonliteOptions {
      * when installed, otherwise the built-in `node:sqlite` (Node >= 22.5).
      */
     driver?: DriverName;
+    /**
+     * Enable sync metadata (change feed, tombstones, version tracking) so the
+     * database can replicate via `@monlite/sync`. Off by default — adds zero
+     * overhead when disabled.
+     */
+    sync?: boolean;
+    /**
+     * Stable node identity used for last-write-wins tie-breaking. Auto-generated
+     * and persisted in the database on first sync-enabled open if omitted.
+     */
+    nodeId?: string;
     /** Auto-create indexes on frequently-queried JSON paths. Default `true`. */
     autoIndex?: boolean;
     /** Number of times a path must be queried before an index is created. Default `10`. */
@@ -176,35 +225,65 @@ 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;
 }
 
 /**
- * A document collection. Backed by a single SQLite table whose rows store the
- * document as JSON in a `data` column. Created lazily on first write/read.
+ * 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);
+    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 prepareInsert;
+    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, but only for document collections (structured sync is future work). */
+    private get recorder();
     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 across the collection. Array fields
-     * are unwound (each element counts as a value), matching MongoDB's `distinct`.
+     * 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;
@@ -265,6 +344,127 @@ declare class AutoIndexer {
     reset(collection?: string): void;
 }
 
+/**
+ * Versions are LWW (last-write-wins) tokens of the form
+ * `<zero-padded-ms>:<nodeId>` so that plain string comparison yields the
+ * correct ordering: newer wall-clock time wins, ties broken by node id.
+ *
+ * (The design reserves room to swap this for a hybrid logical clock later;
+ * the on-disk column is a plain string, so the format can evolve.)
+ */
+type Version = string;
+/**
+ * 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;
+
+type SyncOp = "upsert" | "delete";
+/** A locally-originated change ready to be pushed to a remote. */
+interface LocalChange {
+    seq: number;
+    collection: string;
+    _id: string;
+    op: SyncOp;
+    version: Version;
+    ts: number;
+    /** Full document (with system fields) for `upsert`; absent for `delete`. */
+    doc?: Record<string, any>;
+}
+/** A change received from a remote, to be applied locally. */
+interface RemoteChange {
+    collection: string;
+    _id: string;
+    op: SyncOp;
+    version: Version;
+    doc?: Record<string, any>;
+}
+type ConflictResolver = (ctx: {
+    collection: string;
+    _id: string;
+    local: {
+        version: Version;
+    };
+    remote: {
+        version: Version;
+        doc?: Record<string, any>;
+    };
+}) => "local" | "remote";
+interface ApplyResult {
+    applied: boolean;
+    conflict: boolean;
+    winner: "local" | "remote" | "none";
+}
+interface SyncStateRow {
+    remote: string;
+    cursor: string | null;
+    lastPullAt: number | null;
+    lastPushSeq: number | null;
+    lastPushAt: number | null;
+}
+interface ConflictRow {
+    collection: string;
+    _id: string;
+    localVersion: Version;
+    remoteVersion: Version;
+    winner: "local" | "remote";
+    ts: number;
+}
+/**
+ * Low-level sync primitives stored alongside the data in the same `.db` file:
+ * an append-only change feed, tombstones, per-remote cursors and a conflict
+ * log. Created only when a database is opened with `{ sync: true }`. The
+ * `@monlite/sync` engine drives this; apps rarely touch it directly.
+ */
+declare class SyncStore {
+    private readonly db;
+    readonly nodeId: string;
+    private versionSeq;
+    constructor(db: Driver, nodeId?: string);
+    private init;
+    private resolveNodeId;
+    /** True if this database tracks sync metadata (always, once constructed). */
+    get enabled(): boolean;
+    /** Append a locally-originated change to the feed. Call inside a write txn. */
+    recordLocal(collection: string, id: string, op: SyncOp, ts: number): Version;
+    /** 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[], limit?: number): LocalChange[];
+    /** Mark the given changes (and any earlier local rows per doc) as pushed. */
+    markPushed(changes: LocalChange[]): void;
+    /**
+     * Apply a remote change, resolving conflicts against the local version.
+     * Remote-applied changes are recorded with `source='remote'` so they are
+     * never pushed back (echo prevention).
+     */
+    applyRemote(change: RemoteChange, resolver?: ConflictResolver): ApplyResult;
+    private applyData;
+    /**
+     * Latest change per document with `seq` greater than the given watermark,
+     * 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[], limit?: number): {
+        changes: RemoteChange[];
+        maxSeq: number;
+    };
+    /**
+     * Enqueue existing documents (created before sync was enabled, or never
+     * recorded) as local upserts so they can be pushed. Idempotent.
+     */
+    seed(collections: string[]): number;
+    getState(remote: string): SyncStateRow;
+    setState(remote: string, patch: Partial<Omit<SyncStateRow, "remote">>): void;
+    private recordConflict;
+    conflicts(): ConflictRow[];
+    private readDoc;
+    private ensureCollTable;
+}
+
 /**
  * A monlite database — a thin document layer over a single SQLite file.
  * Create one with {@link createDb}.
@@ -274,15 +474,25 @@ declare class Monlite {
     readonly driver: Driver;
     /** @internal */
     readonly autoIndexer: AutoIndexer;
+    /** @internal Sync metadata store; present only when `{ sync: true }`. */
+    readonly $sync?: SyncStore;
     private readonly collections;
     private closed;
     constructor(filename: string, options?: MonliteOptions);
+    /** Stable node id for LWW tie-breaking (only when sync is enabled). */
+    get nodeId(): string | undefined;
     /** The underlying native database handle (escape hatch). */
     get sqlite(): any;
     /** Name of the active backend: `"better-sqlite3"` or `"node:sqlite"`. */
     get driverName(): string;
-    /** Get (or lazily create) a typed collection handle. */
-    collection<T = Doc>(name: string): Collection<T>;
+    /**
+     * Get (or lazily create) a typed collection handle. Pass `{ schema }` to make
+     * it a structured collection backed by native SQL columns; omit for the
+     * default schema-free document mode. Options apply only on first access.
+     */
+    collection<T = Doc>(name: string, options?: CollectionOptions): Collection<T>;
+    /** Inspect a collection's physical columns (PRAGMA table_info). */
+    $schema(name: string): Promise<ColumnInfo[]>;
     /** Tagged-template SQL query returning rows. Values are safely parameterized. */
     $queryRaw<R = any>(strings: TemplateStringsArray, ...values: any[]): Promise<R[]>;
     /** Like {@link $queryRaw} but takes a raw SQL string and positional params. */
@@ -314,15 +524,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, Collection, 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, Monlite, MonliteError, type MonliteOptions, MonliteQueryError, type OrderBy, type PreparedStatement, type Select, type SortOrder, type SystemFields, type UpdateArgs, type UpdateData, type UpdateOperators, type UpsertArgs, type WhereInput as WhereClause, type WhereInput, type WithId, createDb, isObjectId, objectId };
+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 };