Tsoa: New feature: “pattern” JSDoc decorator for regex

[dgreene1]

Sorting

• I'm submitting a ...

  • [ ] bug report
  • [X] feature request
  • [ ] support request

• I confirm that I

  • [X] used the search to make sure that a similar issue hasn't already been submit

Expected Behavior

redirectURL:
  type: string
  pattern: '^\d{3}-\d{2}-\d{4}$'

/*
 * @pattern /https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%_\+.~#()?&//=]*)/ 
 */
export type URLString = string;

@Post()
  public async createUser(@Query() redirectURL: URLString, @Body() requestBody: any): Promise<void> {
    //...
  }

Detailed Description

A new decorator that works within JSDoc that tsoa will pick up called pattern that will validate at runtime and generate schema yaml.

Breaking change?

No

[dgreene1]

@Eoksni and @WoH lets continue the discussion here. @WoH note that I am recommending that we call this pattern instead of format since that’s what OpenAPI calls it. See here: https://swagger.io/docs/specification/data-models/data-types/#pattern

And maybe we can clarify in the readme (which really aught to have more info on these features) that format provides no runtime validation by pattern will (once this PR implements it).

[WoH]

Pattern jsDoc is supported and part of string validation. Are there any issues you're experiencing?

[dgreene1]

I’m very sorry that I didn’t realize that we already support pattern. So @Eoksni wouldn’t pattern accomplish your needs?

[Eoksni]

Yeah, I didn't realize tsoa already supported a lots of standard validation rules besides simple type assertion, like minLength, maxLength, pattern etc after looking here https://github.com/lukeautry/tsoa/blob/master/tests/fixtures/controllers/getController.ts and in the source code of validation service https://github.com/lukeautry/tsoa/blob/master/src/routeGeneration/templateHelpers.ts

Would be nice if that was mentioned in the docs and it was not required to traverse the source code to discover available features :) So anyway, my particular usecase is covered by standard validations.

I still believe that custom format is there for a reason in the openapi spec and supporting custom validation for custom formats seems like a very natural thing to do.

Even in my usecase custom format could be used to give a reusable descriptive name for a set of validation rules, for example I have a postcode property on a number of models - and it causes a bit of maintenance problem (if postcode validation rule changes, I need to scan through my models and change those rules everywhere, instead of just changing my custom formatter). Or that url regexp from your example above, would be nice to give it a descriptive human-readable name. Same for phone numbers and emails.

Btw, can I specify these validation rules by some decorator instead of jsdoc? It would help with the maintenance problem if I could specify regexp in one place and then just import and reuse it everywhere. Hm, not sure how tsoa does code analysis and whether it can handle the case when I pass non-literal parameters to the decorators.

[WoH]

Would be nice if that was mentioned in the docs and it was not required to traverse the source code to discover available features :) So anyway, my particular usecase is covered by standard validations.

We're always interested in documentation PRs.

Since pattern and format are 2 different things and I believe there are no current issues with patterns, I'll close this for now. If someone wants to submit a format proposal, I'd rather track that in a new issue.

[dgreene1]

Even in my usecase custom format could be used to give a reusable descriptive name for a set of validation rules

@Eoksni you can have a reusable pattern by setting it on an interface that you reuse. And it might even work for reusable type aliases too. Not sure. But it will for interfaces.

And I agree with @WoH we are always open for documentation PRs. We’re all volunteers here and non of us are the original author. So contributions like readme updates are super helpful. Especially since I obviously was unaware that pattern was supported. So it’s very clear that there is a need for a readme update. What isn’t clear is who will take the time to do it.

[nvrdftd]

Hello there,
Just wondering if @pattern supports array annotations that _check every element_ in an array? It seems like the support is missing.
For example,

interface Tester {
/**
*
* @pattern ^[a-zA-Z]+$
*/
listing: string[];
}

If you could throw light on this, it would be really helpful.

[WoH]

No, OpenAPI/json-schema does not support that (at the array level, see array validation keywords. However, you could get there (at least in 3.x):

interface Tester {
  listing: Listing[];
}

/**
* @pattern ^[a-zA-Z]+$
*/
export type Listing = string;