chore: various doc + typing + CI touchups (#270)

- [x] properly run typechecking during CI
- [x] JSDocs + type enhancements
- [x] super hard to notice bug fix

---------

Co-authored-by: Jon Ursenbach <[email protected]>

Author: kanadgupta

package-lock.json

@@ -70,7 +70,7 @@
     "attw": "attw --pack --format table-flipped",
     "build": "tsup",
     "clean": "rm -rf dist/",
-    "lint": "npm run lint:js && npm run prettier",
+    "lint": "npm run lint:js && npm run prettier && tsc",
     "lint:js": "eslint . --ext .js,.cjs,.ts && prettier --check .",
     "prebuild": "npm run clean",
     "prepack": "npm run build",
@@ -80,7 +80,8 @@
   },
   "dependencies": {
     "qs": "^6.11.2",
-    "stringify-object": "^3.3.0"
+    "stringify-object": "^3.3.0",
+    "type-fest": "^4.15.0"
   },
   "devDependencies": {
     "@readme/eslint-config": "^14.4.2",
@@ -94,7 +95,6 @@
     "prettier": "^3.0.3",
     "require-directory": "^2.1.1",
     "tsup": "^8.0.1",
-    "type-fest": "^4.15.0",
     "typescript": "^5.4.4",
     "vitest": "^3.0.5"
   },

package.json

@@ -1,7 +1,9 @@
+import type { CodeBuilderOptions } from './helpers/code-builder.js';
 import type { ReducedHelperObject } from './helpers/reducer.js';
 import type { ClientId, TargetId } from './targets/index.js';
 import type { Param, PostDataCommon, Request as NpmHarRequest } from 'har-format';
 import type { UrlWithParsedQuery } from 'node:url';
+import type { Merge } from 'type-fest';
 
 import { format as urlFormat, parse as urlParse } from 'node:url';
 
@@ -25,6 +27,8 @@ type PostDataBase = PostDataCommon & {
   text?: string;
 };
 
+export type { Client } from './targets/index.js';
+
 export type HarRequest = Omit<NpmHarRequest, 'postData'> & { postData: PostDataBase };
 
 export interface RequestExtras {
@@ -58,6 +62,8 @@ interface HarEntry {
   };
 }
 
+export type Options = Merge<CodeBuilderOptions, Record<string, any>>;
+
 export interface HTTPSnippetOptions {
   harIsAlreadyEncoded?: boolean;
 }
@@ -318,13 +324,13 @@ export class HTTPSnippet {
     };
   }
 
-  convert(targetId: TargetId, clientId?: ClientId, options?: any) {
+  convert(targetId: TargetId, clientId?: ClientId, options?: Options) {
     if (!this.initCalled) {
       this.init();
     }
 
     if (!options && clientId) {
-      options = clientId;
+      options = { clientId };
     }
 
     const target = targets[targetId];
@@ -337,13 +343,13 @@ export class HTTPSnippet {
     return results;
   }
 
-  installation(targetId: TargetId, clientId?: ClientId, options?: any) {
+  installation(targetId: TargetId, clientId?: ClientId, options?: Options) {
     if (!this.initCalled) {
       this.init();
     }
 
     if (!options && clientId) {
-      options = clientId;
+      options = { clientId };
     }
 
     const target = targets[targetId];

src/index.ts

@@ -303,8 +303,8 @@ describe('addTargetClient', () => {
         link: 'https://example.com',
         description: 'A custom HTTP library',
         extname: '.custom',
-        installation: request => {
-          return `brew install ${request.fullUrl}`;
+        installation: (request, opts) => {
+          return `brew install ${request.fullUrl}/${opts?.clientId}`;
         },
       },
       convert: () => {
@@ -320,7 +320,7 @@ describe('addTargetClient', () => {
     expect(result).toBe('This was generated from a custom client.');
 
     const install = snippet.installation('node', 'custom')[0];
-    expect(install).toBe('brew install https://httpbin.org/anything');
+    expect(install).toBe('brew install https://httpbin.org/anything/custom');
   });
 });
 

src/targets/index.test.ts

@@ -27,16 +27,47 @@ export type TargetId = keyof typeof targets;
 export type ClientId = string;
 
 export interface ClientInfo<T extends Record<string, any> = Record<string, any>> {
+  /**
+   * A description of the client.
+   *
+   * @example Promise based HTTP client for the browser and node.js
+   */
   description: string;
+
+  /**
+   * The default file extension for the client.
+   *
+   * @example `.js`
+   */
   extname: Extension;
   /**
    * Retrieve or generate a command to install the client.
    *
-   * @example `npm install axios`
+   * @example () => 'npm install axios --save';
    */
   installation?: Converter<T>;
+
+  /**
+   * A unique identifier for the client.
+   *
+   * This should be a string that is unique to the client for the given target.
+   *
+   * @example `axios`
+   */
   key: ClientId;
+
+  /**
+   * A link to the documentation or homepage of the client.
+   *
+   * @example https://github.com/axios/axios
+   */
   link: string;
+
+  /**
+   * The formatted name of the client.
+   *
+   * @example Axios
+   */
   title: string;
 }
 

src/targets/index.ts

@@ -7,6 +7,7 @@
     "lib": ["DOM", "ES2020"],
     "module": "ESNext",
     "moduleResolution": "Bundler",
+    "noEmit": true,
     "outDir": "dist",
     "resolveJsonModule": true,
     "target": "ES2020",