feat!: introduce a new common runtime

packages/typescript-axios-runtime/package.json

@@ -29,6 +29,7 @@
     "test": "jest"
   },
   "dependencies": {
+    "@nahkies/typescript-common-runtime": "workspace:^",
     "qs": "^6.14.0",
     "tslib": "^2.8.1"
   },

packages/typescript-axios-runtime/src/main.ts

@@ -1,3 +1,11 @@
+import {
+  type Encoding,
+  requestBodyToUrlSearchParams,
+} from "@nahkies/typescript-common-runtime/request-bodies/url-search-params"
+import type {
+  HeaderParams,
+  QueryParams,
+} from "@nahkies/typescript-common-runtime/types"
 import axios, {
   AxiosHeaders,
   type AxiosInstance,
@@ -6,30 +14,12 @@ import axios, {
   type RawAxiosRequestHeaders,
 } from "axios"
 import qs from "qs"
-import {
-  type Encoding,
-  requestBodyToUrlSearchParams,
-} from "./request-bodies/url-search-params"
-
-export type QueryParams = {
-  [name: string]:
-    | string
-    | number
-    | number[]
-    | boolean
-    | string[]
-    | undefined
-    | null
-    | QueryParams
-    | QueryParams[]
-}
-
-export type HeaderParams =
-  | Record<string, string | number | boolean | undefined | null>
-  | [string, string | number | boolean | undefined | null][]
-  | Headers
 
-export type Server<T> = string & {__server__: T}
+export type {
+  HeaderParams,
+  QueryParams,
+  Server,
+} from "@nahkies/typescript-common-runtime/types"
 
 export interface AbstractAxiosConfig {
   axios?: AxiosInstance

packages/typescript-axios-runtime/tsconfig.json

@@ -5,5 +5,9 @@
     "rootDir": "./src"
   },
   "include": ["src/**/*"],
-  "references": []
+  "references": [
+    {
+      "path": "../typescript-common-runtime"
+    }
+  ]
 }

packages/typescript-common-runtime/README.md

@@ -0,0 +1,10 @@
+# @nahkies/typescript-common-runtime
+
+[![CI/CD](https://github.com/mnahkies/openapi-code-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/mnahkies/openapi-code-generator/actions?query=branch%3Amain+event%3Apush)
+[![npm](https://img.shields.io/npm/dm/%40nahkies%2Ftypescript-common-runtime.svg)](https://www.npmjs.com/package/@nahkies/typescript-common-runtime)
+
+This is a supporting package for code generated using [@nahkies/openapi-code-generator](https://www.npmjs.com/package/@nahkies/openapi-code-generator) shared across the typescript templates.
+
+You can [read the docs](https://openapi-code-generator.nahkies.co.nz/) to find out more!
+
+It's not intended by be used standalone. Similar in spirit to [tslib](https://www.npmjs.com/package/tslib)

packages/typescript-common-runtime/jest.config.js

@@ -0,0 +1,12 @@
+const base = require("../../jest.base")
+const {name: displayName} = require("./package.json")
+
+/**
+ * @type { import('@jest/types').Config.ProjectConfig }
+ */
+const config = {
+  ...base,
+  displayName,
+}
+
+module.exports = config

packages/typescript-common-runtime/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@nahkies/typescript-common-runtime",
+  "version": "0.22.0",
+  "description": "Runtime package for code generated by @nahkies/openapi-code-generator using the typescript templates",
+  "license": "MIT",
+  "author": {
+    "name": "Michael Nahkies",
+    "email": "[email protected]"
+  },
+  "homepage": "https://openapi-code-generator.nahkies.co.nz/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mnahkies/openapi-code-generator.git",
+    "directory": "packages/typescript-common-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/mnahkies/openapi-code-generator/issues"
+  },
+  "exports": {
+    "./errors": {
+      "require": "./dist/errors.js",
+      "import": "./dist/errors.js",
+      "types": "./dist/errors.d.ts"
+    },
+    "./validation": {
+      "require": "./dist/validation.js",
+      "import": "./dist/validation.js",
+      "types": "./dist/validation.d.ts"
+    },
+    "./types": {
+      "require": "./dist/types.js",
+      "import": "./dist/types.js",
+      "types": "./dist/types.d.ts"
+    },
+    "./request-bodies/url-search-params": {
+      "require": "./dist/request-bodies/url-search-params.js",
+      "import": "./dist/request-bodies/url-search-params.js",
+      "types": "./dist/request-bodies/url-search-params.d.ts"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf ./dist && rm tsconfig.tsbuildinfo",
+    "build": "tsc -p ./tsconfig.json",
+    "test": "jest"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "peerDependencies": {
+    "joi": "^17.13.3 || ^18.0.1",
+    "zod": "^3.25.74 || ^4.1.12"
+  },
+  "peerDependenciesMeta": {
+    "joi": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "jest": "^30.2.0",
+    "joi": "^18.0.2",
+    "typescript": "^5.9.3",
+    "zod": "^3.25.74"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "tsconfig.json"
+  ],
+  "keywords": [
+    "@nahkies/openapi-code-generator",
+    "openapi",
+    "runtime",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/typescript-common-runtime/src/errors.ts

@@ -0,0 +1,19 @@
+export enum RequestInputType {
+  RouteParam = "route params",
+  QueryString = "querystring",
+  RequestBody = "request body",
+  RequestHeader = "request header",
+}
+
+export abstract class AbstractRuntimeError extends Error {
+  protected constructor(
+    message: string,
+    cause: unknown,
+    public readonly phase:
+      | "request_validation"
+      | "request_handler"
+      | "response_validation",
+  ) {
+    super(message, {cause})
+  }
+}

packages/typescript-common-runtime/src/types.ts

@@ -0,0 +1,50 @@
+// from https://stackoverflow.com/questions/39494689/is-it-possible-to-restrict-number-to-a-certain-range
+type Enumerate<
+  N extends number,
+  Acc extends number[] = [],
+> = Acc["length"] extends N
+  ? Acc[number]
+  : Enumerate<N, [...Acc, Acc["length"]]>
+
+type IntRange<F extends number, T extends number> = F extends T
+  ? F
+  : Exclude<Enumerate<T>, Enumerate<F>> extends never
+    ? never
+    : Exclude<Enumerate<T>, Enumerate<F>> | T
+
+export type StatusCode1xx = IntRange<100, 199>
+export type StatusCode2xx = IntRange<200, 299>
+export type StatusCode3xx = IntRange<300, 399>
+export type StatusCode4xx = IntRange<400, 499>
+export type StatusCode5xx = IntRange<500, 599>
+export type StatusCode =
+  | StatusCode1xx
+  | StatusCode2xx
+  | StatusCode3xx
+  | StatusCode4xx
+  | StatusCode5xx
+
+export type Response<Status extends StatusCode, Type> = {
+  status: Status
+  body: Type
+}
+
+export type QueryParams = {
+  [name: string]:
+    | string
+    | number
+    | number[]
+    | boolean
+    | string[]
+    | undefined
+    | null
+    | QueryParams
+    | QueryParams[]
+}
+
+export type HeaderParams =
+  | Record<string, string | number | boolean | undefined | null>
+  | [string, string | number | boolean | undefined | null][]
+  | Headers
+
+export type Server<T> = string & {__server__: T}

packages/typescript-common-runtime/src/validation.ts

@@ -0,0 +1,18 @@
+export function isMatch(status: number, match: string) {
+  return (
+    (/^\d+$/.test(match) && String(status) === match) ||
+    (/^\d[xX]{2}$/.test(match) && String(status)[0] === match[0])
+  )
+}
+
+export function findMatchingSchema<Schema>(
+  status: number,
+  possibleResponses: [string, Schema][],
+): Schema | undefined {
+  for (const [match, schema] of possibleResponses) {
+    if (isMatch(status, match)) {
+      return schema
+    }
+  }
+  return undefined
+}

packages/typescript-common-runtime/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"],
+  "references": []
+}

packages/typescript-express-runtime/package.json

@@ -32,11 +32,6 @@
       "import": "./dist/joi.js",
       "types": "./dist/joi.d.ts"
     },
-    "./zod": {
-      "require": "./dist/zod.js",
-      "import": "./dist/zod.js",
-      "types": "./dist/zod.d.ts"
-    },
     "./zod-v3": {
       "require": "./dist/zod-v3.js",
       "import": "./dist/zod-v3.js",
@@ -55,6 +50,7 @@
     "test": "jest"
   },
   "dependencies": {
+    "@nahkies/typescript-common-runtime": "workspace:^",
     "tslib": "^2.8.1"
   },
   "peerDependencies": {

packages/typescript-express-runtime/src/errors.ts

@@ -1,20 +1,17 @@
-export enum RequestInputType {
-  RouteParam = "route params",
-  QueryString = "querystring",
-  RequestBody = "request body",
-  RequestHeader = "request header",
-}
+import {
+  AbstractRuntimeError,
+  RequestInputType,
+} from "@nahkies/typescript-common-runtime/errors"
+
+export {RequestInputType}
 
-export class ExpressRuntimeError extends Error {
+export class ExpressRuntimeError extends AbstractRuntimeError {
   private constructor(
     message: string,
     cause: unknown,
-    public readonly phase:
-      | "request_validation"
-      | "request_handler"
-      | "response_validation",
+    phase: "request_validation" | "request_handler" | "response_validation",
   ) {
-    super(message, {cause})
+    super(message, cause, phase)
   }
 
   static RequestError(

packages/typescript-express-runtime/src/joi.ts

@@ -1,3 +1,5 @@
+import {findMatchingSchema} from "@nahkies/typescript-common-runtime/validation"
+
 import type {Schema as JoiSchema} from "joi"
 import {ExpressRuntimeError, type RequestInputType} from "./errors"
 
@@ -45,12 +47,10 @@ export function responseValidationFactory(
   possibleResponses.sort((x, y) => (x[0] < y[0] ? -1 : 1))
 
   return (status: number, value: unknown) => {
-    for (const [match, schema] of possibleResponses) {
-      const isMatch =
-        (/^\d+$/.test(match) && String(status) === match) ||
-        (/^\d[xX]{2}$/.test(match) && String(status)[0] === match[0])
+    try {
+      const schema = findMatchingSchema(status, possibleResponses)
 
-      if (isMatch) {
+      if (schema) {
         const result = schema.validate(value)
 
         if (result.error) {
@@ -59,19 +59,20 @@ export function responseValidationFactory(
 
         return result.value
       }
-    }
 
-    // TODO: wrap thrown error.
-    if (defaultResponse) {
-      const result = defaultResponse.validate(value)
+      if (defaultResponse) {
+        const result = defaultResponse.validate(value)
+
+        if (result.error) {
+          throw result.error
+        }
 
-      if (result.error) {
-        throw result.error
+        return result.value
       }
 
-      return result.value
+      return value
+    } catch (err) {
+      throw ExpressRuntimeError.ResponseError(err)
     }
-
-    return value
   }
 }