Merge branch 'main' into 53-add-soft-delete-middleware-and-drizzle-query-filters

Author: PAMulligan

.claude/skills/database-design/SKILL.md

@@ -194,13 +194,13 @@ export const users = pgTable(
       .defaultNow()
       .notNull()
       .$onUpdate(() => new Date()),
-    // Soft-delete marker — only emitted when `database.softDeleteDefault` is
-    // true in pipeline.config.json. Null = active; a timestamp = soft-deleted.
+    // Soft delete: NULL = live, timestamp = deleted. Added to every table when
+    // `database.softDeleteDefault` is true in pipeline.config.json (Step 6a).
     deletedAt: timestamp('deleted_at', { withTimezone: true }),
   },
   (table) => [
     uniqueIndex('users_email_idx').on(table.email),
-    // Partial index keeps the common "active rows" lookups fast.
+    // Partial index keeps lookups of live rows fast even with many deleted rows.
     index('users_deleted_at_idx').on(table.deletedAt),
   ],
 );
@@ -355,135 +355,102 @@ export const orderItemsRelations = relations(orderItems, ({ one }) => ({
 }));
 ```
 
-### Step 6.5 -- Soft Delete Columns & Helpers (when enabled)
+### Step 6a -- Soft Delete Columns (when enabled)
 
-Gate this step on `pipeline.config.json` -> `database.softDeleteDefault`. When it
-is `true` (the default), every table that represents a deletable resource gets a
-nullable `deletedAt` column and the build emits a shared soft-delete helper
-module. Skip this step entirely when `softDeleteDefault` is `false`.
+Read `database.softDeleteDefault` from `.claude/pipeline.config.json`. When it is
+`true` (the default), **every** generated table gets a nullable `deleted_at`
+column plus an index, and a shared soft-delete helper module is generated.
 
 ```typescript
-// Read the flag from pipeline.config.json before generating schemas
-import { readFile } from 'fs/promises';
-import path from 'path';
+// Add to the column block of every pgTable (after createdAt/updatedAt):
+deletedAt: timestamp('deleted_at', { withTimezone: true }),
+```
 
-const pipelineConfig = JSON.parse(
-  await readFile(
-    path.join(process.cwd(), '.claude', 'pipeline.config.json'),
-    'utf-8',
-  ),
-);
-const softDeleteEnabled: boolean = pipelineConfig.database?.softDeleteDefault ?? false;
+```typescript
+// Add to the index block of every table:
+index('<table>_deleted_at_idx').on(table.deletedAt),
 ```
 
-**1. Add the column to each soft-deletable table.** Use a nullable timestamp
-(no default) plus a supporting index — see the `deletedAt` column and
-`users_deleted_at_idx` in the Users example above. Pure join/pivot tables
-(e.g. `order_items`) are usually hard-deleted with their parent and can be left
-out.
+`deleted_at` is intentionally **nullable with no default** — `NULL` means the row
+is live, a timestamp means it was soft-deleted. Do not add `.notNull()` or a
+default. Join/pivot tables that are physically deleted via `ON DELETE CASCADE`
+(e.g. `order_items`) may opt out — only add `deleted_at` to top-level resources.
 
-**2. Generate the shared helper module** at `api/src/db/soft-delete.ts`. This is
-the single source of truth for the soft-delete query filter and write helpers:
+Then generate the shared helper module once per project. It provides the query
+filter and the `softDelete()` mutation consumed by the service layer in Phase 3
+(`route-generation`):
 
 ```typescript
 // api/src/db/soft-delete.ts
-import {
-  and,
-  eq,
-  isNull,
-  type Column,
-  type SQL,
-  type TablesRelationalConfig,
-} from 'drizzle-orm';
+import { and, eq, isNull, type SQL } from 'drizzle-orm';
 import type {
   PgColumn,
   PgDatabase,
   PgQueryResultHKT,
   PgTable,
   PgUpdateSetSource,
 } from 'drizzle-orm/pg-core';
+import { z } from 'zod';
 
-export interface SoftDeletable {
-  deletedAt: Column;
+export interface SoftDeleteColumns {
+  id: PgColumn;
+  deletedAt: PgColumn;
 }
+export type SoftDeleteTable = PgTable & SoftDeleteColumns;
 
-export type SoftDeletableTable = PgTable & SoftDeletable & { id: PgColumn };
-
-/** WHERE filter that hides soft-deleted rows (`deleted_at IS NULL`). */
-export function notDeleted(table: SoftDeletable): SQL {
+/** `WHERE deleted_at IS NULL` — add to the where clause of every read query. */
+export function notDeleted(table: SoftDeleteColumns): SQL {
   return isNull(table.deletedAt);
 }
 
-/**
- * Hide soft-deleted rows unless an admin explicitly asks for them via
- * `?include_deleted=true`. An optional `extra` clause is AND-ed in.
- */
-export function withSoftDeleteFilter(
-  table: SoftDeletable,
-  includeDeleted: boolean,
-  extra?: SQL,
+/** AND the not-deleted filter with extra conditions (undefined ones ignored). */
+export function withNotDeleted(
+  table: SoftDeleteColumns,
+  ...conditions: Array<SQL | undefined>
 ): SQL | undefined {
-  if (includeDeleted) {
-    return extra;
-  }
-  const active = notDeleted(table);
-  return extra ? and(active, extra) : active;
+  return and(notDeleted(table), ...conditions);
 }
 
-/** Soft-delete one row by id: stamps `deletedAt` instead of removing it. */
-export function softDelete<
-  TQueryResult extends PgQueryResultHKT,
-  TFullSchema extends Record<string, unknown>,
-  TSchema extends TablesRelationalConfig,
->(db: PgDatabase<TQueryResult, TFullSchema, TSchema>, table: SoftDeletableTable, id: string) {
-  return db
-    .update(table)
-    .set({ deletedAt: new Date() } as PgUpdateSetSource<SoftDeletableTable>)
-    .where(eq(table.id, id));
+/** Build a where clause honouring the `?include_deleted=true` admin flag. */
+export function softDeleteFilter(
+  table: SoftDeleteColumns,
+  includeDeleted: boolean,
+  ...conditions: Array<SQL | undefined>
+): SQL | undefined {
+  return includeDeleted
+    ? and(...conditions)
+    : and(notDeleted(table), ...conditions);
 }
 
-/** Restore a soft-deleted row by clearing `deletedAt`. */
-export function restore<
-  TQueryResult extends PgQueryResultHKT,
-  TFullSchema extends Record<string, unknown>,
-  TSchema extends TablesRelationalConfig,
->(db: PgDatabase<TQueryResult, TFullSchema, TSchema>, table: SoftDeletableTable, id: string) {
-  return db
+/** Stamp deleted_at instead of deleting. Returns rows affected (0 or 1). */
+export async function softDelete<TTable extends SoftDeleteTable>(
+  db: PgDatabase<PgQueryResultHKT>,
+  table: TTable,
+  id: string | number,
+): Promise<number> {
+  const result = await db
     .update(table)
-    .set({ deletedAt: null } as PgUpdateSetSource<SoftDeletableTable>)
-    .where(eq(table.id, id));
+    .set({ deletedAt: new Date() } as unknown as PgUpdateSetSource<TTable>)
+    .where(and(eq(table.id, id), notDeleted(table)))
+    .returning({ id: table.id });
+  return result.length;
 }
-```
 
-**3. Use the helpers in read and delete routes.** `route-generation` (Phase 3)
-consumes these helpers so generated handlers filter deleted rows by default and
-expose `?include_deleted=true` on admin/list endpoints:
-
-```typescript
-import { eq } from 'drizzle-orm';
-import { db } from '../db';
-import { users } from '../db/schema';
-import { restore, softDelete, withSoftDeleteFilter } from '../db/soft-delete';
-
-// GET /users — active rows only; ?include_deleted=true reveals soft-deleted rows
-const includeDeleted = c.req.query('include_deleted') === 'true';
-const rows = await db
-  .select()
-  .from(users)
-  .where(withSoftDeleteFilter(users, includeDeleted));
-
-// DELETE /users/:id — soft delete instead of a hard DELETE
-const [deleted] = await softDelete(db, users, c.req.param('id')).returning();
-if (!deleted) return c.json({ error: 'User not found' }, 404);
-return c.json({ message: 'User deleted' });
-
-// POST /users/:id/restore — admin un-delete
-const [restored] = await restore(db, users, c.req.param('id')).returning();
+/** Query-param schema: `?include_deleted=true` for admin endpoints. */
+export const includeDeletedQuerySchema = z.object({
+  include_deleted: z
+    .enum(['true', 'false'])
+    .optional()
+    .default('false')
+    .transform((value) => value === 'true'),
+});
+export type IncludeDeletedQuery = z.infer<typeof includeDeletedQuerySchema>;
 ```
 
-**4. Keep `deletedAt` out of write validators.** When generating Zod schemas in
-Step 8, `deletedAt` is server-managed: omit it from insert/update schemas exactly
-like `id`, `createdAt`, and `updatedAt`.
+This module is also shipped as a template snippet
+(`templates/snippets/shared/src/db/soft-delete.ts`) and is copied automatically by
+`setup-project.sh`. When `softDeleteDefault` is `false`, omit the `deleted_at`
+columns and do not generate this module.
 
 ### Step 7 -- Generate Barrel Export
 
@@ -547,6 +514,7 @@ export type UpdateUser = z.infer<typeof updateUserSchema>;
 import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
 import { z } from 'zod';
 import { books } from '../db/schema/books';
+import { includeDeletedQuerySchema } from '../db/soft-delete';
 
 export const insertBookSchema = createInsertSchema(books, {
   title: z.string().min(1).max(500),
@@ -564,15 +532,19 @@ export const selectBookSchema = createSelectSchema(books);
 
 export const updateBookSchema = insertBookSchema.partial();
 
-// Query params for list endpoint
-export const listBooksQuerySchema = z.object({
-  page: z.coerce.number().int().min(1).default(1),
-  limit: z.coerce.number().int().min(1).max(100).default(20),
-  search: z.string().optional(),
-  author: z.string().optional(),
-  sortBy: z.enum(['title', 'author', 'price', 'createdAt']).default('createdAt'),
-  sortOrder: z.enum(['asc', 'desc']).default('desc'),
-});
+// Query params for list endpoint.
+// `.merge(includeDeletedQuerySchema)` adds the `?include_deleted=true` flag used
+// by admin endpoints to also return soft-deleted rows. Defaults to false.
+export const listBooksQuerySchema = z
+  .object({
+    page: z.coerce.number().int().min(1).default(1),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    search: z.string().optional(),
+    author: z.string().optional(),
+    sortBy: z.enum(['title', 'author', 'price', 'createdAt']).default('createdAt'),
+    sortOrder: z.enum(['asc', 'desc']).default('desc'),
+  })
+  .merge(includeDeletedQuerySchema);
 
 export type InsertBook = z.infer<typeof insertBookSchema>;
 export type SelectBook = z.infer<typeof selectBookSchema>;
@@ -642,7 +614,8 @@ CREATE TABLE IF NOT EXISTS "users" (
   "name" text NOT NULL,
   "role" "user_role" DEFAULT 'customer' NOT NULL,
   "created_at" timestamp with time zone DEFAULT now() NOT NULL,
-  "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "deleted_at" timestamp with time zone
 );
 
 CREATE TABLE IF NOT EXISTS "books" (
@@ -654,7 +627,8 @@ CREATE TABLE IF NOT EXISTS "books" (
   "stock" integer DEFAULT 0 NOT NULL,
   "description" text,
   "created_at" timestamp with time zone DEFAULT now() NOT NULL,
-  "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "deleted_at" timestamp with time zone
 );
 
 CREATE TABLE IF NOT EXISTS "orders" (
@@ -663,7 +637,8 @@ CREATE TABLE IF NOT EXISTS "orders" (
   "status" "order_status" DEFAULT 'pending' NOT NULL,
   "total" numeric(10, 2) NOT NULL,
   "created_at" timestamp with time zone DEFAULT now() NOT NULL,
-  "updated_at" timestamp with time zone DEFAULT now() NOT NULL
+  "updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+  "deleted_at" timestamp with time zone
 );
 
 CREATE TABLE IF NOT EXISTS "order_items" (
@@ -681,6 +656,11 @@ CREATE INDEX IF NOT EXISTS "books_author_idx" ON "books" USING btree ("author");
 CREATE INDEX IF NOT EXISTS "orders_user_id_idx" ON "orders" USING btree ("user_id");
 CREATE INDEX IF NOT EXISTS "order_items_order_id_idx" ON "order_items" USING btree ("order_id");
 CREATE INDEX IF NOT EXISTS "order_items_book_id_idx" ON "order_items" USING btree ("book_id");
+
+-- Soft-delete indexes (generated when database.softDeleteDefault is true)
+CREATE INDEX IF NOT EXISTS "users_deleted_at_idx" ON "users" USING btree ("deleted_at");
+CREATE INDEX IF NOT EXISTS "books_deleted_at_idx" ON "books" USING btree ("deleted_at");
+CREATE INDEX IF NOT EXISTS "orders_deleted_at_idx" ON "orders" USING btree ("deleted_at");
 ```
 
 ### Step 10 -- Install Dependencies
@@ -694,7 +674,8 @@ cd api && pnpm add -D drizzle-kit drizzle-zod
 
 | Artifact | Location | Description |
 |---|---|---|
-| Schema files | `api/src/db/schema/*.ts` | One Drizzle pgTable per model |
+| Schema files | `api/src/db/schema/*.ts` | One Drizzle pgTable per model (incl. `deleted_at`) |
+| Soft-delete helper | `api/src/db/soft-delete.ts` | `notDeleted`/`softDelete` filters (when `softDeleteDefault`) |
 | Enum definitions | `api/src/db/schema/enums.ts` | PostgreSQL enum types |
 | Schema barrel | `api/src/db/schema/index.ts` | Re-exports all schemas |
 | Soft-delete helpers | `api/src/db/soft-delete.ts` | `notDeleted`, `withSoftDeleteFilter`, `softDelete`, `restore` (when `softDeleteDefault`) |
@@ -721,5 +702,5 @@ cd api && pnpm add -D drizzle-kit drizzle-zod
 - **Zod inference from Drizzle**: Single source of truth -- change the Drizzle schema, the Zod validators follow automatically.
 - **UUID primary keys**: Default for all tables. Avoids sequential ID enumeration attacks and works well in distributed systems.
 - **Soft timestamps**: `createdAt` and `updatedAt` on every table. `$onUpdate` handles automatic timestamp refresh.
-- **Soft deletes by default**: when `database.softDeleteDefault` is true, deletable tables get a nullable `deletedAt` column and a shared `soft-delete.ts` helper module instead of issuing hard `DELETE`s. Reads filter with `notDeleted`/`withSoftDeleteFilter`, deletes stamp `deletedAt` via `softDelete`, and `?include_deleted=true` exposes deleted rows to admin endpoints. Set the flag to `false` to opt back into hard deletes.
+- **Soft deletes by default**: When `database.softDeleteDefault` is true, tables carry a nullable `deleted_at` column and rows are never physically removed. Reads filter `WHERE deleted_at IS NULL` via the generated `soft-delete.ts` helper, and DELETE handlers call `softDelete()`. Admin endpoints can opt back in to deleted rows with `?include_deleted=true`. See [route-generation](../route-generation/SKILL.md) for the handler pattern.
 - **snake_case columns**: PostgreSQL convention. Drizzle maps to camelCase in TypeScript automatically.