@gallopsystems/agent-skills 1.14.0 → 1.16.0

package/plugins/kysely-postgres/skills/kysely-postgres/references/common-pitfalls.md

@@ -0,0 +1,132 @@
+## Common Pitfalls to Avoid
+
+### 1. Don't Resort to `sql`` When Kysely Has a Method
+
+```typescript
+// WRONG
+.select(sql`count(*)`.as("count"))
+
+// RIGHT
+.select((eb) => eb.fn.countAll().as("count"))
+
+// WRONG - raw SQL for FILTER (WHERE ...) on aggregates
+.having(sql<number>`count(*) filter (where status != 'signed')`, "=", 0)
+
+// RIGHT - .filterWhere() works on all aggregate function builders
+.having(
+  (eb) => eb.fn.countAll().filterWhere("status", "!=", "signed"),
+  "=",
+  0
+)
+```
+
+### 2. Don't Forget .execute()
+
+Queries are lazy - they won't run without calling an execute method:
+
+```typescript
+// This does nothing!
+db.selectFrom("user").selectAll();
+
+// This runs the query
+await db.selectFrom("user").selectAll().execute();
+```
+
+### 3. Use whereRef for Column-to-Column Comparisons
+
+```typescript
+// WRONG - Compares to string literal "other.column"
+.where("table.column", "=", "other.column")
+
+// RIGHT - Compares to actual column value
+.whereRef("table.column", "=", "other.column")
+```
+
+### 4. Type Your Function Returns
+
+```typescript
+// Better type inference
+eb.fn<string>("concat", [...])
+eb.fn<number>("length", [...])
+```
+
+### 5. PostgreSQL Does NOT Auto-Index Foreign Keys
+
+Always create indexes on foreign key columns:
+
+```typescript
+await db.schema.createIndex("idx_order_user_id").on("order").column("user_id").execute();
+```
+
+### 6. Always Type `sql` Template Literals
+
+When using `sql` template literals, the inferred type is `unknown` since Kysely can't know what the SQL expression resolves to. Always provide an explicit type:
+
+```typescript
+// WRONG - Returns unknown type
+eb.fn.coalesce("some_json_col", sql`'{}'::jsonb`)
+
+// RIGHT - Explicit type annotation
+eb.fn.coalesce("some_json_col", sql<Record<string, unknown>>`'{}'::jsonb`)
+
+// For complex types (e.g., JSON column from a CTE), use typeof with eb.ref
+// This ensures the fallback type matches the column type exactly
+eb.fn
+  .coalesce(
+    eb.ref("jobs_agg.jobs"),
+    sql<typeof eb.ref<"jobs_agg.jobs">>`'[]'::json`
+  )
+  .as("jobs")
+```
+
+**Key rule**: Every `sql` template literal should have a type parameter: `sql<TYPE>`. This ensures proper type inference throughout your query chain.
+
+### 7. DATE Columns Cause Timezone Issues
+
+By default, the `pg` driver converts DATE columns to JavaScript `Date` objects. This causes timezone problems:
+
+```
+Database: 2025-01-01 (just a date, no time)
+JS Date:  2025-01-01T00:00:00.000Z (interpreted as UTC midnight)
+User in NYC sees: Dec 31, 2024 (5 hours behind UTC)
+```
+
+**Solution: Parse DATE as string and let the frontend handle formatting**
+
+Step 1: Configure `pg` to return DATE as string:
+
+```typescript
+import pg from "pg";
+
+// Tell pg to return DATE columns as strings instead of Date objects
+const DATE_OID = 1082;
+pg.types.setTypeParser(DATE_OID, (val: string) => val);
+```
+
+Step 2: Update `kysely-codegen` to generate matching types:
+
+```bash
+npx kysely-codegen \
+  --url="$DATABASE_URL" \
+  --out-file=server/db/db.d.ts \
+  --dialect=postgres \
+  --date-parser=string
+```
+
+Now DATE columns return strings like `"2025-01-01"` and the frontend can parse/format respecting the user's timezone.
+
+**Note**: This applies to DATE columns only. TIMESTAMPTZ columns already handle timezones correctly by storing UTC and converting on read.
+
+### 8. Don't Use the `between` String Operator — It Emits Invalid SQL
+
+The `"between"` operator looks like it should work but compiles to a tuple, which is a PostgreSQL syntax error:
+
+```typescript
+// WRONG - compiles to: "age" between ($1, $2)  -> Postgres syntax error
+.where("age", "between", [18, 65])
+
+// RIGHT - use the expression-builder helpers
+.where((eb) => eb.between("age", 18, 65))            // "age" between $1 and $2
+.where((eb) => eb.betweenSymmetric("age", 65, 18))   // swaps bounds if needed
+```
+

package/plugins/kysely-postgres/skills/kysely-postgres/references/deep-types.md

@@ -0,0 +1,39 @@
+## Handling "Excessively Deep Types" Error
+
+### The Problem
+
+Complex queries with many CTEs can overwhelm TypeScript's type instantiation limits:
+
+```
+Type instantiation is excessively deep and possibly infinite
+```
+
+This commonly occurs with 12+ `with` clauses, as Kysely's nested helper types accumulate.
+
+### The Solution: `$assertType`
+
+Use `$assertType` to simplify the type chain at intermediate points:
+
+```typescript
+const result = await db
+  .with("cte1", (qb) =>
+    qb.selectFrom("user")
+      .select(["id", "email"])
+      .$assertType<{ id: number; email: string }>()  // Simplify type here
+  )
+  .with("cte2", (qb) =>
+    qb.selectFrom("cte1")
+      .select("email")
+      .$assertType<{ email: string }>()
+  )
+  // ... more CTEs
+  .selectFrom("cteN")
+  .selectAll()
+  .execute();
+```
+
+**Key points**:
+- The asserted type must structurally match the actual type (full type safety preserved)
+- Apply to several intermediate `with` clauses in large queries
+- TypeScript cannot automatically simplify these types - explicit assertion is required
+

package/plugins/kysely-postgres/skills/kysely-postgres/references/expression-builder.md

@@ -0,0 +1,132 @@
+## ExpressionBuilder (eb) - The Foundation
+
+The `eb` parameter in select/where callbacks provides all expression methods:
+
+```typescript
+.select((eb) => [
+  eb.ref("column").as("alias"),                    // Column reference
+  eb.fn<string>("upper", [eb.ref("email")]),       // Function call (typed!)
+  eb.fn.count("id").as("count"),                   // Aggregate function
+  eb.fn.sum("amount").as("total"),                 // SUM
+  eb.fn.avg("rating").as("avgRating"),             // AVG
+  eb.fn.coalesce("nullable_col", eb.val(0)),       // COALESCE
+  eb.case().when("status", "=", "active")          // CASE expression
+    .then("Active").else("Inactive").end(),
+  eb("quantity", "*", eb.ref("unit_price")),       // Binary expression
+  eb.exists(subquery),                             // EXISTS
+  eb.not(expression),                              // NOT / negation
+  eb.cast(eb.val(" "), "text"),                    // Cast value to type
+  eb.and([...]),                                   // AND conditions
+  eb.or([...]),                                    // OR conditions
+])
+```
+
+### eb.val() vs eb.lit()
+
+```typescript
+// eb.val() - Creates a parameterized value ($1, $2, etc.) - PREFERRED for user input
+// Note: eb.val() alone may fail with "could not determine data type of parameter"
+// Use eb.cast(eb.val(...), "text") for string values in function arguments
+eb.val("user input")                    // Becomes: $1 with parameter "user input"
+eb.cast(eb.val("safe"), "text")         // Becomes: $1::text - always works
+
+// eb.lit() - Creates a literal value in SQL
+// ONLY accepts: numbers, booleans, null - NOT strings (throws "unsafe immediate value")
+eb.lit(1)             // Becomes: 1 (directly in SQL)
+eb.lit(true)          // Becomes: true
+eb.lit(null)          // Becomes: NULL
+
+// For string literals, use sql`` template instead
+sql`'active'`         // Becomes: 'active' (directly in SQL)
+sql<string>`'label'`  // Typed string literal
+```
+
+### Standalone ExpressionBuilder
+
+For reusable helpers outside query callbacks:
+
+```typescript
+import { expressionBuilder } from "kysely";
+import type { DB } from "./db.d.ts";
+
+// Create standalone expression builder
+const eb = expressionBuilder<DB, "user">();
+
+// Use in helper functions
+function isActiveUser() {
+  return eb.and([
+    eb("is_active", "=", true),
+    eb("role", "!=", "banned"),
+  ]);
+}
+```
+
+A predicate helper can also return a callback that receives the query's
+`eb`, so the same helper works in any `.where()`/`.having()` on that table:
+
+```typescript
+import type { ExpressionBuilder } from "kysely";
+
+// AVOID - raw sql means the column name is an unchecked string.
+// A typo or renamed column only fails at runtime.
+function nameMatches(name: string) {
+  return sql<boolean>`lower(name) = ${name.toLowerCase()}`;
+}
+
+// PREFER - eb.fn keeps the column reference type-checked against DB,
+// and the value stays parameterized.
+function nameMatches(name: string) {
+  return (eb: ExpressionBuilder<DB, "user">) =>
+    eb(eb.fn("lower", ["name"]), "=", name.toLowerCase());
+}
+
+// Both call sites stay identical:
+db.selectFrom("user").where(nameMatches(input)).execute();
+```
+
+### Conditional Expressions with Arrays
+
+Build dynamic filters by collecting expressions:
+
+```typescript
+.where((eb) => {
+  const filters: Expression<SqlBool>[] = [];
+
+  if (firstName) filters.push(eb("first_name", "=", firstName));
+  if (lastName) filters.push(eb("last_name", "=", lastName));
+  if (minAge) filters.push(eb("age", ">=", minAge));
+
+  // Combine all filters with AND (empty array = no filter)
+  return eb.and(filters);
+})
+```
+
+## String Concatenation
+
+Use the `||` operator with `sql` template for clean string concatenation:
+
+```typescript
+// RECOMMENDED - Clean and type-safe with eb.ref()
+.select((eb) => [
+  sql<string>`${eb.ref("first_name")} || ' ' || ${eb.ref("last_name")}`.as("full_name"),
+])
+// Output: "first_name" || ' ' || "last_name"
+
+// ALTERNATIVE - Pure eb() chaining (parameterized literals)
+.select((eb) => [
+  eb(eb("first_name", "||", " "), "||", eb.ref("last_name")).as("full_name"),
+])
+// Output: "first_name" || $1 || "last_name"
+
+// VERBOSE - concat() function (avoid unless you need NULL handling)
+.select((eb) => [
+  eb.fn<string>("concat", [
+    eb.ref("first_name"),
+    eb.cast(eb.val(" "), "text"),
+    eb.ref("last_name"),
+  ]).as("full_name"),
+])
+```
+
+**Note**: `concat()` treats NULL as empty string, while `||` propagates NULL. Use `concat()` only when you need that NULL behavior.
+

package/plugins/kysely-postgres/skills/kysely-postgres/references/full-text-and-grouping.md

@@ -0,0 +1,26 @@
+## Full-Text Search (PostgreSQL)
+
+`@@` is a real Kysely operator — keep it as the operator and put the FTS functions on each side as `sql` fragments. See [full-text-search.ts](references/full-text-search.ts).
+
+```typescript
+db.selectFrom("document").selectAll()
+  .where(
+    sql`to_tsvector('english', ${sql.ref("body")})`,
+    "@@",
+    sql`websearch_to_tsquery('english', ${userInput})`,
+  )
+  .execute();
+// A stored tsvector column can be the typed LHS directly:
+// .where("search_vector", "@@", sql`plainto_tsquery('english', ${userInput})`)
+```
+
+## Advanced Grouping (ROLLUP / CUBE / GROUPING SETS)
+
+No builder exists — pass the grouping spec to `.groupBy()` as a `sql` fragment; the SELECT list stays typed. See [aggregations.ts](references/aggregations.ts).
+
+```typescript
+.groupBy(sql`rollup("status")`)                              // hierarchical subtotals
+.groupBy(sql`cube("order_id", "product_id")`)               // all combinations
+.groupBy(sql`grouping sets (("status"), ("user_id"), ())`)  // explicit sets
+```
+

package/plugins/kysely-postgres/skills/kysely-postgres/references/helpers-and-extending.md

@@ -0,0 +1,81 @@
+## PostgreSQL Helpers Summary
+
+All helpers from `kysely/helpers/postgres`:
+
+```typescript
+import {
+  jsonArrayFrom,    // One-to-many relations (subquery → array)
+  jsonObjectFrom,   // Many-to-one relations (subquery → object | null)
+  jsonBuildObject,  // Build JSON object from expressions
+  mergeAction,      // Get action performed in MERGE query (PostgreSQL 15+)
+} from "kysely/helpers/postgres";
+```
+
+**Note**: `jsonAgg` is NOT imported - use `eb.fn.jsonAgg()` instead.
+
+### mergeAction (PostgreSQL 15+)
+
+For MERGE queries, get which action was performed:
+
+```typescript
+import { mergeAction } from "kysely/helpers/postgres";
+
+const result = await db
+  .mergeInto("person")
+  .using("person_updates", "person.id", "person_updates.id")
+  .whenMatched()
+  .thenUpdateSet({ name: eb.ref("person_updates.name") })
+  .whenNotMatched()
+  .thenInsertValues({ id: eb.ref("person_updates.id"), name: eb.ref("person_updates.name") })
+  .returning([mergeAction().as("action"), "id"])
+  .execute();
+
+// result[0].action is 'INSERT' | 'UPDATE' | 'DELETE'
+```
+
+## Extending Kysely
+
+### Custom Helper Functions
+
+Most extensions use the `sql` template tag with `RawBuilder<T>`:
+
+```typescript
+import { sql, RawBuilder } from "kysely";
+
+// Create a typed helper function
+function json<T>(value: T): RawBuilder<T> {
+  return sql`CAST(${JSON.stringify(value)} AS JSONB)`;
+}
+
+// Use in queries
+.select((eb) => [
+  json({ name: "value" }).as("data"),
+])
+```
+
+### Custom Expression Classes
+
+For reusable expressions, implement the `Expression<T>` interface:
+
+```typescript
+import { Expression, OperationNode, sql } from "kysely";
+
+class JsonValue<T> implements Expression<T> {
+  readonly #value: T;
+
+  constructor(value: T) {
+    this.#value = value;
+  }
+
+  get expressionType(): T | undefined {
+    return undefined;
+  }
+
+  toOperationNode(): OperationNode {
+    return sql`CAST(${JSON.stringify(this.#value)} AS JSONB)`.toOperationNode();
+  }
+}
+```
+
+**Note**: Module augmentation and inheritance-based extension are not recommended.
+