bunql 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 BunQL
+
+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,502 @@
+# BunQL
+
+A fluent SQL query builder for Bun with transaction support, built on top of Bun's native SQL bindings.
+
+## Features
+
+- 🚀 **Fluent API**: Chainable methods for building SQL queries
+- ⚡ **Auto-Execute**: Queries automatically execute when awaited (no `.execute()` needed!)
+- 🔄 **Transaction Support**: Built-in transaction handling with rollback support
+- 🛡️ **SQL Injection Protection**: Parameterized queries prevent SQL injection
+- 🗄️ **Multi-Database Support**: Works with PostgreSQL, MySQL, and SQLite
+- 📦 **Zero Dependencies**: Built on Bun's native SQL bindings
+- 🧪 **TypeScript Support**: Full TypeScript support with type safety
+- 🏗️ **Schema Management**: Complete database schema creation and management API
+
+## Installation
+
+```bash
+bun add bunql
+```
+
+## Quick Start
+
+```typescript
+import { BunQL, createQueryBuilder } from 'bunql';
+
+// Create a BunQL instance
+const db = new BunQL('postgres://user:pass@localhost:5432/mydb');
+// or use the factory function
+const db = createQueryBuilder('sqlite://myapp.db');
+```
+
+## Auto-Execute Feature
+
+BunQL queries automatically execute when awaited, eliminating the need to call `.execute()`:
+
+```typescript
+// ✅ Auto-executes when awaited
+const users = await db.select('*').from('users');
+
+// ✅ Also works with complex queries
+const result = await db.update('users')
+  .set({ active: false })
+  .where('id', '=', 1);
+
+// ✅ You can still use .execute() if you prefer explicit execution
+const users = await db.select('*').from('users').execute();
+```
+
+This makes the API more concise and intuitive while maintaining backward compatibility.
+
+## Usage Examples
+
+### Select Queries
+
+```typescript
+// Basic select (auto-executes when awaited)
+const users = await db.select('*').from('users');
+
+// Select with specific columns
+const users = await db.select(['id', 'name', 'email']).from('users');
+
+// Select with where clause
+const user = await db.select('*')
+  .from('users')
+  .where('id', '=', 1)
+  .first();
+
+// Select with multiple conditions
+const activeUsers = await db.select('*')
+  .from('users')
+  .where('active', '=', true)
+  .where('role', '=', 'admin');
+
+// Select with IN clause
+const users = await db.select('*')
+  .from('users')
+  .whereIn('id', [1, 2, 3]);
+
+// Select with ordering and pagination
+const users = await db.select('*')
+  .from('users')
+  .orderBy('name', 'ASC')
+  .limit(10)
+  .offset(20);
+
+// You can still use .execute() if you prefer explicit execution
+const users = await db.select('*').from('users').execute();
+```
+
+### Insert Queries
+
+```typescript
+// Single insert (auto-executes when awaited)
+const result = await db.insert('users')
+  .values({
+    name: 'John Doe',
+    email: 'john@example.com',
+    active: true
+  });
+
+console.log('Inserted ID:', result.lastInsertRowid);
+
+// Bulk insert
+const users = [
+  { name: 'Alice', email: 'alice@example.com' },
+  { name: 'Bob', email: 'bob@example.com' }
+];
+
+await db.insert('users').values(users);
+```
+
+### Update Queries
+
+```typescript
+// Update with where clause (auto-executes when awaited)
+const result = await db.update('users')
+  .set({
+    name: 'John Smith',
+    email: 'johnsmith@example.com'
+  })
+  .where('id', '=', 1);
+
+console.log('Updated rows:', result.affectedRows);
+
+// Update multiple fields
+await db.update('users')
+  .set({
+    active: false,
+    updated_at: new Date()
+  })
+  .where('last_login', '<', new Date('2023-01-01'));
+```
+
+### Delete Queries
+
+```typescript
+// Delete with where clause (auto-executes when awaited)
+const result = await db.delete('users')
+  .where('id', '=', 1);
+
+console.log('Deleted rows:', result.affectedRows);
+
+// Delete with multiple conditions
+await db.delete('users')
+  .where('active', '=', false)
+  .where('created_at', '<', new Date('2023-01-01'));
+```
+
+### Raw SQL Queries
+
+```typescript
+// Execute raw SQL
+await db.run('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
+
+// Execute with parameters
+await db.run('UPDATE users SET name = ? WHERE id = ?', ['John', 1]);
+
+// Get all results
+const users = await db.all('SELECT * FROM users WHERE active = ?', [true]);
+
+// Get single result
+const user = await db.get('SELECT * FROM users WHERE id = ?', [1]);
+```
+
+### Transactions
+
+```typescript
+// Transaction with automatic rollback on error
+const result = await db.begin(async (tx) => {
+  // Insert user
+  const userResult = await tx.insert('users')
+    .values({ name: 'John', email: 'john@example.com' })
+    .execute();
+  
+  // Insert user profile
+  await tx.insert('user_profiles')
+    .values({ 
+      user_id: userResult.lastInsertRowid,
+      bio: 'Software developer'
+    })
+    .execute();
+  
+  // Update user status
+  await tx.update('users')
+    .set({ active: true })
+    .where('id', '=', userResult.lastInsertRowid)
+    .execute();
+  
+  return userResult.lastInsertRowid;
+});
+
+console.log('Transaction completed, user ID:', result);
+```
+
+## Schema Management
+
+BunQL provides a comprehensive schema management API that can replace Bunely for database schema operations.
+
+### Creating Tables
+
+```typescript
+// Create a table with columns, indexes, and foreign keys
+await db.schema.createTable('users')
+  .addColumn({
+    name: 'id',
+    type: 'INTEGER',
+    primaryKey: true,
+    autoIncrement: true
+  })
+  .addColumn({
+    name: 'name',
+    type: 'TEXT',
+    notNull: true
+  })
+  .addColumn({
+    name: 'email',
+    type: 'TEXT',
+    unique: true,
+    notNull: true
+  })
+  .addColumn({
+    name: 'age',
+    type: 'INTEGER',
+    defaultValue: 0
+  })
+  .addIndex({
+    name: 'idx_users_email',
+    columns: ['email'],
+    unique: true
+  })
+  .execute();
+
+// Create table with foreign key constraints
+await db.schema.createTable('posts')
+  .addColumn({
+    name: 'id',
+    type: 'INTEGER',
+    primaryKey: true,
+    autoIncrement: true
+  })
+  .addColumn({
+    name: 'title',
+    type: 'TEXT',
+    notNull: true
+  })
+  .addColumn({
+    name: 'user_id',
+    type: 'INTEGER',
+    notNull: true
+  })
+  .addForeignKey({
+    name: 'fk_posts_user_id',
+    columns: ['user_id'],
+    referencedTable: 'users',
+    referencedColumns: ['id'],
+    onDelete: 'CASCADE'
+  })
+  .execute();
+```
+
+### Altering Tables
+
+```typescript
+// Add a new column
+await db.schema.alterTable('users')
+  .addColumn({
+    name: 'bio',
+    type: 'TEXT',
+    notNull: false
+  })
+  .execute();
+
+// Rename a column
+await db.schema.alterTable('posts')
+  .renameColumn('content', 'body')
+  .execute();
+
+// Add an index
+await db.schema.alterTable('users')
+  .addIndex({
+    name: 'idx_users_age',
+    columns: ['age'],
+    unique: false
+  })
+  .execute();
+
+// Drop a column
+await db.schema.alterTable('users')
+  .dropColumn('old_column')
+  .execute();
+```
+
+### Schema Introspection
+
+```typescript
+// Check if a table exists
+const exists = await db.schema.hasTable('users');
+
+// Get all tables
+const tables = await db.schema.getTables();
+
+// Get table information
+const tableInfo = await db.schema.getTableInfo('users');
+console.log(tableInfo);
+// [
+//   { name: 'id', type: 'INTEGER', notNull: true, primaryKey: true, ... },
+//   { name: 'name', type: 'TEXT', notNull: true, primaryKey: false, ... }
+// ]
+
+// Get indexes for a table
+const indexes = await db.schema.getIndexes('users');
+
+// Get foreign keys for a table
+const foreignKeys = await db.schema.getForeignKeys('posts');
+
+// Get complete table information
+const completeInfo = await db.schema.getCompleteTableInfo('users');
+```
+
+### Index Management
+
+```typescript
+// Create an index
+await db.schema.createIndex('users', {
+  name: 'idx_users_name_email',
+  columns: ['name', 'email'],
+  unique: false
+});
+
+// Make columns unique
+await db.schema.makeColumnsUnique('posts', ['title', 'user_id']);
+
+// Drop an index
+await db.schema.dropIndex('idx_users_email');
+```
+
+### Table Management
+
+```typescript
+// Drop a table
+await db.schema.dropTable('old_table');
+
+// Drop table if exists
+await db.schema.dropTable('old_table', true);
+```
+
+### Complex Queries
+
+```typescript
+// Complex select with joins (using raw SQL)
+const usersWithProfiles = await db.all(`
+  SELECT u.*, p.bio, p.avatar 
+  FROM users u 
+  LEFT JOIN user_profiles p ON u.id = p.user_id 
+  WHERE u.active = ? 
+  ORDER BY u.created_at DESC 
+  LIMIT ?
+`, [true, 10]);
+
+// Using the query builder for complex conditions
+const recentUsers = await db.select(['u.id', 'u.name', 'u.email', 'p.bio'])
+  .from('users u')
+  .where('u.active', '=', true)
+  .where('u.created_at', '>', new Date('2023-01-01'))
+  .whereIn('u.role', ['admin', 'user'])
+  .orderBy('u.created_at', 'DESC')
+  .limit(50)
+  .execute();
+```
+
+## Database Support
+
+BunQL works with all databases supported by Bun's native SQL bindings:
+
+- **PostgreSQL**: `postgres://user:pass@localhost:5432/db`
+- **MySQL**: `mysql://user:pass@localhost:3306/db`
+- **SQLite**: `sqlite://path/to/database.db` or `:memory:`
+
+## API Reference
+
+### BunQL
+
+Main class for building and executing queries.
+
+#### Methods
+
+- `select(columns?)`: Create a SELECT query
+- `insert(table)`: Create an INSERT query
+- `update(table)`: Create an UPDATE query
+- `delete(table)`: Create a DELETE query
+- `run(query, params?)`: Execute raw SQL
+- `all(query, params?)`: Execute raw SQL and return all results
+- `get(query, params?)`: Execute raw SQL and return first result
+- `begin(callback)`: Execute queries in a transaction
+
+### SelectQuery
+
+Methods for building SELECT queries.
+
+#### Methods
+
+- `from(table)`: Specify the table to select from
+- `where(column, operator, value)`: Add WHERE condition
+- `whereIn(column, values)`: Add WHERE IN condition
+- `whereNotIn(column, values)`: Add WHERE NOT IN condition
+- `orderBy(column, direction?)`: Add ORDER BY clause
+- `limit(count)`: Add LIMIT clause
+- `offset(count)`: Add OFFSET clause
+- `execute()`: Execute the query and return results
+- `first()`: Execute the query and return first result
+- `all()`: Alias for `execute()`
+
+### InsertQuery
+
+Methods for building INSERT queries.
+
+#### Methods
+
+- `values(data)`: Specify values to insert (object or array)
+- `execute()`: Execute the insert query
+
+### UpdateQuery
+
+Methods for building UPDATE queries.
+
+#### Methods
+
+- `set(data)`: Specify values to update
+- `where(column, operator, value)`: Add WHERE condition
+- `execute()`: Execute the update query
+
+### DeleteQuery
+
+Methods for building DELETE queries.
+
+#### Methods
+
+- `where(column, operator, value)`: Add WHERE condition
+- `execute()`: Execute the delete query
+
+## Error Handling
+
+```typescript
+try {
+  const result = await db.insert('users')
+    .values({ email: 'duplicate@example.com' })
+    .execute();
+} catch (error) {
+  if (error.code === 'ER_DUP_ENTRY') {
+    console.log('Duplicate email detected');
+  } else {
+    console.error('Database error:', error.message);
+  }
+}
+```
+
+## Performance Tips
+
+1. **Use transactions for bulk operations**:
+   ```typescript
+   await db.begin(async (tx) => {
+     for (const user of users) {
+       await tx.insert('users').values(user).execute();
+     }
+   });
+   ```
+
+2. **Use prepared statements** (automatic with parameterized queries):
+   ```typescript
+   // This automatically uses prepared statements
+   const user = await db.select('*')
+     .from('users')
+     .where('id', '=', userId)
+     .first();
+   ```
+
+3. **Use bulk inserts for multiple records**:
+   ```typescript
+   await db.insert('users').values(usersArray).execute();
+   ```
+
+## Testing
+
+```bash
+# Run tests
+bun test
+
+# Run tests in watch mode
+bun test --watch
+
+# Type checking
+bun run typecheck
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "bunql",
+  "version": "1.0.0",
+  "description": "A fluent SQL query builder for Bun with transaction support",
+  "module": "src/index.ts",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "keywords": [
+    "bun",
+    "sql",
+    "query-builder",
+    "database",
+    "postgresql",
+    "mysql",
+    "sqlite",
+    "transactions"
+  ],
+  "author": "Your Name",
+  "license": "MIT",
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "build": "bun build src/index.ts --outdir dist --target bun",
+    "dev": "bun run src/index.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "peerDependencies": {
+    "bun-types": "*"
+  },
+  "files": [
+    "src/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/bunql.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/bunql/issues"
+  },
+  "homepage": "https://github.com/yourusername/bunql#readme"
+}