CCM-12896: Automatically Generate Typescript Types and Validator Code from Event JSON Schemas (#138)

* CCM-12896: Generate JSON schemas during make config

* CCM-12896: Generate validation code from JSON schemas using ajv

* CCM-12896: Generate TypeScript types from JSON schemas using json-schema-to-typescript

Author: gareth-allan

.github/workflows/stage-2-test.yaml

@@ -57,7 +57,7 @@ jobs:
           npm ci
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          npm run generate-dependencies
           git diff --exit-code
   test-unit:
     name: "Unit tests"
@@ -71,7 +71,7 @@ jobs:
           npm ci
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          npm run generate-dependencies
       - name: "Run unit test suite"
         run: |
           make test-unit
@@ -104,7 +104,7 @@ jobs:
           npm ci
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          npm run generate-dependencies
       - name: "Run linting"
         run: |
           make test-lint
@@ -120,7 +120,7 @@ jobs:
           npm ci
       - name: "Generate dependencies"
         run: |
-          npm run generate-dependencies --workspaces --if-present
+          npm run generate-dependencies
       - name: "Run typecheck"
         run: |
           make test-typecheck

.github/workflows/stage-3-build.yaml

@@ -44,40 +44,3 @@ jobs:
         uses: ./.github/actions/build-docs
         with:
           version: "${{ inputs.version }}"
-
-
-
-  # artefact-1:
-  #   name: "Artefact 1"
-  #   runs-on: ubuntu-latest
-  #   timeout-minutes: 3
-  #   steps:
-  #     - name: "Checkout code"
-  #       uses: actions/checkout@v5
-  #     - name: "Build artefact 1"
-  #       run: |
-  #         echo "Building artefact 1 ..."
-  #     - name: "Check artefact 1"
-  #       run: |
-  #         echo "Checking artefact 1 ..."
-  #     - name: "Upload artefact 1"
-  #       run: |
-  #         echo "Uploading artefact 1 ..."
-  #         # Use either action/cache or action/upload-artifact
-  # artefact-n:
-  #   name: "Artefact n"
-  #   runs-on: ubuntu-latest
-  #   timeout-minutes: 3
-  #   steps:
-  #     - name: "Checkout code"
-  #       uses: actions/checkout@v5
-  #     - name: "Build artefact n"
-  #       run: |
-  #         echo "Building artefact n ..."
-  #     - name: "Check artefact n"
-  #       run: |
-  #         echo "Checking artefact n ..."
-  #     - name: "Upload artefact n"
-  #       run: |
-  #         echo "Uploading artefact n ..."
-  #         # Use either action/cache or action/upload-artifact

Makefile

@@ -12,6 +12,9 @@ quick-start: config clean build serve-docs # Quick start target to setup, build
 dependencies: # Install dependencies needed to build and test the project @Pipeline
 	# TODO: Implement installation of your project dependencies
 
+generate: # Generate any autogenerated output @Pipeline
+	npm run generate-dependencies
+
 build: # Build the project artefact @Pipeline
 	$(MAKE) -C docs build
 
@@ -30,12 +33,14 @@ clean:: # Clean-up project resources (main) @Operations
 	$(MAKE) -C src/eventcatalogasyncapiimporter clean
 	$(MAKE) -C src/eventcatalogasyncapiimporter clean-output
 	rm -f .version
-	# TODO: Implement project resources clean-up step
+	npm run clean
 
 config:: _install-dependencies version # Configure development environment (main) @Configuration
 	$(MAKE) -C docs install
 	$(MAKE) -C src/cloudevents install
 	$(MAKE) -C src/eventcatalogasyncapiimporter install
+	npm install
+	$(MAKE) generate
 
 serve-docs:
 	$(MAKE) -C docs s
@@ -50,5 +55,5 @@ ${VERBOSE}.SILENT: \
 	build \
 	clean \
 	config \
-	dependencies \
+	generate \
 	deploy \

README.md

@@ -76,6 +76,10 @@ Installation and configuration of the toolchain dependencies
 make config
 ```
 
+Note that the `make config` command will also build the flattened event schemas and auto-generate a Typescript
+type and JS validator code for each event. See the [typescript-schema-generator](src/typescript-schema-generator/)
+package for more details.
+
 ## Usage
 
 ### Testing

docs/Makefile

@@ -43,7 +43,6 @@ build: clean build-schemas copy-schema-docs copy-schema-yaml-docs copy-schemas b
 
 build-ci: build-schemas-ci copy-schema-docs copy-schema-yaml-docs copy-schemas build-eventcatalog build-docs show-build-output
 
-
 build-eventcatalog:
 	$(MAKE) build-eventcatalog-prereq
 	make -C $(EVENT_CAT_ROOT_DIR) build BASE_URL=$(EVENT_CAT_URL)

infrastructure/terraform/components/dl/pre.sh

@@ -6,6 +6,6 @@
 
 npm ci
 
-npm run generate-dependencies --workspaces --if-present
+npm run generate-dependencies
 
 npm run lambda-build --workspaces --if-present

lambdas/mesh-poll/package.json

@@ -1,12 +1,13 @@
 {
   "dependencies": {
-    "aws-lambda": "^1.0.7"
+    "aws-lambda": "^1.0.7",
+    "digital-letters-events": "^0.0.1"
   },
   "devDependencies": {
     "@tsconfig/node22": "^22.0.2",
     "@types/aws-lambda": "^8.10.155",
-    "@types/jest": "^30.0.0",
-    "jest": "^30.2.0",
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
     "jest-mock-extended": "^4.0.0",
     "typescript": "^5.9.3"
   },

lambdas/mesh-poll/src/__tests__/index.test.ts

@@ -1,17 +1,55 @@
 import type { Context } from 'aws-lambda';
 import { mockDeep } from 'jest-mock-extended';
+import { PDMResourceSubmitted } from 'digital-letters-events';
 import { handler } from '..';
 
+const context = mockDeep<Context>();
+const callback = jest.fn();
+
 describe('event-logging Lambda', () => {
   it('logs the input event and returns 200', async () => {
-    const event = { foo: 'bar' };
-    const context = mockDeep<Context>();
-    const callback = jest.fn();
+    const event: PDMResourceSubmitted = {
+      type: 'uk.nhs.notify.digital.letters.pdm.resource.submitted.v1',
+      source:
+        '/nhs/england/notify/staging/dev-647563337/data-plane/digitalletters/pdm',
+      dataschema:
+        'https://notify.nhs.uk/cloudevents/schemas/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-submitted-data.schema.json',
+      specversion: '1.0',
+      id: '0249e529-f947-4012-819e-b634eb71be79',
+      subject:
+        'customer/7ff8ed41-cd5f-20e4-ef4e-34f96d8cc8ac/75027ace-9b8c-bcfe-866e-6c24242cffc3/q58dnxk5e/4cbek805wwx/yiaw7bl0d/her/1ccb7eb8-c6fe-0a42-279a-2a0e48ff1ca9/zk',
+      time: '2025-11-21T16:01:52.268Z',
+      datacontenttype: 'application/json',
+      traceparent: '00-ee4790eb6821064c645406abe918b3da-3a4e6957ce2a15de-01',
+      tracestate: 'nisi quis',
+      partitionkey: 'customer-7ff8ed41',
+      recordedtime: '2025-11-21T16:01:53.268Z',
+      sampledrate: 1,
+      sequence: '00000000000350773861',
+      severitytext: 'INFO',
+      severitynumber: 2,
+      dataclassification: 'restricted',
+      dataregulation: 'ISO-27001',
+      datacategory: 'non-sensitive',
+      data: {
+        messageReference: 'incididunt Ut aute laborum',
+        senderId: 'officia voluptate culpa Ut dolor',
+        resourceId: 'a2bcbb42-ab7e-42b6-88d6-74f8d3ca4a09',
+        retryCount: 97_903_257,
+      },
+    };
+
     const result = await handler(event, context, callback);
 
     expect(result).toEqual({
       statusCode: 200,
       body: 'Event logged',
     });
   });
+
+  it('throws an error if an invalid event is provided', async () => {
+    const invalidEvent = { foo: 'bar' };
+
+    await expect(handler(invalidEvent, context, callback)).rejects.toThrow();
+  });
 });

lambdas/mesh-poll/src/index.ts

@@ -1,9 +1,55 @@
+/* eslint-disable no-console -- Allowing console logging as this is an example file. */
 // Replace me with the actual code for your Lambda function
 import { Handler } from 'aws-lambda';
+import { PDMResourceSubmitted } from 'digital-letters-events';
+import eventValidator from 'digital-letters-events/PDMResourceSubmitted.js';
 
-export const handler: Handler = async (event) => {
-  // eslint-disable-next-line no-console
+export const handler: Handler = async (event: PDMResourceSubmitted) => {
   console.log('Received event:', event);
+
+  // We can build a new PDMResourceSubmitted event object like this:
+  const pdmResourceSubmittedEvent: PDMResourceSubmitted = {
+    type: 'uk.nhs.notify.digital.letters.pdm.resource.submitted.v1',
+    source:
+      '/nhs/england/notify/staging/dev-647563337/data-plane/digitalletters/pdm',
+    dataschema:
+      'https://notify.nhs.uk/cloudevents/schemas/digital-letters/2025-10-draft/data/digital-letters-pdm-resource-submitted-data.schema.json',
+    specversion: '1.0',
+    id: '0249e529-f947-4012-819e-b634eb71be79',
+    subject:
+      'customer/7ff8ed41-cd5f-20e4-ef4e-34f96d8cc8ac/75027ace-9b8c-bcfe-866e-6c24242cffc3/q58dnxk5e/4cbek805wwx/yiaw7bl0d/her/1ccb7eb8-c6fe-0a42-279a-2a0e48ff1ca9/zk',
+    time: '2025-11-21T16:01:52.268Z',
+    datacontenttype: 'application/json',
+    traceparent: '00-ee4790eb6821064c645406abe918b3da-3a4e6957ce2a15de-01',
+    tracestate: 'nisi quis',
+    partitionkey: 'customer-7ff8ed41',
+    recordedtime: '2025-11-21T16:01:53.268Z',
+    sampledrate: 1,
+    sequence: '00000000000350773861',
+    severitytext: 'INFO',
+    severitynumber: 2,
+    dataclassification: 'restricted',
+    dataregulation: 'ISO-27001',
+    datacategory: 'non-sensitive',
+    data: {
+      messageReference: 'incididunt Ut aute laborum',
+      senderId: 'officia voluptate culpa Ut dolor',
+      resourceId: 'a2bcbb42-ab7e-42b6-88d6-74f8d3ca4a09',
+      retryCount: 97_903_257,
+    },
+  };
+
+  console.log('PDM resource submitted event:', pdmResourceSubmittedEvent);
+
+  // We can validate an event like this:
+  const isEventValid = eventValidator(event);
+  if (isEventValid) {
+    console.log('pdmResourceSubmittedEvent is valid!');
+  } else {
+    console.error('Validation failure!', eventValidator.errors);
+    throw new Error('Event validation failed');
+  }
+
   return {
     statusCode: 200,
     body: 'Event logged',

lambdas/mesh-poll/tsconfig.json

@@ -1,4 +1,8 @@
 {
+  "compilerOptions": {
+    "allowJs": true,
+    "isolatedModules": true
+  },
   "extends": "@tsconfig/node22/tsconfig.json",
   "include": [
     "src/**/*",