@monlite/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,271 @@
+import { Database } from 'better-sqlite3';
+
+/**
+ * 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. */
+interface SystemFields {
+    _id: string;
+    /** Unix epoch milliseconds. */
+    created_at: number;
+    /** Unix epoch milliseconds. */
+    updated_at: number;
+}
+/** A stored document: the user's shape plus monlite's system fields. */
+type WithId<T> = T & SystemFields;
+/** Per-field operators, Prisma-style (no `$` prefix). */
+interface FieldFilter<V = any> {
+    equals?: V | null;
+    not?: V | null;
+    in?: V[];
+    notIn?: V[];
+    lt?: V;
+    lte?: V;
+    gt?: V;
+    gte?: V;
+    /** Substring match on strings, or element membership on arrays. */
+    contains?: V extends string ? string : any;
+    startsWith?: string;
+    endsWith?: string;
+    /** Explicit array element membership. */
+    has?: any;
+    /** Field presence. `true` requires the field to exist, `false` requires absence. */
+    exists?: boolean;
+}
+/** A value used directly as a filter is shorthand for `{ equals: value }`. */
+type FilterInput<V> = V | FieldFilter<V>;
+/**
+ * Where input. Known fields are typed from `T`; nested paths can also be
+ * addressed with dot notation (e.g. `"address.city"`).
+ */
+type WhereInput<T = Doc> = {
+    [K in keyof T]?: FilterInput<T[K]>;
+} & {
+    _id?: FilterInput<string>;
+    created_at?: FilterInput<number>;
+    updated_at?: FilterInput<number>;
+    AND?: WhereInput<T> | WhereInput<T>[];
+    OR?: WhereInput<T> | WhereInput<T>[];
+    NOT?: WhereInput<T> | WhereInput<T>[];
+} & {
+    [path: string]: any;
+};
+/** Mongo-inspired update operators. */
+interface UpdateOperators {
+    $set?: Record<string, any>;
+    $unset?: Record<string, true | 1>;
+    $inc?: Record<string, number>;
+    $push?: Record<string, any>;
+    $pull?: Record<string, any>;
+}
+/**
+ * Update payload. Either a plain object (shallow-merged into the document)
+ * or an object using update operators. The two forms cannot be mixed.
+ */
+type UpdateData<T = Doc> = (Partial<T> & Record<string, any>) | UpdateOperators;
+type SortOrder = "asc" | "desc";
+type OrderBy<T = Doc> = ({
+    [K in keyof T]?: SortOrder;
+} & {
+    [path: string]: SortOrder;
+}) | Array<{
+    [path: string]: SortOrder;
+}>;
+type Select<T = Doc> = {
+    [K in keyof T]?: boolean;
+} & {
+    [path: string]: boolean;
+};
+interface FindManyArgs<T = Doc> {
+    where?: WhereInput<T>;
+    orderBy?: OrderBy<T>;
+    select?: Select<T>;
+    skip?: number;
+    take?: number;
+}
+interface FindFirstArgs<T = Doc> {
+    where?: WhereInput<T>;
+    orderBy?: OrderBy<T>;
+    select?: Select<T>;
+    skip?: number;
+}
+interface CreateArgs<T = Doc> {
+    data: Partial<T> & Record<string, any>;
+}
+interface CreateManyArgs<T = Doc> {
+    data: Array<Partial<T> & Record<string, any>>;
+}
+interface UpdateArgs<T = Doc> {
+    where: WhereInput<T>;
+    data: UpdateData<T>;
+}
+interface UpsertArgs<T = Doc> {
+    where: WhereInput<T>;
+    create: Partial<T> & Record<string, any>;
+    update: UpdateData<T>;
+}
+interface DeleteArgs<T = Doc> {
+    where: WhereInput<T>;
+}
+interface CountArgs<T = Doc> {
+    where?: WhereInput<T>;
+}
+/** Map of `field -> true` selecting which fields an accumulator applies to. */
+type FieldSelection = Record<string, boolean>;
+interface AggregateArgs<T = Doc> {
+    where?: WhereInput<T>;
+    _count?: boolean;
+    _sum?: FieldSelection;
+    _avg?: FieldSelection;
+    _min?: FieldSelection;
+    _max?: FieldSelection;
+}
+interface AggregateResult {
+    _count?: number;
+    _sum?: Record<string, number | null>;
+    _avg?: Record<string, number | null>;
+    _min?: Record<string, any>;
+    _max?: Record<string, any>;
+}
+interface GroupByArgs<T = Doc> {
+    by: string[];
+    where?: WhereInput<T>;
+    _count?: boolean;
+    _sum?: FieldSelection;
+    _avg?: FieldSelection;
+    _min?: FieldSelection;
+    _max?: FieldSelection;
+    orderBy?: Record<string, SortOrder>;
+    skip?: number;
+    take?: number;
+}
+type GroupByResult = Record<string, any>;
+interface MonliteOptions {
+    /** 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`. */
+    autoIndexAfter?: number;
+    /** Open the database read-only. Default `false`. */
+    readonly?: boolean;
+    /** Use SQLite WAL journal mode for better concurrency. Default `true`. */
+    wal?: boolean;
+    /** 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.
+ */
+declare class Collection<T = Doc> {
+    private readonly mon;
+    readonly name: string;
+    private initialized;
+    private readonly trackPath;
+    constructor(mon: Monlite, name: string);
+    private get db();
+    private ensureTable;
+    private rowToDoc;
+    private prepareInsert;
+    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>;
+    findById(id: string): Promise<WithId<T> | null>;
+    count(args?: CountArgs<T>): Promise<number>;
+    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[]>;
+}
+
+/**
+ * Tracks which JSON paths are queried per collection and silently creates a
+ * SQLite expression index once a path crosses the configured threshold.
+ */
+declare class AutoIndexer {
+    private readonly db;
+    private readonly enabled;
+    private readonly threshold;
+    private counts;
+    private created;
+    constructor(db: Database, enabled: boolean, threshold: number);
+    track(collection: string, path: string): void;
+    private create;
+    /** Forget tracking for a collection (or everything when omitted). */
+    reset(collection?: string): void;
+}
+
+/**
+ * A monlite database — a thin document layer over a single SQLite file.
+ * Create one with {@link createDb}.
+ */
+declare class Monlite {
+    /** The underlying better-sqlite3 connection (escape hatch). */
+    readonly sqlite: Database;
+    /** @internal */
+    readonly autoIndexer: AutoIndexer;
+    private readonly collections;
+    private closed;
+    constructor(filename: string, options?: MonliteOptions);
+    /** Get (or lazily create) a typed collection handle. */
+    collection<T = Doc>(name: string): Collection<T>;
+    /** 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. */
+    $queryRawUnsafe<R = any>(sql: string, ...params: any[]): Promise<R[]>;
+    /** Tagged-template SQL statement returning the number of affected rows. */
+    $executeRaw(strings: TemplateStringsArray, ...values: any[]): Promise<number>;
+    /** Like {@link $executeRaw} but takes a raw SQL string and positional params. */
+    $executeRawUnsafe(sql: string, ...params: any[]): Promise<number>;
+    /**
+     * Run a function inside a synchronous SQLite transaction. If it throws, the
+     * transaction is rolled back.
+     */
+    $transaction<R>(fn: (db: this) => R): Promise<R>;
+    /** List all collection (table) names. */
+    $collections(): Promise<string[]>;
+    /** Drop a collection and all of its data. */
+    $drop(name: string): Promise<void>;
+    /** Drop every collection in the database. */
+    $dropAll(): Promise<void>;
+    /** Close the underlying SQLite connection. */
+    $disconnect(): Promise<void>;
+    private assertOpen;
+}
+/**
+ * Open (or create) a monlite database backed by a single SQLite file.
+ * Use `":memory:"` for an in-memory database.
+ */
+declare function createDb(filename: string, options?: MonliteOptions): Monlite;
+
+/** Base error for all monlite-originated failures. */
+declare class MonliteError extends Error {
+    constructor(message: string);
+}
+/** Thrown when a query/update payload is malformed. */
+declare class MonliteQueryError extends MonliteError {
+    constructor(message: string);
+}
+
+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 FieldFilter, type FieldSelection, type FilterInput, type FindFirstArgs, type FindManyArgs, type GroupByArgs, type GroupByResult, Monlite, MonliteError, type MonliteOptions, MonliteQueryError, type OrderBy, 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 };