@geekmidas/studio 0.0.1

package/src/data/__tests__/introspection.integration.spec.ts

@@ -0,0 +1,352 @@
+import {
+  CamelCasePlugin,
+  type Generated,
+  Kysely,
+  PostgresDialect,
+  sql,
+} from 'kysely';
+import pg from 'pg';
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { TEST_DATABASE_CONFIG } from '../../../../testkit/test/globalSetup';
+import { introspectSchema, introspectTable } from '../introspection';
+
+interface TestDatabase {
+  studioIntrospectUsers: {
+    id: Generated<number>;
+    name: string;
+    email: string;
+    isActive: boolean;
+    metadata: Generated<Record<string, unknown> | null>;
+    createdAt: Generated<Date>;
+    updatedAt: Generated<Date>;
+  };
+  studioIntrospectPosts: {
+    id: Generated<string>;
+    userId: number;
+    title: string;
+    content: string | null;
+    viewCount: number;
+    publishedAt: Date | null;
+    createdAt: Generated<Date>;
+  };
+  studioIntrospectTags: {
+    id: Generated<number>;
+    name: string;
+  };
+  studioIntrospectExcluded: {
+    id: Generated<number>;
+    value: string;
+  };
+}
+
+describe('Schema Introspection Integration Tests', () => {
+  let db: Kysely<TestDatabase>;
+
+  beforeAll(async () => {
+    db = new Kysely<TestDatabase>({
+      dialect: new PostgresDialect({
+        pool: new pg.Pool({
+          ...TEST_DATABASE_CONFIG,
+          database: 'postgres',
+        }),
+      }),
+      plugins: [new CamelCasePlugin()],
+    });
+
+    // Create users table with various column types
+    await db.schema
+      .createTable('studio_introspect_users')
+      .ifNotExists()
+      .addColumn('id', 'serial', (col) => col.primaryKey())
+      .addColumn('name', 'varchar(255)', (col) => col.notNull())
+      .addColumn('email', 'varchar(255)', (col) => col.notNull().unique())
+      .addColumn('is_active', 'boolean', (col) => col.notNull().defaultTo(true))
+      .addColumn('metadata', 'jsonb')
+      .addColumn('created_at', 'timestamptz', (col) =>
+        col.defaultTo(sql`now()`).notNull(),
+      )
+      .addColumn('updated_at', 'timestamptz', (col) =>
+        col.defaultTo(sql`now()`).notNull(),
+      )
+      .execute();
+
+    // Create posts table with foreign key
+    await db.schema
+      .createTable('studio_introspect_posts')
+      .ifNotExists()
+      .addColumn('id', 'uuid', (col) =>
+        col.primaryKey().defaultTo(sql`gen_random_uuid()`),
+      )
+      .addColumn('user_id', 'integer', (col) =>
+        col
+          .notNull()
+          .references('studio_introspect_users.id')
+          .onDelete('cascade'),
+      )
+      .addColumn('title', 'varchar(500)', (col) => col.notNull())
+      .addColumn('content', 'text')
+      .addColumn('view_count', 'integer', (col) => col.notNull().defaultTo(0))
+      .addColumn('published_at', 'timestamp')
+      .addColumn('created_at', 'timestamptz', (col) =>
+        col.defaultTo(sql`now()`).notNull(),
+      )
+      .execute();
+
+    // Create simple tags table
+    await db.schema
+      .createTable('studio_introspect_tags')
+      .ifNotExists()
+      .addColumn('id', 'serial', (col) => col.primaryKey())
+      .addColumn('name', 'varchar(100)', (col) => col.notNull())
+      .execute();
+
+    // Create excluded table (for exclusion testing)
+    await db.schema
+      .createTable('studio_introspect_excluded')
+      .ifNotExists()
+      .addColumn('id', 'serial', (col) => col.primaryKey())
+      .addColumn('value', 'varchar(100)', (col) => col.notNull())
+      .execute();
+  });
+
+  afterEach(async () => {
+    // Clean up data after each test
+    await db.deleteFrom('studioIntrospectPosts').execute();
+    await db.deleteFrom('studioIntrospectUsers').execute();
+    await db.deleteFrom('studioIntrospectTags').execute();
+    await db.deleteFrom('studioIntrospectExcluded').execute();
+  });
+
+  afterAll(async () => {
+    // Drop tables and close connection
+    await db.schema.dropTable('studio_introspect_posts').ifExists().execute();
+    await db.schema.dropTable('studio_introspect_users').ifExists().execute();
+    await db.schema.dropTable('studio_introspect_tags').ifExists().execute();
+    await db.schema
+      .dropTable('studio_introspect_excluded')
+      .ifExists()
+      .execute();
+    await db.destroy();
+  });
+
+  describe('introspectSchema', () => {
+    it('should discover all tables in the public schema', async () => {
+      const schema = await introspectSchema(db, []);
+
+      // Find our test tables
+      const tableNames = schema.tables.map((t) => t.name);
+      expect(tableNames).toContain('studio_introspect_users');
+      expect(tableNames).toContain('studio_introspect_posts');
+      expect(tableNames).toContain('studio_introspect_tags');
+      expect(tableNames).toContain('studio_introspect_excluded');
+      expect(schema.updatedAt).toBeInstanceOf(Date);
+    });
+
+    it('should exclude specified tables', async () => {
+      const schema = await introspectSchema(db, ['studio_introspect_excluded']);
+
+      const tableNames = schema.tables.map((t) => t.name);
+      expect(tableNames).toContain('studio_introspect_users');
+      expect(tableNames).toContain('studio_introspect_posts');
+      expect(tableNames).not.toContain('studio_introspect_excluded');
+    });
+
+    it('should exclude multiple tables', async () => {
+      const schema = await introspectSchema(db, [
+        'studio_introspect_excluded',
+        'studio_introspect_tags',
+      ]);
+
+      const tableNames = schema.tables.map((t) => t.name);
+      expect(tableNames).toContain('studio_introspect_users');
+      expect(tableNames).toContain('studio_introspect_posts');
+      expect(tableNames).not.toContain('studio_introspect_excluded');
+      expect(tableNames).not.toContain('studio_introspect_tags');
+    });
+  });
+
+  describe('introspectTable', () => {
+    it('should return column information for users table', async () => {
+      const tableInfo = await introspectTable(db, 'studio_introspect_users');
+
+      expect(tableInfo.name).toBe('studio_introspect_users');
+      expect(tableInfo.schema).toBe('public');
+      expect(tableInfo.columns.length).toBe(7);
+
+      // Find specific columns
+      const idCol = tableInfo.columns.find((c) => c.name === 'id');
+      const nameCol = tableInfo.columns.find((c) => c.name === 'name');
+      const emailCol = tableInfo.columns.find((c) => c.name === 'email');
+      const isActiveCol = tableInfo.columns.find((c) => c.name === 'is_active');
+      const metadataCol = tableInfo.columns.find((c) => c.name === 'metadata');
+      const createdAtCol = tableInfo.columns.find(
+        (c) => c.name === 'created_at',
+      );
+
+      // Check id column (primary key, serial)
+      expect(idCol).toBeDefined();
+      expect(idCol!.type).toBe('number');
+      expect(idCol!.rawType).toBe('int4');
+      expect(idCol!.isPrimaryKey).toBe(true);
+      expect(idCol!.nullable).toBe(false);
+
+      // Check name column (varchar, not null)
+      expect(nameCol).toBeDefined();
+      expect(nameCol!.type).toBe('string');
+      expect(nameCol!.rawType).toBe('varchar');
+      expect(nameCol!.nullable).toBe(false);
+
+      // Check email column (varchar, unique)
+      expect(emailCol).toBeDefined();
+      expect(emailCol!.type).toBe('string');
+      expect(emailCol!.nullable).toBe(false);
+
+      // Check is_active column (boolean with default)
+      expect(isActiveCol).toBeDefined();
+      expect(isActiveCol!.type).toBe('boolean');
+      expect(isActiveCol!.rawType).toBe('bool');
+      expect(isActiveCol!.nullable).toBe(false);
+
+      // Check metadata column (jsonb, nullable)
+      expect(metadataCol).toBeDefined();
+      expect(metadataCol!.type).toBe('json');
+      expect(metadataCol!.rawType).toBe('jsonb');
+      expect(metadataCol!.nullable).toBe(true);
+
+      // Check created_at column (timestamptz)
+      expect(createdAtCol).toBeDefined();
+      expect(createdAtCol!.type).toBe('datetime');
+      expect(createdAtCol!.rawType).toBe('timestamptz');
+    });
+
+    it('should detect primary key', async () => {
+      const tableInfo = await introspectTable(db, 'studio_introspect_users');
+
+      expect(tableInfo.primaryKey).toEqual(['id']);
+
+      const idColumn = tableInfo.columns.find((c) => c.name === 'id');
+      expect(idColumn!.isPrimaryKey).toBe(true);
+    });
+
+    it('should detect foreign keys', async () => {
+      const tableInfo = await introspectTable(db, 'studio_introspect_posts');
+
+      const userIdCol = tableInfo.columns.find((c) => c.name === 'user_id');
+      expect(userIdCol).toBeDefined();
+      expect(userIdCol!.isForeignKey).toBe(true);
+      expect(userIdCol!.foreignKeyTable).toBe('studio_introspect_users');
+      expect(userIdCol!.foreignKeyColumn).toBe('id');
+    });
+
+    it('should detect uuid primary key', async () => {
+      const tableInfo = await introspectTable(db, 'studio_introspect_posts');
+
+      expect(tableInfo.primaryKey).toEqual(['id']);
+
+      const idColumn = tableInfo.columns.find((c) => c.name === 'id');
+      expect(idColumn).toBeDefined();
+      expect(idColumn!.type).toBe('uuid');
+      expect(idColumn!.rawType).toBe('uuid');
+      expect(idColumn!.isPrimaryKey).toBe(true);
+    });
+
+    it('should map PostgreSQL types correctly', async () => {
+      const usersTable = await introspectTable(db, 'studio_introspect_users');
+      const postsTable = await introspectTable(db, 'studio_introspect_posts');
+
+      // Integer types -> number
+      const userIdCol = usersTable.columns.find((c) => c.name === 'id');
+      expect(userIdCol!.type).toBe('number');
+
+      // Boolean -> boolean
+      const isActiveCol = usersTable.columns.find(
+        (c) => c.name === 'is_active',
+      );
+      expect(isActiveCol!.type).toBe('boolean');
+
+      // JSONB -> json
+      const metadataCol = usersTable.columns.find((c) => c.name === 'metadata');
+      expect(metadataCol!.type).toBe('json');
+
+      // Timestamptz -> datetime
+      const createdAtCol = usersTable.columns.find(
+        (c) => c.name === 'created_at',
+      );
+      expect(createdAtCol!.type).toBe('datetime');
+
+      // UUID -> uuid
+      const postIdCol = postsTable.columns.find((c) => c.name === 'id');
+      expect(postIdCol!.type).toBe('uuid');
+
+      // Text -> string
+      const contentCol = postsTable.columns.find((c) => c.name === 'content');
+      expect(contentCol!.type).toBe('string');
+      expect(contentCol!.rawType).toBe('text');
+
+      // Timestamp (without tz) -> datetime
+      const publishedCol = postsTable.columns.find(
+        (c) => c.name === 'published_at',
+      );
+      expect(publishedCol!.type).toBe('datetime');
+    });
+
+    it('should detect nullable columns', async () => {
+      const tableInfo = await introspectTable(db, 'studio_introspect_posts');
+
+      const titleCol = tableInfo.columns.find((c) => c.name === 'title');
+      const contentCol = tableInfo.columns.find((c) => c.name === 'content');
+      const publishedAtCol = tableInfo.columns.find(
+        (c) => c.name === 'published_at',
+      );
+
+      expect(titleCol!.nullable).toBe(false);
+      expect(contentCol!.nullable).toBe(true);
+      expect(publishedAtCol!.nullable).toBe(true);
+    });
+
+    it('should provide estimated row count when data exists', async () => {
+      // Insert some data
+      const user = await db
+        .insertInto('studioIntrospectUsers')
+        .values({
+          name: 'Test User',
+          email: 'test@example.com',
+        })
+        .returningAll()
+        .executeTakeFirstOrThrow();
+
+      await db
+        .insertInto('studioIntrospectPosts')
+        .values([
+          { userId: user.id, title: 'Post 1' },
+          { userId: user.id, title: 'Post 2' },
+          { userId: user.id, title: 'Post 3' },
+        ])
+        .execute();
+
+      // ANALYZE to update statistics
+      await sql`ANALYZE studio_introspect_posts`.execute(db);
+
+      const tableInfo = await introspectTable(db, 'studio_introspect_posts');
+
+      // Row count estimate should exist (might not be exact)
+      expect(tableInfo.estimatedRowCount).toBeDefined();
+      expect(tableInfo.estimatedRowCount).toBeGreaterThan(0);
+    });
+
+    it('should return all columns in ordinal position order', async () => {
+      const tableInfo = await introspectTable(db, 'studio_introspect_users');
+
+      const columnNames = tableInfo.columns.map((c) => c.name);
+      expect(columnNames).toEqual([
+        'id',
+        'name',
+        'email',
+        'is_active',
+        'metadata',
+        'created_at',
+        'updated_at',
+      ]);
+    });
+  });
+});

package/src/data/filtering.ts

@@ -0,0 +1,191 @@
+import type { SelectQueryBuilder } from 'kysely';
+import {
+  type ColumnInfo,
+  Direction,
+  type FilterCondition,
+  FilterOperator,
+  type SortConfig,
+  type TableInfo,
+} from '../types';
+
+/**
+ * Validates that a filter is applicable to the given column.
+ */
+export function validateFilter(
+  filter: FilterCondition,
+  columnInfo: ColumnInfo,
+): { valid: boolean; error?: string } {
+  // Validate operator compatibility with column type
+  const typeCompatibility: Record<string, FilterOperator[]> = {
+    string: [
+      FilterOperator.Eq,
+      FilterOperator.Neq,
+      FilterOperator.Like,
+      FilterOperator.Ilike,
+      FilterOperator.In,
+      FilterOperator.Nin,
+      FilterOperator.IsNull,
+      FilterOperator.IsNotNull,
+    ],
+    number: [
+      FilterOperator.Eq,
+      FilterOperator.Neq,
+      FilterOperator.Gt,
+      FilterOperator.Gte,
+      FilterOperator.Lt,
+      FilterOperator.Lte,
+      FilterOperator.In,
+      FilterOperator.Nin,
+      FilterOperator.IsNull,
+      FilterOperator.IsNotNull,
+    ],
+    boolean: [
+      FilterOperator.Eq,
+      FilterOperator.Neq,
+      FilterOperator.IsNull,
+      FilterOperator.IsNotNull,
+    ],
+    date: [
+      FilterOperator.Eq,
+      FilterOperator.Neq,
+      FilterOperator.Gt,
+      FilterOperator.Gte,
+      FilterOperator.Lt,
+      FilterOperator.Lte,
+      FilterOperator.IsNull,
+      FilterOperator.IsNotNull,
+    ],
+    datetime: [
+      FilterOperator.Eq,
+      FilterOperator.Neq,
+      FilterOperator.Gt,
+      FilterOperator.Gte,
+      FilterOperator.Lt,
+      FilterOperator.Lte,
+      FilterOperator.IsNull,
+      FilterOperator.IsNotNull,
+    ],
+    uuid: [
+      FilterOperator.Eq,
+      FilterOperator.Neq,
+      FilterOperator.In,
+      FilterOperator.Nin,
+      FilterOperator.IsNull,
+      FilterOperator.IsNotNull,
+    ],
+    json: [FilterOperator.IsNull, FilterOperator.IsNotNull],
+    binary: [FilterOperator.IsNull, FilterOperator.IsNotNull],
+    unknown: [
+      FilterOperator.Eq,
+      FilterOperator.Neq,
+      FilterOperator.IsNull,
+      FilterOperator.IsNotNull,
+    ],
+  };
+
+  const allowedOps =
+    typeCompatibility[columnInfo.type] ?? typeCompatibility.unknown;
+
+  if (!allowedOps.includes(filter.operator)) {
+    return {
+      valid: false,
+      error: `Operator '${filter.operator}' not supported for column type '${columnInfo.type}'`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Applies filters to a Kysely query builder.
+ */
+export function applyFilters<DB, TB extends keyof DB, O>(
+  query: SelectQueryBuilder<DB, TB, O>,
+  filters: FilterCondition[],
+  tableInfo: TableInfo,
+): SelectQueryBuilder<DB, TB, O> {
+  let result = query;
+
+  for (const filter of filters) {
+    const column = tableInfo.columns.find((c) => c.name === filter.column);
+
+    if (!column) {
+      throw new Error(
+        `Column '${filter.column}' not found in table '${tableInfo.name}'`,
+      );
+    }
+
+    const validation = validateFilter(filter, column);
+    if (!validation.valid) {
+      throw new Error(validation.error);
+    }
+
+    result = applyFilterCondition(result, filter);
+  }
+
+  return result;
+}
+
+function applyFilterCondition<DB, TB extends keyof DB, O>(
+  query: SelectQueryBuilder<DB, TB, O>,
+  filter: FilterCondition,
+): SelectQueryBuilder<DB, TB, O> {
+  const { column, operator, value } = filter;
+
+  switch (operator) {
+    case FilterOperator.Eq:
+      return query.where(column as any, '=', value);
+    case FilterOperator.Neq:
+      return query.where(column as any, '!=', value);
+    case FilterOperator.Gt:
+      return query.where(column as any, '>', value);
+    case FilterOperator.Gte:
+      return query.where(column as any, '>=', value);
+    case FilterOperator.Lt:
+      return query.where(column as any, '<', value);
+    case FilterOperator.Lte:
+      return query.where(column as any, '<=', value);
+    case FilterOperator.Like:
+      return query.where(column as any, 'like', value);
+    case FilterOperator.Ilike:
+      return query.where(column as any, 'ilike', value);
+    case FilterOperator.In:
+      return query.where(column as any, 'in', value as any[]);
+    case FilterOperator.Nin:
+      return query.where(column as any, 'not in', value as any[]);
+    case FilterOperator.IsNull:
+      return query.where(column as any, 'is', null);
+    case FilterOperator.IsNotNull:
+      return query.where(column as any, 'is not', null);
+    default:
+      throw new Error(`Unknown filter operator: ${operator}`);
+  }
+}
+
+/**
+ * Applies sorting to a Kysely query builder.
+ */
+export function applySorting<DB, TB extends keyof DB, O>(
+  query: SelectQueryBuilder<DB, TB, O>,
+  sorts: SortConfig[],
+  tableInfo: TableInfo,
+): SelectQueryBuilder<DB, TB, O> {
+  let result = query;
+
+  for (const sort of sorts) {
+    const column = tableInfo.columns.find((c) => c.name === sort.column);
+
+    if (!column) {
+      throw new Error(
+        `Column '${sort.column}' not found in table '${tableInfo.name}'`,
+      );
+    }
+
+    result = result.orderBy(
+      sort.column as any,
+      sort.direction === Direction.Asc ? 'asc' : 'desc',
+    );
+  }
+
+  return result;
+}

package/src/data/index.ts

@@ -0,0 +1 @@
+export { DataBrowser } from './DataBrowser';