@geekmidas/studio 0.0.1

package/src/data/introspection.ts

@@ -0,0 +1,220 @@
+import type { Kysely } from 'kysely';
+import type { ColumnInfo, ColumnType, SchemaInfo, TableInfo } from '../types';
+
+/**
+ * Introspects the database schema to discover tables and columns.
+ * Uses PostgreSQL information_schema for metadata.
+ */
+export async function introspectSchema<DB>(
+  db: Kysely<DB>,
+  excludeTables: string[],
+): Promise<SchemaInfo> {
+  // Query tables from information_schema
+  const excludePlaceholders =
+    excludeTables.length > 0
+      ? excludeTables.map((_, i) => `$${i + 1}`).join(', ')
+      : "''";
+
+  const tablesQuery = `
+    SELECT
+      table_name,
+      table_schema
+    FROM information_schema.tables
+    WHERE table_schema = 'public'
+      AND table_type = 'BASE TABLE'
+      ${excludeTables.length > 0 ? `AND table_name NOT IN (${excludePlaceholders})` : ''}
+    ORDER BY table_name
+  `;
+
+  const tablesResult = await db.executeQuery({
+    sql: tablesQuery,
+    parameters: excludeTables,
+  } as any);
+
+  const tables: TableInfo[] = [];
+
+  for (const row of tablesResult.rows as any[]) {
+    // Support both snake_case (raw) and camelCase (with CamelCasePlugin)
+    const tableName = row.table_name ?? row.tableName;
+    const tableSchema = row.table_schema ?? row.tableSchema;
+    const tableInfo = await introspectTable(db, tableName, tableSchema);
+    tables.push(tableInfo);
+  }
+
+  return {
+    tables,
+    updatedAt: new Date(),
+  };
+}
+
+/**
+ * Introspects a single table to get column information.
+ */
+export async function introspectTable<DB>(
+  db: Kysely<DB>,
+  tableName: string,
+  schema = 'public',
+): Promise<TableInfo> {
+  // Query columns
+  const columnsQuery = `
+    SELECT
+      c.column_name,
+      c.data_type,
+      c.udt_name,
+      c.is_nullable,
+      c.column_default,
+      CASE WHEN pk.column_name IS NOT NULL THEN true ELSE false END as is_primary_key
+    FROM information_schema.columns c
+    LEFT JOIN (
+      SELECT ku.column_name
+      FROM information_schema.table_constraints tc
+      JOIN information_schema.key_column_usage ku
+        ON tc.constraint_name = ku.constraint_name
+        AND tc.table_schema = ku.table_schema
+      WHERE tc.table_name = $1
+        AND tc.table_schema = $2
+        AND tc.constraint_type = 'PRIMARY KEY'
+    ) pk ON c.column_name = pk.column_name
+    WHERE c.table_name = $1
+      AND c.table_schema = $2
+    ORDER BY c.ordinal_position
+  `;
+
+  const columnsResult = await db.executeQuery({
+    sql: columnsQuery,
+    parameters: [tableName, schema],
+  } as any);
+
+  // Query foreign keys
+  const fkQuery = `
+    SELECT
+      kcu.column_name,
+      ccu.table_name AS foreign_table,
+      ccu.column_name AS foreign_column
+    FROM information_schema.table_constraints tc
+    JOIN information_schema.key_column_usage kcu
+      ON tc.constraint_name = kcu.constraint_name
+      AND tc.table_schema = kcu.table_schema
+    JOIN information_schema.constraint_column_usage ccu
+      ON tc.constraint_name = ccu.constraint_name
+      AND tc.table_schema = ccu.table_schema
+    WHERE tc.table_name = $1
+      AND tc.table_schema = $2
+      AND tc.constraint_type = 'FOREIGN KEY'
+  `;
+
+  const fkResult = await db.executeQuery({
+    sql: fkQuery,
+    parameters: [tableName, schema],
+  } as any);
+
+  const foreignKeys = new Map<string, { table: string; column: string }>();
+  for (const row of fkResult.rows as any[]) {
+    // Support both snake_case (raw) and camelCase (with CamelCasePlugin)
+    const colName = row.column_name ?? row.columnName;
+    foreignKeys.set(colName, {
+      table: row.foreign_table ?? row.foreignTable,
+      column: row.foreign_column ?? row.foreignColumn,
+    });
+  }
+
+  const columns: ColumnInfo[] = (columnsResult.rows as any[]).map((row) => {
+    // Support both snake_case (raw) and camelCase (with CamelCasePlugin)
+    const colName = row.column_name ?? row.columnName;
+    const udtName = row.udt_name ?? row.udtName;
+    const isNullable = row.is_nullable ?? row.isNullable;
+    const isPrimaryKey = row.is_primary_key ?? row.isPrimaryKey;
+    const columnDefault = row.column_default ?? row.columnDefault;
+
+    const fk = foreignKeys.get(colName);
+    return {
+      name: colName,
+      type: mapPostgresType(udtName),
+      rawType: udtName,
+      nullable: isNullable === 'YES',
+      isPrimaryKey: isPrimaryKey,
+      isForeignKey: !!fk,
+      foreignKeyTable: fk?.table,
+      foreignKeyColumn: fk?.column,
+      defaultValue: columnDefault ?? undefined,
+    };
+  });
+
+  const primaryKey = columns.filter((c) => c.isPrimaryKey).map((c) => c.name);
+
+  // Get estimated row count
+  const countQuery = `
+    SELECT reltuples::bigint AS estimate
+    FROM pg_class
+    WHERE relname = $1
+  `;
+
+  let estimatedRowCount: number | undefined;
+  try {
+    const countResult = await db.executeQuery({
+      sql: countQuery,
+      parameters: [tableName],
+    } as any);
+    if (countResult.rows.length > 0) {
+      const estimate = (countResult.rows[0] as any).estimate;
+      estimatedRowCount = estimate > 0 ? Number(estimate) : undefined;
+    }
+  } catch {
+    // Ignore errors, row count is optional
+  }
+
+  return {
+    name: tableName,
+    schema,
+    columns,
+    primaryKey,
+    estimatedRowCount,
+  };
+}
+
+/**
+ * Maps PostgreSQL types to generic column types.
+ */
+function mapPostgresType(udtName: string): ColumnType {
+  const typeMap: Record<string, ColumnType> = {
+    // Strings
+    varchar: 'string',
+    char: 'string',
+    text: 'string',
+    name: 'string',
+    bpchar: 'string',
+
+    // Numbers
+    int2: 'number',
+    int4: 'number',
+    int8: 'number',
+    float4: 'number',
+    float8: 'number',
+    numeric: 'number',
+    money: 'number',
+    serial: 'number',
+    bigserial: 'number',
+
+    // Boolean
+    bool: 'boolean',
+
+    // Dates
+    date: 'date',
+    timestamp: 'datetime',
+    timestamptz: 'datetime',
+    time: 'datetime',
+    timetz: 'datetime',
+
+    // JSON
+    json: 'json',
+    jsonb: 'json',
+
+    // Binary
+    bytea: 'binary',
+
+    // UUID
+    uuid: 'uuid',
+  };
+
+  return typeMap[udtName] ?? 'unknown';
+}

package/src/data/pagination.ts

@@ -0,0 +1,33 @@
+/**
+ * Cursor encoding/decoding utilities for pagination.
+ */
+
+/**
+ * Encode a cursor value for safe URL transmission.
+ * Supports various types: string, number, Date, etc.
+ */
+export function encodeCursor(value: unknown): string {
+  const payload = {
+    v: value instanceof Date ? value.toISOString() : value,
+    t: value instanceof Date ? 'date' : typeof value,
+  };
+  return Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+
+/**
+ * Decode a cursor string back to its original value.
+ */
+export function decodeCursor(cursor: string): unknown {
+  try {
+    const json = Buffer.from(cursor, 'base64url').toString('utf-8');
+    const payload = JSON.parse(json);
+
+    if (payload.t === 'date') {
+      return new Date(payload.v);
+    }
+
+    return payload.v;
+  } catch {
+    throw new Error('Invalid cursor format');
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// Core
+export { Studio } from './Studio';
+
+// Types
+export {
+  Direction,
+  FilterOperator,
+  type CursorConfig,
+  type TableCursorConfig,
+  type MonitoringOptions,
+  type DataBrowserOptions,
+  type StudioOptions,
+  type NormalizedStudioOptions,
+  type ColumnType,
+  type ColumnInfo,
+  type TableInfo,
+  type SchemaInfo,
+  type FilterCondition,
+  type SortConfig,
+  type QueryOptions,
+  type QueryResult,
+  type StudioEventType,
+  type StudioEvent,
+} from './types';
+
+// Re-export Telescope storage types for convenience
+// Users should import storage from @geekmidas/studio, not @geekmidas/telescope
+export type { TelescopeStorage as MonitoringStorage } from '@geekmidas/telescope';
+
+// Re-export InMemoryStorage as InMemoryMonitoringStorage
+export { InMemoryStorage as InMemoryMonitoringStorage } from '@geekmidas/telescope/storage/memory';

package/src/server/__tests__/hono.integration.spec.ts

@@ -0,0 +1,361 @@
+import {
+  CamelCasePlugin,
+  type Generated,
+  Kysely,
+  PostgresDialect,
+  sql,
+} from 'kysely';
+import pg from 'pg';
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from 'vitest';
+import { TEST_DATABASE_CONFIG } from '../../../../testkit/test/globalSetup';
+import { DataBrowser } from '../../data/DataBrowser';
+import { Direction } from '../../types';
+import { createStudioApp } from '../hono';
+
+interface TestDatabase {
+  studioHonoProducts: {
+    id: Generated<number>;
+    name: string;
+    price: number;
+    category: string;
+    inStock: boolean;
+    createdAt: Generated<Date>;
+  };
+}
+
+// Minimal Studio-like object for testing the Hono adapter
+interface MockStudio {
+  data: DataBrowser<TestDatabase>;
+}
+
+describe('Hono Server Adapter Integration Tests', () => {
+  let db: Kysely<TestDatabase>;
+  let mockStudio: MockStudio;
+  let app: ReturnType<typeof createStudioApp>;
+
+  beforeAll(async () => {
+    db = new Kysely<TestDatabase>({
+      dialect: new PostgresDialect({
+        pool: new pg.Pool({
+          ...TEST_DATABASE_CONFIG,
+          database: 'postgres',
+        }),
+      }),
+      plugins: [new CamelCasePlugin()],
+    });
+
+    // Create test table
+    await db.schema
+      .createTable('studio_hono_products')
+      .ifNotExists()
+      .addColumn('id', 'serial', (col) => col.primaryKey())
+      .addColumn('name', 'varchar(255)', (col) => col.notNull())
+      .addColumn('price', 'numeric(10, 2)', (col) => col.notNull())
+      .addColumn('category', 'varchar(100)', (col) => col.notNull())
+      .addColumn('in_stock', 'boolean', (col) => col.notNull().defaultTo(true))
+      .addColumn('created_at', 'timestamptz', (col) =>
+        col.defaultTo(sql`now()`).notNull(),
+      )
+      .execute();
+  });
+
+  beforeEach(async () => {
+    // Create DataBrowser directly for testing
+    const dataBrowser = new DataBrowser({
+      db,
+      cursor: { field: 'id', direction: Direction.Asc },
+      tableCursors: {},
+      excludeTables: [],
+      defaultPageSize: 50,
+      showBinaryColumns: false,
+    });
+
+    mockStudio = { data: dataBrowser };
+    app = createStudioApp(mockStudio as any);
+
+    // Insert test data
+    await db
+      .insertInto('studioHonoProducts')
+      .values([
+        {
+          name: 'Laptop',
+          price: 999.99,
+          category: 'electronics',
+          inStock: true,
+        },
+        {
+          name: 'Mouse',
+          price: 29.99,
+          category: 'electronics',
+          inStock: true,
+        },
+        {
+          name: 'Keyboard',
+          price: 79.99,
+          category: 'electronics',
+          inStock: false,
+        },
+        { name: 'Desk', price: 299.99, category: 'furniture', inStock: true },
+        { name: 'Chair', price: 199.99, category: 'furniture', inStock: true },
+      ])
+      .execute();
+  });
+
+  afterEach(async () => {
+    await db.deleteFrom('studioHonoProducts').execute();
+  });
+
+  afterAll(async () => {
+    await db.schema.dropTable('studio_hono_products').ifExists().execute();
+    await db.destroy();
+  });
+
+  describe('GET /api/schema', () => {
+    it('should return database schema', async () => {
+      const res = await app.request('/api/schema');
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.tables).toBeDefined();
+      expect(Array.isArray(data.tables)).toBe(true);
+      expect(data.updatedAt).toBeDefined();
+    });
+
+    it('should force refresh when requested', async () => {
+      const res1 = await app.request('/api/schema');
+      const data1 = await res1.json();
+
+      const res2 = await app.request('/api/schema?refresh=true');
+      const data2 = await res2.json();
+
+      // Both should have tables
+      expect(data1.tables).toBeDefined();
+      expect(data2.tables).toBeDefined();
+    });
+  });
+
+  describe('GET /api/tables', () => {
+    it('should return list of tables', async () => {
+      const res = await app.request('/api/tables');
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.tables).toBeDefined();
+
+      const productTable = data.tables.find(
+        (t: any) => t.name === 'studio_hono_products',
+      );
+      expect(productTable).toBeDefined();
+      expect(productTable.columnCount).toBeGreaterThan(0);
+      expect(productTable.primaryKey).toEqual(['id']);
+    });
+  });
+
+  describe('GET /api/tables/:name', () => {
+    it('should return table info for existing table', async () => {
+      const res = await app.request('/api/tables/studio_hono_products');
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.name).toBe('studio_hono_products');
+      expect(data.columns).toBeDefined();
+      expect(data.columns.length).toBeGreaterThan(0);
+    });
+
+    it('should return 404 for non-existent table', async () => {
+      const res = await app.request('/api/tables/non_existent_table');
+
+      expect(res.status).toBe(404);
+      const data = await res.json();
+      expect(data.error).toContain('not found');
+    });
+  });
+
+  describe('GET /api/tables/:name/rows', () => {
+    it('should return paginated rows', async () => {
+      const res = await app.request('/api/tables/studio_hono_products/rows');
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.rows).toBeDefined();
+      expect(data.rows.length).toBe(5);
+      expect(data.hasMore).toBe(false);
+    });
+
+    it('should respect pageSize parameter', async () => {
+      const res = await app.request(
+        '/api/tables/studio_hono_products/rows?pageSize=2',
+      );
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.rows.length).toBe(2);
+      expect(data.hasMore).toBe(true);
+      expect(data.nextCursor).toBeDefined();
+    });
+
+    it('should paginate using cursor', async () => {
+      const res1 = await app.request(
+        '/api/tables/studio_hono_products/rows?pageSize=2',
+      );
+      const data1 = await res1.json();
+
+      const res2 = await app.request(
+        `/api/tables/studio_hono_products/rows?pageSize=2&cursor=${data1.nextCursor}`,
+      );
+      const data2 = await res2.json();
+
+      expect(data2.rows.length).toBe(2);
+
+      // Rows should be different
+      const ids1 = data1.rows.map((r: any) => r.id);
+      const ids2 = data2.rows.map((r: any) => r.id);
+      expect(ids1.every((id: number) => !ids2.includes(id))).toBe(true);
+    });
+
+    it('should apply equality filter', async () => {
+      const res = await app.request(
+        '/api/tables/studio_hono_products/rows?filter[category][eq]=electronics',
+      );
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.rows.length).toBe(3);
+      data.rows.forEach((row: any) => {
+        expect(row.category).toBe('electronics');
+      });
+    });
+
+    it('should apply greater-than filter', async () => {
+      const res = await app.request(
+        '/api/tables/studio_hono_products/rows?filter[price][gt]=100',
+      );
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.rows.length).toBe(3);
+      data.rows.forEach((row: any) => {
+        expect(Number(row.price)).toBeGreaterThan(100);
+      });
+    });
+
+    it('should apply boolean filter', async () => {
+      const res = await app.request(
+        '/api/tables/studio_hono_products/rows?filter[in_stock][eq]=false',
+      );
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.rows.length).toBe(1);
+      expect(data.rows[0].name).toBe('Keyboard');
+    });
+
+    it('should apply IN filter', async () => {
+      const res = await app.request(
+        '/api/tables/studio_hono_products/rows?filter[name][in]=Laptop,Mouse',
+      );
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.rows.length).toBe(2);
+    });
+
+    it('should apply multiple filters', async () => {
+      const res = await app.request(
+        '/api/tables/studio_hono_products/rows?filter[category][eq]=electronics&filter[in_stock][eq]=true',
+      );
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.rows.length).toBe(2);
+      data.rows.forEach((row: any) => {
+        expect(row.category).toBe('electronics');
+        expect(row.inStock).toBe(true);
+      });
+    });
+
+    it('should apply sorting', async () => {
+      const res = await app.request(
+        '/api/tables/studio_hono_products/rows?sort=price:desc',
+      );
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      const prices = data.rows.map((r: any) => Number(r.price));
+
+      for (let i = 1; i < prices.length; i++) {
+        expect(prices[i]).toBeLessThanOrEqual(prices[i - 1]);
+      }
+    });
+
+    it('should apply multiple sort columns', async () => {
+      const res = await app.request(
+        '/api/tables/studio_hono_products/rows?sort=category:asc,price:desc',
+      );
+
+      expect(res.status).toBe(200);
+      const data = await res.json();
+      expect(data.rows.length).toBe(5);
+
+      // Electronics should come first (alphabetically)
+      const electronics = data.rows.filter(
+        (r: any) => r.category === 'electronics',
+      );
+      expect(electronics.length).toBe(3);
+
+      // Within electronics, prices should be descending
+      const electronicPrices = electronics.map((r: any) => Number(r.price));
+      for (let i = 1; i < electronicPrices.length; i++) {
+        expect(electronicPrices[i]).toBeLessThanOrEqual(
+          electronicPrices[i - 1],
+        );
+      }
+    });
+
+    it('should return 404 for non-existent table', async () => {
+      const res = await app.request('/api/tables/non_existent_table/rows');
+
+      expect(res.status).toBe(404);
+      const data = await res.json();
+      expect(data.error).toContain('not found');
+    });
+
+    it('should cap pageSize at 100', async () => {
+      const res = await app.request(
+        '/api/tables/studio_hono_products/rows?pageSize=500',
+      );
+
+      expect(res.status).toBe(200);
+      // Since we only have 5 rows, we just verify the request succeeds
+      const data = await res.json();
+      expect(data.rows).toBeDefined();
+    });
+  });
+
+  describe('GET /', () => {
+    it('should return dashboard UI or API info', async () => {
+      const res = await app.request('/');
+
+      expect(res.status).toBe(200);
+      const contentType = res.headers.get('content-type') || '';
+
+      // If UI is embedded, returns HTML; otherwise returns JSON API info
+      if (contentType.includes('text/html')) {
+        const html = await res.text();
+        expect(html).toContain('<!doctype html>');
+      } else {
+        const data = await res.json();
+        expect(data.message).toBe('Studio API is running');
+        expect(data.endpoints).toBeDefined();
+      }
+    });
+  });
+});