create-joist-app 0.0.1

package/templates/basic/src/context.ts

@@ -0,0 +1,14 @@
+import { EntityManager, newPgConnectionConfig } from "joist-orm";
+import { PostgresDriver } from "joist-orm/pg";
+import { Pool } from "pg";
+
+export interface Context {
+  pool: Pool;
+  em: EntityManager;
+}
+
+export function newContext(): Context {
+  const pool = new Pool(newPgConnectionConfig());
+  const em = new EntityManager({}, new PostgresDriver(pool));
+  return { em, pool };
+}

package/templates/basic/src/entities/Author.test.ts

@@ -0,0 +1,17 @@
+import { newEm } from "../setupTests";
+import { newAuthor, newBook } from "./factories";
+
+describe("Author", () => {
+  it("can create an author", async () => {
+    const em = newEm();
+    newAuthor(em, { firstName: "John", lastName: "Doe" });
+    await em.flush();
+  });
+
+  it("can have books", async () => {
+    const em = newEm();
+    const author = newAuthor(em, { firstName: "Test", lastName: "Author" });
+    newBook(em, { title: "Test Book", author });
+    await em.flush();
+  });
+});

package/templates/basic/src/entities/Author.ts

@@ -0,0 +1,7 @@
+import { AuthorCodegen } from "./codegen/AuthorCodegen";
+
+export class Author extends AuthorCodegen {
+  get fullName(): string {
+    return `${this.firstName} ${this.lastName}`;
+  }
+}

package/templates/basic/src/entities/Book.ts

@@ -0,0 +1,3 @@
+import { BookCodegen } from "./codegen/BookCodegen";
+
+export class Book extends BookCodegen {}

package/templates/basic/src/entities/entities.ts

@@ -0,0 +1,14 @@
+// organize-imports-ignore
+
+// This file drives our import order to avoid undefined errors
+// when the subclasses extend the base classes, see:
+// https://medium.com/visual-development/how-to-fix-nasty-circular-dependency-issues-once-and-for-all-in-javascript-typescript-a04c987cf0de
+
+export * from "./codegen/AuthorCodegen";
+export * from "./codegen/BookCodegen";
+export * from "./Author";
+export * from "./Book";
+
+export * from "./factories/newAuthor";
+export * from "./factories/newBook";
+export * from "./codegen/metadata";

package/templates/basic/src/entities/factories/index.ts

@@ -0,0 +1,2 @@
+export * from "./newAuthor";
+export * from "./newBook";

package/templates/basic/src/entities/factories/newAuthor.ts

@@ -0,0 +1,6 @@
+import { EntityManager, FactoryOpts, newTestInstance } from "joist-orm";
+import { Author } from "../entities";
+
+export function newAuthor(em: EntityManager, opts?: FactoryOpts<Author>): Author {
+  return newTestInstance(em, Author, opts);
+}

package/templates/basic/src/entities/factories/newBook.ts

@@ -0,0 +1,6 @@
+import { EntityManager, FactoryOpts, newTestInstance } from "joist-orm";
+import { Book } from "../entities";
+
+export function newBook(em: EntityManager, opts?: FactoryOpts<Book>): Book {
+  return newTestInstance(em, Book, opts);
+}

package/templates/basic/src/entities/index.ts

@@ -0,0 +1,3 @@
+export * from "./entities";
+export * from "./Author";
+export * from "./Book";

package/templates/basic/src/setupTestEnv.ts

@@ -0,0 +1,5 @@
+import { GetEnvVars } from "env-cmd";
+
+export default async function globalSetup() {
+  Object.entries(await GetEnvVars()).forEach(([key, value]) => (process.env[key] = value));
+}

package/templates/basic/src/setupTests.ts

@@ -0,0 +1,29 @@
+import expect from "expect";
+import { newPgConnectionConfig } from "joist-orm";
+import { PostgresDriver } from "joist-orm/pg";
+import { toMatchEntity } from "joist-orm/tests";
+import pg from "pg";
+import { Context } from "./context";
+import { EntityManager } from "./entities";
+
+expect.extend({ toMatchEntity });
+
+let pool: pg.Pool;
+
+beforeAll(async () => {
+  pool = new pg.Pool(newPgConnectionConfig());
+});
+
+beforeEach(async () => {
+  await pool.query("select flush_database()");
+});
+
+afterAll(async () => {
+  await pool.end();
+});
+
+export function newEm(): EntityManager {
+  const driver = new PostgresDriver(pool);
+  const ctx = { pool, em: null as any } satisfies Context;
+  return new EntityManager(ctx, driver);
+}

package/templates/basic/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "lib": ["ES2022"],
+    "moduleResolution": "nodenext",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./build",
+    "rootDir": "./src",
+    "baseUrl": "./src",
+    "paths": {
+      "src/*": ["./*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "build"]
+}

package/templates/graphql/README.md

@@ -0,0 +1,84 @@
+# {{PROJECT_NAME}}
+
+A [Joist ORM](https://joist-orm.io/) project with GraphQL.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- Docker (for PostgreSQL)
+
+### Setup
+
+1. Start the database and run initial setup:
+
+```bash
+yarn db
+```
+
+This command will:
+- Start a PostgreSQL container
+- Run database migrations
+- Generate Joist entity code and GraphQL types
+
+### Development
+
+#### Starting the Server
+
+```bash
+yarn dev
+```
+
+The GraphQL server will start at http://localhost:4000
+
+#### Running Tests
+
+```bash
+yarn test
+```
+
+#### Creating a New Migration
+
+```bash
+yarn migrate:new my-migration-name
+```
+
+Then edit the generated file in `migrations/` and run:
+
+```bash
+yarn migrate
+yarn codegen
+```
+
+#### Resetting the Database
+
+```bash
+yarn redb
+```
+
+### Project Structure
+
+```
+├── migrations/           # Database migrations
+├── src/
+│   ├── entities/        # Joist entities
+│   │   ├── codegen/     # Generated entity code (do not edit)
+│   │   └── factories/   # Test factories
+│   ├── resolvers/       # GraphQL resolvers
+│   ├── generated/       # Generated GraphQL types (do not edit)
+│   ├── context.ts       # Request context
+│   ├── schema.graphql   # GraphQL schema
+│   ├── server.ts        # Apollo Server setup
+│   ├── setupTestEnv.ts  # Global test setup
+│   └── setupTests.ts    # Per-suite test setup
+├── docker-compose.yml   # PostgreSQL service
+├── joist-config.json    # Joist configuration
+└── codegen.yml          # GraphQL codegen configuration
+```
+
+## Learn More
+
+- [Joist Documentation](https://joist-orm.io/)
+- [Apollo Server](https://www.apollographql.com/docs/apollo-server/)
+- [GitHub Repository](https://github.com/joist-orm/joist-orm)

package/templates/graphql/codegen.yml

@@ -0,0 +1,11 @@
+schema: "./src/**/*.graphql"
+generates:
+  ./src/generated/graphql-types.ts:
+    plugins:
+      - typescript
+      - typescript-resolvers
+    config:
+      contextType: "../context#Context"
+      mappers:
+        Author: ../entities#Author
+        Book: ../entities#Book

package/templates/graphql/gitignore

@@ -0,0 +1,28 @@
+# Dependencies
+node_modules/
+
+# Build output
+build/
+dist/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Test output
+coverage/
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# TypeScript
+*.tsbuildinfo

package/templates/graphql/graphql-codegen-joist.js

@@ -0,0 +1,5 @@
+const mappers = { Author: "src/entities#Author", Book: "src/entities#Book" };
+
+const enumValues = {};
+
+module.exports = { mappers, enumValues };

package/templates/graphql/graphql-codegen.js

@@ -0,0 +1,26 @@
+const { mappers, enumValues } = require("./graphql-codegen-joist");
+
+module.exports = {
+  overwrite: true,
+  schema: "./schema/**/*.graphql",
+  documents: null,
+  generates: {
+    "src/generated/graphql-types.ts": {
+      config: {
+        contextType: "src/context#Context",
+        noSchemaStitching: true,
+        avoidOptionals: true,
+        scaffolding: {
+          ignoreObjectsPattern: "Detail$",
+        },
+        mappers,
+        enumValues,
+      },
+      plugins: [
+        "@homebound/graphql-typescript-simple-resolvers",
+        "@homebound/graphql-typescript-resolver-scaffolding",
+        "@homebound/graphql-typescript-possible-types",
+      ],
+    },
+  },
+};

package/templates/graphql/jest.config.js

@@ -0,0 +1,14 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  transform: {
+    "^.+\\.tsx?$": "@swc/jest",
+  },
+  moduleNameMapper: {
+    "^src/(.*)$": "<rootDir>/src/$1",
+  },
+  testMatch: ["<rootDir>/src/**/*.test.{ts,tsx}"],
+  testEnvironment: "node",
+  globalSetup: "./src/setupTestEnv.ts",
+  setupFilesAfterEnv: ["./src/setupTests.ts"],
+  maxWorkers: 1,
+};

package/templates/graphql/joist-config.json

@@ -0,0 +1,8 @@
+{
+  "codegenPlugins": ["joist-graphql-codegen"],
+  "contextType": "Context@src/context",
+  "entities": { "Author": { "tag": "a" }, "Book": { "tag": "b" } },
+  "entitiesDirectory": "./src/entities",
+  "idType": "tagged-string",
+  "version": "0.0.0"
+}

package/templates/graphql/migrations/1580658856631_initial.ts

@@ -0,0 +1,38 @@
+import {
+  createCreatedAtFunction,
+  createEntityTable,
+  createUpdatedAtFunction,
+  foreignKey,
+} from "joist-migration-utils";
+import { MigrationBuilder } from "node-pg-migrate";
+
+export function up(b: MigrationBuilder): void {
+  createUpdatedAtFunction(b);
+  createCreatedAtFunction(b);
+
+  // Create flush_database function for test cleanup
+  b.sql(`
+    CREATE OR REPLACE FUNCTION flush_database() RETURNS void AS $$
+    DECLARE
+      tables CURSOR FOR
+        SELECT tablename FROM pg_tables
+        WHERE schemaname = 'public'
+        AND tablename != 'pgmigrations';
+    BEGIN
+      FOR t IN tables LOOP
+        EXECUTE 'TRUNCATE TABLE ' || quote_ident(t.tablename) || ' CASCADE';
+      END LOOP;
+    END;
+    $$ LANGUAGE plpgsql;
+  `);
+
+  createEntityTable(b, "authors", {
+    first_name: { type: "varchar(255)", notNull: true },
+    last_name: { type: "varchar(255)", notNull: false },
+  });
+
+  createEntityTable(b, "books", {
+    title: { type: "varchar(255)", notNull: true },
+    author_id: foreignKey("authors", { notNull: true }),
+  });
+}

package/templates/graphql/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "graphql-template",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx src/server.ts",
+    "dev": "tsx watch src/server.ts",
+    "test": "env-cmd jest --runInBand",
+    "codegen": "env-cmd yarn joist-codegen && yarn graphql-codegen",
+    "graphql-codegen": "graphql-codegen --config graphql-codegen.js",
+    "format": "prettier --write \"src/**/*.{ts,tsx,graphql}\""
+  },
+  "dependencies": {
+    "@apollo/server": "^4.11.0",
+    "@graphql-tools/graphql-file-loader": "^8.0.0",
+    "@graphql-tools/load": "^8.0.0",
+    "@graphql-tools/merge": "^9.0.0",
+    "graphql": "^16.9.0",
+    "joist-orm": "2.0.3-next.36",
+    "knex": "^3.1.0",
+    "pg": "^8.16.3"
+  },
+  "devDependencies": {
+    "@graphql-codegen/cli": "^5.0.0",
+    "@graphql-codegen/typescript": "^4.0.0",
+    "@graphql-codegen/typescript-resolvers": "^4.0.0",
+    "@homebound/graphql-typescript-possible-types": "^2.19.0",
+    "@homebound/graphql-typescript-resolver-scaffolding": "^2.49.0",
+    "@homebound/graphql-typescript-simple-resolvers": "^1.58.0",
+    "@swc/core": "^1.13.0",
+    "@swc/jest": "^0.2.39",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
+    "env-cmd": "^11.0.0",
+    "jest": "^30.0.0",
+    "prettier": "^3.6.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/graphql/schema/.history.json

@@ -0,0 +1,9 @@
+{
+  "Author": ["books", "createdAt", "firstName", "id", "lastName", "updatedAt"],
+  "Book": ["author", "createdAt", "id", "title", "updatedAt"],
+  "Mutation": ["saveAuthor", "saveBook"],
+  "SaveAuthorInput": ["firstName", "id", "lastName"],
+  "SaveAuthorResult": ["author"],
+  "SaveBookInput": ["authorId", "id", "title"],
+  "SaveBookResult": ["book"]
+}

package/templates/graphql/schema/author.graphql

@@ -0,0 +1,20 @@
+extend type Mutation {
+  saveAuthor(input: SaveAuthorInput!): SaveAuthorResult!
+}
+
+type Author {
+  id: ID!
+  firstName: String!
+  lastName: String
+  books: [Book!]!
+}
+
+input SaveAuthorInput {
+  id: ID
+  firstName: String
+  lastName: String
+}
+
+type SaveAuthorResult {
+  author: Author!
+}

package/templates/graphql/schema/book.graphql

@@ -0,0 +1,19 @@
+extend type Mutation {
+  saveBook(input: SaveBookInput!): SaveBookResult!
+}
+
+type Book {
+  id: ID!
+  title: String!
+  author: Author!
+}
+
+input SaveBookInput {
+  id: ID
+  title: String
+  authorId: ID
+}
+
+type SaveBookResult {
+  book: Book!
+}

package/templates/graphql/src/.history.json

@@ -0,0 +1,12 @@
+{
+  "files": [
+    "resolvers/author/authorResolvers.test.ts",
+    "resolvers/author/authorResolvers.ts",
+    "resolvers/author/saveAuthorMutation.test.ts",
+    "resolvers/author/saveAuthorMutation.ts",
+    "resolvers/book/bookResolvers.test.ts",
+    "resolvers/book/bookResolvers.ts",
+    "resolvers/book/saveBookMutation.test.ts",
+    "resolvers/book/saveBookMutation.ts"
+  ]
+}

package/templates/graphql/src/context.ts

@@ -0,0 +1,14 @@
+import { EntityManager, newPgConnectionConfig } from "joist-orm";
+import { PostgresDriver } from "joist-orm/pg";
+import { Pool } from "pg";
+
+export interface Context {
+  pool: Pool;
+  em: EntityManager;
+}
+
+export function newContext(): Context {
+  const pool = new Pool(newPgConnectionConfig());
+  const em = new EntityManager({}, new PostgresDriver(pool));
+  return { em, pool };
+}

package/templates/graphql/src/entities/Author.test.ts

@@ -0,0 +1,36 @@
+import { newEm } from "../setupTests";
+import { newAuthor, newBook } from "./factories";
+
+describe("Author", () => {
+  it("can create an author", async () => {
+    const em = newEm();
+    const author = newAuthor(em, { firstName: "John", lastName: "Doe" });
+    await em.flush();
+
+    const loaded = await em.load(author.constructor, author.id);
+    expect(loaded).toMatchEntity({ firstName: "John", lastName: "Doe" });
+  });
+
+  it("has a full name", async () => {
+    const em = newEm();
+    const author = newAuthor(em, { firstName: "Jane", lastName: "Smith" });
+    expect(author.fullName).toBe("Jane Smith");
+  });
+
+  it("handles missing last name in fullName", async () => {
+    const em = newEm();
+    const author = newAuthor(em, { firstName: "Jane" });
+    expect(author.fullName).toBe("Jane");
+  });
+
+  it("can have books", async () => {
+    const em = newEm();
+    const author = newAuthor(em, { firstName: "Test", lastName: "Author" });
+    const book = newBook(em, { title: "Test Book", author });
+    await em.flush();
+
+    const books = await author.books.load();
+    expect(books).toHaveLength(1);
+    expect(books[0]).toMatchEntity({ title: "Test Book" });
+  });
+});

package/templates/graphql/src/entities/Author.ts

@@ -0,0 +1,7 @@
+import { AuthorCodegen } from "./codegen/AuthorCodegen";
+
+export class Author extends AuthorCodegen {
+  get fullName(): string {
+    return `${this.firstName} ${this.lastName || ""}`.trim();
+  }
+}

package/templates/graphql/src/entities/Book.ts

@@ -0,0 +1,3 @@
+import { BookCodegen } from "./codegen/BookCodegen";
+
+export class Book extends BookCodegen {}

package/templates/graphql/src/entities/entities.ts

@@ -0,0 +1,14 @@
+// organize-imports-ignore
+
+// This file drives our import order to avoid undefined errors
+// when the subclasses extend the base classes, see:
+// https://medium.com/visual-development/how-to-fix-nasty-circular-dependency-issues-once-and-for-all-in-javascript-typescript-a04c987cf0de
+
+export * from "./codegen/AuthorCodegen";
+export * from "./codegen/BookCodegen";
+export * from "./Author";
+export * from "./Book";
+
+export * from "./factories/newAuthor";
+export * from "./factories/newBook";
+export * from "./codegen/metadata";

package/templates/graphql/src/entities/factories/index.ts

@@ -0,0 +1,2 @@
+export * from "./newAuthor";
+export * from "./newBook";

package/templates/graphql/src/entities/factories/newAuthor.ts

@@ -0,0 +1,6 @@
+import { EntityManager, FactoryOpts, newTestInstance } from "joist-orm";
+import { Author } from "../Author";
+
+export function newAuthor(em: EntityManager, opts?: FactoryOpts<Author>): Author {
+  return newTestInstance(em, Author, opts);
+}

package/templates/graphql/src/entities/factories/newBook.ts

@@ -0,0 +1,6 @@
+import { EntityManager, FactoryOpts, newTestInstance } from "joist-orm";
+import { Book } from "../Book";
+
+export function newBook(em: EntityManager, opts?: FactoryOpts<Book>): Book {
+  return newTestInstance(em, Book, opts);
+}

package/templates/graphql/src/entities/index.ts

@@ -0,0 +1,3 @@
+export * from "./entities";
+export * from "./Author";
+export * from "./Book";

package/templates/graphql/src/jest.d.ts

@@ -0,0 +1,9 @@
+declare namespace jest {
+  type ContextOpts = Partial<import("./context").Context & import("./context").AppContext>;
+  type itWithCtxFn = (ctx: import("./context").Context) => Promise<void>;
+
+  interface It {
+    withCtx(name: string, fn: itWithCtxFn): void;
+    withCtx(name: string, opts: ContextOpts, fn: itWithCtxFn): void;
+  }
+}

package/templates/graphql/src/resolvers/author/authorResolvers.test.ts

@@ -0,0 +1,17 @@
+import { newAuthor } from "src/entities";
+import { authorResolvers } from "src/resolvers/author/authorResolvers";
+import { makeRunObjectField, makeRunObjectFields } from "src/resolvers/testUtils";
+
+describe("authorResolvers", () => {
+  it.withCtx("can return", async (ctx) => {
+    const { em } = ctx;
+    // Given a Author
+    const a = newAuthor(em);
+    // Then we can query it
+    const result = await runFields(ctx, a, ["firstName", "lastName", "createdAt", "updatedAt"]);
+    expect(result).toMatchEntity({});
+  });
+});
+
+const runFields = makeRunObjectFields(authorResolvers);
+const runField = makeRunObjectField(authorResolvers);

package/templates/graphql/src/resolvers/author/authorResolvers.ts

@@ -0,0 +1,5 @@
+import { Author } from "src/entities";
+import type { AuthorResolvers } from "src/generated/graphql-types";
+import { entityResolver } from "src/resolvers/utils";
+
+export const authorResolvers: AuthorResolvers = { ...entityResolver(Author) };

package/templates/graphql/src/resolvers/author/saveAuthorMutation.test.ts

@@ -0,0 +1,13 @@
+import { saveAuthor } from "src/resolvers/author/saveAuthorMutation";
+import { makeRunInputMutation } from "src/resolvers/testUtils";
+
+describe("saveAuthor", () => {
+  it.withCtx("can create", async (ctx) => {
+    const result = await runSave(ctx, () => ({
+      firstName: "Test",
+    }));
+    expect(result).toBeDefined();
+  });
+});
+
+const runSave = makeRunInputMutation(saveAuthor);

package/templates/graphql/src/resolvers/author/saveAuthorMutation.ts

@@ -0,0 +1,9 @@
+import { Author } from "src/entities";
+import type { MutationResolvers } from "src/generated/graphql-types";
+import { saveEntity } from "src/resolvers/utils";
+
+export const saveAuthor: Pick<MutationResolvers, "saveAuthor"> = {
+  async saveAuthor(_, args, ctx) {
+    return { author: await saveEntity(ctx, Author, args.input) };
+  },
+};