feat: required-options example

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.Optiions` interface.
+
+```ts
+declare module "javascript-plugin-architecture-with-typescript-definitions" {
+  namespace Base {
+    interface Options {
+      myRequiredUserOption: string;
+    }
+  }
+}
+```
+
+With that extension, the same code will have type 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,12 @@
+import { Base } from "../../index.js";
+export { 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 (!options.myRequiredUserOption) {
+    throw new Error('Required option "myRequiredUserOption" missing');
+  }
+}
+
+export const MyBase = Base.plugin(pluginRequiringOption);

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

@@ -0,0 +1,11 @@
+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: "",
+});

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();