joist-codegen 2.3.0-next.99 → 2.4.0

package/skills/joist-em-basics/SKILL.md

@@ -72,8 +72,8 @@ const one = await em.findOrCreate(Author, { email: "a@b.com" });
 `undefined` values are pruned (the condition and any now-unused join are
 dropped), so filters compose cleanly. To filter for null, pass `null`
 explicitly, e.g. `{ firstName: null }`. For `OR` / nested boolean logic, use
-`alias`/`aliases` with a `conditions` argument. For aggregates or group-bys,
-drop down to Knex/Kysely — Joist's `find` only returns whole entities.
+`alias`/`aliases` with a `conditions` argument. See `joist-em-find` for more;
+for aggregates or group-bys, use `joist-em-query` instead.
 
 ## Mutating
 

package/skills/joist-em-execute/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: joist-em-execute
+description: Use when writing bulk or immediate SQL INSERT, UPDATE, or DELETE statements with Joist em.execute, including typed table values, set expressions, and returning rows. Explains when to prefer entity mutations and em.flush and which hooks, validation, and in-memory state immediate writes bypass.
+---
+
+<!-- Managed by joist-codegen. Do not edit by hand; re-run codegen to update. -->
+
+# Immediate SQL writes with `em.execute`
+
+Prefer mutating entities and calling `em.flush()` so Joist runs validation, hooks, and reactions. Use `em.execute` for bulk SQL writes that must happen immediately:
+
+```ts
+import { table, sql } from "joist-orm";
+
+const b = table(Book);
+const inserted = await em.execute({
+  insert: b,
+  values: [{ title: "New book", authorId: "a:1" }],
+  returning: b.id,
+}); // inserted.rows is BookId[]
+
+const updated = await em.execute({
+  update: b,
+  set: { order: sql.number`${b.order} + ${1}` },
+  where: b.id.eq("b:1"),
+  returning: b.order,
+}); // updated.rows is number[]
+
+await em.execute({ delete: b, where: b.id.eq("b:1") });
+```
+
+- `insert` also supports `from: { from: source, select: [...] }` for INSERT ... SELECT. `returning` accepts a column or a named projection; results are in `.rows`.
+- These statements do **not** flush pending entities or run entity hooks, validation, defaults, reactions, updatedAt maintenance, or optimistic locking. Already-loaded entities may be stale afterward; database triggers still run.
+
+Full docs: <https://joist-orm.io/features/sql-mutations/>.

package/skills/joist-em-find/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: joist-em-find
+description: Use when writing or debugging Joist em.find, findOne, or findOneOrFail entity queries, including relation filters, OR conditions, optional filters, collection joins, and N+1 behavior. For aggregates or custom SELECTs, use joist-em-query instead.
+---
+
+<!-- Managed by joist-codegen. Do not edit by hand; re-run codegen to update. -->
+
+# Finding entities with `em.find`
+
+Prefer `em.find` for entity SELECTs: Joist automatically batches finds to avoid N+1 queries. Nested relation filters become joins; inline conditions are AND-ed:
+
+```ts
+const books = await em.find(Book, {
+  author: { firstName: "Alice" },
+  publishedAt: { gte: jan1 },
+});
+```
+
+- Operators include `eq`, `ne`, `in`, `gt`, `gte`, `lt`, `lte`, `like`, and `ilike`. Pass an entity or tagged ID to filter a reference.
+- `undefined` drops a condition and any unused join; use explicit `null` for `IS NULL`.
+- For `OR`, bind `alias(Book)` with `{ as: b }` and pass `{ conditions: { or: [b.title.eq("A"), b.title.eq("B")] } }` as the third argument. Bind aliases on joined tables too when conditions span relations.
+- Collection filters usually become `EXISTS` subqueries to avoid duplicate roots. Complex alias conditions may instead use `LEFT JOIN`s; opt into multiple collection left joins only when the fanout is intentional.
+- `findOne` returns `undefined` when absent; `findOneOrFail` throws. Both reject multiple matches.
+- Normal `find` reads the database, not unflushed entity changes; use `findWithNewOrChanged` for flat filters that must include in-memory changes.
+
+For aggregates, projections, subqueries, or explicit SQL control, use `joist-em-query`.
+Full docs: <https://joist-orm.io/features/queries-find/>.

package/skills/joist-em-query/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: joist-em-query
+description: Use when writing Joist em.query SELECTs that need aggregates, projections, grouping, subqueries, CTEs, or SQL expressions beyond em.find. Covers typed table aliases, joins, select result shapes, pruning, and the fact that every em.query is a database call.
+---
+
+<!-- Managed by joist-codegen. Do not edit by hand; re-run codegen to update. -->
+
+# SQL SELECTs with `em.query`
+
+Use `em.find` for ordinary entity reads; use `em.query` for SQL-shaped SELECTs. Unlike batched `em.find`, **each `em.query` makes a database call**.
+
+```ts
+import { tables } from "joist-orm";
+
+const [a, b] = tables(Author, Book);
+const rows = await em.query({
+  from: a,
+  join: [a.books.as(b)],
+  select: { name: a.firstName, bookCount: b.id.count() },
+  groupBy: [a.firstName],
+  orderBy: { bookCount: "DESC" },
+}); // { name: string; bookCount: number }[]
+```
+
+- `table(Entity)` / `tables(...)` expose typed columns. Join via relation paths (`a.books.as(b)`), a relation tree, or explicit `{ inner: b, on: ... }` / `{ left: b, on: ... }`.
+- `select: { ... }` returns typed rows; `select: a.id` returns scalar values; `select: a` returns identity-mapped entities (optionally with `populate`). None are auto-batched.
+- Use column methods (`eq`, `gte`, `count`, etc.) in `where`/`having`; compose conditions with `{ and: [...] }` or `{ or: [...] }`. Use `query(...)` for reusable subqueries or CTEs and typed `sql.*` tagged templates for custom SQL.
+- Conditions with `undefined` and joins unused after pruning disappear. Use explicit `null` to filter for SQL NULL; use `keep: true` on a join or `pruneJoins: false` if it must remain.
+- Joins to collections fan out rows. For a yes/no child filter without duplicates, use `exists` or an `in` subquery.
+
+For immediate INSERT/UPDATE/DELETE, use `joist-em-execute`.
+Full docs: <https://joist-orm.io/features/queries-raw/>.

package/skills/joist-reactive-hints/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: joist-reactive-hint
-description: Explains how Joist reactive hints work and what they cost to run — a hint is both a reverse-reactivity trigger (which roots re-run when a hinted field changes) and a forward load hint (what gets populated before the lambda runs), so a rule can pull an entire child collection into memory even when its lambda only reads a parent field. Covers followReverseHint, the two rule shapes (child-rooted reacting up to a parent vs parent-rooted reacting down into a child collection), and how to avoid surprise O(children) loads. Use when reasoning about the performance of a reactive rule/field/property (addRule, hasReactiveField, hasReactiveProperty, hasReactiveReference), when a validation rule seems to load far more rows than expected, when deciding whether to put a field in a reactive hint vs load it on-demand, or when a hot-path mutation (e.g. a bulk job) triggers surprise N×M loads. Keywords: reactive hint, load hint, reverse reactivity, followReverseHint, reverseSubHint, m2o vs o2m reactivity, over-invalidation, populate, "a parent rule that hints a child collection loads the whole collection".
+name: joist-reactive-hints
+description: "Use when diagnosing Joist reactive rule, field, property, or reference performance (addRule, hasReactiveField, hasReactiveProperty, hasReactiveReference), especially unexpected loads during validation or bulk mutations. Reactive hints serve as both reverse-reactivity triggers, finding which roots rerun when a hinted field changes, and forward load hints, populating data before the lambda runs. A child-rooted rule reacting to a parent field can load every sibling during the reverse walk; a parent-rooted rule hinting into children can load the whole child collection before its lambda runs, even if the lambda only reads a parent field. Covers followReverseHint, m2o/o2m traversal, and how to avoid surprise O(children) loads."
 ---
 
 # Joist reactive hints