@gradientedge/commercetools-utils 5.9.0 → 5.10.0

package/dist/cjs/utils/retry-on-conflict.d.ts

@@ -0,0 +1,99 @@
+export interface RetryOnConflictParams<T = any> {
+    /**
+     * Any function that returns a promise
+     *
+     * This function is expected to be able to throw a {@link CommercetoolsError}
+     * with a status code of 409. These errors should **not** be swallowed by the
+     * code in this function.
+     */
+    executeFn: (attemptNo: number) => Promise<T>;
+    /**
+     * The number of milliseconds to wait before retrying a failed request.
+     * This will be increased exponentially {@link CommercetoolsApi.calculateDelay}.
+     * Defaults to 100.
+     */
+    delayMs?: number;
+    /**
+     * The maximum number of times that we'll call the `executeFn` function
+     * before returning the error caught from the last failure.
+     * Defaults to 3.
+     */
+    maxRetries?: number;
+    /**
+     * If enabled, adds a random element to the exponential increase
+     * in retry time. See the following url for more details:
+     * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
+     * We utilise the 'full' jitter + plus an additional decaying variance.
+     */
+    jitter?: boolean;
+}
+/**
+ * Re-executes a function if a 409 response code is returned from commercetools
+ *
+ * When you make a request to update a resource in commercetools, you may receive a
+ * 409 response code if the resource has been updated since you last fetched it. This
+ * function will re-execute the function passed in to {@link RetryOnConflictParams.executeFn}
+ * in that scenario.
+ *
+ * You should retrieve the latest version of the resource before re-executing the function
+ * that caused the 409 response in the first place.
+ *
+ * For example, in order to update a product, you would first need to fetch the latest
+ * product (or product projection) and then post the update actions:
+ *
+ * ```typescript
+ * import { retryOnConflict, CommercetoolsApi, Region } from '@gradientedge/commercetools-utils'
+ *
+ * const api = new CommercetoolsApi({
+ *   projectKey: 'your-project-key',
+ *   region: Region.EUROPE_GCP,
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   clientScopes: ['manage_products'],
+ * })
+ *
+ * const updatedProduct = await retryOnConflict({
+ *   executeFn: async () => {
+ *     // Get the latest product projection
+ *     const productProjection = await api.getProductProjectionByKey({key: 'dummy-product-id'})
+ *
+ *     // Attempt to update the product. If this fails with a 409, the function
+ *     // will be retried, otherwise the `Product` object will be returned.
+ *     return await api.updateProductById({
+ *       id: productProjection.id,
+ *       data: {
+ *         version: productProjection.version,
+ *         actions: [
+ *           {
+ *             action: 'setMetaTitle',
+ *             metaTitle: {
+ *               en: 'New meta title',
+ *             },
+ *           },
+ *         ],
+ *       },
+ *     })
+ *   },
+ *   // The `executeFn` function will be called a maximum of 3 times (first attempt + 2 retries)
+ *   maxRetries: 2,
+ *   // The delay between for the first retry will be 20ms, increasing exponentially
+ *   delayMs: 20,
+ * })
+ *
+ * console.log(updatedProduct)
+ *
+ * ```
+ *
+ * By default, the function passed in to {@link RetryOnConflictParams.executeFn} will be
+ * retried 3 times, though this can be altered by passing in a different value for the
+ * {@link RetryOnConflictParams.maxRetries} parameter.
+ *
+ * There is by default a 100ms delay after the first unsuccessful attempt, which is then
+ * increases exponentially for each subsequent attempt. This delay can be altered by passing
+ * in a different value for the {@link RetryOnConflictParams.delayMs} parameter.
+ *
+ * If the {@link RetryOnConflictParams.jitter} parameter is set to `true`, then a random
+ * element is added to the exponential increase in retry time.
+ */
+export declare function retryOnConflict<T = any>(options: RetryOnConflictParams): Promise<T>;
+//# sourceMappingURL=retry-on-conflict.d.ts.map

package/dist/cjs/utils/retry-on-conflict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-on-conflict.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/retry-on-conflict.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,GAAG;IAC5C;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IAC5C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,GAAG,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,CAAC,CAsBzF"}

package/dist/cjs/utils/retry-on-conflict.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.retryOnConflict = void 0;
+const calculate_delay_js_1 = require("./calculate-delay.js");
+const status_1 = require("@tshttp/status");
+/**
+ * Default maximum number of retries
+ *
+ * See the {@link calculateDelay} function for more details
+ */
+const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Default delay (in milliseconds) before a retry attempt is made
+ *
+ * See the {@link calculateDelay} function for more details
+ */
+const DEFAULT_DELAY_MS = 100;
+/**
+ * Re-executes a function if a 409 response code is returned from commercetools
+ *
+ * When you make a request to update a resource in commercetools, you may receive a
+ * 409 response code if the resource has been updated since you last fetched it. This
+ * function will re-execute the function passed in to {@link RetryOnConflictParams.executeFn}
+ * in that scenario.
+ *
+ * You should retrieve the latest version of the resource before re-executing the function
+ * that caused the 409 response in the first place.
+ *
+ * For example, in order to update a product, you would first need to fetch the latest
+ * product (or product projection) and then post the update actions:
+ *
+ * ```typescript
+ * import { retryOnConflict, CommercetoolsApi, Region } from '@gradientedge/commercetools-utils'
+ *
+ * const api = new CommercetoolsApi({
+ *   projectKey: 'your-project-key',
+ *   region: Region.EUROPE_GCP,
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   clientScopes: ['manage_products'],
+ * })
+ *
+ * const updatedProduct = await retryOnConflict({
+ *   executeFn: async () => {
+ *     // Get the latest product projection
+ *     const productProjection = await api.getProductProjectionByKey({key: 'dummy-product-id'})
+ *
+ *     // Attempt to update the product. If this fails with a 409, the function
+ *     // will be retried, otherwise the `Product` object will be returned.
+ *     return await api.updateProductById({
+ *       id: productProjection.id,
+ *       data: {
+ *         version: productProjection.version,
+ *         actions: [
+ *           {
+ *             action: 'setMetaTitle',
+ *             metaTitle: {
+ *               en: 'New meta title',
+ *             },
+ *           },
+ *         ],
+ *       },
+ *     })
+ *   },
+ *   // The `executeFn` function will be called a maximum of 3 times (first attempt + 2 retries)
+ *   maxRetries: 2,
+ *   // The delay between for the first retry will be 20ms, increasing exponentially
+ *   delayMs: 20,
+ * })
+ *
+ * console.log(updatedProduct)
+ *
+ * ```
+ *
+ * By default, the function passed in to {@link RetryOnConflictParams.executeFn} will be
+ * retried 3 times, though this can be altered by passing in a different value for the
+ * {@link RetryOnConflictParams.maxRetries} parameter.
+ *
+ * There is by default a 100ms delay after the first unsuccessful attempt, which is then
+ * increases exponentially for each subsequent attempt. This delay can be altered by passing
+ * in a different value for the {@link RetryOnConflictParams.delayMs} parameter.
+ *
+ * If the {@link RetryOnConflictParams.jitter} parameter is set to `true`, then a random
+ * element is added to the exponential increase in retry time.
+ */
+async function retryOnConflict(options) {
+    const maxAttempts = (options?.maxRetries || DEFAULT_MAX_RETRIES) + 1;
+    const delayMs = options?.delayMs || DEFAULT_DELAY_MS;
+    const jitter = !!options?.jitter;
+    let result;
+    for (let attemptCount = 1; attemptCount <= maxAttempts; attemptCount++) {
+        if (attemptCount > 1) {
+            const delay = (0, calculate_delay_js_1.calculateDelay)(attemptCount - 1, { delayMs, jitter });
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+        try {
+            return await options.executeFn(attemptCount);
+        }
+        catch (e) {
+            if (!e.isCommercetoolsError || e.status !== status_1.Status.Conflict || attemptCount === maxAttempts) {
+                throw e;
+            }
+        }
+    }
+    // eslint-disable-next-line
+    return result;
+}
+exports.retryOnConflict = retryOnConflict;
+//# sourceMappingURL=retry-on-conflict.js.map

package/dist/cjs/utils/retry-on-conflict.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-on-conflict.js","sourceRoot":"","sources":["../../../src/lib/utils/retry-on-conflict.ts"],"names":[],"mappings":";;;AAAA,6DAAqD;AACrD,2CAAuC;AAEvC;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,CAAC,CAAA;AAE7B;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAkC5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACI,KAAK,UAAU,eAAe,CAAU,OAA8B;IAC3E,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,UAAU,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAA;IACpE,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,gBAAgB,CAAA;IACpD,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,CAAA;IAChC,IAAI,MAAS,CAAA;IAEb,KAAK,IAAI,YAAY,GAAG,CAAC,EAAE,YAAY,IAAI,WAAW,EAAE,YAAY,EAAE,EAAE,CAAC;QACvE,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,MAAM,KAAK,GAAG,IAAA,mCAAc,EAAC,YAAY,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;YACnE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAA;QAC5D,CAAC;QACD,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAA;QAC9C,CAAC;QAAC,OAAO,CAAM,EAAE,CAAC;YAChB,IAAI,CAAC,CAAC,CAAC,oBAAoB,IAAI,CAAC,CAAC,MAAM,KAAK,eAAM,CAAC,QAAQ,IAAI,YAAY,KAAK,WAAW,EAAE,CAAC;gBAC5F,MAAM,CAAC,CAAA;YACT,CAAC;QACH,CAAC;IACH,CAAC;IAED,2BAA2B;IAC3B,OAAO,MAAO,CAAA;AAChB,CAAC;AAtBD,0CAsBC"}

package/dist/cjs/utils/useragent.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Build a string suitable for sending as the `User-Agent` HTTP header.
+ * This should contain information that allows commercetools to easily
+ * identify the source of the request. The `systemIdentifier` comes from
+ * {@see CommercetoolsApiConfig.systemIdentifier} and should be a string
+ * that uniquely identifies the application where this package is being
+ * used.
+ */
+export declare function buildUserAgent(systemIdentifier?: string): string;
+//# sourceMappingURL=useragent.d.ts.map

package/dist/cjs/utils/useragent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useragent.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/useragent.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAMhE"}

package/dist/cjs/utils/useragent.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUserAgent = void 0;
+const constants_js_1 = require("../constants.js");
+/**
+ * Build a string suitable for sending as the `User-Agent` HTTP header.
+ * This should contain information that allows commercetools to easily
+ * identify the source of the request. The `systemIdentifier` comes from
+ * {@see CommercetoolsApiConfig.systemIdentifier} and should be a string
+ * that uniquely identifies the application where this package is being
+ * used.
+ */
+function buildUserAgent(systemIdentifier) {
+    let userAgent = constants_js_1.USER_AGENT_PREFIX;
+    if (systemIdentifier) {
+        userAgent = `${userAgent} (${systemIdentifier})`;
+    }
+    return userAgent;
+}
+exports.buildUserAgent = buildUserAgent;
+//# sourceMappingURL=useragent.js.map

package/dist/cjs/utils/useragent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useragent.js","sourceRoot":"","sources":["../../../src/lib/utils/useragent.ts"],"names":[],"mappings":";;;AAAA,kDAAmD;AAEnD;;;;;;;GAOG;AACH,SAAgB,cAAc,CAAC,gBAAyB;IACtD,IAAI,SAAS,GAAG,gCAAiB,CAAA;IACjC,IAAI,gBAAgB,EAAE,CAAC;QACrB,SAAS,GAAG,GAAG,SAAS,KAAK,gBAAgB,GAAG,CAAA;IAClD,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAND,wCAMC"}