Skip to content

Commit 97db3ae

Browse files
rekmarksrekmarks
committed
refactor: Fix require-jsdoc violations
1 parent 511fb65 commit 97db3ae

File tree

10 files changed

+181
-29
lines changed

10 files changed

+181
-29
lines changed

‎eslint-warning-thresholds.json‎

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -153,27 +153,6 @@
153153
"packages/eth-block-tracker/tests/withBlockTracker.ts": {
154154
"@typescript-eslint/no-explicit-any": 1
155155
},
156-
"packages/eth-json-rpc-middleware/src/block-cache.ts": {
157-
"jsdoc/require-jsdoc": 1
158-
},
159-
"packages/eth-json-rpc-middleware/src/methods/wallet-request-execution-permissions.ts": {
160-
"jsdoc/require-jsdoc": 1
161-
},
162-
"packages/eth-json-rpc-middleware/src/methods/wallet-revoke-execution-permission.ts": {
163-
"jsdoc/require-jsdoc": 1
164-
},
165-
"packages/eth-json-rpc-middleware/src/providerAsMiddleware.ts": {
166-
"jsdoc/require-jsdoc": 2
167-
},
168-
"packages/eth-json-rpc-middleware/src/utils/error.ts": {
169-
"jsdoc/require-jsdoc": 1
170-
},
171-
"packages/eth-json-rpc-middleware/src/utils/validation.ts": {
172-
"jsdoc/require-jsdoc": 4
173-
},
174-
"packages/eth-json-rpc-middleware/src/wallet.ts": {
175-
"jsdoc/require-jsdoc": 12
176-
},
177156
"packages/gas-fee-controller/src/GasFeeController.test.ts": {
178157
"import-x/namespace": 2,
179158
"import-x/order": 1

‎eslint.config.mjs‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -231,13 +231,6 @@ const config = createConfig([
231231
'@typescript-eslint/consistent-type-definitions': 'warn',
232232
},
233233
},
234-
{
235-
files: ['packages/eth-json-rpc-middleware/**/*.ts'],
236-
rules: {
237-
// TODO: Re-enable this
238-
'jsdoc/require-jsdoc': 'warn',
239-
},
240-
},
241234
{
242235
files: ['packages/foundryup/**/*.{js,ts}'],
243236
rules: {

‎packages/eth-json-rpc-middleware/src/block-cache.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,13 @@ class BlockCacheStrategy {
133133
}
134134
}
135135

136+
/**
137+
* Creates a middleware that caches block-related requests.
138+
*
139+
* @param options - The options for the middleware.
140+
* @param options.blockTracker - The block tracker to use.
141+
* @returns The block cache middleware.
142+
*/
136143
export function createBlockCacheMiddleware({
137144
blockTracker,
138145
}: BlockCacheMiddlewareOptions = {}): JsonRpcMiddleware<

‎packages/eth-json-rpc-middleware/src/methods/wallet-request-execution-permissions.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,15 @@ export type ProcessRequestExecutionPermissionsHook = (
6767
req: JsonRpcRequest,
6868
) => Promise<RequestExecutionPermissionsResult>;
6969

70+
/**
71+
* Creates a handler for the `wallet_requestExecutionPermissions` JSON-RPC method.
72+
*
73+
* @param options - The options for the handler.
74+
* @param options.processRequestExecutionPermissions - The function to process the
75+
* request execution permissions request.
76+
* @returns A JSON-RPC middleware function that handles the
77+
* `wallet_requestExecutionPermissions` JSON-RPC method.
78+
*/
7079
export function createWalletRequestExecutionPermissionsHandler({
7180
processRequestExecutionPermissions,
7281
}: {

‎packages/eth-json-rpc-middleware/src/methods/wallet-revoke-execution-permission.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,15 @@ export type ProcessRevokeExecutionPermissionHook = (
2727
req: JsonRpcRequest,
2828
) => Promise<RevokeExecutionPermissionResult>;
2929

30+
/**
31+
* Creates a handler for the `wallet_revokeExecutionPermission` JSON-RPC method.
32+
*
33+
* @param options - The options for the handler.
34+
* @param options.processRevokeExecutionPermission - The function to process the
35+
* revoke execution permission request.
36+
* @returns A JSON-RPC middleware function that handles the
37+
* `wallet_revokeExecutionPermission` JSON-RPC method.
38+
*/
3039
export function createWalletRevokeExecutionPermissionHandler({
3140
processRevokeExecutionPermission,
3241
}: {

‎packages/eth-json-rpc-middleware/src/providerAsMiddleware.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ import {
66
import type { JsonRpcMiddleware } from '@metamask/json-rpc-engine/v2';
77
import type { Json, JsonRpcParams, JsonRpcRequest } from '@metamask/utils';
88

9+
/**
10+
* Creates a legacy JSON-RPC middleware that forwards requests to a provider.
11+
*
12+
* @param provider - The provider to forward requests to.
13+
* @returns A legacy JSON-RPC middleware that forwards requests to the provider.
14+
* @deprecated Use {@link providerAsMiddlewareV2} instead.
15+
*/
916
export function providerAsMiddleware(
1017
provider: InternalProvider,
1118
): LegacyJsonRpcMiddleware<JsonRpcParams, Json> {
@@ -14,6 +21,12 @@ export function providerAsMiddleware(
1421
});
1522
}
1623

24+
/**
25+
* Creates a V2 JSON-RPC middleware that forwards requests to a provider.
26+
*
27+
* @param provider - The provider to forward requests to.
28+
* @returns A V2 JSON-RPC middleware that forwards requests to the provider.
29+
*/
1730
export function providerAsMiddlewareV2(
1831
provider: InternalProvider,
1932
): JsonRpcMiddleware<JsonRpcRequest, Json> {

‎packages/eth-json-rpc-middleware/src/utils/error.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@ import { errorCodes } from '@metamask/rpc-errors';
22
import { isJsonRpcError } from '@metamask/utils';
33
import type { JsonRpcError } from '@metamask/utils';
44

5+
/**
6+
* Checks if a value is a JSON-RPC error that indicates an execution reverted error.
7+
*
8+
* @param error - The value to check.
9+
* @returns True if the value is a JSON-RPC error that indicates an execution reverted
10+
* error, false otherwise.
11+
*/
512
export function isExecutionRevertedError(
613
error: unknown,
714
): error is JsonRpcError {

‎packages/eth-json-rpc-middleware/src/utils/validation.ts‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,17 @@ import type { Struct, StructError } from '@metamask/superstruct';
44
import { validate } from '@metamask/superstruct';
55
import type { Hex } from '@metamask/utils';
66

7+
/**
8+
* Validates and normalizes a keyholder address for transaction- and
9+
* signature-related operations.
10+
*
11+
* @param address - The Ethereum address to validate and normalize.
12+
* @param context - The context of the request.
13+
* @param options - The options for the validation.
14+
* @param options.getAccounts - The function to get the accounts for the origin.
15+
* @returns The normalized address, if valid. Otherwise, throws
16+
* an error
17+
*/
718
export async function validateAndNormalizeKeyholder(
819
address: Hex,
920
context: MiddlewareContext<{ origin: string }>,
@@ -36,6 +47,14 @@ export async function validateAndNormalizeKeyholder(
3647
});
3748
}
3849

50+
/**
51+
* Validates the parameters of a request against a Superstruct schema.
52+
* Throws a JSON-RPC error if the parameters are invalid.
53+
*
54+
* @param value - The value to validate.
55+
* @param struct - The Superstruct schema to validate against.
56+
* @throws An error if the parameters are invalid.
57+
*/
3958
export function validateParams<ParamsType>(
4059
value: unknown | ParamsType,
4160
struct: Struct<ParamsType>,
@@ -49,11 +68,24 @@ export function validateParams<ParamsType>(
4968
}
5069
}
5170

71+
/**
72+
* Checks if a string resembles an Ethereum address.
73+
*
74+
* @param str - The string to check.
75+
* @returns True if the string resembles an Ethereum address, false otherwise.
76+
*/
5277
export function resemblesAddress(str: string): boolean {
5378
// hex prefix 2 + 20 bytes
5479
return str.length === 2 + 20 * 2;
5580
}
5681

82+
/**
83+
* Formats a Superstruct validation error into a human-readable string.
84+
*
85+
* @param error - The Superstruct validation error.
86+
* @param message - The base error message to prepend to the formatted details.
87+
* @returns The formatted error.
88+
*/
5789
function formatValidationError(error: StructError, message: string): string {
5890
return `${message}\n\n${error
5991
.failures()

‎packages/eth-json-rpc-middleware/src/wallet.ts‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,25 @@ export type WalletMiddlewareParams = MiddlewareParams<
8888
WalletMiddlewareContext
8989
>;
9090

91+
/**
92+
* Creates a JSON-RPC middleware that handles "wallet"-related JSON-RPC methods.
93+
* "Wallet" may have had a specific meaning at some point in the distant past,
94+
* but at this point it's just an arbitrary label.
95+
*
96+
* @param options - The options for the middleware.
97+
* @param options.getAccounts - The function to get the accounts for the origin.
98+
* @param options.processDecryptMessage - The function to process the decrypt message request.
99+
* @param options.processEncryptionPublicKey - The function to process the encryption public key request.
100+
* @param options.processPersonalMessage - The function to process the personal message request.
101+
* @param options.processTransaction - The function to process the transaction request.
102+
* @param options.processSignTransaction - The function to process the sign transaction request.
103+
* @param options.processTypedMessage - The function to process the typed message request.
104+
* @param options.processTypedMessageV3 - The function to process the typed message v3 request.
105+
* @param options.processTypedMessageV4 - The function to process the typed message v4 request.
106+
* @param options.processRequestExecutionPermissions - The function to process the request execution permissions request.
107+
* @param options.processRevokeExecutionPermission - The function to process the revoke execution permission request.
108+
* @returns A JSON-RPC middleware that handles wallet-related JSON-RPC methods.
109+
*/
91110
export function createWalletMiddleware({
92111
getAccounts,
93112
processDecryptMessage,
@@ -142,12 +161,26 @@ export function createWalletMiddleware({
142161
// account lookups
143162
//
144163

164+
/**
165+
* Gets the accounts for the origin.
166+
*
167+
* @param options - Options bag.
168+
* @param options.context - The context of the request.
169+
* @returns The accounts for the origin.
170+
*/
145171
async function lookupAccounts({
146172
context,
147173
}: WalletMiddlewareParams): Promise<Json> {
148174
return await getAccounts(context.assertGet('origin'));
149175
}
150176

177+
/**
178+
* Gets the default account (i.e. first in the list) for the origin.
179+
*
180+
* @param options - Options bag.
181+
* @param options.context - The context of the request.
182+
* @returns The default account for the origin.
183+
*/
151184
async function lookupDefaultAccount({
152185
context,
153186
}: WalletMiddlewareParams): Promise<Json> {
@@ -159,6 +192,14 @@ export function createWalletMiddleware({
159192
// transaction signatures
160193
//
161194

195+
/**
196+
* Sends a transaction.
197+
*
198+
* @param options - Options bag.
199+
* @param options.request - The request.
200+
* @param options.context - The context of the request.
201+
* @returns The transaction hash.
202+
*/
162203
async function sendTransaction({
163204
request,
164205
context,
@@ -182,6 +223,14 @@ export function createWalletMiddleware({
182223
return await processTransaction(txParams, request);
183224
}
184225

226+
/**
227+
* Signs a transaction.
228+
*
229+
* @param options - Options bag.
230+
* @param options.request - The request.
231+
* @param options.context - The context of the request.
232+
* @returns The signed transaction.
233+
*/
185234
async function signTransaction({
186235
request,
187236
context,
@@ -209,6 +258,14 @@ export function createWalletMiddleware({
209258
// message signatures
210259
//
211260

261+
/**
262+
* Signs a `eth_signTypedData` message.
263+
*
264+
* @param options - Options bag.
265+
* @param options.request - The request.
266+
* @param options.context - The context of the request.
267+
* @returns The signed message.
268+
*/
212269
async function signTypedData({
213270
request,
214271
context,
@@ -244,6 +301,14 @@ export function createWalletMiddleware({
244301
return await processTypedMessage(msgParams, request, version);
245302
}
246303

304+
/**
305+
* Signs a `eth_signTypedData_v3` message.
306+
*
307+
* @param options - Options bag.
308+
* @param options.request - The request.
309+
* @param options.context - The context of the request.
310+
* @returns The signed message.
311+
*/
247312
async function signTypedDataV3({
248313
request,
249314
context,
@@ -276,6 +341,14 @@ export function createWalletMiddleware({
276341
return await processTypedMessageV3(msgParams, request, version);
277342
}
278343

344+
/**
345+
* Signs a `eth_signTypedData_v4` message.
346+
*
347+
* @param options - Options bag.
348+
* @param options.request - The request.
349+
* @param options.context - The context of the request.
350+
* @returns The signed message.
351+
*/
279352
async function signTypedDataV4({
280353
request,
281354
context,
@@ -308,6 +381,14 @@ export function createWalletMiddleware({
308381
return await processTypedMessageV4(msgParams, request, version);
309382
}
310383

384+
/**
385+
* Signs a `personal_sign` message.
386+
*
387+
* @param options - Options bag.
388+
* @param options.request - The request.
389+
* @param options.context - The context of the request.
390+
* @returns The signed message.
391+
*/
311392
async function personalSign({
312393
request,
313394
context,
@@ -358,6 +439,13 @@ export function createWalletMiddleware({
358439
return await processPersonalMessage(msgParams, request);
359440
}
360441

442+
/**
443+
* Recovers the signer address from a `personal_sign` message.
444+
*
445+
* @param options - Options bag.
446+
* @param options.request - The request.
447+
* @returns The recovered signer address.
448+
*/
361449
async function personalRecover({
362450
request,
363451
}: WalletMiddlewareParams): Promise<Json> {
@@ -380,6 +468,14 @@ export function createWalletMiddleware({
380468
return signerAddress;
381469
}
382470

471+
/**
472+
* Gets the encryption public key for an address.
473+
*
474+
* @param options - Options bag.
475+
* @param options.request - The request.
476+
* @param options.context - The context of the request.
477+
* @returns The encryption public key.
478+
*/
383479
async function encryptionPublicKey({
384480
request,
385481
context,
@@ -402,6 +498,14 @@ export function createWalletMiddleware({
402498
return await processEncryptionPublicKey(address, request);
403499
}
404500

501+
/**
502+
* Decrypts a message.
503+
*
504+
* @param options - Options bag.
505+
* @param options.request - The request.
506+
* @param options.context - The context of the request.
507+
* @returns The decrypted message.
508+
*/
405509
async function decryptMessage({
406510
request,
407511
context,

‎packages/eth-json-rpc-middleware/test/util/helpers.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@ export const createRequest = <
2020
jsonrpc: '2.0',
2121
id: request.id ?? '1',
2222
method: request.method ?? 'test_request',
23-
// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
2423
params: request.params === undefined ? [] : request.params,
2524
} as Output;
2625
};

0 commit comments

Comments
 (0)