refactor: rename parameterStructures to parameterStructure

.changeset/spicy-rivers-act.md

@@ -0,0 +1,5 @@
+---
+"async-call-rpc": minor
+---
+
+rename parameterStructures to parameterStructure

__tests__/options.ts

@@ -119,3 +119,14 @@ it(
         ).toThrowErrorMatchingInlineSnapshot(`[TypeError: Please remove key.]`)
     }),
 )
+
+it(
+    'should error if both parameterStructure and parameterStructures are provided',
+    withSnapshotDefault('async-call-key-name', async ({ init }) => {
+        expect(() =>
+            init({
+                options: { parameterStructure: 'by-name', parameterStructures: 'by-name' },
+            }),
+        ).toThrowErrorMatchingInlineSnapshot(`[TypeError: Please remove key.]`)
+    }),
+)

api/base.api.md

@@ -28,6 +28,8 @@ export interface AsyncCallOptions<EncodedRequest = unknown, EncodedResponse = un
     logger?: ConsoleInterface;
     mapError?: ErrorMapFunction<unknown>;
     name?: string;
+    parameterStructure?: 'by-position' | 'by-name';
+    // @deprecated
     parameterStructures?: 'by-position' | 'by-name';
     preferLocalImplementation?: boolean;
     // @deprecated

api/full.api.md

@@ -28,6 +28,8 @@ export interface AsyncCallOptions<EncodedRequest = unknown, EncodedResponse = un
     logger?: ConsoleInterface;
     mapError?: ErrorMapFunction<unknown>;
     name?: string;
+    parameterStructure?: 'by-position' | 'by-name';
+    // @deprecated
     parameterStructures?: 'by-position' | 'by-name';
     preferLocalImplementation?: boolean;
     // @deprecated

docs/async-call-rpc.asynccalloptions.md

@@ -23,6 +23,7 @@ export interface AsyncCallOptions<EncodedRequest = unknown, EncodedResponse = un
 |  [logger?](./async-call-rpc.asynccalloptions.logger.md) |  | [ConsoleInterface](./async-call-rpc.consoleinterface.md) | _(Optional)_ Provide the logger |
 |  [mapError?](./async-call-rpc.asynccalloptions.maperror.md) |  | [ErrorMapFunction](./async-call-rpc.errormapfunction.md)<!-- -->&lt;unknown&gt; | _(Optional)_ Change the [ErrorResponseDetail](./async-call-rpc.errorresponsedetail.md)<!-- -->. |
 |  [name?](./async-call-rpc.asynccalloptions.name.md) |  | string | _(Optional)_ Name used when pretty log is enabled. |
+|  [parameterStructure?](./async-call-rpc.asynccalloptions.parameterstructure.md) |  | 'by-position' \| 'by-name' | _(Optional)_ Choose flavor of parameter structures defined in the spec |
 |  [parameterStructures?](./async-call-rpc.asynccalloptions.parameterstructures.md) |  | 'by-position' \| 'by-name' | _(Optional)_ Choose flavor of parameter structures defined in the spec |
 |  [preferLocalImplementation?](./async-call-rpc.asynccalloptions.preferlocalimplementation.md) |  | boolean | _(Optional)_ Prefer local implementation than remote. |
 |  [serializer?](./async-call-rpc.asynccalloptions.serializer.md) |  | [Serialization](./async-call-rpc.serialization.md) | _(Optional)_ Serializer of the requests and responses. |

docs/async-call-rpc.asynccalloptions.parameterstructure.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [async-call-rpc](./async-call-rpc.md) &gt; [AsyncCallOptions](./async-call-rpc.asynccalloptions.md) &gt; [parameterStructure](./async-call-rpc.asynccalloptions.parameterstructure.md)
+
+## AsyncCallOptions.parameterStructure property
+
+Choose flavor of parameter structures defined in the spec
+
+**Signature:**
+
+```typescript
+parameterStructure?: 'by-position' | 'by-name';
+```
+
+## Remarks
+
+When using `by-name`<!-- -->, only first parameter is sent to the remote and it must be an object.
+

docs/async-call-rpc.asynccalloptions.parameterstructures.md

@@ -4,6 +4,11 @@
 
 ## AsyncCallOptions.parameterStructures property
 
+> Warning: This API is now obsolete.
+> 
+> renamed to "parameterStructure"
+> 
+
 Choose flavor of parameter structures defined in the spec
 
 **Signature:**

src/Async-Call.ts

@@ -116,7 +116,8 @@ export function AsyncCall<OtherSideImplementedFunctions = {}>(
         name,
         strict = true,
         log = true,
-        parameterStructures = 'by-position',
+        parameterStructures: deprecatedParameterStructures,
+        parameterStructure,
         preferLocalImplementation = false,
         idGenerator = generateRandomID,
         mapError,
@@ -128,6 +129,8 @@ export function AsyncCall<OtherSideImplementedFunctions = {}>(
     // Note: we're not shorten this error message because it will be removed in the next major version.
     if (serializer && encoder) throw new TypeError('Please remove serializer.')
     if (name && deprecatedName) throw new TypeError('Please remove key.')
+    if (deprecatedParameterStructures && parameterStructure) throw new TypeError('Please remove parameterStructure.')
+    const paramStyle = deprecatedParameterStructures || parameterStructure || 'by-position'
     const logKey = name || deprecatedName || 'rpc'
 
     const {
@@ -190,8 +193,7 @@ export function AsyncCall<OtherSideImplementedFunctions = {}>(
             const { params, method, id: req_id, remoteStack } = data
             // ? We're mapping any method starts with 'rpc.' to a Symbol.for
             const key = (method.startsWith('rpc.') ? Symbol.for(method) : method) as keyof object
-            const executor: unknown =
-                resolvedThisSideImplementationValue && (resolvedThisSideImplementationValue as any)[key]
+            const executor: unknown = resolvedThisSideImplementationValue && resolvedThisSideImplementationValue[key]
             if (!isFunction(executor)) {
                 if (!banMethodNotFound) {
                     if (log_localError) console_debug('Missing method', key, data)
@@ -307,8 +309,11 @@ export function AsyncCall<OtherSideImplementedFunctions = {}>(
             }
         } catch (e) {
             if (log_localError) console_error(e, data, result)
-            // TODO: should check before access e.stack
-            return ErrorResponseParseError(e, mapError || defaultErrorMapper(e && (e as any).stack))
+            let stack: string | undefined
+            try {
+                stack = '' + (e as any).stack
+            } catch {}
+            return ErrorResponseParseError(e, mapError || defaultErrorMapper(stack))
         }
     }
     const rawMessageSender = async (res: undefined | Response | (Response | undefined)[]) => {
@@ -382,7 +387,7 @@ export function AsyncCall<OtherSideImplementedFunctions = {}>(
             }
             const id = idGenerator()
             stack = removeStackHeader(stack)
-            const param = parameterStructures === 'by-name' && args.length === 1 && isObject(args[0]) ? args[0] : args
+            const param = paramStyle === 'by-name' && args.length === 1 && isObject(args[0]) ? args[0] : args
             const request = makeRequest(
                 notify ? undefined : id,
                 method as string,

src/types.ts

@@ -114,6 +114,17 @@ export interface AsyncCallStrictOptions {
      * @defaultValue true
      */
     unknownMessage?: boolean
+    // TODO: implement this if there is needed
+    /**
+     * Controls if redundant arguments on the client triggers a warning or error.
+     * @see {@link https://www.jsonrpc.org/specification#parameter_structures}
+     * @remarks
+     * If this option is set and parameterStructure is "by-name",
+     * and the client calls with more than 1 argument, it will trigger a warning or error.
+     *
+     * @defaultValue false
+     */
+    // redundantArguments?: false | 'error' | 'warning'
 }
 /**
  * Strict options
@@ -133,8 +144,6 @@ export interface AsyncCallOptions<EncodedRequest = unknown, EncodedResponse = un
      * Name used when pretty log is enabled.
      * @defaultValue `rpc`
      * @deprecated Renamed to "name".
-     * @privateRemarks
-     * TODO: rename this option to name.
      */
     key?: string
     /**
@@ -204,6 +213,16 @@ export interface AsyncCallOptions<EncodedRequest = unknown, EncodedResponse = un
      * @defaultValue true
      */
     strict?: AsyncCallStrictJSONRPC | boolean
+    /**
+     * Choose flavor of parameter structures defined in the spec
+     * @see {@link https://www.jsonrpc.org/specification#parameter_structures}
+     * @remarks
+     * When using `by-name`, only first parameter is sent to the remote and it must be an object.
+     *
+     * @deprecated renamed to "parameterStructure"
+     * @defaultValue "by-position"
+     */
+    parameterStructures?: 'by-position' | 'by-name'
     /**
      * Choose flavor of parameter structures defined in the spec
      * @see {@link https://www.jsonrpc.org/specification#parameter_structures}
@@ -213,10 +232,9 @@ export interface AsyncCallOptions<EncodedRequest = unknown, EncodedResponse = un
      * @privateRemarks
      * TODO: review the edge cases when using "by-name".
      * TODO: throw an error/print a warning when using "by-name" and the first parameter is not an object/more than 1 parameter is given.
-     * TODO: rename to parameterStructure
      * @defaultValue "by-position"
      */
-    parameterStructures?: 'by-position' | 'by-name'
+    parameterStructure?: 'by-position' | 'by-name'
     /**
      * Prefer local implementation than remote.
      * @remarks
@@ -227,8 +245,6 @@ export interface AsyncCallOptions<EncodedRequest = unknown, EncodedResponse = un
     /**
      * The ID generator of each JSON RPC request
      * @defaultValue () =\> Math.random().toString(36).slice(2)
-     * @privateRemarks
-     * TODO: rename to generateID
      */
     idGenerator?(): string | number
     /**