joist-codegen 2.3.0 → 2.4.0-next.1

package/skills/joist-docs/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: joist-docs
+description: Read the `src/entities/<Entity>.md` business-docs when working on an entity, its resolvers, jobs, or tests. Add only durable, non-obvious domain knowledge that helps readers understand a business rule or avoid a likely mistake; prioritize succinctness, clarity, and discretion. Also covers how `## Overview` and `## Fields`/`### fieldName` sections sync to JSDocs via `yarn joist-codegen`.
+---
+
+# Entity docs (`src/entities/<Entity>.md`)
+
+Many Joist entities have a sibling Markdown doc — `src/entities/Author.ts` ↔
+`src/entities/Author.md` (same basename; enums under `src/entities/enums/` too). These files hold the
+**"why"** that code can't: business rationale, worked scenarios, gotchas, domain vocabulary, and
+cross-entity workflows. They are written for **both humans and agents** — you are a primary audience.
+
+Read routinely; write selectively:
+
+1. **Read** the sibling `.md` before/while you work on an entity, to get domain context.
+2. **Write** only when a concise addition would give future readers important context they cannot
+   readily get from the code or existing docs. Leaving the docs unchanged is often the right outcome.
+
+## 1. Read it first
+
+Before editing an entity — its `src/entities/<Entity>.ts`, its resolvers, a job that touches it, or its
+tests — open `src/entities/<Entity>.md` if one exists. It routinely explains things you would otherwise
+have to reverse-engineer or would get subtly wrong:
+
+- **Business rationale** — *why* a field/entity exists and what real-world thing it models
+  (e.g. `PurchaseOrder.md` on tracking "what and why" a project's cost changed).
+- **Worked scenarios** — concrete `I.e.` walkthroughs with real values ("when an `Employee` is termined, the status workflow is...").
+- **Gotchas & edge cases** — footguns, "this looks stale but isn't", exemptions
+- **Domain vocabulary** — statuses, flags, and other "esoteric unless you know it" domain concepts
+
+Follow relevant cross-links (`[Book](Book.md)`, sometimes with anchors like
+`Book.md#Definitions`) into related docs. A missing or thin doc is not by itself a reason to add content.
+
+## 2. How the file maps to code (the codegen doc-sync)
+
+`joist-config.json` has `"docs": true`, so `yarn joist-codegen` keeps these `.md` files and the entity
+JSDocs in sync. Understanding this is what makes your writing land in the right place.
+
+**Only two heading shapes are parsed and synced; everything else is free-form narrative:**
+
+| `.md` section | Syncs to | Notes |
+|---|---|---|
+| `## Overview` (body) | the entity **class** JSDoc | exact heading `## Overview` |
+| `## Fields` → `### <fieldName>` (body) | that field/property/relation's JSDoc | `### ` heading must be the **exact member name** |
+| any other `## Section` (e.g. `## Hard vs. Soft Costs`, `## DB Constraints`, mermaid) | **nothing** | free-form; lives only in the `.md`, preserved verbatim |
+
+Synced JSDocs are tagged `@generated <Entity>.md` in the `.ts` — that tag means "this comment came from
+the `.md`; edit the `.md`, not here."
+
+**Sync is bidirectional, but the `.md` wins.** `yarn joist-codegen`:
+
+1. **Backfills** the `.md` from any hand-written `.ts` JSDoc that isn't in the `.md` yet (so a jsdoc you
+   write directly on a field gets pulled into `## Fields` for you), then
+2. **Writes the `.md` back into the `.ts`** JSDocs — so for anything already in the `.md`, the `.md` is
+   the source of truth and will overwrite a divergent `.ts` comment.
+
+Net rule: **to durably document an entity or field, edit the `.md`.** Hand-editing a `@generated` JSDoc
+in the `.ts` gets stomped on the next codegen.
+
+### Field-heading constraints (easy to get wrong)
+
+- `### <fieldName>` must be a **single word** — the parser matches `\w+` only. `### excludeFromBudget`
+  works; `### is excluded`, `` ### `excludeFromBudget` ``, or `### excludeFromBudget (derived)` are **not**
+  recognized as field docs.
+- It must be the **exact** name of a field, relation, or property on the entity, and must sit **under the
+  `## Fields` heading**. Any other `##` heading ends the fields section — so keep all `### fieldName`
+  entries together under the one `## Fields` section (conventionally at the bottom of the file).
+- **Methods don't sync** — only fields/getters/properties/relations get their JSDoc updated.
+
+## 3. Choose what is worth documenting
+
+Add a note only when the knowledge is durable, non-obvious, and useful for a future domain decision or
+for avoiding a likely mistake. Possible candidates, not a checklist to fill:
+
+- You just figured out **why** an entity or field exists, or what it really models.
+- A **non-obvious business rule**, invariant, or "this only applies to X clients" exemption.
+- A **gotcha / footgun** — a value that looks stale but isn't, an ordering requirement, a special-cased
+  type.
+- A **cross-entity interaction** or workflow that isn't visible from one file.
+- **Domain vocabulary** a newcomer (human or agent) wouldn't know.
+- A **worked scenario** needed to resolve an ambiguity that a short explanation cannot.
+
+**Omit** what the code already says plainly, transient implementation details, exhaustive edge-case
+lists, and a recap of the work just completed. Do not repeat knowledge already documented elsewhere;
+link to it when readers need it. Correct outdated guidance rather than appending a competing explanation.
+
+**Where to put it:**
+
+- Something specific to one field → a `### <fieldName>` block under `## Fields`. It syncs to that
+  member's JSDoc, so it shows on hover/`@generated` in the `.ts`.
+- The entity's purpose → a short `## Overview`, which syncs to the class JSDoc.
+- Necessary longer explanations or cross-entity workflows → a free-form `##` section, linked from the
+  field doc if needed. Keep synced JSDocs small enough to read comfortably on hover.
+
+**Style** (prioritize succinctness and clarity):
+
+- Lead with business meaning and *why*. Use plain language and state each fact once.
+- Default to one sentence for a field and one short paragraph for an overview. Add detail only when
+  shortening it would hide an important rule or make the meaning ambiguous.
+- Use a single brief `I.e. ...` example with concrete values only when it clarifies a difficult rule.
+  Do not add examples, diagrams, or sections merely to make the doc look complete.
+- Cross-link related entities with relative links: `[Book](Book.md)`.
+- Reference field/entity names in backticks.
+- Before finishing, remove any sentence that does not add necessary meaning. Match existing terminology,
+  but do not copy existing verbosity.
+
+## 4. Workflow to add or update a doc
+
+1. If an addition meets the criteria above, edit `src/entities/<Entity>.md` (create it only if needed — basename must equal the entity, e.g.
+   `Author.md`). For field docs, use the exact member name as a `### ` heading under `## Fields`.
+2. Sync into the JSDocs:
+   ```bash
+   mise exec -- yarn joist-codegen
+   ```
+   (or `mise exec -- yarn codegen` to also run graphql-codegen.)
+3. Verify the `@generated <Entity>.md` JSDoc now appears on the class / field in `src/entities/<Entity>.ts`.
+4. Commit the `.md` **and** the regenerated `.ts` JSDoc changes together.
+
+Never hand-edit a `@generated <Entity>.md` JSDoc in the `.ts` — edit the `.md` and re-run codegen. Do not
+touch files under `src/entities/codegen/` (see the repo's generated-files rules).
+
+## Skeleton for a new doc
+
+Include only the sections and fields that need explanation; this is a structure, not a checklist.
+
+```markdown
+# <Entity>
+
+## Overview
+
+<What this entity models and *why* it exists, in business terms. One short paragraph.>
+
+## <Some Business Concept>   <!-- free-form: rationale, scenarios, gotchas, diagrams; NOT synced -->
+
+<Only if needed: a concise explanation of a non-obvious business concept.>
+
+## Fields   <!-- each ### below syncs into that member's JSDoc -->
+
+### someField
+
+<Usually one sentence: why it exists or the important non-obvious rule.>
+```

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

@@ -0,0 +1,114 @@
+---
+name: joist-em-basics
+description: Create, load, find, mutate, and save entities with Joist's EntityManager. Use when writing data-access or business logic in a Joist project — anything using em.create, em.load, em.find, em.flush, or walking the entity graph.
+---
+
+<!-- Managed by joist-codegen. Do not edit by hand; re-run codegen to update. -->
+
+# Joist EntityManager basics
+
+The `EntityManager` (`em`) is how entities are loaded from and saved to the
+database. It is a Unit of Work: each request gets its own `em`, which tracks
+the entities it has loaded/created and writes them all out on `em.flush()`.
+
+Entities are always loaded/created _through_ the `em`, never via static methods
+on the class (Joist is not ActiveRecord). IDs are tagged strings like `"a:1"`.
+
+## Creating
+
+`em.create` is synchronous and returns the new entity immediately:
+
+```ts
+const author = em.create(Author, { firstName: "a1" });
+// Nested/related entities can be created inline
+const author = em.create(Author, { firstName: "a1", address: { street: "123 Main" } });
+```
+
+## Loading by id
+
+Use tagged ids. These throw if the id does not exist (except the `IfExists`
+variants):
+
+```ts
+const a = await em.load(Author, "a:1");
+const as = await em.loadAll(Author, ["a:1", "a:2"]);
+const as = await em.loadAllIfExists(Author, ["a:1", "a:2"]); // skips missing ids
+```
+
+To eagerly load relations, pass a populate hint as the 3rd argument; the
+returned entity is typed as "loaded" so the relations can be read synchronously:
+
+```ts
+const a = await em.load(Author, "a:1", { books: "reviews" });
+a.books.get.flatMap((b) => b.reviews.get);
+```
+
+## Walking the graph
+
+~90% of reads are just navigating relations from an entity you already have.
+These are guaranteed N+1-safe, even in a loop:
+
+```ts
+const author = await book.author.load();        // load a single relation
+const reviews = await publisher.load((p) => p.books.reviews); // lens
+const loaded = await author.populate({ books: "reviews" });   // populate + .get
+```
+
+## Finding (filtered queries)
+
+`em.find` issues a `SELECT` with a "join literal" of nested relations plus
+inline `WHERE` conditions. It is batch/N+1-safe.
+
+```ts
+const books = await em.find(Book, { author: { firstName: "a1" } });
+const recent = await em.find(Book, { publishedAt: { gte: jan1 } });
+const some = await em.find(Author, { firstName: { in: ["a1", "a2"] } });
+
+const one = await em.findOne(Book, { title: "b1" });        // undefined if none
+const one = await em.findOneOrFail(Book, { title: "b1" });  // throws if none
+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. See `joist-em-find` for more;
+for aggregates or group-bys, use `joist-em-query` instead.
+
+## Mutating
+
+Assign fields directly, or use `.set` for a batch of changes:
+
+```ts
+author.firstName = "a2";
+author.set({ firstName: "a2", lastName: "b2" });
+```
+
+For partial/RPC-style updates (treating `null` as "unset"), and for
+incrementally updating children, see the `joist-upsert` skill.
+
+## Deleting
+
+```ts
+const a = await em.load(Author, "a:1");
+em.delete(a);
+```
+
+## Saving with `em.flush()`
+
+`em.flush()` is where everything happens. It is async and:
+
+1. Runs lifecycle hooks and validation rules,
+2. Opens a transaction,
+3. Issues batched `INSERT`/`UPDATE`/`DELETE` (one batch per entity type),
+4. Commits.
+
+You don't write individual SQL statements — let Joist batch them. `flush` can
+be called multiple times as you do more work:
+
+```ts
+const author = em.create(Author, { firstName: "a1" });
+await em.flush();
+author.firstName = "a2";
+await em.flush();
+```

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/>.