Kubb: Fixing Missing @pattern In JSDoc With PluginTs

Hey everyone! Today, we're diving into an interesting issue encountered while using the pluginTs feature in Kubb for generating TypeScript types from an OpenAPI schema. Specifically, we'll be addressing the missing @pattern property in the JSDoc for generated types. Let's get started!

The Issue: Missing @pattern in JSDoc

So, here's the deal. When generating TypeScript types from an OpenAPI schema using pluginTs, the @pattern property defined in the schema isn't being included in the JSDoc comments for the generated types. This can be a bit of a pain because the @pattern property is super useful for documenting regular expression constraints on string fields. Without it, developers might miss important validation rules, leading to potential bugs and headaches down the road.

Let's break down why this is important and how it affects our workflow. Imagine you have an OpenAPI schema that defines a User object with a username field. This field has a @pattern defined to ensure it adheres to a specific format, like only alphanumeric characters. When Kubb generates the TypeScript type for User, we'd expect the JSDoc for the username field to include this pattern. However, if it's missing, developers reviewing the generated code might not realize this constraint exists, potentially leading to errors when creating or validating user data.

This issue becomes even more critical in larger projects where multiple developers are working on the same codebase. Consistent and accurate documentation is key to maintaining code quality and preventing misunderstandings. By ensuring that the @pattern property is included in the JSDoc, we provide developers with a clear and concise way to understand the constraints on each field, reducing the likelihood of errors and improving overall code maintainability.

Furthermore, having the @pattern in the JSDoc can be beneficial for tooling and code analysis. Some IDEs and linters can leverage JSDoc comments to provide additional validation and auto-completion suggestions. By including the @pattern, we enable these tools to better understand the expected format of the data, leading to a more robust and developer-friendly experience.

Reproducing the Bug

To reproduce this issue, follow these simple steps:

1. Generate types from an OpenAPI schema using Kubb with the pluginTs plugin.
2. Inspect the generated TypeScript files, specifically the types that include properties with a pattern defined in the OpenAPI schema.
3. Observe that the JSDoc for these properties is missing the @pattern tag.

For example, consider the following OpenAPI schema snippet:

properties:
  creationTime:
    description: The creation date
    type: string
    pattern: "\\S"
    format: date-time

When Kubb generates the TypeScript type for this schema, we expect the creationTime property to have a JSDoc comment that includes the @pattern tag, like this:

export interface Task {
  /**
   * @description The creation date
   * @type string, date-time
   * @pattern \S
   */
  creationTime: Instant;
}

However, the actual output is missing the @pattern tag:

export interface Task {
  /**
   * @description The creation date
   * @type string, date-time
   */
  creationTime: Instant;
}

This discrepancy highlights the bug we're addressing today.

OpenAPI Schema Example

Here's a snippet from the OpenAPI schema used to reproduce the issue:

{
  "openapi": "3.1.0",
  "components": {
    "schemas": {
      "Task": {
        "description": "A Task",
        "type": "object",
        "required": ["creationTime"],
        "properties": {
          "creationTime": {
            "description": "The creation date",
            "type": "string",
            "pattern": "\\S",
            "$ref": "#/components/schemas/Instant"
          }
        }
      },
      "User": {
        "type": "object",
        "required": ["id", "username"],
        "properties": {
          "username": {
            "type": "string",
            "pattern": "\\S",
            "minLength": 2,
            "maxLength": 20
          }
        }
      }
    }
  }
}

In this schema, the Task schema has a creationTime property with a pattern defined. Similarly, the User schema has a username property with a pattern. The expectation is that these patterns should be reflected in the generated JSDoc comments.

Expected vs. Actual Behavior

Expected Behavior:

The generated TypeScript type for the Task schema should include the @pattern tag in the JSDoc for the creationTime property:

export interface Task {
  /**
   * @description The creation date
   * @type string, date-time
   * @pattern \S
   */
  creationTime: Instant;
}

Actual Behavior:

The @pattern tag is missing from the JSDoc:

export interface Task {
  /**
   * @description The creation date
   * @type string, date-time
   */
  creationTime: Instant;
}

This discrepancy highlights the need for a fix to ensure that the @pattern property is correctly included in the generated JSDoc comments.

Digging into the Details

Kubb Configuration

First, let's take a look at the Kubb configuration being used. This is crucial because the configuration dictates how Kubb generates the types. Here's the relevant part of the kubb.config.ts file:

pluginTs({
  output: {
    path: './type'
  },
  exclude: [],
  group: {
    type: 'tag',
    name: ({ group }) => `${group}`
  },
  syntaxType: 'interface',
  enumType: "enum",
  dateType: 'date',
  unknownType: 'unknown',
  oasType: false
})

This configuration specifies several options, such as the output path for the generated types, how to group types (by tag in this case), and the syntax type (interface). Notably, there's nothing in this configuration that explicitly excludes the @pattern property from being included in the JSDoc. This suggests that the issue lies within the pluginTs plugin's logic for handling the pattern property from the OpenAPI schema.

Version Information

It's also important to note the version of Kubb being used. In this case, it's version 3.16.1. Knowing the version helps in identifying whether the bug has been reported or fixed in later versions. It also helps in narrowing down the codebase to examine for the issue.

Impact of the Missing @pattern

The absence of the @pattern property in the JSDoc can have several implications:

• Lack of Clarity: Developers might not be aware of the constraints on a particular field, leading to incorrect data being used.
• Validation Issues: Without the @pattern, validation logic might not be implemented correctly, potentially allowing invalid data to slip through.
• Maintainability: Code becomes harder to maintain as the constraints are not clearly documented, making it difficult for new developers to understand the expected data format.

Why This Matters: The Importance of JSDoc

Okay, so why are we making such a fuss about JSDoc? Well, JSDoc comments are more than just extra text in your code. They serve as a crucial bridge between your code and the developers who use it. Think of JSDoc as a mini-manual for your code, providing essential information about what each part does, what it expects, and what it returns.

Documentation for Humans

First and foremost, JSDoc is for humans. When you or another developer comes back to a piece of code months or even years later, JSDoc comments can be a lifesaver. They help you quickly understand the purpose of a function, the meaning of its parameters, and the expected output. This is especially important in large projects where the codebase can be complex and overwhelming.

API Generation

JSDoc comments are also invaluable for generating API documentation. Tools like JSDoc, TypeDoc, and others can parse your comments and automatically create beautiful, interactive documentation websites. This means you can write your documentation alongside your code, ensuring it stays up-to-date and accurate. Imagine having a comprehensive API reference that's always in sync with your codebase – that's the power of JSDoc!

Type Checking and Validation

But wait, there's more! JSDoc can also be used for type checking and validation. TypeScript, for example, can use JSDoc comments to infer types and catch errors. This allows you to add type safety to your JavaScript code without fully migrating to TypeScript. Additionally, some linters and IDEs can use JSDoc comments to provide real-time feedback and suggestions, helping you write cleaner and more robust code.

Collaboration and Onboarding

In a team environment, JSDoc comments are essential for collaboration. They provide a common language for developers to communicate about the code. When a new team member joins the project, well-documented code can significantly speed up the onboarding process. They can read the JSDoc comments and quickly understand the codebase, reducing the learning curve and allowing them to contribute more effectively.

Possible Solutions and Workarounds

Now that we've identified the issue and understood its impact, let's brainstorm some possible solutions and workarounds. While a proper fix within the pluginTs plugin is the ideal solution, there might be temporary workarounds we can use in the meantime.

Contributing to Kubb

The most direct solution is to contribute a fix to the Kubb project itself. This involves diving into the pluginTs plugin's codebase, identifying the part that handles the pattern property, and ensuring it's included in the generated JSDoc. This approach not only solves the issue for ourselves but also benefits the entire Kubb community. If you're comfortable with TypeScript and have some experience with code generation tools, this could be a great way to give back to the open-source community.

Workarounds

In the meantime, here are a few workarounds we can consider:

1. Post-processing: We could write a script that runs after Kubb generates the types and adds the missing @pattern tags to the JSDoc. This script would parse the generated TypeScript files, identify the properties with a pattern in the OpenAPI schema, and inject the corresponding JSDoc comments. While this adds an extra step to the build process, it ensures that the generated types have the necessary documentation.
2. Custom Plugin: Another option is to create a custom Kubb plugin that extends the functionality of pluginTs. This plugin could hook into the type generation process and add the @pattern tags. This approach is more complex than post-processing but provides more control over the generation process.
3. Manual Documentation: As a last resort, we could manually add the @pattern tags to the JSDoc in the generated types. This is the least efficient approach but might be necessary if we need a quick fix and don't have the resources to implement a more automated solution. However, it's important to remember that manual documentation can easily become outdated if the OpenAPI schema changes.

Next Steps: Let's Get This Fixed!

Alright, guys, we've thoroughly explored the issue of the missing @pattern property in JSDoc generation with Kubb's pluginTs. We've seen why it's important, how to reproduce it, and some potential solutions and workarounds. Now, it's time to take action!

The next step is to ideally contribute a fix to the Kubb project. This not only solves the issue for ourselves but also benefits the entire Kubb community. If you're comfortable with TypeScript and have some experience with code generation tools, this could be a great way to give back to the open-source community. Alternatively, implementing one of the workarounds discussed can provide a temporary solution while waiting for a permanent fix.

By addressing this issue, we can ensure that our generated TypeScript types are fully documented, making our code more maintainable and reducing the risk of errors. Let's get this fixed and make Kubb even better!

In conclusion, the missing @pattern property in JSDoc generation with Kubb's pluginTs is a significant issue that can impact code maintainability and correctness. By understanding the problem, its implications, and potential solutions, we can take steps to address it and improve the overall development experience. Whether it's contributing a fix to the Kubb project or implementing a workaround, the goal is to ensure that our generated types are fully documented and reliable.