@optique/config 1.0.0-dev.921 → 1.0.1

package/dist/index.d.cts

@@ -19,36 +19,6 @@ interface ConfigMeta {
    */
   readonly configPath: string;
 }
-/**
- * Sets active config data for a context.
- * @internal
- */
-declare function setActiveConfig<T>(contextId: symbol, data: T): void;
-/**
- * Gets active config data for a context.
- * @internal
- */
-declare function getActiveConfig<T>(contextId: symbol): T | undefined;
-/**
- * Clears active config data for a context.
- * @internal
- */
-declare function clearActiveConfig(contextId: symbol): void;
-/**
- * Sets active config metadata for a context.
- * @internal
- */
-declare function setActiveConfigMeta<T>(contextId: symbol, meta: T): void;
-/**
- * Gets active config metadata for a context.
- * @internal
- */
-declare function getActiveConfigMeta<T>(contextId: symbol): T | undefined;
-/**
- * Clears active config metadata for a context.
- * @internal
- */
-declare function clearActiveConfigMeta(contextId: symbol): void;
 /**
  * Options for creating a config context.
  *
@@ -82,7 +52,10 @@ interface ConfigContextOptions<T> {
  */
 interface ConfigLoadResult<TConfigMeta = ConfigMeta> {
   /**
-   * Raw config data to validate against the schema.
+   * Raw config data to validate against the schema.  The value is always
+   * passed to the schema validator, even when `undefined` or `null`.
+   * To signal "no config found" without validation, return `undefined`
+   * or `null` directly from `load()` instead of wrapping it in an object.
    */
   readonly config: unknown;
   /**
@@ -117,15 +90,18 @@ interface ConfigContextRequiredOptions<TConfigMeta = ConfigMeta> {
    * returns the config data (or a Promise of it).  This allows full control
    * over file discovery, loading, merging, and error handling.
    *
-   * The returned data will be validated against the schema.
+   * The returned `ConfigLoadResult.config` is always validated against the
+   * schema.  Return `undefined` or `null` directly (not wrapped in a
+   * `ConfigLoadResult`) to signal that no config data was found;
+   * `bindConfig()` will fall back to its defaults.
    *
    * When `load` is provided, `getConfigPath` is ignored.
    *
    * @param parsed The result from the first parse pass.
-   * @returns Config data and metadata (config is validated by schema).
+   * @returns Config data and metadata, or `undefined`/`null` for no config.
    * @since 1.0.0
    */
-  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
+  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta> | undefined | null> | ConfigLoadResult<TConfigMeta> | undefined | null;
 }
 /**
  * A config context that provides configuration data via annotations.
@@ -150,13 +126,24 @@ interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<Confi
  *
  * The config context implements the `SourceContext` interface and can be used
  * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
- * *@optique/run* to provide configuration file support.
+ * *@optique/run* to provide configuration file support. Each runner call
+ * receives its own annotation snapshot, so the same `ConfigContext`
+ * instance can be reused safely across independent or concurrent runs.
+ * When calling `context.getAnnotations()` manually, omit the request for a
+ * phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
+ * snapshot, then thread the returned annotations into low-level APIs such
+ * as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
+ * `getDocPage()`. Calling `getAnnotations()` by itself does not affect
+ * later parses unless those returned annotations are explicitly threaded
+ * into a low-level API call.
  *
  * @template T The output type of the config schema.
  * @template TConfigMeta The metadata type for config sources.
  * @param options Configuration options including schema and optional file
  *   parser.
  * @returns A config context that can be used with `bindConfig()` and runners.
+ * @throws {TypeError} If `schema` is not a valid Standard Schema object.
+ * @throws {TypeError} If `fileParser` is provided but is not a function.
  * @since 0.10.0
  *
  * @example
@@ -214,6 +201,12 @@ interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
  * @param parser The parser to bind to config values.
  * @param options Binding options including context, key, and default.
  * @returns A new parser with config fallback behavior.
+ * @throws {TypeError} If `key` is not a property key or function.
+ * @throws {Error} If the inner parser's {@link Parser.validateValue} hook
+ *                 throws while re-validating a fallback value (a
+ *                 config-sourced value or the configured `default`) —
+ *                 the hook can run even when no CLI tokens are parsed
+ *                 (see issue #414).
  * @since 0.10.0
  *
  * @example
@@ -231,4 +224,4 @@ interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
  */
 declare function bindConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue, TConfigMeta>): Parser<M, TValue, TState>;
 //#endregion
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigLoadResult, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigLoadResult, ConfigMeta, bindConfig, createConfigContext };

package/dist/index.d.ts

@@ -19,36 +19,6 @@ interface ConfigMeta {
    */
   readonly configPath: string;
 }
-/**
- * Sets active config data for a context.
- * @internal
- */
-declare function setActiveConfig<T>(contextId: symbol, data: T): void;
-/**
- * Gets active config data for a context.
- * @internal
- */
-declare function getActiveConfig<T>(contextId: symbol): T | undefined;
-/**
- * Clears active config data for a context.
- * @internal
- */
-declare function clearActiveConfig(contextId: symbol): void;
-/**
- * Sets active config metadata for a context.
- * @internal
- */
-declare function setActiveConfigMeta<T>(contextId: symbol, meta: T): void;
-/**
- * Gets active config metadata for a context.
- * @internal
- */
-declare function getActiveConfigMeta<T>(contextId: symbol): T | undefined;
-/**
- * Clears active config metadata for a context.
- * @internal
- */
-declare function clearActiveConfigMeta(contextId: symbol): void;
 /**
  * Options for creating a config context.
  *
@@ -82,7 +52,10 @@ interface ConfigContextOptions<T> {
  */
 interface ConfigLoadResult<TConfigMeta = ConfigMeta> {
   /**
-   * Raw config data to validate against the schema.
+   * Raw config data to validate against the schema.  The value is always
+   * passed to the schema validator, even when `undefined` or `null`.
+   * To signal "no config found" without validation, return `undefined`
+   * or `null` directly from `load()` instead of wrapping it in an object.
    */
   readonly config: unknown;
   /**
@@ -117,15 +90,18 @@ interface ConfigContextRequiredOptions<TConfigMeta = ConfigMeta> {
    * returns the config data (or a Promise of it).  This allows full control
    * over file discovery, loading, merging, and error handling.
    *
-   * The returned data will be validated against the schema.
+   * The returned `ConfigLoadResult.config` is always validated against the
+   * schema.  Return `undefined` or `null` directly (not wrapped in a
+   * `ConfigLoadResult`) to signal that no config data was found;
+   * `bindConfig()` will fall back to its defaults.
    *
    * When `load` is provided, `getConfigPath` is ignored.
    *
    * @param parsed The result from the first parse pass.
-   * @returns Config data and metadata (config is validated by schema).
+   * @returns Config data and metadata, or `undefined`/`null` for no config.
    * @since 1.0.0
    */
-  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
+  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta> | undefined | null> | ConfigLoadResult<TConfigMeta> | undefined | null;
 }
 /**
  * A config context that provides configuration data via annotations.
@@ -150,13 +126,24 @@ interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<Confi
  *
  * The config context implements the `SourceContext` interface and can be used
  * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
- * *@optique/run* to provide configuration file support.
+ * *@optique/run* to provide configuration file support. Each runner call
+ * receives its own annotation snapshot, so the same `ConfigContext`
+ * instance can be reused safely across independent or concurrent runs.
+ * When calling `context.getAnnotations()` manually, omit the request for a
+ * phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
+ * snapshot, then thread the returned annotations into low-level APIs such
+ * as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
+ * `getDocPage()`. Calling `getAnnotations()` by itself does not affect
+ * later parses unless those returned annotations are explicitly threaded
+ * into a low-level API call.
  *
  * @template T The output type of the config schema.
  * @template TConfigMeta The metadata type for config sources.
  * @param options Configuration options including schema and optional file
  *   parser.
  * @returns A config context that can be used with `bindConfig()` and runners.
+ * @throws {TypeError} If `schema` is not a valid Standard Schema object.
+ * @throws {TypeError} If `fileParser` is provided but is not a function.
  * @since 0.10.0
  *
  * @example
@@ -214,6 +201,12 @@ interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
  * @param parser The parser to bind to config values.
  * @param options Binding options including context, key, and default.
  * @returns A new parser with config fallback behavior.
+ * @throws {TypeError} If `key` is not a property key or function.
+ * @throws {Error} If the inner parser's {@link Parser.validateValue} hook
+ *                 throws while re-validating a fallback value (a
+ *                 config-sourced value or the configured `default`) —
+ *                 the hook can run even when no CLI tokens are parsed
+ *                 (see issue #414).
  * @since 0.10.0
  *
  * @example
@@ -231,4 +224,4 @@ interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
  */
 declare function bindConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue, TConfigMeta>): Parser<M, TValue, TState>;
 //#endregion
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigLoadResult, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigLoadResult, ConfigMeta, bindConfig, createConfigContext };