Config API Reference

Package Import

import {
  resolveConfigPath,
  parseConfig,
  checkRuntimeVersion,
  validateContext,
  validateBundleRestrictions,
  parseMainField,
  resolveMounts,
  detectNamespaceCollisions,
  loadExtensions,
  buildExtensionBindings,
  buildContextBindings,
  buildResolvers,
  loadProject,
  introspectHandler,
  marshalCliArgs,
} from '@rcrsr/rill-config';

The package path is @rcrsr/rill-config. All functions, types, and error classes documented here are public exports.

Process Isolation Contract

The library never calls process.exit(). It never writes to process.stdout or process.stderr. It never reads process.env. Callers supply all environment variables via the env parameter on each function that requires them.

.env Auto-Loading

The rill-run CLI loads .env automatically using dotenv before calling library functions. The library itself never calls dotenv.config().

Embedded callers must supply pre-resolved environment variables. Resolve your .env file before passing values to parseConfig or loadProject:

import { config } from 'dotenv';
import { loadProject } from '@rcrsr/rill-config';

// Caller resolves .env; library receives pre-resolved values
const env = config().parsed ?? {};

const result = await loadProject({
  configPath: './rill.config.json',
  env,
  rillVersion: '1.2.0',
});

Exported Functions

resolveConfigPath

resolveConfigPath(options: { configFlag?: string; cwd: string }): string

Locates the config file path. Walks ancestor directories from cwd when configFlag is absent.

Returns: Absolute path to the config file.

Throws: ConfigNotFoundError (EC-1) when no config file is found.

parseConfig

parseConfig(raw: string, env: Record<string, string>): RillConfigFile

Parses and validates a raw JSON config string. Substitutes ${VAR} references using env.

Returns: Validated RillConfigFile.

Throws: ConfigParseError (EC-2) on invalid JSON. Throws ConfigEnvError (EC-3) on missing env vars. Throws ConfigValidationError (EC-4) on invalid field types or orphaned config keys.

checkRuntimeVersion

checkRuntimeVersion(constraint: string, installedVersion: string): void

Validates that installedVersion satisfies the semver constraint from the config file.

Returns: void on success.

Throws: RuntimeVersionError (EC-5) on version mismatch or invalid semver constraint.

validateContext

validateContext(context: ContextBlock): Record<string, unknown>

Validates context values against their schema types.

Returns: Validated context values as a plain object.

Throws: ContextValidationError (EC-12) on missing values or type mismatches.

validateBundleRestrictions

validateBundleRestrictions(config: RillConfigFile): void

Checks that the config file contains no fields prohibited at bundle time.

Returns: void on success.

Throws: BundleRestrictionError (EC-14) when prohibited fields are present.

parseMainField

parseMainField(main: string): { filePath: string; handlerName?: string }

Parses the main field of the config file into its file path and optional handler name.

Returns: Object with filePath and optional handlerName.

Throws: ConfigValidationError (EC-4) on empty path or invalid format.

resolveMounts

resolveMounts(mounts: Record<string, string>): ResolvedMount[]

Validates and resolves raw mount definitions from the config into structured ResolvedMount objects.

Returns: Array of ResolvedMount objects.

Throws: MountValidationError (EC-6) on invalid segments or conflicting version constraints.

detectNamespaceCollisions

detectNamespaceCollisions(mounts: ResolvedMount[]): void

Checks for cross-package mount path collisions (exact match or prefix overlap).

Returns: void on success.

Throws: NamespaceCollisionError (EC-9/EC-13) when mount paths from different packages conflict or have prefix overlap.

loadExtensions

loadExtensions(
  mounts: ResolvedMount[],
  config: Record<string, Record<string, unknown>>
): Promise<LoadedProject>

Loads all extension packages listed in mounts and applies per-extension config.

Returns: Promise<LoadedProject> containing all loaded extension data.

Throws: ExtensionLoadError (EC-7) when a package is not found, has no manifest, or the factory fails. Throws ExtensionVersionError (EC-10) on version constraint mismatch.

buildExtensionBindings

buildExtensionBindings(extTree: Record<string, RillValue>): string

Generates rill source text that binds loaded extension values into the script namespace.

Returns: rill source string with extension bindings.

Throws: ExtensionBindingError when a value cannot be bound (e.g., invalid mount path or incompatible value shape).

buildContextBindings

buildContextBindings(
  schema: Record<string, ContextFieldSchema>,
  values: Record<string, unknown>
): string

Generates rill source text that binds context values into the script namespace.

Returns: rill source string with context variable bindings.

buildResolvers

buildResolvers(options: {
  extTree: Record<string, RillValue>;
  contextValues: Record<string, unknown>;
  extensionBindings: string;
  contextBindings: string;
  modulesConfig: Record<string, string>;
}): ResolverConfig

Assembles the final resolver configuration for the rill runtime.

Returns: ResolverConfig for use with createRuntimeContext.

loadProject

loadProject(options: {
  configPath: string;
  env: Record<string, string>;
  rillVersion: string;
}): Promise<ProjectResult>

Orchestrates the full project loading sequence: parse config, check version, load extensions, build bindings, and assemble resolvers.

Returns: Promise<ProjectResult>.

Throws: Any typed error from the functions it orchestrates (EC-1 through EC-14).

introspectHandler

introspectHandler(closure: ScriptCallable): HandlerIntrospection

Extracts parameter metadata from a rill script closure.

Returns: HandlerIntrospection with the closure’s parameter list.

marshalCliArgs

marshalCliArgs(
  args: Record<string, string>,
  params: ReadonlyArray<HandlerParam>
): Record<string, unknown>

Coerces CLI flag values to the types declared in the handler’s parameter list.

Returns: Coerced argument map with values typed per the parameter schema.

Throws: HandlerArgError (EC-16) on missing required param, coercion failure, or unknown flag.

Exported Types

RillConfigFile

The parsed and validated config file structure.

ExtensionsBlock

Extension configuration from the extensions section of the config file.

ContextBlock

Context schema and values from the context section of the config file.

ContextFieldSchema

Type descriptor for a single context field.

HostBlock

Host and runtime options from the host section of the config file.

ResolvedMount

Structured result of parsing a single mount entry.

LoadedProject

Result of loadExtensions. Contains all loaded extension data.

ResolverConfig

Resolver configuration for use with createRuntimeContext from @rcrsr/rill.

ProjectResult

Result of loadProject. Contains everything needed to run a rill script.

HandlerIntrospection

Introspection result for a script closure.

HandlerParam

Descriptor for a single handler parameter.

Typed Errors

All errors extend ConfigError, which extends Error with a code: string field.

class ConfigError extends Error {
  readonly code: string;
}

Catching Typed Errors

import {
  loadProject,
  ConfigError,
  ConfigNotFoundError,
  ConfigEnvError,
  ExtensionBindingError,
} from '@rcrsr/rill-config';

try {
  const result = await loadProject({ configPath, env, rillVersion });
} catch (err) {
  if (err instanceof ConfigNotFoundError) {
    console.error('No config file found:', err.message);
  } else if (err instanceof ConfigEnvError) {
    console.error('Missing environment variables:', err.message);
  } else if (err instanceof ExtensionBindingError) {
    console.error('Extension binding failed:', err.message);
  } else if (err instanceof ConfigError) {
    console.error(`Config error [${err.code}]:`, err.message);
  } else {
    throw err;
  }
}

See Also

• Config File Format — JSON structure, field reference, and env var substitution syntax
• CLI Tools — rill-run command and --config flag usage
• Host Integration — Using ResolverConfig with createRuntimeContext