joist-codegen 2.3.0-next.8 → 2.3.0-next.80

package/skills/joist-test-factories/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: joist-test-factories
+description: Use when writing or refactoring Joist ORM tests with newTestInstance factories, DeepNew, run or makeRun, toMatchEntity, and nested Given graphs.
+---
+
+# Joist Test Factories
+
+Write isolated, succinct tests that use Joist's factories for setup, retain
+typed entity references through the action, and assert those same entities
+with `toMatchEntity`.
+
+Authoritative references:
+
+- <https://joist-orm.io/testing/test-factories/>
+- <https://joist-orm.io/testing/entity-matcher/>
+- <https://joist-orm.io/testing/test-utils/>
+- <https://joist-orm.io/goals/great-tests/>
+
+## Non-Negotiable Rules
+
+1. Create initial Given state with test factories. Never use the same function
+   or API operation under test to arrange its own preconditions.
+2. Set only fields and relationships that define the boundary case. Let the
+   factories supply unrelated required values and dependencies.
+3. Keep direct `const` references to entities that participate in the action or
+   assertions.
+4. Keep using the factory-created `DeepNew` graph after same-`EntityManager`
+   actions or actions run through Joist's test `run` helper. Do not reload the
+   same rows merely to assert against them.
+5. Use `run` or the project's `makeRun` wrapper when production code needs an
+   isolated `EntityManager`; it flushes Given state and mirrors the callback's
+   flushed Joist writes into the original test graph.
+6. Assert entity state and relationships with `toMatchEntity`.
+7. Prefer focused tests for one behavior over a single scenario that exercises
+   unrelated updates at several graph levels.
+
+## Given, When, Then
+
+Structure every test as "Given the state of the world is X, When action Y
+happens, Then the state of the world is Z": the factory-created graph is the
+Given, the code under test is the When, and `toMatchEntity` proves the Then.
+Mark the three phases with `// Given`, `// When`, `// Then` comments:
+
+```ts
+it.withCtx("updates a book", async (ctx) => {
+  // Given an author with one book
+  const author = newAuthor(ctx.em, {
+    books: [{ title: "Before" }],
+  });
+  const [book] = author.books.get;
+
+  // When we update the book's title (updateBook owns and flushes its production unit of work)
+  await run(ctx, (ctx) => updateBook(ctx, { id: book.id, title: "After" }));
+
+  // Then the book's title is changed
+  expect(author).toMatchEntity({ books: [{ title: "After" }] });
+});
+```
+
+The factory owns the Given defaults. `run` provides production isolation and
+mirrors flushed writes. The callback still owns its production unit of work.
+`toMatchEntity` owns the Then's entity-aware assertions.
+
+## Factories Own Given State
+
+Do not call the same code under test to arrange its own preconditions:
+
+```ts
+// Wrong: saveAuthor is both setup and the behavior under test.
+const created = await saveAuthor(ctx, {
+  firstName: "a1",
+  books: [{ title: "Before" }],
+});
+const author = await created.author;
+```
+
+This couples setup to the behavior under test, can reproduce the same bug in
+both phases, and loses the ergonomic `DeepNew` type.
+
+Use a factory instead:
+
+```ts
+const author = newAuthor(ctx.em, {
+  books: [{ title: "Before" }],
+});
+const [book] = author.books.get;
+```
+
+Factories are test-only tools. Never call them from production code.
+Using another production API for Given state can be valid in an integration
+test when that API's authorization, hooks, defaults, or events are part of the
+scenario. This should be intentional, not the default way to create rows.
+
+## Keep Given State Minimal
+
+Every explicit factory option should answer: "Why does this test need this
+value?"
+
+```ts
+// Wrong: most values are unrelated to changing one title.
+const author = newAuthor(ctx.em, {
+  firstName: "Ann",
+  lastName: "Smith",
+  age: 40,
+  books: [
+    {
+      title: "Before",
+      order: 1,
+      published: false,
+      reviews: [],
+    },
+  ],
+});
+```
+
+```ts
+// Right: only the value being changed is specified.
+const author = newAuthor(ctx.em, {
+  books: [{ title: "Before" }],
+});
+```
+
+Specify additional values only when they establish the scenario. Examples:
+
+- Two `{}` children establish collection cardinality.
+- Distinct sort orders may be necessary for a parent/sort-order unique key.
+- An initial value is necessary when the assertion proves that it changed.
+- A relation override is necessary when the identity of that relation matters.
+
+Do not copy production payloads into factory opts. Factory opts describe the
+minimum database state before the action, not every field the action accepts.
+
+## Build Graphs in One Factory Call
+
+Prefer a top-level factory with nested opts when it clearly describes the
+scenario:
+
+```ts
+const author = newAuthor(ctx.em, {
+  books: [{ title: "First", reviews: [{ rating: 5 }] }, { title: "Second" }],
+});
+const [firstBook, secondBook] = author.books.get;
+const [review] = firstBook.reviews.get;
+```
+
+This is usually clearer than creating each row separately and wiring every
+required relation by hand. Separate factory calls are appropriate when the
+test's behavior is specifically about how independently created entities
+relate.
+
+Factories recursively fill required primitives and relations. They also reuse
+an obvious existing entity when exactly one candidate exists. Use factory
+controls intentionally:
+
+- Pass an entity directly to force a specific relation.
+- Pass `{ use: entity }` to nominate an existing entity throughout a factory
+  scope.
+- Pass `{}` for a relation when a new related entity is required.
+- Use `useFactoryDefaults: false` sparingly; frequent use means the factory
+  defaults may be too opinionated.
+- Use `useFactoryDefaults: "none"` only for tests explicitly exercising invalid
+  or incomplete state.
+
+## Retain Entity References
+
+Immediately name entities used by the action or assertions:
+
+```ts
+const author = newAuthor(ctx.em, {
+  books: [{}, {}],
+});
+const [updatedBook, deletedBook] = author.books.get;
+```
+
+Do not unnecessarily rediscover Given entities later by index, query, ID, or
+mutation result. Newly created entities can come from the action result, and a
+query result is appropriate when querying is the behavior under test.
+
+For complicated cross-references in one factory graph, use factory IDs:
+
+```ts
+const author = newAuthor(ctx.em, {
+  books: [
+    { is: "b#1", title: "First" },
+    { is: "b#2", prequel: "b#1", title: "Second" },
+  ],
+});
+const [firstBook, secondBook] = author.books.get;
+
+expect(secondBook).toMatchEntity({ prequel: firstBook });
+```
+
+The `factories` proxy is also available when direct relation destructuring is
+awkward:
+
+```ts
+newAuthor(ctx.em, { books: [{}, {}] });
+const { a1, b1, b2 } = factories;
+```
+
+The proxy resolves against the most recently used `EntityManager`, so avoid it
+in tests with multiple active test entity managers.
+
+Prefer ordinary named constants when the graph is small; they make the test's
+roles clearer than numeric factory IDs.
+
+## DeepNew Means Async-Free Graph Access
+
+Follow the signature generated by the project's Joist version. Factories that
+return `DeepNew<Entity>` provide the loaded graph ergonomics used here:
+
+```ts
+export function newAuthor(em: EntityManager, opts: FactoryOpts<Author> = {}): DeepNew<Author> {
+  return newTestInstance(em, Author, opts, {});
+}
+```
+
+`DeepNew` is a loadedness type for the factory-created graph, so setup and
+assertions can use `.get` without `await`:
+
+```ts
+const author = newAuthor(ctx.em, { books: [{}] });
+const [book] = author.books.get;
+
+expect(author).toMatchEntity({ books: [book] });
+```
+
+Avoid this boilerplate:
+
+```ts
+const books = await author.books.load();
+const reloadedAuthor = await ctx.em.load(Author, author.id);
+const reloadedBooks = await reloadedAuthor.books.load();
+```
+
+`DeepNew` does not synchronize writes from another `EntityManager`. If a
+relation was not part of the factory-created graph, use an intentional
+populate, or use Joist's `run` helper when testing a separate production unit
+of work. Do not silence a legitimate unloaded-relation boundary with arbitrary
+test-only loads.
+
+## Use run for Production Isolation
+
+Joist's `run(ctx, fn)` executes `fn` with a fresh production-style context and
+`EntityManager`. Before the callback, it flushes the test factory graph. As the
+callback flushes Joist writes, `RunPlugin` mirrors those writes into the
+original test `EntityManager`. It does not call `EntityManager.refresh`. The
+callback result is also mapped back to entities from the original test
+`EntityManager`.
+
+```ts
+const author = newAuthor(ctx.em, { books: [{ title: "Before" }] });
+const [book] = author.books.get;
+
+// updateBook must own and flush its production unit of work.
+await run(ctx, (ctx) => updateBook(ctx, { id: book.id, title: "After" }));
+
+expect(book).toMatchEntity({ title: "After" });
+```
+
+Many applications expose a project-specific helper created with `makeRun`,
+such as `runMutation` or `runService`. Use that helper instead of manually
+constructing a second `EntityManager`.
+
+`run` deliberately does not flush the callback's `EntityManager`; production
+code under test must own its normal unit-of-work boundary. Unflushed changes,
+direct SQL, and writes outside Joist are not guaranteed to be mirrored into the
+test graph.
+
+Do not write:
+
+```ts
+const result = await runMutation(ctx, () => updateBookInput(book.id));
+const savedBook = await result.book;
+const books = await savedBook.author.load().then((author) => author.books.load());
+```
+
+Keep using `author` and `book`. They are the stable test references.
+
+Call `em.flush()` directly only when the test intentionally needs a persistence
+boundary and its helper does not provide one. Pure entity tests should usually
+avoid unnecessary flushes.
+
+## Register toMatchEntity
+
+Examples assume `toMatchEntity` is imported from the `joist-orm/tests`
+entry point and registered in the project's test setup:
+
+```ts
+import { toMatchEntity } from "joist-orm/tests";
+
+expect.extend({ toMatchEntity });
+```
+
+Use the runner-specific setup and types from the installed Joist version.
+
+## Assert with toMatchEntity
+
+`toMatchEntity` provides `toMatchObject`-style subset assertions while
+understanding Joist references, collections, properties, reactive fields, and
+entity identity. It also produces concise entity IDs in diffs.
+
+`toMatchEntity` synchronously unwraps loaded relations through `.get`; it does
+not query or asynchronously load missing relations. Ensure the asserted graph
+is loaded by the factory, an intentional populate, or `RunPlugin`.
+
+```ts
+expect(author).toMatchEntity({
+  firstName: "Ann",
+  books: [book],
+});
+expect(book).toMatchEntity({ title: "After" });
+```
+
+Pass retained entity constants directly for relationship identity. Use nested
+object literals when the nested values themselves are the assertion:
+
+```ts
+expect(author).toMatchEntity({
+  books: [{ title: "First" }, { title: "Second" }],
+});
+```
+
+For a hard delete, assert both the surviving collection and deletion state
+when deletion semantics matter:
+
+```ts
+expect(author).toMatchEntity({ books: [updatedBook] });
+expect(deletedBook).toMatchEntity({ isDeletedEntity: true });
+```
+
+Do not map entity graphs into temporary POJOs just to use `toEqual`:
+
+```ts
+// Wrong.
+expect((await author.books.load()).map((book) => ({ id: book.id, title: book.title }))).toEqual([
+  { id: updatedBook.id, title: "After" },
+]);
+```
+
+## Keep Tests Focused
+
+One test should describe one coherent boundary. Split a large graph mutation
+into separate tests when failures would otherwise have several unrelated
+causes:
+
+- Updating/deleting members of a parent collection.
+- Updating/deleting grandchildren.
+- Creating a new nested entity.
+- Clearing a collection.
+- Preserving an omitted relation.
+
+Combining an update and delete can be appropriate when they jointly exercise
+one incremental-collection contract. Avoid a kitchen-sink test that performs
+step updates, ingredient updates, note updates, and several unrelated scalar
+changes in one action.
+
+Focused tests produce smaller Given graphs, clearer constants, and useful
+failure messages.
+
+## Factory Defaults
+
+Customize a generated factory only for defaults that make entities valid by
+default across the suite:
+
+```ts
+export function newAuthor(em: EntityManager, opts: FactoryOpts<Author> = {}): DeepNew<Author> {
+  return newTestInstance(em, Author, opts, {
+    age: 40,
+  });
+}
+```
+
+Use `testIndex` for deterministic unique values when a database unique
+constraint requires them. Add collection defaults only for genuine suite-wide
+validity rules, such as every valid author requiring at least one book.
+
+Custom options such as `withSignedContract` can package a commonly repeated
+graph, but use them sparingly. A reader should not need to inspect a factory to
+understand the values directly asserted by the test.
+
+If factory behavior is surprising, enable `useLogging: true` for that call or
+temporarily enable global factory logging. Diagnose the factory scope and
+reuse decisions instead of replacing factories with manual setup.
+
+## Review Checklist
+
+- Test reads as Given, When, Then, with the code under test isolated as a single
+  When.
+- Given state uses minimal factory opts and does not invoke the behavior under
+  test.
+- Important entities have direct, role-based `const` names.
+- Separate production units of work use `run`/`makeRun` and flush normally.
+- Assertions reuse loaded factory entities with `toMatchEntity`.
+- No unnecessary reloads, `load()` calls, assertion awaits, or direct flushes
+  remain.
+- Each test covers one coherent boundary.

package/skills/joist-upsert/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: joist-upsert
+description: Implement partial-update / RPC / GraphQL save endpoints with Joist using setPartial, createPartial, em.upsert, and incremental collection ops. Use when a create/update accepts a subset of fields, treats null as "unset", or saves a parent plus a mix of new and existing children.
+---
+
+<!-- Managed by joist-codegen. Do not edit by hand; re-run codegen to update. -->
+
+# Joist partial updates & upsert
+
+These APIs exist for "partial update" endpoints (REST/GraphQL/gRPC) where the
+input is loosely typed (`string | null | undefined`) and follows the
+conventions:
+
+- A subset of fields may be sent; omitted fields are left as-is.
+- `null` means "unset this field".
+- Children collections can be updated incrementally.
+
+Joist's normal `em.create` / `Entity.set` are intentionally strict and won't
+accept `string | null | undefined`. The partial variants opt into the looser
+semantics.
+
+## `setPartial`
+
+```ts
+// firstName is typed `string | null | undefined` (e.g. from a GraphQL input)
+const author = await em.load(Author, "a:1");
+author.setPartial({ firstName }); // compiles; `set` would not
+```
+
+Semantics, per field:
+
+- Required field (`firstName`): value updates it; `undefined` does nothing;
+  `null` is a **validation error** (required field can't be unset).
+- Optional field (`lastName`): value updates it; `undefined` does nothing;
+  `null` unsets it (sets to `undefined`).
+- Collection (`books`): `[b1]` sets it to exactly `[b1]`; `null` sets it to
+  `[]`; `undefined` does nothing.
+
+`em.createPartial(Author, ...)` and `em.upsert(Author, ...)` share these
+semantics.
+
+## `em.upsert` — parent plus children
+
+`em.upsert` saves a parent and a mix of new/existing children in one call. It is
+**async** (unlike `em.create`) because it may issue `SELECT`s to resolve
+existing child ids.
+
+```ts
+await em.upsert(Author, {
+  id: "a:1",                       // update author 1
+  books: [
+    { title: "new book" },         // no id -> create
+    { id: "b:1" },                 // existing, unchanged
+    { id: "b:2", title: "updated" }, // existing, updated
+  ],
+});
+```
+
+By default a collection is set **exhaustively** — any existing child not listed
+is removed.
+
+## Incremental collections (`op`)
+
+To change only some children without sending the whole collection, add an `op`
+hint to each child:
+
+```ts
+author.setPartial({
+  books: [{ op: "include", title: "b3" }], // adds b3, leaves existing books
+});
+```
+
+- `{ op: "include", id }` — add if needed, or update an existing child
+- `{ op: "remove", id }` — remove from the collection (no delete)
+- `{ op: "delete", id }` — remove and `em.delete` the child
+
+Rules and gotchas:
+
+- If **any** child has an `op`, **all** children must have one.
+- `op` is not a real entity field — it's only a hint on the input type.
+- An **empty** list always clears the collection (it looks like an exhaustive
+  set), so to send "no changes" omit the collection key entirely. Alternatively
+  include a single `{ op: "incremental" }` sentinel child to force incremental
+  semantics without adding/removing anything.
+
+## Legacy keys (soft-deprecated)
+
+Older code used `delete: true` / `remove: true` instead of `op`; still
+supported, but prefer `op` for new code:
+
+```ts
+author.setPartial({
+  books: [{ id: "b:1", delete: true }, { id: "b:2", remove: true }, { id: "b:4" }],
+});
+```