@optique/core 0.10.0-dev.295 → 0.10.0-dev.297

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.
@@ -1,3 +1,4 @@
1
+ const require_message = require('./message.cjs');
1
2
 
2
3
  //#region src/dependency.ts
3
4
  /**
@@ -26,11 +27,23 @@ const DependencyId = Symbol.for("@optique/core/dependency/DependencyId");
26
27
  */
27
28
  const DependencyIds = Symbol.for("@optique/core/dependency/DependencyIds");
28
29
  /**
30
+ * A unique symbol used to store the default values function on derived parsers.
31
+ * This is used during partial dependency resolution to fill in missing values.
32
+ * @since 0.10.0
33
+ */
34
+ const DefaultValues = Symbol.for("@optique/core/dependency/DefaultValues");
35
+ /**
29
36
  * A unique symbol used to access the parseWithDependency method on derived parsers.
30
37
  * @since 0.10.0
31
38
  */
32
39
  const ParseWithDependency = Symbol.for("@optique/core/dependency/ParseWithDependency");
33
40
  /**
41
+ * A unique symbol used to access the suggestWithDependency method on derived parsers.
42
+ * This method generates suggestions using the provided dependency values instead of defaults.
43
+ * @since 0.10.0
44
+ */
45
+ const SuggestWithDependency = Symbol.for("@optique/core/dependency/SuggestWithDependency");
46
+ /**
34
47
  * Creates a dependency source from a {@link ValueParser}.
35
48
  *
36
49
  * A dependency source wraps an existing value parser and enables creating
@@ -194,13 +207,23 @@ function createSyncDerivedFromParser(sourceId, options) {
194
207
  [DerivedValueParserMarker]: true,
195
208
  [DependencyId]: sourceId,
196
209
  [DependencyIds]: allDependencyIds,
210
+ [DefaultValues]: options.defaultValues,
197
211
  parse(input) {
198
212
  const sourceValues = options.defaultValues();
199
213
  const derivedParser = options.factory(...sourceValues);
200
214
  return derivedParser.parse(input);
201
215
  },
202
216
  [ParseWithDependency](input, dependencyValue) {
203
- const derivedParser = options.factory(...dependencyValue);
217
+ let derivedParser;
218
+ try {
219
+ derivedParser = options.factory(...dependencyValue);
220
+ } catch (e) {
221
+ const msg = e instanceof Error ? e.message : String(e);
222
+ return {
223
+ success: false,
224
+ error: require_message.message`Factory error: ${msg}`
225
+ };
226
+ }
204
227
  return derivedParser.parse(input);
205
228
  },
206
229
  format(value) {
@@ -212,6 +235,16 @@ function createSyncDerivedFromParser(sourceId, options) {
212
235
  const sourceValues = options.defaultValues();
213
236
  const derivedParser = options.factory(...sourceValues);
214
237
  if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
238
+ },
239
+ *[SuggestWithDependency](prefix, dependencyValue) {
240
+ let derivedParser;
241
+ try {
242
+ derivedParser = options.factory(...dependencyValue);
243
+ } catch {
244
+ const sourceValues = options.defaultValues();
245
+ derivedParser = options.factory(...sourceValues);
246
+ }
247
+ if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
215
248
  }
216
249
  };
217
250
  }
@@ -227,13 +260,23 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
227
260
  [DerivedValueParserMarker]: true,
228
261
  [DependencyId]: sourceId,
229
262
  [DependencyIds]: allDependencyIds,
263
+ [DefaultValues]: options.defaultValues,
230
264
  parse(input) {
231
265
  const sourceValues = options.defaultValues();
232
266
  const derivedParser = options.factory(...sourceValues);
233
267
  return derivedParser.parse(input);
234
268
  },
235
269
  [ParseWithDependency](input, dependencyValue) {
236
- const derivedParser = options.factory(...dependencyValue);
270
+ let derivedParser;
271
+ try {
272
+ derivedParser = options.factory(...dependencyValue);
273
+ } catch (e) {
274
+ const msg = e instanceof Error ? e.message : String(e);
275
+ return Promise.resolve({
276
+ success: false,
277
+ error: require_message.message`Factory error: ${msg}`
278
+ });
279
+ }
237
280
  return derivedParser.parse(input);
238
281
  },
239
282
  format(value) {
@@ -245,6 +288,16 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
245
288
  const sourceValues = options.defaultValues();
246
289
  const derivedParser = options.factory(...sourceValues);
247
290
  if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
291
+ },
292
+ async *[SuggestWithDependency](prefix, dependencyValue) {
293
+ let derivedParser;
294
+ try {
295
+ derivedParser = options.factory(...dependencyValue);
296
+ } catch {
297
+ const sourceValues = options.defaultValues();
298
+ derivedParser = options.factory(...sourceValues);
299
+ }
300
+ if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
248
301
  }
249
302
  };
250
303
  }
@@ -260,13 +313,23 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
260
313
  [DerivedValueParserMarker]: true,
261
314
  [DependencyId]: sourceId,
262
315
  [DependencyIds]: allDependencyIds,
316
+ [DefaultValues]: options.defaultValues,
263
317
  parse(input) {
264
318
  const sourceValues = options.defaultValues();
265
319
  const derivedParser = options.factory(...sourceValues);
266
320
  return Promise.resolve(derivedParser.parse(input));
267
321
  },
268
322
  [ParseWithDependency](input, dependencyValue) {
269
- const derivedParser = options.factory(...dependencyValue);
323
+ let derivedParser;
324
+ try {
325
+ derivedParser = options.factory(...dependencyValue);
326
+ } catch (e) {
327
+ const msg = e instanceof Error ? e.message : String(e);
328
+ return Promise.resolve({
329
+ success: false,
330
+ error: require_message.message`Factory error: ${msg}`
331
+ });
332
+ }
270
333
  return Promise.resolve(derivedParser.parse(input));
271
334
  },
272
335
  format(value) {
@@ -278,6 +341,16 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
278
341
  const sourceValues = options.defaultValues();
279
342
  const derivedParser = options.factory(...sourceValues);
280
343
  if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
344
+ },
345
+ *[SuggestWithDependency](prefix, dependencyValue) {
346
+ let derivedParser;
347
+ try {
348
+ derivedParser = options.factory(...dependencyValue);
349
+ } catch {
350
+ const sourceValues = options.defaultValues();
351
+ derivedParser = options.factory(...sourceValues);
352
+ }
353
+ if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
281
354
  }
282
355
  };
283
356
  }
@@ -311,7 +384,16 @@ function createSyncDerivedParser(sourceId, options) {
311
384
  return derivedParser.parse(input);
312
385
  },
313
386
  [ParseWithDependency](input, dependencyValue) {
314
- const derivedParser = options.factory(dependencyValue);
387
+ let derivedParser;
388
+ try {
389
+ derivedParser = options.factory(dependencyValue);
390
+ } catch (e) {
391
+ const msg = e instanceof Error ? e.message : String(e);
392
+ return {
393
+ success: false,
394
+ error: require_message.message`Factory error: ${msg}`
395
+ };
396
+ }
315
397
  return derivedParser.parse(input);
316
398
  },
317
399
  format(value) {
@@ -323,6 +405,15 @@ function createSyncDerivedParser(sourceId, options) {
323
405
  const sourceValue = options.defaultValue();
324
406
  const derivedParser = options.factory(sourceValue);
325
407
  if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
408
+ },
409
+ *[SuggestWithDependency](prefix, dependencyValue) {
410
+ let derivedParser;
411
+ try {
412
+ derivedParser = options.factory(dependencyValue);
413
+ } catch {
414
+ derivedParser = options.factory(options.defaultValue());
415
+ }
416
+ if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
326
417
  }
327
418
  };
328
419
  }
@@ -342,7 +433,16 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
342
433
  return derivedParser.parse(input);
343
434
  },
344
435
  [ParseWithDependency](input, dependencyValue) {
345
- const derivedParser = options.factory(dependencyValue);
436
+ let derivedParser;
437
+ try {
438
+ derivedParser = options.factory(dependencyValue);
439
+ } catch (e) {
440
+ const msg = e instanceof Error ? e.message : String(e);
441
+ return Promise.resolve({
442
+ success: false,
443
+ error: require_message.message`Factory error: ${msg}`
444
+ });
445
+ }
346
446
  return derivedParser.parse(input);
347
447
  },
348
448
  format(value) {
@@ -354,6 +454,15 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
354
454
  const sourceValue = options.defaultValue();
355
455
  const derivedParser = options.factory(sourceValue);
356
456
  if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
457
+ },
458
+ async *[SuggestWithDependency](prefix, dependencyValue) {
459
+ let derivedParser;
460
+ try {
461
+ derivedParser = options.factory(dependencyValue);
462
+ } catch {
463
+ derivedParser = options.factory(options.defaultValue());
464
+ }
465
+ if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
357
466
  }
358
467
  };
359
468
  }
@@ -373,7 +482,16 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
373
482
  return Promise.resolve(derivedParser.parse(input));
374
483
  },
375
484
  [ParseWithDependency](input, dependencyValue) {
376
- const derivedParser = options.factory(dependencyValue);
485
+ let derivedParser;
486
+ try {
487
+ derivedParser = options.factory(dependencyValue);
488
+ } catch (e) {
489
+ const msg = e instanceof Error ? e.message : String(e);
490
+ return Promise.resolve({
491
+ success: false,
492
+ error: require_message.message`Factory error: ${msg}`
493
+ });
494
+ }
377
495
  return Promise.resolve(derivedParser.parse(input));
378
496
  },
379
497
  format(value) {
@@ -385,6 +503,15 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
385
503
  const sourceValue = options.defaultValue();
386
504
  const derivedParser = options.factory(sourceValue);
387
505
  if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
506
+ },
507
+ *[SuggestWithDependency](prefix, dependencyValue) {
508
+ let derivedParser;
509
+ try {
510
+ derivedParser = options.factory(dependencyValue);
511
+ } catch {
512
+ derivedParser = options.factory(options.defaultValue());
513
+ }
514
+ if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
388
515
  }
389
516
  };
390
517
  }
@@ -416,12 +543,15 @@ function isDeferredParseState(value) {
416
543
  */
417
544
  function createDeferredParseState(rawInput, parser, preliminaryResult) {
418
545
  const multipleIds = DependencyIds in parser ? parser[DependencyIds] : void 0;
546
+ const defaultValuesFn = DefaultValues in parser ? parser[DefaultValues] : void 0;
547
+ const defaultVals = defaultValuesFn ? defaultValuesFn() : void 0;
419
548
  return {
420
549
  [DeferredParseMarker]: true,
421
550
  rawInput,
422
551
  parser,
423
552
  dependencyId: parser[DependencyId],
424
553
  dependencyIds: multipleIds,
554
+ defaultValues: defaultVals,
425
555
  preliminaryResult
426
556
  };
427
557
  }
@@ -492,6 +622,28 @@ function createPendingDependencySourceState(dependencyId) {
492
622
  */
493
623
  const WrappedDependencySourceMarker = Symbol.for("@optique/core/dependency/WrappedDependencySourceMarker");
494
624
  /**
625
+ * A unique symbol used to indicate that a wrapper transforms the dependency
626
+ * source value. This is used by withDefault to determine whether its default
627
+ * value should be registered as the dependency value.
628
+ *
629
+ * When a wrapper has this marker set to `true`, it means the wrapper transforms
630
+ * the dependency source value (e.g., via map()), so the wrapper's output is NOT
631
+ * a valid dependency source value.
632
+ *
633
+ * @since 0.10.0
634
+ */
635
+ const TransformsDependencyValueMarker = Symbol.for("@optique/core/dependency/TransformsDependencyValueMarker");
636
+ /**
637
+ * Checks if a parser transforms the dependency value (has TransformsDependencyValueMarker).
638
+ *
639
+ * @param parser The parser to check.
640
+ * @returns `true` if the parser transforms the dependency value.
641
+ * @since 0.10.0
642
+ */
643
+ function transformsDependencyValue(parser) {
644
+ return typeof parser === "object" && parser !== null && TransformsDependencyValueMarker in parser && parser[TransformsDependencyValueMarker] === true;
645
+ }
646
+ /**
495
647
  * Checks if a parser wraps a dependency source (has WrappedDependencySourceMarker).
496
648
  *
497
649
  * @param parser The parser to check.
@@ -567,6 +719,7 @@ function formatDependencyError(error) {
567
719
  }
568
720
 
569
721
  //#endregion
722
+ exports.DefaultValues = DefaultValues;
570
723
  exports.DeferredParseMarker = DeferredParseMarker;
571
724
  exports.DependencyId = DependencyId;
572
725
  exports.DependencyIds = DependencyIds;
@@ -576,6 +729,8 @@ exports.DependencySourceStateMarker = DependencySourceStateMarker;
576
729
  exports.DerivedValueParserMarker = DerivedValueParserMarker;
577
730
  exports.ParseWithDependency = ParseWithDependency;
578
731
  exports.PendingDependencySourceStateMarker = PendingDependencySourceStateMarker;
732
+ exports.SuggestWithDependency = SuggestWithDependency;
733
+ exports.TransformsDependencyValueMarker = TransformsDependencyValueMarker;
579
734
  exports.WrappedDependencySourceMarker = WrappedDependencySourceMarker;
580
735
  exports.createDeferredParseState = createDeferredParseState;
581
736
  exports.createDependencySourceState = createDependencySourceState;
@@ -590,4 +745,5 @@ exports.isDependencySource = isDependencySource;
590
745
  exports.isDependencySourceState = isDependencySourceState;
591
746
  exports.isDerivedValueParser = isDerivedValueParser;
592
747
  exports.isPendingDependencySourceState = isPendingDependencySourceState;
593
- exports.isWrappedDependencySource = isWrappedDependencySource;
748
+ exports.isWrappedDependencySource = isWrappedDependencySource;
749
+ exports.transformsDependencyValue = transformsDependencyValue;
@@ -1,7 +1,7 @@
1
1
  import { NonEmptyString } from "./nonempty.cjs";
2
2
  import { Message } from "./message.cjs";
3
3
  import { ValueParser, ValueParserResult } from "./valueparser.cjs";
4
- import { Mode } from "./parser.cjs";
4
+ import { Mode, Suggestion } from "./parser.cjs";
5
5
 
6
6
  //#region src/dependency.d.ts
7
7
 
@@ -30,11 +30,23 @@ declare const DependencyId: unique symbol;
30
30
  * @since 0.10.0
31
31
  */
32
32
  declare const DependencyIds: unique symbol;
33
+ /**
34
+ * A unique symbol used to store the default values function on derived parsers.
35
+ * This is used during partial dependency resolution to fill in missing values.
36
+ * @since 0.10.0
37
+ */
38
+ declare const DefaultValues: unique symbol;
33
39
  /**
34
40
  * A unique symbol used to access the parseWithDependency method on derived parsers.
35
41
  * @since 0.10.0
36
42
  */
37
43
  declare const ParseWithDependency: unique symbol;
44
+ /**
45
+ * A unique symbol used to access the suggestWithDependency method on derived parsers.
46
+ * This method generates suggestions using the provided dependency values instead of defaults.
47
+ * @since 0.10.0
48
+ */
49
+ declare const SuggestWithDependency: unique symbol;
38
50
  /**
39
51
  * Combines two modes into a single mode.
40
52
  * If either mode is async, the result is async.
@@ -327,6 +339,12 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
327
339
  * @internal
328
340
  */
329
341
  readonly [DependencyIds]?: readonly symbol[];
342
+ /**
343
+ * The default values function for this parser's dependencies.
344
+ * Used during partial dependency resolution to fill in missing values.
345
+ * @internal
346
+ */
347
+ readonly [DefaultValues]?: () => readonly unknown[];
330
348
  /**
331
349
  * Parses the input using the actual dependency value instead of the default.
332
350
  * This method is used during dependency resolution in `complete()`.
@@ -337,6 +355,16 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
337
355
  * @internal
338
356
  */
339
357
  readonly [ParseWithDependency]: (input: string, dependencyValue: S) => ValueParserResult<T> | Promise<ValueParserResult<T>>;
358
+ /**
359
+ * Generates suggestions using the provided dependency value instead of the default.
360
+ * This method is used during shell completion when dependency sources have been parsed.
361
+ *
362
+ * @param prefix The input prefix to filter suggestions.
363
+ * @param dependencyValue The resolved dependency value.
364
+ * @returns An iterable of suggestions.
365
+ * @internal
366
+ */
367
+ readonly [SuggestWithDependency]?: (prefix: string, dependencyValue: S) => Iterable<Suggestion> | AsyncIterable<Suggestion>;
340
368
  }
341
369
  /**
342
370
  * Creates a dependency source from a {@link ValueParser}.
@@ -484,6 +512,12 @@ interface DeferredParseState<T = unknown> {
484
512
  * If present, this is used instead of `dependencyId`.
485
513
  */
486
514
  readonly dependencyIds?: readonly symbol[];
515
+ /**
516
+ * The default values to use for dependencies that are not provided.
517
+ * For multi-dependency parsers, this is a tuple of default values in order.
518
+ * For single-dependency parsers, this is the single default value.
519
+ */
520
+ readonly defaultValues?: readonly unknown[];
487
521
  /**
488
522
  * The preliminary parse result using the default dependency value.
489
523
  * This is used as a fallback if dependency resolution is not needed
@@ -602,6 +636,28 @@ declare function createPendingDependencySourceState(dependencyId: symbol): Pendi
602
636
  * @since 0.10.0
603
637
  */
604
638
  declare const WrappedDependencySourceMarker: unique symbol;
639
+ /**
640
+ * A unique symbol used to indicate that a wrapper transforms the dependency
641
+ * source value. This is used by withDefault to determine whether its default
642
+ * value should be registered as the dependency value.
643
+ *
644
+ * When a wrapper has this marker set to `true`, it means the wrapper transforms
645
+ * the dependency source value (e.g., via map()), so the wrapper's output is NOT
646
+ * a valid dependency source value.
647
+ *
648
+ * @since 0.10.0
649
+ */
650
+ declare const TransformsDependencyValueMarker: unique symbol;
651
+ /**
652
+ * Checks if a parser transforms the dependency value (has TransformsDependencyValueMarker).
653
+ *
654
+ * @param parser The parser to check.
655
+ * @returns `true` if the parser transforms the dependency value.
656
+ * @since 0.10.0
657
+ */
658
+ declare function transformsDependencyValue(parser: unknown): parser is {
659
+ [TransformsDependencyValueMarker]: true;
660
+ };
605
661
  /**
606
662
  * Checks if a parser wraps a dependency source (has WrappedDependencySourceMarker).
607
663
  *
@@ -691,4 +747,4 @@ type DependencyError = {
691
747
  */
692
748
  declare function formatDependencyError(error: DependencyError): Message;
693
749
  //#endregion
694
- export { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseMarker, DeferredParseState, DependencyError, DependencyId, DependencyIds, DependencyMode, DependencyRegistry, DependencySource, DependencySourceMarker, DependencySourceState, DependencySourceStateMarker, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DerivedValueParserMarker, ParseWithDependency, PendingDependencySourceState, PendingDependencySourceStateMarker, ResolvedDependency, WrappedDependencySourceMarker, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependency, deriveFrom, deriveFromAsync, deriveFromSync, formatDependencyError, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource };
750
+ export { AnyDependencySource, CombineMode, CombinedDependencyMode, DefaultValues, DeferredParseMarker, DeferredParseState, DependencyError, DependencyId, DependencyIds, DependencyMode, DependencyRegistry, DependencySource, DependencySourceMarker, DependencySourceState, DependencySourceStateMarker, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DerivedValueParserMarker, ParseWithDependency, PendingDependencySourceState, PendingDependencySourceStateMarker, ResolvedDependency, SuggestWithDependency, TransformsDependencyValueMarker, WrappedDependencySourceMarker, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependency, deriveFrom, deriveFromAsync, deriveFromSync, formatDependencyError, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, transformsDependencyValue };
@@ -1,7 +1,7 @@
1
1
  import { NonEmptyString } from "./nonempty.js";
2
2
  import { Message } from "./message.js";
3
3
  import { ValueParser, ValueParserResult } from "./valueparser.js";
4
- import { Mode } from "./parser.js";
4
+ import { Mode, Suggestion } from "./parser.js";
5
5
 
6
6
  //#region src/dependency.d.ts
7
7
 
@@ -30,11 +30,23 @@ declare const DependencyId: unique symbol;
30
30
  * @since 0.10.0
31
31
  */
32
32
  declare const DependencyIds: unique symbol;
33
+ /**
34
+ * A unique symbol used to store the default values function on derived parsers.
35
+ * This is used during partial dependency resolution to fill in missing values.
36
+ * @since 0.10.0
37
+ */
38
+ declare const DefaultValues: unique symbol;
33
39
  /**
34
40
  * A unique symbol used to access the parseWithDependency method on derived parsers.
35
41
  * @since 0.10.0
36
42
  */
37
43
  declare const ParseWithDependency: unique symbol;
44
+ /**
45
+ * A unique symbol used to access the suggestWithDependency method on derived parsers.
46
+ * This method generates suggestions using the provided dependency values instead of defaults.
47
+ * @since 0.10.0
48
+ */
49
+ declare const SuggestWithDependency: unique symbol;
38
50
  /**
39
51
  * Combines two modes into a single mode.
40
52
  * If either mode is async, the result is async.
@@ -327,6 +339,12 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
327
339
  * @internal
328
340
  */
329
341
  readonly [DependencyIds]?: readonly symbol[];
342
+ /**
343
+ * The default values function for this parser's dependencies.
344
+ * Used during partial dependency resolution to fill in missing values.
345
+ * @internal
346
+ */
347
+ readonly [DefaultValues]?: () => readonly unknown[];
330
348
  /**
331
349
  * Parses the input using the actual dependency value instead of the default.
332
350
  * This method is used during dependency resolution in `complete()`.
@@ -337,6 +355,16 @@ interface DerivedValueParser<M extends Mode = "sync", T = unknown, S = unknown>
337
355
  * @internal
338
356
  */
339
357
  readonly [ParseWithDependency]: (input: string, dependencyValue: S) => ValueParserResult<T> | Promise<ValueParserResult<T>>;
358
+ /**
359
+ * Generates suggestions using the provided dependency value instead of the default.
360
+ * This method is used during shell completion when dependency sources have been parsed.
361
+ *
362
+ * @param prefix The input prefix to filter suggestions.
363
+ * @param dependencyValue The resolved dependency value.
364
+ * @returns An iterable of suggestions.
365
+ * @internal
366
+ */
367
+ readonly [SuggestWithDependency]?: (prefix: string, dependencyValue: S) => Iterable<Suggestion> | AsyncIterable<Suggestion>;
340
368
  }
341
369
  /**
342
370
  * Creates a dependency source from a {@link ValueParser}.
@@ -484,6 +512,12 @@ interface DeferredParseState<T = unknown> {
484
512
  * If present, this is used instead of `dependencyId`.
485
513
  */
486
514
  readonly dependencyIds?: readonly symbol[];
515
+ /**
516
+ * The default values to use for dependencies that are not provided.
517
+ * For multi-dependency parsers, this is a tuple of default values in order.
518
+ * For single-dependency parsers, this is the single default value.
519
+ */
520
+ readonly defaultValues?: readonly unknown[];
487
521
  /**
488
522
  * The preliminary parse result using the default dependency value.
489
523
  * This is used as a fallback if dependency resolution is not needed
@@ -602,6 +636,28 @@ declare function createPendingDependencySourceState(dependencyId: symbol): Pendi
602
636
  * @since 0.10.0
603
637
  */
604
638
  declare const WrappedDependencySourceMarker: unique symbol;
639
+ /**
640
+ * A unique symbol used to indicate that a wrapper transforms the dependency
641
+ * source value. This is used by withDefault to determine whether its default
642
+ * value should be registered as the dependency value.
643
+ *
644
+ * When a wrapper has this marker set to `true`, it means the wrapper transforms
645
+ * the dependency source value (e.g., via map()), so the wrapper's output is NOT
646
+ * a valid dependency source value.
647
+ *
648
+ * @since 0.10.0
649
+ */
650
+ declare const TransformsDependencyValueMarker: unique symbol;
651
+ /**
652
+ * Checks if a parser transforms the dependency value (has TransformsDependencyValueMarker).
653
+ *
654
+ * @param parser The parser to check.
655
+ * @returns `true` if the parser transforms the dependency value.
656
+ * @since 0.10.0
657
+ */
658
+ declare function transformsDependencyValue(parser: unknown): parser is {
659
+ [TransformsDependencyValueMarker]: true;
660
+ };
605
661
  /**
606
662
  * Checks if a parser wraps a dependency source (has WrappedDependencySourceMarker).
607
663
  *
@@ -691,4 +747,4 @@ type DependencyError = {
691
747
  */
692
748
  declare function formatDependencyError(error: DependencyError): Message;
693
749
  //#endregion
694
- export { AnyDependencySource, CombineMode, CombinedDependencyMode, DeferredParseMarker, DeferredParseState, DependencyError, DependencyId, DependencyIds, DependencyMode, DependencyRegistry, DependencySource, DependencySourceMarker, DependencySourceState, DependencySourceStateMarker, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DerivedValueParserMarker, ParseWithDependency, PendingDependencySourceState, PendingDependencySourceStateMarker, ResolvedDependency, WrappedDependencySourceMarker, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependency, deriveFrom, deriveFromAsync, deriveFromSync, formatDependencyError, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource };
750
+ export { AnyDependencySource, CombineMode, CombinedDependencyMode, DefaultValues, DeferredParseMarker, DeferredParseState, DependencyError, DependencyId, DependencyIds, DependencyMode, DependencyRegistry, DependencySource, DependencySourceMarker, DependencySourceState, DependencySourceStateMarker, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DerivedValueParserMarker, ParseWithDependency, PendingDependencySourceState, PendingDependencySourceStateMarker, ResolvedDependency, SuggestWithDependency, TransformsDependencyValueMarker, WrappedDependencySourceMarker, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependency, deriveFrom, deriveFromAsync, deriveFromSync, formatDependencyError, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, transformsDependencyValue };