Add support for errors being mapped to unknown types (#79)

* WIP - Error/unknown support

* Change files

* Added tests

* PR Feedback: Tweaked change log

Author: JakeShirley

README.md

@@ -40,6 +40,8 @@ All packages are validated via ESLint with a consistent set of rules as well as
 
 All packages support testing via `vitest`. Tests are authored with the `.test.ts` suffix and tests can be run with `npm run test`.
 
+Snapshot tests will fail if the number of files generated or the contents of the files change. If snapshot changes are expected, you can update them by running: `npm run test:update`
+
 ## Contributing
 
 See [Contributing.md](./CONTRIBUTING.md) for details on contributions

change/@minecraft-api-docs-generator-1ad6e5ce-d72c-4412-97fa-5af5b98fee10.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Added support for Error types as function arguments to the TypeScript generator.  They will be typed as 'unknown'",
+  "packageName": "@minecraft/api-docs-generator",
+  "email": "[email protected]",
+  "dependentChangeType": "none"
+}

tools/api-docs-generator-test-snapshots/README.md

@@ -3,3 +3,12 @@
 This package contains vitest snapshots for various @minecraft/api-docs-generator scenarios, processing different configurations of Minecraft API metadata with different combinations of markup generator outputs.
 
 It exists as a separate package in order to import both @minecraft/api-docs-generator and the @minecraft/markup-generators-plugin packages and test them together.
+
+## Testing
+
+This package is validated with a series of vitest snapshot tests that validate generated markup for specific scenarios. When making changes to the generator, please add new scenarios or update the existing scenarios.
+
+Snapshot tests will fail if the number of files generated or the contents of the files change. If snapshot changes are expected, you can update them by running: `npm run test:update` at the root of the repository.
+
+It is possible to run specific tests using `npm run test -- -- --test <name>`, where `<name>` is a pattern matching `.test.ts`/`.spec.ts`file names. Running this in the JavaScript Debug Terminal allows for debugging specific tests (see above).
+

tools/api-docs-generator-test-snapshots/test/errors/__snapshots__/errors.spec.ts.snap

@@ -91,11 +91,25 @@ Notes:
     - Throws [*ExampleError*](ExampleError.md)
 
 ## Methods
+- [exampleMethodThatTakesErrorParam](#examplemethodthattakeserrorparam)
 - [exampleMethodThatThrows](#examplemethodthatthrows)
 - [exampleMethodThatThrowsCustomError](#examplemethodthatthrowscustomerror)
 - [exampleMethodThatThrowsTwoErrors](#examplemethodthatthrowstwoerrors)
 - [exampleMethodThatThrowsWithReadOnlyPrivilege](#examplemethodthatthrowswithreadonlyprivilege)
 
+### **exampleMethodThatTakesErrorParam**
+\`
+exampleMethodThatTakesErrorParam(errorParam: unknown): string
+\`
+
+#### **Parameters**
+- **errorParam**: *unknown*
+
+**Returns** *string*
+  
+Notes:
+- This function can't be called in read-only mode.
+
 ### **exampleMethodThatThrows**
 \`
 exampleMethodThatThrows(): string
@@ -432,6 +446,12 @@ export class ExampleClass {
      * {@link ExampleError}
      */
     examplePropertyWithCrossModuleReturnAndError: minecraftexamplemodule2.CrossModuleReturn;
+    /**
+     * @remarks
+     * This function can't be called in read-only mode.
+     *
+     */
+    exampleMethodThatTakesErrorParam(errorParam: unknown): string;
     /**
      * @remarks
      * This function can't be called in read-only mode.

tools/api-docs-generator-test-snapshots/test/errors/input/test-script-module.json

@@ -4,6 +4,25 @@
       "base_types": [],
       "constants": [],
       "functions": [
+         {
+          "arguments": [
+            {
+              "name": "errorParam",
+              "type": {
+                "is_bind_type": false,
+                "is_errorable": false,
+                "name": "error"
+              }
+            }
+          ],
+          "is_constructor": false,
+          "name": "exampleMethodThatTakesErrorParam",
+          "return_type": {
+            "is_bind_type": false,
+            "is_errorable": false,
+            "name": "string"
+          }
+        },
         {
           "arguments": [],
           "is_constructor": false,

tools/api-docs-generator/README.md

@@ -86,7 +86,7 @@ We recommend using Visual Studio Code's [JavaScript Debug Terminal](https://code
 
 This package is validated with a series of vitest snapshot tests that validate generated markup for specific scenarios. When making changes to the generator, please add new scenarios or update the existing scenarios.
 
-Snapshot tests will fail if the number of files generated or the contents of the files change. If snapshot changes are expected, you can update them by running: `npm run test:update`
+Snapshot tests will fail if the number of files generated or the contents of the files change. If snapshot changes are expected, you can update them by running: `npm run test:update` at the root of the repository.
 
 It is possible to run specific tests using `npm run test -- -- --test <name>`, where `<name>` is a pattern matching `.test.ts`/`.spec.ts`file names. Running this in the JavaScript Debug Terminal allows for debugging specific tests (see above).
 

tools/api-docs-generator/src/filters/TypeScriptFilters.ts

@@ -22,6 +22,7 @@ const typescriptTypeMappings: Record<string, string> = {
     uint64: 'number',
     float: 'number',
     double: 'number',
+    error: 'unknown', // You can throw anything in JavaScript, so the type is unknown
 };
 
 /**