joist-codegen 2.4.0-next.4 → 2.4.0-next.40

package/build/utils.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.cts","names":[],"sources":["../src/utils.ts"],"mappings":";;;;iBASgB,YAAY;iBAIZ,cAAc,QAAQ,QAAQ,GAAG;iBA8BjC,gBAAgB,GAAG;iBAKnB,YAAY,QAAQ,QAAQ,GAAG;iBAW/B,YAAY,QAAQ,QAAQ,GAAG;;iBAoB/B,eAAe,GAAG;;iBAelB,kBAAkB,QAAQ,QAAQ,OAAO;cAY5C,4BAAQ;cACR,iCAAa;cACb,iCAAa;cACb,qCAAiB;cACjB,qCAAiB;;iBAGd,gCAAgC,QAAQ,QAAQ,QAAQ,qBAAqB;iBA4C7E,MAAM,GAAG,GAAG,KAAK,GAAG,MAAM;;iBAKpB,eAAe,GAAG,mBAAmB;iBAO3C,KAAK;iBAIL,SAAS,kBAAkB,GAAG,IAAI;iBAclC,WAAW;EAA8B;EAAe;;iBAWxD,EAAE;iBAIF,aAAa;;iBASb,oBAAoB,QAAQ,QAAQ,GAAG"}
+{"version":3,"file":"utils.d.cts","names":[],"sources":["../src/utils.ts"],"mappings":";;;;wBASgB,YAAY;wBAIZ,cAAc,QAAQ,QAAQ,GAAG;wBA8BjC,gBAAgB,GAAG;wBAKnB,YAAY,QAAQ,QAAQ,GAAG;wBAW/B,YAAY,QAAQ,QAAQ,GAAG;;wBAoB/B,eAAe,GAAG;;wBAelB,kBAAkB,QAAQ,QAAQ,OAAO;qBAY5C,4BAAQ;qBACR,iCAAa;qBACb,iCAAa;qBACb,qCAAiB;qBACjB,qCAAiB;;wBAGd,gCAAgC,QAAQ,QAAQ,QAAQ,qBAAqB;wBA4C7E,MAAM,GAAG,GAAG,KAAK,GAAG,MAAM;;wBAKpB,eAAe,GAAG,mBAAmB;wBAO3C,KAAK;wBAIL,SAAS,kBAAkB,GAAG,IAAI;wBAclC,WAAW;EAA8B;EAAe;;wBAWxD,EAAE;wBAIF,aAAa;;wBASb,oBAAoB,QAAQ,QAAQ,GAAG"}

package/build/utils.d.mts

@@ -2,35 +2,34 @@ import { Config } from "./config.mjs";
 import { Table } from "./pgMetadata.mjs";
 import { DatabaseColumnType, PrimitiveTypescriptType } from "./EntityDbMetadata.mjs";
 //#region src/utils.d.ts
-declare function assertNever(x: never): never;
-declare function isEntityTable(config: Config, t: Table): boolean;
-declare function isSubClassTable(t: Table): boolean;
-declare function isEnumTable(config: Config, t: Table): boolean;
-declare function isJoinTable(config: Config, t: Table): boolean;
+export declare function assertNever(x: never): never;
+export declare function isEntityTable(config: Config, t: Table): boolean;
+export declare function isSubClassTable(t: Table): boolean;
+export declare function isEnumTable(config: Config, t: Table): boolean;
+export declare function isJoinTable(config: Config, t: Table): boolean;
 /** Whether a join table has a surrogate `id` primary key (vs. an id-less FK-pair composite PK). */
-declare function joinTableHasId(t: Table): boolean;
+export declare function joinTableHasId(t: Table): boolean;
 /** Converts `projects` to `Project`. */
-declare function tableToEntityName(config: Config, table: Table): string;
-declare const dateCode: import("ts-poet").Code;
-declare const plainDateCode: import("ts-poet").Code;
-declare const plainTimeCode: import("ts-poet").Code;
-declare const plainDateTimeCode: import("ts-poet").Code;
-declare const zonedDateTimeCode: import("ts-poet").Code;
+export declare function tableToEntityName(config: Config, table: Table): string;
+export declare const dateCode: import("ts-poet").Code;
+export declare const plainDateCode: import("ts-poet").Code;
+export declare const plainTimeCode: import("ts-poet").Code;
+export declare const plainDateTimeCode: import("ts-poet").Code;
+export declare const zonedDateTimeCode: import("ts-poet").Code;
 /** Maps db types, i.e. `int`, to JS types, i.e. `number`. */
-declare function mapSimpleDbTypeToTypescriptType(config: Config, dbType: DatabaseColumnType): PrimitiveTypescriptType;
-declare function merge<T>(a: T[], b: T[]): T[];
+export declare function mapSimpleDbTypeToTypescriptType(config: Config, dbType: DatabaseColumnType): PrimitiveTypescriptType;
+export declare function merge<T>(a: T[], b: T[]): T[];
 /** Returns true if `p` is resolved, otherwise false if it is rejected. */
-declare function trueIfResolved(p: Promise<unknown>): Promise<boolean>;
-declare function fail(message?: string): never;
-declare function sortKeys<T extends object>(o: T): T;
-declare function parseOrder(order: string | undefined): {
+export declare function trueIfResolved(p: Promise<unknown>): Promise<boolean>;
+export declare function fail(message?: string): never;
+export declare function sortKeys<T extends object>(o: T): T;
+export declare function parseOrder(order: string | undefined): {
   field: string;
   direction: "ASC" | "DESC";
 } | undefined;
-declare function q(s: string | undefined): string;
-declare function uncapitalize(s: string): string;
+export declare function q(s: string | undefined): string;
+export declare function uncapitalize(s: string): string;
 /** Uses the same schema selection for metadata and test database cleanup. */
-declare function shouldIncludeSchema(config: Config, t: Table): boolean;
+export declare function shouldIncludeSchema(config: Config, t: Table): boolean;
 //#endregion
-export { assertNever, dateCode, fail, isEntityTable, isEnumTable, isJoinTable, isSubClassTable, joinTableHasId, mapSimpleDbTypeToTypescriptType, merge, parseOrder, plainDateCode, plainDateTimeCode, plainTimeCode, q, shouldIncludeSchema, sortKeys, tableToEntityName, trueIfResolved, uncapitalize, zonedDateTimeCode };
 //# sourceMappingURL=utils.d.mts.map

package/build/utils.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.mts","names":[],"sources":["../src/utils.ts"],"mappings":";;;;iBASgB,YAAY;iBAIZ,cAAc,QAAQ,QAAQ,GAAG;iBA8BjC,gBAAgB,GAAG;iBAKnB,YAAY,QAAQ,QAAQ,GAAG;iBAW/B,YAAY,QAAQ,QAAQ,GAAG;;iBAoB/B,eAAe,GAAG;;iBAelB,kBAAkB,QAAQ,QAAQ,OAAO;cAY5C,4BAAQ;cACR,iCAAa;cACb,iCAAa;cACb,qCAAiB;cACjB,qCAAiB;;iBAGd,gCAAgC,QAAQ,QAAQ,QAAQ,qBAAqB;iBA4C7E,MAAM,GAAG,GAAG,KAAK,GAAG,MAAM;;iBAKpB,eAAe,GAAG,mBAAmB;iBAO3C,KAAK;iBAIL,SAAS,kBAAkB,GAAG,IAAI;iBAclC,WAAW;EAA8B;EAAe;;iBAWxD,EAAE;iBAIF,aAAa;;iBASb,oBAAoB,QAAQ,QAAQ,GAAG"}
+{"version":3,"file":"utils.d.mts","names":[],"sources":["../src/utils.ts"],"mappings":";;;;wBASgB,YAAY;wBAIZ,cAAc,QAAQ,QAAQ,GAAG;wBA8BjC,gBAAgB,GAAG;wBAKnB,YAAY,QAAQ,QAAQ,GAAG;wBAW/B,YAAY,QAAQ,QAAQ,GAAG;;wBAoB/B,eAAe,GAAG;;wBAelB,kBAAkB,QAAQ,QAAQ,OAAO;qBAY5C,4BAAQ;qBACR,iCAAa;qBACb,iCAAa;qBACb,qCAAiB;qBACjB,qCAAiB;;wBAGd,gCAAgC,QAAQ,QAAQ,QAAQ,qBAAqB;wBA4C7E,MAAM,GAAG,GAAG,KAAK,GAAG,MAAM;;wBAKpB,eAAe,GAAG,mBAAmB;wBAO3C,KAAK;wBAIL,SAAS,kBAAkB,GAAG,IAAI;wBAclC,WAAW;EAA8B;EAAe;;wBAWxD,EAAE;wBAIF,aAAa;;wBASb,oBAAoB,QAAQ,QAAQ,GAAG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "joist-codegen",
-  "version": "2.4.0-next.4",
+  "version": "2.4.0-next.40",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -48,32 +48,32 @@
     "skills"
   ],
   "peerDependencies": {
-    "joist-utils": "2.4.0-next.4",
+    "joist-utils": "2.4.0-next.40",
     "knex": "^3.1.0",
     "pg": "^8.23.0"
   },
   "dependencies": {
     "@dprint/formatter": "^0.5.1",
-    "@dprint/json": "^0.21.3",
-    "@inquirer/prompts": "^8.6.0",
+    "@dprint/json": "^0.25.2",
+    "@inquirer/prompts": "^8.7.3",
     "@types/jscodeshift": "^17.3.0",
     "@types/pluralize": "^0.0.33",
-    "change-case": "^4.1.2",
+    "change-case": "^5.4.4",
     "fast-glob": "^3.3.3",
     "jscodeshift": "^17.4.0",
     "jsonc-parser": "^3.3.1",
     "pluralize": "^8.0.0",
-    "prettier": "^3.9.6",
+    "prettier": "^3.9.10",
     "ts-poet": "^6.12.0",
-    "zod": "^4.4.3"
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@swc/jest": "^0.2.39",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.6.5",
     "jest": "30.4.2",
     "tsconfig-paths": "^4.2.0",
-    "tsx": "^4.23.12",
+    "tsx": "^4.23.15",
     "typescript": "7.0.2"
   }
 }

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

@@ -1,14 +1,18 @@
 ---
 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.
+description: Use when writing or refactoring Joist ORM entity or API-layer tests with newTestInstance factories, DeepNew, toMatchEntity, and nested Given graphs, or deciding whether EntityManager isolation with run, makeRun, or RunPlugin is needed.
 ---
 
 # Joist Test Factories
 
-Write isolated, succinct tests that use Joist's factories for setup, retain
+Write focused, succinct tests that use Joist's factories for setup, retain
 typed entity references through the action, and assert those same entities
 with `toMatchEntity`.
 
+Entity tests normally use one `EntityManager` for Given, When, and Then.
+Use `run` for API-layer tests and other production boundaries that need a
+separate `EntityManager`, not as a default wrapper around every test action.
+
 Authoritative references:
 
 - <https://joist-orm.io/testing/test-factories/>
@@ -27,10 +31,16 @@ Authoritative references:
 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
+5. Keep entity tests in the original test `EntityManager`; they normally do not
+   need EM isolation or `RunPlugin`. Use `run` or the project's `makeRun` wrapper
+   for API/request-layer tests or another production boundary that 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`.
+   Do not `await em.flush()` right before `run` or a `makeRun` helper: it
+   already flushes the Given graph, use as few `em.flush()` calls as possible.
+6. Assert entity state and relationships with `toMatchEntity`. Prefer checking
+   side effects through retained entities and their relations instead of using
+   `em.getEntities` to discover what the action created or changed.
 7. Prefer focused tests for one behavior over a single scenario that exercises
    unrelated updates at several graph levels.
 
@@ -41,6 +51,23 @@ 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:
 
+For an entity test, act directly on the factory-created entity:
+
+```ts
+it.withCtx("updates a book's title", async (ctx) => {
+  // Given a book with its original title
+  const book = newBook(ctx.em, { title: "Before" });
+
+  // When we change the book's title
+  book.title = "After";
+
+  // Then the book has the new title
+  expect(book).toMatchEntity({ title: "After" });
+});
+```
+
+For an API-layer test, use `run` to model its separate production unit of work:
+
 ```ts
 it.withCtx("updates a book", async (ctx) => {
   // Given an author with one book
@@ -241,6 +268,23 @@ test-only loads.
 
 ## Use run for Production Isolation
 
+Choose isolation based on the behavior under test:
+
+- **Entity tests:** Test entity methods, properties, relationships, and domain
+  logic directly with the test's `ctx.em` and factory-created entities. These
+  normally do not need `run`, a second EM, or a manually installed `RunPlugin`.
+  Flush only when the behavior requires it, such as validation, flush hooks,
+  persisted reactive fields, or database constraints. Needing a flush does not
+  by itself mean the test needs EM isolation.
+- **API/request-layer tests:** Use `run` or an existing project wrapper such as
+  `runMutation` when testing a resolver, endpoint, or service entry point whose
+  production unit of work uses a fresh EM. This ensures the action loads its
+  own entities rather than inheriting the test's loaded factory graph.
+- **Other boundaries:** Use `run` when a fresh production unit of work is part
+  of the behavior being tested. A service/helper that operates on existing
+  entities or the caller's EM does not need isolation merely because it is
+  production code.
+
 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
@@ -248,6 +292,11 @@ original test `EntityManager`. It does not call `EntityManager.refresh`. The
 callback result is also mapped back to entities from the original test
 `EntityManager`.
 
+`run` installs `RunPlugin` automatically on the isolated EM. The plugin bridges
+that production unit of work back to the retained test entities; it is not
+needed when Given, When, and Then already share one EM. Prefer `run` or the
+project's wrapper over manually wiring the plugin.
+
 ```ts
 const author = newAuthor(ctx.em, { books: [{ title: "Before" }] });
 const [book] = author.books.get;
@@ -278,8 +327,9 @@ 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.
+boundary and its helper does not provide one, e.g. to persist one Given state
+before changing it into the next one. Pure entity tests should usually avoid
+unnecessary flushes.
 
 ## Register toMatchEntity
 
@@ -338,6 +388,39 @@ expect((await author.books.load()).map((book) => ({ id: book.id, title: book.tit
 ]);
 ```
 
+## Assert Side Effects Through the Domain Graph
+
+Avoid `em.getEntities(Entity).filter(...)` or `.find(...)` to look up side
+effects for assertions. `getEntities` inspects the `EntityManager`'s tracked
+entities; finding a new child there does not prove that the action attached it
+to the correct parent. Assert through the retained Given graph instead, so the
+test describes the resulting domain state and checks relationship membership.
+
+```ts
+// Less useful: finds a book without proving which author owns it.
+const [createdBook] = ctx.em.getEntities(Book).filter((book) => book.title === "New book");
+expect(createdBook).toMatchEntity({ title: "New book" });
+```
+
+```ts
+it.withCtx("adds a book to the existing author", async (ctx) => {
+  // Given an author with an existing book
+  const author = newAuthor(ctx.em, { books: [{}] });
+  const [existingBook] = author.books.get;
+
+  // When we add another book to that author
+  await run(ctx, (ctx) => addBook(ctx, { authorId: author.id, title: "New book" }));
+
+  // Then the author keeps the existing book and owns the new book
+  expect(author).toMatchEntity({ books: [existingBook, { title: "New book" }] });
+});
+```
+
+Use the action result when a new entity has no natural path from the Given
+graph. If neither a relation nor the result exposes it, use an intentional
+domain query. Reserve `getEntities` assertions for tests whose behavior under
+test is specifically which entities the `EntityManager` tracks.
+
 ## Keep Tests Focused
 
 One test should describe one coherent boundary. Split a large graph mutation
@@ -390,8 +473,12 @@ reuse decisions instead of replacing factories with manual setup.
 - Given state uses minimal factory opts and does not invoke the behavior under
   test.
 - Important entities have direct, role-based `const` names.
+- Entity tests use the original test EM unless the behavior specifically needs
+  a separate production unit of work; a flush alone does not require `run`.
 - Separate production units of work use `run`/`makeRun` and flush normally.
 - Assertions reuse loaded factory entities with `toMatchEntity`.
+- Side-effect assertions follow domain relations or action results instead of
+  scanning `em.getEntities` for created or changed entities.
 - No unnecessary reloads, `load()` calls, assertion awaits, or direct flushes
   remain.
 - Each test covers one coherent boundary.