@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/dist/annotation-state.cjs +26 -26
  2. package/dist/annotation-state.d.cts +133 -1
  3. package/dist/annotation-state.d.ts +133 -1
  4. package/dist/annotations.cjs +2 -2
  5. package/dist/constructs.cjs +873 -73
  6. package/dist/constructs.d.cts +72 -1
  7. package/dist/constructs.d.ts +72 -1
  8. package/dist/constructs.js +808 -9
  9. package/dist/dependency-metadata.cjs +12 -12
  10. package/dist/dependency-metadata.d.cts +34 -3
  11. package/dist/dependency-metadata.d.ts +34 -3
  12. package/dist/dependency-runtime.cjs +37 -13
  13. package/dist/dependency-runtime.d.cts +197 -2
  14. package/dist/dependency-runtime.d.ts +197 -2
  15. package/dist/dependency-runtime.js +22 -1
  16. package/dist/dependency.cjs +7 -7
  17. package/dist/displaywidth.d.cts +12 -0
  18. package/dist/displaywidth.d.ts +12 -0
  19. package/dist/doc.cjs +3 -0
  20. package/dist/doc.js +3 -0
  21. package/dist/execution-context.d.cts +23 -0
  22. package/dist/execution-context.d.ts +23 -0
  23. package/dist/extension.cjs +14 -14
  24. package/dist/facade.cjs +49 -37
  25. package/dist/facade.js +34 -22
  26. package/dist/index.cjs +23 -21
  27. package/dist/index.d.cts +3 -3
  28. package/dist/index.d.ts +3 -3
  29. package/dist/index.js +4 -4
  30. package/dist/input-trace.d.cts +2 -1
  31. package/dist/input-trace.d.ts +2 -1
  32. package/dist/internal/annotations.cjs +3 -0
  33. package/dist/internal/annotations.d.cts +47 -5
  34. package/dist/internal/annotations.d.ts +47 -5
  35. package/dist/internal/annotations.js +1 -1
  36. package/dist/internal/command-alias.cjs +16 -0
  37. package/dist/internal/command-alias.js +14 -0
  38. package/dist/internal/dependency.cjs +131 -0
  39. package/dist/internal/dependency.d.cts +311 -2
  40. package/dist/internal/dependency.d.ts +311 -2
  41. package/dist/internal/dependency.js +119 -1
  42. package/dist/internal/parser.cjs +108 -23
  43. package/dist/internal/parser.d.cts +58 -3
  44. package/dist/internal/parser.d.ts +58 -3
  45. package/dist/internal/parser.js +101 -16
  46. package/dist/modifiers.cjs +74 -44
  47. package/dist/modifiers.js +34 -4
  48. package/dist/parser.cjs +11 -11
  49. package/dist/phase2-seed.cjs +2 -2
  50. package/dist/phase2-seed.d.cts +50 -0
  51. package/dist/phase2-seed.d.ts +50 -0
  52. package/dist/primitives.cjs +104 -33
  53. package/dist/primitives.d.cts +10 -0
  54. package/dist/primitives.d.ts +10 -0
  55. package/dist/primitives.js +84 -13
  56. package/dist/suggestion.cjs +72 -2
  57. package/dist/suggestion.d.cts +188 -0
  58. package/dist/suggestion.d.ts +188 -0
  59. package/dist/suggestion.js +71 -3
  60. package/dist/usage-internals.cjs +14 -6
  61. package/dist/usage-internals.js +14 -6
  62. package/dist/usage.cjs +33 -8
  63. package/dist/usage.d.cts +31 -0
  64. package/dist/usage.d.ts +31 -0
  65. package/dist/usage.js +33 -8
  66. package/dist/validate.cjs +1 -0
  67. package/dist/validate.d.cts +99 -0
  68. package/dist/validate.d.ts +99 -0
  69. package/dist/validate.js +1 -1
  70. package/dist/valueparser.cjs +333 -79
  71. package/dist/valueparser.d.cts +197 -1
  72. package/dist/valueparser.d.ts +197 -1
  73. package/dist/valueparser.js +334 -81
  74. package/package.json +19 -4
@@ -1,4 +1,6 @@
1
1
  import { NonEmptyString } from "../nonempty.cjs";
2
+ import { Message } from "../message.cjs";
3
+ import { DependencyRegistryLike } from "../registry-types.cjs";
2
4
  import { ValueParser, ValueParserResult } from "../valueparser.cjs";
3
5
  import { Mode, Suggestion } from "./parser.cjs";
4
6
 
@@ -51,7 +53,7 @@ declare const singleDefaultValue: unique symbol;
51
53
  *
52
54
  * @internal
53
55
  */
54
-
56
+ declare const defaultDependencyValueSnapshot: unique symbol;
55
57
  /**
56
58
  * A unique symbol used to access the parseWithDependency method on derived parsers.
57
59
  * @since 0.10.0
@@ -535,5 +537,312 @@ declare function deriveFromAsync<Deps extends readonly AnyDependencySource[], T>
535
537
  * @returns A cloned parse result with an internal snapshot attached.
536
538
  * @internal
537
539
  */
540
+ declare function snapshotDefaultDependencyValues<T>(result: ValueParserResult<T>, values: readonly unknown[]): ValueParserResult<T>;
541
+ /**
542
+ * Reads the snapshotted default dependency values from a parse result.
543
+ *
544
+ * @param result The parse result to inspect.
545
+ * @returns The snapshotted dependency values, if present.
546
+ * @internal
547
+ */
548
+ declare function getSnapshottedDefaultDependencyValues<T>(result: ValueParserResult<T>): readonly unknown[] | undefined;
549
+ /**
550
+ * A unique symbol used to identify deferred parse states.
551
+ * @since 0.10.0
552
+ */
553
+ declare const deferredParseMarker: unique symbol;
554
+ /**
555
+ * Represents a deferred parse state for a DerivedValueParser.
556
+ *
557
+ * When a DerivedValueParser is used in an option or argument, the raw
558
+ * input string is stored along with the parser reference. The actual
559
+ * parsing is deferred until `complete()` time when all dependencies
560
+ * have been resolved.
561
+ *
562
+ * @template T The type of value this parser will produce after resolution.
563
+ * @since 0.10.0
564
+ */
565
+ interface DeferredParseState<T = unknown> {
566
+ /**
567
+ * Marker to identify this as a deferred parse state.
568
+ */
569
+ readonly [deferredParseMarker]: true;
570
+ /**
571
+ * The raw input string to be parsed.
572
+ */
573
+ readonly rawInput: string;
574
+ /**
575
+ * The DerivedValueParser that will parse the input.
576
+ */
577
+ readonly parser: DerivedValueParser<Mode, T, unknown>;
578
+ /**
579
+ * The dependency ID that this parser depends on (for single-dependency parsers).
580
+ */
581
+ readonly dependencyId: symbol;
582
+ /**
583
+ * The dependency IDs that this parser depends on (for multi-dependency parsers).
584
+ * If present, this is used instead of `dependencyId`.
585
+ */
586
+ readonly dependencyIds?: readonly symbol[];
587
+ /**
588
+ * The default values to use for dependencies that are not provided.
589
+ * For multi-dependency parsers, this is a tuple of default values in order.
590
+ * For single-dependency parsers, this is the single default value.
591
+ */
592
+ readonly defaultValues?: readonly unknown[];
593
+ /**
594
+ * The preliminary parse result using the default dependency value.
595
+ * This is used as a fallback if dependency resolution is not needed
596
+ * or if the dependency was not provided.
597
+ */
598
+ readonly preliminaryResult: ValueParserResult<T>;
599
+ }
600
+ /**
601
+ * Checks if a value is a {@link DeferredParseState}.
602
+ *
603
+ * @param value The value to check.
604
+ * @returns `true` if the value is a deferred parse state, `false` otherwise.
605
+ * @since 0.10.0
606
+ */
607
+ declare function isDeferredParseState<T>(value: unknown): value is DeferredParseState<T>;
608
+ /**
609
+ * Gets all dependency IDs from a derived parser.
610
+ * If the parser was created with `deriveFrom` (multiple dependencies),
611
+ * returns the array of dependency IDs. Otherwise, returns an array
612
+ * containing the single dependency ID.
613
+ *
614
+ * @param parser The derived value parser to get dependency IDs from.
615
+ * @returns An array of dependency ID symbols.
616
+ * @internal
617
+ * @since 0.10.0
618
+ */
619
+ declare function getDependencyIds<M extends Mode, T, S>(parser: DerivedValueParser<M, T, S>): readonly symbol[];
620
+ /**
621
+ * Gets the default values function from a multi-source derived parser, if
622
+ * present.
623
+ *
624
+ * Single-source `derive()` defaults must stay lazy during suggestion-time
625
+ * replay so missing dependencies do not eagerly evaluate side-effectful
626
+ * `defaultValue()` thunks.
627
+ *
628
+ * @param parser The derived value parser to get the default values function from.
629
+ * @returns The default values function, or undefined if not available.
630
+ * @internal
631
+ * @since 0.10.0
632
+ */
633
+ declare function getDefaultValuesFunction<M extends Mode, T, S>(parser: DerivedValueParser<M, T, S>): (() => readonly unknown[]) | undefined;
634
+ /**
635
+ * Creates a deferred parse state for a DerivedValueParser.
636
+ *
637
+ * @template T The type of value the parser will produce.
638
+ * @template S The type of the source dependency value.
639
+ * @param rawInput The raw input string to be parsed.
640
+ * @param parser The DerivedValueParser that will parse the input.
641
+ * @param preliminaryResult The parse result using default dependency value.
642
+ * @returns A DeferredParseState object.
643
+ * @since 0.10.0
644
+ */
645
+ declare function createDeferredParseState<T, S>(rawInput: string, parser: DerivedValueParser<Mode, T, S>, preliminaryResult: ValueParserResult<T>): DeferredParseState<T>;
646
+ /**
647
+ * A unique symbol used to identify dependency source parse states.
648
+ * @since 0.10.0
649
+ */
650
+ declare const dependencySourceStateMarker: unique symbol;
651
+ /**
652
+ * Represents a parse state from a DependencySource.
653
+ * This wraps the normal ValueParserResult with the dependency ID so that
654
+ * it can be matched with DeferredParseState during resolution.
655
+ *
656
+ * @template T The type of value this state contains.
657
+ * @since 0.10.0
658
+ */
659
+ interface DependencySourceState<T = unknown> {
660
+ /**
661
+ * Marker to identify this as a dependency source state.
662
+ */
663
+ readonly [dependencySourceStateMarker]: true;
664
+ /**
665
+ * The dependency ID of the source.
666
+ */
667
+ readonly [dependencyId]: symbol;
668
+ /**
669
+ * The underlying parse result.
670
+ */
671
+ readonly result: ValueParserResult<T>;
672
+ }
673
+ /**
674
+ * Checks if a value is a {@link DependencySourceState}.
675
+ *
676
+ * @param value The value to check.
677
+ * @returns `true` if the value is a dependency source state, `false` otherwise.
678
+ * @since 0.10.0
679
+ */
680
+ declare function isDependencySourceState<T>(value: unknown): value is DependencySourceState<T>;
681
+ /**
682
+ * Creates a dependency source state from a parse result.
683
+ *
684
+ * @template T The type of value the state contains.
685
+ * @param result The parse result.
686
+ * @param depId The dependency ID.
687
+ * @returns A DependencySourceState object.
688
+ * @since 0.10.0
689
+ */
690
+ declare function createDependencySourceState<T>(result: ValueParserResult<T>, depId: symbol): DependencySourceState<T>;
691
+ /**
692
+ * A unique symbol used to identify pending dependency source states.
693
+ * @since 0.10.0
694
+ */
695
+ declare const pendingDependencySourceStateMarker: unique symbol;
696
+ /**
697
+ * Represents a pending dependency source state.
698
+ * This is used when a dependency source option was not provided, but its
699
+ * dependency ID still needs to be tracked for later resolution with a
700
+ * default value.
701
+ *
702
+ * @since 0.10.0
703
+ */
704
+ interface PendingDependencySourceState {
705
+ /**
706
+ * Marker to identify this as a pending dependency source state.
707
+ */
708
+ readonly [pendingDependencySourceStateMarker]: true;
709
+ /**
710
+ * The dependency ID of the source.
711
+ */
712
+ readonly [dependencyId]: symbol;
713
+ }
714
+ /**
715
+ * Checks if a value is a {@link PendingDependencySourceState}.
716
+ *
717
+ * @param value The value to check.
718
+ * @returns `true` if the value is a pending dependency source state.
719
+ * @since 0.10.0
720
+ */
721
+ declare function isPendingDependencySourceState(value: unknown): value is PendingDependencySourceState;
722
+ /**
723
+ * Creates a pending dependency source state.
724
+ *
725
+ * @param depId The dependency ID.
726
+ * @returns A PendingDependencySourceState object.
727
+ * @since 0.10.0
728
+ */
729
+ declare function createPendingDependencySourceState(depId: symbol): PendingDependencySourceState;
730
+ /**
731
+ * A unique symbol used to identify parsers that wrap a dependency source.
732
+ * This is used by withDefault to indicate it contains an inner parser
733
+ * with a PendingDependencySourceState initialState.
734
+ * @since 0.10.0
735
+ */
736
+ declare const wrappedDependencySourceMarker: unique symbol;
737
+ /**
738
+ * A unique symbol used to indicate that a wrapper transforms the dependency
739
+ * source value. This is used by withDefault to determine whether its default
740
+ * value should be registered as the dependency value.
741
+ *
742
+ * When a wrapper has this marker set to `true`, it means the wrapper transforms
743
+ * the dependency source value (e.g., via map()), so the wrapper's output is NOT
744
+ * a valid dependency source value.
745
+ *
746
+ * @since 0.10.0
747
+ */
748
+ declare const transformsDependencyValueMarker: unique symbol;
749
+ /**
750
+ * Checks if a parser transforms the dependency value (has transformsDependencyValueMarker).
751
+ *
752
+ * @param parser The parser to check.
753
+ * @returns `true` if the parser transforms the dependency value.
754
+ * @since 0.10.0
755
+ */
756
+ declare function transformsDependencyValue(parser: unknown): parser is {
757
+ [transformsDependencyValueMarker]: true;
758
+ };
759
+ /**
760
+ * Checks if a parser wraps a dependency source (has wrappedDependencySourceMarker).
761
+ *
762
+ * @param parser The parser to check.
763
+ * @returns `true` if the parser wraps a dependency source.
764
+ * @since 0.10.0
765
+ */
766
+ declare function isWrappedDependencySource(parser: unknown): parser is {
767
+ [wrappedDependencySourceMarker]: PendingDependencySourceState;
768
+ };
769
+ /**
770
+ * Represents a resolved dependency value stored during parsing.
771
+ * @since 0.10.0
772
+ */
773
+ interface ResolvedDependency<T = unknown> {
774
+ /**
775
+ * The dependency ID.
776
+ */
777
+ readonly id: symbol;
778
+ /**
779
+ * The resolved value.
780
+ */
781
+ readonly value: T;
782
+ }
783
+ /**
784
+ * A registry for storing resolved dependency values during parsing.
785
+ * This is used to pass dependency values from DependencySource options
786
+ * to DerivedValueParser options.
787
+ * @since 0.10.0
788
+ */
789
+ declare class DependencyRegistry implements DependencyRegistryLike {
790
+ private readonly values;
791
+ /**
792
+ * Registers a resolved dependency value.
793
+ * @param id The dependency ID.
794
+ * @param value The resolved value.
795
+ */
796
+ set<T>(id: symbol, value: T): void;
797
+ /**
798
+ * Gets a resolved dependency value.
799
+ * @param id The dependency ID.
800
+ * @returns The resolved value, or undefined if not found.
801
+ */
802
+ get<T>(id: symbol): T | undefined;
803
+ /**
804
+ * Checks if a dependency has been resolved.
805
+ * @param id The dependency ID.
806
+ * @returns `true` if the dependency has been resolved.
807
+ */
808
+ has(id: symbol): boolean;
809
+ /**
810
+ * Creates a copy of the registry.
811
+ */
812
+ clone(): DependencyRegistry;
813
+ }
814
+ /**
815
+ * Error types for dependency resolution failures.
816
+ * @since 0.10.0
817
+ */
818
+ type DependencyError = {
819
+ /**
820
+ * The dependency was used in multiple locations.
821
+ */
822
+ readonly kind: "duplicate";
823
+ readonly dependencyId: symbol;
824
+ readonly locations: readonly string[];
825
+ } | {
826
+ /**
827
+ * A derived parser references a dependency that was not provided.
828
+ */
829
+ readonly kind: "unresolved";
830
+ readonly dependencyId: symbol;
831
+ readonly derivedParserMetavar: string;
832
+ } | {
833
+ /**
834
+ * Circular dependency detected.
835
+ */
836
+ readonly kind: "circular";
837
+ readonly cycle: readonly symbol[];
838
+ };
839
+ /**
840
+ * Formats a {@link DependencyError} into a human-readable {@link Message}.
841
+ *
842
+ * @param error The dependency error to format.
843
+ * @returns A Message describing the error.
844
+ * @since 0.10.0
845
+ */
846
+ declare function formatDependencyError(error: DependencyError): Message;
538
847
  //#endregion
539
- export { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser };
848
+ export { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };
@@ -1,4 +1,6 @@
1
1
  import { NonEmptyString } from "../nonempty.js";
2
+ import { Message } from "../message.js";
3
+ import { DependencyRegistryLike } from "../registry-types.js";
2
4
  import { ValueParser, ValueParserResult } from "../valueparser.js";
3
5
  import { Mode, Suggestion } from "./parser.js";
4
6
 
@@ -51,7 +53,7 @@ declare const singleDefaultValue: unique symbol;
51
53
  *
52
54
  * @internal
53
55
  */
54
-
56
+ declare const defaultDependencyValueSnapshot: unique symbol;
55
57
  /**
56
58
  * A unique symbol used to access the parseWithDependency method on derived parsers.
57
59
  * @since 0.10.0
@@ -535,5 +537,312 @@ declare function deriveFromAsync<Deps extends readonly AnyDependencySource[], T>
535
537
  * @returns A cloned parse result with an internal snapshot attached.
536
538
  * @internal
537
539
  */
540
+ declare function snapshotDefaultDependencyValues<T>(result: ValueParserResult<T>, values: readonly unknown[]): ValueParserResult<T>;
541
+ /**
542
+ * Reads the snapshotted default dependency values from a parse result.
543
+ *
544
+ * @param result The parse result to inspect.
545
+ * @returns The snapshotted dependency values, if present.
546
+ * @internal
547
+ */
548
+ declare function getSnapshottedDefaultDependencyValues<T>(result: ValueParserResult<T>): readonly unknown[] | undefined;
549
+ /**
550
+ * A unique symbol used to identify deferred parse states.
551
+ * @since 0.10.0
552
+ */
553
+ declare const deferredParseMarker: unique symbol;
554
+ /**
555
+ * Represents a deferred parse state for a DerivedValueParser.
556
+ *
557
+ * When a DerivedValueParser is used in an option or argument, the raw
558
+ * input string is stored along with the parser reference. The actual
559
+ * parsing is deferred until `complete()` time when all dependencies
560
+ * have been resolved.
561
+ *
562
+ * @template T The type of value this parser will produce after resolution.
563
+ * @since 0.10.0
564
+ */
565
+ interface DeferredParseState<T = unknown> {
566
+ /**
567
+ * Marker to identify this as a deferred parse state.
568
+ */
569
+ readonly [deferredParseMarker]: true;
570
+ /**
571
+ * The raw input string to be parsed.
572
+ */
573
+ readonly rawInput: string;
574
+ /**
575
+ * The DerivedValueParser that will parse the input.
576
+ */
577
+ readonly parser: DerivedValueParser<Mode, T, unknown>;
578
+ /**
579
+ * The dependency ID that this parser depends on (for single-dependency parsers).
580
+ */
581
+ readonly dependencyId: symbol;
582
+ /**
583
+ * The dependency IDs that this parser depends on (for multi-dependency parsers).
584
+ * If present, this is used instead of `dependencyId`.
585
+ */
586
+ readonly dependencyIds?: readonly symbol[];
587
+ /**
588
+ * The default values to use for dependencies that are not provided.
589
+ * For multi-dependency parsers, this is a tuple of default values in order.
590
+ * For single-dependency parsers, this is the single default value.
591
+ */
592
+ readonly defaultValues?: readonly unknown[];
593
+ /**
594
+ * The preliminary parse result using the default dependency value.
595
+ * This is used as a fallback if dependency resolution is not needed
596
+ * or if the dependency was not provided.
597
+ */
598
+ readonly preliminaryResult: ValueParserResult<T>;
599
+ }
600
+ /**
601
+ * Checks if a value is a {@link DeferredParseState}.
602
+ *
603
+ * @param value The value to check.
604
+ * @returns `true` if the value is a deferred parse state, `false` otherwise.
605
+ * @since 0.10.0
606
+ */
607
+ declare function isDeferredParseState<T>(value: unknown): value is DeferredParseState<T>;
608
+ /**
609
+ * Gets all dependency IDs from a derived parser.
610
+ * If the parser was created with `deriveFrom` (multiple dependencies),
611
+ * returns the array of dependency IDs. Otherwise, returns an array
612
+ * containing the single dependency ID.
613
+ *
614
+ * @param parser The derived value parser to get dependency IDs from.
615
+ * @returns An array of dependency ID symbols.
616
+ * @internal
617
+ * @since 0.10.0
618
+ */
619
+ declare function getDependencyIds<M extends Mode, T, S>(parser: DerivedValueParser<M, T, S>): readonly symbol[];
620
+ /**
621
+ * Gets the default values function from a multi-source derived parser, if
622
+ * present.
623
+ *
624
+ * Single-source `derive()` defaults must stay lazy during suggestion-time
625
+ * replay so missing dependencies do not eagerly evaluate side-effectful
626
+ * `defaultValue()` thunks.
627
+ *
628
+ * @param parser The derived value parser to get the default values function from.
629
+ * @returns The default values function, or undefined if not available.
630
+ * @internal
631
+ * @since 0.10.0
632
+ */
633
+ declare function getDefaultValuesFunction<M extends Mode, T, S>(parser: DerivedValueParser<M, T, S>): (() => readonly unknown[]) | undefined;
634
+ /**
635
+ * Creates a deferred parse state for a DerivedValueParser.
636
+ *
637
+ * @template T The type of value the parser will produce.
638
+ * @template S The type of the source dependency value.
639
+ * @param rawInput The raw input string to be parsed.
640
+ * @param parser The DerivedValueParser that will parse the input.
641
+ * @param preliminaryResult The parse result using default dependency value.
642
+ * @returns A DeferredParseState object.
643
+ * @since 0.10.0
644
+ */
645
+ declare function createDeferredParseState<T, S>(rawInput: string, parser: DerivedValueParser<Mode, T, S>, preliminaryResult: ValueParserResult<T>): DeferredParseState<T>;
646
+ /**
647
+ * A unique symbol used to identify dependency source parse states.
648
+ * @since 0.10.0
649
+ */
650
+ declare const dependencySourceStateMarker: unique symbol;
651
+ /**
652
+ * Represents a parse state from a DependencySource.
653
+ * This wraps the normal ValueParserResult with the dependency ID so that
654
+ * it can be matched with DeferredParseState during resolution.
655
+ *
656
+ * @template T The type of value this state contains.
657
+ * @since 0.10.0
658
+ */
659
+ interface DependencySourceState<T = unknown> {
660
+ /**
661
+ * Marker to identify this as a dependency source state.
662
+ */
663
+ readonly [dependencySourceStateMarker]: true;
664
+ /**
665
+ * The dependency ID of the source.
666
+ */
667
+ readonly [dependencyId]: symbol;
668
+ /**
669
+ * The underlying parse result.
670
+ */
671
+ readonly result: ValueParserResult<T>;
672
+ }
673
+ /**
674
+ * Checks if a value is a {@link DependencySourceState}.
675
+ *
676
+ * @param value The value to check.
677
+ * @returns `true` if the value is a dependency source state, `false` otherwise.
678
+ * @since 0.10.0
679
+ */
680
+ declare function isDependencySourceState<T>(value: unknown): value is DependencySourceState<T>;
681
+ /**
682
+ * Creates a dependency source state from a parse result.
683
+ *
684
+ * @template T The type of value the state contains.
685
+ * @param result The parse result.
686
+ * @param depId The dependency ID.
687
+ * @returns A DependencySourceState object.
688
+ * @since 0.10.0
689
+ */
690
+ declare function createDependencySourceState<T>(result: ValueParserResult<T>, depId: symbol): DependencySourceState<T>;
691
+ /**
692
+ * A unique symbol used to identify pending dependency source states.
693
+ * @since 0.10.0
694
+ */
695
+ declare const pendingDependencySourceStateMarker: unique symbol;
696
+ /**
697
+ * Represents a pending dependency source state.
698
+ * This is used when a dependency source option was not provided, but its
699
+ * dependency ID still needs to be tracked for later resolution with a
700
+ * default value.
701
+ *
702
+ * @since 0.10.0
703
+ */
704
+ interface PendingDependencySourceState {
705
+ /**
706
+ * Marker to identify this as a pending dependency source state.
707
+ */
708
+ readonly [pendingDependencySourceStateMarker]: true;
709
+ /**
710
+ * The dependency ID of the source.
711
+ */
712
+ readonly [dependencyId]: symbol;
713
+ }
714
+ /**
715
+ * Checks if a value is a {@link PendingDependencySourceState}.
716
+ *
717
+ * @param value The value to check.
718
+ * @returns `true` if the value is a pending dependency source state.
719
+ * @since 0.10.0
720
+ */
721
+ declare function isPendingDependencySourceState(value: unknown): value is PendingDependencySourceState;
722
+ /**
723
+ * Creates a pending dependency source state.
724
+ *
725
+ * @param depId The dependency ID.
726
+ * @returns A PendingDependencySourceState object.
727
+ * @since 0.10.0
728
+ */
729
+ declare function createPendingDependencySourceState(depId: symbol): PendingDependencySourceState;
730
+ /**
731
+ * A unique symbol used to identify parsers that wrap a dependency source.
732
+ * This is used by withDefault to indicate it contains an inner parser
733
+ * with a PendingDependencySourceState initialState.
734
+ * @since 0.10.0
735
+ */
736
+ declare const wrappedDependencySourceMarker: unique symbol;
737
+ /**
738
+ * A unique symbol used to indicate that a wrapper transforms the dependency
739
+ * source value. This is used by withDefault to determine whether its default
740
+ * value should be registered as the dependency value.
741
+ *
742
+ * When a wrapper has this marker set to `true`, it means the wrapper transforms
743
+ * the dependency source value (e.g., via map()), so the wrapper's output is NOT
744
+ * a valid dependency source value.
745
+ *
746
+ * @since 0.10.0
747
+ */
748
+ declare const transformsDependencyValueMarker: unique symbol;
749
+ /**
750
+ * Checks if a parser transforms the dependency value (has transformsDependencyValueMarker).
751
+ *
752
+ * @param parser The parser to check.
753
+ * @returns `true` if the parser transforms the dependency value.
754
+ * @since 0.10.0
755
+ */
756
+ declare function transformsDependencyValue(parser: unknown): parser is {
757
+ [transformsDependencyValueMarker]: true;
758
+ };
759
+ /**
760
+ * Checks if a parser wraps a dependency source (has wrappedDependencySourceMarker).
761
+ *
762
+ * @param parser The parser to check.
763
+ * @returns `true` if the parser wraps a dependency source.
764
+ * @since 0.10.0
765
+ */
766
+ declare function isWrappedDependencySource(parser: unknown): parser is {
767
+ [wrappedDependencySourceMarker]: PendingDependencySourceState;
768
+ };
769
+ /**
770
+ * Represents a resolved dependency value stored during parsing.
771
+ * @since 0.10.0
772
+ */
773
+ interface ResolvedDependency<T = unknown> {
774
+ /**
775
+ * The dependency ID.
776
+ */
777
+ readonly id: symbol;
778
+ /**
779
+ * The resolved value.
780
+ */
781
+ readonly value: T;
782
+ }
783
+ /**
784
+ * A registry for storing resolved dependency values during parsing.
785
+ * This is used to pass dependency values from DependencySource options
786
+ * to DerivedValueParser options.
787
+ * @since 0.10.0
788
+ */
789
+ declare class DependencyRegistry implements DependencyRegistryLike {
790
+ private readonly values;
791
+ /**
792
+ * Registers a resolved dependency value.
793
+ * @param id The dependency ID.
794
+ * @param value The resolved value.
795
+ */
796
+ set<T>(id: symbol, value: T): void;
797
+ /**
798
+ * Gets a resolved dependency value.
799
+ * @param id The dependency ID.
800
+ * @returns The resolved value, or undefined if not found.
801
+ */
802
+ get<T>(id: symbol): T | undefined;
803
+ /**
804
+ * Checks if a dependency has been resolved.
805
+ * @param id The dependency ID.
806
+ * @returns `true` if the dependency has been resolved.
807
+ */
808
+ has(id: symbol): boolean;
809
+ /**
810
+ * Creates a copy of the registry.
811
+ */
812
+ clone(): DependencyRegistry;
813
+ }
814
+ /**
815
+ * Error types for dependency resolution failures.
816
+ * @since 0.10.0
817
+ */
818
+ type DependencyError = {
819
+ /**
820
+ * The dependency was used in multiple locations.
821
+ */
822
+ readonly kind: "duplicate";
823
+ readonly dependencyId: symbol;
824
+ readonly locations: readonly string[];
825
+ } | {
826
+ /**
827
+ * A derived parser references a dependency that was not provided.
828
+ */
829
+ readonly kind: "unresolved";
830
+ readonly dependencyId: symbol;
831
+ readonly derivedParserMetavar: string;
832
+ } | {
833
+ /**
834
+ * Circular dependency detected.
835
+ */
836
+ readonly kind: "circular";
837
+ readonly cycle: readonly symbol[];
838
+ };
839
+ /**
840
+ * Formats a {@link DependencyError} into a human-readable {@link Message}.
841
+ *
842
+ * @param error The dependency error to format.
843
+ * @returns A Message describing the error.
844
+ * @since 0.10.0
845
+ */
846
+ declare function formatDependencyError(error: DependencyError): Message;
538
847
  //#endregion
539
- export { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser };
848
+ export { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, PendingDependencySourceState, ResolvedDependency, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultDependencyValueSnapshot, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, getSnapshottedDefaultDependencyValues, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, singleDefaultValue, snapshotDefaultDependencyValues, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker };