@indiekitai/pg-toolkit 0.1.0

package/dist/index.cjs

@@ -0,0 +1,220 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PgInspector: () => import_pg_inspect.PgInspector,
+  PgMonitor: () => import_pg_top.PgMonitor,
+  analyze: () => analyze,
+  computeDiff: () => import_pg_diff.computeDiff,
+  diff: () => import_pg_diff.diff,
+  formatAnalyzeResult: () => formatAnalyzeResult,
+  inspect: () => import_pg_inspect.inspect,
+  inspectSchema: () => import_pg_diff.inspectSchema
+});
+module.exports = __toCommonJS(index_exports);
+var import_pg_inspect = require("@indiekitai/pg-inspect");
+var import_pg_diff = require("@indiekitai/pg-diff");
+
+// src/analyze.ts
+var EAV_ENTITY_PATTERNS = /^(entity|item|record|submission|object|resource|parent)[_]?id$/i;
+var EAV_KEY_PATTERNS = /^(key|name|attribute|field|property|type|kind|label)[_]?(name|key|id)?$/i;
+var EAV_VALUE_PATTERNS = /^(value|data|content|payload|text)$/i;
+function detectEav(tableName, columns) {
+  const colNames = columns.map((c) => c.columnName);
+  const entityCol = colNames.find((c) => EAV_ENTITY_PATTERNS.test(c));
+  const keyCol = colNames.find((c) => EAV_KEY_PATTERNS.test(c));
+  const valueCol = colNames.find((c) => EAV_VALUE_PATTERNS.test(c));
+  if (entityCol && keyCol && valueCol) {
+    return {
+      type: "eav_pattern",
+      severity: "high",
+      table: tableName,
+      description: `Table "${tableName}" looks like an EAV table (entity=${entityCol}, key=${keyCol}, value=${valueCol}). Querying parent + this table typically causes N+1.`,
+      suggestion: `Use CTE + JSON_AGG to aggregate rows by "${entityCol}" in a single query.`,
+      sql: `WITH aggregated AS (
+  SELECT
+    "${entityCol}",
+    JSON_AGG(JSON_BUILD_OBJECT('${keyCol}', "${keyCol}", '${valueCol}', "${valueCol}")) AS attrs
+  FROM "${tableName}"
+  GROUP BY "${entityCol}"
+)
+SELECT p.*, COALESCE(a.attrs, '[]'::json) AS attrs
+FROM <parent_table> p
+LEFT JOIN aggregated a ON a."${entityCol}" = p.id;`
+    };
+  }
+  return null;
+}
+function detectNPlus1FromFks(fks) {
+  const parentToChildren = /* @__PURE__ */ new Map();
+  for (const fk of fks) {
+    const list = parentToChildren.get(fk.parentTable) || [];
+    list.push(fk);
+    parentToChildren.set(fk.parentTable, list);
+  }
+  const warnings = [];
+  for (const [parentTable, children] of parentToChildren) {
+    for (const fk of children) {
+      if (fk.childTable === parentTable) continue;
+      warnings.push({
+        type: "n_plus_1_risk",
+        severity: "medium",
+        table: fk.childTable,
+        parentTable,
+        description: `"${fk.childTable}".${fk.childColumn} \u2192 "${parentTable}".${fk.parentColumn}. Loading ${parentTable} list + ${fk.childTable} details per row = N+1.`,
+        suggestion: `Use CTE + JSON_AGG to pre-aggregate "${fk.childTable}" rows per "${fk.childColumn}".`,
+        sql: `WITH child_agg AS (
+  SELECT "${fk.childColumn}", JSON_AGG(t.*) AS children
+  FROM "${fk.childTable}" t
+  GROUP BY "${fk.childColumn}"
+)
+SELECT p.*, COALESCE(c.children, '[]'::json) AS ${fk.childTable}
+FROM "${parentTable}" p
+LEFT JOIN child_agg c ON c."${fk.childColumn}" = p."${fk.parentColumn}";`
+      });
+    }
+    const uniqueChildren = new Set(children.map((c) => c.childTable));
+    if (uniqueChildren.size > 2) {
+      warnings.push({
+        type: "multi_fk_parent",
+        severity: "low",
+        table: parentTable,
+        description: `"${parentTable}" has ${uniqueChildren.size} child tables referencing it. Loading all children per row compounds N+1.`,
+        suggestion: `Consider multiple CTEs in a single query to fetch all child data at once.`
+      });
+    }
+  }
+  return warnings;
+}
+async function analyze(connectionString) {
+  const pg = await import("pg");
+  const Pool = pg.default?.Pool || pg.Pool;
+  const pool = new Pool({ connectionString });
+  try {
+    const dbResult = await pool.query("SELECT current_database() AS db");
+    const database = dbResult.rows[0].db;
+    const colResult = await pool.query(`
+      SELECT table_name, column_name, data_type, is_nullable = 'YES' AS is_nullable
+      FROM information_schema.columns
+      WHERE table_schema = 'public'
+      ORDER BY table_name, ordinal_position
+    `);
+    const columnsByTable = /* @__PURE__ */ new Map();
+    for (const row of colResult.rows) {
+      const list = columnsByTable.get(row.table_name) || [];
+      list.push({
+        tableName: row.table_name,
+        columnName: row.column_name,
+        dataType: row.data_type,
+        isNullable: row.is_nullable
+      });
+      columnsByTable.set(row.table_name, list);
+    }
+    const fkResult = await pool.query(`
+      SELECT
+        tc.constraint_name,
+        tc.table_name AS child_table,
+        kcu.column_name AS child_column,
+        ccu.table_name AS parent_table,
+        ccu.column_name AS parent_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.constraint_type = 'FOREIGN KEY' AND tc.table_schema = 'public'
+    `);
+    const fks = fkResult.rows.map((r) => ({
+      constraintName: r.constraint_name,
+      childTable: r.child_table,
+      childColumn: r.child_column,
+      parentTable: r.parent_table,
+      parentColumn: r.parent_column
+    }));
+    const warnings = [];
+    for (const [tableName, columns] of columnsByTable) {
+      const eav = detectEav(tableName, columns);
+      if (eav) warnings.push(eav);
+    }
+    warnings.push(...detectNPlus1FromFks(fks));
+    const severityOrder = { high: 0, medium: 1, low: 2 };
+    warnings.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+    return {
+      database,
+      analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      tablesScanned: columnsByTable.size,
+      warnings
+    };
+  } finally {
+    await pool.end();
+  }
+}
+function formatAnalyzeResult(result, json) {
+  if (json) return JSON.stringify(result, null, 2);
+  const lines = [];
+  lines.push(`\u{1F50D} N+1 Analysis for "${result.database}"`);
+  lines.push(`   Scanned ${result.tablesScanned} tables at ${result.analyzedAt}`);
+  lines.push("");
+  if (result.warnings.length === 0) {
+    lines.push("\u2705 No N+1 patterns detected.");
+    return lines.join("\n");
+  }
+  lines.push(`\u26A0\uFE0F  Found ${result.warnings.length} potential issue(s):
+`);
+  const severityIcon = { high: "\u{1F534}", medium: "\u{1F7E1}", low: "\u{1F535}" };
+  for (const w of result.warnings) {
+    lines.push(`${severityIcon[w.severity]} [${w.severity.toUpperCase()}] ${w.type}`);
+    lines.push(`   ${w.description}`);
+    lines.push(`   \u{1F4A1} ${w.suggestion}`);
+    if (w.sql) {
+      lines.push("   \u{1F4DD} Suggested SQL:");
+      for (const sqlLine of w.sql.split("\n")) {
+        lines.push(`      ${sqlLine}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/index.ts
+var import_pg_top = require("@indiekitai/pg-top");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PgInspector,
+  PgMonitor,
+  analyze,
+  computeDiff,
+  diff,
+  formatAnalyzeResult,
+  inspect,
+  inspectSchema
+});

package/dist/index.d.cts

@@ -0,0 +1,31 @@
+export { ConnectionConfig, PgInspector, inspect } from '@indiekitai/pg-inspect';
+export { DiffOptions, DiffResult, computeDiff, diff, inspectSchema } from '@indiekitai/pg-diff';
+export { Activity, DbStats, MonitorOptions, PgMonitor } from '@indiekitai/pg-top';
+
+/**
+ * pg-toolkit analyze — Detect N+1 query patterns and suggest CTE + JSON_AGG optimizations.
+ *
+ * Scans database schema for:
+ * - Many-to-one relationships (foreign keys)
+ * - EAV-pattern tables (entity_id + key/name + value columns)
+ * - Tables with multiple FKs pointing to the same parent
+ */
+interface AnalyzeWarning {
+    type: 'n_plus_1_risk' | 'eav_pattern' | 'multi_fk_parent';
+    severity: 'high' | 'medium' | 'low';
+    table: string;
+    parentTable?: string;
+    description: string;
+    suggestion: string;
+    sql?: string;
+}
+interface AnalyzeResult {
+    database: string;
+    analyzedAt: string;
+    tablesScanned: number;
+    warnings: AnalyzeWarning[];
+}
+declare function analyze(connectionString: string): Promise<AnalyzeResult>;
+declare function formatAnalyzeResult(result: AnalyzeResult, json: boolean): string;
+
+export { type AnalyzeResult, type AnalyzeWarning, analyze, formatAnalyzeResult };

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+export { ConnectionConfig, PgInspector, inspect } from '@indiekitai/pg-inspect';
+export { DiffOptions, DiffResult, computeDiff, diff, inspectSchema } from '@indiekitai/pg-diff';
+export { Activity, DbStats, MonitorOptions, PgMonitor } from '@indiekitai/pg-top';
+
+/**
+ * pg-toolkit analyze — Detect N+1 query patterns and suggest CTE + JSON_AGG optimizations.
+ *
+ * Scans database schema for:
+ * - Many-to-one relationships (foreign keys)
+ * - EAV-pattern tables (entity_id + key/name + value columns)
+ * - Tables with multiple FKs pointing to the same parent
+ */
+interface AnalyzeWarning {
+    type: 'n_plus_1_risk' | 'eav_pattern' | 'multi_fk_parent';
+    severity: 'high' | 'medium' | 'low';
+    table: string;
+    parentTable?: string;
+    description: string;
+    suggestion: string;
+    sql?: string;
+}
+interface AnalyzeResult {
+    database: string;
+    analyzedAt: string;
+    tablesScanned: number;
+    warnings: AnalyzeWarning[];
+}
+declare function analyze(connectionString: string): Promise<AnalyzeResult>;
+declare function formatAnalyzeResult(result: AnalyzeResult, json: boolean): string;
+
+export { type AnalyzeResult, type AnalyzeWarning, analyze, formatAnalyzeResult };

package/dist/index.js

@@ -0,0 +1,178 @@
+// src/index.ts
+import { PgInspector, inspect } from "@indiekitai/pg-inspect";
+import { inspectSchema, computeDiff, diff } from "@indiekitai/pg-diff";
+
+// src/analyze.ts
+var EAV_ENTITY_PATTERNS = /^(entity|item|record|submission|object|resource|parent)[_]?id$/i;
+var EAV_KEY_PATTERNS = /^(key|name|attribute|field|property|type|kind|label)[_]?(name|key|id)?$/i;
+var EAV_VALUE_PATTERNS = /^(value|data|content|payload|text)$/i;
+function detectEav(tableName, columns) {
+  const colNames = columns.map((c) => c.columnName);
+  const entityCol = colNames.find((c) => EAV_ENTITY_PATTERNS.test(c));
+  const keyCol = colNames.find((c) => EAV_KEY_PATTERNS.test(c));
+  const valueCol = colNames.find((c) => EAV_VALUE_PATTERNS.test(c));
+  if (entityCol && keyCol && valueCol) {
+    return {
+      type: "eav_pattern",
+      severity: "high",
+      table: tableName,
+      description: `Table "${tableName}" looks like an EAV table (entity=${entityCol}, key=${keyCol}, value=${valueCol}). Querying parent + this table typically causes N+1.`,
+      suggestion: `Use CTE + JSON_AGG to aggregate rows by "${entityCol}" in a single query.`,
+      sql: `WITH aggregated AS (
+  SELECT
+    "${entityCol}",
+    JSON_AGG(JSON_BUILD_OBJECT('${keyCol}', "${keyCol}", '${valueCol}', "${valueCol}")) AS attrs
+  FROM "${tableName}"
+  GROUP BY "${entityCol}"
+)
+SELECT p.*, COALESCE(a.attrs, '[]'::json) AS attrs
+FROM <parent_table> p
+LEFT JOIN aggregated a ON a."${entityCol}" = p.id;`
+    };
+  }
+  return null;
+}
+function detectNPlus1FromFks(fks) {
+  const parentToChildren = /* @__PURE__ */ new Map();
+  for (const fk of fks) {
+    const list = parentToChildren.get(fk.parentTable) || [];
+    list.push(fk);
+    parentToChildren.set(fk.parentTable, list);
+  }
+  const warnings = [];
+  for (const [parentTable, children] of parentToChildren) {
+    for (const fk of children) {
+      if (fk.childTable === parentTable) continue;
+      warnings.push({
+        type: "n_plus_1_risk",
+        severity: "medium",
+        table: fk.childTable,
+        parentTable,
+        description: `"${fk.childTable}".${fk.childColumn} \u2192 "${parentTable}".${fk.parentColumn}. Loading ${parentTable} list + ${fk.childTable} details per row = N+1.`,
+        suggestion: `Use CTE + JSON_AGG to pre-aggregate "${fk.childTable}" rows per "${fk.childColumn}".`,
+        sql: `WITH child_agg AS (
+  SELECT "${fk.childColumn}", JSON_AGG(t.*) AS children
+  FROM "${fk.childTable}" t
+  GROUP BY "${fk.childColumn}"
+)
+SELECT p.*, COALESCE(c.children, '[]'::json) AS ${fk.childTable}
+FROM "${parentTable}" p
+LEFT JOIN child_agg c ON c."${fk.childColumn}" = p."${fk.parentColumn}";`
+      });
+    }
+    const uniqueChildren = new Set(children.map((c) => c.childTable));
+    if (uniqueChildren.size > 2) {
+      warnings.push({
+        type: "multi_fk_parent",
+        severity: "low",
+        table: parentTable,
+        description: `"${parentTable}" has ${uniqueChildren.size} child tables referencing it. Loading all children per row compounds N+1.`,
+        suggestion: `Consider multiple CTEs in a single query to fetch all child data at once.`
+      });
+    }
+  }
+  return warnings;
+}
+async function analyze(connectionString) {
+  const pg = await import("pg");
+  const Pool = pg.default?.Pool || pg.Pool;
+  const pool = new Pool({ connectionString });
+  try {
+    const dbResult = await pool.query("SELECT current_database() AS db");
+    const database = dbResult.rows[0].db;
+    const colResult = await pool.query(`
+      SELECT table_name, column_name, data_type, is_nullable = 'YES' AS is_nullable
+      FROM information_schema.columns
+      WHERE table_schema = 'public'
+      ORDER BY table_name, ordinal_position
+    `);
+    const columnsByTable = /* @__PURE__ */ new Map();
+    for (const row of colResult.rows) {
+      const list = columnsByTable.get(row.table_name) || [];
+      list.push({
+        tableName: row.table_name,
+        columnName: row.column_name,
+        dataType: row.data_type,
+        isNullable: row.is_nullable
+      });
+      columnsByTable.set(row.table_name, list);
+    }
+    const fkResult = await pool.query(`
+      SELECT
+        tc.constraint_name,
+        tc.table_name AS child_table,
+        kcu.column_name AS child_column,
+        ccu.table_name AS parent_table,
+        ccu.column_name AS parent_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.constraint_type = 'FOREIGN KEY' AND tc.table_schema = 'public'
+    `);
+    const fks = fkResult.rows.map((r) => ({
+      constraintName: r.constraint_name,
+      childTable: r.child_table,
+      childColumn: r.child_column,
+      parentTable: r.parent_table,
+      parentColumn: r.parent_column
+    }));
+    const warnings = [];
+    for (const [tableName, columns] of columnsByTable) {
+      const eav = detectEav(tableName, columns);
+      if (eav) warnings.push(eav);
+    }
+    warnings.push(...detectNPlus1FromFks(fks));
+    const severityOrder = { high: 0, medium: 1, low: 2 };
+    warnings.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+    return {
+      database,
+      analyzedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      tablesScanned: columnsByTable.size,
+      warnings
+    };
+  } finally {
+    await pool.end();
+  }
+}
+function formatAnalyzeResult(result, json) {
+  if (json) return JSON.stringify(result, null, 2);
+  const lines = [];
+  lines.push(`\u{1F50D} N+1 Analysis for "${result.database}"`);
+  lines.push(`   Scanned ${result.tablesScanned} tables at ${result.analyzedAt}`);
+  lines.push("");
+  if (result.warnings.length === 0) {
+    lines.push("\u2705 No N+1 patterns detected.");
+    return lines.join("\n");
+  }
+  lines.push(`\u26A0\uFE0F  Found ${result.warnings.length} potential issue(s):
+`);
+  const severityIcon = { high: "\u{1F534}", medium: "\u{1F7E1}", low: "\u{1F535}" };
+  for (const w of result.warnings) {
+    lines.push(`${severityIcon[w.severity]} [${w.severity.toUpperCase()}] ${w.type}`);
+    lines.push(`   ${w.description}`);
+    lines.push(`   \u{1F4A1} ${w.suggestion}`);
+    if (w.sql) {
+      lines.push("   \u{1F4DD} Suggested SQL:");
+      for (const sqlLine of w.sql.split("\n")) {
+        lines.push(`      ${sqlLine}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/index.ts
+import { PgMonitor } from "@indiekitai/pg-top";
+export {
+  PgInspector,
+  PgMonitor,
+  analyze,
+  computeDiff,
+  diff,
+  formatAnalyzeResult,
+  inspect,
+  inspectSchema
+};