Merge branch 'library-mode'

Author: Gerrit0

package.json

@@ -66,7 +66,8 @@
     "postbuild": "node scripts/replace_application_version.js",
     "build_and_test": "npm run build && npm run test",
     "lint": "tslint --project .",
-    "prepublishOnly": "npm run lint && npm run build_and_test",
+    "prepublishOnly": "node scripts/set_strict.js false && npm run lint && npm run build_and_test",
+    "postpublish": "node scripts/set_strict.js true",
     "prepare": "npm run build",
     "clean": "rm -rf node_modules package-lock.json lib coverage"
   },

scripts/set_strict.js

@@ -0,0 +1,18 @@
+// @ts-check
+// Sets the Strict type that TypeDoc uses to enable overloads for consumers only.
+// See the rationale in src/lib/utils/index.ts
+
+const fs = require('fs-extra');
+const { join } = require('path');
+
+const file = join(__dirname, '../src/lib/utils/index.ts');
+
+const isStrict = process.argv[2] === 'true'
+
+fs.readFile(file, { encoding: 'utf-8'})
+    .then(text => fs.writeFile(file, text.replace(/type Strict =.*/, `type Strict = ${isStrict};`)))
+    .catch(reason => {
+        console.error(reason);
+        process.exit(1);
+    });
+

src/lib/application.ts

@@ -24,7 +24,7 @@ import {
     DUMMY_APPLICATION_OWNER
 } from './utils/component';
 import { Options, BindOption } from './utils';
-import { TypeDocAndTSOptions } from './utils/options/declaration';
+import { TypeDocAndTSOptions, TypeDocOptions } from './utils/options/declaration';
 
 /**
  * The default TypeDoc main application class.
@@ -115,7 +115,13 @@ export class Application extends ChildableComponent<
      * @param options  The desired options to set.
      */
     bootstrap(options: Partial<TypeDocAndTSOptions> = {}): { hasErrors: boolean, inputFiles: string[] } {
-        this.options.setValues(options); // Ignore result, plugins might declare an option
+        for (const [key, val] of Object.entries(options)) {
+            try {
+                this.options.setValue(key as keyof TypeDocOptions, val);
+            } catch {
+                // Ignore errors, plugins haven't been loaded yet and may declare an option.
+            }
+        }
         this.options.read(new Logger());
 
         const logger = this.loggerType;
@@ -130,11 +136,13 @@ export class Application extends ChildableComponent<
         this.plugins.load();
 
         this.options.reset();
-        this.options.setValues(options).mapErr(errors => {
-            for (const error of errors) {
+        for (const [key, val] of Object.entries(options)) {
+            try {
+                this.options.setValue(key as keyof TypeDocOptions, val);
+            } catch (error) {
                 this.logger.error(error.message);
             }
-        });
+        }
         this.options.read(this.logger);
 
         return {

src/lib/utils/index.ts

@@ -1,3 +1,35 @@
+/**
+ * This type provides a flag that can be used to turn off more lax overloads intended for
+ * plugin use only to catch type errors in the TypeDoc codebase. The prepublishOnly npm
+ * script will be used to switch this flag to false when publishing, then immediately back
+ * to true after a successful publish.
+ */
+type InternalOnly = true;
+
+/**
+ * Helper type to convert `T` to `F` if strict mode is on.
+ *
+ * Can be used in overloads to map a parameter type to `never`. For example, the
+ * following function will work with any string argument, but to improve the type safety
+ * of internal code, we only ever want to pass 'a' or 'b' to it. Plugins on the other
+ * hand need to be able to pass any string to it. Overloads similar to this are used
+ * in the {@link Options} class.
+ *
+ * ```ts
+ * function over(flag: 'a' | 'b'): string
+ * function over(flag: IfStrict<string, never>): string
+ * function over(flag: string): string { return flag }
+ * ```
+ */
+export type IfInternal<T, F> = InternalOnly extends true ? T : F;
+
+/**
+ * Helper type to convert `T` to `never` if strict mode is on.
+ *
+ * See {@link IfInternal} for the rationale.
+ */
+export type NeverIfInternal<T> = IfInternal<never, T>;
+
 export {
     Options,
     ParameterType,
@@ -18,4 +50,3 @@ export {
 } from './fs';
 export { Logger, LogLevel, ConsoleLogger, CallbackLogger } from './loggers';
 export { PluginHost } from './plugins';
-export { Result } from './result';

src/lib/utils/options/declaration.ts

@@ -1,6 +1,5 @@
 import * as _ from 'lodash';
 import { CompilerOptions } from 'typescript';
-import { Result } from '../result';
 import { IgnoredTsOptionKeys } from './sources/typescript';
 
 /**
@@ -52,6 +51,7 @@ export interface TypeDocOptionMap {
     excludeNotExported: boolean;
     excludePrivate: boolean;
     excludeProtected: boolean;
+    excludeNotDocumented: boolean;
     ignoreCompilerErrors: boolean;
     disableSources: boolean;
     includes: string;
@@ -249,49 +249,49 @@ export type DeclarationOptionToOptionType<T extends DeclarationOption> =
  * @param option The option for which the value should be converted.
  * @returns The result of the conversion. Might be the value or an error.
  */
-export function convert<T extends DeclarationOption>(value: unknown, option: T): Result<DeclarationOptionToOptionType<T>, string>;
-export function convert<T extends DeclarationOption>(value: unknown, option: T): Result<unknown, string> {
+export function convert<T extends DeclarationOption>(value: unknown, option: T): DeclarationOptionToOptionType<T>;
+export function convert<T extends DeclarationOption>(value: unknown, option: T): unknown {
     switch (option.type) {
         case undefined:
         case ParameterType.String:
-            return Result.Ok(value == null ? '' : String(value));
+            return value == null ? '' : String(value);
         case ParameterType.Number:
             const numberOption = option as NumberDeclarationOption;
             const numValue = parseInt(String(value), 10) || 0;
             if (!valueIsWithinBounds(numValue, numberOption.minValue, numberOption.maxValue)) {
-                return Result.Err(getBoundsError(numberOption.name, numberOption.minValue, numberOption.maxValue));
+                throw new Error(getBoundsError(numberOption.name, numberOption.minValue, numberOption.maxValue));
             }
-            return Result.Ok(numValue);
+            return numValue;
         case ParameterType.Boolean:
-            return Result.Ok(Boolean(value));
+            return Boolean(value);
         case ParameterType.Array:
             if (Array.isArray(value)) {
-                return Result.Ok(value.map(String));
+                return value.map(String);
             } else if (typeof value === 'string') {
-                return Result.Ok(value.split(','));
+                return value.split(',');
             }
-            return Result.Ok([]);
+            return [];
         case ParameterType.Map:
             const optionMap = option as MapDeclarationOption<unknown>;
             const key = String(value).toLowerCase();
             if (optionMap.map instanceof Map) {
                 if (optionMap.map.has(key)) {
-                    return Result.Ok(optionMap.map.get(key));
+                    return optionMap.map.get(key);
                 }
                 if ([...optionMap.map.values()].includes(value)) {
-                    return Result.Ok(value);
+                    return value;
                 }
             } else {
                 if (optionMap.map.hasOwnProperty(key)) {
-                    return Result.Ok(optionMap.map[key]);
+                    return optionMap.map[key];
                 }
                 if (Object.values(optionMap.map).includes(value)) {
-                    return Result.Ok(value);
+                    return value;
                 }
             }
-            return Result.Err(optionMap.mapError ?? getMapError(optionMap.map, optionMap.name));
+            throw new Error(optionMap.mapError ?? getMapError(optionMap.map, optionMap.name));
         case ParameterType.Mixed:
-            return Result.Ok(value);
+            return value;
     }
 }
 

src/lib/utils/options/options.ts

@@ -3,10 +3,10 @@ import * as ts from 'typescript';
 
 import { DeclarationOption, ParameterScope, ParameterType, convert, TypeDocOptions, KeyToDeclaration, TypeDocAndTSOptions, TypeDocOptionMap } from './declaration';
 import { Logger } from '../loggers';
-import { Result, Ok, Err } from '../result';
 import { insertPrioritySorted } from '../array';
 import { addTSOptions, addTypeDocOptions } from './sources';
 import { Application } from '../../..';
+import { NeverIfInternal } from '..';
 
 /**
  * Describes an option reader that discovers user configuration and converts it to the
@@ -148,7 +148,7 @@ export class Options {
      * Adds an option declaration to the container.
      * @param declaration
      */
-    addDeclaration(declaration: Readonly<DeclarationOption>): void;
+    addDeclaration(declaration: NeverIfInternal<Readonly<DeclarationOption>>): void;
 
     addDeclaration(declaration: Readonly<DeclarationOption>): void {
         const names = [declaration.name];
@@ -172,10 +172,15 @@ export class Options {
     /**
      * Adds the given declarations to the container
      * @param declarations
+     *
+     * @privateRemarks
+     * This function explicitly provides a way out of the strict typing enforced
+     * by {@link addDeclaration}. It should only be used with careful validation
+     * of the declaration map. Internally, it is only used for adding TS options
      */
     addDeclarations(declarations: readonly DeclarationOption[]): void {
         for (const decl of declarations) {
-            this.addDeclaration(decl);
+            this.addDeclaration(decl as any);
         }
     }
 
@@ -217,11 +222,11 @@ export class Options {
      * Checks if the given option has a set value or if the value is the default value.
      * @param name
      */
-    isDefault(name: keyof TypeDocAndTSOptions): boolean;
-    isDefault(name: string): boolean;
+    isDefault(name: keyof TypeDocOptions): boolean;
+    isDefault(name: NeverIfInternal<string>): boolean;
     isDefault(name: string): boolean {
         // getValue will throw if the declaration does not exist.
-        return this.getValue(name) === this.getDeclaration(name)!.defaultValue;
+        return this.getValue(name as keyof TypeDocOptions) === this.getDeclaration(name)!.defaultValue;
     }
 
     /**
@@ -236,32 +241,18 @@ export class Options {
      * @param name
      */
     getValue<K extends keyof TypeDocOptions>(name: K): TypeDocOptions[K];
-    getValue(name: string): unknown;
+    getValue(name: NeverIfInternal<string>): unknown;
     getValue(name: string): unknown {
-        return this.tryGetValue(name).match({
-            ok: v => v,
-            err(err) { throw err; }
-        });
-    }
-
-    /**
-     * Tries to get the given option key, returns an [[Ok]] result if the option has been
-     * declared with a TypeDoc scope, or an [[Err]] result otherwise.
-     * @param name
-     */
-    tryGetValue<K extends keyof TypeDocOptions>(name: K): Result<TypeDocOptions[K], Error>;
-    tryGetValue(name: string): Result<unknown, Error>;
-    tryGetValue(name: string): Result<unknown, Error> {
         const declaration = this.getDeclaration(name);
         if (!declaration) {
-            return Err(new Error(`Unknown option '${name}'`));
+            throw new Error(`Unknown option '${name}'`);
         }
 
         if (declaration.scope === ParameterScope.TypeScript) {
-            return Err(new Error('TypeScript options must be fetched with getCompilerOptions.'));
+            throw new Error('TypeScript options must be fetched with getCompilerOptions.');
         }
 
-        return Ok(this._values[declaration.name]);
+        return this._values[declaration.name];
     }
 
     /**
@@ -272,47 +263,35 @@ export class Options {
     }
 
     /**
-     * Sets the given declared option. Returns a result with the Err set if the option fails,
-     * otherwise Ok(void).
+     * Sets the given declared option. Throws if setting the option fails.
      * @param name
      * @param value
      */
-    setValue<K extends keyof TypeDocAndTSOptions>(name: K, value: TypeDocAndTSOptions[K]): Result<void, Error>;
-    setValue(name: string, value: unknown): Result<void, Error>;
-    setValue(name: string, value: unknown): Result<void, Error> {
+    setValue<K extends keyof TypeDocAndTSOptions>(name: K, value: TypeDocAndTSOptions[K]): void;
+    setValue(name: NeverIfInternal<string>, value: NeverIfInternal<unknown>): void;
+    setValue(name: string, value: unknown): void {
         const declaration = this.getDeclaration(name);
         if (!declaration) {
-            return Err(Error(`Tried to set an option (${name}) that was not declared.`));
+            throw new Error(`Tried to set an option (${name}) that was not declared.`);
         }
 
-        return convert(value, declaration).match({
-            ok: value => {
-                const bag = declaration.scope === ParameterScope.TypeScript
-                    ? this._compilerOptions
-                    : this._values;
-                bag[declaration.name] = value;
-                return Ok(void 0);
-            },
-            err: err => Err(Error(err))
-        });
+        const converted = convert(value, declaration);
+        const bag = declaration.scope === ParameterScope.TypeScript
+            ? this._compilerOptions
+            : this._values;
+        bag[declaration.name] = converted;
     }
 
     /**
-     * Sets all the given option values, returns a result with an array of errors for
-     * keys which failed to be set.
+     * Sets all the given option values, throws if any value fails to be set.
      * @param obj
+     * @deprecated will be removed in 0.19. Use setValue in a loop instead.
      */
-    setValues(obj: Partial<TypeDocAndTSOptions>): Result<void, Error[]> {
-        const errors: Error[] = [];
+    setValues(obj: NeverIfInternal<Partial<TypeDocAndTSOptions>>): void {
+        this._logger.warn('Options.setValues is deprecated and will be removed in 0.19.');
         for (const [name, value] of Object.entries(obj)) {
-            this.setValue(name, value).match({
-                ok() {},
-                err(error) {
-                    errors.push(error);
-                }
-            });
+            this.setValue(name as keyof TypeDocOptions, value);
         }
-        return errors.length ? Err(errors) : Ok(void 0);
     }
 
     /**
@@ -325,8 +304,7 @@ export class Options {
             if (declaration.type === ParameterType.Map) {
                 this._values[declaration.name] = declaration.defaultValue;
             } else {
-                this._values[declaration.name] = convert(declaration.defaultValue, declaration)
-                    .expect(`Failed to validate default value for ${declaration.name}`);
+                this._values[declaration.name] = convert(declaration.defaultValue, declaration);
             }
         }
     }
@@ -350,17 +328,17 @@ export function BindOption<K extends keyof TypeDocOptionMap>(name: K):
  * @privateRemarks
  * This overload is intended for plugin use only with looser type checks. Do not use internally.
  */
-export function BindOption(name: string):
+export function BindOption(name: NeverIfInternal<string>):
     (target: { application: Application } | { options: Options }, key: PropertyKey) => void;
 
 export function BindOption(name: string) {
     return function(target: { application: Application } | { options: Options }, key: PropertyKey) {
         Object.defineProperty(target, key, {
             get(this: { application: Application } | { options: Options }) {
                 if ('options' in this) {
-                    return this.options.getValue(name);
+                    return this.options.getValue(name as keyof TypeDocOptions);
                 } else {
-                    return this.application.options.getValue(name);
+                    return this.application.options.getValue(name as keyof TypeDocOptions);
                 }
             },
             enumerable: true,