Generator configuration
Live configuration surface for deterministic OpenAPI generation.
generateFromOpenAPI reads an OpenAPI 2 or 3 document, applies documented patch envelopes, and emits Effect-native operations. The generator is a source-traceable local adaptation governed by the runtime parity decision; it does not replace Alchemy’s runtime.
specPathstring
Path to the OpenAPI spec file
stringpatchDirstring
Directory containing *.patch.json files (can be same as spec dir or separate)
stringoutputDirstring
Output directory for generated files
stringimportPrefixstring
Import prefix for relative imports (e.g., ".." for operations/ -> src/)
stringclientImport?string
Client import path (e.g., "../client")
stringtraitsImport?string
Traits import path (e.g., "../traits" or "@distilled.cloud/core/traits")
stringsensitiveImport?string
Sensitive import path
stringerrorsImport?string
Errors import path (for operation-specific error imports)
stringincludeOperationErrors?boolean
Whether to include operation-specific error imports (default: true for Swagger, false for OAS 3.x)
booleanstatusToErrorClass?Record<string, string>
Status codes to error class name mapping (only used when includeOperationErrors=true)
Record<string, string>defaultErrorStatuses?Set<string>
Default error status codes to exclude from operation-specific errors
Set<string>skipDeprecated?boolean
Whether to skip deprecated operations (default: true)
booleanapiVersion?string
Default `api-version` for versioned APIs (e.g. Azure ARM). When set, the generator bakes `apiVersion` into each operation's `T.Http` trait (so the client injects `?api-version=<value>` automatically) and omits the `api-version` query parameter from the generated input schema.
stringMinimal invocation
import { generateFromOpenAPI } from "@kevinmichaelchen/distilled/openapi/generate";
const coverage = generateFromOpenAPI({
specPath: "specs/provider/specs/openapi.json",
patchDir: "patches",
outputDir: "src/operations",
});The generated directory should be committed and checked for drift after regeneration.
Output contract
Generation is all-or-nothing. Operation failures are collected and reported together, and the existing output directory is left intact. A successful run replaces the directory as one complete projection, so stale operation modules cannot survive a source change.
Every successful output contains:
- generated operation modules and an
index.tsbarrel with a provenance header; coverage.json, a deterministic record of the specification identity, applied patches, deprecations, unsupported operations, failures, and totals by HTTP method; and- query, path, and header traits that retain their exact wire names.
The function returns the same coverage value written to disk:
schemaVersion1
1spec{
readonly format: SpecVersion;
readonly title: string;
readonly version: string;
}
{
readonly format: SpecVersion;
readonly title: string;
readonly version: string;
}configuration{
readonly skipDeprecated: boolean;
}
{
readonly skipDeprecated: boolean;
}patches{
readonly applied: readonly string[];
readonly skipped: readonly string[];
}
{
readonly applied: readonly string[];
readonly skipped: readonly string[];
}operations{
readonly total: number;
readonly deprecated: number;
readonly skippedDeprecated: number;
readonly attempted: number;
readonly generated: number;
readonly failed: number;
readonly unsupported: number;
readonly byMethod: Record<
UppercaseHttpMethod,
{
readonly total: number;
readonly deprecated: number;
readonly skippedDeprecated: number;
readonly attempted: number;
readonly generated: number;
readonly failed: number;
}
>;
}
{
readonly total: number;
readonly deprecated: number;
readonly skippedDeprecated: number;
readonly attempted: number;
readonly generated: number;
readonly failed: number;
readonly unsupported: number;
readonly byMethod: Record<
UppercaseHttpMethod,
{
readonly total: number;
readonly deprecated: number;
readonly skippedDeprecated: number;
readonly attempted: number;
readonly generated: number;
readonly failed: number;
}
>;
}Treat a nonzero failure count as a broken generation run, not as partial success. Review coverage changes alongside generated source changes, especially when the upstream specification adds or removes operations.