@optique/core 1.0.0-dev.1766 → 1.0.0-dev.1776

package/dist/annotations.cjs

@@ -131,6 +131,21 @@ function inheritAnnotations(source, target) {
 	return cloned;
 }
 /**
+* Returns whether an annotations record carries at least one own symbol key.
+*
+* An annotations object with no own symbol keys is treated as a no-op by the
+* injection pipeline: it should behave identically to omitting the
+* `annotations` option entirely.  `null` and `undefined` are accepted for
+* call-site convenience and always return `false`.
+*
+* @param annotations The annotations record to check.
+* @returns `true` when the record has at least one own symbol key.
+* @internal
+*/
+function hasMeaningfulAnnotations(annotations) {
+	return annotations != null && Object.getOwnPropertySymbols(annotations).length > 0;
+}
+/**
 * Injects annotations into parser state while preserving state shape.
 *
 * - Primitive, null, and undefined states are wrapped with internal metadata.
@@ -138,6 +153,8 @@ function inheritAnnotations(source, target) {
 * - Plain object states are shallow-cloned with annotations attached.
 * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
 * - Other non-plain object states are cloned via prototype/descriptors.
+* - If the `annotations` record has no own symbol keys, the state is
+*   returned unchanged; an empty annotations object is a no-op.
 *
 * @param state The parser state to annotate.
 * @param annotations The annotations to inject.
@@ -145,6 +162,7 @@ function inheritAnnotations(source, target) {
 * @internal
 */
 function injectAnnotations(state, annotations) {
+	if (!hasMeaningfulAnnotations(annotations)) return state;
 	if (state == null || typeof state !== "object") {
 		const wrapper = {};
 		Object.defineProperties(wrapper, {
@@ -243,6 +261,7 @@ exports.annotationStateValueKey = annotationStateValueKey;
 exports.annotationWrapperKey = annotationWrapperKey;
 exports.firstPassAnnotationKey = firstPassAnnotationKey;
 exports.getAnnotations = getAnnotations;
+exports.hasMeaningfulAnnotations = hasMeaningfulAnnotations;
 exports.inheritAnnotations = inheritAnnotations;
 exports.injectAnnotations = injectAnnotations;
 exports.isInjectedAnnotationWrapper = isInjectedAnnotationWrapper;

package/dist/annotations.d.cts

@@ -100,6 +100,19 @@ declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): r
  * @internal
  */
 declare function inheritAnnotations<T>(source: unknown, target: T): T;
+/**
+ * Returns whether an annotations record carries at least one own symbol key.
+ *
+ * An annotations object with no own symbol keys is treated as a no-op by the
+ * injection pipeline: it should behave identically to omitting the
+ * `annotations` option entirely.  `null` and `undefined` are accepted for
+ * call-site convenience and always return `false`.
+ *
+ * @param annotations The annotations record to check.
+ * @returns `true` when the record has at least one own symbol key.
+ * @internal
+ */
+declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -108,6 +121,8 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * - Plain object states are shallow-cloned with annotations attached.
  * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
  * - Other non-plain object states are cloned via prototype/descriptors.
+ * - If the `annotations` record has no own symbol keys, the state is
+ *   returned unchanged; an empty annotations object is a no-op.
  *
  * @param state The parser state to annotate.
  * @param annotations The annotations to inject.
@@ -134,4 +149,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.d.ts

@@ -100,6 +100,19 @@ declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): r
  * @internal
  */
 declare function inheritAnnotations<T>(source: unknown, target: T): T;
+/**
+ * Returns whether an annotations record carries at least one own symbol key.
+ *
+ * An annotations object with no own symbol keys is treated as a no-op by the
+ * injection pipeline: it should behave identically to omitting the
+ * `annotations` option entirely.  `null` and `undefined` are accepted for
+ * call-site convenience and always return `false`.
+ *
+ * @param annotations The annotations record to check.
+ * @returns `true` when the record has at least one own symbol key.
+ * @internal
+ */
+declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -108,6 +121,8 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * - Plain object states are shallow-cloned with annotations attached.
  * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
  * - Other non-plain object states are cloned via prototype/descriptors.
+ * - If the `annotations` record has no own symbol keys, the state is
+ *   returned unchanged; an empty annotations object is a no-op.
  *
  * @param state The parser state to annotate.
  * @param annotations The annotations to inject.
@@ -134,4 +149,4 @@ declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
  */
 declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 //#endregion
-export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/annotations.js

@@ -130,6 +130,21 @@ function inheritAnnotations(source, target) {
 	return cloned;
 }
 /**
+* Returns whether an annotations record carries at least one own symbol key.
+*
+* An annotations object with no own symbol keys is treated as a no-op by the
+* injection pipeline: it should behave identically to omitting the
+* `annotations` option entirely.  `null` and `undefined` are accepted for
+* call-site convenience and always return `false`.
+*
+* @param annotations The annotations record to check.
+* @returns `true` when the record has at least one own symbol key.
+* @internal
+*/
+function hasMeaningfulAnnotations(annotations) {
+	return annotations != null && Object.getOwnPropertySymbols(annotations).length > 0;
+}
+/**
 * Injects annotations into parser state while preserving state shape.
 *
 * - Primitive, null, and undefined states are wrapped with internal metadata.
@@ -137,6 +152,8 @@ function inheritAnnotations(source, target) {
 * - Plain object states are shallow-cloned with annotations attached.
 * - Built-in object states (Date/Map/Set/RegExp) are cloned by constructor.
 * - Other non-plain object states are cloned via prototype/descriptors.
+* - If the `annotations` record has no own symbol keys, the state is
+*   returned unchanged; an empty annotations object is a no-op.
 *
 * @param state The parser state to annotate.
 * @param annotations The annotations to inject.
@@ -144,6 +161,7 @@ function inheritAnnotations(source, target) {
 * @internal
 */
 function injectAnnotations(state, annotations) {
+	if (!hasMeaningfulAnnotations(annotations)) return state;
 	if (state == null || typeof state !== "object") {
 		const wrapper = {};
 		Object.defineProperties(wrapper, {
@@ -236,4 +254,4 @@ function isInjectedAnnotationWrapper(value) {
 }
 
 //#endregion
-export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };
+export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper };

package/dist/parser.cjs

@@ -68,7 +68,7 @@ function createParserContext(frame, exec) {
 }
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
-	if (annotations == null) return state;
+	if (!require_annotations.hasMeaningfulAnnotations(annotations)) return state;
 	return require_annotations.injectAnnotations(state, annotations);
 }
 /**
@@ -97,7 +97,7 @@ function injectAnnotationsIntoState(state, options) {
 */
 function parseSync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_annotations.hasMeaningfulAnnotations(options?.annotations) || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
@@ -169,7 +169,7 @@ function isBufferUnchanged(previous, current) {
 */
 async function parseAsync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_annotations.hasMeaningfulAnnotations(options?.annotations) || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",

package/dist/parser.js

@@ -1,4 +1,4 @@
-import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
+import { hasMeaningfulAnnotations, injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
 import { cloneMessage, message } from "./message.js";
 import { cloneUsage, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
@@ -68,7 +68,7 @@ function createParserContext(frame, exec) {
 }
 function injectAnnotationsIntoState(state, options) {
 	const annotations = options?.annotations;
-	if (annotations == null) return state;
+	if (!hasMeaningfulAnnotations(annotations)) return state;
 	return injectAnnotations(state, annotations);
 }
 /**
@@ -97,7 +97,7 @@ function injectAnnotationsIntoState(state, options) {
 */
 function parseSync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",
@@ -169,7 +169,7 @@ function isBufferUnchanged(previous, current) {
 */
 async function parseAsync(parser, args, options) {
 	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = hasMeaningfulAnnotations(options?.annotations) || isInjectedAnnotationWrapper(parser.initialState);
 	const exec = {
 		usage: parser.usage,
 		phase: "parse",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1766+87276239",
+  "version": "1.0.0-dev.1776+898f38af",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",