@optique/core 0.10.7 → 1.0.0-dev.1109

package/dist/context.cjs

@@ -1,21 +1,61 @@
 
 //#region src/context.ts
 /**
+* Brand symbol for placeholder values.
+*
+* Placeholder values are sentinel objects that represent values to be
+* resolved later (e.g., deferred interactive prompts).  During two-phase
+* parsing, placeholder values are stripped from parsed results before they
+* are passed to phase-2 context annotation collection, and `map()`
+* transformations skip them.
+*
+* Packages that produce placeholder values should set this symbol as a
+* property on their sentinel objects:
+*
+* ~~~~ typescript
+* import { placeholder } from "@optique/core/context";
+*
+* class MyPlaceholder {
+*   readonly [placeholder] = true;
+* }
+* ~~~~
+*
+* @since 1.0.0
+*/
+const placeholder = Symbol.for("@optique/core/placeholder");
+/**
+* Tests whether a value is a placeholder.
+*
+* Returns `true` if the value is a non-null object carrying the
+* {@link placeholder} property.
+*
+* @param value The value to test.
+* @returns `true` if the value is a placeholder.
+* @since 1.0.0
+*/
+function isPlaceholderValue(value) {
+	return value != null && typeof value === "object" && placeholder in value;
+}
+/**
 * Checks whether a context is static (returns annotations without needing
 * parsed results).
 *
-* A context is considered static if `getAnnotations()` called without
-* arguments returns a non-empty annotations object synchronously.
+* A context is considered static if it declares `mode: "static"` or if
+* `getAnnotations()` called without arguments returns a non-empty
+* annotations object synchronously.
 *
 * @param context The source context to check.
 * @returns `true` if the context is static, `false` otherwise.
 * @since 0.10.0
 */
 function isStaticContext(context) {
+	if (context.mode !== void 0) return context.mode === "static";
 	const result = context.getAnnotations();
 	if (result instanceof Promise) return false;
 	return Object.getOwnPropertySymbols(result).length > 0;
 }
 
 //#endregion
-exports.isStaticContext = isStaticContext;
+exports.isPlaceholderValue = isPlaceholderValue;
+exports.isStaticContext = isStaticContext;
+exports.placeholder = placeholder;

package/dist/context.d.cts

@@ -2,6 +2,17 @@ import { Annotations } from "./annotations.cjs";
 
 //#region src/context.d.ts
 
+/**
+ * Declares whether a {@link SourceContext} provides its annotations
+ * immediately (`"static"`) or only after a prior parse pass (`"dynamic"`).
+ *
+ * Used as the type of the optional `mode` field on {@link SourceContext}.
+ * When set, {@link isStaticContext} reads this value directly instead of
+ * calling `getAnnotations()`, preventing any side effects.
+ *
+ * @since 1.0.0
+ */
+type SourceContextMode = "static" | "dynamic";
 /**
  * Brand symbol for ParserValuePlaceholder type.
  * @internal
@@ -46,6 +57,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 +103,20 @@ interface SourceContext<TRequiredOptions = void> {
    * Type-level marker for the required options. Not used at runtime.
    * @internal
    */
-  readonly _requiredOptions?: TRequiredOptions;
+  readonly $requiredOptions?: TRequiredOptions;
+  /**
+   * Optional declaration of whether this context is static or dynamic.
+   *
+   * When present, {@link isStaticContext} reads this field directly instead
+   * of calling {@link getAnnotations}, avoiding any side effects that
+   * `getAnnotations` might have (such as mutating a global registry).
+   *
+   * If omitted, {@link isStaticContext} falls back to calling
+   * `getAnnotations()` with no arguments to determine static-ness.
+   *
+   * @since 1.0.0
+   */
+  readonly mode?: SourceContextMode;
   /**
    * Get annotations to inject into parsing.
    *
@@ -103,17 +131,97 @@ 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 hook to provide additional internal annotations during
+   * annotation collection.  Called after {@link getAnnotations} with the
+   * same parsed value and the annotations returned by `getAnnotations()`.
+   *
+   * Returns additional annotations to merge, or `undefined` to add nothing.
+   * This enables contexts to inject phase-specific markers without
+   * exposing them through the primary `getAnnotations()` API.
+   *
+   * @param parsed The parsed result from a previous parse pass, or
+   *               `undefined` during the first pass.
+   * @param annotations The annotations returned by `getAnnotations()`.
+   * @returns Additional annotations to merge, or `undefined`.
+   * @since 1.0.0
+   */
+  getInternalAnnotations?(parsed: unknown, annotations: Annotations): Annotations | undefined;
+  /**
+   * Optional hook to transform the parsed value before it is passed to
+   * {@link getAnnotations} during phase-2 annotation collection.
+   *
+   * This allows contexts to distinguish between "parsed value was
+   * `undefined`" and "no parse happened yet" by wrapping `undefined`
+   * values with a context-private marker.
+   *
+   * @param parsed The parsed value to finalize.
+   * @returns The finalized parsed value.
+   * @since 1.0.0
+   */
+  finalizeParsed?(parsed: unknown): unknown;
+  /**
+   * 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.  `runWithSync()` also calls this
+   * method when `[Symbol.dispose]` is absent, but throws if it returns a
+   * Promise.
+   */
+  [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
+/**
+ * Brand symbol for placeholder values.
+ *
+ * Placeholder values are sentinel objects that represent values to be
+ * resolved later (e.g., deferred interactive prompts).  During two-phase
+ * parsing, placeholder values are stripped from parsed results before they
+ * are passed to phase-2 context annotation collection, and `map()`
+ * transformations skip them.
+ *
+ * Packages that produce placeholder values should set this symbol as a
+ * property on their sentinel objects:
+ *
+ * ~~~~ typescript
+ * import { placeholder } from "@optique/core/context";
+ *
+ * class MyPlaceholder {
+ *   readonly [placeholder] = true;
+ * }
+ * ~~~~
+ *
+ * @since 1.0.0
+ */
+declare const placeholder: unique symbol;
+/**
+ * Tests whether a value is a placeholder.
+ *
+ * Returns `true` if the value is a non-null object carrying the
+ * {@link placeholder} property.
+ *
+ * @param value The value to test.
+ * @returns `true` if the value is a placeholder.
+ * @since 1.0.0
+ */
+declare function isPlaceholderValue(value: unknown): boolean;
 /**
  * Checks whether a context is static (returns annotations without needing
  * parsed results).
  *
- * A context is considered static if `getAnnotations()` called without
- * arguments returns a non-empty annotations object synchronously.
+ * A context is considered static if it declares `mode: "static"` or if
+ * `getAnnotations()` called without arguments returns a non-empty
+ * annotations object synchronously.
  *
  * @param context The source context to check.
  * @returns `true` if the context is static, `false` otherwise.
@@ -121,4 +229,4 @@ interface SourceContext<TRequiredOptions = void> {
  */
 declare function isStaticContext(context: SourceContext<unknown>): boolean;
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, isStaticContext };
+export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextMode, isPlaceholderValue, isStaticContext, placeholder };

package/dist/context.d.ts

@@ -2,6 +2,17 @@ import { Annotations } from "./annotations.js";
 
 //#region src/context.d.ts
 
+/**
+ * Declares whether a {@link SourceContext} provides its annotations
+ * immediately (`"static"`) or only after a prior parse pass (`"dynamic"`).
+ *
+ * Used as the type of the optional `mode` field on {@link SourceContext}.
+ * When set, {@link isStaticContext} reads this value directly instead of
+ * calling `getAnnotations()`, preventing any side effects.
+ *
+ * @since 1.0.0
+ */
+type SourceContextMode = "static" | "dynamic";
 /**
  * Brand symbol for ParserValuePlaceholder type.
  * @internal
@@ -46,6 +57,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 +103,20 @@ interface SourceContext<TRequiredOptions = void> {
    * Type-level marker for the required options. Not used at runtime.
    * @internal
    */
-  readonly _requiredOptions?: TRequiredOptions;
+  readonly $requiredOptions?: TRequiredOptions;
+  /**
+   * Optional declaration of whether this context is static or dynamic.
+   *
+   * When present, {@link isStaticContext} reads this field directly instead
+   * of calling {@link getAnnotations}, avoiding any side effects that
+   * `getAnnotations` might have (such as mutating a global registry).
+   *
+   * If omitted, {@link isStaticContext} falls back to calling
+   * `getAnnotations()` with no arguments to determine static-ness.
+   *
+   * @since 1.0.0
+   */
+  readonly mode?: SourceContextMode;
   /**
    * Get annotations to inject into parsing.
    *
@@ -103,17 +131,97 @@ 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 hook to provide additional internal annotations during
+   * annotation collection.  Called after {@link getAnnotations} with the
+   * same parsed value and the annotations returned by `getAnnotations()`.
+   *
+   * Returns additional annotations to merge, or `undefined` to add nothing.
+   * This enables contexts to inject phase-specific markers without
+   * exposing them through the primary `getAnnotations()` API.
+   *
+   * @param parsed The parsed result from a previous parse pass, or
+   *               `undefined` during the first pass.
+   * @param annotations The annotations returned by `getAnnotations()`.
+   * @returns Additional annotations to merge, or `undefined`.
+   * @since 1.0.0
+   */
+  getInternalAnnotations?(parsed: unknown, annotations: Annotations): Annotations | undefined;
+  /**
+   * Optional hook to transform the parsed value before it is passed to
+   * {@link getAnnotations} during phase-2 annotation collection.
+   *
+   * This allows contexts to distinguish between "parsed value was
+   * `undefined`" and "no parse happened yet" by wrapping `undefined`
+   * values with a context-private marker.
+   *
+   * @param parsed The parsed value to finalize.
+   * @returns The finalized parsed value.
+   * @since 1.0.0
+   */
+  finalizeParsed?(parsed: unknown): unknown;
+  /**
+   * 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.  `runWithSync()` also calls this
+   * method when `[Symbol.dispose]` is absent, but throws if it returns a
+   * Promise.
+   */
+  [Symbol.asyncDispose]?(): void | PromiseLike<void>;
 }
+/**
+ * Brand symbol for placeholder values.
+ *
+ * Placeholder values are sentinel objects that represent values to be
+ * resolved later (e.g., deferred interactive prompts).  During two-phase
+ * parsing, placeholder values are stripped from parsed results before they
+ * are passed to phase-2 context annotation collection, and `map()`
+ * transformations skip them.
+ *
+ * Packages that produce placeholder values should set this symbol as a
+ * property on their sentinel objects:
+ *
+ * ~~~~ typescript
+ * import { placeholder } from "@optique/core/context";
+ *
+ * class MyPlaceholder {
+ *   readonly [placeholder] = true;
+ * }
+ * ~~~~
+ *
+ * @since 1.0.0
+ */
+declare const placeholder: unique symbol;
+/**
+ * Tests whether a value is a placeholder.
+ *
+ * Returns `true` if the value is a non-null object carrying the
+ * {@link placeholder} property.
+ *
+ * @param value The value to test.
+ * @returns `true` if the value is a placeholder.
+ * @since 1.0.0
+ */
+declare function isPlaceholderValue(value: unknown): boolean;
 /**
  * Checks whether a context is static (returns annotations without needing
  * parsed results).
  *
- * A context is considered static if `getAnnotations()` called without
- * arguments returns a non-empty annotations object synchronously.
+ * A context is considered static if it declares `mode: "static"` or if
+ * `getAnnotations()` called without arguments returns a non-empty
+ * annotations object synchronously.
  *
  * @param context The source context to check.
  * @returns `true` if the context is static, `false` otherwise.
@@ -121,4 +229,4 @@ interface SourceContext<TRequiredOptions = void> {
  */
 declare function isStaticContext(context: SourceContext<unknown>): boolean;
 //#endregion
-export { type Annotations, ParserValuePlaceholder, SourceContext, isStaticContext };
+export { type Annotations, ParserValuePlaceholder, SourceContext, SourceContextMode, isPlaceholderValue, isStaticContext, placeholder };

package/dist/context.js

@@ -1,20 +1,58 @@
 //#region src/context.ts
 /**
+* Brand symbol for placeholder values.
+*
+* Placeholder values are sentinel objects that represent values to be
+* resolved later (e.g., deferred interactive prompts).  During two-phase
+* parsing, placeholder values are stripped from parsed results before they
+* are passed to phase-2 context annotation collection, and `map()`
+* transformations skip them.
+*
+* Packages that produce placeholder values should set this symbol as a
+* property on their sentinel objects:
+*
+* ~~~~ typescript
+* import { placeholder } from "@optique/core/context";
+*
+* class MyPlaceholder {
+*   readonly [placeholder] = true;
+* }
+* ~~~~
+*
+* @since 1.0.0
+*/
+const placeholder = Symbol.for("@optique/core/placeholder");
+/**
+* Tests whether a value is a placeholder.
+*
+* Returns `true` if the value is a non-null object carrying the
+* {@link placeholder} property.
+*
+* @param value The value to test.
+* @returns `true` if the value is a placeholder.
+* @since 1.0.0
+*/
+function isPlaceholderValue(value) {
+	return value != null && typeof value === "object" && placeholder in value;
+}
+/**
 * Checks whether a context is static (returns annotations without needing
 * parsed results).
 *
-* A context is considered static if `getAnnotations()` called without
-* arguments returns a non-empty annotations object synchronously.
+* A context is considered static if it declares `mode: "static"` or if
+* `getAnnotations()` called without arguments returns a non-empty
+* annotations object synchronously.
 *
 * @param context The source context to check.
 * @returns `true` if the context is static, `false` otherwise.
 * @since 0.10.0
 */
 function isStaticContext(context) {
+	if (context.mode !== void 0) return context.mode === "static";
 	const result = context.getAnnotations();
 	if (result instanceof Promise) return false;
 	return Object.getOwnPropertySymbols(result).length > 0;
 }
 
 //#endregion
-export { isStaticContext };
+export { isPlaceholderValue, isStaticContext, placeholder };