@type32/tauri-sqlite-orm 0.1.3 → 0.1.4

package/LICENSE

@@ -1,21 +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.
+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

@@ -1,210 +1,247 @@
-## 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 @type32/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"),
-  randomId: text("random_id").$defaultFn(() => crypto.randomUUID()),
-  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
+## 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
+bun add @type32/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 {
+  TauriORM,
+  defineTable,
+  integer,
+  text,
+  relations,
+} from "tauri-sqlite-orm";
+
+const db = new TauriORM("sqlite:app.db");
+
+export const users = defineTable("users", {
+  id: integer("id").primaryKey({ autoIncrement: true }),
+  name: text("name").notNull(),
+  email: text("email"),
+});
+
+export const posts = defineTable("posts", {
+  id: integer("id").primaryKey(),
+  content: text("content"),
+  randomId: text("random_id").$defaultFn(() => crypto.randomUUID()),
+  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").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").primaryKey(),
+  userId: integer("user_id")
+    .references(() => users.id, { onDelete: "cascade" })
+    .notNull(),
+});
+```
+
+### More data types and modes
+
+```ts
+// JSON stored in TEXT with proper SQLite JSON function support
+const cfg = defineTable("cfg", {
+  jsonText: text("json_text", { mode: "json" }).$type<{ foo: string }>(),
+  tsMs: integer("ts_ms", { mode: "timestamp_ms" }),
+  dataBuf: blob("data_buf", { mode: "buffer" }),
+});
+```
+
+Tip: Prefer `text(name, { mode: 'json' })` over `blob(name, { mode: 'json' })` to use SQLite JSON functions.
+
+### 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();
+```
+
+### Runtime defaults and onUpdate
+
+```ts
+import { defineTable, integer, text, increments } from "tauri-sqlite-orm";
+
+export const audit = defineTable("audit", {
+  id: increments("id"),
+  // Called on insert if value not provided
+  createdAt: integer("created_at", { mode: "timestamp" }).$defaultFn(
+    () => new Date()
+  ),
+  // Called on update when not explicitly set; if no default is provided, also used on insert
+  updatedAt: integer("updated_at", { mode: "timestamp" }).$onUpdateFn(
+    () => new Date()
+  ),
+  token: text("token").$default(() => crypto.randomUUID()),
+});
+```
+
+### Query API (relations)
+
+Auto-generated with `db.configure(tables, relations?)`:
+
+```ts
+// Flat relations with join
+import { asc } from "tauri-sqlite-orm";
+
+const usersWithPosts = await db.query.users.findMany({
+  with: { posts: true },
+  join: true,
+  where: (users, { eq }) => eq(users.id, 1),
+  orderBy: (users, { asc }) => [asc(users.id)],
+  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"],
+    },
+  },
+});
+
+// First row helper
+const firstUser = await db.query.users.findFirst({
+  where: (users, { eq }) => eq(users.id, 1),
+});
+```
+
+Notes:
+
+- `where` accepts SQL helpers (eq, lt, gte, like) or object map, or a callback `(table, ops) => SQL`.
+- `orderBy` accepts typed helpers or a callback `(table, { asc, desc }) => [...]`.
+- `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: (posts, { eq }) => eq(posts.authorId, 1),
+  orderBy: (posts, { asc }) => [asc(posts.id)],
+});
+```
+
+### Nuxt + Tauri usage
+
+Initialize in a client plugin and ensure a single ORM instance is created:
+
+```ts
+// plugins/orm.client.ts
+import { TauriORM } from "tauri-sqlite-orm";
+import { users, posts, usersRelations } from "@/lib/schema";
+
+export default defineNuxtPlugin(async () => {
+  const db = new TauriORM("sqlite:app.db");
+  db.configure({ users, posts }, { users: usersRelations });
+  await db.migrateConfigured({ name: "init:users,posts" });
+
+  return { provide: { db } };
+});
+```
+
+### 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

@@ -1,18 +1,5 @@
 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;
@@ -26,6 +13,7 @@ interface Column<T = any> {
     isNotNull?: boolean;
     defaultValue?: T | SQLExpression;
     defaultFn?: () => any;
+    onUpdateFn?: () => any;
     references?: {
         table: string;
         column: string;
@@ -48,29 +36,49 @@ type ColumnBuilder<T> = Column<T> & {
     default: (value: T | SQLExpression) => ColumnBuilder<T>;
     $type: <U>() => ColumnBuilder<U>;
     $defaultFn: (fn: () => any) => ColumnBuilder<T>;
+    $default: (fn: () => any) => ColumnBuilder<T>;
+    $onUpdate: (fn: () => any) => ColumnBuilder<T>;
+    $onUpdateFn: (fn: () => any) => ColumnBuilder<T>;
     references: (target: () => Column<any>, actions?: {
         onDelete?: UpdateDeleteAction;
         onUpdate?: UpdateDeleteAction;
     }) => ColumnBuilder<T>;
 };
-declare function text<TEnum extends string>(name: string, config?: {
-    isPrimaryKey?: boolean;
+type TextConfig<TEnum extends string> = {
     enum?: readonly TEnum[];
-}): ColumnBuilder<TEnum extends string ? TEnum : string>;
+    mode?: "json";
+};
+declare function text<TEnum extends string>(name: string, config?: TextConfig<TEnum>): ColumnBuilder<TEnum extends string ? TEnum : string>;
+declare function text<TEnum extends string>(config?: TextConfig<TEnum>): ColumnBuilder<TEnum extends string ? TEnum : string>;
+type IntegerMode = "number" | "boolean" | "timestamp" | "timestamp_ms";
 declare function integer(name: string, config?: {
-    isPrimaryKey?: boolean;
-    mode?: "number" | "boolean" | "timestamp";
-    autoIncrement?: boolean;
+    mode?: IntegerMode;
+}): ColumnBuilder<number | boolean | Date>;
+declare function integer(config?: {
+    mode?: IntegerMode;
 }): ColumnBuilder<number | boolean | Date>;
 declare function real(name: string): ColumnBuilder<number>;
+declare function real(): ColumnBuilder<number>;
+type BlobMode = "json" | "bigint" | "buffer";
 declare function blob(name: string, config?: {
-    mode?: "json" | "bigint";
+    mode?: BlobMode;
 }): ColumnBuilder<unknown | bigint | Uint8Array>;
+declare function blob(config?: {
+    mode?: BlobMode;
+}): ColumnBuilder<unknown | bigint | Uint8Array>;
+type NumericMode = "string" | "number" | "bigint";
 declare function numeric(name: string, config?: {
-    mode?: "string" | "number" | "bigint";
+    mode?: NumericMode;
+}): ColumnBuilder<string | number | bigint>;
+declare function numeric(config?: {
+    mode?: NumericMode;
 }): ColumnBuilder<string | number | bigint>;
-declare const boolean: (name: string) => ColumnBuilder<boolean>;
-declare const timestamp: (name: string) => ColumnBuilder<Date>;
+declare function boolean(name: string): ColumnBuilder<boolean>;
+declare function boolean(): ColumnBuilder<boolean>;
+declare function timestamp(name: string): ColumnBuilder<Date>;
+declare function timestamp(): ColumnBuilder<Date>;
+declare function increments(name: string): ColumnBuilder<number>;
+declare function increments(): ColumnBuilder<number>;
 type SchemaDefinition = Record<string, Column<any>>;
 type InferModel<T extends SchemaDefinition> = {
     [K in keyof T]: T[K]["_dataType"];
@@ -103,7 +111,8 @@ declare class SelectQueryBuilder<T> {
     private _limit;
     private _offset;
     private _eager;
-    constructor(fields?: Record<string, Column<any>>);
+    private _dbProvider;
+    constructor(dbProvider: () => Promise<Database>, fields?: Record<string, Column<any>>);
     from(table: Table<any>): this;
     where(...conditions: SQL[]): this;
     leftJoin(otherTable: Table<any>, on: SQL): this;
@@ -116,6 +125,9 @@ declare class TauriORM {
     query: Record<string, any>;
     private _tables;
     private _relations;
+    private _dbPromise;
+    constructor(dbUri: string);
+    private getDb;
     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>): {
@@ -209,7 +221,6 @@ declare class TauriORM {
         preserveData?: boolean;
     }): Promise<void>;
 }
-declare const db: TauriORM;
 type OneConfig = {
     fields?: Column[];
     references?: Column[];
@@ -238,12 +249,17 @@ 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]: {
+declare function makeQueryAPI(tables: Record<string, Table<any>>, relDefs: Record<string, Record<string, RelationConfig>>, dbProvider: () => Promise<Database>): { [K in keyof typeof tables]: {
     findMany: (opts?: {
         with?: WithSpec;
         join?: boolean;
         columns?: string[];
     }) => Promise<any[]>;
+    findFirst: (opts?: {
+        with?: WithSpec;
+        join?: boolean;
+        columns?: string[];
+    }) => Promise<any | null>;
 }; };
 
-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 };
+export { type BlobMode, type Column, type ColumnBuilder, type IntegerMode, type ManyRelation, type NumericMode, type OneRelation, type SQL, type SQLExpression, type Table, TauriORM, type UpdateDeleteAction, asc, blob, boolean, defineTable, desc, eq, gt, gte, increments, integer, like, lt, lte, makeQueryAPI, ne, numeric, real, relations, sql, text, timestamp };