feat: centralize code table management and enum generation

Refactors database lookup code tables to dynamically build caches and types directly from Prisma metadata.

- Move enum generation script to `src/db/codes/generate.ts`
- Implement dynamic cache manager in `src/db/codes/cache.ts` with a fail-fast Proxy to catch type sync errors
- Fetch active tables dynamically via Prisma DMMF models
- Initialize caches in `peachSync.ts` prior to sync loop
- Replace static Joi `.valid()` calls with a `.custom()` Proxy to ensure code tables evaluate at runtime
- Update unit tests and Jest mocks to support the central cache system

Signed-off-by: qhanson55 <quinn.hanson@gov.bc.ca>

Author: qhanson55

app/package.json

@@ -12,7 +12,7 @@
     "clean:all": "tsx ./deploy-utils.ts clean",
     "clean": "rimraf coverage dist sbin",
     "format": "prettier ./src --write",
-    "prisma:enums": "tsx ./src/db/utils/generate_enums.ts",
+    "prisma:enums": "tsx ./src/db/codes/generate.ts",
     "knex:local": "tsx ./node_modules/knex/bin/cli.js",
     "lint": "eslint",
     "lint:fix": "eslint --fix",

app/peachSync.ts

@@ -1,5 +1,6 @@
 import { syncPeachRecords } from './src/controllers/peach.ts';
 import { sendPermitUpdateNotifications } from './src/controllers/permit.ts';
+import { refreshCodeCaches } from './src/db/codes/cache.ts';
 import { getLogger } from './src/utils/log.ts';
 import { state } from './state.ts';
 
@@ -38,4 +39,17 @@ async function syncPeachToPcns() {
   }
 }
 
-void syncPeachToPcns();
+async function main() {
+  const cacheRefreshSucceeded = await refreshCodeCaches();
+  if (!cacheRefreshSucceeded) {
+    log.error('Fatal error in PEACH sync: failed to refresh code caches');
+    process.exitCode = 1;
+    return;
+  }
+  await syncPeachToPcns();
+}
+
+void main().catch((error) => {
+  log.error('Fatal error in PEACH sync', error);
+  process.exit(1);
+});

app/server.ts

@@ -5,8 +5,8 @@ import config from 'config';
 import { createServer } from 'node:http';
 
 import app from './app.ts';
+import { refreshCodeCaches } from './src/db/codes/cache.ts';
 import { checkDatabaseHealth, checkDatabaseSchema } from './src/db/utils/utils.ts';
-import { refreshCodeCaches } from './src/utils/cache/codes.ts';
 import getLogger from './src/utils/log.ts';
 import { state } from './state.ts';
 

app/src/controllers/generalProject.ts

@@ -2,7 +2,7 @@ import config from 'config';
 import { Prisma } from '@prisma/client';
 import { v4 as uuidv4 } from 'uuid';
 
-import { PermitStage, PermitState } from '../db/utils/codeEnums.ts';
+import { PermitStage, PermitState } from '../db/codes/enums.ts';
 import { transactionWrapper } from '../db/utils/transactionWrapper.ts';
 import {
   generateCreateStamps,

app/src/controllers/housingProject.ts

@@ -2,7 +2,7 @@ import config from 'config';
 import { Prisma } from '@prisma/client';
 import { v4 as uuidv4 } from 'uuid';
 
-import { PermitStage, PermitState } from '../db/utils/codeEnums.ts';
+import { PermitStage, PermitState } from '../db/codes/enums.ts';
 import { transactionWrapper } from '../db/utils/transactionWrapper.ts';
 import {
   generateCreateStamps,

app/src/controllers/peach.ts

@@ -1,4 +1,4 @@
-import { PermitStage, PermitState } from '../db/utils/codeEnums.ts';
+import { PermitStage, PermitState } from '../db/codes/enums.ts';
 import { transactionWrapper } from '../db/utils/transactionWrapper.ts';
 import { generateUpdateStamps } from '../db/utils/utils.ts';
 import { parsePeachRecords, summarizePeachRecord } from '../parsers/peach.ts';

app/src/controllers/permit.ts

@@ -2,7 +2,7 @@ import config from 'config';
 import { v4 as uuidv4 } from 'uuid';
 
 import { findPriorityPermitTracking } from './peach.ts';
-import { PermitStage } from '../db/utils/codeEnums.ts';
+import { PermitStage } from '../db/codes/enums.ts';
 import { transactionWrapper } from '../db/utils/transactionWrapper.ts';
 import { generateCreateStamps, generateUpdateStamps } from '../db/utils/utils.ts';
 import { summarizePeachRecord } from '../parsers/peach.ts';
@@ -44,6 +44,20 @@ import type {
   SearchPermitsOptions,
   SourceSystemKind
 } from '../types/index.ts';
+import { codeTable } from '../db/codes/cache.ts';
+
+function checkIfPeachIntegratedAuthType(sourceSystem: string, sourceSystemKinds: SourceSystemKind[]): boolean {
+  const sourceSystemKind = sourceSystemKinds.find((ssk) => ssk.integrated && ssk.sourceSystem === sourceSystem);
+  return !!sourceSystemKind;
+}
+
+const snapshotPermitStatus = (p: Partial<Permit>) => ({
+  state: p.state,
+  stage: p.stage,
+  decisionDate: p.decisionDate,
+  submittedDate: p.submittedDate,
+  statusLastChanged: p.statusLastChanged
+});
 
 export const deletePermitController = async (req: Request<{ permitId: string }>, res: Response) => {
   await transactionWrapper<void>(async (tx: PrismaTransactionClient) => {
@@ -187,18 +201,26 @@ export const sendPermitUpdateNotifications = async (
         });
     }
 
+    const stateDisplay = codeTable.PermitState.displays[permit.state];
+    const stageDisplay = codeTable.PermitStage.displays[permit.stage];
+
+    if (!stateDisplay || !stageDisplay) {
+      throw new Error(`Invalid permit.state: ${permit.state} or permit.stage: ${permit.stage}`);
+    }
+
     // Create update note for status change
     const permitNote = await createPermitNote(tx, {
       permitNoteId: uuidv4(),
       permitId: permit.permitId,
       note:
-        note ?? `This application is ${permit.state.toLocaleLowerCase()} in the ${permit.stage.toLocaleLowerCase()}.`,
+        note ?? `This application is ${stateDisplay.toLocaleLowerCase()} in the ${stageDisplay.toLocaleLowerCase()}.`,
       ...generateCreateStamps(undefined),
       updatedBy: null,
       updatedAt: null,
       deletedBy: null,
       deletedAt: null
     });
+
     // Add proponent update email to email jobs
     const primaryContact = project?.activity?.activityContact?.find(
       (ac) => ac.role === ActivityContactRole.PRIMARY
@@ -210,7 +232,7 @@ export const sendPermitUpdateNotifications = async (
     const isOnlyTemplate = permitNote.note.trim() === peachUpdateNotePlaceholder;
     const isFirstNote = !permit?.permitNote?.length;
 
-    const usePeachTemplate = isOnlyTemplate && isFirstNote && state.features.peach;
+    const useInitialPeachTemplate = isOnlyTemplate && isFirstNote && state.features.peach;
 
     if (
       project.projectId &&
@@ -223,7 +245,7 @@ export const sendPermitUpdateNotifications = async (
         dearName: primaryContact?.firstName ?? '',
         projectId: project.projectId,
         toEmails: [primaryContact.email],
-        emailTemplate: usePeachTemplate ? initialPeachPermitUpdateTemplate : permitNoteUpdateTemplate
+        emailTemplate: useInitialPeachTemplate ? initialPeachPermitUpdateTemplate : permitNoteUpdateTemplate
       });
     }
   };
@@ -240,19 +262,6 @@ export const sendPermitUpdateNotifications = async (
   }
 };
 
-function checkIfPeachIntegratedAuthType(sourceSystem: string, sourceSystemKinds: SourceSystemKind[]): boolean {
-  const sourceSystemKind = sourceSystemKinds.find((ssk) => ssk.integrated && ssk.sourceSystem === sourceSystem);
-  return !!sourceSystemKind;
-}
-
-const snapshotPermitStatus = (p: Partial<Permit>) => ({
-  state: p.state,
-  stage: p.stage,
-  decisionDate: p.decisionDate,
-  submittedDate: p.submittedDate,
-  statusLastChanged: p.statusLastChanged
-});
-
 export const upsertPermitController = async (req: Request<never, never, Permit>, res: Response) => {
   const response = await transactionWrapper<Permit>(async (tx: PrismaTransactionClient) => {
     const createStamps = generateCreateStamps(req.currentContext);

app/src/controllers/roadmap.ts

@@ -1,6 +1,6 @@
 import { v4 as uuidv4 } from 'uuid';
 
-import { PermitStage } from '../db/utils/codeEnums.ts';
+import { PermitStage } from '../db/codes/enums.ts';
 import { transactionWrapper } from '../db/utils/transactionWrapper';
 import { generateCreateStamps, generateNullDeleteStamps, generateNullUpdateStamps } from '../db/utils/utils';
 import { getObject } from '../services/coms';

app/src/db/codes/cache.ts

@@ -0,0 +1,60 @@
+import { transactionWrapper } from '../utils/transactionWrapper.ts';
+import { listAllCodeTables } from '../../services/code.ts';
+import { getLogger } from '../../utils/log.ts';
+import { CODE_TABLES } from './tables.ts';
+
+import type { CachedCodeTable, CodeCache, CodeTableName, CodeTablesResult } from './types.ts';
+import type { PrismaTransactionClient } from '../dataConnection.ts';
+
+const log = getLogger(module.filename);
+
+const toCachedCodeTable = (
+  rows: { code: string; display: string; definition: string | null }[] = []
+): CachedCodeTable => ({
+  codes: rows.map((r) => r.code),
+  displays: Object.fromEntries(rows.map((r) => [r.code, r.display])),
+  definitions: Object.fromEntries(
+    rows.filter((r): r is typeof r & { definition: string } => r.definition !== null).map((r) => [r.code, r.definition])
+  )
+});
+
+const buildCodeCache = (codeTables?: CodeTablesResult): CodeCache =>
+  Object.fromEntries(
+    CODE_TABLES.map(({ name }) => [name, toCachedCodeTable(codeTables?.[name as CodeTableName])])
+  ) as CodeCache;
+
+let codeCache: CodeCache = buildCodeCache();
+
+export const codeTable: CodeCache = new Proxy({} as Record<CodeTableName, CachedCodeTable>, {
+  get: (_target, prop: string) => {
+    const cachedTable = codeCache[prop as CodeTableName];
+
+    if (!cachedTable) {
+      throw new Error(
+        `Code table '${prop}' is missing from the cache. Run 'npm run prisma:enums' to ensure correct code enums.`
+      );
+    }
+
+    return cachedTable;
+  }
+});
+
+/**
+ * Pull the currently‑active codes from the DB and refresh the in‑memory arrays.
+ * @returns true if successful, false otherwise
+ */
+export async function refreshCodeCaches(): Promise<boolean> {
+  try {
+    const codeTables: CodeTablesResult = await transactionWrapper(async (tx: PrismaTransactionClient) => {
+      return await listAllCodeTables(tx);
+    });
+
+    codeCache = buildCodeCache(codeTables);
+
+    log.debug('Codes cache refreshed');
+    return true;
+  } catch (error) {
+    log.error('Codes cache refresh failed', error);
+    return false;
+  }
+}

app/src/db/utils/codeEnums.ts app/src/db/codes/enums.tsapp/src/db/utils/codeEnums.ts renamed to app/src/db/codes/enums.ts

@@ -1,6 +1,6 @@
 /**
  * AUTO-GENERATED FILE - DO NOT EDIT
- * @see app/src/db/utils/generate_enums.ts
+ * @see app/src/db/codes/generate.ts
  *
  * To update this file when updating or adding code tables to the db, run:
  * `npm run prisma:enums`