@geekmidas/studio 0.0.1

package/src/server/hono.ts

@@ -0,0 +1,225 @@
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+import type { DataBrowser } from '../data/DataBrowser';
+import {
+  Direction,
+  type FilterCondition,
+  FilterOperator,
+  type SortConfig,
+} from '../types';
+import { getAsset, getIndexHtml } from '../ui-assets';
+
+/**
+ * Interface for the Studio instance used by the Hono adapter.
+ * Only requires the data browser - monitoring routes are separate.
+ */
+export interface StudioLike {
+  data: DataBrowser<unknown>;
+}
+
+/**
+ * Parse filter conditions from query parameters.
+ * Format: filter[column][operator]=value
+ * Example: filter[name][eq]=John&filter[age][gt]=18
+ */
+function parseFilters(c: Context): FilterCondition[] {
+  const filters: FilterCondition[] = [];
+  const url = new URL(c.req.url);
+
+  url.searchParams.forEach((value, key) => {
+    const match = key.match(/^filter\[(\w+)\]\[(\w+)\]$/);
+    if (match) {
+      const [, column, operator] = match;
+      const op = operator as FilterOperator;
+
+      // Validate operator
+      if (!Object.values(FilterOperator).includes(op)) {
+        return;
+      }
+
+      // Handle special cases
+      if (op === FilterOperator.In || op === FilterOperator.Nin) {
+        filters.push({ column, operator: op, value: value.split(',') });
+      } else if (
+        op === FilterOperator.IsNull ||
+        op === FilterOperator.IsNotNull
+      ) {
+        filters.push({ column, operator: op });
+      } else {
+        // Try to parse as number or boolean
+        let parsedValue: unknown = value;
+        if (value === 'true') parsedValue = true;
+        else if (value === 'false') parsedValue = false;
+        else if (!isNaN(Number(value)) && value !== '')
+          parsedValue = Number(value);
+
+        filters.push({ column, operator: op, value: parsedValue });
+      }
+    }
+  });
+
+  return filters;
+}
+
+/**
+ * Parse sort configuration from query parameters.
+ * Format: sort=column:direction,column:direction
+ * Example: sort=name:asc,created_at:desc
+ */
+function parseSort(c: Context): SortConfig[] {
+  const sortParam = c.req.query('sort');
+  if (!sortParam) return [];
+
+  return sortParam.split(',').map((part) => {
+    const [column, dir] = part.split(':');
+    return {
+      column,
+      direction: dir === 'desc' ? Direction.Desc : Direction.Asc,
+    };
+  });
+}
+
+/**
+ * Create Hono app with Studio API routes and dashboard UI.
+ */
+export function createStudioApp(studio: StudioLike): Hono {
+  const app = new Hono();
+
+  // ============================================
+  // Schema API
+  // ============================================
+
+  /**
+   * GET /api/schema
+   * Get the complete database schema
+   */
+  app.get('/api/schema', async (c) => {
+    const forceRefresh = c.req.query('refresh') === 'true';
+    const schema = await studio.data.getSchema(forceRefresh);
+    return c.json(schema);
+  });
+
+  /**
+   * GET /api/tables
+   * List all tables with basic info
+   */
+  app.get('/api/tables', async (c) => {
+    const schema = await studio.data.getSchema();
+    const tables = schema.tables.map((t) => ({
+      name: t.name,
+      schema: t.schema,
+      columnCount: t.columns.length,
+      primaryKey: t.primaryKey,
+      estimatedRowCount: t.estimatedRowCount,
+    }));
+    return c.json({ tables });
+  });
+
+  /**
+   * GET /api/tables/:name
+   * Get detailed information about a specific table
+   */
+  app.get('/api/tables/:name', async (c) => {
+    const tableName = c.req.param('name');
+    const tableInfo = await studio.data.getTableInfo(tableName);
+
+    if (!tableInfo) {
+      return c.json({ error: `Table '${tableName}' not found` }, 404);
+    }
+
+    return c.json(tableInfo);
+  });
+
+  /**
+   * GET /api/tables/:name/rows
+   * Query table data with pagination, filtering, and sorting
+   *
+   * Query parameters:
+   * - pageSize: number (default: 50, max: 100)
+   * - cursor: string (pagination cursor)
+   * - filter[column][operator]=value (e.g., filter[status][eq]=active)
+   * - sort=column:direction (e.g., sort=created_at:desc)
+   */
+  app.get('/api/tables/:name/rows', async (c) => {
+    const tableName = c.req.param('name');
+    const pageSize = Math.min(
+      parseInt(c.req.query('pageSize') || '50', 10),
+      100,
+    );
+    const cursor = c.req.query('cursor') || undefined;
+    const filters = parseFilters(c);
+    const sort = parseSort(c);
+
+    try {
+      const result = await studio.data.query({
+        table: tableName,
+        pageSize,
+        cursor,
+        filters: filters.length > 0 ? filters : undefined,
+        sort: sort.length > 0 ? sort : undefined,
+      });
+
+      return c.json(result);
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('not found')) {
+        return c.json({ error: error.message }, 404);
+      }
+      throw error;
+    }
+  });
+
+  // ============================================
+  // Static Assets & Dashboard UI
+  // ============================================
+
+  // Static assets
+  app.get('/assets/:filename', (c) => {
+    const filename = c.req.param('filename');
+    const assetPath = `assets/${filename}`;
+    const asset = getAsset(assetPath);
+    if (asset) {
+      return c.body(asset.content, 200, {
+        'Content-Type': asset.contentType,
+        'Cache-Control': 'public, max-age=31536000, immutable',
+      });
+    }
+    return c.notFound();
+  });
+
+  // Dashboard UI - serve React app
+  app.get('/', (c) => {
+    const html = getIndexHtml();
+    if (!html) {
+      return c.json({
+        message: 'Studio API is running',
+        note: 'UI not available. Run "pnpm build:ui" first.',
+        endpoints: {
+          schema: '/api/schema',
+          tables: '/api/tables',
+          tableInfo: '/api/tables/:name',
+          tableRows: '/api/tables/:name/rows',
+        },
+      });
+    }
+    return c.html(html);
+  });
+
+  // SPA fallback - serve index.html for client-side routing
+  app.get('/*', (c) => {
+    // Skip API routes
+    if (c.req.path.startsWith('/api/')) {
+      return c.notFound();
+    }
+
+    const html = getIndexHtml();
+    if (!html) {
+      return c.notFound();
+    }
+    return c.html(html);
+  });
+
+  return app;
+}
+
+// Re-export types
+export type { StudioLike, DataBrowser };

package/src/types.ts

@@ -0,0 +1,278 @@
+import type { TelescopeStorage } from '@geekmidas/telescope';
+import type { Kysely } from 'kysely';
+
+// ============================================
+// Enums
+// ============================================
+
+/**
+ * Sort direction for cursor-based pagination and sorting.
+ */
+export enum Direction {
+  Asc = 'asc',
+  Desc = 'desc',
+}
+
+/**
+ * Filter operators for querying data.
+ */
+export enum FilterOperator {
+  Eq = 'eq',
+  Neq = 'neq',
+  Gt = 'gt',
+  Gte = 'gte',
+  Lt = 'lt',
+  Lte = 'lte',
+  Like = 'like',
+  Ilike = 'ilike',
+  In = 'in',
+  Nin = 'nin',
+  IsNull = 'is_null',
+  IsNotNull = 'is_not_null',
+}
+
+// ============================================
+// Cursor Configuration
+// ============================================
+
+/**
+ * Configuration for cursor-based pagination.
+ */
+export interface CursorConfig {
+  /** The field to use for cursor-based pagination (e.g., 'id', 'created_at') */
+  field: string;
+  /** Sort direction for the cursor field */
+  direction: Direction;
+}
+
+/**
+ * Per-table cursor configuration overrides.
+ */
+export interface TableCursorConfig {
+  [tableName: string]: CursorConfig;
+}
+
+// ============================================
+// Monitoring Configuration
+// ============================================
+
+/**
+ * Configuration for the monitoring feature (Telescope).
+ */
+export interface MonitoringOptions {
+  /** Storage backend for monitoring data */
+  storage: TelescopeStorage;
+  /** Patterns to ignore when recording requests (supports wildcards) */
+  ignorePatterns?: string[];
+  /** Whether to record request/response bodies (default: true) */
+  recordBody?: boolean;
+  /** Maximum body size to record in bytes (default: 64KB) */
+  maxBodySize?: number;
+  /** Hours after which to prune old entries */
+  pruneAfterHours?: number;
+}
+
+// ============================================
+// Data Browser Configuration
+// ============================================
+
+/**
+ * Configuration for the data browser feature.
+ */
+export interface DataBrowserOptions<DB = unknown> {
+  /** Kysely database instance */
+  db: Kysely<DB>;
+  /** Default cursor configuration for all tables */
+  cursor: CursorConfig;
+  /** Per-table cursor overrides */
+  tableCursors?: TableCursorConfig;
+  /** Tables to exclude from browsing */
+  excludeTables?: string[];
+  /** Maximum rows per page (default: 50, max: 100) */
+  defaultPageSize?: number;
+  /** Whether to allow viewing of binary/blob columns (default: false) */
+  showBinaryColumns?: boolean;
+}
+
+// ============================================
+// Studio Configuration
+// ============================================
+
+/**
+ * Configuration for the Studio dashboard.
+ */
+export interface StudioOptions<DB = unknown> {
+  /** Monitoring configuration */
+  monitoring: MonitoringOptions;
+  /** Data browser configuration */
+  data: DataBrowserOptions<DB>;
+  /** Dashboard path (default: '/__studio') */
+  path?: string;
+  /** Whether Studio is enabled (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Normalized Studio options with all defaults applied.
+ */
+export interface NormalizedStudioOptions<DB = unknown> {
+  monitoring: Required<MonitoringOptions>;
+  data: Required<DataBrowserOptions<DB>>;
+  path: string;
+  enabled: boolean;
+}
+
+// ============================================
+// Table Introspection Types
+// ============================================
+
+/**
+ * Generic column type classification.
+ */
+export type ColumnType =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'datetime'
+  | 'json'
+  | 'binary'
+  | 'uuid'
+  | 'unknown';
+
+/**
+ * Information about a database column.
+ */
+export interface ColumnInfo {
+  /** Column name */
+  name: string;
+  /** Generic column type */
+  type: ColumnType;
+  /** Raw database type (e.g., 'varchar', 'int4') */
+  rawType: string;
+  /** Whether the column allows NULL values */
+  nullable: boolean;
+  /** Whether this column is part of the primary key */
+  isPrimaryKey: boolean;
+  /** Whether this column is a foreign key */
+  isForeignKey: boolean;
+  /** Referenced table if foreign key */
+  foreignKeyTable?: string;
+  /** Referenced column if foreign key */
+  foreignKeyColumn?: string;
+  /** Default value expression */
+  defaultValue?: string;
+}
+
+/**
+ * Information about a database table.
+ */
+export interface TableInfo {
+  /** Table name */
+  name: string;
+  /** Schema name (e.g., 'public') */
+  schema: string;
+  /** List of columns */
+  columns: ColumnInfo[];
+  /** Primary key column names */
+  primaryKey: string[];
+  /** Estimated row count (if available) */
+  estimatedRowCount?: number;
+}
+
+/**
+ * Complete schema information.
+ */
+export interface SchemaInfo {
+  /** List of tables */
+  tables: TableInfo[];
+  /** When the schema was last introspected */
+  updatedAt: Date;
+}
+
+// ============================================
+// Query Types
+// ============================================
+
+/**
+ * A single filter condition.
+ */
+export interface FilterCondition {
+  /** Column to filter on */
+  column: string;
+  /** Filter operator */
+  operator: FilterOperator;
+  /** Value to compare against (optional for IsNull/IsNotNull operators) */
+  value?: unknown;
+}
+
+/**
+ * Sort configuration for a column.
+ */
+export interface SortConfig {
+  /** Column to sort by */
+  column: string;
+  /** Sort direction */
+  direction: Direction;
+}
+
+/**
+ * Options for querying table data.
+ */
+export interface QueryOptions {
+  /** Table to query */
+  table: string;
+  /** Filter conditions */
+  filters?: FilterCondition[];
+  /** Sort configuration */
+  sort?: SortConfig[];
+  /** Cursor for pagination */
+  cursor?: string | null;
+  /** Number of rows per page */
+  pageSize?: number;
+  /** Pagination direction */
+  direction?: 'next' | 'prev';
+}
+
+/**
+ * Result of a paginated query.
+ */
+export interface QueryResult<T = Record<string, unknown>> {
+  /** Retrieved rows */
+  rows: T[];
+  /** Whether there are more rows */
+  hasMore: boolean;
+  /** Cursor for next page */
+  nextCursor: string | null;
+  /** Cursor for previous page */
+  prevCursor: string | null;
+  /** Estimated total row count */
+  totalEstimate?: number;
+}
+
+// ============================================
+// WebSocket Events
+// ============================================
+
+/**
+ * Types of events broadcast via WebSocket.
+ */
+export type StudioEventType =
+  | 'request'
+  | 'exception'
+  | 'log'
+  | 'stats'
+  | 'connected'
+  | 'schema_updated';
+
+/**
+ * A WebSocket event payload.
+ */
+export interface StudioEvent<T = unknown> {
+  /** Event type */
+  type: StudioEventType;
+  /** Event payload */
+  payload: T;
+  /** Event timestamp */
+  timestamp: number;
+}