create-ej-app 16.0.0 → 18.0.0

package/template/api/src/data-access/todo.ts

@@ -0,0 +1,142 @@
+/**
+ * Data-access layer for the `todos` resource.
+ *
+ * All direct database interactions for todos are encapsulated here.
+ * Route handlers call these functions and never import `db` directly,
+ * keeping database logic separate from HTTP concerns.
+ */
+import { asc, count, desc, eq, ilike, InferSelectModel, or } from 'drizzle-orm'
+import { db } from '~/db'
+import { todosTable } from '~/db/schema'
+import { SortOrderEnum } from '~/lib/util'
+
+type TodoType = InferSelectModel<typeof todosTable>
+
+/** Input parameters accepted by {@link getTodos}. */
+type GetTodosInput = {
+  page: number
+  limit: number
+  sortBy?: keyof TodoType
+  sortOrder?: SortOrderEnum
+  search?: string
+}
+
+/**
+ * Fetches a paginated, optionally sorted and searched list of todos.
+ *
+ * @returns A readonly tuple `[todos, total]`.
+ */
+export const getTodos = async ({
+  page,
+  limit,
+  sortBy = 'createdAt',
+  sortOrder = SortOrderEnum.DESC,
+  search
+}: GetTodosInput) => {
+  const where = search
+    ? or(
+        ilike(todosTable.title, `%${search}%`),
+        ilike(todosTable.content, `%${search}%`)
+      )
+    : undefined
+
+  const [results, total] = await Promise.all([
+    db.query.todosTable.findMany({
+      where,
+      limit,
+      offset: (page - 1) * limit,
+      orderBy: [
+        sortOrder === SortOrderEnum.ASC
+          ? asc(todosTable[sortBy])
+          : desc(todosTable[sortBy])
+      ]
+    }),
+    db
+      .select({
+        count: count()
+      })
+      .from(todosTable)
+      .where(where)
+  ])
+
+  return [results, total[0]?.count || 0] as const
+}
+
+/**
+ * Fetches a single todo by its UUID.
+ * @returns The todo row, or `undefined` if no match was found.
+ */
+export const getTodoById = async (id: string) => {
+  return await db.query.todosTable.findFirst({
+    where: eq(todosTable.id, id)
+  })
+}
+
+/** Input shape for creating a new todo. */
+type CreateTodoInput = {
+  title: string
+  content?: string | null
+}
+
+/**
+ * Inserts a new todo row and returns the generated UUID.
+ * @throws If the INSERT succeeds but no id is returned (should never happen).
+ */
+export const createTodo = async (input: CreateTodoInput) => {
+  const [todo] = await db
+    .insert(todosTable)
+    .values({
+      title: input.title,
+      content: input.content
+    })
+    .returning({
+      id: todosTable.id
+    })
+
+  if (!todo?.id) {
+    throw new Error('Failed to create todo or not returning id')
+  }
+
+  return todo.id
+}
+
+/** Input shape for partially updating an existing todo. */
+type UpdateTodoInput = {
+  id: string
+  title?: string
+  content?: string | null
+}
+
+/**
+ * Updates an existing todo by UUID.
+ * Only the fields present in `input` (besides `id`) are written.
+ * @returns `true` if a row was updated, `false` if the id was not found.
+ */
+export const updateTodoById = async (input: UpdateTodoInput) => {
+  const { id, ...rest } = input
+
+  const [todo] = await db
+    .update(todosTable)
+    .set(rest)
+    .where(eq(todosTable.id, id))
+    .returning({
+      id: todosTable.id
+    })
+
+  return !!todo?.id
+}
+
+/**
+ * Deletes a todo by UUID.
+ * @returns `true` if a row was deleted, `false` if the id was not found.
+ */
+export const deleteTodoById = async (id: string) => {
+  const [todo] = await db
+    .delete(todosTable)
+    .where(eq(todosTable.id, id))
+    .returning({
+      id: todosTable.id
+    })
+
+  return !!todo?.id
+}

package/template/api/src/db/fields.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared / reusable column definitions for Drizzle schemas.
+ *
+ * Centralising common column definitions here keeps every table
+ * consistent (same naming, same types, same defaults) and eliminates
+ * duplication across schema files.
+ */
+import { timestamp, uuid } from 'drizzle-orm/pg-core'
+
+export const commonFieldDefs = {
+  /**
+   * Standard UUID primary key column.
+   * The database generates a random UUID v4 by default.
+   */
+  id: uuid('id').primaryKey().defaultRandom(),
+
+  /**
+   * Factory for a single timezone-aware timestamp column.
+   * @param name – The underlying database column name.
+   */
+  date: (name: string) =>
+    timestamp(name, {
+      mode: 'date',
+      withTimezone: true
+    }),
+
+  /**
+   * Standard `created_at` / `updated_at` audit columns.
+   * Both default to the current time at insert; `updated_at` should
+   * be refreshed on every UPDATE (via application logic or a trigger).
+   */
+  dates: {
+    createdAt: timestamp('created_at', {
+      mode: 'date',
+      withTimezone: true
+    })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp('updated_at', {
+      mode: 'date',
+      withTimezone: true
+    })
+      .notNull()
+      .defaultNow()
+  }
+}

package/template/api/src/db/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Drizzle ORM database client.
+ *
+ * Creates and exports the singleton `db` instance that is used
+ * throughout the application to interact with the PostgreSQL database.
+ * The Bun-native SQL driver (`bun-sql`) is used for maximum performance.
+ *
+ * All table definitions from the schema are passed in so that Drizzle's
+ * relational query API (`db.query.*`) is fully typed.
+ */
+import { drizzle } from 'drizzle-orm/bun-sql'
+import { env } from '~/env'
+import * as schema from './schema'
+
+// Instantiate the Drizzle client with the validated DATABASE_URL and the
+// full schema so relational queries (db.query.todosTable.*) are available.
+export const db = drizzle(env.DATABASE_URL, {
+  schema: {
+    ...schema
+  }
+})

package/template/api/src/db/schema.ts

@@ -0,0 +1,19 @@
+/**
+ * Database schema definitions.
+ *
+ * All Drizzle table definitions live here and are imported by both the
+ * Drizzle client (`db/index.ts`) and the Drizzle Kit config
+ * (`drizzle.config.ts`) so that migrations stay in sync with the code.
+ */
+import { pgTable, text } from 'drizzle-orm/pg-core'
+import { commonFieldDefs } from './fields'
+
+/**
+ * `todos` table – stores individual todo items.
+ */
+export const todosTable = pgTable('todos', {
+  id: commonFieldDefs.id,
+  title: text('title').notNull(),
+  content: text('content'),
+  ...commonFieldDefs.dates
+})

package/template/api/src/env.ts

@@ -0,0 +1,24 @@
+/**
+ * Validated environment configuration.
+ *
+ * Uses @t3-oss/env-core together with Zod to parse and validate all
+ * required environment variables at startup.  The application will
+ * throw a descriptive error and refuse to start if any variable is
+ * missing or fails its validation rule.
+ */
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    PORT: z.coerce.number().int().positive(),
+    APP_ENV: z.enum(['development', 'staging', 'production']),
+    DATABASE_URL: z.url()
+  },
+
+  // Read all variables directly from process.env
+  runtimeEnv: process.env,
+
+  // Treat empty strings the same as missing (undefined) variables
+  emptyStringAsUndefined: true
+})

package/template/api/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Application entry point.
+ *
+ * Bootstraps the Elysia HTTP server, registers all route plugins,
+ * mounts the OpenAPI documentation UI, and starts
+ * listening on the port defined in the environment.
+ */
+import { openapi } from '@elysiajs/openapi'
+import { Elysia } from 'elysia'
+import { env } from './env'
+import { apiRoutes } from './routes'
+
+async function main() {
+  const app = new Elysia()
+
+  // Simple liveness probe used by load-balancers and container orchestrators
+  app.get('/health', () => 'OK', {
+    detail: {
+      description: 'Health check endpoint'
+    }
+  })
+
+  // Mount all /api/* routes (todo CRUD, etc.)
+  app.use(apiRoutes)
+
+  // Serve interactive OpenAPI docs at GET /docs
+  app.use(
+    openapi({
+      path: '/docs'
+    })
+  )
+
+  // Start the Bun HTTP server on the configured port
+  app.listen(env.PORT)
+
+  console.log(`🚀 Server ready at ${app.server?.hostname}:${app.server?.port}`)
+}
+
+main()

package/template/api/src/lib/util.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared utility types, enums, and reusable Zod schema fragments.
+ */
+import { z } from 'zod'
+
+/**
+ * Allowed values for the `sortOrder` query parameter.
+ * Maps to the SQL `ASC` / `DESC` keywords.
+ */
+export enum SortOrderEnum {
+  ASC = 'asc',
+  DESC = 'desc'
+}
+
+/**
+ * Reusable Zod schema fragment for cursor-less offset pagination.
+ *
+ * - `page`  – 1-based page number (defaults to 1)
+ * - `limit` – Number of items per page; clamped between 10 and 100 (defaults to 10)
+ *
+ * Spread this object into a `z.object({})` call to add pagination
+ * to any route's query schema.
+ */
+export const paginationSchema = {
+  page: z.coerce.number().int().positive().optional().default(1),
+  limit: z.coerce
+    .number()
+    .int()
+    .positive()
+    .min(10)
+    .max(100)
+    .optional()
+    .default(10)
+}
+
+/**
+ * Generates a reusable Zod schema fragment for sort parameters.
+ *
+ * @param keys – A non-empty tuple of the allowed `sortBy` field names for
+ *               the resource (e.g. `['title', 'createdAt', 'updatedAt']`).
+ * @returns An object with `sortOrder` and `sortBy` Zod validators that can
+ *          be spread into a `z.object({})` query schema.
+ *
+ * @example
+ * z.object({
+ *   ...paginationSchema,
+ *   ...getSortSchema(['title', 'createdAt', 'updatedAt'])
+ * })
+ */
+export const getSortSchema = <T extends string>(
+  keys: readonly [T, ...T[]]
+) => ({
+  sortOrder: z.enum(SortOrderEnum).optional(),
+  sortBy: z.enum(keys).optional()
+})

package/template/api/src/routes/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Top-level API router.
+ *
+ * All REST resources are registered here under the `/api` prefix and
+ * then mounted onto the root Elysia app in `src/index.ts`.
+ *
+ * Adding a new resource:
+ *   1. Create its router in `src/routes/<resource>/index.ts`.
+ *   2. Import it here and call `apiRoutes.use(yourRouter)`.
+ */
+import Elysia from 'elysia'
+import { todoRouter } from './todo'
+
+export const apiRoutes = new Elysia({
+  prefix: '/api'
+})
+
+apiRoutes.use(todoRouter)

package/template/api/src/routes/todo/index.ts

@@ -0,0 +1,241 @@
+/**
+ * Todos resource router.
+ *
+ * Defines the full CRUD REST API for the `todos` resource mounted at
+ * `/api/todos`.  Every handler delegates database work to the data-access
+ * layer (`~/data-access/todo`) and uses Zod schemas for request
+ * validation so that invalid input is rejected before it reaches the DB.
+ *
+ * Endpoints:
+ *   GET    /api/todos          – List todos with pagination, sorting & search
+ *   GET    /api/todos/:id      – Fetch a single todo by UUID
+ *   POST   /api/todos          – Create a new todo
+ *   PATCH  /api/todos/:id      – Partially update an existing todo
+ *   DELETE /api/todos/:id      – Delete a todo
+ */
+import Elysia, { status } from 'elysia'
+import { z } from 'zod'
+import {
+  createTodo,
+  deleteTodoById,
+  getTodoById,
+  getTodos,
+  updateTodoById
+} from '~/data-access/todo'
+import { getSortSchema, paginationSchema } from '~/lib/util'
+
+export const todoRouter = new Elysia({ prefix: '/todos' })
+
+/**
+ * GET /api/todos
+ * Returns a paginated, optionally sorted and searched list of todos.
+ * Supports full-text search across `title` and `content` columns.
+ */
+todoRouter.get(
+  '/',
+  async ({ query }) => {
+    try {
+      const [todos, count] = await getTodos(query)
+
+      return {
+        success: true,
+        data: {
+          page: query.page,
+          limit: query.limit,
+          hasMore: query.page * query.limit < count,
+          todos,
+          count
+        }
+      }
+    } catch (err) {
+      console.error('Error in GET /api/todos', err)
+      return status(500, {
+        success: false,
+        error: 'Something went wrong.'
+      })
+    }
+  },
+  {
+    query: z.object({
+      ...paginationSchema,
+      ...getSortSchema(['title', 'createdAt', 'updatedAt']),
+      search: z.string().trim().min(1).max(100).optional()
+    }),
+    detail: {
+      description: 'Get all todos',
+      tags: ['Todos']
+    }
+  }
+)
+
+/**
+ * GET /api/todos/:id
+ * Fetches a single todo by its UUID. Returns 404 if not found.
+ */
+todoRouter.get(
+  '/:id',
+  async ({ params }) => {
+    try {
+      const todo = await getTodoById(params.id)
+
+      if (!todo) {
+        return status(404, {
+          success: false,
+          error: 'Todo not found'
+        })
+      }
+
+      return {
+        success: true,
+        data: {
+          todo
+        }
+      }
+    } catch (err) {
+      console.error('Error in GET /api/todos/:id', err)
+      return status(500, {
+        success: false,
+        error: 'Something went wrong.'
+      })
+    }
+  },
+  {
+    // Validate that :id is a well-formed UUID before hitting the DB
+    params: z.object({
+      id: z.uuid()
+    }),
+    detail: {
+      description: 'Get a todo by id',
+      tags: ['Todos']
+    }
+  }
+)
+
+/**
+ * POST /api/todos
+ * Creates a new todo from the request body. Returns the generated UUID.
+ */
+todoRouter.post(
+  '/',
+  async ({ body }) => {
+    try {
+      const id = await createTodo(body)
+
+      return {
+        success: true,
+        data: {
+          id
+        }
+      }
+    } catch (err) {
+      console.error('Error in POST /api/todos', err)
+      return status(500, {
+        success: false,
+        error: 'Something went wrong.'
+      })
+    }
+  },
+  {
+    body: z.object({
+      title: z.string().trim().min(1).max(255),
+      content: z.string().trim().max(5000).nullish()
+    }),
+    detail: {
+      description: 'Create a new todo',
+      tags: ['Todos']
+    }
+  }
+)
+
+/**
+ * PATCH /api/todos/:id
+ * Partially updates a todo. All body fields are optional — only provided
+ * fields are written to the database. Returns 404 if the todo does not exist.
+ */
+todoRouter.patch(
+  '/:id',
+  async ({ params, body }) => {
+    try {
+      const success = await updateTodoById({
+        id: params.id,
+        ...body
+      })
+
+      if (!success) {
+        return status(404, {
+          success: false,
+          error: 'Todo not found'
+        })
+      }
+
+      return {
+        success: true,
+        data: {
+          id: params.id
+        }
+      }
+    } catch (err) {
+      console.error('Error in PATCH /api/todos/:id', err)
+      return status(500, {
+        success: false,
+        error: 'Something went wrong.'
+      })
+    }
+  },
+  {
+    params: z.object({
+      id: z.uuid()
+    }),
+    // Both fields are optional for a true partial-update (PATCH) semantic
+    body: z.object({
+      title: z.string().trim().min(1).max(255).optional(),
+      content: z.string().trim().max(5000).nullish()
+    }),
+    detail: {
+      description: 'Update a todo by id',
+      tags: ['Todos']
+    }
+  }
+)
+
+/**
+ * DELETE /api/todos/:id
+ * Permanently removes a todo by UUID. Returns 404 if not found.
+ */
+todoRouter.delete(
+  '/:id',
+  async ({ params }) => {
+    try {
+      const success = await deleteTodoById(params.id)
+
+      if (!success) {
+        return status(404, {
+          success: false,
+          error: 'Todo not found'
+        })
+      }
+
+      return {
+        success: true,
+        data: {
+          id: params.id
+        }
+      }
+    } catch (err) {
+      console.error('Error in DELETE /api/todos/:id', err)
+      return status(500, {
+        success: false,
+        error: 'Something went wrong.'
+      })
+    }
+  },
+  {
+    params: z.object({
+      id: z.uuid()
+    }),
+    detail: {
+      description: 'Delete a todo by id',
+      tags: ['Todos']
+    }
+  }
+)

package/template/api/src/scripts/seed.ts

@@ -0,0 +1,25 @@
+import { db } from '~/db'
+import { todosTable } from '~/db/schema'
+
+const seedData = async () => {
+  await db.insert(todosTable).values([
+    {
+      title: 'Buy groceries',
+      content: 'Milk, Bread, Butter, Jam'
+    },
+    {
+      title: 'Finish project',
+      content: 'Complete the frontend and backend integration'
+    }
+  ])
+}
+
+if (import.meta.main) {
+  try {
+    await seedData()
+  } catch (err) {
+    console.error('Error seeding data:', err)
+  } finally {
+    process.exit(0)
+  }
+}

package/template/api/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "allowJs": true,
+    "checkJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "noImplicitThis": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowUnreachableCode": false,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "incremental": true,
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx", "**/*.cjs", "**/*.mjs"],
+  "exclude": ["node_modules"]
+}

package/template/nextjs/drizzle.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'drizzle-kit'
+import { env } from '~/env'
+
+export default defineConfig({
+  schema: './src/db/schema.ts',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: env.DATABASE_URL
+  }
+})