@gallopsystems/agent-skills 1.0.0

package/plugins/kysely-postgres/skills/kysely-postgres/references/aggregations.ts

@@ -0,0 +1,167 @@
+/**
+ * Aggregation Patterns
+ * COUNT, SUM, AVG, GROUP BY, HAVING
+ */
+import { db } from "./db";
+
+// ============================================
+// BASIC AGGREGATIONS
+// ============================================
+
+// COUNT - total rows
+const totalUsers = await db
+  .selectFrom("user")
+  .select((eb) => eb.fn.count("id").as("totalUsers"))
+  .executeTakeFirst();
+// Result: { totalUsers: "5" } - Note: returned as string!
+
+// COUNT with GROUP BY
+const usersByRole = await db
+  .selectFrom("user")
+  .select((eb) => [
+    "role",
+    eb.fn.count("id").as("count"),
+  ])
+  .groupBy("role")
+  .execute();
+// Result: [{ role: "admin", count: "1" }, { role: "user", count: "3" }]
+
+// SUM
+const totalRevenue = await db
+  .selectFrom("order")
+  .where("status", "=", "completed")
+  .select((eb) => eb.fn.sum("total_amount").as("totalRevenue"))
+  .executeTakeFirst();
+
+// AVG
+const averageRating = await db
+  .selectFrom("review")
+  .select((eb) => eb.fn.avg("rating").as("averageRating"))
+  .executeTakeFirst();
+
+// ============================================
+// MULTIPLE AGGREGATIONS
+// ============================================
+
+// Multiple aggregations with GROUP BY
+const orderStats = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "status",
+    eb.fn.count("id").as("orderCount"),
+    eb.fn.sum("total_amount").as("totalAmount"),
+    eb.fn.avg("total_amount").as("avgAmount"),
+  ])
+  .groupBy("status")
+  .execute();
+
+// ============================================
+// HAVING CLAUSE
+// ============================================
+
+// HAVING - filter aggregated results
+// Use HAVING for conditions on aggregated values
+// Use WHERE for conditions on individual rows
+const popularProducts = await db
+  .selectFrom("review")
+  .innerJoin("product", "product.id", "review.product_id")
+  .select((eb) => [
+    "product.name",
+    eb.fn.count("review.id").as("reviewCount"),
+    eb.fn.avg("review.rating").as("avgRating"),
+  ])
+  .groupBy("product.id")
+  .groupBy("product.name") // Group by all non-aggregated columns
+  .having((eb) => eb.fn.count("review.id"), ">", 1)
+  .execute();
+
+// ============================================
+// FILTER (WHERE ...) ON AGGREGATES
+// ============================================
+
+// PostgreSQL's FILTER (WHERE ...) clause works on ALL aggregate function builders
+// via .filterWhere(). This is NOT specific to jsonAgg — it works on count, sum, avg, etc.
+
+// Basic usage: conditional counting/summing without CASE expressions
+const filteredAggregates = await db
+  .selectFrom("user")
+  .select((eb) => [
+    eb.fn.count("id").filterWhere("status", "=", "active").as("active_count"),
+    eb.fn.countAll().filterWhere("role", "!=", "banned").as("non_banned"),
+    eb.fn.sum("balance").filterWhere("type", "=", "credit").as("total_credits"),
+    eb.fn.avg("rating").filterWhere("verified", "=", true).as("verified_avg_rating"),
+  ])
+  .executeTakeFirst();
+
+// .filterWhere() also works inside .having() as the first argument
+const groupsWithNoUnsigned = await db
+  .selectFrom("document")
+  .select((eb) => [
+    "group_id",
+    eb.fn.countAll().as("total"),
+    eb.fn.countAll().filterWhere("status", "!=", "signed").as("unsigned_count"),
+  ])
+  .groupBy("group_id")
+  .having(
+    (eb) => eb.fn.countAll().filterWhere("status", "!=", "signed"),
+    "=",
+    0
+  )
+  .execute();
+
+// ============================================
+// AGGREGATE FUNCTIONS REFERENCE
+// ============================================
+
+// Available aggregate functions:
+// eb.fn.count(column)     - Count rows
+// eb.fn.countAll()        - COUNT(*)
+// eb.fn.sum(column)       - Sum values
+// eb.fn.avg(column)       - Average value
+// eb.fn.min(column)       - Minimum value
+// eb.fn.max(column)       - Maximum value
+
+// Example with all
+const productStats = await db
+  .selectFrom("product")
+  .select((eb) => [
+    eb.fn.count("id").as("total"),
+    eb.fn.countAll().as("totalAll"),
+    eb.fn.sum("price").as("totalPrice"),
+    eb.fn.avg("price").as("avgPrice"),
+    eb.fn.min("price").as("minPrice"),
+    eb.fn.max("price").as("maxPrice"),
+  ])
+  .executeTakeFirst();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. Aggregate functions return strings
+   - count, sum, avg all return string type by default
+   - Cast if you need numbers: eb.fn.count<number>("id")
+
+2. GROUP BY rules:
+   - All non-aggregated columns in SELECT must be in GROUP BY
+   - Chain multiple .groupBy() calls for multiple columns
+
+3. HAVING vs WHERE:
+   - WHERE: filters rows BEFORE aggregation
+   - HAVING: filters groups AFTER aggregation
+
+4. Syntax pattern:
+   .select((eb) => [
+     "groupColumn",
+     eb.fn.count("id").as("alias"),
+   ])
+   .groupBy("groupColumn")
+   .having((eb) => eb.fn.count("id"), ">", 5)
+
+5. .filterWhere() - PostgreSQL FILTER (WHERE ...) clause:
+   - Available on ALL aggregate function builders (count, countAll, sum, avg, min, max, jsonAgg)
+   - Replaces CASE WHEN ... inside aggregates for conditional aggregation
+   - Works as the first argument to .having() for filtered aggregate conditions
+   - Example: eb.fn.count("id").filterWhere("status", "=", "active").as("active_count")
+*/

package/plugins/kysely-postgres/skills/kysely-postgres/references/ctes.ts

@@ -0,0 +1,165 @@
+/**
+ * CTE (Common Table Expression) Patterns
+ * WITH clauses for complex multi-step queries
+ */
+import { db } from "./db";
+
+// ============================================
+// SIMPLE CTE
+// ============================================
+
+// Basic CTE - named subquery
+const activeProducts = await db
+  .with("active_products", (db) =>
+    db
+      .selectFrom("product")
+      .select(["id", "name", "price"])
+      .where("is_active", "=", true)
+  )
+  .selectFrom("active_products")
+  .selectAll()
+  .execute();
+
+// ============================================
+// CTE WITH AGGREGATION
+// ============================================
+
+// CTE for pre-aggregating data
+const topSpenders = await db
+  .with("order_totals", (db) =>
+    db
+      .selectFrom("order")
+      .innerJoin("user", "user.id", "order.user_id")
+      .select((eb) => [
+        "user.id as userId",
+        "user.email",
+        eb.fn.sum("order.total_amount").as("totalSpent"),
+        eb.fn.count("order.id").as("orderCount"),
+      ])
+      .groupBy(["user.id", "user.email"])
+  )
+  .selectFrom("order_totals")
+  .selectAll()
+  .orderBy("totalSpent", "desc")
+  .execute();
+
+// ============================================
+// MULTIPLE CTEs
+// ============================================
+
+// Chain CTEs for multi-step processing
+const topRatedProducts = await db
+  // First CTE: aggregate reviews
+  .with("product_reviews", (db) =>
+    db
+      .selectFrom("review")
+      .select((eb) => [
+        "product_id",
+        eb.fn.avg("rating").as("avgRating"),
+        eb.fn.count("id").as("reviewCount"),
+      ])
+      .groupBy("product_id")
+  )
+  // Second CTE: join with products
+  .with("top_products", (db) =>
+    db
+      .selectFrom("product")
+      .leftJoin("product_reviews", "product_reviews.product_id", "product.id")
+      .select([
+        "product.name",
+        "product.price",
+        "product_reviews.avgRating",
+        "product_reviews.reviewCount",
+      ])
+      .where("product.is_active", "=", true)
+  )
+  // Final query: select from last CTE
+  .selectFrom("top_products")
+  .selectAll()
+  .orderBy("avgRating", (ob) => ob.desc().nullsLast())
+  .execute();
+
+// ============================================
+// CTE USE CASES
+// ============================================
+
+// Use Case 1: Break down complex logic
+const dashboardData = await db
+  .with("monthly_orders", (db) =>
+    db
+      .selectFrom("order")
+      .select((eb) => [
+        eb.fn.count("id").as("orderCount"),
+        eb.fn.sum("total_amount").as("revenue"),
+      ])
+      .where("status", "=", "completed")
+  )
+  .with("active_users", (db) =>
+    db
+      .selectFrom("user")
+      .select((eb) => eb.fn.count("id").as("userCount"))
+      .where("is_active", "=", true)
+  )
+  .selectFrom("monthly_orders")
+  .innerJoin("active_users", (join) =>
+    join.on((eb) => eb.lit(true)) // Cross join
+  )
+  .select([
+    "monthly_orders.orderCount",
+    "monthly_orders.revenue",
+    "active_users.userCount",
+  ])
+  .executeTakeFirst();
+
+// Use Case 2: Self-referencing/recursive (for hierarchies)
+// Note: Recursive CTEs use withRecursive
+const categoryHierarchy = await db
+  .withRecursive("category_tree", (db) =>
+    // Base case: root categories
+    db
+      .selectFrom("category")
+      .select(["id", "name", "parent_id"])
+      .where("parent_id", "is", null)
+      .unionAll(
+        // Recursive case: children
+        db
+          .selectFrom("category as c")
+          .innerJoin("category_tree as ct", "ct.id", "c.parent_id")
+          .select(["c.id", "c.name", "c.parent_id"])
+      )
+  )
+  .selectFrom("category_tree")
+  .selectAll()
+  .execute();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. Basic CTE syntax:
+   db.with("name", (db) => db.selectFrom(...))
+     .selectFrom("name")
+     .selectAll()
+
+2. Multiple CTEs - chain .with() calls:
+   db.with("cte1", ...)
+     .with("cte2", ...)  // Can reference cte1
+     .selectFrom("cte2")
+
+3. CTEs can reference earlier CTEs:
+   - cte2 can use cte1 in its FROM
+   - Order matters!
+
+4. Recursive CTEs:
+   - Use .withRecursive()
+   - Base case UNION ALL recursive case
+   - Recursive case joins to the CTE itself
+
+5. When to use CTEs:
+   - Complex multi-step aggregations
+   - Reusing a subquery multiple times
+   - Breaking down complex logic
+   - Recursive/hierarchical data
+   - Improving query readability
+*/

package/plugins/kysely-postgres/skills/kysely-postgres/references/expressions.ts

@@ -0,0 +1,272 @@
+/**
+ * Expression Patterns
+ * CASE, $if, subqueries, eb functions, advanced expression building
+ */
+import { db } from "./db";
+import { sql, expressionBuilder, Expression, SqlBool } from "kysely";
+import type { DB } from "./db.d";
+
+// ============================================
+// CASE EXPRESSIONS
+// ============================================
+
+// Simple CASE
+const ordersWithLabels = await db
+  .selectFrom("order")
+  .select((eb) => [
+    "id",
+    "status",
+    eb
+      .case()
+      .when("status", "=", "completed")
+      .then("Done")
+      .when("status", "=", "shipped")
+      .then("In Transit")
+      .when("status", "=", "pending")
+      .then("Processing")
+      .else("Unknown")
+      .end()
+      .as("statusLabel"),
+  ])
+  .execute();
+
+// ============================================
+// $if - CONDITIONAL QUERY BUILDING
+// ============================================
+
+// $if for conditional WHERE
+const includeInactive = false;
+const users = await db
+  .selectFrom("user")
+  .selectAll()
+  .$if(!includeInactive, (qb) => qb.where("is_active", "=", true))
+  .execute();
+
+// $if for conditional SELECT columns
+const includeMetadata = true;
+const usersWithOptionalMeta = await db
+  .selectFrom("user")
+  .select(["id", "email", "first_name", "last_name"])
+  .$if(includeMetadata, (qb) => qb.select("metadata"))
+  .execute();
+// Note: metadata becomes OPTIONAL in result type (metadata?: Json)
+
+// Multiple $if conditions
+const filterRole: string | null = "admin";
+const onlyActive = true;
+const filteredUsers = await db
+  .selectFrom("user")
+  .selectAll()
+  .$if(!!filterRole, (qb) => qb.where("role", "=", filterRole!))
+  .$if(onlyActive, (qb) => qb.where("is_active", "=", true))
+  .execute();
+
+// ============================================
+// SUBQUERIES
+// ============================================
+
+// Subquery in WHERE (IN)
+const usersWithOrders = await db
+  .selectFrom("user")
+  .selectAll()
+  .where(
+    "id",
+    "in",
+    db.selectFrom("order").select("user_id").where("status", "=", "completed")
+  )
+  .execute();
+
+// EXISTS subquery
+const productsWithReviews = await db
+  .selectFrom("product")
+  .selectAll()
+  .where((eb) =>
+    eb.exists(
+      db
+        .selectFrom("review")
+        .select(sql`1`.as("one"))
+        .whereRef("review.product_id", "=", eb.ref("product.id"))
+    )
+  )
+  .execute();
+
+// ============================================
+// eb.fn - FUNCTION CALLS
+// ============================================
+
+// String functions with eb.fn<ReturnType>
+const userNames = await db
+  .selectFrom("user")
+  .select((eb) => [
+    eb.fn<string>("concat", [
+      eb.ref("first_name"),
+      eb.cast(eb.val(" "), "text"), // Cast string literals!
+      eb.ref("last_name"),
+    ]).as("fullName"),
+    eb.fn<string>("upper", [eb.ref("email")]).as("upperEmail"),
+    eb.fn<number>("length", [eb.ref("email")]).as("emailLength"),
+  ])
+  .execute();
+
+// COALESCE
+const productsWithDefault = await db
+  .selectFrom("product")
+  .select((eb) => [
+    "name",
+    eb.fn.coalesce("cost", sql`0`).as("costOrZero"),
+  ])
+  .execute();
+
+// ============================================
+// BINARY EXPRESSIONS
+// ============================================
+
+// Arithmetic with eb()
+const lineItems = await db
+  .selectFrom("order_item")
+  .select((eb) => [
+    "id",
+    "quantity",
+    "unit_price",
+    eb("quantity", "*", eb.ref("unit_price")).as("lineTotal"),
+  ])
+  .execute();
+
+// ============================================
+// eb.val() vs eb.lit()
+// ============================================
+
+// eb.val() - Parameterized value ($1, $2) - SAFER for user input
+// Note: May need cast for type inference
+const searchTerm = "alice";
+const searchResults = await db
+  .selectFrom("user")
+  .select(["id", "email"])
+  .where("email", "like", (eb) =>
+    eb.fn<string>("concat", [
+      eb.cast(eb.val("%"), "text"),
+      eb.cast(eb.val(searchTerm), "text"),
+      eb.cast(eb.val("%"), "text"),
+    ])
+  )
+  .execute();
+
+// eb.lit() - Literal in SQL - ONLY for numbers, booleans, null
+// THROWS "unsafe immediate value" for strings!
+const priceCategories = await db
+  .selectFrom("product")
+  .select((eb) => [
+    "name",
+    "price",
+    eb
+      .case()
+      .when("price", ">", eb.lit(100)) // Number literal - OK
+      .then(sql<string>`'expensive'`)   // String - use sql``
+      .when("price", ">", eb.lit(50))   // Number literal - OK
+      .then(sql<string>`'moderate'`)    // String - use sql``
+      .else(sql<string>`'cheap'`)       // String - use sql``
+      .end()
+      .as("priceCategory"),
+  ])
+  .execute();
+
+// ============================================
+// eb.not() - NEGATION
+// ============================================
+
+// Negate a condition
+const inactiveProducts = await db
+  .selectFrom("product")
+  .select(["name", "is_active"])
+  .where((eb) => eb.not(eb("is_active", "=", true)))
+  .execute();
+
+// NOT EXISTS
+const usersWithoutOrders = await db
+  .selectFrom("user")
+  .select(["id", "email"])
+  .where((eb) =>
+    eb.not(
+      eb.exists(
+        db
+          .selectFrom("order")
+          .select(sql`1`.as("one"))
+          .whereRef("order.user_id", "=", "user.id")
+      )
+    )
+  )
+  .execute();
+
+// ============================================
+// STANDALONE expressionBuilder
+// ============================================
+
+// Build expressions outside query context
+const eb = expressionBuilder<DB, "user">();
+const activeCondition = eb("is_active", "=", true);
+const adminCondition = eb("role", "=", "admin");
+
+const activeAdmins = await db
+  .selectFrom("user")
+  .select(["id", "email", "role"])
+  .where((qb) => qb.and([activeCondition, adminCondition]))
+  .execute();
+
+// ============================================
+// CONDITIONAL EXPRESSIONS WITH ARRAYS
+// ============================================
+
+// Build conditions dynamically
+const conditions: Expression<SqlBool>[] = [];
+const productEb = expressionBuilder<DB, "product">();
+
+const filterActive = true;
+const minPrice = 50;
+const maxPrice: number | null = null;
+
+if (filterActive) {
+  conditions.push(productEb("is_active", "=", true));
+}
+if (minPrice) {
+  conditions.push(productEb("price", ">=", String(minPrice)));
+}
+if (maxPrice) {
+  conditions.push(productEb("price", "<=", String(maxPrice)));
+}
+
+const filteredProducts = await db
+  .selectFrom("product")
+  .select(["name", "price", "is_active"])
+  .$if(conditions.length > 0, (qb) => qb.where((eb) => eb.and(conditions)))
+  .execute();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. CASE expressions:
+   eb.case().when(...).then(...).else(...).end()
+
+2. $if for conditional query parts:
+   .$if(condition, (qb) => qb.where/select/etc)
+   - Columns added via $if become OPTIONAL in type
+
+3. eb.val() vs eb.lit():
+   - eb.val(): Parameterized ($1) - use for user input
+   - eb.lit(): Literal - ONLY numbers, booleans, null
+   - For string literals: use sql`'string'`
+
+4. eb.not(): Negate any expression
+   eb.not(eb("col", "=", value))
+   eb.not(eb.exists(...))
+
+5. Standalone expressionBuilder:
+   const eb = expressionBuilder<DB, "table">();
+   - Build expressions outside query context
+   - Useful for dynamic condition building
+
+6. Expression<SqlBool>[] arrays:
+   - Build conditions dynamically
+   - Combine with eb.and([...]) or eb.or([...])
+*/