ARFA Generator

English

Русский

English

Русский

Appearance

Validation schema generation ​

createValidators accepts a list of files and project settings:

ts
import path from 'node:path';

import { createValidators } from '@arfa-tools/generator/api-contract-check/builder';

const { result, deps } = createValidators(
  [path.resolve('src/api/getUser.ts')],
  {
    tsconfigPath: 'tsconfig.json',
    requestDeclaration: 'TypeRequest',
    responseDeclaration: 'TypeResponse',
    getDegraded: (names) => console.log(names),
  }
);

Input files must declare both root types locally using type or interface. They do not have to be exported. Files that declare neither the request nor the response type are skipped. If only one of the two types is declared, or no contracts are found (including an empty file list), the call fails with an error.

ts
import type { TypeUser } from '../models/TypeUser';

type TypeRequest = { id: string; };

type TypeResponse = TypeUser;

Types can reference named imports, including import type, re-exports, and export * from barrel files. Path aliases from tsconfig.json are supported.

Arguments ​

The first argument is input; the second is an object containing the remaining fields listed below.

ts
input: Array<string>

Absolute paths of the input files

ts
tsconfigPath: string

The path to tsconfig.json on disk for resolving imports and path aliases. Relative paths are resolved from process.cwd()

ts
requestDeclaration: string

The name of the local request type declaration, such as TypeRequest

ts
responseDeclaration: string

The name of the local response type declaration, such as TypeResponse

ts
readFile?: (filePath: string) => string | undefined

Reads source files by absolute path. Returning undefined falls back to reading from disk

ts
getDegraded?: (names: Array<string>) => void

Receives sorted, unique names of properties or root declarations that fell back to any, without full paths. Called once per run if any fallbacks occurred

Result ​

ts
result: Array<{
  filePath: string;
  schema: {
    request: TypeSchema;
    response: TypeSchema;
  };
}>

Validation schemas for the contracts found. filePath is the absolute file path; schema.request and schema.response contain serializable request and response validation schemas

ts
deps: Record<string, Array<string>>

A reverse dependency map: imported file → affected entry files. All paths in keys and values are absolute

In-memory files ​

createValidators reads files from disk, from memory, or from both sources. Here is an example of reading contracts from memory:

ts
const entryFilePath = '/virtual/api/getUser.ts';

const memory: Record<string, string> = {
  [entryFilePath]: `
    import type { TypeUser } from '../models/TypeUser';

    type TypeRequest = { id: string };
    type TypeResponse = TypeUser;
  `,
  '/virtual/models/TypeUser.ts': 'export type TypeUser = { name: string };',
};

const { result } = createValidators(
  [entryFilePath], 
  { ...options, readFile: (filePath) => memory[filePath] }
);

This lets you perform multiple transformations and file operations (for example, deriving request and response types from OpenAPI while api-contract-check generates validation schemas on the fly) and save everything to disk in a single batch.

MIT License