@gunshi/shared 1.0.0-beta.0 → 1.0.0-beta.1

package/lib/index.d.ts

@@ -55,9 +55,6 @@ interface ArgToken {
    */
   inlineValue?: boolean | undefined;
 }
-/**
- * Parser Options.
- */
 //#endregion
 //#region ../../node_modules/.pnpm/args-tokens@1.0.0-beta.1/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
@@ -638,7 +635,7 @@ interface Args {
  *
  * @typeParam T - {@link Args | Arguments} which is an object that defines the command line arguments.
  */
-type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
+type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]>; }> : {
   [option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
 };
 /**
@@ -670,7 +667,7 @@ type ResolveOptionValue<A extends ArgSchema, T> = A['multiple'] extends true ? T
  *
  * @internal
  */
-type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: IsPresentArg<A[Arg]> extends true ? unknown : V[Arg] } & { -readonly [Arg in keyof A as IsPresentArg<A[Arg]> extends true ? Arg : never]: V[Arg] } extends (infer P) ? { [K in keyof P]: P[K] } : never;
+type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: IsPresentArg<A[Arg]> extends true ? unknown : V[Arg]; } & { -readonly [Arg in keyof A as IsPresentArg<A[Arg]> extends true ? Arg : never]: V[Arg]; } extends (infer P) ? { [K in keyof P]: P[K]; } : never;
 /**
  * Whether an argument with the schema `S` has a value: with a default, with `required: true` or as
  * a required positional argument. For a union of schemas, only when each schema of the union has
@@ -678,16 +675,6 @@ type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -r
  * value, as {@link FilterArgs} does.
  */
 type IsPresentArg<S extends ArgSchema> = S extends ArgSchema ? true extends (S['default'] extends {} ? true : S['required'] extends true ? true : false) ? true : IsRequiredPositionalArg<S> : never;
-/**
- * Filters the arguments based on their default values.
- *
- * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
- * @typeParam V - Resolvable argument values.
- * @typeParam K - Key of the {@link ArgSchema | argument schema} to filter by.
- *
- * @internal
- */
-
 type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positional' ? A['multiple'] extends true ? A['required'] extends true ? true : false : MayBeUnrequired<A> extends true ? A['default'] extends {} ? true : false : true : false;
 /**
  * Whether the `required` of `A` may be `false`. An optional `required` of type `boolean`, as in
@@ -698,10 +685,6 @@ type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positiona
 type MayBeUnrequired<A extends ArgSchema> = false extends A['required'] ? [A] extends [{
   required: unknown;
 }] ? true : boolean | undefined extends A['required'] ? false : true : false;
-/**
- * An arguments for {@link resolveArgs | resolve arguments}.
- */
-
 /**
  * Tracks which arguments were explicitly provided by the user.
  *
@@ -714,7 +697,7 @@ type MayBeUnrequired<A extends ArgSchema> = false extends A['required'] ? [A] ex
  *
  * @typeParam A - {@link Args | Arguments}, which is an object that defines the command line arguments.
  */
-type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
+type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean; };
 //#endregion
 //#region ../gunshi/src/types.d.ts
 /**
@@ -1366,23 +1349,24 @@ type CommonArgType = {
 declare const COMMON_ARGS: CommonArgType;
 declare const COMMAND_BUILTIN_RESOURCE_KEYS: readonly ["USAGE", "COMMAND", "SUBCOMMAND", "COMMANDS", "ARGUMENTS", "OPTIONS", "EXAMPLES", "FORMORE", "NEGATABLE", "DEFAULT", "CHOICES"];
 declare const ARG_ERROR_RESOURCE_KEYS: readonly ["err:arg:required-option", "err:arg:required-positional", "err:arg:invalid-type", "err:arg:invalid-choice", "err:arg:custom-parse", "err:arg:unknown-option", "err:arg:unexpected-value", "err:arg:missing-value", "err:arg:conflict", "err:arg:invalid-default"];
+declare const ARG_ERROR_HINT_RESOURCE_KEYS: readonly ["err:arg:missing-value:hint"];
 declare const COMMAND_ERROR_RESOURCE_KEYS: readonly ["err:cmd:not-found", "err:cmd:ambiguous", "err:cmd:inconsistent-options", "err:cmd:lazy-schema-mismatch"];
 declare const SUGGESTION_ERROR_RESOURCE_KEYS: readonly ["err:suggestion:did-you-mean"];
 //#endregion
 //#region src/types.d.ts
-type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
+type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]; };
 /**
- * Make all properties in T deeply writeable (not readonly)
+ * Make all properties in T deeply writable (not readonly)
  */
-type DeepWriteable<T> = T extends ((...args: any) => any) ? T : T extends readonly (infer U)[] ? DeepWriteable<U>[] : T extends object ? { -readonly [P in keyof T]: DeepWriteable<T[P]> } : T;
+type DeepWriteable<T> = T extends ((...args: any) => any) ? T : T extends readonly (infer U)[] ? DeepWriteable<U>[] : T extends object ? { -readonly [P in keyof T]: DeepWriteable<T[P]>; } : T;
 /**
  * Remove index signature from object or record type.
  */
-type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K] }>;
+type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K]; }>;
 /**
  * Resolve a key on {@link Args}.
  */
-type KeyOfArgs<A extends Args> = keyof A | { [K in keyof A]: A[K]['type'] extends 'boolean' ? A[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never }[keyof A];
+type KeyOfArgs<A extends Args> = keyof A | { [K in keyof A]: A[K]['type'] extends 'boolean' ? A[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never; }[keyof A];
 /**
  * Generate a namespaced key.
  */
@@ -1399,6 +1383,10 @@ type CommandBuiltinResourceKeys = (typeof COMMAND_BUILTIN_RESOURCE_KEYS)[number]
  * Args validation error resource keys.
  */
 type ArgErrorResourceKeys = (typeof ARG_ERROR_RESOURCE_KEYS)[number];
+/**
+ * Resource keys of the hints that follow an args validation error.
+ */
+type ArgErrorHintResourceKeys = (typeof ARG_ERROR_HINT_RESOURCE_KEYS)[number];
 /**
  * Command validation error resource keys.
  */
@@ -1410,7 +1398,7 @@ type SuggestionErrorResourceKeys = (typeof SUGGESTION_ERROR_RESOURCE_KEYS)[numbe
 /**
  * Error resource keys.
  */
-type ErrorResourceKeys = ArgErrorResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
+type ErrorResourceKeys = ArgErrorResourceKeys | ArgErrorHintResourceKeys | CommandErrorResourceKeys | SuggestionErrorResourceKeys;
 /**
  * Built-in resource keys.
  */
@@ -1433,21 +1421,17 @@ type CommandArgKeys<A extends Args, C = {}, K extends string = GenerateNamespace
 /**
  * Resolve translation keys for command context.
  */
-type ResolveTranslationKeys<A extends Args, C = {},
-// for CommandContext
-E extends Record<string, string> = {},
-// for extended resources
-R extends string = keyof RemovedIndex<E>, T extends string = (C extends {
+type ResolveTranslationKeys<A extends Args, C = {} // for CommandContext
+, E extends Record<string, string> = {} // for extended resources
+, R extends string = keyof RemovedIndex<E>, T extends string = C extends {
   name: infer N;
-} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys), O = CommandArgKeys<A, C>> = ErrorResourceKeys | CommandBuiltinKeys | O | T;
+} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys, O = CommandArgKeys<A, C>> = ErrorResourceKeys | CommandBuiltinKeys | O | T;
 /**
  * Translation function interface
  */
-interface Translation<A extends Args, C = {},
-// for CommandContext
-E extends Record<string, string> = {},
-// for extended resources
-K = ResolveTranslationKeys<A, C, E>> {
+interface Translation<A extends Args, C = {} // for CommandContext
+, E extends Record<string, string> = {} // for extended resources
+, K = ResolveTranslationKeys<A, C, E>> {
   (key: K, values?: Record<string, unknown>): string;
 }
 //#endregion
@@ -1459,9 +1443,8 @@ K = ResolveTranslationKeys<A, C, E>> {
  * @typeParam C - Additional context type for command localization.
  * @typeParam E - Extended resource keys type.
  */
-interface Localization<A extends Args, C = {},
-// for CommandContext
-E extends Record<string, string> = {}> {
+interface Localization<A extends Args, C = {} // for CommandContext
+, E extends Record<string, string> = {}> {
   <K = ResolveTranslationKeys<A, C, E>>(key: K, values?: Record<string, unknown>): Promise<string>;
 }
 /**
@@ -1478,11 +1461,9 @@ E extends Record<string, string> = {}> {
  * @param translate - Translation function
  * @returns Localizable function
  */
-declare function localizable<A extends Args, C = {},
-// for CommandContext
-E extends Record<string, string> = {},
-// for extended resources
-K = ResolveTranslationKeys<A, C, E>>(ctx: CommandContext, cmd: Command, translate?: Translation<A, C, E, K>): Localization<A, C, E>;
+declare function localizable<A extends Args, C = {} // for CommandContext
+, E extends Record<string, string> = {} // for extended resources
+, K = ResolveTranslationKeys<A, C, E>>(ctx: CommandContext, cmd: Command, translate?: Translation<A, C, E, K>): Localization<A, C, E>;
 /**
  * Format a resource message by replacing placeholder values.
  *
@@ -1492,7 +1473,7 @@ K = ResolveTranslationKeys<A, C, E>>(ctx: CommandContext, cmd: Command, translat
  */
 declare function formatResource(resource: string | undefined, values?: Record<string, unknown>): string | undefined;
 //#endregion
-//#region ../resources/locales/en-US.d.ts
+//#region ../resources/locales/en-US.json.d.ts
 declare const _exports: {
   COMMAND: string;
   COMMANDS: string;
@@ -1515,6 +1496,7 @@ declare const _exports: {
   "err:arg:unknown-option": string;
   "err:arg:unexpected-value": string;
   "err:arg:missing-value": string;
+  "err:arg:missing-value:hint": string;
   "err:arg:conflict": string;
   "err:arg:invalid-default": string;
   "err:cmd:not-found": string;
@@ -1560,7 +1542,7 @@ declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K e
  * @param name - The command name.
  * @returns Prefixed non-built-in key.
  */
-declare function resolveKey<T extends Record<string, string> = {}, K extends string = (keyof T extends string ? keyof T : string)>(key: K, name?: string): string;
+declare function resolveKey<T extends Record<string, string> = {}, K extends string = keyof T extends string ? keyof T : string>(key: K, name?: string): string;
 /**
  * Resolve command examples.
  *
@@ -1610,11 +1592,4 @@ declare function resolveDisplayName(name: string, schema: ArgSchema, toKebab?: b
  */
 declare function resolveOptionNames(args: Args, toKebab?: boolean): Set<string>;
 //#endregion
-//#region src/index.d.ts
-/**
-* @author kazuya kawaguchi (a.k.a. kazupon)
-* @license MIT
-*/
-
-//#endregion
-export { ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, ArgErrorResourceKeys, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResource, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandErrorResourceKeys, DeepWriteable, _exports as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, ErrorResourceKeys, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, SUGGESTION_ERROR_RESOURCE_KEYS, SuggestionErrorResourceKeys, Translation, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveKey, resolveLazyCommand, resolveOptionNames };
+export { ARG_ERROR_HINT_RESOURCE_KEYS, ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, type ArgErrorHintResourceKeys, type ArgErrorResourceKeys, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, type BuiltinResource, type BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, type CommandArgKeys, type CommandBuiltinArgsKeys, type CommandBuiltinKeys, type CommandBuiltinResourceKeys, type CommandErrorResourceKeys, type DeepWriteable, _exports as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, type ErrorResourceKeys, type GenerateNamespacedKey, type KeyOfArgs, Localization, PLUGIN_PREFIX, type RemovedIndex, type ResolveTranslationKeys, SUGGESTION_ERROR_RESOURCE_KEYS, type SuggestionErrorResourceKeys, type Translation, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveKey, resolveLazyCommand, resolveOptionNames };

package/lib/index.js

@@ -225,6 +225,7 @@ const ARG_ERROR_RESOURCE_KEYS = [
 	"err:arg:conflict",
 	"err:arg:invalid-default"
 ];
+const ARG_ERROR_HINT_RESOURCE_KEYS = ["err:arg:missing-value:hint"];
 const COMMAND_ERROR_RESOURCE_KEYS = [
 	"err:cmd:not-found",
 	"err:cmd:ambiguous",
@@ -249,13 +250,14 @@ var en_US_default = {
 	help: "Display this help message",
 	version: "Display this version",
 	"err:arg:required-option": "Optional argument {$displayName} is required",
-	"err:arg:required-positional": "Positional argument {$name} is required",
+	"err:arg:required-positional": "Positional argument {$displayName} is required",
 	"err:arg:invalid-type": "Invalid value for {$displayName}: expected {$expected}",
 	"err:arg:invalid-choice": "Invalid value for {$displayName}: expected one of {$choices}",
 	"err:arg:custom-parse": "Invalid value for {$displayName}: {$reason}",
 	"err:arg:unknown-option": "Unknown option: {$rawName}",
 	"err:arg:unexpected-value": "Optional argument {$displayName} does not take a value",
 	"err:arg:missing-value": "Optional argument {$displayName} requires a value",
+	"err:arg:missing-value:hint": "(to pass '{$next}' as its value, write '{$suggestion}')",
 	"err:arg:conflict": "{$displayName} conflicts with {$conflictDisplayName}",
 	"err:arg:invalid-default": "Invalid default for {$displayName}: {$actual} is not one of {$choices}",
 	"err:cmd:not-found": "Command not found: {$commandName}",
@@ -445,4 +447,4 @@ function formatResource(resource, values = Object.create(null)) {
 * @license MIT
 */
 //#endregion
-export { ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, PLUGIN_PREFIX, SUGGESTION_ERROR_RESOURCE_KEYS, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveKey, resolveLazyCommand, resolveOptionNames };
+export { ARG_ERROR_HINT_RESOURCE_KEYS, ARG_ERROR_RESOURCE_KEYS, ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMAND_ERROR_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, ERROR_PREFIX, ERROR_PREFIX_AND_KEY_SEPARATOR, PLUGIN_PREFIX, SUGGESTION_ERROR_RESOURCE_KEYS, create, deepFreeze, formatResource, getCommandSubCommands, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveCommandArgs, resolveDisplayName, resolveExamples, resolveKey, resolveLazyCommand, resolveOptionNames };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/shared",
   "description": "shared utils for gunshi",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -50,13 +50,13 @@
     }
   },
   "devDependencies": {
+    "@gunshi/resources": "1.0.0-beta.1",
     "deno": "^2.7.14",
+    "gunshi": "1.0.0-beta.1",
     "jsr": "^0.14.3",
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
-    "tsdown": "0.21.0",
-    "@gunshi/resources": "1.0.0-beta.0",
-    "gunshi": "1.0.0-beta.0"
+    "tsdown": "0.22.14"
   },
   "scripts": {
     "build": "tsdown",