hazo_connect 2.2.0 → 2.3.2

package/docs/types.md

@@ -0,0 +1,490 @@
+# Type Definitions Reference for hazo_connect
+
+Complete TypeScript type reference for `hazo_connect`.
+
+## Table of Contents
+
+- [Core Types](#core-types)
+- [Configuration Types](#configuration-types)
+- [Query Builder Types](#query-builder-types)
+- [Adapter Types](#adapter-types)
+- [Error Types](#error-types)
+- [SQLite Admin Types](#sqlite-admin-types)
+
+## Core Types
+
+### HazoConnectConfig
+
+Main configuration interface for creating adapters.
+
+```typescript
+import type { HazoConnectConfig } from 'hazo_connect'
+
+interface HazoConnectConfig {
+  type: ConnectionType
+  logger?: Logger
+  configProvider?: ConfigProvider
+  enable_admin_ui?: boolean  // For SQLite admin UI
+  [key: string]: any  // Provider-specific config
+}
+```
+
+**Example:**
+```typescript
+const config: HazoConnectConfig = {
+  type: 'sqlite',
+  enable_admin_ui: true,
+  sqlite: {
+    database_path: './database.sqlite'
+  }
+}
+```
+
+### ConnectionType
+
+Supported database connection types.
+
+```typescript
+type ConnectionType = 'postgrest' | 'supabase' | 'sqlite' | 'file'
+```
+
+### HazoConnectAdapter
+
+Interface that all adapters implement.
+
+```typescript
+import type { HazoConnectAdapter } from 'hazo_connect'
+
+interface HazoConnectAdapter {
+  query(
+    builder: QueryBuilder,
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+    body?: any
+  ): Promise<any>
+  
+  rawQuery(endpoint: string, options?: RequestInit): Promise<any>
+  
+  getConfig(): Promise<any>
+}
+```
+
+**Return Types:**
+- `query()`: Returns `Promise<any[]>` for GET requests, `Promise<any>` for mutations
+- `rawQuery()`: Returns `Promise<any[]>` for SELECT, `Promise<any>` for mutations
+- `getConfig()`: Returns `Promise<AdapterSpecificConfig>`
+
+## Configuration Types
+
+### PostgREST Configuration
+
+```typescript
+interface PostgrestConfig {
+  postgrest: {
+    base_url: string
+    api_key: string
+  }
+}
+```
+
+### SQLite Configuration
+
+```typescript
+interface SqliteConfig {
+  sqlite: {
+    database_path?: string  // Optional - in-memory if omitted
+    read_only?: boolean      // Default: false
+    initial_sql?: string[]   // Optional seed statements
+    wasm_directory?: string // Optional WASM file directory
+  }
+}
+```
+
+### Supabase Configuration
+
+```typescript
+interface SupabaseConfig {
+  supabase: {
+    url: string
+    anon_key: string
+    service_role_key?: string
+  }
+}
+```
+
+## Query Builder Types
+
+### QueryOperator
+
+Supported query operators.
+
+```typescript
+type QueryOperator = 
+  | 'eq'      // equals
+  | 'neq'     // not equals
+  | 'gt'      // greater than
+  | 'gte'     // greater than or equal
+  | 'lt'      // less than
+  | 'lte'     // less than or equal
+  | 'like'    // like (case-sensitive)
+  | 'ilike'   // like (case-insensitive)
+  | 'in'      // in array
+  | 'is'      // is null/not null
+  | 'or'      // or condition
+```
+
+### WhereCondition
+
+Condition structure for WHERE clauses.
+
+```typescript
+interface WhereCondition {
+  field: string
+  operator: QueryOperator
+  value: any
+}
+```
+
+### OrderDirection
+
+Sort direction.
+
+```typescript
+type OrderDirection = 'asc' | 'desc'
+```
+
+### JoinType
+
+Join types for table joins.
+
+```typescript
+type JoinType = 'inner' | 'left' | 'right'
+```
+
+### NestedSelect
+
+Nested select structure (PostgREST).
+
+```typescript
+interface NestedSelect {
+  table: string
+  fields: string[]
+}
+```
+
+## Adapter Types
+
+### PostgrestAdapter
+
+```typescript
+import { PostgrestAdapter } from 'hazo_connect/server'
+
+const adapter = new PostgrestAdapter(config, logger)
+```
+
+### SqliteAdapter
+
+```typescript
+import { SqliteAdapter } from 'hazo_connect/server'
+
+const adapter = new SqliteAdapter(config, logger)
+```
+
+## Error Types
+
+### ErrorCode
+
+Error code enumeration.
+
+```typescript
+import { ErrorCode } from 'hazo_connect/server'
+
+enum ErrorCode {
+  CONFIG_ERROR = 'HAZO_CONNECT_CONFIG_ERROR',
+  CONNECTION_FAILED = 'HAZO_CONNECT_CONNECTION_FAILED',
+  QUERY_ERROR = 'HAZO_CONNECT_QUERY_ERROR',
+  NOT_IMPLEMENTED = 'HAZO_CONNECT_NOT_IMPLEMENTED',
+  VALIDATION_ERROR = 'HAZO_CONNECT_VALIDATION_ERROR'
+}
+```
+
+### HazoConnectError
+
+Standardized error response.
+
+```typescript
+interface HazoConnectError {
+  code: string  // ErrorCode enum value
+  message: string
+  statusCode?: number
+  originalError?: any
+}
+```
+
+**Error Handling Example:**
+```typescript
+try {
+  const result = await hazo.query(builder)
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('Error code:', error.code)
+    console.error('Error message:', error.message)
+  }
+}
+```
+
+## SQLite Admin Types
+
+### TableSummary
+
+Summary information about a table.
+
+```typescript
+import type { TableSummary } from 'hazo_connect/ui'
+
+interface TableSummary {
+  name: string
+  type: 'table' | 'view'
+  row_count: number | null
+}
+```
+
+### TableSchema
+
+Complete table schema information.
+
+```typescript
+import type { TableSchema } from 'hazo_connect/ui'
+
+interface TableSchema {
+  columns: TableColumn[]
+  foreign_keys: TableForeignKey[]
+}
+```
+
+### TableColumn
+
+Column definition.
+
+```typescript
+import type { TableColumn } from 'hazo_connect/ui'
+
+interface TableColumn {
+  cid: number
+  name: string
+  type: string
+  notnull: boolean
+  default_value: unknown
+  primary_key_position: number
+}
+```
+
+### TableForeignKey
+
+Foreign key definition.
+
+```typescript
+import type { TableForeignKey } from 'hazo_connect/ui'
+
+interface TableForeignKey {
+  id: number
+  seq: number
+  table: string
+  from: string
+  to: string
+  on_update: string
+  on_delete: string
+  match: string
+}
+```
+
+### RowPage
+
+Paginated row data.
+
+```typescript
+import type { RowPage } from 'hazo_connect/ui'
+
+interface RowPage {
+  rows: Record<string, unknown>[]
+  total: number
+}
+```
+
+### SqliteWhereFilter
+
+Filter for SQLite queries.
+
+```typescript
+import type { SqliteWhereFilter } from 'hazo_connect/ui'
+
+interface SqliteWhereFilter {
+  column: string
+  operator: SqliteFilterOperator
+  value: unknown
+}
+```
+
+### SqliteFilterOperator
+
+Supported filter operators for SQLite.
+
+```typescript
+import type { SqliteFilterOperator } from 'hazo_connect/ui'
+
+type SqliteFilterOperator =
+  | 'eq'
+  | 'neq'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'like'
+  | 'ilike'
+  | 'is'
+```
+
+## Logger Interface
+
+### Logger
+
+Optional logger interface for dependency injection.
+
+```typescript
+import type { Logger } from 'hazo_connect'
+
+interface Logger {
+  debug(message: string, data?: Record<string, unknown>): void
+  info(message: string, data?: Record<string, unknown>): void
+  warn(message: string, data?: Record<string, unknown>): void
+  error(message: string, data?: Record<string, unknown>): void
+}
+```
+
+**Example:**
+```typescript
+const logger: Logger = {
+  debug: (msg, data) => console.log('[DEBUG]', msg, data),
+  info: (msg, data) => console.log('[INFO]', msg, data),
+  warn: (msg, data) => console.warn('[WARN]', msg, data),
+  error: (msg, data) => console.error('[ERROR]', msg, data),
+}
+
+const hazo = createHazoConnect({ type: 'sqlite', logger, ... })
+```
+
+## Next.js Helper Types
+
+### CreateHazoConnectFromEnvOptions
+
+Options for environment-based adapter creation.
+
+```typescript
+import type { CreateHazoConnectFromEnvOptions } from 'hazo_connect/nextjs/setup'
+
+interface CreateHazoConnectFromEnvOptions {
+  type?: 'sqlite' | 'postgrest' | 'supabase' | 'file'
+  sqlitePath?: string
+  readOnly?: boolean
+  enableAdminUi?: boolean
+  logger?: Logger
+}
+```
+
+### ApiRouteHandler
+
+Handler function for API route helpers.
+
+```typescript
+import type { ApiRouteHandler } from 'hazo_connect/nextjs'
+
+type ApiRouteHandler = (
+  hazo: HazoConnectAdapter,
+  request: NextRequest
+) => Promise<NextResponse | Response>
+```
+
+## Type Usage Examples
+
+### Type-Safe Configuration
+
+```typescript
+import type { HazoConnectConfig } from 'hazo_connect'
+import { createHazoConnect } from 'hazo_connect/server'
+
+const config: HazoConnectConfig = {
+  type: 'sqlite',
+  sqlite: {
+    database_path: './db.sqlite'
+  }
+}
+
+const hazo = createHazoConnect(config)
+```
+
+### Type-Safe Query Results
+
+```typescript
+interface User {
+  id: number
+  name: string
+  email: string
+}
+
+const users = await hazo.query(
+  new QueryBuilder().from('users').select('*')
+) as User[]
+```
+
+### Type-Safe Error Handling
+
+```typescript
+import { ErrorCode } from 'hazo_connect/server'
+
+try {
+  await hazo.query(builder)
+} catch (error: any) {
+  if (error.code === ErrorCode.CONFIG_ERROR) {
+    // Handle configuration error
+  } else if (error.code === ErrorCode.QUERY_ERROR) {
+    // Handle query error
+  }
+}
+```
+
+## Import Paths
+
+### Server-Side Types
+
+```typescript
+import type {
+  HazoConnectConfig,
+  HazoConnectAdapter,
+  Logger,
+  ConnectionType
+} from 'hazo_connect/server'
+```
+
+### Client-Side Types
+
+```typescript
+import type {
+  HazoConnectConfig,
+  HazoConnectAdapter
+} from 'hazo_connect'
+
+import type {
+  TableSummary,
+  TableSchema,
+  TableColumn
+} from 'hazo_connect/ui'
+```
+
+### Next.js Helper Types
+
+```typescript
+import type {
+  CreateHazoConnectFromEnvOptions,
+  ApiRouteHandler
+} from 'hazo_connect/nextjs'
+```
+

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "hazo_connect",
-  "version": "2.2.0",
+  "version": "2.3.2",
   "description": "Module to connect to the data store (postgres via postgrest, supabase, etc)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
     "app",
+    "scripts",
+    "docs",
     "README.md"
   ],
+  "bin": {
+    "hazo-connect-setup-routes": "./scripts/setup-routes.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -22,6 +27,10 @@
       "types": "./dist/nextjs/index.d.ts",
       "default": "./dist/nextjs/index.js"
     },
+    "./nextjs/setup": {
+      "types": "./dist/nextjs/setup-helpers.d.ts",
+      "default": "./dist/nextjs/setup-helpers.js"
+    },
     "./ui": {
       "types": "./dist/ui/index.d.ts",
       "default": "./dist/ui/index.js"
@@ -42,7 +51,7 @@
     "test:integration": "POSTGREST_INTEGRATION=true jest --runInBand tests/integration/postgrest.integration.test.ts",
     "test:integration:sqlite": "jest --runInBand tests/integration/sqlite.integration.test.ts",
     "prepublishOnly": "npm run build:lib",
-    "postinstall": "patch-package"
+    "postinstall": "patch-package && node scripts/postinstall-setup.js"
   },
   "repository": {
     "type": "git",
@@ -85,11 +94,11 @@
     "@types/sql.js": "^1.4.9",
     "autoprefixer": "^10.4.19",
     "eslint": "^8.57.0",
-    "eslint-config-next": "14.2.5",
+    "eslint-config-next": "14.2.33",
     "jest": "^30.2.0",
     "jest-environment-node": "^30.2.0",
     "lucide-react": "^0.553.0",
-    "next": "14.2.5",
+    "next": "14.2.33",
     "patch-package": "^8.0.1",
     "postcss": "^8.4.39",
     "react": "18.3.1",
@@ -100,5 +109,8 @@
     "ts-jest": "^29.4.5",
     "tsx": "^4.17.0",
     "typescript": "^5.5.4"
+  },
+  "overrides": {
+    "glob": "^10.4.6"
   }
 }

package/scripts/postinstall-setup.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+/**
+ * Purpose: Postinstall script to optionally setup SQLite admin routes
+ * 
+ * This script runs after npm install and checks if HAZO_CONNECT_ENABLE_ADMIN_UI
+ * is set to 'true'. If so, it automatically sets up the admin routes.
+ * 
+ * This is called from package.json postinstall script.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+// Only run if we're in a Next.js project (has app or pages directory)
+function isNextJsProject() {
+  const cwd = process.cwd()
+  return fs.existsSync(path.join(cwd, 'app')) || fs.existsSync(path.join(cwd, 'pages'))
+}
+
+// Check if admin UI is enabled
+function isAdminUiEnabled() {
+  // Check environment variable
+  if (process.env.HAZO_CONNECT_ENABLE_ADMIN_UI === 'true') {
+    return true
+  }
+  
+  // Check .env files
+  const envFiles = ['.env.local', '.env', '.env.development']
+  for (const envFile of envFiles) {
+    const envPath = path.join(process.cwd(), envFile)
+    if (fs.existsSync(envPath)) {
+      const content = fs.readFileSync(envPath, 'utf-8')
+      if (content.includes('HAZO_CONNECT_ENABLE_ADMIN_UI=true')) {
+        return true
+      }
+    }
+  }
+  
+  return false
+}
+
+function main() {
+  // Only run in Next.js projects
+  if (!isNextJsProject()) {
+    return
+  }
+  
+  // Only setup routes if admin UI is enabled
+  if (!isAdminUiEnabled()) {
+    return
+  }
+  
+  // Check if routes already exist
+  const targetRoutesDir = path.join(process.cwd(), 'app', 'hazo_connect')
+  if (fs.existsSync(targetRoutesDir)) {
+    return
+  }
+  
+  // Run the setup script
+  try {
+    process.env.SILENT = '1' // Suppress output during postinstall
+    const setupModule = require('./setup-routes.js')
+    setupModule.main()
+  } catch (error) {
+    // Silently fail - user can run setup manually if needed
+    // Don't log errors during postinstall to avoid noise
+  }
+}
+
+main()
+