docs: optimize ts docs

Author: janniks

package-lock.json

@@ -67,14 +67,14 @@
     "rollup-plugin-node-globals": "^1.4.0",
     "rollup-plugin-terser": "^7.0.2",
     "stream-http": "^3.2.0",
-    "typedoc": "^0.22.13",
+    "typedoc": "^0.22.15",
     "typescript": "^4.2.4",
     "vite-compatible-readable-stream": "^3.6.0"
   },
   "scripts": {
     "bootstrap": "lerna bootstrap",
     "build": "lerna run build",
-    "build:docs": "rimraf docs && typedoc --tsconfig tsconfig.typedoc.json packages/**/src/index.ts --release-version $(node -p \"require('./lerna.json').version\")",
+    "build:docs": "rimraf docs && RELEASE_VERSION=$(node -p \"require('./lerna.json').version\") && typedoc --tsconfig tsconfig.typedoc.json packages/**/src/index.ts --release-version $RELEASE_VERSION",
     "clean": "lerna clean",
     "lerna": "lerna",
     "lint": "npm run lint:eslint && npm run lint:prettier",

package.json

@@ -7,28 +7,36 @@ const defaultFetchOpts: RequestInit = {
   referrerPolicy: 'origin', // Use origin value for referrer policy
   // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
 };
-/*
+
+/**
  * Get fetch options
- * @return fetchOptions
+ * @category Network
  */
 export const getFetchOptions = () => {
   return defaultFetchOpts;
 };
-/*
- * Set fetch options
- * Users can change default referrer as well as other options when fetch is used internally by stacks.js libraries or from server side
+
+/**
+ * Sets global fetch options for stacks.js network calls.
+ *
  * @example
- *  Reference: https://developer.mozilla.org/en-US/docs/Web/API/Request/Request
- *  setFetchOptions({  referrer: 'no-referrer', referrerPolicy: 'no-referrer', ... other options as per above reference  });
- * Now all the subsequent fetchPrivate will use above options
- * @return fetchOptions
+ * Users can change the default referrer as well as other options when fetch is used internally by stacks.js:
+ * ```
+ * setFetchOptions({ referrer: 'no-referrer', referrerPolicy: 'no-referrer', ...otherRequestOptions });
+ * ```
+ * After calling {@link setFetchOptions} all subsequent network calls will use the specified options above.
+ *
+ * @see MDN Request: https://developer.mozilla.org/en-US/docs/Web/API/Request/Request
+ * @returns global fetch options after merging with previous options (or defaults)
+ * @category Network
+ * @related {@link getFetchOptions}
  */
-export const setFetchOptions = (ops: RequestInit) => {
+export const setFetchOptions = (ops: RequestInit): RequestInit => {
   return Object.assign(defaultFetchOpts, ops);
 };
 
-/** @ignore */
-export async function fetchPrivate(input: RequestInfo, init?: RequestInit): Promise<Response> {
+/** @internal */
+export async function fetchWrapper(input: RequestInfo, init?: RequestInit): Promise<Response> {
   const fetchOpts = {};
   // Use the provided options in request options along with default or user provided values
   Object.assign(fetchOpts, init, defaultFetchOpts);
@@ -76,6 +84,14 @@ export function hostMatches(host: string, pattern: string | RegExp) {
   return (pattern as RegExp).exec(host);
 }
 
+/**
+ * Creates a new middleware from an API key.
+ * @example
+ * ```
+ * const apiMiddleware = createApiKeyMiddleware("example_e8e044a3_41d8b0fe_3dd3988ef302");
+ * ```
+ * @category Network
+ */
 export function createApiKeyMiddleware({
   apiKey,
   host = /(.*)api(.*)\.stacks\.co$/i,
@@ -104,9 +120,8 @@ function createDefaultMiddleware(): FetchMiddleware[] {
   return [setOriginMiddleware];
 }
 
-// Argument helper function for {createFetchFn}
 function argsForCreateFetchFn(args: any[]): { middlewares: FetchMiddleware[]; fetchLib: FetchFn } {
-  let fetchLib: FetchFn = fetch;
+  let fetchLib: FetchFn = fetchWrapper;
   let middlewares: FetchMiddleware[] = [];
   if (args.length > 0 && typeof args[0] === 'function') {
     fetchLib = args.shift();
@@ -117,6 +132,16 @@ function argsForCreateFetchFn(args: any[]): { middlewares: FetchMiddleware[]; fe
   return { middlewares, fetchLib };
 }
 
+/**
+ * Creates a new network fetching function, which combines an optional fetch-compatible library with optional middlware.
+ * @example
+ * ```
+ * const customFetch = createFetchFn(someMiddleware)
+ * const customFetch = createFetchFn(fetch, someMiddleware)
+ * const customFetch = createFetchFn(fetch, middlewareA, middlewareB)
+ * ```
+ * @category Network
+ */
 export function createFetchFn(fetchLib: FetchFn, ...middleware: FetchMiddleware[]): FetchFn;
 export function createFetchFn(...middleware: FetchMiddleware[]): FetchFn;
 export function createFetchFn(...args: any[]): FetchFn {
@@ -125,6 +150,7 @@ export function createFetchFn(...args: any[]): FetchFn {
 
   const fetchFn = async (url: string, init?: RequestInit | undefined): Promise<Response> => {
     let fetchParams = { url, init: init ?? {} };
+
     for (const middleware of middlewares) {
       if (typeof middleware.pre !== 'function') continue;
       const result = await Promise.resolve(

packages/common/src/fetchUtil.ts

@@ -1,14 +1,17 @@
-import { fetchPrivate, getFetchOptions, setFetchOptions } from '../src'
-import fetchMock from "jest-fetch-mock";
+import { fetchWrapper, getFetchOptions, setFetchOptions } from '../src';
+import fetchMock from 'jest-fetch-mock';
 
 test('Verify fetch private options', async () => {
-  const defaultOptioins  = getFetchOptions();
+  const defaultOptioins = getFetchOptions();
 
   expect(defaultOptioins).toEqual({ referrerPolicy: 'origin' });
 
   // Override default options when fetchPrivate is called internally by other stacks.js libraries like transactions or from server side
   // This is for developers as they cannot directly pass options directly in fetchPrivate
-  const modifiedOptions: RequestInit= { referrer: 'http://test.com', referrerPolicy: 'same-origin' };
+  const modifiedOptions: RequestInit = {
+    referrer: 'http://test.com',
+    referrerPolicy: 'same-origin',
+  };
 
   // Developers can set fetch options globally one time specifically when fetchPrivate is used internally by stacks.js libraries
   setFetchOptions(modifiedOptions);
@@ -18,11 +21,10 @@ test('Verify fetch private options', async () => {
   // Browser will replace about:client with actual url but it will not be visible in test case
   fetchMock.mockOnce(`{ status: 'success'}`, { headers: modifiedOptions as any });
 
-  const result = await fetchPrivate('https://example.com');
+  const result = await fetchWrapper('https://example.com');
 
   // Verify the request options
   expect(result.status).toEqual(200);
   expect(result.headers.get('referrer')).toEqual(modifiedOptions.referrer);
   expect(result.headers.get('referrerPolicy')).toEqual(modifiedOptions.referrerPolicy);
-})
-
+});

packages/common/tests/fetch.test.ts

@@ -1,12 +1,11 @@
 import { makeAuthResponse } from '@stacks/auth';
-import { FetchFn, createFetchFn } from '@stacks/common';
+import { createFetchFn, FetchFn } from '@stacks/common';
 import { getPublicKeyFromPrivate, publicKeyToAddress } from '@stacks/encryption';
 import { bip32 } from 'bitcoinjs-lib';
 import { Identity as IdentifyInterface, Profile } from './common';
 import IdentityAddressOwnerNode from './nodes/identity-address-owner-node';
 import { DEFAULT_PROFILE, fetchProfile, signAndUploadProfile } from './profiles';
 import { getProfileURLFromZoneFile, IdentityKeyPair } from './utils';
-import { fetchPrivate } from '@stacks/common';
 import {
   connectToGaiaHubWithConfig,
   DEFAULT_GAIA_HUB,

packages/keychain/src/identity.ts

@@ -1,13 +1,11 @@
-import { Buffer, fetchPrivate } from '@stacks/common';
-import { sha256, sha512 } from 'sha.js';
-import { ClarityValue, serializeCV } from './clarity';
-import RIPEMD160 from 'ripemd160-min';
+import { bytesToHex } from '@noble/hashes/utils';
 import { utils } from '@noble/secp256k1';
-import { deserializeCV } from './clarity';
+import { Buffer, with0x } from '@stacks/common';
 import { c32addressDecode } from 'c32check';
 import lodashCloneDeep from 'lodash.clonedeep';
-import { with0x } from '@stacks/common';
-import { bytesToHex } from '@noble/hashes/utils';
+import RIPEMD160 from 'ripemd160-min';
+import { sha256, sha512 } from 'sha.js';
+import { ClarityValue, deserializeCV, serializeCV } from './clarity';
 
 /**
  * Use utils.randomBytes to replace randombytes dependency
@@ -197,9 +195,6 @@ export function isClarityName(name: string) {
   return regex.test(name) && name.length < 128;
 }
 
-/** @ignore */
-export { fetchPrivate };
-
 /**
  * Converts a clarity value to a hex encoded string with `0x` prefix
  * @param {ClarityValue} cv  - the clarity value to convert

packages/transactions/src/utils.ts

@@ -12,8 +12,11 @@
     "theme": "stacks",
     "excludePrivate": true,
     "excludeProtected": true,
-    "gitRevision": "master",
     "listInvalidSymbolLinks": true,
+    "categoryOrder": [
+      "*",
+      "Other"
+    ],
     // theme and plugin options
     "external-modulemap": ".*\/packages\/([\\w\\-_]+)\/",
     "package-prefix": "@stacks",