test: add parameter defaults to our signature generation test (#793)

5 files changed, 267 insertions, 31 deletions

diff --git a/scripts/apidoc.ts b/scripts/apidoc.ts
index 4ac4fbf9..d519a320 100644
--- a/scripts/apidoc.ts
+++ b/scripts/apidoc.ts
@@ -1,32 +1,14 @@
 import { resolve } from 'path';
-import * as TypeDoc from 'typedoc';
 import { writeApiPagesIndex } from './apidoc/apiDocsWriter';
 import { processDirectMethods } from './apidoc/directMethods';
 import { processModuleMethods } from './apidoc/moduleMethods';
-import {
-  DefaultParameterAwareSerializer,
-  parameterDefaultReader,
-  patchProjectParameterDefaults,
-} from './apidoc/parameterDefaults';
 import type { PageIndex } from './apidoc/utils';
-import { pathOutputDir } from './apidoc/utils';
+import { newTypeDocApp, patchProject, pathOutputDir } from './apidoc/utils';
 
 const pathOutputJson = resolve(pathOutputDir, 'typedoc.json');
 
 async function build(): Promise<void> {
-  const app = new TypeDoc.Application();
-
-  app.options.addReader(new TypeDoc.TSConfigReader());
-  // If you want TypeDoc to load typedoc.json files
-  //app.options.addReader(new TypeDoc.TypeDocReader());
-
-  // Read parameter defaults
-  app.converter.on(
-    TypeDoc.Converter.EVENT_CREATE_DECLARATION,
-    parameterDefaultReader
-  );
-  // Add to debug json output
-  app.serializer.addSerializer(new DefaultParameterAwareSerializer(undefined));
+  const app = newTypeDocApp();
 
   app.bootstrap({
     entryPoints: ['src/index.ts'],
@@ -36,15 +18,10 @@ async function build(): Promise<void> {
 
   const project = app.convert();
 
-  if (!project) {
-    // Project may not have converted correctly
-    return;
-  }
   // Useful for manually analyzing the content
   await app.generateJson(project, pathOutputJson);
-  console.log(pathOutputDir);
 
-  patchProjectParameterDefaults(project);
+  patchProject(project);
 
   const modulesPages: PageIndex = [];
   modulesPages.push({ text: 'Localization', link: '/api/localization.html' });
diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts
index ee38d58d..68b69746 100644
--- a/scripts/apidoc/utils.ts
+++ b/scripts/apidoc/utils.ts
@@ -1,4 +1,10 @@
 import { resolve } from 'node:path';
+import * as TypeDoc from 'typedoc';
+import {
+  DefaultParameterAwareSerializer,
+  parameterDefaultReader,
+  patchProjectParameterDefaults,
+} from './parameterDefaults';
 
 export type Page = { text: string; link: string };
 export type PageIndex = Array<Page>;
@@ -6,3 +12,35 @@ export type PageIndex = Array<Page>;
 const pathRoot = resolve(__dirname, '..', '..');
 export const pathDocsDir = resolve(pathRoot, 'docs');
 export const pathOutputDir = resolve(pathDocsDir, 'api');
+
+/**
+ * Creates and configures a new typedoc application.
+ */
+export function newTypeDocApp(): TypeDoc.Application {
+  const app = new TypeDoc.Application();
+
+  app.options.addReader(new TypeDoc.TSConfigReader());
+  // If you want TypeDoc to load typedoc.json files
+  //app.options.addReader(new TypeDoc.TypeDocReader());
+
+  // Read parameter defaults
+  app.converter.on(
+    TypeDoc.Converter.EVENT_CREATE_DECLARATION,
+    parameterDefaultReader
+  );
+  // Add to debug json output
+  app.serializer.addSerializer(new DefaultParameterAwareSerializer(undefined));
+
+  return app;
+}
+
+/**
+ * Apply our patches to the generated typedoc data.
+ *
+ * This is moved to a separate method to allow printing/saving the original content before patching it.
+ *
+ * @param project The project to patch.
+ */
+export function patchProject(project: TypeDoc.ProjectReflection): void {
+  patchProjectParameterDefaults(project);
+}
diff --git a/test/scripts/apidoc/signature.example.ts b/test/scripts/apidoc/signature.example.ts
index b413dd20..16dae935 100644
--- a/test/scripts/apidoc/signature.example.ts
+++ b/test/scripts/apidoc/signature.example.ts
@@ -1,3 +1,63 @@
+/**
+ * Parameter options type with default from signature.
+ */
+export type ParameterOptionsTypeA = {
+  /**
+   * Options value.
+   */
+  value?: number;
+};
+
+/**
+ * Parameter options type with default from jsdocs. Defaults to `{value: 0}`.
+ */
+export type ParameterOptionsTypeB = {
+  /**
+   * Options value.
+   */
+  value?: number;
+};
+
+/**
+ * Parameter options type with default from inner jsdocs.
+ */
+export type ParameterOptionsTypeC = {
+  /**
+   * Options value. Defaults to `0`.
+   */
+  value?: number;
+};
+
+/**
+ * Parameter options type with default from signature.
+ */
+export interface ParameterOptionsInterfaceA {
+  /**
+   * Options value.
+   */
+  value?: number;
+}
+
+/**
+ * Parameter options type with default from jsdocs.
+ */
+export interface ParameterOptionsInterfaceB {
+  /**
+   * Options value.
+   */
+  value?: number;
+}
+
+/**
+ * Parameter options type with default from inner jsdocs.
+ */
+export interface ParameterOptionsInterfaceC {
+  /**
+   * Options value. Defaults to `0`.
+   */
+  value?: number;
+}
+
 export class SignatureTest {
   /**
    * Test with no parameters.
@@ -72,6 +132,60 @@ export class SignatureTest {
   }
 
   /**
+   * Test with a function parameters (inline types) with defaults.
+   *
+   * @param a Parameter with signature default.
+   * @param a.value The number parameter.
+   * @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`.
+   * @param b.value The boolean parameter.
+   * @param c Parameter with inner jsdocs default.
+   * @param c.value The boolean parameter. Defaults to `2`.
+   */
+  optionsInlineParamMethodWithDefaults(
+    a: { value?: number } = { value: 1 },
+    b: { value?: number },
+    c: { value?: number }
+  ): number {
+    return a.value ?? b.value ?? c.value ?? -1;
+  }
+
+  /**
+   * Test with a function parameters with defaults.
+   *
+   * @param a Parameter with signature default.
+   * @param a.value The number parameter.
+   * @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`.
+   * @param b.value The boolean parameter.
+   * @param c Parameter with inner jsdocs default.
+   * @param c.value The boolean parameter. Defaults to `2`.
+   */
+  optionsTypeParamMethodWithDefaults(
+    a: ParameterOptionsTypeA = { value: 1 },
+    b: ParameterOptionsTypeB,
+    c: ParameterOptionsTypeC
+  ): number {
+    return a.value ?? b.value ?? c.value ?? -1;
+  }
+
+  /**
+   * Test with a function parameters with defaults.
+   *
+   * @param a Parameter with signature default.
+   * @param a.value The number parameter.
+   * @param b Parameter with jsdocs default. Defaults to `{ value: 1 }`.
+   * @param b.value The boolean parameter.
+   * @param c Parameter with inner jsdocs default.
+   * @param c.value The boolean parameter. Defaults to `2`.
+   */
+  optionsInterfaceParamMethodWithDefaults(
+    a: ParameterOptionsInterfaceA = { value: 1 },
+    b: ParameterOptionsInterfaceB,
+    c: ParameterOptionsInterfaceC
+  ): number {
+    return a.value ?? b.value ?? c.value ?? -1;
+  }
+
+  /**
    * Test with example marker.
    *
    * @example
diff --git a/test/scripts/apidoc/signature.expected.json b/test/scripts/apidoc/signature.expected.json
index da7c2e87..f6e398fe 100644
--- a/test/scripts/apidoc/signature.expected.json
+++ b/test/scripts/apidoc/signature.expected.json
@@ -89,6 +89,106 @@
     "deprecated": false,
     "seeAlsos": []
   },
+  "optionsInlineParamMethodWithDefaults": {
+    "name": "optionsInlineParamMethodWithDefaults",
+    "title": "Options Inline Param Method With Defaults",
+    "description": "<p>Test with a function parameters (inline types) with defaults.</p>\n",
+    "parameters": [
+      {
+        "name": "a",
+        "type": "{ ... }",
+        "default": "{ value: 1 }",
+        "description": "<p>Parameter with signature default.</p>\n"
+      },
+      {
+        "name": "a.value?",
+        "type": "number",
+        "description": "<p>The number parameter.</p>\n"
+      },
+      {
+        "name": "b",
+        "type": "{ ... }",
+        "default": "{ value: 1 }",
+        "description": "<p>Parameter with jsdocs default.</p>\n"
+      },
+      {
+        "name": "b.value?",
+        "type": "number",
+        "description": "<p>The boolean parameter.</p>\n"
+      },
+      {
+        "name": "c",
+        "type": "{ ... }",
+        "description": "<p>Parameter with inner jsdocs default.</p>\n"
+      },
+      {
+        "name": "c.value?",
+        "type": "number",
+        "default": "2",
+        "description": "<p>The boolean parameter.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsInlineParamMethodWithDefaults</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> <span class=\"token punctuation\">{</span>\n  value<span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n<span class=\"token punctuation\">}</span> <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> b<span class=\"token operator\">:</span> <span class=\"token punctuation\">{</span>\n  value<span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n<span class=\"token punctuation\">}</span> <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> c<span class=\"token operator\">:</span> <span class=\"token punctuation\">{</span>\n  value<span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n<span class=\"token punctuation\">}</span><span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": []
+  },
+  "optionsInterfaceParamMethodWithDefaults": {
+    "name": "optionsInterfaceParamMethodWithDefaults",
+    "title": "Options Interface Param Method With Defaults",
+    "description": "<p>Test with a function parameters with defaults.</p>\n",
+    "parameters": [
+      {
+        "name": "a",
+        "type": "ParameterOptionsInterfaceA",
+        "default": "{ value: 1 }",
+        "description": "<p>Parameter with signature default.</p>\n"
+      },
+      {
+        "name": "b",
+        "type": "ParameterOptionsInterfaceB",
+        "default": "{ value: 1 }",
+        "description": "<p>Parameter with jsdocs default.</p>\n"
+      },
+      {
+        "name": "c",
+        "type": "ParameterOptionsInterfaceC",
+        "description": "<p>Parameter with inner jsdocs default.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsInterfaceParamMethodWithDefaults</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> ParameterOptionsInterfaceA <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> b<span class=\"token operator\">:</span> ParameterOptionsInterfaceB <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> c<span class=\"token operator\">:</span> ParameterOptionsInterfaceC<span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": []
+  },
+  "optionsTypeParamMethodWithDefaults": {
+    "name": "optionsTypeParamMethodWithDefaults",
+    "title": "Options Type Param Method With Defaults",
+    "description": "<p>Test with a function parameters with defaults.</p>\n",
+    "parameters": [
+      {
+        "name": "a",
+        "type": "ParameterOptionsTypeA",
+        "default": "{ value: 1 }",
+        "description": "<p>Parameter with signature default.</p>\n"
+      },
+      {
+        "name": "b",
+        "type": "ParameterOptionsTypeB",
+        "default": "{ value: 1 }",
+        "description": "<p>Parameter with jsdocs default.</p>\n"
+      },
+      {
+        "name": "c",
+        "type": "ParameterOptionsTypeC",
+        "description": "<p>Parameter with inner jsdocs default.</p>\n"
+      }
+    ],
+    "returns": "number",
+    "examples": "<div class=\"language-ts\"><pre v-pre><code>faker<span class=\"token punctuation\">.</span><span class=\"token function\">optionsTypeParamMethodWithDefaults</span><span class=\"token punctuation\">(</span>a<span class=\"token operator\">:</span> ParameterOptionsTypeA <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> b<span class=\"token operator\">:</span> ParameterOptionsTypeB <span class=\"token operator\">=</span> <span class=\"token punctuation\">{</span> value<span class=\"token operator\">:</span> <span class=\"token number\">1</span> <span class=\"token punctuation\">}</span><span class=\"token punctuation\">,</span> c<span class=\"token operator\">:</span> ParameterOptionsTypeC<span class=\"token punctuation\">)</span><span class=\"token operator\">:</span> <span class=\"token builtin\">number</span>\n</code></pre>\n</div>",
+    "deprecated": false,
+    "seeAlsos": []
+  },
   "optionalStringParamMethod": {
     "name": "optionalStringParamMethod",
     "title": "Optional String Param Method",
diff --git a/test/scripts/apidoc/signature.spec.ts b/test/scripts/apidoc/signature.spec.ts
index f536a219..d550dfd2 100644
--- a/test/scripts/apidoc/signature.spec.ts
+++ b/test/scripts/apidoc/signature.spec.ts
@@ -4,6 +4,8 @@ import * as TypeDoc from 'typedoc';
 import { afterAll, describe, expect, it } from 'vitest';
 import type { Method } from '../../../docs/.vitepress/components/api-docs/method';
 import { analyzeSignature } from '../../../scripts/apidoc/signature';
+import { newTypeDocApp, patchProject } from '../../../scripts/apidoc/utils';
+import { SignatureTest } from './signature.example';
 import expected_ from './signature.expected.json';
 const expected: Record<string, Method> = expected_;
 
@@ -12,17 +14,18 @@ function prettyJson(object): string {
 }
 
 describe('signature', () => {
-  const app = new TypeDoc.Application();
-
-  app.options.addReader(new TypeDoc.TSConfigReader());
+  const app = newTypeDocApp();
 
   app.bootstrap({
     entryPoints: ['test/scripts/apidoc/signature.example.ts'],
     tsconfig: 'test/scripts/apidoc/tsconfig.json',
   });
 
-  const methods: Record<string, TypeDoc.DeclarationReflection> = app
-    .convert()
+  const project = app.convert();
+
+  patchProject(project);
+
+  const methods: Record<string, TypeDoc.DeclarationReflection> = project
     .getChildrenByKind(TypeDoc.ReflectionKind.Class)[0]
     .getChildrenByKind(TypeDoc.ReflectionKind.Method)
     .reduce((a, v) => ({ ...a, [v.name]: v }), {});
@@ -30,6 +33,10 @@ describe('signature', () => {
   describe('analyzeSignature()', () => {
     const actuals = {};
 
+    it('dummy dependency to rerun the test if the example changes', () => {
+      expect(new SignatureTest()).toBeTruthy();
+    });
+
     it('expected and actual methods are equal', () => {
       expect(Object.keys(methods).sort()).toEqual(Object.keys(expected).sort());
     });