@type32/tauri-sqlite-orm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wilson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+## tauri-sqlite-orm
+
+A Drizzle-like TypeScript ORM tailored for Tauri v2's `@tauri-apps/plugin-sql` (SQLite). Plug-and-play for Nuxt/Tauri apps: define schema in TS, run tracked migrations, and query with a soft-relations API.
+
+### Install
+
+```bash
+pnpm add tauri-sqlite-orm @tauri-apps/plugin-sql
+```
+
+Make sure the SQL plugin is registered on the Rust side (see Tauri docs).
+
+### Quick start
+
+```ts
+import {
+  initDb,
+  db,
+  defineTable,
+  integer,
+  text,
+  relations,
+} from "tauri-sqlite-orm";
+
+await initDb("sqlite:app.db");
+
+export const users = defineTable("users", {
+  id: integer("id", { isPrimaryKey: true, autoIncrement: true }).primaryKey({
+    autoIncrement: true,
+  }),
+  name: text("name").notNull(),
+  email: text("email"),
+});
+
+export const posts = defineTable("posts", {
+  id: integer("id", { isPrimaryKey: true }).primaryKey(),
+  content: text("content"),
+  authorId: integer("author_id"),
+});
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+
+db.configure({ users, posts }, { users: usersRelations });
+await db.migrateConfigured({ name: "init:users,posts" });
+
+// Create
+await db
+  .insert(users)
+  .values({ name: "Dan", email: "dan@example.com" })
+  .execute();
+
+// Query with relations (join-based when flat)
+const res = await db.query.users.findMany({
+  with: { posts: true },
+  join: true,
+});
+```
+
+### Schema builder
+
+Chainable, Drizzle-style:
+
+```ts
+import {
+  defineTable,
+  integer,
+  text,
+  real,
+  blob,
+  numeric,
+  sql,
+} from "tauri-sqlite-orm";
+
+type Data = { foo: string; bar: number };
+
+export const example = defineTable("example", {
+  id: integer("id", { isPrimaryKey: true, autoIncrement: true }).primaryKey({
+    autoIncrement: true,
+  }),
+  isActive: integer("is_active", { mode: "boolean" }),
+  createdAt: integer("created_at", { mode: "timestamp" }).default(
+    sql`(strftime('%s','now'))`
+  ),
+  rating: real("rating"),
+  status: text("status", { enum: ["active", "inactive"] as const }),
+  name: text("name").notNull().default("Anonymous"),
+  data: blob("data"),
+  jsonField: blob("json_field", { mode: "json" }).$type<Data>(),
+  bigCounter: blob("big_counter", { mode: "bigint" }),
+  valueNumeric: numeric("value_numeric"),
+  valueNumericNum: numeric("value_numeric_num", { mode: "number" }),
+  valueNumericBig: numeric("value_numeric_big", { mode: "bigint" }),
+});
+
+// Foreign key
+export const posts = defineTable("posts", {
+  id: integer("id", { isPrimaryKey: true }).primaryKey(),
+  userId: integer("user_id")
+    .references(() => users.id, { onDelete: "cascade" })
+    .notNull(),
+});
+```
+
+### Migrations
+
+Tracked simple migrations are part of the ORM instance:
+
+```ts
+// one-off for specific tables
+await db.migrate([users, posts], { name: "init:users,posts" });
+
+// or using configured schema
+await db.migrateConfigured({ name: "init:users,posts" });
+```
+
+DDL emitted respects: primaryKey + autoIncrement, notNull, default(value or sql), references (with onDelete/onUpdate).
+
+### CRUD (Drizzle-like builders)
+
+```ts
+// Insert
+await db.insert(users).values({ name: "Alice" }).execute();
+await db
+  .insert(users)
+  .values([{ name: "A" }, { name: "B" }])
+  .execute();
+
+// Update
+import { eq } from "tauri-sqlite-orm";
+await db
+  .update(users)
+  .set({ email: "new@mail.com" })
+  .where(eq(users.id, 1))
+  .execute();
+
+// Delete
+await db.delete(users).where(eq(users.id, 2)).execute();
+```
+
+### Query API (relations)
+
+Auto-generated with `db.configure(tables, relations?)`:
+
+```ts
+// Flat relations with join
+const usersWithPosts = await db.query.users.findMany({
+  with: { posts: true },
+  join: true,
+  where: { id: 1 },
+  orderBy: ["users.id ASC"],
+  limit: 10,
+  offset: 0,
+  columns: { id: true, name: true },
+});
+
+// Nested relations (batched loader)
+const nested = await db.query.users.findMany({
+  with: {
+    posts: {
+      with: { comments: true },
+      columns: ["id", "content"],
+    },
+  },
+});
+```
+
+Notes:
+
+- `where` accepts SQL helpers (eq, lt, gte, like) or object map.
+- `columns` accepts string[] or object map of base table columns.
+- `join: true` only for one-level `with` (flat). Nested uses batched selects.
+
+### SQL helpers
+
+```ts
+import { eq, ne, gt, gte, lt, lte, like, asc, desc } from "tauri-sqlite-orm";
+db.query.posts.findMany({
+  where: eq(posts.authorId, 1),
+  orderBy: [asc(posts.id)],
+});
+```
+
+### Nuxt + Tauri usage
+
+Initialize in a client plugin and ensure `initDb()` runs once:
+
+```ts
+// plugins/orm.client.ts
+import { initDb, db } from "tauri-sqlite-orm";
+import { users, posts, usersRelations } from "@/lib/schema";
+
+export default defineNuxtPlugin(async () => {
+  await initDb("sqlite:app.db");
+  db.configure({ users, posts }, { users: usersRelations });
+  await db.migrateConfigured({ name: "init:users,posts" });
+});
+```
+
+### Roadmap
+
+- Aliasing helpers and typed orderBy (asc(users.id)) for findMany
+- Unique(), check(), composite primary/unique constraints
+- Insert returning / batch returning (where feasible)
+
+### License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,193 @@
+import Database from '@tauri-apps/plugin-sql';
+
+/**
+ * Initializes the database connection. This must be called once at the start of your application.
+ * @param dbPath The path to the database file, e.g., 'sqlite:mydatabase.db'
+ * @returns The database instance.
+ */
+declare function initDb(dbPath: string): Promise<Database>;
+/**
+ * Gets the singleton database instance.
+ * @throws If `initDb` has not been called.
+ * @returns The database instance.
+ */
+declare function getDb(): Database;
+
+type UpdateDeleteAction = "cascade" | "restrict" | "no action" | "set null" | "set default";
+interface SQLExpression {
+    raw: string;
+}
+declare function sql(strings: TemplateStringsArray, ...values: any[]): SQLExpression;
+interface Column<T = any> {
+    name: string;
+    type: "TEXT" | "INTEGER" | "REAL" | "BLOB" | "NUMERIC";
+    isPrimaryKey?: boolean;
+    autoIncrement?: boolean;
+    isNotNull?: boolean;
+    defaultValue?: T | SQLExpression;
+    references?: {
+        table: string;
+        column: string;
+        onDelete?: UpdateDeleteAction;
+        onUpdate?: UpdateDeleteAction;
+    };
+    enumValues?: readonly string[];
+    mode?: string;
+    _dataType: T;
+    /**
+     * Populated by defineTable so we can reason about relations and aliasing.
+     */
+    tableName?: string;
+}
+type ColumnBuilder<T> = Column<T> & {
+    primaryKey: (opts?: {
+        autoIncrement?: boolean;
+    }) => ColumnBuilder<T>;
+    notNull: () => ColumnBuilder<T>;
+    default: (value: T | SQLExpression) => ColumnBuilder<T>;
+    $type: <U>() => ColumnBuilder<U>;
+    references: (target: () => Column<any>, actions?: {
+        onDelete?: UpdateDeleteAction;
+        onUpdate?: UpdateDeleteAction;
+    }) => ColumnBuilder<T>;
+};
+declare function text<TEnum extends string>(name: string, config?: {
+    isPrimaryKey?: boolean;
+    enum?: readonly TEnum[];
+}): ColumnBuilder<TEnum extends string ? TEnum : string>;
+declare function integer(name: string, config?: {
+    isPrimaryKey?: boolean;
+    mode?: "number" | "boolean" | "timestamp";
+    autoIncrement?: boolean;
+}): ColumnBuilder<number | boolean | Date>;
+declare function real(name: string): ColumnBuilder<number>;
+declare function blob(name: string, config?: {
+    mode?: "json" | "bigint";
+}): ColumnBuilder<unknown | bigint | Uint8Array>;
+declare function numeric(name: string, config?: {
+    mode?: "string" | "number" | "bigint";
+}): ColumnBuilder<string | number | bigint>;
+declare const boolean: (name: string) => ColumnBuilder<boolean>;
+declare const timestamp: (name: string) => ColumnBuilder<Date>;
+type SchemaDefinition = Record<string, Column<any>>;
+type InferModel<T extends SchemaDefinition> = {
+    [K in keyof T]: T[K]["_dataType"];
+};
+declare function defineTable<T extends SchemaDefinition>(tableName: string, schema: T): any & InferModel<T>;
+type Table<T extends SchemaDefinition> = ReturnType<typeof defineTable<T>>;
+
+interface SQL {
+    toSQL: () => {
+        clause: string;
+        bindings: any[];
+    };
+}
+declare const eq: (column: Column, value: any) => SQL;
+declare const ne: (column: Column, value: any) => SQL;
+declare const gt: (column: Column, value: number | Date) => SQL;
+declare const gte: (column: Column, value: number | Date) => SQL;
+declare const lt: (column: Column, value: number | Date) => SQL;
+declare const lte: (column: Column, value: number | Date) => SQL;
+declare const like: (column: Column<string>, value: string) => SQL;
+declare const asc: (column: Column) => string;
+declare const desc: (column: Column) => string;
+
+declare class SelectQueryBuilder<T> {
+    private _table;
+    private _selectedColumns;
+    private _joins;
+    private _where;
+    private _orderBy;
+    private _limit;
+    private _offset;
+    private _eager;
+    constructor(fields?: Record<string, Column<any>>);
+    from(table: Table<any>): this;
+    where(...conditions: SQL[]): this;
+    leftJoin(otherTable: Table<any>, on: SQL): this;
+    orderBy(...clauses: string[]): this;
+    limit(value: number): this;
+    offset(value: number): this;
+    execute(): Promise<T[]>;
+}
+declare class TauriORM {
+    query: Record<string, any>;
+    private _tables;
+    private _relations;
+    configureQuery(tables: Record<string, Table<any>>, relations: Record<string, Record<string, RelationConfig>>): void;
+    select<T>(fields?: Record<string, Column<any>>): SelectQueryBuilder<T>;
+    insert(table: Table<any>): {
+        _table: any;
+        _rows: Record<string, any>[];
+        values(rowOrRows: Record<string, any> | Record<string, any>[]): /*elided*/ any;
+        execute(): Promise<void>;
+    };
+    update(table: Table<any>): {
+        _table: any;
+        _data: Record<string, any> | null;
+        _where: Record<string, any> | SQL | null;
+        set(data: Record<string, any>): /*elided*/ any;
+        where(cond: Record<string, any> | SQL): /*elided*/ any;
+        execute(): Promise<void>;
+    };
+    delete(table: Table<any>): {
+        _table: any;
+        _where: Record<string, any> | SQL | null;
+        where(cond: Record<string, any> | SQL): /*elided*/ any;
+        execute(): Promise<void>;
+    };
+    run(query: string, bindings?: any[]): Promise<void>;
+    private generateCreateTableSql;
+    createTableIfNotExists(table: Table<any>): Promise<void>;
+    createTablesIfNotExist(tables: Table<any>[]): Promise<void>;
+    private ensureMigrationsTable;
+    private hasMigration;
+    private recordMigration;
+    migrate(tables: Table<any>[], options?: {
+        name?: string;
+        track?: boolean;
+    }): Promise<void>;
+    configure(tables: Record<string, Table<any>>, relDefs?: Record<string, Record<string, RelationConfig>>): this;
+    migrateConfigured(options?: {
+        name?: string;
+        track?: boolean;
+    }): Promise<void>;
+}
+declare const db: TauriORM;
+type OneConfig = {
+    fields?: Column[];
+    references?: Column[];
+    relationName?: string;
+};
+type ManyConfig = {
+    relationName?: string;
+};
+type RelationBuilderCtx = {
+    one: (table: Table<any>, cfg?: OneConfig) => OneRelation;
+    many: (table: Table<any>, cfg?: ManyConfig) => ManyRelation;
+};
+type OneRelation = {
+    kind: "one";
+    table: Table<any>;
+    cfg?: OneConfig;
+};
+type ManyRelation = {
+    kind: "many";
+    table: Table<any>;
+    cfg?: ManyConfig;
+};
+declare function relations(baseTable: Table<any>, builder: (ctx: RelationBuilderCtx) => Record<string, OneRelation | ManyRelation>): Record<string, OneRelation | ManyRelation>;
+type RelationConfig = OneRelation | ManyRelation;
+type WithSpec = Record<string, boolean | {
+    with?: WithSpec;
+    columns?: string[];
+}>;
+declare function makeQueryAPI(tables: Record<string, Table<any>>, relDefs: Record<string, Record<string, RelationConfig>>): { [K in keyof typeof tables]: {
+    findMany: (opts?: {
+        with?: WithSpec;
+        join?: boolean;
+        columns?: string[];
+    }) => Promise<any[]>;
+}; };
+
+export { type Column, type ManyRelation, type OneRelation, type SQL, type SQLExpression, type Table, TauriORM, type UpdateDeleteAction, asc, blob, boolean, db, defineTable, desc, eq, getDb, gt, gte, initDb, integer, like, lt, lte, makeQueryAPI, ne, numeric, real, relations, sql, text, timestamp };

package/dist/index.d.ts

@@ -0,0 +1,193 @@
+import Database from '@tauri-apps/plugin-sql';
+
+/**
+ * Initializes the database connection. This must be called once at the start of your application.
+ * @param dbPath The path to the database file, e.g., 'sqlite:mydatabase.db'
+ * @returns The database instance.
+ */
+declare function initDb(dbPath: string): Promise<Database>;
+/**
+ * Gets the singleton database instance.
+ * @throws If `initDb` has not been called.
+ * @returns The database instance.
+ */
+declare function getDb(): Database;
+
+type UpdateDeleteAction = "cascade" | "restrict" | "no action" | "set null" | "set default";
+interface SQLExpression {
+    raw: string;
+}
+declare function sql(strings: TemplateStringsArray, ...values: any[]): SQLExpression;
+interface Column<T = any> {
+    name: string;
+    type: "TEXT" | "INTEGER" | "REAL" | "BLOB" | "NUMERIC";
+    isPrimaryKey?: boolean;
+    autoIncrement?: boolean;
+    isNotNull?: boolean;
+    defaultValue?: T | SQLExpression;
+    references?: {
+        table: string;
+        column: string;
+        onDelete?: UpdateDeleteAction;
+        onUpdate?: UpdateDeleteAction;
+    };
+    enumValues?: readonly string[];
+    mode?: string;
+    _dataType: T;
+    /**
+     * Populated by defineTable so we can reason about relations and aliasing.
+     */
+    tableName?: string;
+}
+type ColumnBuilder<T> = Column<T> & {
+    primaryKey: (opts?: {
+        autoIncrement?: boolean;
+    }) => ColumnBuilder<T>;
+    notNull: () => ColumnBuilder<T>;
+    default: (value: T | SQLExpression) => ColumnBuilder<T>;
+    $type: <U>() => ColumnBuilder<U>;
+    references: (target: () => Column<any>, actions?: {
+        onDelete?: UpdateDeleteAction;
+        onUpdate?: UpdateDeleteAction;
+    }) => ColumnBuilder<T>;
+};
+declare function text<TEnum extends string>(name: string, config?: {
+    isPrimaryKey?: boolean;
+    enum?: readonly TEnum[];
+}): ColumnBuilder<TEnum extends string ? TEnum : string>;
+declare function integer(name: string, config?: {
+    isPrimaryKey?: boolean;
+    mode?: "number" | "boolean" | "timestamp";
+    autoIncrement?: boolean;
+}): ColumnBuilder<number | boolean | Date>;
+declare function real(name: string): ColumnBuilder<number>;
+declare function blob(name: string, config?: {
+    mode?: "json" | "bigint";
+}): ColumnBuilder<unknown | bigint | Uint8Array>;
+declare function numeric(name: string, config?: {
+    mode?: "string" | "number" | "bigint";
+}): ColumnBuilder<string | number | bigint>;
+declare const boolean: (name: string) => ColumnBuilder<boolean>;
+declare const timestamp: (name: string) => ColumnBuilder<Date>;
+type SchemaDefinition = Record<string, Column<any>>;
+type InferModel<T extends SchemaDefinition> = {
+    [K in keyof T]: T[K]["_dataType"];
+};
+declare function defineTable<T extends SchemaDefinition>(tableName: string, schema: T): any & InferModel<T>;
+type Table<T extends SchemaDefinition> = ReturnType<typeof defineTable<T>>;
+
+interface SQL {
+    toSQL: () => {
+        clause: string;
+        bindings: any[];
+    };
+}
+declare const eq: (column: Column, value: any) => SQL;
+declare const ne: (column: Column, value: any) => SQL;
+declare const gt: (column: Column, value: number | Date) => SQL;
+declare const gte: (column: Column, value: number | Date) => SQL;
+declare const lt: (column: Column, value: number | Date) => SQL;
+declare const lte: (column: Column, value: number | Date) => SQL;
+declare const like: (column: Column<string>, value: string) => SQL;
+declare const asc: (column: Column) => string;
+declare const desc: (column: Column) => string;
+
+declare class SelectQueryBuilder<T> {
+    private _table;
+    private _selectedColumns;
+    private _joins;
+    private _where;
+    private _orderBy;
+    private _limit;
+    private _offset;
+    private _eager;
+    constructor(fields?: Record<string, Column<any>>);
+    from(table: Table<any>): this;
+    where(...conditions: SQL[]): this;
+    leftJoin(otherTable: Table<any>, on: SQL): this;
+    orderBy(...clauses: string[]): this;
+    limit(value: number): this;
+    offset(value: number): this;
+    execute(): Promise<T[]>;
+}
+declare class TauriORM {
+    query: Record<string, any>;
+    private _tables;
+    private _relations;
+    configureQuery(tables: Record<string, Table<any>>, relations: Record<string, Record<string, RelationConfig>>): void;
+    select<T>(fields?: Record<string, Column<any>>): SelectQueryBuilder<T>;
+    insert(table: Table<any>): {
+        _table: any;
+        _rows: Record<string, any>[];
+        values(rowOrRows: Record<string, any> | Record<string, any>[]): /*elided*/ any;
+        execute(): Promise<void>;
+    };
+    update(table: Table<any>): {
+        _table: any;
+        _data: Record<string, any> | null;
+        _where: Record<string, any> | SQL | null;
+        set(data: Record<string, any>): /*elided*/ any;
+        where(cond: Record<string, any> | SQL): /*elided*/ any;
+        execute(): Promise<void>;
+    };
+    delete(table: Table<any>): {
+        _table: any;
+        _where: Record<string, any> | SQL | null;
+        where(cond: Record<string, any> | SQL): /*elided*/ any;
+        execute(): Promise<void>;
+    };
+    run(query: string, bindings?: any[]): Promise<void>;
+    private generateCreateTableSql;
+    createTableIfNotExists(table: Table<any>): Promise<void>;
+    createTablesIfNotExist(tables: Table<any>[]): Promise<void>;
+    private ensureMigrationsTable;
+    private hasMigration;
+    private recordMigration;
+    migrate(tables: Table<any>[], options?: {
+        name?: string;
+        track?: boolean;
+    }): Promise<void>;
+    configure(tables: Record<string, Table<any>>, relDefs?: Record<string, Record<string, RelationConfig>>): this;
+    migrateConfigured(options?: {
+        name?: string;
+        track?: boolean;
+    }): Promise<void>;
+}
+declare const db: TauriORM;
+type OneConfig = {
+    fields?: Column[];
+    references?: Column[];
+    relationName?: string;
+};
+type ManyConfig = {
+    relationName?: string;
+};
+type RelationBuilderCtx = {
+    one: (table: Table<any>, cfg?: OneConfig) => OneRelation;
+    many: (table: Table<any>, cfg?: ManyConfig) => ManyRelation;
+};
+type OneRelation = {
+    kind: "one";
+    table: Table<any>;
+    cfg?: OneConfig;
+};
+type ManyRelation = {
+    kind: "many";
+    table: Table<any>;
+    cfg?: ManyConfig;
+};
+declare function relations(baseTable: Table<any>, builder: (ctx: RelationBuilderCtx) => Record<string, OneRelation | ManyRelation>): Record<string, OneRelation | ManyRelation>;
+type RelationConfig = OneRelation | ManyRelation;
+type WithSpec = Record<string, boolean | {
+    with?: WithSpec;
+    columns?: string[];
+}>;
+declare function makeQueryAPI(tables: Record<string, Table<any>>, relDefs: Record<string, Record<string, RelationConfig>>): { [K in keyof typeof tables]: {
+    findMany: (opts?: {
+        with?: WithSpec;
+        join?: boolean;
+        columns?: string[];
+    }) => Promise<any[]>;
+}; };
+
+export { type Column, type ManyRelation, type OneRelation, type SQL, type SQLExpression, type Table, TauriORM, type UpdateDeleteAction, asc, blob, boolean, db, defineTable, desc, eq, getDb, gt, gte, initDb, integer, like, lt, lte, makeQueryAPI, ne, numeric, real, relations, sql, text, timestamp };