openapi-contract-kit 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-09-11
+
+- Initial public release.
+- JSON OpenAPI 3.1 generator.
+- Generated schema and endpoint runtime validators.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ibeanu Hillary (ibeanuhillary@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# openapi-contract-kit
+
+JSON-first OpenAPI 3.1 contract generation and runtime validation for TypeScript applications.
+
+`openapi-contract-kit` reads a JSON OpenAPI document and generates:
+
+- TypeScript schema types
+- `ShapeOf*` compatibility aliases
+- Runtime schema makers
+- Request validators
+- Status-aware response validators
+- Standalone endpoint modules
+
+## Installation
+
+```bash
+npm install --save-dev openapi-contract-kit
+```
+
+## Quick start
+
+Create `openapi.config.json`:
+
+```json
+{
+  "specPath": "openapi.json",
+  "outDir": "src/api/generated",
+  "runtimeImport": "openapi-contract-kit/runtime"
+}
+```
+
+Add a generation script:
+
+```json
+{
+  "scripts": {
+    "openapi:generate": "openapi-contract-kit"
+  }
+}
+```
+
+Generate contracts:
+
+```bash
+npm run openapi:generate
+```
+
+## Generated validation
+
+Schema makers return a discriminated result:
+
+```ts
+const result = makeLoginRequest(input);
+
+if (!result.ok) {
+  console.error(result.errors);
+}
+```
+
+Validation errors contain a path, keyword, and message. Successful validation returns the original input without mutating or cloning it.
+
+## Supported input
+
+The generator supports JSON OpenAPI 3.1 documents with objects, primitive types, nullable values, arrays, enums, constants, unions, local `$ref` references, additional-property rules, string and numeric constraints, and email format validation.
+
+## Current limitations
+
+- YAML documents are not supported.
+- Remote `$ref` references are not supported.
+- Unsupported schema keywords fail generation.
+- Path and operation parameters are not currently generated.
+- Generated output is application-specific and should not be published with this package.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run pack:check
+```
+
+## Versioning
+
+The package follows semantic versioning. Changes to generated contracts, public exports, CLI flags, or validation behavior are documented in `CHANGELOG.md`.
+
+## License
+
+MIT

package/bin/openapi-contract-kit.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { main } from '../src/generator/generateOpenApiRuntime.mjs';
+
+await main();

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "openapi-contract-kit",
+  "version": "0.0.1",
+  "description": "Generate type-safe TypeScript contracts and runtime validators from JSON OpenAPI 3.1 documents.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.11"
+  },
+  "main": "./src/index.mjs",
+  "types": "./src/index.d.ts",
+  "bin": {
+    "openapi-contract-kit": "./bin/openapi-contract-kit.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.mjs"
+    },
+    "./runtime": {
+      "types": "./src/runtime.d.ts",
+      "import": "./src/runtime.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Clinsmann/openapi-contract-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Clinsmann/openapi-contract-kit/issues"
+  },
+  "homepage": "https://github.com/Clinsmann/openapi-contract-kit#readme",
+  "keywords": [
+    "openapi",
+    "openapi3",
+    "typescript",
+    "code-generation",
+    "runtime-validation",
+    "api-contracts",
+    "json-schema",
+    "cli"
+  ]
+}

package/src/generator/config.mjs

@@ -0,0 +1,92 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+
+const CONFIG_KEYS = new Set(['specPath', 'outDir', 'runtimeImport']);
+const FLAG_NAMES = new Map([
+  ['--config', 'configPath'],
+  ['--spec', 'specPath'],
+  ['--out', 'outDir'],
+  ['--runtime-import', 'runtimeImport'],
+]);
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function parseArguments(argv, cwd) {
+  const values = {};
+
+  for (let index = 0; index < argv.length; index += 2) {
+    const flag = argv[index];
+    const key = FLAG_NAMES.get(flag);
+    const value = argv[index + 1];
+
+    if (key === undefined) {
+      throw new Error(`Unknown argument "${flag}"`);
+    }
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new Error(`Missing value for "${flag}"`);
+    }
+
+    values[key] = isAbsolute(value) ? value : resolve(cwd, value);
+  }
+
+  return values;
+}
+
+function requirePath(config, key, configPath) {
+  const value = config[key];
+
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`Config "${configPath}" requires a non-empty "${key}"`);
+  }
+
+  return value;
+}
+
+export async function resolveGeneratorConfig({
+  argv = [],
+  cwd = process.cwd(),
+} = {}) {
+  const cli = parseArguments(argv, cwd);
+  const configPath = cli.configPath ?? resolve(cwd, 'openapi.config.json');
+  let config;
+
+  try {
+    config = JSON.parse(await readFile(configPath, 'utf8'));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Unable to read OpenAPI config "${configPath}": ${message}`
+    );
+  }
+
+  if (!isRecord(config)) {
+    throw new Error(`OpenAPI config "${configPath}" must contain an object`);
+  }
+
+  for (const key of Object.keys(config)) {
+    if (!CONFIG_KEYS.has(key)) {
+      throw new Error(`Unknown OpenAPI config key "${key}"`);
+    }
+  }
+
+  const configDirectory = dirname(configPath);
+  const resolveConfigPath = (key) => {
+    const value = requirePath(config, key, configPath);
+    return isAbsolute(value) ? value : resolve(configDirectory, value);
+  };
+
+  const runtimeImport =
+    cli.runtimeImport ?? requirePath(config, 'runtimeImport', configPath);
+  if (runtimeImport.includes('\\') || runtimeImport.startsWith('.')) {
+    throw new Error(`Config "${configPath}" requires a package runtimeImport`);
+  }
+
+  return {
+    configPath,
+    specPath: cli.specPath ?? resolveConfigPath('specPath'),
+    outDir: cli.outDir ?? resolveConfigPath('outDir'),
+    runtimeImport,
+  };
+}

package/src/generator/documents.mjs

@@ -0,0 +1,119 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, extname, resolve } from 'node:path';
+
+export function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function escapePointerSegment(segment) {
+  return segment.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+export function pointerChild(pointer, segment) {
+  return `${pointer}/${escapePointerSegment(String(segment))}`;
+}
+
+export function locationOf(documentPath, pointer) {
+  return `${documentPath}#${pointer}`;
+}
+
+export function requireRecord(value, location, label) {
+  if (!isRecord(value)) {
+    throw new Error(`${label} at ${location} must be an object`);
+  }
+
+  return value;
+}
+
+export class DocumentStore {
+  #documents = new Map();
+
+  async load(documentPath) {
+    const absolutePath = resolve(documentPath);
+    const existing = this.#documents.get(absolutePath);
+
+    if (existing !== undefined) {
+      return existing;
+    }
+
+    const pending = this.#read(absolutePath);
+    this.#documents.set(absolutePath, pending);
+    return pending;
+  }
+
+  async #read(documentPath) {
+    let source;
+
+    try {
+      source = await readFile(documentPath, 'utf8');
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Unable to read OpenAPI document "${documentPath}": ${message}`
+      );
+    }
+
+    try {
+      const extension = extname(documentPath).toLowerCase();
+      if (extension !== '.json') {
+        throw new Error('Only JSON OpenAPI documents are supported');
+      }
+      const value = JSON.parse(source);
+      return requireRecord(value, documentPath, 'OpenAPI document');
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Unable to parse OpenAPI document "${documentPath}": ${message}`
+      );
+    }
+  }
+
+  async resolveReference(reference, fromDocumentPath) {
+    if (typeof reference !== 'string' || reference.length === 0) {
+      throw new Error(`Invalid $ref at ${fromDocumentPath}`);
+    }
+    if (/^[A-Za-z][A-Za-z\d+.-]*:/u.test(reference)) {
+      throw new Error(`Remote $ref "${reference}" is unsupported`);
+    }
+
+    const hashIndex = reference.indexOf('#');
+    const filePart =
+      hashIndex === -1 ? reference : reference.slice(0, hashIndex);
+    const fragment = hashIndex === -1 ? '' : reference.slice(hashIndex + 1);
+    const documentPath =
+      filePart.length === 0
+        ? fromDocumentPath
+        : resolve(dirname(fromDocumentPath), decodeURIComponent(filePart));
+    const document = await this.load(documentPath);
+    const decodedFragment = decodeURIComponent(fragment);
+
+    if (decodedFragment.length > 0 && !decodedFragment.startsWith('/')) {
+      throw new Error(`Anchor $ref "${reference}" is unsupported`);
+    }
+
+    let value = document;
+    for (const encodedSegment of decodedFragment.split('/').slice(1)) {
+      const segment = encodedSegment
+        .replaceAll('~1', '/')
+        .replaceAll('~0', '~');
+      if (!isRecord(value) && !Array.isArray(value)) {
+        throw new Error(
+          `Unresolved $ref "${reference}" from ${fromDocumentPath}`
+        );
+      }
+      if (!Object.prototype.hasOwnProperty.call(value, segment)) {
+        throw new Error(
+          `Unresolved $ref "${reference}" from ${fromDocumentPath}`
+        );
+      }
+      value = Reflect.get(value, segment);
+    }
+
+    return {
+      canonicalKey: locationOf(documentPath, decodedFragment),
+      documentPath,
+      pointer: decodedFragment,
+      value,
+    };
+  }
+}

package/src/generator/emitEndpoints.mjs

@@ -0,0 +1,182 @@
+import { join } from 'node:path';
+
+function renderResponseType(responses) {
+  if (responses.length === 0) {
+    return 'never';
+  }
+
+  return responses
+    .map(({ schemaName, status }) => {
+      const bodyType = schemaName ?? 'null';
+      return `{ readonly status: ${status}; readonly body: ${bodyType} }`;
+    })
+    .join(' | ');
+}
+
+function renderStatusCases(responses) {
+  const lines = [];
+
+  for (const response of responses) {
+    lines.push(`    case ${response.status}: {`);
+    if (response.schemaName === null) {
+      lines.push(
+        `      if (parts.body !== null) {`,
+        `        return failure(['body'], 'nullBody', 'Expected a null response body');`,
+        `      }`,
+        `      return { ok: true, value: { status: ${response.status}, body: null } };`
+      );
+    } else {
+      lines.push(
+        `      const result = make${response.schemaName}(parts.body);`,
+        `      if (!result.ok) {`,
+        `        return result;`,
+        `      }`,
+        `      return { ok: true, value: { status: ${response.status}, body: result.value } };`
+      );
+    }
+    lines.push('    }');
+  }
+
+  lines.push(
+    `    default:`,
+    `      return failure(['status'], 'status', 'Undocumented response status');`
+  );
+  return lines.join('\n');
+}
+
+function emitEndpoint(operation, { outDir, runtimeImport }) {
+  const successResponses = operation.responses.filter(
+    (response) => response.isSuccess
+  );
+  const errorResponses = operation.responses.filter(
+    (response) => !response.isSuccess
+  );
+  const schemaNames = new Set();
+
+  if (operation.request.schemaName !== null) {
+    schemaNames.add(operation.request.schemaName);
+  }
+  for (const response of operation.responses) {
+    if (response.schemaName !== null) {
+      schemaNames.add(response.schemaName);
+    }
+  }
+
+  const sortedSchemaNames = [...schemaNames].sort();
+  const typeImport =
+    sortedSchemaNames.length === 0
+      ? ''
+      : `import type { ${sortedSchemaNames.join(', ')} } from '../quickpay-api';\n`;
+  const makerImports = sortedSchemaNames
+    .map((name) => `import { make${name} } from '../schemas/${name}';`)
+    .join('\n');
+  const requestType = operation.request.schemaName ?? 'null';
+  const requestMaker =
+    operation.request.schemaName === null
+      ? `export function makeRequest(input: unknown): Result<null> {
+  if (input !== null) {
+    return failure([], 'nullBody', 'Expected null');
+  }
+
+  return { ok: true, value: null };
+}`
+      : `export const makeRequest = make${operation.request.schemaName};`;
+
+  return `/**
+ * Generated by openapi-contract-kit.
+ * Do not edit directly.
+ */
+
+import type { Result, ValidationPath } from ${JSON.stringify(runtimeImport)};
+${typeImport}${makerImports}${makerImports.length > 0 ? '\n' : ''}
+export const URL = ${JSON.stringify(operation.path)};
+export const METHOD = ${JSON.stringify(operation.method)};
+export const OPERATION_ID = ${JSON.stringify(operation.operationId)};
+
+export type ShapeOfRequest = ${requestType};
+export type ShapeOfSuccessResponse = ${renderResponseType(successResponses)};
+export type ShapeOfErrorResponse = ${renderResponseType(errorResponses)};
+export type ShapeOfResponse = ShapeOfSuccessResponse | ShapeOfErrorResponse;
+
+type ResponseParts = {
+  readonly status: number;
+  readonly body: unknown;
+};
+
+function failure<T>(
+  path: ValidationPath,
+  keyword: string,
+  message: string
+): Result<T> {
+  return { ok: false, errors: [{ path, keyword, message }] };
+}
+
+function readResponse(input: unknown): ResponseParts | null {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    return null;
+  }
+  if (
+    !Object.prototype.hasOwnProperty.call(input, 'status') ||
+    !Object.prototype.hasOwnProperty.call(input, 'body')
+  ) {
+    return null;
+  }
+
+  const status = Reflect.get(input, 'status');
+  if (typeof status !== 'number' || !Number.isInteger(status)) {
+    return null;
+  }
+
+  return { status, body: Reflect.get(input, 'body') };
+}
+
+${requestMaker}
+
+function makeSuccessResponseResult(input: unknown): Result<ShapeOfSuccessResponse> {
+  const parts = readResponse(input);
+  if (parts === null) {
+    return failure([], 'response', 'Expected { status, body }');
+  }
+
+  switch (parts.status) {
+${renderStatusCases(successResponses)}
+  }
+}
+
+function makeErrorResponseResult(input: unknown): Result<ShapeOfErrorResponse> {
+  const parts = readResponse(input);
+  if (parts === null) {
+    return failure([], 'response', 'Expected { status, body }');
+  }
+
+  switch (parts.status) {
+${renderStatusCases(errorResponses)}
+  }
+}
+
+function makeAnyResponse(input: unknown): Result<ShapeOfResponse> {
+  const parts = readResponse(input);
+  if (parts === null) {
+    return failure([], 'response', 'Expected { status, body }');
+  }
+
+  return parts.status >= 200 && parts.status <= 299
+    ? makeSuccessResponseResult(input)
+    : makeErrorResponseResult(input);
+}
+
+export const makeResponse = Object.assign(makeAnyResponse, {
+  success: makeSuccessResponseResult,
+  error: makeErrorResponseResult,
+});
+`;
+}
+
+export function emitEndpointModules(model, config) {
+  return new Map(
+    model.operations.map((operation) => [
+      `endpoints/${operation.name}.ts`,
+      emitEndpoint(operation, config),
+    ])
+  );
+}