nanodb-orm 0.0.4 → 0.0.5

package/README.md

@@ -1,15 +1,15 @@
 # nanodb-orm
 
-A lightweight, schema-agnostic ORM wrapper for Drizzle ORM with automatic migrations, schema introspection, CLI tools, and support for SQLite/Turso databases.
+A lightweight ORM wrapper for Drizzle ORM with automatic migrations, schema introspection, CLI tools, and support for SQLite/Turso databases.
 
 ## Features
 
+- **TypeScript First** — Full type inference from schema to queries
 - **Auto-Migrations** — Automatically creates and updates database schemas from Drizzle tables
 - **Schema Introspection** — Comprehensive schema analysis and validation
 - **Multi-Database** — Works with local SQLite and remote Turso databases
 - **Transactions** — Full transaction support with automatic rollback
 - **CLI Tools** — Built-in commands including Drizzle Studio integration
-- **Type Safe** — Full TypeScript support with proper type inference
 - **Plugin System** — Extensible with hooks for audit, validation, transformations
 - **Minimal** — ~1K lines of code, zero bloat
 
@@ -54,65 +54,136 @@ npx nanodb studio
 
 ![Drizzle Studio](https://orm.drizzle.team/images/drizzle-studio.png)
 
+## Import Styles
+
+```typescript
+// Default import (recommended)
+import nanodb from 'nanodb-orm';
+
+const users = nanodb.schema.table('users', { ... });
+const db = await nanodb.createDatabase({ tables: { users } });
+await db.select().from(users).where(nanodb.query.eq(users.id, 1));
+```
+
+```typescript
+// Named imports
+import { createDatabase, schema, query } from 'nanodb-orm';
+```
+
+```typescript
+// Individual imports (tree-shakeable)
+import { createDatabase, table, integer, text, eq } from 'nanodb-orm';
+```
+
 ## Quick Start
 
 ### 1. Define Your Schema
 
 ```typescript
-import { table, integer, text } from 'nanodb-orm';
+import nanodb from 'nanodb-orm';
 
-const users = table('users', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  name: text('name').notNull(),
-  email: text('email').unique().notNull(),
-  age: integer('age'),
+const users = nanodb.schema.table('users', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  name: nanodb.schema.text('name').notNull(),
+  email: nanodb.schema.text('email').unique().notNull(),
+  age: nanodb.schema.integer('age'),
 });
 
-const posts = table('posts', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  title: text('title').notNull(),
-  userId: integer('userId').notNull(),
+const posts = nanodb.schema.table('posts', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  title: nanodb.schema.text('title').notNull(),
+  userId: nanodb.schema.integer('userId').notNull(),
 });
-
-const tables = { users, posts };
 ```
 
 ### 2. Create Database
 
 ```typescript
-import { createDatabase } from 'nanodb-orm';
-
-// One line: creates tables, runs migrations, seeds data, returns db
-const db = await createDatabase({
-  tables,
+const db = await nanodb.createDatabase({
+  tables: { users, posts },
   seedData: {
     users: [{ name: 'Alice', email: 'alice@example.com', age: 28 }],
   },
 });
 
-// Store db and use it everywhere - no need for getInstance() or getDb()
 export { db };
 ```
 
-### 3. Query with Type Safety
+### 3. Query Your Data
 
 ```typescript
-import { eq, gte } from 'nanodb-orm';
-
 // SELECT
 const allUsers = await db.select().from(users);
-const adults = await db.select().from(users).where(gte(users.age, 18));
+const adults = await db.select().from(users).where(nanodb.query.gte(users.age, 18));
 
 // INSERT
 await db.insert(users).values({ name: 'Bob', email: 'bob@example.com' });
 
 // UPDATE
-await db.update(users).set({ name: 'Robert' }).where(eq(users.email, 'bob@example.com'));
+await db.update(users).set({ name: 'Robert' }).where(nanodb.query.eq(users.email, 'bob@example.com'));
 
 // DELETE
-await db.delete(users).where(eq(users.email, 'bob@example.com'));
+await db.delete(users).where(nanodb.query.eq(users.email, 'bob@example.com'));
+```
+
+## Type Inference
+
+nanodb-orm provides full type inference from your schema:
+
+```typescript
+import { 
+  createDatabase, 
+  table, 
+  integer, 
+  text,
+  type SelectModel,
+  type InsertModel,
+} from 'nanodb-orm';
+
+const users = table('users', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  name: text('name').notNull(),
+  email: text('email').notNull(),
+  age: integer('age'),
+});
+
+// Infer types directly from your table definitions
+type User = SelectModel<typeof users>;
+// { id: number; name: string; email: string; age: number | null }
+
+type NewUser = InsertModel<typeof users>;
+// { id?: number; name: string; email: string; age?: number | null }
+
+// The database is fully typed
+const db = await createDatabase({ tables: { users } });
+
+// All operations are type-safe
+const allUsers: User[] = await db.select().from(users);
+
+// Seed data is type-checked at compile time
+const db2 = await createDatabase({
+  tables: { users },
+  seedData: {
+    users: [
+      { name: 'Alice', email: 'alice@example.com' }, // ✓ Valid
+      // { name: 123 }, // ✗ TypeScript error!
+    ],
+  },
+});
 ```
 
+### Available Type Utilities
+
+| Type | Description |
+|------|-------------|
+| `SelectModel<T>` | Infer the row type (SELECT result) from a table |
+| `InsertModel<T>` | Infer the insert type from a table (optional auto-generated columns) |
+| `SchemaModels<S>` | Extract all row types from a schema object |
+| `SchemaInsertModels<S>` | Extract all insert types from a schema |
+| `NanoDatabase<S>` | The typed database instance |
+| `Schema` | Type for schema objects |
+| `AnyTable` | Type constraint for Drizzle tables |
+
 ## API Reference
 
 ### `createDatabase(config)`
@@ -122,7 +193,7 @@ Create and initialize database. Returns `db` with all utilities attached.
 ```typescript
 const db = await createDatabase({
   tables: { users, posts },
-  seedData: { users: [...] },
+  seedData: { users: [...] },  // Type-checked against schema
   migrationConfig: {
     preserveData: true,   // default: true
     autoMigrate: true,    // default: true
@@ -149,7 +220,7 @@ await db.clearData();      // Delete all data (keep tables)
 ### Schema Introspection (from `db.schema`)
 
 ```typescript
-db.schema.tables();              // ['users', 'posts']
+db.schema.tables();              // ['users', 'posts'] - typed as (keyof Schema)[]
 db.schema.getTable('users');     // { columns, primaryKey, indexes }
 db.schema.getColumns('users');   // ['id', 'name', 'email']
 await db.schema.validate();      // { isValid, missingTables, ... }
@@ -165,24 +236,31 @@ await db.migrations.validate();    // Validate schema vs DB
 await db.migrations.checkTables(); // { users: true, posts: true }
 ```
 
-### `transaction(fn)`
+### `transaction(fn)` / `batch(statements)`
 
-Execute operations atomically.
+Execute operations atomically. Uses Drizzle's native transaction when available (better for Turso).
 
 ```typescript
-import { transaction, sql } from 'nanodb-orm';
+import nanodb from 'nanodb-orm';
 
-const result = await transaction(async (tx) => {
-  await tx.run(sql`INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')`);
-  await tx.run(sql`INSERT INTO posts (title, userId) VALUES ('Hello', 1)`);
+// Transaction with custom logic
+const result = await nanodb.transaction(async (tx) => {
+  await tx.run(nanodb.query.sql`INSERT INTO users (name) VALUES ('Alice')`);
+  await tx.run(nanodb.query.sql`INSERT INTO posts (title, userId) VALUES ('Hello', 1)`);
   return { created: true };
 });
 
 if (result.success) {
-  console.log(result.result);
+  console.log(result.result); // { created: true }
 } else {
   console.log('Rolled back:', result.error?.message);
 }
+
+// Batch multiple statements (simpler for bulk operations)
+const batchResult = await nanodb.batch([
+  nanodb.query.sql`INSERT INTO users (name) VALUES ('Bob')`,
+  nanodb.query.sql`INSERT INTO users (name) VALUES ('Carol')`,
+]);
 ```
 
 ### `parseDbError(error, context)`
@@ -193,10 +271,10 @@ Parse SQLite errors into user-friendly messages.
 import { parseDbError } from 'nanodb-orm';
 
 try {
-  await db.run('INSERT INTO users ...');
+  await db.insert(users).values({ email: 'duplicate@example.com' });
 } catch (error) {
   const parsed = parseDbError(error, { table: 'users', operation: 'insert' });
-  console.log(parsed.message); // "Column 'email' does not exist"
+  console.log(parsed.message); // "Duplicate value for unique column 'email'"
 }
 ```
 
@@ -282,6 +360,192 @@ await db.insert(users).values({ email: 'invalid' }); // throws error
 db.plugins.list(); // ['audit', 'slug', 'validation']
 ```
 
+## Best Practices
+
+### Recommended Project Structure
+
+```
+db/
+├── schema.ts      # Table definitions
+├── index.ts       # Database instance export
+├── types.ts       # Type aliases (SelectModel, InsertModel)
+├── plugins.ts     # Custom plugins
+└── seeds.ts       # Seed data
+```
+
+### 1. Schema Order Matters
+
+Define parent tables before children for correct seeding order:
+
+```typescript
+// db/schema.ts
+import nanodb from 'nanodb-orm';
+
+// Parent tables first (no foreign keys)
+export const users = nanodb.schema.table('users', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  name: nanodb.schema.text('name').notNull(),
+  email: nanodb.schema.text('email').notNull().unique(),
+});
+
+export const categories = nanodb.schema.table('categories', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  name: nanodb.schema.text('name').notNull(),
+});
+
+// Child tables after (have foreign keys)
+export const posts = nanodb.schema.table('posts', {
+  id: nanodb.schema.integer('id').primaryKey({ autoIncrement: true }),
+  title: nanodb.schema.text('title').notNull(),
+  userId: nanodb.schema.integer('userId').notNull(),      // FK to users
+  categoryId: nanodb.schema.integer('categoryId'),        // FK to categories
+});
+
+// Order: parents → children
+export const schema = { users, categories, posts };
+```
+
+### 2. Single Database Instance
+
+```typescript
+// db/index.ts
+import nanodb from 'nanodb-orm';
+import { schema } from './schema';
+import { seedData } from './seeds';
+
+export const db = await nanodb.createDatabase({ tables: schema, seedData });
+```
+
+```typescript
+// anywhere.ts
+import { db } from './db';
+import { users } from './db/schema';
+
+const allUsers = await db.select().from(users);
+```
+
+### 3. Use Type Inference
+
+```typescript
+// db/types.ts
+import { type SelectModel, type InsertModel } from 'nanodb-orm';
+import { users, posts } from './schema';
+
+export type User = SelectModel<typeof users>;
+export type NewUser = InsertModel<typeof users>;
+export type Post = SelectModel<typeof posts>;
+
+// Usage
+async function createUser(data: NewUser): Promise<void> {
+  await db.insert(users).values(data);  // TypeScript enforces shape
+}
+```
+
+### 4. Prefer Grouped Imports
+
+```typescript
+// ✅ Clean - default import
+import nanodb from 'nanodb-orm';
+
+const users = nanodb.schema.table('users', { ... });
+await db.select().from(users).where(nanodb.query.eq(users.id, 1));
+
+// ✅ Also good - grouped imports
+import { schema, query, errors } from 'nanodb-orm';
+
+// ❌ Avoid - many individual imports
+import { table, integer, text, eq, gte, and, sql, count, ... } from 'nanodb-orm';
+```
+
+### 5. Handle Errors Gracefully
+
+```typescript
+import { parseDbError, DatabaseError } from 'nanodb-orm';
+
+try {
+  await db.insert(users).values({ email: 'duplicate@test.com' });
+} catch (error) {
+  if (error instanceof DatabaseError) {
+    // Already formatted with context
+    console.log(error.message);  // "UNIQUE constraint failed: users.email"
+    console.log(error.table);    // "users"
+  } else {
+    const parsed = parseDbError(error, { table: 'users' });
+    console.log(parsed.format());
+  }
+}
+```
+
+### 6. Use Transactions for Atomic Operations
+
+```typescript
+import nanodb from 'nanodb-orm';
+
+const result = await nanodb.transaction(async (tx) => {
+  await tx.run(nanodb.query.sql`INSERT INTO users (name) VALUES ('Alice')`);
+  await tx.run(nanodb.query.sql`INSERT INTO posts (title, userId) VALUES ('Hello', 1)`);
+  return { inserted: 2 };
+});
+
+if (!result.success) {
+  console.log('Rolled back:', result.error?.message);
+}
+```
+
+### 7. Validate on Startup (Production)
+
+```typescript
+import nanodb from 'nanodb-orm';
+
+const db = await nanodb.createDatabase({ tables: schema });
+
+if (process.env.NODE_ENV === 'production') {
+  const validation = await db.schema.validate();
+  if (!validation.isValid) {
+    throw new Error(`Schema mismatch: ${validation.missingTables.join(', ')}`);
+  }
+
+  const health = await db.healthCheck();
+  if (!health.healthy) {
+    console.warn('Database issues:', health.errors);
+  }
+}
+```
+
+### 8. Keep Plugins Simple
+
+```typescript
+// Good: focused, single responsibility
+const timestampPlugin: NanoPlugin = {
+  name: 'timestamps',
+  beforeInsert: (_table, data) => ({
+    ...data,
+    createdAt: new Date().toISOString(),
+  }),
+  beforeUpdate: (_table, data) => ({
+    ...data,
+    updatedAt: new Date().toISOString(),
+  }),
+};
+
+// Avoid: complex business logic in hooks
+```
+
+### 9. Environment Configuration
+
+```bash
+# .env
+TURSO_CONNECTION_URL=libsql://your-db.turso.io
+TURSO_AUTH_TOKEN=your-token
+FORCE_LOCAL_DB=true           # Use local SQLite
+DATABASE_PATH=./data/app.db   # Custom DB path
+```
+
+nanodb-orm auto-detects the right database:
+- **Turso**: when `TURSO_*` vars are set
+- **Local**: when `FORCE_LOCAL_DB=true` or no Turso config  
+- **Test**: isolated `test.db` when `NODE_ENV=test`
+
 ## Configuration
 
 ### Environment Variables
@@ -291,14 +555,18 @@ db.plugins.list(); // ['audit', 'slug', 'validation']
 TURSO_CONNECTION_URL=libsql://your-db.turso.io
 TURSO_AUTH_TOKEN=your-token
 
-# Force local SQLite (for testing)
+# Force local SQLite
 FORCE_LOCAL_DB=true
+
+# Custom database path (works with FORCE_LOCAL_DB or as fallback)
+DATABASE_PATH=./data/myapp.db
 ```
 
 ### Database Selection
 
 - **Turso** — Used when `TURSO_CONNECTION_URL` and `TURSO_AUTH_TOKEN` are set
-- **Local SQLite** — Fallback when Turso credentials are missing
+- **Local SQLite** — Used when `FORCE_LOCAL_DB=true` or Turso credentials missing
+- **Custom Path** — Set `DATABASE_PATH=./path/to/db.sqlite` for custom location
 - **Test Mode** — Isolated `test.db` when `NODE_ENV=test`
 
 ## Error Handling
@@ -331,6 +599,78 @@ Error output is clean and actionable:
 └────────────────────────────────────────────────
 ```
 
+## Exports
+
+```typescript
+// Default export (recommended)
+import nanodb from 'nanodb-orm';
+
+nanodb.createDatabase  // Main entry point
+nanodb.transaction     // Atomic operations
+nanodb.schema          // .table, .integer, .text, .real, .blob
+nanodb.query           // .eq, .gte, .and, .or, .sql, .count, ...
+nanodb.errors          // .DatabaseError, .parse
+nanodb.cli             // .studio, .setup, .reset, .status, .validate
+
+// Types (named imports)
+import { type SelectModel, type InsertModel, type NanoPlugin } from 'nanodb-orm';
+```
+
+## nanodb-orm vs Drizzle + Turso (Direct)
+
+| Feature | nanodb-orm | Drizzle + Turso |
+|---------|------------|-----------------|
+| **Setup** | One-liner: `createDatabase({ tables })` | Manual: create client, drizzle, manage connection |
+| **Migrations** | Automatic on startup | Manual: `drizzle-kit push/migrate` |
+| **Seeding** | Built-in with `seedData` | Write seed scripts |
+| **Type Safety** | ✅ Full (same as Drizzle) | ✅ Full |
+| **Query API** | ✅ Same as Drizzle | ✅ Native Drizzle |
+| **Plugins/Hooks** | ✅ beforeInsert, afterQuery, etc. | ❌ None |
+| **Schema Introspection** | ✅ `db.schema.tables()` | ❌ Manual |
+| **Health Checks** | ✅ `db.healthCheck()` | ❌ Manual |
+| **CLI** | `npx nanodb studio/status/validate` | `npx drizzle-kit studio` only |
+| **Error Parsing** | User-friendly messages | Raw SQLite errors |
+| **Connection** | Auto-detects Turso vs local | Manual configuration |
+
+### When to Use What
+
+| Use Case | Recommendation |
+|----------|----------------|
+| Quick prototyping | **nanodb-orm** |
+| Need plugins/hooks | **nanodb-orm** |
+| Want auto-migrations | **nanodb-orm** |
+| New SQLite/Turso project | **nanodb-orm** |
+| Maximum control | Drizzle directly |
+| Complex migration strategies | Drizzle + drizzle-kit |
+| Existing Drizzle project | Keep Drizzle |
+
+### Comparison
+
+```typescript
+// nanodb-orm: 5 lines
+import nanodb from 'nanodb-orm';
+
+const users = nanodb.schema.table('users', { id: nanodb.schema.integer('id').primaryKey() });
+const db = await nanodb.createDatabase({ tables: { users }, seedData: { users: [{ id: 1 }] } });
+// Ready - tables created, seeded
+```
+
+```typescript
+// Drizzle + Turso: More setup
+import { drizzle } from 'drizzle-orm/libsql';
+import { createClient } from '@libsql/client';
+import { sqliteTable, integer } from 'drizzle-orm/sqlite-core';
+import { migrate } from 'drizzle-orm/libsql/migrator';
+
+const users = sqliteTable('users', { id: integer('id').primaryKey() });
+const client = createClient({ url: process.env.TURSO_CONNECTION_URL!, authToken: process.env.TURSO_AUTH_TOKEN! });
+const db = drizzle(client);
+await migrate(db, { migrationsFolder: './drizzle' });
+await db.insert(users).values([{ id: 1 }]);
+```
+
+**nanodb-orm is a convenience layer** — it uses Drizzle under the hood and passes through all queries unchanged. You get Drizzle's full type safety plus automatic setup, plugins, and utilities.
+
 ## License
 
 MIT © Damilola Alao

package/dist/cli.d.ts

@@ -9,5 +9,88 @@
  *   status     - Show database health and stats
  *   validate   - Validate schema against database
  */
-export {};
+import { type ChildProcess } from 'child_process';
+export interface StudioOptions {
+    /** Database file path (default: auto-detected or 'database.db') */
+    dbPath?: string | undefined;
+    /** Port for Drizzle Studio (default: 4983) */
+    port?: number | undefined;
+    /** Suppress console output */
+    silent?: boolean | undefined;
+}
+export interface StatusResult {
+    healthy: boolean;
+    schemaValid: boolean;
+    totalTables: number;
+    totalRecords: number;
+    tables: Record<string, number>;
+    errors: string[];
+}
+export interface ValidationResult {
+    isValid: boolean;
+    missingTables: string[];
+    extraTables: string[];
+    errors: string[];
+}
+/**
+ * Launch Drizzle Studio for visual database browsing.
+ *
+ * @example
+ * ```ts
+ * import { launchStudio } from 'nanodb-orm';
+ *
+ * // Launch with defaults
+ * await launchStudio();
+ *
+ * // Launch with options
+ * await launchStudio({ dbPath: './data/app.db', port: 3000 });
+ * ```
+ */
+export declare function launchStudio(options?: StudioOptions): Promise<ChildProcess>;
+/**
+ * Run database setup (initialize schema and seed data).
+ *
+ * @example
+ * ```ts
+ * import { runSetup } from 'nanodb-orm';
+ * await runSetup();
+ * ```
+ */
+export declare function runSetup(silent?: boolean): Promise<void>;
+/**
+ * Reset database (drop all tables and recreate with seed data).
+ *
+ * @example
+ * ```ts
+ * import { runReset } from 'nanodb-orm';
+ * await runReset();
+ * ```
+ */
+export declare function runReset(silent?: boolean): Promise<void>;
+/**
+ * Get database status and health information.
+ *
+ * @example
+ * ```ts
+ * import { getStatus } from 'nanodb-orm';
+ *
+ * const status = await getStatus();
+ * console.log(status.healthy, status.totalRecords);
+ * ```
+ */
+export declare function getStatus(silent?: boolean): Promise<StatusResult>;
+/**
+ * Validate schema against database.
+ *
+ * @example
+ * ```ts
+ * import { runValidate } from 'nanodb-orm';
+ *
+ * const result = await runValidate();
+ * if (!result.isValid) {
+ *   console.log('Missing tables:', result.missingTables);
+ * }
+ * ```
+ */
+export declare function runValidate(silent?: boolean): Promise<ValidationResult>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AAEH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAQzD,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA8CrF;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,MAAM,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAO5D;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,MAAM,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAO5D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,SAAS,CAAC,MAAM,UAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CAsCrE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,MAAM,UAAQ,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsC3E"}