@webex/common 3.8.1 → 3.9.0

package/README.md

@@ -1,14 +1,6 @@
 # @webex/common
 
-[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
-
-> Common functions for the Cisco Webex JS SDK.
-
-- [Install](#install)
-- [Usage](#usage)
-- [Contribute](#contribute)
-- [Maintainers](#maintainers)
-- [License](#license)
+Utility functions and helpers for the Cisco Webex JS SDK.
 
 ## Install
 
@@ -16,18 +8,119 @@
 npm install --save @webex/common
 ```
 
+## What it Does
+
+This package provides essential utility functions used throughout the Webex SDK. While many exports are designed for internal SDK use, several utilities can be useful in general applications.
+
 ## Usage
 
-Since this package exports common functions for the Cisco Webex JS SDK, many of its exports are applicable only within that SDK.
+### Capped Debounce
+
+A debounce function that executes after a time delay OR after a maximum number of calls.
+
+```js
+import {cappedDebounce} from '@webex/common';
+
+const debouncedFn = cappedDebounce(
+  () => console.log('Executed!'),
+  1000, // Wait 1 second
+  {
+    maxWait: 5000,  // Execute after 5 seconds maximum
+    maxCalls: 10    // Execute after 10 calls maximum
+  }
+);
+
+// Will execute after 1 second of inactivity, 10 calls, or 5 seconds total
+debouncedFn();
+```
+
+### Defer
+
+Creates a deferred promise with exposed resolve/reject methods.
+
+```js
+import {Defer} from '@webex/common';
+
+const deferred = new Defer();
+
+// Resolve later
+setTimeout(() => {
+  deferred.resolve('Success!');
+}, 1000);
+
+deferred.promise.then(result => {
+  console.log(result); // 'Success!'
+});
+```
+
+### One Flight
+
+Decorator that ensures a method only runs one instance at a time, preventing duplicate calls.
+
+```js
+import {oneFlight} from '@webex/common';
+
+class MyClass {
+  @oneFlight
+  async fetchData() {
+    // This will only run one instance at a time
+    // Subsequent calls while running will return the same promise
+    return await fetch('/api/data');
+  }
+}
+```
+
+### Exception
+
+Utility for creating custom error types.
+
+```js
+import {Exception} from '@webex/common';
+
+const MyError = Exception.extend('MyError');
+throw new MyError('Something went wrong');
+```
+
+### Tap
+
+Utility for debugging promise chains without affecting the flow.
+
+```js
+import {tap} from '@webex/common';
+
+fetch('/api/data')
+  .then(tap(response => console.log('Response received:', response)))
+  .then(response => response.json())
+  .then(tap(data => console.log('Data parsed:', data)));
+```
+
+### Deprecated
+
+Decorator for marking methods as deprecated.
+
+```js
+import {deprecated} from '@webex/common';
+
+class MyClass {
+  @deprecated('Use newMethod() instead')
+  oldMethod() {
+    // Will log deprecation warning when called
+  }
+}
+```
+
+## Available Utilities
+
+- **cappedDebounce** - Debounce with call count limit
+- **defer** - Deferred promise creation
+- **deprecated** - Deprecation warnings
+- **exception** - Custom error types
+- **oneFlight** - Prevent duplicate method calls
+- **tap** - Debug promise chains
 
-General-use exports include
+## SDK Integration
 
-- [capped-debounce](./src/capped-debounce.js)
-- [defer](./src/defer.js)
-- [deprecated](./src/deprecated.js)
-- [exception](./src/exception.js)
-- [one-flight](./src/one-flight.js)
-- [tap](./src/tap.js)
+These utilities are primarily designed for use within the Webex SDK ecosystem but can be useful in any JavaScript application requiring these common patterns.
 
 ## Maintainers
 
@@ -39,4 +132,4 @@ Pull requests welcome. Please see [CONTRIBUTING.md](https://github.com/webex/web
 
 ## License
 
-© 2016-2020 Cisco and/or its affiliates. All Rights Reserved.
+© 2016-2025 Cisco and/or its affiliates. All Rights Reserved.

package/package.json

@@ -29,10 +29,10 @@
     "@webex/eslint-config-legacy": "0.0.0",
     "@webex/jest-config-legacy": "0.0.0",
     "@webex/legacy-tools": "0.0.0",
-    "@webex/test-helper-chai": "3.8.1",
-    "@webex/test-helper-mocha": "3.8.1",
-    "@webex/test-helper-mock-webex": "3.8.1",
-    "@webex/test-helper-test-users": "3.8.1",
+    "@webex/test-helper-chai": "3.9.0",
+    "@webex/test-helper-mocha": "3.9.0",
+    "@webex/test-helper-mock-webex": "3.9.0",
+    "@webex/test-helper-test-users": "3.9.0",
     "ampersand-state": "^5.0.3",
     "eslint": "^8.24.0",
     "prettier": "^2.7.1",
@@ -55,5 +55,5 @@
     "test:style": "eslint ./src/**/*.*",
     "test:unit": "webex-legacy-tools test --unit --runner jest"
   },
-  "version": "3.8.1"
+  "version": "3.9.0"
 }