oaspec/config

Types

Config

opaque </>

Configuration for oaspec code generation.

Opaque: external callers construct via new/6 and read fields via the accessors below. Mutators (with_mode, with_validate, with_output) live in this module too, so every change to a Config value goes through an explicit function.

pub opaque type Config

ConfigError

</>

Errors that can occur when loading config.

pub type ConfigError {
  FileNotFound(path: String)
  FileReadError(path: String, detail: String)
  ParseError(detail: String)
  MissingField(field: String)
  InvalidValue(field: String, detail: String)
}

Constructors

```
FileNotFound(path: String)
```

FileReadError(path: String, detail: String)

```
ParseError(detail: String)
```
```
MissingField(field: String)
```

InvalidValue(field: String, detail: String)

GenerateMode

</>

Generation mode.

pub type GenerateMode {
  Server
  Client
  Both
}

Constructors

```
Server
```
```
Client
```
```
Both
```

Values

error_to_string

</>

pub fn error_to_string(error: ConfigError) -> String

Convert config error to a human-readable string.

input

</>

pub fn input(cfg: Config) -> String

Path to the OpenAPI spec this config was built for.

load

</>

pub fn load(path: String) -> Result(Config, ConfigError)

Load config from a YAML file.

mode

</>

pub fn mode(cfg: Config) -> GenerateMode

Generation mode: server, client, or both.

new

</>

pub fn new(
  input input: String,
  output_server output_server: String,
  output_client output_client: String,
  package package: String,
  mode mode: GenerateMode,
  validate validate: Bool,
) -> Config

Construct a new Config from its six fields. Prefer load/1 in production code; new/6 is primarily for tests and ad-hoc tooling that assembles a config in memory.

output_client

</>

pub fn output_client(cfg: Config) -> String

Output directory for client-side generated files.

output_server

</>

pub fn output_server(cfg: Config) -> String

Output directory for server-side generated files.

package

</>

pub fn package(cfg: Config) -> String

Gleam package name (module prefix) for generated files.

parse_mode

</>

pub fn parse_mode(
  mode: String,
) -> Result(GenerateMode, ConfigError)

Parse a mode string into GenerateMode.

validate

</>

pub fn validate(cfg: Config) -> Bool

Whether guard-based runtime validation is enabled.

validate_output_package_match

</>

pub fn validate_output_package_match(
  config: Config,
) -> Result(Nil, ConfigError)

Validate that output directory basenames are valid Gleam module names usable as import roots.

Server output must end in <package> so generated imports such as import <package>/types resolve. Client output may end in either <package> (when client lives in its own project) or <package>_client (the new default since Issue #248 — both server and client share the same <dir> and need distinct basenames). Anything else is a misconfigured package/output mismatch the user should be told about.

with_mode

</>

pub fn with_mode(config: Config, mode: GenerateMode) -> Config

Apply CLI overrides to a config.

with_output

</>

pub fn with_output(
  config: Config,
  output: option.Option(String),
) -> Config

Apply output base directory override. Derives server/client paths as

/ and /_client in Both mode. In client-only mode the client path drops the suffix (Issue #262) so generated import <package>/... lines resolve.

The suffix decision reads config.mode at call time, so apply with_mode/2 before with_output/2 if both overrides are needed — otherwise the client path will reflect the previous mode’s default.

with_validate

</>

pub fn with_validate(config: Config, validate: Bool) -> Config

Apply validation mode override.