hazo_connect 2.2.0 → 2.3.2

package/docs/examples/nextjs-singleton-pattern.ts

@@ -0,0 +1,166 @@
+/**
+ * Example: Singleton Pattern for hazo_connect in Next.js
+ * 
+ * This example shows how to use a singleton pattern to share
+ * a single hazo_connect instance across multiple API routes.
+ */
+
+// ============================================================================
+// Step 1: Create singleton instance
+// ============================================================================
+
+// lib/hazo_connect.ts
+import { getHazoConnectSingleton } from 'hazo_connect/nextjs/setup'
+import type { HazoConnectAdapter } from 'hazo_connect/server'
+
+/**
+ * Get the singleton hazo_connect adapter instance
+ * 
+ * This instance is created on first call and reused for all subsequent calls.
+ * Thread-safe for Next.js serverless environment.
+ */
+export const hazo: HazoConnectAdapter = getHazoConnectSingleton()
+
+// ============================================================================
+// Step 2: Use singleton in API routes
+// ============================================================================
+
+// app/api/users/route.ts
+import { NextResponse } from 'next/server'
+import { hazo } from '@/lib/hazo_connect'
+import { QueryBuilder } from 'hazo_connect/server'
+
+export async function GET() {
+  try {
+    // Use the shared singleton instance
+    const users = await hazo.query(
+      new QueryBuilder()
+        .from('users')
+        .select('*')
+        .order('name', 'asc')
+    )
+    
+    return NextResponse.json({ data: users })
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Unknown error' },
+      { status: 500 }
+    )
+  }
+}
+
+// app/api/posts/route.ts
+import { NextResponse } from 'next/server'
+import { hazo } from '@/lib/hazo_connect'
+import { QueryBuilder } from 'hazo_connect/server'
+
+export async function GET() {
+  try {
+    // Same singleton instance, different query
+    const posts = await hazo.query(
+      new QueryBuilder()
+        .from('posts')
+        .select('*')
+        .order('created_at', 'desc')
+        .limit(10)
+    )
+    
+    return NextResponse.json({ data: posts })
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Unknown error' },
+      { status: 500 }
+    )
+  }
+}
+
+// app/api/comments/route.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { hazo } from '@/lib/hazo_connect'
+import { QueryBuilder } from 'hazo_connect/server'
+
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url)
+    const postId = searchParams.get('post_id')
+    
+    let builder = new QueryBuilder()
+      .from('comments')
+      .select('*')
+    
+    if (postId) {
+      builder = builder.where('post_id', 'eq', postId)
+    }
+    
+    // Same singleton instance, filtered query
+    const comments = await hazo.query(builder)
+    
+    return NextResponse.json({ data: comments })
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Unknown error' },
+      { status: 500 }
+    )
+  }
+}
+
+// ============================================================================
+// Alternative: Manual Singleton Pattern
+// ============================================================================
+
+// lib/hazo_connect-manual.ts
+import { createHazoConnect } from 'hazo_connect/server'
+import type { HazoConnectAdapter } from 'hazo_connect/server'
+import path from 'path'
+
+let hazoInstance: HazoConnectAdapter | null = null
+
+/**
+ * Get or create the singleton hazo_connect adapter instance
+ */
+export function getHazoConnect(): HazoConnectAdapter {
+  if (!hazoInstance) {
+    hazoInstance = createHazoConnect({
+      type: 'sqlite',
+      sqlite: {
+        database_path: process.env.HAZO_CONNECT_SQLITE_PATH
+          ? path.resolve(process.env.HAZO_CONNECT_SQLITE_PATH)
+          : path.resolve(process.cwd(), 'database.sqlite'),
+        read_only: process.env.HAZO_CONNECT_SQLITE_READONLY === 'true'
+      },
+      enable_admin_ui: process.env.HAZO_CONNECT_ENABLE_ADMIN_UI === 'true'
+    })
+  }
+  
+  return hazoInstance
+}
+
+/**
+ * Reset the singleton (useful for testing)
+ */
+export function resetHazoConnect(): void {
+  hazoInstance = null
+}
+
+// Usage:
+// import { getHazoConnect } from '@/lib/hazo_connect-manual'
+// const hazo = getHazoConnect()
+
+// ============================================================================
+// Benefits of Singleton Pattern
+// ============================================================================
+
+/**
+ * Benefits:
+ * 
+ * 1. Single database connection shared across all API routes
+ * 2. Reduced memory usage (one instance instead of many)
+ * 3. Faster response times (no connection overhead per request)
+ * 4. Thread-safe in Next.js serverless environment
+ * 5. Configuration is centralized in one place
+ * 
+ * Note: The singleton is automatically created on first use and
+ * reused for all subsequent calls. If configuration changes,
+ * a new instance will be created automatically.
+ */
+

package/docs/migration-guide.md

@@ -0,0 +1,272 @@
+# Migration Guide for hazo_connect
+
+This guide helps you migrate existing code to use the new server-side entry points and patterns.
+
+## Table of Contents
+
+- [From Old Import Paths](#from-old-import-paths)
+- [From Client-Side to Server-Side](#from-client-side-to-server-side)
+- [From Direct Calls to API Routes](#from-direct-calls-to-api-routes)
+- [Testing Considerations](#testing-considerations)
+
+## From Old Import Paths
+
+### Before (Old Import)
+
+```typescript
+import { createHazoConnect, QueryBuilder } from 'hazo_connect'
+```
+
+### After (New Import)
+
+```typescript
+// For server-side code (API routes, Server Components, Server Actions)
+import { createHazoConnect, QueryBuilder } from 'hazo_connect/server'
+
+// For types in client components
+import type { HazoConnectConfig, HazoConnectAdapter } from 'hazo_connect'
+import type { TableSummary } from 'hazo_connect/ui'
+```
+
+### Migration Steps
+
+1. **Find all imports** of `hazo_connect` in your codebase
+2. **Replace server-side imports** with `hazo_connect/server`
+3. **Replace type imports** in client components with `hazo_connect` or `hazo_connect/ui`
+4. **Update test files** to use `hazo_connect/server`
+
+## From Client-Side to Server-Side
+
+### Before (Client Component - Won't Work)
+
+```typescript
+'use client'
+
+import { createHazoConnect } from 'hazo_connect'  // ❌ Old import
+
+export function MyComponent() {
+  const [data, setData] = useState([])
+  
+  useEffect(() => {
+    const hazo = createHazoConnect({ ... })
+    hazo.query(...).then(setData)
+  }, [])
+  
+  return <div>{/* render data */}</div>
+}
+```
+
+### After (Client Component - Correct Pattern)
+
+```typescript
+'use client'
+
+export function MyComponent() {
+  const [data, setData] = useState([])
+  
+  useEffect(() => {
+    // Fetch from API route instead
+    fetch('/api/data')
+      .then(res => res.json())
+      .then(json => setData(json.data))
+  }, [])
+  
+  return <div>{/* render data */}</div>
+}
+```
+
+```typescript
+// app/api/data/route.ts
+import { createHazoConnect } from 'hazo_connect/server'
+import { QueryBuilder } from 'hazo_connect/server'
+
+export async function GET() {
+  const hazo = createHazoConnect({ ... })
+  const data = await hazo.query(new QueryBuilder().from('table'))
+  return NextResponse.json({ data })
+}
+```
+
+## From Direct Calls to API Routes
+
+### Before (Direct Call in Server Component)
+
+```typescript
+// app/users/page.tsx
+import { createHazoConnect } from 'hazo_connect'  // ❌ Old import
+
+export default async function UsersPage() {
+  const hazo = createHazoConnect({ ... })
+  const users = await hazo.query(...)
+  
+  return <div>{/* render users */}</div>
+}
+```
+
+### After (Fetch from API Route)
+
+```typescript
+// app/users/page.tsx
+import { headers } from 'next/headers'
+
+export default async function UsersPage() {
+  const headersList = await headers()
+  const host = headersList.get('host') || 'localhost:3000'
+  
+  const response = await fetch(`http://${host}/api/users`, {
+    cache: 'no-store'
+  })
+  const { data: users } = await response.json()
+  
+  return <div>{/* render users */}</div>
+}
+```
+
+```typescript
+// app/api/users/route.ts
+import { createHazoConnect } from 'hazo_connect/server'
+import { QueryBuilder } from 'hazo_connect/server'
+
+export async function GET() {
+  const hazo = createHazoConnect({ ... })
+  const users = await hazo.query(new QueryBuilder().from('users'))
+  return NextResponse.json({ data: users })
+}
+```
+
+## Testing Considerations
+
+### Unit Tests
+
+Update test imports:
+
+```typescript
+// Before
+import { createHazoConnect } from 'hazo_connect'
+
+// After
+import { createHazoConnect } from 'hazo_connect/server'
+```
+
+### Integration Tests
+
+No changes needed - integration tests already use relative imports:
+
+```typescript
+// tests/integration/test.ts
+import { createHazoConnect } from '../../src/lib/factory'  // ✅ Still works
+```
+
+### Mocking in Tests
+
+```typescript
+// tests/setup.ts
+import { resetHazoConnectSingleton } from 'hazo_connect/nextjs/setup'
+
+beforeEach(() => {
+  resetHazoConnectSingleton()  // Reset singleton between tests
+})
+```
+
+## Common Migration Patterns
+
+### Pattern 1: API Route Migration
+
+**Before:**
+```typescript
+// pages/api/users.ts (Pages Router)
+import { createHazoConnect } from 'hazo_connect'
+
+export default async function handler(req, res) {
+  const hazo = createHazoConnect({ ... })
+  const users = await hazo.query(...)
+  res.json({ data: users })
+}
+```
+
+**After:**
+```typescript
+// app/api/users/route.ts (App Router)
+import { createHazoConnect } from 'hazo_connect/server'
+import { QueryBuilder } from 'hazo_connect/server'
+import { NextResponse } from 'next/server'
+
+export async function GET() {
+  const hazo = createHazoConnect({ ... })
+  const users = await hazo.query(new QueryBuilder().from('users'))
+  return NextResponse.json({ data: users })
+}
+```
+
+### Pattern 2: Server Component Migration
+
+**Before:**
+```typescript
+// components/UsersList.tsx
+import { createHazoConnect } from 'hazo_connect'
+
+export async function UsersList() {
+  const hazo = createHazoConnect({ ... })
+  const users = await hazo.query(...)
+  return <ul>{/* render */}</ul>
+}
+```
+
+**After:**
+```typescript
+// app/users/page.tsx
+import { headers } from 'next/headers'
+
+export default async function UsersPage() {
+  const headersList = await headers()
+  const host = headersList.get('host') || 'localhost:3000'
+  const response = await fetch(`http://${host}/api/users`, { cache: 'no-store' })
+  const { data: users } = await response.json()
+  return <ul>{/* render */}</ul>
+}
+```
+
+### Pattern 3: Singleton Pattern Migration
+
+**Before:**
+```typescript
+// Multiple API routes each creating their own instance
+// app/api/users/route.ts
+const hazo = createHazoConnect({ ... })
+
+// app/api/posts/route.ts
+const hazo = createHazoConnect({ ... })  // New instance each time
+```
+
+**After:**
+```typescript
+// lib/hazo_connect.ts
+import { getHazoConnectSingleton } from 'hazo_connect/nextjs/setup'
+export const hazo = getHazoConnectSingleton()
+
+// app/api/users/route.ts
+import { hazo } from '@/lib/hazo_connect'  // Shared instance
+
+// app/api/posts/route.ts
+import { hazo } from '@/lib/hazo_connect'  // Same shared instance
+```
+
+## Checklist
+
+When migrating:
+
+- [ ] Update all imports from `hazo_connect` to `hazo_connect/server` for runtime code
+- [ ] Update type imports in client components to `hazo_connect` or `hazo_connect/ui`
+- [ ] Move direct `hazo_connect` calls from Server Components to API routes
+- [ ] Update client components to fetch from API routes instead of calling `hazo_connect`
+- [ ] Update test files to use `hazo_connect/server`
+- [ ] Consider using singleton pattern for multiple API routes
+- [ ] Update Next.js configuration (see [Next.js Setup Guide](./nextjs-setup.md))
+- [ ] Test in development and production environments
+
+## Need Help?
+
+- See [Troubleshooting Guide](./troubleshooting.md) for common issues
+- See [Next.js Setup Guide](./nextjs-setup.md) for configuration
+- See [Code Examples](./examples/) for working patterns
+