flashorm 1.0.1

package/README.md

@@ -0,0 +1,601 @@
+# FlashORM ORM
+
+A powerful, database-agnostic migration CLI tool built in Go with multi-database support, visual database editor (FlashORM Studio), and type-safe code generation for JavaScript/TypeScript.
+
+## ✨ Features
+
+- 🎨 **FlashORM Studio**: Visual database editor with React-based schema visualization
+- 🗃️ **Multi-Database Support**: PostgreSQL, MySQL, SQLite
+- 🔄 **Migration Management**: Create, apply, and track migrations
+- 🔒 **Safe Migration System**: Transaction-based execution with automatic rollback
+- 📤 **Smart Export System**: Multiple formats (JSON, CSV, SQLite)
+- 🔧 **Type-Safe Code Generation**: Generate fully typed JavaScript/TypeScript code
+- ⚡ **Blazing Fast**: 2.5x faster than Drizzle, 10x faster than Prisma
+- 💻 **Raw SQL Execution**: Execute SQL files or inline queries
+- 🎯 **Prisma-like Commands**: Familiar CLI interface
+- 🎨 **Enum Support**: Full PostgreSQL ENUM support
+
+## 📊 Performance
+
+| Operation | FlashORM | Drizzle | Prisma |
+|-----------|-------|---------|--------|
+| Insert 1000 Users | **158ms** | 224ms | 230ms |
+| Complex Query x500 | **4071ms** | 12500ms | 56322ms |
+| Mixed Workload x1000 | **186ms** | 1174ms | 10863ms |
+| **TOTAL** | **6947ms** | **17149ms** | **71551ms** |
+
+## 🚀 Installation
+
+```bash
+npm install -g flashorm
+```
+
+### For Bun Users
+
+Bun blocks postinstall scripts by default. After installation, run:
+
+```bash
+bun pm trust flashorm
+```
+
+Or add to your `package.json`:
+```json
+{
+  "trustedDependencies": ["flashorm"]
+}
+```
+
+## 🏁 Quick Start
+
+### 1. Initialize Project
+
+```bash
+flash init --postgresql  # or --mysql, --sqlite
+```
+
+This creates:
+```
+your-project/
+├── flash.config.json
+├── .env
+└── db/
+    ├── schema/
+    │   └── schema.sql
+    └── queries/
+        └── users.sql
+```
+
+### 2. Configure Database
+
+```bash
+# .env file
+DATABASE_URL=postgresql://user:password@localhost:5432/mydb
+```
+
+### 3. Define Schema
+
+**db/schema/schema.sql**
+```sql
+CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    email VARCHAR(255) UNIQUE NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
+);
+```
+
+### 4. Write Queries
+
+**db/queries/users.sql**
+```sql
+-- name: GetUser :one
+SELECT id, name, email, created_at, updated_at FROM users
+WHERE id = $1 LIMIT 1;
+
+-- name: CreateUser :one
+INSERT INTO users (name, email)
+VALUES ($1, $2)
+RETURNING id, name, email, created_at, updated_at;
+
+-- name: ListUsers :many
+SELECT id, name, email, created_at, updated_at FROM users
+ORDER BY created_at DESC;
+
+-- name: UpdateUser :one
+UPDATE users
+SET name = $2, email = $3, updated_at = NOW()
+WHERE id = $1
+RETURNING id, name, email, created_at, updated_at;
+
+-- name: DeleteUser :exec
+DELETE FROM users WHERE id = $1;
+```
+
+### 5. Create Migration
+
+```bash
+flash migrate "create users table"
+```
+
+### 6. Apply Migration
+
+```bash
+flash apply
+```
+
+### 7. Generate Type-Safe Code
+
+```bash
+flash gen
+```
+
+**Generated Types (flash_gen/index.d.ts)**
+```typescript
+// Code generated by FlashORM. DO NOT EDIT.
+
+export interface Users {
+  id: number | null;
+  name: string;
+  email: string;
+  created_at: Date;
+  updated_at: Date;
+}
+
+export interface GetUserResult {
+  id: number | null;
+  name: string;
+  email: string;
+  created_at: Date;
+  updated_at: Date;
+}
+
+export class Queries {
+  constructor(db: any);
+
+  getUser(id: number): Promise<GetUserResult | null>;
+  createUser(name: string, email: string): Promise<Users | null>;
+  listUsers(): Promise<Users[]>;
+  updateUser(id: number, name: string, email: string): Promise<Users | null>;
+  deleteUser(id: number): Promise<void>;
+}
+
+export function New(db: any): Queries;
+```
+
+### 8. Use in Your Code
+
+**index.ts**
+```typescript
+import { Pool } from 'pg';
+import { New } from './flash_gen/database';
+
+const DATABASE_URL = process.env.DATABASE_URL || 'postgresql://postgres:postgres@localhost:5432/mydb';
+
+async function main() {
+    const pool = new Pool({
+        connectionString: DATABASE_URL,
+    });
+    
+    const db = New(pool);
+    
+    // Create user - fully type-safe!
+    const newUser = await db.createUser('Alice', 'alice@example.com');
+    console.log('New user:', newUser);
+    
+    // Get user by ID
+    const user = await db.getUser(newUser.id);
+    console.log('Found user:', user);
+    
+    // List all users
+    const users = await db.listUsers();
+    console.log('All users:', users);
+    
+    // Update user
+    const updated = await db.updateUser(newUser.id, 'Alice Smith', 'alice.smith@example.com');
+    console.log('Updated user:', updated);
+    
+    await pool.end();
+}
+
+main().catch((err) => {
+    console.error('Error:', err);
+    process.exit(1);
+});
+```
+
+## 📋 All Commands
+
+### Visual Database Editor
+
+```bash
+# Launch FlashORM Studio (web-based database editor)
+flash studio
+
+# Launch on custom port
+flash studio --port 3000
+
+# Connect to any database directly
+flash studio --db "postgresql://user:pass@localhost:5432/mydb"
+
+# Launch without opening browser
+flash studio --browser=false
+```
+
+**Studio Features:**
+- 📊 **Data Browser**: View and edit table data with inline editing
+- 💻 **SQL Editor**: Execute queries with CodeMirror syntax highlighting
+- 🎨 **Schema Visualization**: Interactive database diagram with React + ReactFlow
+- 📤 **CSV Export**: Export query results to CSV
+- 🔍 **Search & Filter**: Search across all tables
+- ⚡ **Real-time Updates**: See changes immediately
+
+### Project Setup
+
+```bash
+# Initialize new project
+flash init --postgresql
+flash init --mysql
+flash init --sqlite
+```
+
+### Migrations
+
+```bash
+# Create new migration
+flash migrate "migration name"
+
+# Create empty migration
+flash migrate "custom migration" --empty
+
+# Apply all pending migrations
+flash apply
+
+# Apply with force (skip confirmations)
+flash apply --force
+
+# Check migration status
+flash status
+```
+
+### Code Generation
+
+```bash
+# Generate type-safe code
+flash gen
+```
+
+### Schema Management
+
+```bash
+# Pull schema from existing database
+flash pull
+
+# Pull with backup
+flash pull --backup
+
+# Pull to custom file
+flash pull --output custom-schema.sql
+```
+
+### Database Export
+
+```bash
+# Export as JSON (default)
+flash export
+flash export --json
+
+# Export as CSV
+flash export --csv
+
+# Export as SQLite
+flash export --sqlite
+```
+
+### Database Operations
+
+```bash
+# Reset database (destructive!)
+flash reset
+
+# Reset with force
+flash reset --force
+
+# Execute raw SQL file
+flash raw script.sql
+flash raw migrations/seed.sql
+
+# Execute inline SQL query
+flash raw -q "SELECT * FROM users WHERE active = true"
+flash raw "SELECT COUNT(*) FROM orders"
+
+# Force file mode
+flash raw --file queries/complex.sql
+```
+
+### Help & Info
+
+```bash
+# Launch FlashORM Studio
+flash studio
+
+# Show version
+flash --version
+flash -v
+
+# Show help
+flash --help
+flash <command> --help
+```
+
+## ⚙️ Configuration
+
+**flash.config.json**
+```json
+{
+  "version": "2",
+  "schema_path": "db/schema/schema.sql",
+  "queries": "db/queries/",
+  "migrations_path": "db/migrations",
+  "export_path": "db/export",
+  "database": {
+    "provider": "postgresql",
+    "url_env": "DATABASE_URL"
+  },
+  "gen": {
+    "js": {
+      "enabled": true,
+    }
+  }
+}
+```
+
+## 🎨 PostgreSQL ENUM Support
+
+**Schema with ENUMs**
+```sql
+CREATE TYPE user_role AS ENUM ('admin', 'user', 'guest');
+
+CREATE TABLE users (
+    id SERIAL PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    role user_role NOT NULL DEFAULT 'user'
+);
+```
+
+**Query with ENUM**
+```sql
+-- name: GetUsersByRole :many
+SELECT id, name, role FROM users
+WHERE role = $1;
+```
+
+**Generated TypeScript**
+```typescript
+export type UserRole = 'admin' | 'user' | 'guest';
+
+export interface Users {
+  id: number | null;
+  name: string;
+  role: UserRole;
+}
+```
+
+## 🔒 Safe Migrations
+
+Every migration runs in a transaction with automatic rollback on failure:
+
+```bash
+$ flash apply
+📦 Applying 2 migration(s)...
+  [1/2] 20251103_create_users
+      ✅ Applied
+  [2/2] 20251103_add_email_index
+      ✅ Applied
+✅ All migrations applied successfully
+```
+
+If a migration fails:
+```bash
+❌ Failed at migration: 20251103_bad_migration
+   Error: syntax error at or near "INVALID"
+   Transaction rolled back. Fix the error and run 'flash apply' again.
+```
+
+## 🛡️ Conflict Detection
+
+FlashORM automatically detects schema conflicts:
+
+```bash
+⚠️  Migration conflicts detected:
+  - Table 'users' already exists
+  - Column 'email' conflicts with existing column
+
+Reset database to resolve conflicts? (y/n): y
+Create export before applying? (y/n): y
+📦 Creating export...
+✅ Export created successfully
+🔄 Resetting database and applying all migrations...
+```
+
+## 📤 Export Formats
+
+### JSON Export
+```bash
+flash export --json
+```
+```json
+{
+  "timestamp": "2025-11-03 16:30:00",
+  "version": "1.0",
+  "tables": {
+    "users": [
+      {"id": 1, "name": "Alice", "email": "alice@example.com"}
+    ]
+  }
+}
+```
+
+### CSV Export
+```bash
+flash export --csv
+```
+Creates directory with individual CSV files per table.
+
+### SQLite Export
+```bash
+flash export --sqlite
+```
+Creates portable `.db` file.
+
+## 🎨 FlashORM Studio
+
+Launch the visual database editor:
+
+```bash
+flash studio
+```
+
+Open http://localhost:5555 (or your custom port)
+
+**Features:**
+
+### 1. Data Browser (`/`)
+- View all tables in sidebar
+- Click any table to view/edit data
+- Double-click cells for inline editing
+- Add/delete rows with intuitive modals
+- Pagination (50 rows per page)
+- Search across tables
+- Foreign key hints
+
+### 2. SQL Editor (`/sql`)
+- Execute custom SQL queries
+- CodeMirror editor with syntax highlighting
+- Press Ctrl+Enter to run queries
+- Export results to CSV
+- Resizable split-pane interface
+- Query history
+
+### 3. Schema Visualization (`/schema`)
+- Interactive database diagram
+- React + ReactFlow rendering
+- Automatic layout with Dagre algorithm
+- Drag and drop tables
+- Zoom and pan controls
+- Foreign key relationship arrows
+- MiniMap for navigation
+
+**Tech Stack:**
+- Backend: Go Fiber v2.52.9
+- Frontend: React 18.2.0, ReactFlow 12.8.4, CodeMirror 5.65.2
+- All assets embedded in single binary
+
+## 💻 Raw SQL Execution
+
+Execute SQL files or inline queries:
+
+```bash
+# Execute SQL file
+flash raw script.sql
+
+# Execute inline query
+flash raw -q "SELECT * FROM users LIMIT 10"
+
+# Auto-detection (file if exists, otherwise query)
+flash raw "SELECT COUNT(*) FROM orders"
+```
+
+**Features:**
+- ✅ Beautiful table output for SELECT queries
+- ✅ Multi-statement execution
+- ✅ Transaction support
+- ✅ Auto-detection of file vs query
+- ✅ Formatted error messages
+
+**Example Output:**
+```bash
+$ flash raw -q "SELECT id, name, email FROM users LIMIT 3"
+
+🎯 Database: postgresql
+
+⚡ Executing query...
+✅ Query executed successfully
+📊 3 row(s) returned
+
+┌────┬────────────┬─────────────────────┐
+│ id │ name       │ email               │
+├────┼────────────┼─────────────────────┤
+│ 1  │ Alice      │ alice@example.com   │
+│ 2  │ Bob        │ bob@example.com     │
+│ 3  │ Charlie    │ charlie@example.com │
+└────┴────────────┴─────────────────────┘
+```
+
+## 🔧 Programmatic API
+
+```javascript
+const flash = require('flashorm');
+
+// Execute commands
+flash.exec('status');
+flash.exec('migrate "add users"');
+flash.exec('apply');
+flash.exec('studio'); // Launch Studio
+
+// Get binary path
+const binaryPath = flash.getBinaryPath();
+```
+
+## 📚 Examples
+
+Check out complete examples:
+- [TypeScript Example](https://github.com/Lumos-Labs-HQ/FlashORM/tree/main/example/ts)
+- [Go Example](https://github.com/Lumos-Labs-HQ/FlashORM/tree/main/example/go)
+
+## 🐛 Troubleshooting
+
+### Bun Postinstall Blocked
+
+```bash
+bun pm trust flashorm
+```
+
+### Binary Not Found
+
+```bash
+npm install -g flashorm --force
+```
+
+### Database Connection Failed
+
+Check your `DATABASE_URL` in `.env` file.
+
+### Studio Not Loading
+
+Make sure port 5555 is not in use, or specify a different port:
+```bash
+flash studio --port 3000
+```
+
+## 📖 Documentation
+
+- [Full Documentation](https://github.com/Lumos-Labs-HQ/FlashORM)
+- [How It Works](https://github.com/Lumos-Labs-HQ/FlashORM/blob/main/docs/HOW_IT_WORKS.md)
+- [Technology Stack](https://github.com/Lumos-Labs-HQ/FlashORM/blob/main/docs/TECHNOLOGY_STACK.md)
+- [Contributing](https://github.com/Lumos-Labs-HQ/FlashORM/blob/main/docs/CONTRIBUTING.md)
+
+## 🌟 Key Highlights
+
+- **Visual Database Editor**: Manage your database visually with FlashORM Studio
+- **Raw SQL Support**: Execute SQL files or queries directly from CLI
+- **Type-Safe**: Full TypeScript support with generated types
+- **Fast**: 2.5x-10x faster than popular ORMs
+- **Multi-DB**: PostgreSQL, MySQL, and SQLite support
+- **Zero Config**: Works out of the box with sensible defaults
+
+## 📄 License
+
+MIT License - see [LICENSE](https://github.com/Lumos-Labs-HQ/FlashORM/blob/main/LICENSE)
+
+---

package/bin/flash.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const platform = process.platform;
+const binaryName = platform === 'win32' ? 'flash.exe' : 'flash';
+const binaryPath = path.join(__dirname, binaryName);
+
+if (!fs.existsSync(binaryPath)) {
+  console.error('❌ flash binary not found. Please reinstall: npm install -g FlashORM-orm');
+  process.exit(1);
+}
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});
+
+child.on('error', (err) => {
+  console.error('❌ Failed to start flash:', err);
+  process.exit(1);
+});

package/index.js

@@ -0,0 +1,28 @@
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+function getBinaryPath() {
+  const platform = process.platform;
+  const binaryName = platform === 'win32' ? 'flash.exe' : 'flash';
+  const binaryPath = path.join(__dirname, 'bin', binaryName);
+  
+  if (!fs.existsSync(binaryPath)) {
+    throw new Error('flash binary not found. Please reinstall: npm install -g FlashORM-orm');
+  }
+  
+  return binaryPath;
+}
+
+function exec(command, options = {}) {
+  const binaryPath = getBinaryPath();
+  return execSync(`"${binaryPath}" ${command}`, {
+    encoding: 'utf8',
+    ...options
+  });
+}
+
+module.exports = {
+  getBinaryPath,
+  exec
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "flashorm",
+  "version": "1.0.1",
+  "description": "A powerful, database-agnostic migration CLI tool with multi-database support and type-safe code generation",
+  "main": "index.js",
+  "bin": {
+    "flash": "./bin/flash.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "keywords": [
+    "orm",
+    "database",
+    "migration",
+    "sqlc",
+    "postgresql",
+    "mysql",
+    "sqlite",
+    "cli",
+    "typescript",
+    "javascript",
+    "type-safe"
+  ],
+  "author": "Rana718",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Lumos-Labs-HQ/FlashORM.git"
+  },
+  "homepage": "https://github.com/Lumos-Labs-HQ/FlashORM#readme",
+  "bugs": {
+    "url": "https://github.com/Lumos-Labs-HQ/FlashORM/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "bin/",
+    "scripts/",
+    "index.js",
+    "README.md"
+  ]
+}

package/scripts/install.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+
+const VERSION = '1.0.1';
+const REPO = 'Lumos-Labs-HQ/FlashORM';
+
+const platform = process.platform;
+const arch = process.arch;
+
+const platformMap = {
+  'darwin': 'darwin',
+  'linux': 'linux',
+  'win32': 'windows'
+};
+
+const archMap = {
+  'x64': 'amd64',
+  'arm64': 'arm64'
+};
+
+const mappedPlatform = platformMap[platform];
+const mappedArch = archMap[arch];
+
+if (!mappedPlatform || !mappedArch) {
+  console.error(`❌ Unsupported platform: ${platform}-${arch}`);
+  process.exit(1);
+}
+
+const binaryName = platform === 'win32' ? 'flash.exe' : 'flash';
+const downloadName = `flash-${mappedPlatform}-${mappedArch}${platform === 'win32' ? '.exe' : ''}`;
+const downloadUrl = `https://github.com/${REPO}/releases/download/v${VERSION}/${downloadName}`;
+
+const binDir = path.join(__dirname, '..', 'bin');
+const binaryPath = path.join(binDir, binaryName);
+
+console.log(`📦 Installing flash v${VERSION} for ${platform}-${arch}...`);
+console.log(`📥 Downloading from: ${downloadUrl}`);
+
+if (!fs.existsSync(binDir)) {
+  fs.mkdirSync(binDir, { recursive: true });
+}
+
+const file = fs.createWriteStream(binaryPath);
+
+https.get(downloadUrl, (response) => {
+  if (response.statusCode === 302 || response.statusCode === 301) {
+    https.get(response.headers.location, (redirectResponse) => {
+      redirectResponse.pipe(file);
+      file.on('finish', () => {
+        file.close(() => {
+          fs.chmodSync(binaryPath, 0o755);
+          console.log(`✅ flash installed successfully!`);
+          console.log(`🚀 Run 'flash --help' to get started!`);
+        });
+      });
+    });
+  } else {
+    response.pipe(file);
+    file.on('finish', () => {
+      file.close(() => {
+        fs.chmodSync(binaryPath, 0o755);
+        console.log(`✅ flash installed successfully!`);
+        console.log(`🚀 Run 'flash --help' to get started!`);
+      });
+    });
+  }
+}).on('error', (err) => {
+  fs.unlinkSync(binaryPath);
+  console.error(`❌ Download failed: ${err.message}`);
+  console.error(`Please check: ${downloadUrl}`);
+  process.exit(1);
+});