@optique/core 1.0.0-dev.921 → 1.0.1

package/dist/extension.cjs

@@ -0,0 +1,87 @@
+const require_annotations = require('./internal/annotations.cjs');
+const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
+const require_parser = require('./internal/parser.cjs');
+const require_annotation_state = require('./annotation-state.cjs');
+
+//#region src/extension.ts
+const emptyTraits = Object.freeze({});
+/**
+* Defines stable extension traits on a parser object.
+*
+* @param parser The parser object to annotate.
+* @param traits Traits to enable.
+* @throws {TypeError} If a trait property cannot be defined on `parser`.
+* @since 1.0.0
+*/
+function defineTraits(parser, traits) {
+	if (traits.inheritsAnnotations === true) require_parser.defineInheritedAnnotationParser(parser);
+	if (traits.completesFromSource === true) Object.defineProperty(parser, require_parser.unmatchedNonCliDependencySourceStateMarker, {
+		value: true,
+		configurable: true,
+		enumerable: true
+	});
+	if (traits.requiresSourceBinding === true) Object.defineProperty(parser, require_parser.annotationWrapperRequiresSourceBindingKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Reads the stable extension traits defined on a parser object.
+*
+* @param parser The parser object to inspect.
+* @returns The enabled traits.  Returns an empty object when none are set.
+* @since 1.0.0
+*/
+function getTraits(parser) {
+	const traits = {
+		...Reflect.get(parser, require_parser.inheritParentAnnotationsKey) === true ? { inheritsAnnotations: true } : {},
+		...Reflect.get(parser, require_parser.unmatchedNonCliDependencySourceStateMarker) === true ? { completesFromSource: true } : {},
+		...Reflect.get(parser, require_parser.annotationWrapperRequiresSourceBindingKey) === true ? { requiresSourceBinding: true } : {}
+	};
+	return Object.keys(traits).length > 0 ? traits : emptyTraits;
+}
+/**
+* Delegates suggest-time runtime nodes to an inner parser while preserving an
+* outer parser's own source metadata node.
+*
+* @param innerParser The wrapped parser that owns the underlying nodes.
+* @param outerParser The outer parser that may contribute its own source node.
+* @param state The outer parser state.
+* @param path The parser path within the parse tree.
+* @param innerState The state to use when collecting inner nodes.
+* @param position Whether the outer node is appended or prepended.
+* @returns The composed runtime nodes.
+* @since 1.0.0
+*/
+function delegateSuggestNodes(innerParser, outerParser, state, path, innerState, position = "append") {
+	return require_parser.getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, position);
+}
+/**
+* Maps the source capability of a parser's dependency metadata while
+* preserving any derived or transform capabilities unchanged.
+*
+* @param parser The parser whose source metadata should be transformed.
+* @param mapSource Function that transforms the source capability.
+* @returns The dependency metadata with its source capability transformed when
+*          present; otherwise the original dependency metadata, or
+*          `undefined` when the parser has no dependency metadata.
+* @since 1.0.0
+*/
+function mapSourceMetadata(parser, mapSource) {
+	return require_parser.composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
+}
+
+//#endregion
+exports.defineTraits = defineTraits;
+exports.delegateSuggestNodes = delegateSuggestNodes;
+exports.dispatchByMode = require_mode_dispatch.dispatchByMode;
+exports.getTraits = getTraits;
+exports.inheritAnnotations = require_annotations.inheritAnnotations;
+exports.injectAnnotations = require_annotations.injectAnnotations;
+exports.isInjectedAnnotationState = require_annotations.isInjectedAnnotationState;
+exports.mapModeValue = require_mode_dispatch.mapModeValue;
+exports.mapSourceMetadata = mapSourceMetadata;
+exports.unwrapInjectedAnnotationState = require_annotations.unwrapInjectedAnnotationState;
+exports.withAnnotationView = require_annotation_state.withAnnotationView;
+exports.wrapForMode = require_mode_dispatch.wrapForMode;

package/dist/extension.d.cts

@@ -0,0 +1,97 @@
+import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState } from "./internal/annotations.cjs";
+import { Mode, Parser } from "./internal/parser.cjs";
+import { withAnnotationView } from "./annotation-state.cjs";
+import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.cjs";
+
+//#region src/extension.d.ts
+
+/**
+ * Stable trait flags for custom parser extensions.
+ *
+ * @since 1.0.0
+ */
+interface ParserTraits {
+  /**
+   * Whether parent-state annotations should be injected into rebuilt child
+   * states instead of relying on structural inheritance.
+   */
+  readonly inheritsAnnotations?: true;
+  /**
+   * Whether a missing CLI state can still complete from a source-backed
+   * fallback such as config or environment data.
+   */
+  readonly completesFromSource?: true;
+  /**
+   * Whether annotation-only primitive states should count as completable only
+   * when they come from a nested source-bound parser.
+   */
+  readonly requiresSourceBinding?: true;
+}
+/**
+ * Suggest-time runtime node used to seed dependency-aware completion.
+ *
+ * @since 1.0.0
+ */
+interface SuggestNode {
+  /** Path from the root parser to this node. */
+  readonly path: readonly PropertyKey[];
+  /** The parser whose dependency metadata should be inspected. */
+  readonly parser: Parser<Mode, unknown, unknown>;
+  /** Current parser state for this node. */
+  readonly state: unknown;
+  /** Whether this node reflects explicit input consumption. */
+  readonly matched?: boolean;
+  /** Snapshotted default dependency values for derived parsers. */
+  readonly defaultDependencyValues?: readonly unknown[];
+}
+/**
+ * Public view of a parser's source capability metadata.
+ *
+ * @since 1.0.0
+ */
+type ParserSourceMetadata<M extends Mode = Mode, TValue = unknown, TState = unknown> = NonNullable<NonNullable<Parser<M, TValue, TState>["dependencyMetadata"]>["source"]>;
+/**
+ * Defines stable extension traits on a parser object.
+ *
+ * @param parser The parser object to annotate.
+ * @param traits Traits to enable.
+ * @throws {TypeError} If a trait property cannot be defined on `parser`.
+ * @since 1.0.0
+ */
+declare function defineTraits(parser: object, traits: ParserTraits): void;
+/**
+ * Reads the stable extension traits defined on a parser object.
+ *
+ * @param parser The parser object to inspect.
+ * @returns The enabled traits.  Returns an empty object when none are set.
+ * @since 1.0.0
+ */
+declare function getTraits(parser: object): ParserTraits;
+/**
+ * Delegates suggest-time runtime nodes to an inner parser while preserving an
+ * outer parser's own source metadata node.
+ *
+ * @param innerParser The wrapped parser that owns the underlying nodes.
+ * @param outerParser The outer parser that may contribute its own source node.
+ * @param state The outer parser state.
+ * @param path The parser path within the parse tree.
+ * @param innerState The state to use when collecting inner nodes.
+ * @param position Whether the outer node is appended or prepended.
+ * @returns The composed runtime nodes.
+ * @since 1.0.0
+ */
+declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unknown, TInnerState>, outerParser: Parser<Mode, unknown, unknown>, state: unknown, path: readonly PropertyKey[], innerState: TInnerState, position?: "append" | "prepend"): readonly SuggestNode[];
+/**
+ * Maps the source capability of a parser's dependency metadata while
+ * preserving any derived or transform capabilities unchanged.
+ *
+ * @param parser The parser whose source metadata should be transformed.
+ * @param mapSource Function that transforms the source capability.
+ * @returns The dependency metadata with its source capability transformed when
+ *          present; otherwise the original dependency metadata, or
+ *          `undefined` when the parser has no dependency metadata.
+ * @since 1.0.0
+ */
+declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
+//#endregion
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.d.ts

@@ -0,0 +1,97 @@
+import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState } from "./internal/annotations.js";
+import { Mode, Parser } from "./internal/parser.js";
+import { withAnnotationView } from "./annotation-state.js";
+import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
+
+//#region src/extension.d.ts
+
+/**
+ * Stable trait flags for custom parser extensions.
+ *
+ * @since 1.0.0
+ */
+interface ParserTraits {
+  /**
+   * Whether parent-state annotations should be injected into rebuilt child
+   * states instead of relying on structural inheritance.
+   */
+  readonly inheritsAnnotations?: true;
+  /**
+   * Whether a missing CLI state can still complete from a source-backed
+   * fallback such as config or environment data.
+   */
+  readonly completesFromSource?: true;
+  /**
+   * Whether annotation-only primitive states should count as completable only
+   * when they come from a nested source-bound parser.
+   */
+  readonly requiresSourceBinding?: true;
+}
+/**
+ * Suggest-time runtime node used to seed dependency-aware completion.
+ *
+ * @since 1.0.0
+ */
+interface SuggestNode {
+  /** Path from the root parser to this node. */
+  readonly path: readonly PropertyKey[];
+  /** The parser whose dependency metadata should be inspected. */
+  readonly parser: Parser<Mode, unknown, unknown>;
+  /** Current parser state for this node. */
+  readonly state: unknown;
+  /** Whether this node reflects explicit input consumption. */
+  readonly matched?: boolean;
+  /** Snapshotted default dependency values for derived parsers. */
+  readonly defaultDependencyValues?: readonly unknown[];
+}
+/**
+ * Public view of a parser's source capability metadata.
+ *
+ * @since 1.0.0
+ */
+type ParserSourceMetadata<M extends Mode = Mode, TValue = unknown, TState = unknown> = NonNullable<NonNullable<Parser<M, TValue, TState>["dependencyMetadata"]>["source"]>;
+/**
+ * Defines stable extension traits on a parser object.
+ *
+ * @param parser The parser object to annotate.
+ * @param traits Traits to enable.
+ * @throws {TypeError} If a trait property cannot be defined on `parser`.
+ * @since 1.0.0
+ */
+declare function defineTraits(parser: object, traits: ParserTraits): void;
+/**
+ * Reads the stable extension traits defined on a parser object.
+ *
+ * @param parser The parser object to inspect.
+ * @returns The enabled traits.  Returns an empty object when none are set.
+ * @since 1.0.0
+ */
+declare function getTraits(parser: object): ParserTraits;
+/**
+ * Delegates suggest-time runtime nodes to an inner parser while preserving an
+ * outer parser's own source metadata node.
+ *
+ * @param innerParser The wrapped parser that owns the underlying nodes.
+ * @param outerParser The outer parser that may contribute its own source node.
+ * @param state The outer parser state.
+ * @param path The parser path within the parse tree.
+ * @param innerState The state to use when collecting inner nodes.
+ * @param position Whether the outer node is appended or prepended.
+ * @returns The composed runtime nodes.
+ * @since 1.0.0
+ */
+declare function delegateSuggestNodes<TInnerState>(innerParser: Parser<Mode, unknown, TInnerState>, outerParser: Parser<Mode, unknown, unknown>, state: unknown, path: readonly PropertyKey[], innerState: TInnerState, position?: "append" | "prepend"): readonly SuggestNode[];
+/**
+ * Maps the source capability of a parser's dependency metadata while
+ * preserving any derived or transform capabilities unchanged.
+ *
+ * @param parser The parser whose source metadata should be transformed.
+ * @param mapSource Function that transforms the source capability.
+ * @returns The dependency metadata with its source capability transformed when
+ *          present; otherwise the original dependency metadata, or
+ *          `undefined` when the parser has no dependency metadata.
+ * @since 1.0.0
+ */
+declare function mapSourceMetadata<M extends Mode, TValue, TState>(parser: Pick<Parser<M, TValue, TState>, "dependencyMetadata">, mapSource: (source: ParserSourceMetadata<M, TValue, TState>) => ParserSourceMetadata<M, TValue, TState>): Parser<M, TValue, TState>["dependencyMetadata"] | undefined;
+//#endregion
+export { ParserSourceMetadata, ParserTraits, SuggestNode, defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };

package/dist/extension.js

@@ -0,0 +1,76 @@
+import { inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState } from "./internal/annotations.js";
+import { dispatchByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
+import { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, defineInheritedAnnotationParser, getDelegatingSuggestRuntimeNodes, inheritParentAnnotationsKey, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
+import { withAnnotationView } from "./annotation-state.js";
+
+//#region src/extension.ts
+const emptyTraits = Object.freeze({});
+/**
+* Defines stable extension traits on a parser object.
+*
+* @param parser The parser object to annotate.
+* @param traits Traits to enable.
+* @throws {TypeError} If a trait property cannot be defined on `parser`.
+* @since 1.0.0
+*/
+function defineTraits(parser, traits) {
+	if (traits.inheritsAnnotations === true) defineInheritedAnnotationParser(parser);
+	if (traits.completesFromSource === true) Object.defineProperty(parser, unmatchedNonCliDependencySourceStateMarker, {
+		value: true,
+		configurable: true,
+		enumerable: true
+	});
+	if (traits.requiresSourceBinding === true) Object.defineProperty(parser, annotationWrapperRequiresSourceBindingKey, {
+		value: true,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Reads the stable extension traits defined on a parser object.
+*
+* @param parser The parser object to inspect.
+* @returns The enabled traits.  Returns an empty object when none are set.
+* @since 1.0.0
+*/
+function getTraits(parser) {
+	const traits = {
+		...Reflect.get(parser, inheritParentAnnotationsKey) === true ? { inheritsAnnotations: true } : {},
+		...Reflect.get(parser, unmatchedNonCliDependencySourceStateMarker) === true ? { completesFromSource: true } : {},
+		...Reflect.get(parser, annotationWrapperRequiresSourceBindingKey) === true ? { requiresSourceBinding: true } : {}
+	};
+	return Object.keys(traits).length > 0 ? traits : emptyTraits;
+}
+/**
+* Delegates suggest-time runtime nodes to an inner parser while preserving an
+* outer parser's own source metadata node.
+*
+* @param innerParser The wrapped parser that owns the underlying nodes.
+* @param outerParser The outer parser that may contribute its own source node.
+* @param state The outer parser state.
+* @param path The parser path within the parse tree.
+* @param innerState The state to use when collecting inner nodes.
+* @param position Whether the outer node is appended or prepended.
+* @returns The composed runtime nodes.
+* @since 1.0.0
+*/
+function delegateSuggestNodes(innerParser, outerParser, state, path, innerState, position = "append") {
+	return getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, position);
+}
+/**
+* Maps the source capability of a parser's dependency metadata while
+* preserving any derived or transform capabilities unchanged.
+*
+* @param parser The parser whose source metadata should be transformed.
+* @param mapSource Function that transforms the source capability.
+* @returns The dependency metadata with its source capability transformed when
+*          present; otherwise the original dependency metadata, or
+*          `undefined` when the parser has no dependency metadata.
+* @since 1.0.0
+*/
+function mapSourceMetadata(parser, mapSource) {
+	return composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
+}
+
+//#endregion
+export { defineTraits, delegateSuggestNodes, dispatchByMode, getTraits, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, mapModeValue, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView, wrapForMode };