flashorm 1.0.0__tar.gz

flashorm-1.0.0/LICENSE

@@ -0,0 +1,19 @@
+MIT Non-Commercial License (MIT-NC)
+
+Copyright (c) 2025 FlashORM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to use,
+copy, modify, merge, publish, and distribute copies of the Software for
+personal, educational, or non-commercial purposes only, 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.
+
+Commercial use of the Software (including use by any for-profit business or
+organization) requires a separate commercial license from the author.
+
+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.

flashorm-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include flashorm/bin *

flashorm-1.0.0/PKG-INFO

@@ -0,0 +1,615 @@
+Metadata-Version: 2.4
+Name: flashorm
+Version: 1.0.0
+Summary: A powerful, database-agnostic ORM with multi-database support and type-safe code generation
+Home-page: https://github.com/Lumos-Labs-HQ/flash
+Author: Rana718
+Author-email: 
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Lumos-Labs-HQ/flash
+Project-URL: Repository, https://github.com/Lumos-Labs-HQ/flash
+Project-URL: Issues, https://github.com/Lumos-Labs-HQ/flash/issues
+Keywords: orm,database,migration,postgresql,mysql,sqlite,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# FlashORM
+
+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 |
+| Insert 10 Cat + 5K Posts + 15K Comments | **2410ms** | 3028ms | 3977ms |
+| Complex Query x500 | **4071ms** | 12500ms | 56322ms |
+| Mixed Workload x1000 (75% read, 25% write) | **186ms** | 1174ms | 10863ms |
+| Stress Test Simple Query x2000 | **122ms** | 160ms | 223ms |
+| **TOTAL** | **6947ms** | **17149ms** | **71551ms** |
+
+## 🚀 Installation
+
+```bash
+pip install 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/flash/tree/main/example/ts)
+- [Go Example](https://github.com/Lumos-Labs-HQ/flash/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/flash)
+- [How It Works](https://github.com/Lumos-Labs-HQ/flash/blob/main/docs/HOW_IT_WORKS.md)
+- [Technology Stack](https://github.com/Lumos-Labs-HQ/flash/blob/main/docs/TECHNOLOGY_STACK.md)
+- [Contributing](https://github.com/Lumos-Labs-HQ/flash/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/flash/blob/main/LICENSE)
+
+---