Parse simple_components.json into type-safe ComponentDescriptors

Author: pavi2410

src/ComponentMetadata.ts

@@ -1,5 +1,6 @@
-import { YAIL_TYPES, type YailType, type Component, type EventMetadata, type ComponentMetadata as IComponentMetadata, type MethodMetadata, type PropertyMetadata, type ComponentDescriptorJson } from './types.js'
 import type { Environment } from './Environment.js'
+import { YAIL_TYPES, type Component, type EventMetadata, type ComponentMetadata as IComponentMetadata, type MethodMetadata, type PropertyMetadata, type YailType } from './types.js'
+import type { ComponentDescriptor } from './validators/component-descriptor.js'
 
 interface ValidationResult {
   valid: boolean
@@ -23,13 +24,13 @@ interface ComponentStatistics {
 }
 
 class ComponentMetadata implements IComponentMetadata {
-  private componentsData: ComponentDescriptorJson[]
+  private componentsData: ComponentDescriptor[]
   private supportedComponents: Set<string>
 
   constructor(private environment: Environment) {
     // Use the environment's component descriptors directly
     this.componentsData = this.environment.componentDescriptors
-    
+
     // Create supported components set from the environment data
     this.supportedComponents = new Set(
       this.componentsData.map(comp => comp.type)
@@ -61,7 +62,7 @@ class ComponentMetadata implements IComponentMetadata {
     return results
   }
 
-  private getComponent(componentType: string): ComponentDescriptorJson | null {
+  private getComponent(componentType: string): ComponentDescriptor | null {
     const fullType = componentType.includes('.')
       ? componentType
       : `com.google.appinventor.components.runtime.${componentType}`

src/Environment.ts

@@ -1,25 +1,21 @@
-import type {
-  ComponentDescriptorJson,
-  ExtensionDescriptorJson,
-} from "./types.js";
+import type { ExtensionDescriptorJson } from "./types.js";
+import { type ComponentDescriptor, type ComponentDescriptors, ComponentDescriptorsSchema } from "./validators/component-descriptor.js";
 
 export class Environment {
   constructor(
     public readonly name: string,
-    public readonly componentDescriptors: ComponentDescriptorJson[],
-  ) {}
+    public readonly componentDescriptors: ComponentDescriptors,
+  ) { }
 
   isComponentSupported(componentName: string): boolean {
     return this.componentDescriptors.some(
       (comp) => comp.name === componentName,
     );
   }
 
-  getComponentDescriptor(
-    componentType: string,
-  ): ComponentDescriptorJson | null {
+  getComponentDescriptor(componentType: string): ComponentDescriptor | null {
     return (
-      this.componentDescriptors.find((comp) => comp.type === componentType) ||
+      this.componentDescriptors.find((comp) => comp.type === componentType) ??
       null
     );
   }
@@ -35,28 +31,40 @@ export class Environment {
   }
 
   static async kodularCreator(): Promise<Environment> {
+    const environmentName = "Kodular Creator";
     const simpleComponentsJSON = (
       await import("./environments/kodular-creator/simple_components.json", {
         with: { type: "json" },
       })
     ).default;
-    // TODO: Use Zod to validate the JSON structure
-    return new Environment(
-      "Kodular Creator",
-      simpleComponentsJSON as ComponentDescriptorJson[],
-    );
+
+    // Validate the JSON structure using Zod
+    const validationResult = await ComponentDescriptorsSchema.safeParseAsync(simpleComponentsJSON);
+    if (!validationResult.success) {
+      throw new Error(
+        `Invalid component descriptor JSON for ${environmentName}: ${validationResult.error.message}`
+      );
+    }
+
+    return new Environment(environmentName, validationResult.data);
   }
 
   static async mitAppInventor(): Promise<Environment> {
+    const environmentName = "MIT App Inventor";
     const simpleComponentsJSON = (
       await import("./environments/mit-app-inventor/simple_components.json", {
         with: { type: "json" },
       })
     ).default;
-    // TODO: Use Zod to validate the JSON structure
-    return new Environment(
-      "MIT App Inventor",
-      simpleComponentsJSON as ComponentDescriptorJson[],
-    );
+
+    // Validate the JSON structure using Zod
+    const validationResult = await ComponentDescriptorsSchema.safeParseAsync(simpleComponentsJSON);
+    if (!validationResult.success) {
+      throw new Error(
+        `Invalid component descriptor JSON for ${environmentName}: ${validationResult.error.message}`
+      );
+    }
+
+    return new Environment(environmentName, validationResult.data);
   }
 }

src/types.ts

@@ -90,25 +90,6 @@ export interface BkyStatistics {
   eventHandlers: number
 }
 
-export interface ComponentDescriptorJson {
-  type: string;
-  name: string;
-  external: "true" | "false";
-  version: string;
-  dateBuilt: string;
-  categoryString: string;
-  helpString: string;
-  helpUrl: string;
-  showOnPalette: "true" | "false";
-  nonVisible: "true" | "false";
-  iconName: string;
-  androidMinSdk: string | number;
-  properties: ComponentDescriptorProperty[];
-  blockProperties: ComponentDescriptorBlockProperty[];
-  events: ComponentDescriptorEvent[];
-  methods: ComponentDescriptorMethod[];
-}
-
 // ===== Component Metadata Types =====
 export interface ComponentMetadata {
   validateComponents(components: Component[]): { valid: boolean; errors: string[] }
@@ -154,7 +135,7 @@ export interface ComponentDescriptorProperty {
   name: string;
   editorType: string;
   defaultValue: string;
-  propertyType: string;
+  propertyType?: string;
   editorArgs: any[];
 }
 
@@ -163,20 +144,20 @@ export interface ComponentDescriptorBlockProperty {
   description: string;
   type: string;
   rw: string;
-  deprecated: string;
+  deprecated: boolean;
 }
 
 export interface ComponentDescriptorEvent {
   name: string;
   description: string;
-  deprecated: string;
+  deprecated: boolean;
   params: ComponentDescriptorParam[];
 }
 
 export interface ComponentDescriptorMethod {
   name: string;
   description: string;
-  deprecated: string;
+  deprecated: boolean;
   params: ComponentDescriptorParam[];
   returnType?: string;
 }
@@ -189,14 +170,14 @@ export interface ComponentDescriptorParam {
 export interface ExtensionDescriptorJson {
   type: string;
   name: string;
-  external: "true" | "false";
+  external: boolean;
   version: string;
   dateBuilt: string;
   categoryString: string;
   helpString: string;
   helpUrl: string;
-  showOnPalette: "true" | "false";
-  nonVisible: "true" | "false";
+  showOnPalette: boolean;
+  nonVisible: boolean;
   iconName: string;
   androidMinSdk: number;
   versionName: string;

src/utils/property-processor.ts

@@ -1,8 +1,9 @@
 import type { ComponentProperty } from "../component.js";
-import type { ComponentDescriptorJson, ComponentJson } from "../types.js";
+import type { ComponentJson } from "../types.js";
+import type { ComponentDescriptor } from "../validators/component-descriptor.js";
 
 export function resolveProperties(
-  componentDescriptor: ComponentDescriptorJson,
+  componentDescriptor: ComponentDescriptor,
   propertyJSON: ComponentJson,
 ): ComponentProperty[] {
   return componentDescriptor.properties.map(property => {

src/validators/component-descriptor.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for ComponentDescriptorParam
+ */
+export const ComponentDescriptorParamSchema = z.object({
+  name: z.string(),
+  type: z.string(),
+});
+
+/**
+ * Zod schema for ComponentDescriptorProperty
+ */
+export const ComponentDescriptorPropertySchema = z.object({
+  name: z.string(),
+  editorType: z.string(),
+  defaultValue: z.string(),
+  /** 
+   * Kodular Creator specific extension - not present in MIT App Inventor.
+   * Typically has values like "common", "advanced", etc.
+   */
+  propertyType: z.string().optional(),
+  editorArgs: z.array(z.any()),
+});
+
+/**
+ * Zod schema for ComponentDescriptorBlockProperty
+ */
+export const ComponentDescriptorBlockPropertySchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  type: z.string(),
+  rw: z.string(),
+  deprecated: z.stringbool(),
+});
+
+/**
+ * Zod schema for ComponentDescriptorEvent
+ */
+export const ComponentDescriptorEventSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  deprecated: z.stringbool(),
+  params: z.array(ComponentDescriptorParamSchema),
+});
+
+/**
+ * Zod schema for ComponentDescriptorMethod
+ */
+export const ComponentDescriptorMethodSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  deprecated: z.stringbool(),
+  params: z.array(ComponentDescriptorParamSchema),
+  returnType: z.string().optional(),
+});
+
+/**
+ * Zod schema for ComponentDescriptor
+ */
+export const ComponentDescriptorSchema = z.object({
+  type: z.string(),
+  name: z.string(),
+  external: z.stringbool(),
+  version: z.string(),
+  dateBuilt: z.string(),
+  categoryString: z.string(),
+  helpString: z.string(),
+  helpUrl: z.string(),
+  showOnPalette: z.stringbool(),
+  nonVisible: z.stringbool(),
+  iconName: z.string(),
+  androidMinSdk: z.union([z.string(), z.number()]),
+  properties: z.array(ComponentDescriptorPropertySchema),
+  blockProperties: z.array(ComponentDescriptorBlockPropertySchema),
+  events: z.array(ComponentDescriptorEventSchema),
+  methods: z.array(ComponentDescriptorMethodSchema),
+});
+
+export const ComponentDescriptorsSchema = z.array(ComponentDescriptorSchema);
+
+/**
+ * Type inferred from the Zod schema for ComponentDescriptor
+ */
+export type ComponentDescriptor = z.infer<typeof ComponentDescriptorSchema>;
+
+/**
+ * Type inferred from the Zod schema for ComponentDescriptors
+ */
+export type ComponentDescriptors = z.infer<typeof ComponentDescriptorsSchema>;