feat: user-defined required constructor options (#63)

Co-authored-by: Josh Goldberg <me@joshuakgoldberg.com>

Author: gr2m

examples/required-options/README.md

@@ -0,0 +1,29 @@
+# required options Example
+
+`Base` has no required options by default, so the following code has no type errors.
+
+```js
+import { Base } from "javascript-plugin-architecture-with-typescript-definitions";
+
+const base1 = new Base();
+const base2 = new Base({});
+```
+
+But required options can be added by extending the `Base.Options` interface.
+
+```ts
+declare module "javascript-plugin-architecture-with-typescript-definitions" {
+  namespace Base {
+    interface Options {
+      myRequiredUserOption: string;
+    }
+  }
+}
+```
+
+With that extension, the same code will have a type error
+
+```ts
+// TS Error: Property 'myRequiredUserOption' is missing in type '{}' but required in type 'Options'
+const base = new Base({});
+```

examples/required-options/index.d.ts

@@ -0,0 +1,11 @@
+import { Base } from "../../index.js";
+
+declare module "../.." {
+  namespace Base {
+    interface Options {
+      myRequiredUserOption: string;
+    }
+  }
+}
+
+export class MyBase extends Base {}

examples/required-options/index.js

@@ -0,0 +1,13 @@
+import { Base } from "../../index.js";
+
+/**
+ * @param {Base} base
+ * @param {Base.Options} options
+ */
+function pluginRequiringOption(base, options) {
+  if (typeof options.myRequiredUserOption !== "string") {
+    throw new Error('Required option "myRequiredUserOption" missing');
+  }
+}
+
+export const MyBase = Base.plugin(pluginRequiringOption);

examples/required-options/index.test-d.ts

@@ -0,0 +1,17 @@
+import { MyBase } from "./index.js";
+
+// @ts-expect-error - An argument for 'options' was not provided
+new MyBase();
+
+// @ts-expect-error - Type '{}' is missing the following properties from type 'Options': myRequiredUserOption
+new MyBase({});
+
+new MyBase({
+  myRequiredUserOption: "",
+});
+
+const MyBaseWithDefaults = MyBase.defaults({
+  myRequiredUserOption: "",
+});
+
+new MyBaseWithDefaults();

examples/required-options/test.js

@@ -0,0 +1,18 @@
+import { test } from "uvu";
+import * as assert from "uvu/assert";
+
+import { MyBase } from "./index.js";
+
+test("new MyBase()", () => {
+  assert.throws(() => new MyBase());
+});
+
+test("new MyBase({})", () => {
+  assert.throws(() => new MyBase({}));
+});
+
+test('new MyBase({ myRequiredUserOption: ""})', () => {
+  assert.not.throws(() => new MyBase({ myRequiredUserOption: "" }));
+});
+
+test.run();

index.d.ts

@@ -1,8 +1,5 @@
 export declare namespace Base {
-  interface Options {
-    version: string;
-    [key: string]: unknown;
-  }
+  interface Options { }
 }
 
 declare type ApiExtension = {
@@ -26,28 +23,36 @@ declare type UnionToIntersection<Union> = (
 declare type AnyFunction = (...args: any) => any;
 declare type ReturnTypeOf<T extends AnyFunction | AnyFunction[]> =
   T extends AnyFunction
-    ? ReturnType<T>
-    : T extends AnyFunction[]
-    ? UnionToIntersection<Exclude<ReturnType<T[number]>, void>>
-    : never;
+  ? ReturnType<T>
+  : T extends AnyFunction[]
+  ? UnionToIntersection<Exclude<ReturnType<T[number]>, void>>
+  : never;
 
 type ClassWithPlugins = Constructor<any> & {
-  plugins: any[];
+  plugins: Plugin[];
 };
 
+type RemainingRequirements<PredefinedOptions> =
+  keyof PredefinedOptions extends never
+  ? Base.Options
+  : Omit<Base.Options, keyof PredefinedOptions>
+
+type NonOptionalKeys<Obj> = {
+  [K in keyof Obj]: {} extends Pick<Obj, K> ? undefined : K;
+}[keyof Obj];
+
+type RequiredIfRemaining<PredefinedOptions, NowProvided> =
+  NonOptionalKeys<RemainingRequirements<PredefinedOptions>> extends undefined
+  ? [(Partial<Base.Options> & NowProvided)?]
+  : [Partial<Base.Options> & RemainingRequirements<PredefinedOptions> & NowProvided];
+
 type ConstructorRequiringVersion<Class extends ClassWithPlugins, PredefinedOptions> = {
   defaultOptions: PredefinedOptions;
-} & (PredefinedOptions extends { version: string }
-  ? {
-      new <NowProvided>(options?: NowProvided): Class & {
-        options: NowProvided & PredefinedOptions;
-      };
-    }
-  : {
-      new <NowProvided>(options: Base.Options & NowProvided): Class & {
-        options: NowProvided & PredefinedOptions;
-      };
-    });
+} & {
+  new <NowProvided>(...options: RequiredIfRemaining<PredefinedOptions, NowProvided>): Class & {
+    options: NowProvided & PredefinedOptions;
+  };
+};
 
 export declare class Base<TOptions extends Base.Options = Base.Options> {
   static plugins: Plugin[];
@@ -74,9 +79,9 @@ export declare class Base<TOptions extends Base.Options = Base.Options> {
   static plugin<
     Class extends ClassWithPlugins,
     Plugins extends [Plugin, ...Plugin[]],
-  >(
-    this: Class,
-    ...plugins: Plugins,
+    >(
+      this: Class,
+      ...plugins: Plugins,
   ): Class & {
     plugins: [...Class['plugins'], ...Plugins];
   } & Constructor<UnionToIntersection<ReturnTypeOf<Plugins>>>;
@@ -130,4 +135,4 @@ export declare class Base<TOptions extends Base.Options = Base.Options> {
 
   constructor(options: TOptions);
 }
-export {};
+export { };