[refactor] introduce frontend type augmentation pattern (#4192)

Author: christian-byrne

src/composables/widgets/useImageUploadWidget.ts

@@ -9,6 +9,7 @@ import type { ResultItem } from '@/schemas/apiSchema'
 import type { InputSpec } from '@/schemas/nodeDefSchema'
 import type { ComfyWidgetConstructor } from '@/scripts/widgets'
 import { useNodeOutputStore } from '@/stores/imagePreviewStore'
+import { isImageUploadInput } from '@/types/nodeDefAugmentation'
 import { createAnnotatedPath } from '@/utils/formatUtil'
 import { addToComboValues } from '@/utils/litegraphUtil'
 
@@ -33,7 +34,13 @@ export const useImageUploadWidget = () => {
     inputName: string,
     inputData: InputSpec
   ) => {
-    const inputOptions = inputData[1] ?? {}
+    if (!isImageUploadInput(inputData)) {
+      throw new Error(
+        'Image upload widget requires imageInputName augmentation'
+      )
+    }
+
+    const inputOptions = inputData[1]
     const { imageInputName, allow_batch, image_folder = 'input' } = inputOptions
     const nodeOutputStore = useNodeOutputStore()
 
@@ -43,11 +50,9 @@ export const useImageUploadWidget = () => {
     const { showPreview } = isVideo ? useNodeVideo(node) : useNodeImage(node)
 
     const fileFilter = isVideo ? isVideoFile : isImageFile
-    // @ts-expect-error InputSpec is not typed correctly
     const fileComboWidget = findFileComboWidget(node, imageInputName)
     const initialFile = `${fileComboWidget.value}`
     const formatPath = (value: InternalFile) =>
-      // @ts-expect-error InputSpec is not typed correctly
       createAnnotatedPath(value, { rootFolder: image_folder })
 
     const transform = (internalValue: InternalValue): ExposedValue => {
@@ -67,7 +72,6 @@ export const useImageUploadWidget = () => {
 
     // Setup file upload handling
     const { openFileSelection } = useNodeImageUpload(node, {
-      // @ts-expect-error InputSpec is not typed correctly
       allow_batch,
       fileFilter,
       accept,

src/types/nodeDefAugmentation.ts

@@ -0,0 +1,38 @@
+/**
+ * Frontend augmentations for node definitions.
+ *
+ * This module defines type extensions that augment the backend node definition
+ * types with frontend-specific properties. These augmentations are applied at
+ * runtime and are not part of the backend API contract.
+ */
+import type { ComboInputOptions, InputSpec } from '@/schemas/nodeDefSchema'
+
+/**
+ * Frontend augmentation for image upload combo inputs.
+ * This extends ComboInputOptions with properties injected by the uploadImage extension.
+ */
+export interface ImageUploadComboOptions extends ComboInputOptions {
+  /**
+   * Reference to the associated filename combo widget.
+   * Injected by uploadImage.ts to link upload buttons with their combo widgets.
+   *
+   * @remarks This property exists only in the frontend runtime.
+   */
+  imageInputName: string
+}
+
+/**
+ * Type guard to check if an InputSpec has image upload augmentations.
+ * Narrows from base InputSpec to augmented type.
+ */
+export function isImageUploadInput(
+  inputData: InputSpec
+): inputData is [string, ImageUploadComboOptions] {
+  const options = inputData[1]
+  return (
+    options !== undefined &&
+    typeof options === 'object' &&
+    'imageInputName' in options &&
+    typeof options.imageInputName === 'string'
+  )
+}