@optique/core 1.0.0-dev.429 → 1.0.0-dev.432

package/dist/context.d.cts

@@ -46,6 +46,10 @@ type ParserValuePlaceholder = {
  * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
  *   is determined by a CLI option)
  *
+ * Contexts may optionally implement `Disposable` or `AsyncDisposable` for
+ * cleanup.  When present, `runWith()` and `runWithSync()` call the dispose
+ * method in a `finally` block after parsing completes.
+ *
  * @template TRequiredOptions Additional options that `runWith()` must provide
  *   when this context is used. Use `void` (the default) for contexts that
  *   don't require extra options. Use {@link ParserValuePlaceholder} in option
@@ -88,7 +92,7 @@ interface SourceContext<TRequiredOptions = void> {
    * Type-level marker for the required options. Not used at runtime.
    * @internal
    */
-  readonly _requiredOptions?: TRequiredOptions;
+  readonly $requiredOptions?: TRequiredOptions;
   /**
    * Get annotations to inject into parsing.
    *
@@ -103,10 +107,24 @@ interface SourceContext<TRequiredOptions = void> {
    * @param parsed Optional parsed result from a previous parse pass.
    *               Static contexts can ignore this parameter.
    *               Dynamic contexts use this to extract necessary data.
+   * @param options Optional context-required options provided by the caller
+   *               of `runWith()`. These are the options declared via the
+   *               `TRequiredOptions` type parameter.
    * @returns Annotations to merge into the parsing session. Can be a Promise
    *          for async operations (e.g., loading config files).
    */
-  getAnnotations(parsed?: unknown): Promise<Annotations> | Annotations;
+  getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
+  /**
+   * Optional synchronous cleanup method.  Called by `runWith()` and
+   * `runWithSync()` in a `finally` block after parsing completes.
+   */
+  [Symbol.dispose]?(): void;
+  /**
+   * Optional asynchronous cleanup method.  Called by `runWith()` in a
+   * `finally` block after parsing completes.  Takes precedence over
+   * `[Symbol.dispose]` in async runners.
+   */
+  [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
 /**
  * Checks whether a context is static (returns annotations without needing

package/dist/context.d.ts

@@ -46,6 +46,10 @@ type ParserValuePlaceholder = {
  * - *Dynamic*: Data depends on parsing results (e.g., config files whose path
  *   is determined by a CLI option)
  *
+ * Contexts may optionally implement `Disposable` or `AsyncDisposable` for
+ * cleanup.  When present, `runWith()` and `runWithSync()` call the dispose
+ * method in a `finally` block after parsing completes.
+ *
  * @template TRequiredOptions Additional options that `runWith()` must provide
  *   when this context is used. Use `void` (the default) for contexts that
  *   don't require extra options. Use {@link ParserValuePlaceholder} in option
@@ -88,7 +92,7 @@ interface SourceContext<TRequiredOptions = void> {
    * Type-level marker for the required options. Not used at runtime.
    * @internal
    */
-  readonly _requiredOptions?: TRequiredOptions;
+  readonly $requiredOptions?: TRequiredOptions;
   /**
    * Get annotations to inject into parsing.
    *
@@ -103,10 +107,24 @@ interface SourceContext<TRequiredOptions = void> {
    * @param parsed Optional parsed result from a previous parse pass.
    *               Static contexts can ignore this parameter.
    *               Dynamic contexts use this to extract necessary data.
+   * @param options Optional context-required options provided by the caller
+   *               of `runWith()`. These are the options declared via the
+   *               `TRequiredOptions` type parameter.
    * @returns Annotations to merge into the parsing session. Can be a Promise
    *          for async operations (e.g., loading config files).
    */
-  getAnnotations(parsed?: unknown): Promise<Annotations> | Annotations;
+  getAnnotations(parsed?: unknown, options?: unknown): Promise<Annotations> | Annotations;
+  /**
+   * Optional synchronous cleanup method.  Called by `runWith()` and
+   * `runWithSync()` in a `finally` block after parsing completes.
+   */
+  [Symbol.dispose]?(): void;
+  /**
+   * Optional asynchronous cleanup method.  Called by `runWith()` in a
+   * `finally` block after parsing completes.  Takes precedence over
+   * `[Symbol.dispose]` in async runners.
+   */
+  [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
 /**
  * Checks whether a context is static (returns annotations without needing