feat: support option choice inference from union of literals

Author: zojize

README.md

@@ -132,8 +132,6 @@ export default (name: string, style: string) => {
 }
 ```
 
-> **Coming Soon:** Support choices inferred from Typescript literal union types
-
 ## Web Interface
 
 Access the command management interface at `/discord/slash-commands` in your application. The interface provides:
@@ -272,12 +270,7 @@ Here's what's planned for future releases:
 
 ## Contribution
 
-<details>
-  <summary>Local development</summary>
-
-  Refer to the official [Module Author Guide](https://nuxt.com/docs/guide/going-further/modules)
-
-</details>
+Refer to the official [Module Author Guide](https://nuxt.com/docs/guide/going-further/modules)
 
 ## Acknowledgement
 

playground/discord/commands/greet.ts

@@ -4,25 +4,17 @@
  * @param name The person to greet
  * @param style The greeting style
  */
-export default (name: string, style: string) => {
+export default (name: string, style: 'formal' | 'casual' | 'enthusiastic') => {
   describeOption(name, {
     minLength: 1,
     maxLength: 32,
   })
 
-  describeOption(style, {
-    choices: [
-      { name: 'Formal', value: 'formal' },
-      { name: 'Casual', value: 'casual' },
-      { name: 'Enthusiastic', value: 'enthusiastic' },
-    ],
-  })
-
   const greetings = {
     formal: `Good day, ${name}.`,
     casual: `Hey ${name}!`,
     enthusiastic: `HELLO THERE ${name.toUpperCase()}!!! 🎉`,
   } as const
 
-  return greetings[style as keyof typeof greetings]
+  return greetings[style]
 }

src/runtime/client/pages/slash-commands.vue

@@ -120,7 +120,7 @@ const commandsWithStatus = computed(() => {
       name: cmd.name,
       description: cmd.description,
       path: 'unknown',
-      options: (cmd.options as SlashCommandOption[]),
+      options: (cmd.options as SlashCommandOption[]) ?? [],
       status: 'removed' as const,
       remote: cmd,
     })),
@@ -277,7 +277,6 @@ const statusClasses = {
           />
         </div>
 
-        <!-- <UButton icon="i-lucide-circle" @click="test" /> -->
         <UButton
           v-if="!allSynced"
           :icon="pendingSync ? 'i-lucide-refresh-ccw' : 'i-lucide-cloud-upload'"
@@ -398,8 +397,12 @@ const statusClasses = {
                   <!-- Choices dropdown -->
                   <UDropdownMenu
                     v-if="'choices' in option && option.choices && option.choices.length > 0"
-                    :items="option.choices.map(choice => ({ label: choice.name }))"
+                    :items="option.choices.map(choice => ({
+                      label: choice.name,
+                      value: typeof choice.value === 'string' ? `'${choice.value}'` : choice.value,
+                    }))"
                     :popper="{ placement: 'bottom-start' }"
+                    :ui="{ itemTrailing: 'text-sm text-gray-500 dark:text-gray-400' }"
                   >
                     <UBadge
                       v-if="'choices' in option && option.choices && option.choices.length > 0"
@@ -409,6 +412,9 @@ const statusClasses = {
                       size="sm"
                       class="hover:cursor-pointer"
                     />
+                    <template #item-trailing="{ item: { value } }">
+                      {{ value }}
+                    </template>
                   </UDropdownMenu>
                 </div>
 

src/runtime/server/utils/describeOption.ts

@@ -9,37 +9,37 @@ export interface DescribeOptionOptionsBase {
   description?: string
 }
 
-export interface IntegerOption extends DescribeOptionOptionsBase {
+export interface IntegerOption<T extends number = number> extends DescribeOptionOptionsBase {
   /** The minimum value for the integer option. */
   min?: number
 
   /** The maximum value for the integer option. */
   max?: number
 
   /** An array of choices for the integer option. */
-  choices?: APIApplicationCommandOptionChoice<number>[]
+  choices?: APIApplicationCommandOptionChoice<T>[]
 }
 
-export interface NumberOption extends DescribeOptionOptionsBase {
+export interface NumberOption<T extends number = number> extends DescribeOptionOptionsBase {
   /** The minimum value for the number option. */
   min?: number
 
   /** The maximum value for the number option. */
   max?: number
 
   /** An array of choices for the number option. */
-  choices?: APIApplicationCommandOptionChoice<number>[]
+  choices?: APIApplicationCommandOptionChoice<T>[]
 }
 
-export interface StringOption extends DescribeOptionOptionsBase {
+export interface StringOption<T extends string = string> extends DescribeOptionOptionsBase {
   /** The minimum length of the string option. */
   minLength?: number
 
   /** The maximum length of the string option. */
   maxLength?: number
 
   /** An array of choices for the string option. */
-  choices?: APIApplicationCommandOptionChoice<string>[]
+  choices?: APIApplicationCommandOptionChoice<T>[]
 }
 
 export type DescribeOptionOptions
@@ -48,12 +48,33 @@ export type DescribeOptionOptions
     | StringOption
 
 /**
+ * A compiler macro that describes a slash command option. Used for defining
+ * metadata for registering slash command options. Options defined here will
+ * take higher precedence over the inferred ones from the function signature
+ * and JSDoc tags.
+ *
+ * @param _option - The type of the option, used for type inference.
+ * @param _options - The options for the command option.
+ * @example
+ * // this will describe the name option as a string with a minimum length of 1 and a maximum length of 32
+ * describeOption(name, {
+ *   minLength: 1,
+ *   maxLength: 32,
+ * })
+ * // this will describe the style option as a string with three choices
+ * describeOption(style, {
+ *   choices: [
+ *     { name: 'Formal', value: 'formal' },
+ *     { name: 'Casual', value: 'casual' },
+ *     { name: 'Enthusiastic', value: 'enthusiastic' },
+ *   ],
+ * })
  */
 export function describeOption<const T extends SlashCommandOptionType>(
   _option: T | undefined,
-  _options: T extends integer ? IntegerOption
-    : T extends number ? NumberOption
-      : T extends string ? StringOption : DescribeOptionOptionsBase,
+  _options: T extends integer ? IntegerOption<T>
+    : T extends number ? NumberOption<T>
+      : T extends string ? StringOption<T> : never,
 ): void {
-// This function is a placeholder for the build time macro
+  // This function is a placeholder for the build time macro
 }

src/utils/collect.ts

@@ -71,28 +71,128 @@ export function processCommandFile(ctx: NuxtDiscordContext, file: string): Slash
     return
   }
 
+  const whichLiteral = (node: ts.TypeNode): SlashCommandOptionTypeIdentifier | undefined => {
+    if (ts.isLiteralTypeNode(node)) {
+      if (ts.isStringLiteral(node.literal)) {
+        return 'string'
+      }
+      if (ts.isNumericLiteral(node.literal)) {
+        return 'number'
+      }
+    }
+  }
+
+  const getType = (type: ts.TypeNode | undefined): {
+    type: SlashCommandOptionTypeIdentifier
+    choices?: (string | number)[]
+  } => {
+    if (!type) {
+      ctx.logger.warn(`No type found for slash command option in ${file}, defaulting to string`)
+      return { type: 'string' as const }
+    }
+
+    if (ts.isUnionTypeNode(type)) {
+      const types = new Set(type.types.map(t => whichLiteral(t)))
+      if (types.size !== 1) {
+        ctx.logger.warn(`Union type with multiple conflicting types found in ${file}, defaulting to string`)
+        return { type: 'string' as const }
+      }
+      const typeName = types.values().next().value
+      if (!(typeName! in typeIdentifierToEnum)) {
+        ctx.logger.warn(`Unrecognizable type ${type.getText(sourceFile)}, defaulting to string`)
+        return { type: 'string' as const }
+      }
+      return {
+        type: typeName as SlashCommandOptionTypeIdentifier,
+        choices: typeName === 'string'
+          ? type.types.map(t => t.getText(sourceFile).slice(1, -1))
+          : type.types.map(t => Number(t.getText(sourceFile))),
+      }
+    }
+
+    if (ts.isLiteralTypeNode(type)) {
+      const typeName = whichLiteral(type)
+      if (!typeName) {
+        ctx.logger.warn(`Unrecognizable literal type ${type.getText(sourceFile)}, defaulting to string`)
+        return { type: 'string' as const }
+      }
+      if (!(typeName in typeIdentifierToEnum)) {
+        ctx.logger.warn(`Unrecognizable literal type ${type.getText(sourceFile)}, defaulting to string`)
+        return { type: 'string' as const }
+      }
+      return {
+        type: typeName,
+        choices: typeName === 'string'
+          ? [type.literal.getText(sourceFile).slice(1, -1)]
+          : [Number(type.literal.getText(sourceFile))],
+      }
+    }
+
+    const typeName = type.getText(sourceFile)
+    if (typeName && typeName in typeIdentifierToEnum) {
+      return { type: typeName as SlashCommandOptionTypeIdentifier }
+    }
+
+    ctx.logger.warn(`Unknown slash command option type: ${type.getText(sourceFile)} in ${file}, defaulting to string`)
+    return { type: 'string' as const }
+  }
+
   for (const param of commandDefinition.parameters) {
     const name = param.name.getText(sourceFile)
-    let type = param.type?.getText(sourceFile)
+    // let type = param.type?.getText(sourceFile)
+    let { type, choices } = getType(param.type)
+
+    const jsDocTagIdx = jsDocTags
+      .findIndex(tag => ts.isJSDocParameterTag(tag) && tag.name.getText() === name)
+
+    const findModifiers = <K extends string>(modifiers: K[]): Record<K, any> => {
+      let idx = jsDocTagIdx
+      const ret = {} as Record<K, any>
+      while (idx >= 0) {
+        const tag = jsDocTags[idx]
+        if (modifiers.includes(tag.tagName.escapedText as string as K) && tag.comment) {
+          ret[tag.tagName.escapedText as string as K] = JSON.parse(tag.comment.toString())
+        }
+        else {
+          return ret
+        }
+        idx -= 1
+      }
+      return ret
+    }
 
-    // TODO: support literal union types
+    const jsdocDescription = jsDocTagIdx !== -1
+      ? jsDocTags[jsDocTagIdx].comment?.toString() ?? ''
+      : ''
 
-    if (!type || !(type in typeIdentifierToEnum)) {
-      ctx.logger.warn(`Unknown slash command option type: ${type} for parameter ${name} in ${file}, defaulting to string`)
-      type = 'string' as const
+    const modifiersMap = {
+      string: ['minLength', 'maxLength', 'choices'],
+      number: ['min', 'max', 'choices'],
+      integer: ['min', 'max', 'choices'],
+      boolean: [],
     }
 
-    const jsdocDescription = jsDocTags
-      .find(tag => ts.isJSDocParameterTag(tag) && tag.name.getText() === name)
-      ?.comment
-      ?.toString() ?? ''
+    const modifiers = findModifiers(modifiersMap[type as SlashCommandOptionTypeIdentifier])
+
+    choices = choices ?? modifiers.choices
 
     command.options!.push({
       name,
       // TODO: remove this type assertion
       type: typeIdentifierToEnum[type as SlashCommandOptionTypeIdentifier],
       description: jsdocDescription,
       required: !param.questionToken,
+      ...modifiers,
+      ...choices
+        ? {
+            choices: choices.map((choice) => {
+              if (typeof choice === 'string') {
+                return { name: choice, value: choice }
+              }
+              return { name: String(choice), value: choice }
+            }) as any, // hmm... is it possible to not use `any` here?
+          }
+        : {},
     })
   }