@geekmidas/studio 0.0.1

package/dist/DataBrowser-SOcqmZb2.d.mts

@@ -0,0 +1,267 @@
+import { TelescopeStorage } from "@geekmidas/telescope";
+import { Kysely } from "kysely";
+
+//#region src/types.d.ts
+
+/**
+ * Sort direction for cursor-based pagination and sorting.
+ */
+declare enum Direction {
+  Asc = "asc",
+  Desc = "desc",
+}
+/**
+ * Filter operators for querying data.
+ */
+declare 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",
+}
+/**
+ * Configuration for cursor-based pagination.
+ */
+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.
+ */
+interface TableCursorConfig {
+  [tableName: string]: CursorConfig;
+}
+/**
+ * Configuration for the monitoring feature (Telescope).
+ */
+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;
+}
+/**
+ * Configuration for the data browser feature.
+ */
+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;
+}
+/**
+ * Configuration for the Studio dashboard.
+ */
+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.
+ */
+interface NormalizedStudioOptions<DB = unknown> {
+  monitoring: Required<MonitoringOptions>;
+  data: Required<DataBrowserOptions<DB>>;
+  path: string;
+  enabled: boolean;
+}
+/**
+ * Generic column type classification.
+ */
+type ColumnType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'json' | 'binary' | 'uuid' | 'unknown';
+/**
+ * Information about a database column.
+ */
+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.
+ */
+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.
+ */
+interface SchemaInfo {
+  /** List of tables */
+  tables: TableInfo[];
+  /** When the schema was last introspected */
+  updatedAt: Date;
+}
+/**
+ * A single filter condition.
+ */
+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.
+ */
+interface SortConfig {
+  /** Column to sort by */
+  column: string;
+  /** Sort direction */
+  direction: Direction;
+}
+/**
+ * Options for querying table data.
+ */
+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.
+ */
+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;
+}
+/**
+ * Types of events broadcast via WebSocket.
+ */
+type StudioEventType = 'request' | 'exception' | 'log' | 'stats' | 'connected' | 'schema_updated';
+/**
+ * A WebSocket event payload.
+ */
+interface StudioEvent<T = unknown> {
+  /** Event type */
+  type: StudioEventType;
+  /** Event payload */
+  payload: T;
+  /** Event timestamp */
+  timestamp: number;
+}
+//#endregion
+//#region src/data/DataBrowser.d.ts
+/**
+ * Database browser for introspecting and querying PostgreSQL databases.
+ *
+ * @example
+ * ```typescript
+ * const browser = new DataBrowser({
+ *   db: kyselyInstance,
+ *   cursor: { field: 'id', direction: Direction.Desc },
+ * });
+ *
+ * const schema = await browser.getSchema();
+ * const result = await browser.query({ table: 'users', pageSize: 20 });
+ * ```
+ */
+declare class DataBrowser<DB = unknown> {
+  private db;
+  private options;
+  private schemaCache;
+  private schemaCacheExpiry;
+  private readonly CACHE_TTL_MS;
+  constructor(options: Required<DataBrowserOptions<DB>>);
+  /**
+   * Get the database schema information.
+   * Results are cached for 1 minute.
+   *
+   * @param forceRefresh - Force a refresh of the cache
+   */
+  getSchema(forceRefresh?: boolean): Promise<SchemaInfo>;
+  /**
+   * Get information about a specific table.
+   */
+  getTableInfo(tableName: string): Promise<TableInfo | null>;
+  /**
+   * Query table data with pagination, filtering, and sorting.
+   */
+  query(options: QueryOptions): Promise<QueryResult>;
+  /**
+   * Get the cursor configuration for a table.
+   * Returns the table-specific config if defined, otherwise the default.
+   */
+  getCursorConfig(tableName: string): CursorConfig;
+  /**
+   * Get the underlying Kysely database instance.
+   */
+  get database(): Kysely<DB>;
+}
+//#endregion
+export { ColumnInfo, ColumnType, CursorConfig, DataBrowser, DataBrowserOptions, Direction, FilterCondition, FilterOperator, MonitoringOptions, NormalizedStudioOptions, QueryOptions, QueryResult, SchemaInfo, SortConfig, StudioEvent, StudioEventType, StudioOptions, TableCursorConfig, TableInfo };
+//# sourceMappingURL=DataBrowser-SOcqmZb2.d.mts.map

package/dist/DataBrowser-c-Gs6PZB.cjs

@@ -0,0 +1,432 @@
+const require_types = require('./types-CMttUZYk.cjs');
+
+//#region src/data/filtering.ts
+/**
+* Validates that a filter is applicable to the given column.
+*/
+function validateFilter(filter, columnInfo) {
+	const typeCompatibility = {
+		string: [
+			require_types.FilterOperator.Eq,
+			require_types.FilterOperator.Neq,
+			require_types.FilterOperator.Like,
+			require_types.FilterOperator.Ilike,
+			require_types.FilterOperator.In,
+			require_types.FilterOperator.Nin,
+			require_types.FilterOperator.IsNull,
+			require_types.FilterOperator.IsNotNull
+		],
+		number: [
+			require_types.FilterOperator.Eq,
+			require_types.FilterOperator.Neq,
+			require_types.FilterOperator.Gt,
+			require_types.FilterOperator.Gte,
+			require_types.FilterOperator.Lt,
+			require_types.FilterOperator.Lte,
+			require_types.FilterOperator.In,
+			require_types.FilterOperator.Nin,
+			require_types.FilterOperator.IsNull,
+			require_types.FilterOperator.IsNotNull
+		],
+		boolean: [
+			require_types.FilterOperator.Eq,
+			require_types.FilterOperator.Neq,
+			require_types.FilterOperator.IsNull,
+			require_types.FilterOperator.IsNotNull
+		],
+		date: [
+			require_types.FilterOperator.Eq,
+			require_types.FilterOperator.Neq,
+			require_types.FilterOperator.Gt,
+			require_types.FilterOperator.Gte,
+			require_types.FilterOperator.Lt,
+			require_types.FilterOperator.Lte,
+			require_types.FilterOperator.IsNull,
+			require_types.FilterOperator.IsNotNull
+		],
+		datetime: [
+			require_types.FilterOperator.Eq,
+			require_types.FilterOperator.Neq,
+			require_types.FilterOperator.Gt,
+			require_types.FilterOperator.Gte,
+			require_types.FilterOperator.Lt,
+			require_types.FilterOperator.Lte,
+			require_types.FilterOperator.IsNull,
+			require_types.FilterOperator.IsNotNull
+		],
+		uuid: [
+			require_types.FilterOperator.Eq,
+			require_types.FilterOperator.Neq,
+			require_types.FilterOperator.In,
+			require_types.FilterOperator.Nin,
+			require_types.FilterOperator.IsNull,
+			require_types.FilterOperator.IsNotNull
+		],
+		json: [require_types.FilterOperator.IsNull, require_types.FilterOperator.IsNotNull],
+		binary: [require_types.FilterOperator.IsNull, require_types.FilterOperator.IsNotNull],
+		unknown: [
+			require_types.FilterOperator.Eq,
+			require_types.FilterOperator.Neq,
+			require_types.FilterOperator.IsNull,
+			require_types.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.
+*/
+function applyFilters(query, filters, tableInfo) {
+	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(query, filter) {
+	const { column, operator, value } = filter;
+	switch (operator) {
+		case require_types.FilterOperator.Eq: return query.where(column, "=", value);
+		case require_types.FilterOperator.Neq: return query.where(column, "!=", value);
+		case require_types.FilterOperator.Gt: return query.where(column, ">", value);
+		case require_types.FilterOperator.Gte: return query.where(column, ">=", value);
+		case require_types.FilterOperator.Lt: return query.where(column, "<", value);
+		case require_types.FilterOperator.Lte: return query.where(column, "<=", value);
+		case require_types.FilterOperator.Like: return query.where(column, "like", value);
+		case require_types.FilterOperator.Ilike: return query.where(column, "ilike", value);
+		case require_types.FilterOperator.In: return query.where(column, "in", value);
+		case require_types.FilterOperator.Nin: return query.where(column, "not in", value);
+		case require_types.FilterOperator.IsNull: return query.where(column, "is", null);
+		case require_types.FilterOperator.IsNotNull: return query.where(column, "is not", null);
+		default: throw new Error(`Unknown filter operator: ${operator}`);
+	}
+}
+/**
+* Applies sorting to a Kysely query builder.
+*/
+function applySorting(query, sorts, tableInfo) {
+	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, sort.direction === require_types.Direction.Asc ? "asc" : "desc");
+	}
+	return result;
+}
+
+//#endregion
+//#region src/data/introspection.ts
+/**
+* Introspects the database schema to discover tables and columns.
+* Uses PostgreSQL information_schema for metadata.
+*/
+async function introspectSchema(db, excludeTables) {
+	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
+	});
+	const tables = [];
+	for (const row of tablesResult.rows) {
+		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: /* @__PURE__ */ new Date()
+	};
+}
+/**
+* Introspects a single table to get column information.
+*/
+async function introspectTable(db, tableName, schema = "public") {
+	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]
+	});
+	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]
+	});
+	const foreignKeys = /* @__PURE__ */ new Map();
+	for (const row of fkResult.rows) {
+		const colName = row.column_name ?? row.columnName;
+		foreignKeys.set(colName, {
+			table: row.foreign_table ?? row.foreignTable,
+			column: row.foreign_column ?? row.foreignColumn
+		});
+	}
+	const columns = columnsResult.rows.map((row) => {
+		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,
+			isForeignKey: !!fk,
+			foreignKeyTable: fk?.table,
+			foreignKeyColumn: fk?.column,
+			defaultValue: columnDefault ?? void 0
+		};
+	});
+	const primaryKey = columns.filter((c) => c.isPrimaryKey).map((c) => c.name);
+	const countQuery = `
+    SELECT reltuples::bigint AS estimate
+    FROM pg_class
+    WHERE relname = $1
+  `;
+	let estimatedRowCount;
+	try {
+		const countResult = await db.executeQuery({
+			sql: countQuery,
+			parameters: [tableName]
+		});
+		if (countResult.rows.length > 0) {
+			const estimate = countResult.rows[0].estimate;
+			estimatedRowCount = estimate > 0 ? Number(estimate) : void 0;
+		}
+	} catch {}
+	return {
+		name: tableName,
+		schema,
+		columns,
+		primaryKey,
+		estimatedRowCount
+	};
+}
+/**
+* Maps PostgreSQL types to generic column types.
+*/
+function mapPostgresType(udtName) {
+	const typeMap = {
+		varchar: "string",
+		char: "string",
+		text: "string",
+		name: "string",
+		bpchar: "string",
+		int2: "number",
+		int4: "number",
+		int8: "number",
+		float4: "number",
+		float8: "number",
+		numeric: "number",
+		money: "number",
+		serial: "number",
+		bigserial: "number",
+		bool: "boolean",
+		date: "date",
+		timestamp: "datetime",
+		timestamptz: "datetime",
+		time: "datetime",
+		timetz: "datetime",
+		json: "json",
+		jsonb: "json",
+		bytea: "binary",
+		uuid: "uuid"
+	};
+	return typeMap[udtName] ?? "unknown";
+}
+
+//#endregion
+//#region src/data/pagination.ts
+/**
+* Cursor encoding/decoding utilities for pagination.
+*/
+/**
+* Encode a cursor value for safe URL transmission.
+* Supports various types: string, number, Date, etc.
+*/
+function encodeCursor(value) {
+	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.
+*/
+function decodeCursor(cursor) {
+	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");
+	}
+}
+
+//#endregion
+//#region src/data/DataBrowser.ts
+/**
+* Database browser for introspecting and querying PostgreSQL databases.
+*
+* @example
+* ```typescript
+* const browser = new DataBrowser({
+*   db: kyselyInstance,
+*   cursor: { field: 'id', direction: Direction.Desc },
+* });
+*
+* const schema = await browser.getSchema();
+* const result = await browser.query({ table: 'users', pageSize: 20 });
+* ```
+*/
+var DataBrowser = class {
+	db;
+	options;
+	schemaCache = null;
+	schemaCacheExpiry = 0;
+	CACHE_TTL_MS = 60 * 1e3;
+	constructor(options) {
+		this.db = options.db;
+		this.options = options;
+	}
+	/**
+	* Get the database schema information.
+	* Results are cached for 1 minute.
+	*
+	* @param forceRefresh - Force a refresh of the cache
+	*/
+	async getSchema(forceRefresh = false) {
+		const now = Date.now();
+		if (!forceRefresh && this.schemaCache && now < this.schemaCacheExpiry) return this.schemaCache;
+		const schema = await introspectSchema(this.db, this.options.excludeTables);
+		this.schemaCache = schema;
+		this.schemaCacheExpiry = now + this.CACHE_TTL_MS;
+		return schema;
+	}
+	/**
+	* Get information about a specific table.
+	*/
+	async getTableInfo(tableName) {
+		const schema = await this.getSchema();
+		return schema.tables.find((t) => t.name === tableName) ?? null;
+	}
+	/**
+	* Query table data with pagination, filtering, and sorting.
+	*/
+	async query(options) {
+		const tableInfo = await this.getTableInfo(options.table);
+		if (!tableInfo) throw new Error(`Table '${options.table}' not found`);
+		const cursorConfig = this.getCursorConfig(options.table);
+		const pageSize = Math.min(options.pageSize ?? this.options.defaultPageSize, 100);
+		let query = this.db.selectFrom(options.table).selectAll();
+		if (options.filters && options.filters.length > 0) query = applyFilters(query, options.filters, tableInfo);
+		if (options.sort && options.sort.length > 0) query = applySorting(query, options.sort, tableInfo);
+		else query = query.orderBy(cursorConfig.field, cursorConfig.direction);
+		if (options.cursor) {
+			const cursorValue = decodeCursor(options.cursor);
+			const operator = cursorConfig.direction === require_types.Direction.Asc ? ">" : "<";
+			query = query.where(cursorConfig.field, operator, cursorValue);
+		}
+		const rows = await query.limit(pageSize + 1).execute();
+		const hasMore = rows.length > pageSize;
+		const resultRows = hasMore ? rows.slice(0, pageSize) : rows;
+		let nextCursor = null;
+		let prevCursor = null;
+		if (hasMore && resultRows.length > 0) {
+			const lastRow = resultRows[resultRows.length - 1];
+			nextCursor = encodeCursor(lastRow[cursorConfig.field]);
+		}
+		if (options.cursor && resultRows.length > 0) {
+			const firstRow = resultRows[0];
+			prevCursor = encodeCursor(firstRow[cursorConfig.field]);
+		}
+		return {
+			rows: resultRows,
+			hasMore,
+			nextCursor,
+			prevCursor
+		};
+	}
+	/**
+	* Get the cursor configuration for a table.
+	* Returns the table-specific config if defined, otherwise the default.
+	*/
+	getCursorConfig(tableName) {
+		return this.options.tableCursors[tableName] ?? this.options.cursor;
+	}
+	/**
+	* Get the underlying Kysely database instance.
+	*/
+	get database() {
+		return this.db;
+	}
+};
+
+//#endregion
+Object.defineProperty(exports, 'DataBrowser', {
+  enumerable: true,
+  get: function () {
+    return DataBrowser;
+  }
+});
+//# sourceMappingURL=DataBrowser-c-Gs6PZB.cjs.map