Miscellaneous notes

[thorwhalen]

To record miscellaneous notes and ideas and resources and discuss them.

[thorwhalen]

Is there a standard way to write a TS interface so that names, types, defaults and descriptions can be parsed out in a robust manner?

Creating TypeScript interfaces in a standardized way to facilitate parsing and extraction of names, types, default values, and descriptions can indeed enhance the robustness of the process. Here's a guideline for structuring TypeScript interfaces to make them more parser-friendly:

1. Consistent Commenting Style: Use a consistent format for comments, ideally JSDoc style, as it is widely recognized and tools are available for parsing it.

   /**
    * Description of the property.
    * @default defaultValue
    */
   propertyName: PropertyType;

2. Explicit Default Values: Clearly annotate default values using a specific tag (like @default) in the comments.

3. Type Annotations: Always specify types explicitly.

4. Optional Properties: Clearly indicate optional properties.

5. Avoid Complex Structures in Comments: Keep descriptions and default values simple and avoid embedding complex structures or code snippets in comments.

6. Use Annotations for Additional Metadata: If more metadata is needed, use specific annotation tags consistently.

Example of a well-structured TypeScript interface:

export interface ExampleInterface {
  /**
   * Description of stringProperty.
   * @default "defaultString"
   */
  stringProperty: string;

  /**
   * Description of optionalNumberProperty.
   * @default 10
   */
  optionalNumberProperty?: number;

  /**
   * Description of booleanProperty.
   * @default false
   */
  booleanProperty: boolean;
}

This structure allows a parser to look for specific patterns, such as lines starting with /**, to identify the beginning of a property description, and the @default tag to find default values. The parser can then extract the property name and type from the subsequent line.

Using a well-defined structure like this greatly improves the reliability of parsing, as it reduces ambiguities and variations in the format. However, it's important to ensure that everyone who contributes to the codebase adheres to these standards. Automated tools like linters can help enforce these conventions.

[thorwhalen]

Isn’t there a way I type script to specify what defaults are but not in comments since comments can’t contain anything else than strings!

In TypeScript, you cannot directly specify default values for properties within interfaces. Interfaces in TypeScript are purely for type checking and do not compile into any JavaScript code that can hold actual values like defaults. They are used to define the shape of an object, not its implementation details.

However, there are ways to indirectly handle default values, typically in the implementation that uses these interfaces. Here are a few approaches:

1. Default Function Parameters: When implementing functions that use these interfaces, you can specify default values for parameters.

   interface Example {
     property: string;
   }
   
   function exampleFunction({ property = "defaultValue" }: Example) {
     // Implementation
   }

2. Class Implementation with Defaults: If you're using classes, you can provide default values in the class implementing the interface.

   interface Example {
     property: string;
   }
   
   class ExampleClass implements Example {
     property = "defaultValue";
   }

3. Object Merging for Defaults: Use object merging to combine an object with default values and the one passed by the user.

   const DEFAULTS = {
     property: "defaultValue"
   };
   
   function exampleFunction(options: Example) {
     const finalOptions = { ...DEFAULTS, ...options };
     // Implementation
   }

4. Utility Types for Defaults: Create utility types or functions to combine defaults with user-provided options.

   type WithDefaults<T> = { [P in keyof T]?: T[P] };
   const applyDefaults = <T>(defaults: T, options: WithDefaults<T>): T => ({ ...defaults, ...options });

While these methods help in managing default values in TypeScript, they do not allow you to specify defaults directly in the interface. TypeScript interfaces are purely for type checking and don't retain any runtime information like default values. To maintain a clear record of defaults, you might need to rely on well-documented code (using comments or external documentation), especially if the defaults are critical for the users of your API or library.

[rokotyan]

I usually use Option 3 (Object Merging) because Typescript classes don't inherit types from interfaces they extend. It's counter-intuitive but that how it is.

[thorwhalen]

Okay -- we should discuss and see how exactly defaults are being handled. It definitely seems that at the very least, there's two sources of truths (if not more) for defaults: The comments in the descriptions, and the object you use (option 3) to define the actual defaults.

[thorwhalen]

interface GraphConfigInterface<N extends CosmosInputNode, L extends CosmosInputLink>

[thorwhalen]

Parsing Typescript

In order to get more single-source-of-truth in parameter information (in code, documentation, and python interfaces), I looked into TS parsers.

I wrote jy.parse_ts to start this effort. It works partially only, but it is setup to easily be extendable (by just adding elements in the node_handlers dictionary mainly).

I managed to get something working with tree-sitter, along with tree-sitter-typescript, but to make it work, I had to downgrade tree-sitter to 0.21.3 to make it work.
I wrote an issue for tree-sitter authors: Versions 0.22+ break tree_sitter_languages.get_language.