Merge pull request #2040 from citkane/issue#2024

New BOOTSTRAP_END event and ParameterType.Object

Author: Gerrit0

src/lib/application-events.ts

@@ -0,0 +1,3 @@
+export const ApplicationEvents = {
+    BOOTSTRAP_END: "bootstrapEnd",
+};

src/lib/application.ts

@@ -35,6 +35,7 @@ import { getLoadedPaths, hasBeenLoadedMultipleTimes } from "./utils/general";
 import { validateExports } from "./validation/exports";
 import { validateDocumentation } from "./validation/documentation";
 import { validateLinks } from "./validation/links";
+import { ApplicationEvents } from "./application-events";
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const packageInfo = require("../../package.json") as {
@@ -161,6 +162,7 @@ export class Application extends ChildableComponent<
                 )}`
             );
         }
+        this.trigger(ApplicationEvents.BOOTSTRAP_END, this, options);
     }
 
     /**

src/lib/utils/options/declaration.ts

@@ -188,9 +188,11 @@ export type KeyToDeclaration<K extends keyof TypeDocOptionMap> =
         : TypeDocOptionMap[K] extends string[]
         ? ArrayDeclarationOption
         : unknown extends TypeDocOptionMap[K]
-        ? MixedDeclarationOption
+        ? MixedDeclarationOption | ObjectDeclarationOption
         : TypeDocOptionMap[K] extends ManuallyValidatedOption<unknown>
-        ? MixedDeclarationOption & { validate(value: unknown): void }
+        ?
+              | (MixedDeclarationOption & { validate(value: unknown): void })
+              | (ObjectDeclarationOption & { validate(value: unknown): void })
         : TypeDocOptionMap[K] extends Record<string, boolean>
         ? FlagsDeclarationOption<TypeDocOptionMap[K]>
         : TypeDocOptionMap[K] extends Record<string | number, infer U>
@@ -225,6 +227,10 @@ export enum ParameterType {
      * Resolved according to the config directory unless it starts with `**`, after skipping any leading `!` and `#` characters.
      */
     GlobArray,
+    /**
+     * An unopinionated object that preserves default settings unless explicitly overridden
+     */
+    Object,
     /**
      * An object with true/false flags
      */
@@ -341,6 +347,20 @@ export interface MixedDeclarationOption extends DeclarationOptionBase {
     validate?: (value: unknown) => void;
 }
 
+export interface ObjectDeclarationOption extends DeclarationOptionBase {
+    type: ParameterType.Object;
+
+    /**
+     * If not specified defaults to undefined.
+     */
+    defaultValue?: unknown;
+
+    /**
+     * An optional validation function that validates a potential value of this option.
+     * The function must throw an Error if the validation fails and should do nothing otherwise.
+     */
+    validate?: (value: unknown) => void;
+}
 export interface MapDeclarationOption<T> extends DeclarationOptionBase {
     type: ParameterType.Map;
 
@@ -378,6 +398,7 @@ export type DeclarationOption =
     | NumberDeclarationOption
     | BooleanDeclarationOption
     | MixedDeclarationOption
+    | ObjectDeclarationOption
     | MapDeclarationOption<unknown>
     | ArrayDeclarationOption
     | FlagsDeclarationOption<Record<string, boolean>>;
@@ -388,6 +409,7 @@ export interface ParameterTypeToOptionTypeMap {
     [ParameterType.Number]: number;
     [ParameterType.Boolean]: boolean;
     [ParameterType.Mixed]: unknown;
+    [ParameterType.Object]: unknown;
     [ParameterType.Array]: string[];
     [ParameterType.PathArray]: string[];
     [ParameterType.ModuleArray]: string[];
@@ -409,7 +431,8 @@ const converters: {
     [K in ParameterType]: (
         value: unknown,
         option: DeclarationOption & { type: K },
-        configPath: string
+        configPath: string,
+        oldValue: unknown
     ) => ParameterTypeToOptionTypeMap[K];
 } = {
     [ParameterType.String](value, option) {
@@ -503,6 +526,12 @@ const converters: {
         option.validate?.(value);
         return value;
     },
+    [ParameterType.Object](value, option, _configPath, oldValue) {
+        option.validate?.(value);
+        if (typeof oldValue !== "undefined")
+            value = { ...(oldValue as {}), ...(value as {}) };
+        return value;
+    },
     [ParameterType.Flags](value, option) {
         if (typeof value === "boolean") {
             value = Object.fromEntries(
@@ -554,16 +583,18 @@ const converters: {
 export function convert(
     value: unknown,
     option: DeclarationOption,
-    configPath: string
+    configPath: string,
+    oldValue?: unknown
 ): unknown {
     const _converters = converters as Record<
         ParameterType,
-        (v: unknown, o: DeclarationOption, c: string) => unknown
+        (v: unknown, o: DeclarationOption, c: string, ov: unknown) => unknown
     >;
     return _converters[option.type ?? ParameterType.String](
         value,
         option,
-        configPath
+        configPath,
+        oldValue
     );
 }
 
@@ -596,6 +627,9 @@ const defaultGetters: {
     [ParameterType.Mixed](option) {
         return option.defaultValue;
     },
+    [ParameterType.Object](option) {
+        return option.defaultValue;
+    },
     [ParameterType.Array](option) {
         return option.defaultValue?.slice() ?? [];
     },

src/lib/utils/options/options.ts

@@ -301,10 +301,15 @@ export class Options {
             );
         }
 
+        let oldValue = this._values[declaration.name];
+        if (typeof oldValue === "undefined")
+            oldValue = getDefaultValue(declaration);
+
         const converted = convert(
             value,
             declaration,
-            configPath ?? process.cwd()
+            configPath ?? process.cwd(),
+            oldValue
         );
 
         if (declaration.type === ParameterType.Flags) {

src/test/converter2/issues/gh2024.ts

@@ -0,0 +1 @@
+() => null;

src/test/issueTests.ts

@@ -1,9 +1,11 @@
 import {
+    deepStrictEqual,
     deepStrictEqual as equal,
     notDeepStrictEqual as notEqual,
     ok,
 } from "assert";
-import type { Application } from "../lib/application";
+import { Application } from "../lib/application";
+import { ApplicationEvents } from "../lib/application-events";
 import {
     DeclarationReflection,
     ProjectReflection,
@@ -18,6 +20,7 @@ import {
     IntrinsicType,
 } from "../lib/models";
 import type { InlineTagDisplayPart } from "../lib/models/comments/comment";
+import { ParameterType, TypeDocOptionMap } from "../lib/utils";
 import { getConverter2App } from "./programs";
 import type { TestLogger } from "./TestLogger";
 
@@ -725,6 +728,40 @@ export const issueTests: {
         );
     },
 
+    gh2024() {
+        const name = "objectOptions" as keyof TypeDocOptionMap;
+        const defaultValue = {
+            neverChange: "ok",
+            foo: "foo",
+        };
+        const app = new Application();
+        app.options.addDeclaration({
+            help: "Test option parsing with default values from plugins",
+            name,
+            type: ParameterType.Object,
+            defaultValue,
+        });
+        deepStrictEqual(app.options.getValue(name), defaultValue);
+        app.options.setValue(name, { foo: "bar" });
+        const newVal = app.options.getValue(name) as typeof defaultValue;
+        equal(newVal.foo, "bar");
+        equal(newVal.neverChange, "ok");
+        app.options.setValue("out", "testOutString");
+        app.on(ApplicationEvents.BOOTSTRAP_END, () => {
+            equal(app.options.getValue("out"), "");
+            app.options.setValue("out", "testOutString");
+            app.options.setValue(name, { foo: "foo" });
+        });
+        app.bootstrap();
+        app.options.setValue(name, {});
+        app.convert();
+        deepStrictEqual(app.options.getValue(name), defaultValue);
+        equal(
+            app.options.getValue("out").trim().endsWith("testOutString"),
+            true
+        );
+    },
+
     gh2031(project, logger) {
         const sig = query(project, "MyClass.aMethod").signatures![0];
         const summaryLink = sig.comment?.summary[0];

src/test/utils/options/declaration.test.ts

@@ -7,6 +7,7 @@ import {
     getDefaultValue,
     MapDeclarationOption,
     MixedDeclarationOption,
+    ObjectDeclarationOption,
     NumberDeclarationOption,
     ParameterType,
     StringDeclarationOption,
@@ -321,6 +322,29 @@ describe("Options - conversions", () => {
             new Error("test must not be a number")
         );
     });
+    it("Passes through object", () => {
+        const data = {};
+        equal(convert(data, optionWithType(ParameterType.Object), ""), data);
+    });
+
+    it("Validates object options", () => {
+        const declaration: ObjectDeclarationOption = {
+            name: "test",
+            help: "",
+            type: ParameterType.Object,
+            defaultValue: "default",
+            validate: (value: unknown) => {
+                if (typeof value !== "object" || Array.isArray(value)) {
+                    throw new Error("test must be an object");
+                }
+            },
+        };
+        equal(convert({}, declaration, ""), {});
+        throws(
+            () => convert(1, declaration, ""),
+            new Error("test must be an object")
+        );
+    });
 });
 
 describe("Options - default values", () => {