Allow documentation of strings that should match a pattern similar to enum of strings

[AncientSwordRage]

Similar to jsdoc/issues/629 I'd like to be able to specify a regex pattern a string should match:

/**
 * @param {('gif'|/jp(e?)g/)} imageType - Type of the image
 */
function foo(imageType){};

I'm not expecting anything to be enforced, but some parsing to make sense of the regex without displaying it as a literal string enum.

Here're another few examples:

/**
 * note the lowercase flag
 * @param {/[0-9A-F]+/i} hexDigitString - string representation of a hexadecimal digit
 */
function foo(hexDigitString){};

And real wishlist idea:

/**
 * @patternDef hexString
 * @pattern /[0-9A-F]+/
 */

/**
 * compose patterns
 * this one matches ^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-[89AB][0-9A-F]{3}-[0-9A-F]{12}$
 * @param {/{hexString}{8}-{hexString}{4}-4{hexString}{3}-[89AB]{hexString}{3}-{hexString}{12}/} uuid - string representation uuidv4
 */
function foo(hexDigitString){};

Is this a possible new feature?

[oriadam]

+1 adding some more real-life usages we really need in our project at the moment:

/**
 * @typeDef {string(//\d{4}-[01]\d-[0-3]\d(T[0-2]\d:[0-5]\d:[0-5]\d)?([+-][0-2]\d:[0-5]\d|Z)?/)} isoDate
 * @typeDef {number|string(/^-?\d+(\.\d+)?$/)} numeric
 * @typeDef {string(/^\d+(%|px|em|rem|vh|vw|cm|mm|in|pt|pc)$/)} cssSize 
 * @typeDef {string(/^#[\da-f]{3,4}|#([\da-f]{6,8})|(rgb|hsl)a?\(([.\d]+%?[,\s]*){3,4}\)$/)} cssColor
 */

p.s int is also something that we need

[agworkscode]

+1

/* * \@typeDef {string('^[0-9a-fA-F]{8}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{4}\b-[0-9a-fA-F]{12}$')} UUID \ /

Yes, and int is desired here also.

[floscher]

Something like the Template Literal Strings from TypeScript would be much appreciated.

But supporting regular expressions would be even better, of course. Something similar is being proposed for Typescript here: https://github.com/microsoft/TypeScript/issues/41160

[zijianhuang]

OpenApiClientGen can generate C# codes and TypeScript codes along with comments including regex.

Upon yaml:

   RepositoryName:
      type: string
      pattern: '(?:[a-z0-9]+(?:[._-][a-z0-9]+)*/)*[a-z0-9]+(?:[._-][a-z0-9]+)*'
      minLength: 2
      maxLength: 256

For C#, no problem:

        /// <summary>
        /// Max length: 256
        /// Min length: 2
        /// Pattern: (?:[a-z0-9]+(?:[._-][a-z0-9]+)*/)*[a-z0-9]+(?:[._-][a-z0-9]+)*
        /// </summary>
        [System.ComponentModel.DataAnnotations.Required()]
        [System.Runtime.Serialization.DataMember()]
        [System.ComponentModel.DataAnnotations.StringLength(256, MinimumLength=2)]
        public string RepositoryName { get; set; }

for JsDoc in TypeScript codes,

        /**
         * Required
         * Max length: 256
         * Min length: 2
         * Pattern: (?:[a-z0-9]+(?:[._-][a-z0-9]+)*/)*[a-z0-9]+(?:[._-][a-z0-9]+)*
         */
        repositoryName: string;

VS Code and TypeScript compiler will report errors.

At the moment, the workaround is to skip Pattern of OpenApi def when generating doc comment for TS.

[zijianhuang]

others encountered similar problems: https://github.com/lukeautry/tsoa/issues/543

https://github.com/gajus/eslint-plugin-jsdoc/issues/710