fix(core): emit nested array item constraints in jsdoc (#3357)

Author: daugvinasr

packages/core/src/utils/doc.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+
+import { jsDoc } from './doc';
+
+describe('jsDoc', () => {
+  it('includes validators from array items', () => {
+    expect(
+      jsDoc({
+        type: 'array',
+        maxItems: 20,
+        items: {
+          type: 'string',
+          maxLength: 50,
+          pattern: '^[a-z]+$',
+        },
+      }),
+    ).toBe(`/**
+ * @maxItems 20
+ * @items.maxLength 50
+ * @items.pattern ^[a-z]+$
+ */
+`);
+  });
+
+  it('includes validators from nested array items', () => {
+    expect(
+      jsDoc({
+        type: 'array',
+        items: {
+          type: 'array',
+          minItems: 2,
+          maxItems: 5,
+          items: {
+            type: 'string',
+            minLength: 1,
+          },
+        },
+      }),
+    ).toBe(`/**
+ * @items.minItems 2
+ * @items.maxItems 5
+ * @items.items.minLength 1
+ */
+`);
+  });
+});

packages/core/src/utils/doc.ts

@@ -19,6 +19,44 @@ interface JsDocSchema extends Record<string, unknown> {
   maxItems?: number;
   type?: string | string[];
   pattern?: string;
+  items?: JsDocSchema;
+}
+
+interface JsDocEntry {
+  key: string;
+  value: boolean | number | string;
+}
+
+const itemValidationKeys = [
+  'minLength',
+  'maxLength',
+  'minimum',
+  'maximum',
+  'exclusiveMinimum',
+  'exclusiveMaximum',
+  'minItems',
+  'maxItems',
+  'pattern',
+] as const satisfies readonly (keyof JsDocSchema)[];
+
+function getItemValidationDocEntries(
+  schema?: JsDocSchema,
+  prefix = 'items',
+): JsDocEntry[] {
+  if (!schema) {
+    return [];
+  }
+
+  const entries = itemValidationKeys.flatMap((key) => {
+    const value = schema[key];
+
+    return value === undefined ? [] : [{ key: `${prefix}.${key}`, value }];
+  });
+
+  return [
+    ...entries,
+    ...getItemValidationDocEntries(schema.items, `${prefix}.items`),
+  ];
 }
 
 export function jsDoc(
@@ -49,6 +87,7 @@ export function jsDoc(
   const isNullable =
     schema.type === 'null' ||
     (Array.isArray(schema.type) && schema.type.includes('null'));
+  const itemValidationDocEntries = getItemValidationDocEntries(schema.items);
   // Ensure there aren't any comment terminations in doc
   const lines = (
     Array.isArray(description)
@@ -70,6 +109,7 @@ export function jsDoc(
     maxItems?.toString(),
     isNullable ? 'null' : '',
     pattern,
+    ...itemValidationDocEntries.map(({ value }) => value.toString()),
   ].filter(Boolean).length;
 
   if (!count) {
@@ -131,6 +171,18 @@ export function jsDoc(
   tryAppendBooleanDocLine('nullable', isNullable);
   tryAppendStringDocLine('pattern', pattern);
 
+  for (const { key, value } of itemValidationDocEntries) {
+    if (typeof value === 'string') {
+      tryAppendStringDocLine(key, value);
+      continue;
+    }
+    if (typeof value === 'number') {
+      tryAppendNumberDocLine(key, value);
+      continue;
+    }
+    tryAppendBooleanDocLine(key, value);
+  }
+
   doc += oneLine ? ' ' : `\n ${tryOneLine ? '  ' : ''}`;
 
   doc += '*/\n';

tests/__snapshots__/mock/circular/model/addListBody.ts

@@ -9,6 +9,8 @@ export type AddListBody = {
   /**
    * @minItems 1
    * @maxItems 10
+   * @items.minimum 1
+   * @items.maximum 10
    */
   list: number[];
 };

tests/__snapshots__/swr/nested-arrays/model/resSampleModel.ts

@@ -6,5 +6,9 @@
  */
 
 export interface ResSampleModel {
+  /**
+   * @items.minItems 2
+   * @items.maxItems 5
+   */
   items: string[][];
 }