@gallopsystems/agent-skills 1.0.0

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

@@ -0,0 +1,206 @@
+/**
+ * JOIN Patterns
+ * Simple joins, multi-table joins, and complex callback joins
+ */
+import { db } from "./db";
+import { sql } from "kysely";
+
+// ============================================
+// BASIC JOINS
+// ============================================
+
+// Inner join - simple format
+const ordersWithUsers = await db
+  .selectFrom("order")
+  .innerJoin("user", "user.id", "order.user_id")
+  .select([
+    "order.id as orderId",
+    "order.status",
+    "user.email",
+    "user.first_name",
+  ])
+  .execute();
+
+// Left join - includes rows without matches
+const productsWithCategories = await db
+  .selectFrom("product")
+  .leftJoin("category", "category.id", "product.category_id")
+  .select([
+    "product.name as productName",
+    "category.name as categoryName", // null if no category
+  ])
+  .execute();
+
+// Multiple joins - chain them
+const orderDetails = await db
+  .selectFrom("order_item")
+  .innerJoin("order", "order.id", "order_item.order_id")
+  .innerJoin("product", "product.id", "order_item.product_id")
+  .innerJoin("user", "user.id", "order.user_id")
+  .select([
+    "user.email",
+    "product.name as productName",
+    "order_item.quantity",
+    "order_item.unit_price",
+  ])
+  .execute();
+
+// Self-join with aliases
+const categoriesWithParent = await db
+  .selectFrom("category as c")
+  .leftJoin("category as parent", "parent.id", "c.parent_id")
+  .select([
+    "c.name as categoryName",
+    "parent.name as parentCategoryName",
+  ])
+  .execute();
+
+// ============================================
+// COMPLEX JOINS (Callback Format)
+// ============================================
+
+// When to use callback format:
+// 1. Multiple join conditions (composite keys)
+// 2. Mixed column-to-column AND column-to-literal
+// 3. OR conditions in joins
+// 4. Subquery joins (derived tables)
+
+// Multi-condition join: onRef + on
+// onRef = column-to-column, on = column-to-literal
+const activeProductItems = await db
+  .selectFrom("order_item as oi")
+  .innerJoin("product as p", (join) =>
+    join
+      .onRef("p.id", "=", "oi.product_id")
+      .on("p.is_active", "=", true) // Filter in join, not WHERE
+  )
+  .select([
+    "oi.id as orderItemId",
+    "p.name as productName",
+    "oi.quantity",
+  ])
+  .execute();
+
+// Join with OR conditions
+const usersWithCompletedOrShipped = await db
+  .selectFrom("user as u")
+  .leftJoin("order as o", (join) =>
+    join
+      .onRef("o.user_id", "=", "u.id")
+      .on((eb) =>
+        eb.or([
+          eb("o.status", "=", "completed"),
+          eb("o.status", "=", "shipped"),
+        ])
+      )
+  )
+  .select([
+    "u.email",
+    "o.id as orderId",
+    "o.status",
+  ])
+  .execute();
+
+// ============================================
+// SUBQUERY JOINS (Derived Tables)
+// ============================================
+
+// Two-callback format: first builds subquery, second defines join
+const usersWithOrderStats = await db
+  .selectFrom("user as u")
+  .leftJoin(
+    // First callback: build the subquery
+    (eb) =>
+      eb
+        .selectFrom("order")
+        .select((eb) => [
+          "user_id",
+          eb.fn.count("id").as("order_count"),
+          eb.fn.sum("total_amount").as("total_spent"),
+        ])
+        .groupBy("user_id")
+        .as("order_stats"), // MUST have alias!
+    // Second callback: define join condition
+    (join) => join.onRef("order_stats.user_id", "=", "u.id")
+  )
+  .select([
+    "u.email",
+    "u.first_name",
+    "order_stats.order_count",
+    "order_stats.total_spent",
+  ])
+  .execute();
+
+// Subquery join with MAX aggregation
+const productsWithLatestReview = await db
+  .selectFrom("product as p")
+  .leftJoin(
+    (eb) =>
+      eb
+        .selectFrom("review")
+        .select((eb) => [
+          "product_id",
+          eb.fn.max("created_at").as("latest_review_at"),
+          eb.fn.count("id").as("review_count"),
+        ])
+        .groupBy("product_id")
+        .as("review_stats"),
+    (join) => join.onRef("review_stats.product_id", "=", "p.id")
+  )
+  .select([
+    "p.name",
+    "p.price",
+    "review_stats.latest_review_at",
+    "review_stats.review_count",
+  ])
+  .orderBy("review_stats.review_count", (ob) => ob.desc().nullsLast())
+  .execute();
+
+// ============================================
+// CROSS JOIN
+// ============================================
+
+// Cross join using always-true condition
+// Use case: Join CTE aggregation to main query
+const usersWithSummary = await db
+  .with("summary", (db) =>
+    db
+      .selectFrom("order")
+      .select((eb) => [
+        eb.fn.count("id").as("total_orders"),
+        eb.fn.sum("total_amount").as("total_revenue"),
+      ])
+  )
+  .selectFrom("user as u")
+  .leftJoin("summary", (join) =>
+    join.on(sql`true`, "=", sql`true`)
+  )
+  .select([
+    "u.email",
+    "summary.total_orders",
+    "summary.total_revenue",
+  ])
+  .where("u.role", "=", "admin")
+  .execute();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. Simple joins: .innerJoin("table", "a.col", "b.col")
+   - Use when joining on single column equality
+
+2. Callback joins: .innerJoin("table", (join) => join.onRef(...).on(...))
+   - onRef(col1, op, col2): column-to-column
+   - on(col, op, value): column-to-literal
+   - on((eb) => eb.or([...])): OR conditions
+
+3. Subquery joins: Two callbacks
+   - First: (eb) => eb.selectFrom(...).as("alias")
+   - Second: (join) => join.onRef(...)
+   - ALWAYS include .as("alias") on subquery!
+
+4. Cross joins: join.on(sql`true`, "=", sql`true`)
+   - For joining unrelated data (like CTE summaries)
+*/

package/plugins/kysely-postgres/skills/kysely-postgres/references/json-arrays.ts

@@ -0,0 +1,398 @@
+/**
+ * JSON/JSONB and Array Patterns
+ * PostgreSQL-specific JSON functions and array handling
+ */
+import { db } from "./db";
+import { sql } from "kysely";
+import { jsonBuildObject } from "kysely/helpers/postgres";
+
+// ============================================
+// JSONB INSERT/UPDATE - NO JSON.stringify!
+// ============================================
+
+// The pg driver handles JSONB serialization automatically
+// Just pass JavaScript objects directly!
+
+// Insert with JSONB
+const newUser = await db
+  .insertInto("user")
+  .values({
+    email: "test@example.com",
+    first_name: "Test",
+    last_name: "User",
+    metadata: { preferences: { theme: "dark" }, notifications: true } as any,
+  })
+  .returning(["id", "email", "metadata"])
+  .executeTakeFirst();
+
+// Update JSONB
+const updatedUser = await db
+  .updateTable("user")
+  .set({
+    metadata: { preferences: { theme: "light" }, notifications: false } as any,
+  })
+  .where("email", "=", "test@example.com")
+  .returning(["id", "metadata"])
+  .executeTakeFirst();
+
+// ============================================
+// JSONB READ - NO JSON.parse!
+// ============================================
+
+// Returns parsed objects automatically
+const user = await db
+  .selectFrom("user")
+  .select(["id", "email", "metadata"])
+  .where("email", "=", "test@example.com")
+  .executeTakeFirst();
+
+// Access directly - already an object!
+console.log(user?.metadata?.preferences?.theme); // "light"
+console.log(typeof user?.metadata); // "object"
+
+// ============================================
+// ARRAY COLUMNS - NO JSON.stringify!
+// ============================================
+
+// Insert with text[] array - pass array directly
+const product = await db
+  .insertInto("product")
+  .values({
+    name: "Test Product",
+    sku: "TEST-001",
+    price: "19.99",
+    tags: ["electronics", "sale", "featured"], // Direct array!
+  })
+  .returning(["id", "name", "tags"])
+  .executeTakeFirst();
+
+// Read array - returns native JavaScript array
+const productWithTags = await db
+  .selectFrom("product")
+  .select(["name", "tags"])
+  .where("sku", "=", "TEST-001")
+  .executeTakeFirst();
+
+console.log(productWithTags?.tags); // ["electronics", "sale", "featured"]
+console.log(Array.isArray(productWithTags?.tags)); // true
+
+// Update array
+await db
+  .updateTable("product")
+  .set({ tags: ["updated", "tags"] })
+  .where("sku", "=", "TEST-001")
+  .execute();
+
+// ============================================
+// ARRAY QUERIES
+// ============================================
+
+// Array contains all (@>) - operator works natively!
+const hasAllTags = await db
+  .selectFrom("product")
+  .select(["name", "tags"])
+  .where("tags", "@>", sql`ARRAY['electronics', 'premium']::text[]`)
+  .execute();
+
+// Array overlap (&&) - operator works natively!
+const premiumOrBasic = await db
+  .selectFrom("product")
+  .select(["name", "tags"])
+  .where("tags", "&&", sql`ARRAY['premium', 'basic']::text[]`)
+  .execute();
+
+// Array contains value (ANY) - type-safe with eb.fn
+// eb.ref("tags") validates column exists at compile time
+const searchTag = "phone";
+const phonesProducts = await db
+  .selectFrom("product")
+  .select(["name", "tags"])
+  .where((eb) => eb(sql`${searchTag}`, "=", eb.fn("any", [eb.ref("tags")])))
+  .execute();
+// Using eb.ref("invalid_column") would be a TypeScript error!
+
+// ============================================
+// JSONB QUERIES - Operators that work natively
+// ============================================
+
+// Key exists (?) - works as native operator!
+const hasThemeKey = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("metadata", "?", "theme")
+  .execute();
+
+// Any key exists (?|) - works as native operator!
+const hasAnyKey = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("metadata", "?|", sql`array['theme', 'language']`)
+  .execute();
+
+// All keys exist (?&) - works as native operator!
+const hasAllKeys = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("metadata", "?&", sql`array['theme', 'notifications']`)
+  .execute();
+
+// JSONB contains (@>) - works as native operator!
+const usersWithPrefs = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("metadata", "@>", sql`'{"notifications": true}'::jsonb`)
+  .execute();
+
+// JSONB contained by (<@) - works as native operator!
+const simpleMetadata = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("metadata", "<@", sql`'{"theme": "dark", "notifications": true}'::jsonb`)
+  .execute();
+
+// ============================================
+// JSONB QUERIES - Extraction
+// ============================================
+
+// Single-level extraction: -> and ->> work with eb() - type-safe!
+const extracted = await db
+  .selectFrom("user")
+  .select((eb) => [
+    "id",
+    eb("metadata", "->", "preferences").as("preferences"),  // Returns JSONB
+    eb("metadata", "->>", "theme").as("theme"),             // Returns text
+  ])
+  .execute();
+
+// Nested path extraction: #> and #>> need sql``
+const nestedJson = await db
+  .selectFrom("user")
+  .select([
+    "id",
+    sql`metadata#>'{preferences,theme}'`.as("theme"),       // Returns JSONB
+  ])
+  .execute();
+
+const nestedText = await db
+  .selectFrom("user")
+  .select([
+    "id",
+    sql<string>`metadata#>>'{preferences,theme}'`.as("theme"), // Returns text
+  ])
+  .execute();
+
+// Filter by JSON field value - type-safe!
+const darkThemeUsers = await db
+  .selectFrom("user")
+  .selectAll()
+  .where((eb) => eb(eb("metadata", "->>", "theme"), "=", "dark"))
+  .execute();
+// eb("metadata", ...) validates column - eb("invalid", ...) would be TS error
+
+// Filter by nested JSON value (path syntax still needs sql``)
+const specificUsers = await db
+  .selectFrom("user")
+  .selectAll()
+  .where(sql`metadata#>>'{preferences,theme}'`, "=", "dark")
+  .execute();
+
+// ============================================
+// JSONPath (PostgreSQL 12+)
+// ============================================
+
+// JSONPath match (@@) - works as native operator!
+const matchingUsers = await db
+  .selectFrom("user")
+  .selectAll()
+  .where("metadata", "@@", sql`'$.preferences.theme == "dark"'`)
+  .execute();
+
+// JSONPath exists (@?) - NOT in Kysely's allowlist, use function instead
+// Use jsonb_path_exists() for type-safe column validation
+const usersWithTheme = await db
+  .selectFrom("user")
+  .selectAll()
+  .where((eb) =>
+    eb.fn("jsonb_path_exists", [eb.ref("metadata"), sql`'$.preferences.theme'`])
+  )
+  .execute();
+// eb.ref("metadata") validates column exists - eb.ref("invalid") would be TS error
+
+// Extract value with JSONPath - type-safe with eb.fn
+const themes = await db
+  .selectFrom("user")
+  .select((eb) => [
+    "id",
+    eb
+      .fn("jsonb_path_query_first", [
+        eb.ref("metadata"),
+        sql`'$.preferences.theme'`,
+      ])
+      .as("theme"),
+  ])
+  .execute();
+
+// JSONPath with variables
+const searchValue = "dark";
+const filtered = await db
+  .selectFrom("user")
+  .selectAll()
+  .where((eb) =>
+    eb.fn("jsonb_path_exists", [
+      eb.ref("metadata"),
+      sql`'$.preferences.theme ? (@ == $val)'`,
+      sql`jsonb_build_object('val', ${searchValue}::text)`,
+    ])
+  )
+  .execute();
+
+// ============================================
+// jsonBuildObject
+// ============================================
+
+// Build JSON objects in SELECT
+const usersWithInfo = await db
+  .selectFrom("user")
+  .select((eb) => [
+    "id",
+    jsonBuildObject({
+      fullName: eb.fn<string>("concat", [
+        eb.ref("first_name"),
+        eb.cast(eb.val(" "), "text"),
+        eb.ref("last_name"),
+      ]),
+      email: eb.ref("email"),
+      role: eb.ref("role"),
+    }).as("userInfo"),
+  ])
+  .execute();
+
+// ============================================
+// jsonAgg with CTEs
+// ============================================
+
+// Aggregate rows into JSON array
+const usersWithOrders = await db
+  .with("user_orders", (db) =>
+    db
+      .selectFrom("order")
+      .innerJoin("user", "user.id", "order.user_id")
+      .select((eb) => [
+        "user.id as userId",
+        "user.email",
+        eb.fn
+          .jsonAgg(
+            jsonBuildObject({
+              orderId: eb.ref("order.id"),
+              status: eb.ref("order.status"),
+              total: eb.ref("order.total_amount"),
+            })
+          )
+          .as("orders"),
+      ])
+      .groupBy(["user.id", "user.email"])
+  )
+  .selectFrom("user_orders")
+  .selectAll()
+  .execute();
+
+// ============================================
+// NESTED jsonAgg
+// ============================================
+
+// Multiple levels of nesting
+const productsWithReviews = await db
+  .with("product_with_reviews", (db) =>
+    db
+      .selectFrom("product")
+      .leftJoin("review", "review.product_id", "product.id")
+      .leftJoin("user", "user.id", "review.user_id")
+      .select((eb) => [
+        "product.id as productId",
+        "product.name as productName",
+        eb.fn
+          .jsonAgg(
+            jsonBuildObject({
+              reviewId: eb.ref("review.id"),
+              rating: eb.ref("review.rating"),
+              title: eb.ref("review.title"),
+              // Nested object!
+              reviewer: jsonBuildObject({
+                name: eb.fn<string>("concat", [
+                  eb.ref("user.first_name"),
+                  eb.cast(eb.val(" "), "text"),
+                  eb.ref("user.last_name"),
+                ]),
+                email: eb.ref("user.email"),
+              }),
+            })
+          )
+          // .filterWhere() is available on ALL aggregate functions (count, sum, avg, etc.),
+          // not just jsonAgg. See aggregations.ts for general usage.
+          .filterWhere("review.id", "is not", null) // Filter nulls!
+          .as("reviews"),
+      ])
+      .groupBy(["product.id", "product.name"])
+  )
+  .selectFrom("product_with_reviews")
+  .selectAll()
+  .where("reviews", "is not", null)
+  .execute();
+
+// ============================================
+// KEY PATTERNS SUMMARY
+// ============================================
+
+/*
+1. JSONB columns:
+   - INSERT/UPDATE: Pass objects directly (no JSON.stringify)
+   - SELECT: Returns parsed objects (no JSON.parse)
+   - The pg driver handles serialization automatically
+
+2. Array columns (text[], int[], etc.):
+   - INSERT/UPDATE: Pass arrays directly (no JSON.stringify)
+   - SELECT: Returns native JavaScript arrays
+   - The pg driver handles this automatically
+
+3. Array queries - operators work natively:
+   - @>  : .where("tags", "@>", sql`ARRAY[...]::text[]`)
+   - &&  : .where("tags", "&&", sql`ARRAY[...]::text[]`)
+   - ANY : .where((eb) => eb(sql`${val}`, "=", eb.fn("any", [eb.ref("tags")])))
+           eb.ref() provides type-safety - invalid columns are TS errors
+
+4. JSONB queries - operators that work natively:
+   - ?   : .where("col", "?", "key")
+   - ?|  : .where("col", "?|", sql`array[...]`)
+   - ?&  : .where("col", "?&", sql`array[...]`)
+   - @>  : .where("col", "@>", sql`'{...}'::jsonb`)
+   - <@  : .where("col", "<@", sql`'{...}'::jsonb`)
+
+   Extraction operators:
+   - ->> : eb(eb("col", "->>", "key"), "=", val)  (type-safe!)
+   - ->  : eb("col", "->", "key")                 (returns JSONB)
+   - #>  : sql`col#>'{a,b}'`    (nested path, needs sql``)
+   - #>> : sql`col#>>'{a,b}'`   (nested path, needs sql``)
+
+5. JSONPath (PostgreSQL 12+):
+   - @@  : .where("col", "@@", sql`'$.path == "val"'`)  (native operator!)
+   - @?  : NOT in allowlist - use jsonb_path_exists() instead
+   - Functions (type-safe with eb.fn):
+     - jsonb_path_exists(col, path)
+     - jsonb_path_query_first(col, path)
+   - eb.ref() provides type-safety for column references
+
+6. jsonBuildObject:
+   - Import from "kysely/helpers/postgres"
+   - Use eb.ref() for column references
+   - Can be nested for deep structures
+
+7. jsonAgg:
+   - Use eb.fn.jsonAgg() (NOT imported from helpers!)
+   - Use .filterWhere() to exclude nulls
+   - Combine with jsonBuildObject for structured arrays
+
+8. .filterWhere() (PostgreSQL FILTER (WHERE ...)):
+   - Available on ALL aggregate builders, not just jsonAgg
+   - Works on: count, countAll, sum, avg, min, max, jsonAgg
+   - See aggregations.ts for general examples
+*/