updated beforeSend return format to allow modifying the request url

pocketbase · Feb 27, 2023 · 2133b69 · 2133b69
1 parent 8457ade
commit 2133b69
Show file tree

Hide file tree

Showing 18 changed files with 123 additions and 76 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,22 @@
+## 0.12.0
+
+- Changed the return type of `pb.beforeSend` hook to allow modifying the request url ([#1930](https://github.com/pocketbase/pocketbase/discussions/1930)).
+  ```js
+  // old
+  pb.beforeSend = function (url, options) {
+    ...
+    return options;
+  }
+
+  // new
+  pb.beforeSend = function (url, options) {
+    ...
+    return { url, options };
+  }
+  ```
+  The old return format is soft-deprecated and will still work, but you'll get a `console.warn` message to replace it.
+
+
 ## 0.11.1
 
 - Exported the services class definitions to allow being used as argument types ([#153](https://github.com/pocketbase/js-sdk/issues/153)).

diff --git a/README.md b/README.md
@@ -287,14 +287,14 @@ To accomplish this, the SDK provides 2 function hooks:
     ```js
     const pb = new PocketBase('http://127.0.0.1:8090');
 
-    pb.beforeSend = function (url, reqConfig) {
-        // For list of the possible reqConfig properties check
+    pb.beforeSend = function (url, options) {
+        // For list of the possible request options properties check
         // https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
-        reqConfig.headers = Object.assign({}, reqConfig.headers, {
+        options.headers = Object.assign({}, options.headers, {
             'X-Custom-Header': 'example',
         });
 
-        return reqConfig;
+        return { url, options };
     };
     ```
 

diff --git a/dist/pocketbase.cjs.d.ts b/dist/pocketbase.cjs.d.ts
@@ -774,27 +774,31 @@ declare class Client {
     baseUrl: string;
     /**
      * Hook that get triggered right before sending the fetch request,
-     * allowing you to inspect/modify the request config.
-     *
-     * Returns the new modified config that will be used to send the request.
+     * allowing you to inspect and modify the url and request options.
      *
      * For list of the possible options check https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
      *
+     * You can return a non-empty result object `{ url, options }` to replace the url and request options entirely.
+     *
      * Example:
      * ```js
-     * client.beforeSend = function (url, reqConfig) {
-     *     reqConfig.headers = Object.assign({}, reqConfig.headers, {
+     * client.beforeSend = function (url, options) {
+     *     options.headers = Object.assign({}, options.headers, {
      *         'X-Custom-Header': 'example',
      *     });
      *
-     *     return reqConfig;
+     *     return { url, options }
      * };
      * ```
      */
-    beforeSend?: (url: string, reqConfig: {
+    beforeSend?: (url: string, options: {
         [key: string]: any;
     }) => {
         [key: string]: any;
+        url?: string;
+        options?: {
+            [key: string]: any;
+        };
     };
     /**
      * Hook that get triggered after successfully sending the fetch request,
@@ -895,7 +899,7 @@ declare class Client {
     /**
      * Sends an api http request.
      */
-    send(path: string, reqConfig: {
+    send(path: string, reqOptions: {
         [key: string]: any;
     }): Promise<any>;
     /**

diff --git a/dist/pocketbase.cjs.js b/dist/pocketbase.cjs.js
diff --git a/dist/pocketbase.cjs.js.map b/dist/pocketbase.cjs.js.map
diff --git a/dist/pocketbase.es.d.mts b/dist/pocketbase.es.d.mts
@@ -774,27 +774,31 @@ declare class Client {
     baseUrl: string;
     /**
      * Hook that get triggered right before sending the fetch request,
-     * allowing you to inspect/modify the request config.
-     *
-     * Returns the new modified config that will be used to send the request.
+     * allowing you to inspect and modify the url and request options.
      *
      * For list of the possible options check https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
      *
+     * You can return a non-empty result object `{ url, options }` to replace the url and request options entirely.
+     *
      * Example:
      * ```js
-     * client.beforeSend = function (url, reqConfig) {
-     *     reqConfig.headers = Object.assign({}, reqConfig.headers, {
+     * client.beforeSend = function (url, options) {
+     *     options.headers = Object.assign({}, options.headers, {
      *         'X-Custom-Header': 'example',
      *     });
      *
-     *     return reqConfig;
+     *     return { url, options }
      * };
      * ```
      */
-    beforeSend?: (url: string, reqConfig: {
+    beforeSend?: (url: string, options: {
         [key: string]: any;
     }) => {
-        [key: string]: any;
+        [key: string]: any; // for backward compatibility
+        url?: string;
+        options?: {
+            [key: string]: any;
+        };
     };
     /**
      * Hook that get triggered after successfully sending the fetch request,
@@ -877,7 +881,7 @@ declare class Client {
     /**
      * Sends an api http request.
      */
-    send(path: string, reqConfig: {
+    send(path: string, reqOptions: {
         [key: string]: any;
     }): Promise<any>;
     /**

diff --git a/dist/pocketbase.es.js b/dist/pocketbase.es.js
diff --git a/dist/pocketbase.es.js.map b/dist/pocketbase.es.js.map
diff --git a/dist/pocketbase.es.mjs b/dist/pocketbase.es.mjs
diff --git a/dist/pocketbase.es.mjs.map b/dist/pocketbase.es.mjs.map
diff --git a/dist/pocketbase.iife.d.ts b/dist/pocketbase.iife.d.ts
@@ -774,27 +774,31 @@ declare class Client {
     baseUrl: string;
     /**
      * Hook that get triggered right before sending the fetch request,
-     * allowing you to inspect/modify the request config.
-     *
-     * Returns the new modified config that will be used to send the request.
+     * allowing you to inspect and modify the url and request options.
      *
      * For list of the possible options check https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
      *
+     * You can return a non-empty result object `{ url, options }` to replace the url and request options entirely.
+     *
      * Example:
      * ```js
-     * client.beforeSend = function (url, reqConfig) {
-     *     reqConfig.headers = Object.assign({}, reqConfig.headers, {
+     * client.beforeSend = function (url, options) {
+     *     options.headers = Object.assign({}, options.headers, {
      *         'X-Custom-Header': 'example',
      *     });
      *
-     *     return reqConfig;
+     *     return { url, options }
      * };
      * ```
      */
-    beforeSend?: (url: string, reqConfig: {
+    beforeSend?: (url: string, options: {
         [key: string]: any;
     }) => {
         [key: string]: any;
+        url?: string;
+        options?: {
+            [key: string]: any;
+        };
     };
     /**
      * Hook that get triggered after successfully sending the fetch request,
@@ -895,7 +899,7 @@ declare class Client {
     /**
      * Sends an api http request.
      */
-    send(path: string, reqConfig: {
+    send(path: string, reqOptions: {
         [key: string]: any;
     }): Promise<any>;
     /**

diff --git a/dist/pocketbase.iife.js b/dist/pocketbase.iife.js
diff --git a/dist/pocketbase.iife.js.map b/dist/pocketbase.iife.js.map
diff --git a/dist/pocketbase.umd.d.ts b/dist/pocketbase.umd.d.ts
@@ -774,27 +774,31 @@ declare class Client {
     baseUrl: string;
     /**
      * Hook that get triggered right before sending the fetch request,
-     * allowing you to inspect/modify the request config.
-     *
-     * Returns the new modified config that will be used to send the request.
+     * allowing you to inspect and modify the url and request options.
      *
      * For list of the possible options check https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
      *
+     * You can return a non-empty result object `{ url, options }` to replace the url and request options entirely.
+     *
      * Example:
      * ```js
-     * client.beforeSend = function (url, reqConfig) {
-     *     reqConfig.headers = Object.assign({}, reqConfig.headers, {
+     * client.beforeSend = function (url, options) {
+     *     options.headers = Object.assign({}, options.headers, {
      *         'X-Custom-Header': 'example',
      *     });
      *
-     *     return reqConfig;
+     *     return { url, options }
      * };
      * ```
      */
-    beforeSend?: (url: string, reqConfig: {
+    beforeSend?: (url: string, options: {
         [key: string]: any;
     }) => {
         [key: string]: any;
+        url?: string;
+        options?: {
+            [key: string]: any;
+        };
     };
     /**
      * Hook that get triggered after successfully sending the fetch request,
@@ -895,7 +899,7 @@ declare class Client {
     /**
      * Sends an api http request.
      */
-    send(path: string, reqConfig: {
+    send(path: string, reqOptions: {
         [key: string]: any;
     }): Promise<any>;
     /**

diff --git a/dist/pocketbase.umd.js b/dist/pocketbase.umd.js
diff --git a/dist/pocketbase.umd.js.map b/dist/pocketbase.umd.js.map
diff --git a/package.json b/package.json
@@ -1,5 +1,5 @@
 {
-    "version": "0.11.1",
+    "version": "0.12.0",
     "name": "pocketbase",
     "description": "PocketBase JavaScript SDK",
     "author": "Gani Georgiev",

diff --git a/src/Client.ts b/src/Client.ts
@@ -22,24 +22,28 @@ export default class Client {
 
     /**
      * Hook that get triggered right before sending the fetch request,
-     * allowing you to inspect/modify the request config.
-     *
-     * Returns the new modified config that will be used to send the request.
+     * allowing you to inspect and modify the url and request options.
      *
      * For list of the possible options check https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
      *
+     * You can return a non-empty result object `{ url, options }` to replace the url and request options entirely.
+     *
      * Example:
      * ```js
-     * client.beforeSend = function (url, reqConfig) {
-     *     reqConfig.headers = Object.assign({}, reqConfig.headers, {
+     * client.beforeSend = function (url, options) {
+     *     options.headers = Object.assign({}, options.headers, {
      *         'X-Custom-Header': 'example',
      *     });
      *
-     *     return reqConfig;
+     *     return { url, options }
      * };
      * ```
      */
-    beforeSend?: (url: string, reqConfig: { [key: string]: any }) => { [key: string]: any };
+    beforeSend?: (url: string, options: { [key: string]: any }) => {
+        [key: string]: any, // for backward compatibility
+        url?: string,
+        options?: {[key: string]: any}
+    };
 
     /**
      * Hook that get triggered after successfully sending the fetch request,
@@ -178,28 +182,28 @@ export default class Client {
     /**
      * Sends an api http request.
      */
-    async send(path: string, reqConfig: { [key: string]: any }): Promise<any> {
-        let config = Object.assign({ method: 'GET' } as { [key: string]: any }, reqConfig);
+    async send(path: string, reqOptions: { [key: string]: any }): Promise<any> {
+        let options = Object.assign({ method: 'GET' } as { [key: string]: any }, reqOptions);
 
         // serialize the body if needed and set the correct content type
         // note1: for FormData body the Content-Type header should be skipped
         // note2: we are checking the constructor name because FormData is not available natively in node
-        if (config.body && config.body.constructor.name !== 'FormData') {
-            if (typeof config.body !== 'string') {
-                config.body = JSON.stringify(config.body);
+        if (options.body && options.body.constructor.name !== 'FormData') {
+            if (typeof options.body !== 'string') {
+                options.body = JSON.stringify(options.body);
             }
 
             // add the json header (if not already)
-            if (typeof config?.headers?.['Content-Type'] === 'undefined') {
-                config.headers = Object.assign({}, config.headers, {
+            if (typeof options?.headers?.['Content-Type'] === 'undefined') {
+                options.headers = Object.assign({}, options.headers, {
                     'Content-Type': 'application/json',
                 });
             }
         }
 
         // add Accept-Language header (if not already)
-        if (typeof config?.headers?.['Accept-Language'] === 'undefined') {
-            config.headers = Object.assign({}, config.headers, {
+        if (typeof options?.headers?.['Accept-Language'] === 'undefined') {
+            options.headers = Object.assign({}, options.headers, {
                 'Accept-Language': this.lang,
             });
         }
@@ -209,46 +213,54 @@ export default class Client {
             // has stored token
             this.authStore?.token &&
             // auth header is not explicitly set
-            (typeof config?.headers?.Authorization === 'undefined')
+            (typeof options?.headers?.Authorization === 'undefined')
         ) {
-            config.headers = Object.assign({}, config.headers, {
+            options.headers = Object.assign({}, options.headers, {
                 'Authorization': this.authStore.token,
             });
         }
 
         // handle auto cancelation for duplicated pending request
-        if (this.enableAutoCancellation && config.params?.$autoCancel !== false) {
-            const cancelKey = config.params?.$cancelKey || ((config.method || 'GET') + path);
+        if (this.enableAutoCancellation && options.params?.$autoCancel !== false) {
+            const cancelKey = options.params?.$cancelKey || ((options.method || 'GET') + path);
 
             // cancel previous pending requests
             this.cancelRequest(cancelKey);
 
             const controller = new AbortController();
             this.cancelControllers[cancelKey] = controller;
-            config.signal = controller.signal;
+            options.signal = controller.signal;
         }
         // remove the special cancellation params from the other valid query params
-        delete config.params?.$autoCancel;
-        delete config.params?.$cancelKey;
+        delete options.params?.$autoCancel;
+        delete options.params?.$cancelKey;
 
         // build url + path
         let url = this.buildUrl(path);
 
         // serialize the query parameters
-        if (typeof config.params !== 'undefined') {
-            const query = this.serializeQueryParams(config.params)
+        if (typeof options.params !== 'undefined') {
+            const query = this.serializeQueryParams(options.params)
             if (query) {
                 url += (url.includes('?') ? '&' : '?') + query;
             }
-            delete config.params;
+            delete options.params;
         }
 
         if (this.beforeSend) {
-            config = Object.assign({}, this.beforeSend(url, config));
+            const result = Object.assign({}, this.beforeSend(url, options));
+            if (typeof result.url !== "undefined" || typeof result.options !== "undefined") {
+                url = result.url || url;
+                options = result.options || options;
+            } else if (Object.keys(result).length) {
+                // legacy behavior
+                options = result;
+                console?.warn && console.warn("Deprecated format of beforeSend return: please use `return { url, options }`, instead of `return options`.");
+            }
         }
 
         // send the request
-        return fetch(url, config)
+        return fetch(url, options)
             .then(async (response) => {
                 let data : any = {};