fix: types api doc and types, add commit hook (#168)

doc/api.md

@@ -12,6 +12,9 @@
 <dt><a href="#validate">validate(schema, data)</a> ⇒ <code>object</code></dt>
 <dd><p>Validates json according to a schema.</p>
 </dd>
+<dt><a href="#handleResponse">handleResponse(response, params)</a> ⇒ <code>void</code></dt>
+<dd><p>Handle a network response.</p>
+</dd>
 <dt><a href="#init">init([config])</a> ⇒ <code><a href="#AdobeState">Promise.&lt;AdobeState&gt;</a></code></dt>
 <dd><p>Initializes and returns the key-value-store SDK.</p>
 <p>To use the SDK you must either provide your
@@ -52,12 +55,27 @@ Cloud State Management
 **Kind**: global abstract class 
 
 * *[AdobeState](#AdobeState)*
+ * *[.getRegionalEndpoint(endpoint, region)](#AdobeState+getRegionalEndpoint) ⇒ <code>string</code>*
  * *[.get(key)](#AdobeState+get) ⇒ [<code>Promise.&lt;AdobeStateGetReturnValue&gt;</code>](#AdobeStateGetReturnValue)*
  * *[.put(key, value, [options])](#AdobeState+put) ⇒ <code>Promise.&lt;string&gt;</code>*
  * *[.delete(key)](#AdobeState+delete) ⇒ <code>Promise.&lt;string&gt;</code>*
  * *[.deleteAll()](#AdobeState+deleteAll) ⇒ <code>Promise.&lt;boolean&gt;</code>*
  * *[.any()](#AdobeState+any) ⇒ <code>Promise.&lt;boolean&gt;</code>*
  * *[.stats()](#AdobeState+stats) ⇒ <code>Promise.&lt;({bytesKeys: number, bytesValues: number, keys: number}\|boolean)&gt;</code>*
+ * *[.list(options)](#AdobeState+list) ⇒ <code>AsyncGenerator.&lt;{keys: Array.&lt;string&gt;}&gt;</code>*
+
+<a name="AdobeState+getRegionalEndpoint"></a>
+
+### *adobeState.getRegionalEndpoint(endpoint, region) ⇒ <code>string</code>*
+Gets the regional endpoint for an endpoint.
+
+**Kind**: instance method of [<code>AdobeState</code>](#AdobeState) 
+**Returns**: <code>string</code> - the endpoint, with the correct region 
+
+| Param | Type | Description |
+| --- | --- | --- |
+| endpoint | <code>string</code> | the endpoint to test |
+| region | <code>string</code> | the region to set |
 
 <a name="AdobeState+get"></a>
 
@@ -92,7 +110,7 @@ Creates or updates a state key-value pair
 Deletes a state key-value pair
 
 **Kind**: instance method of [<code>AdobeState</code>](#AdobeState) 
-**Returns**: <code>Promise.&lt;string&gt;</code> - key of deleted state or `null` if state does not exists 
+**Returns**: <code>Promise.&lt;string&gt;</code> - key of deleted state or `null` if state does not exist 
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -119,6 +137,28 @@ Get stats.
 
 **Kind**: instance method of [<code>AdobeState</code>](#AdobeState) 
 **Returns**: <code>Promise.&lt;({bytesKeys: number, bytesValues: number, keys: number}\|boolean)&gt;</code> - namespace stats or false if not exists 
+<a name="AdobeState+list"></a>
+
+### *adobeState.list(options) ⇒ <code>AsyncGenerator.&lt;{keys: Array.&lt;string&gt;}&gt;</code>*
+List keys, returns an iterator. Every iteration returns a batch of
+approximately `countHint` keys.
+
+**Kind**: instance method of [<code>AdobeState</code>](#AdobeState) 
+**Returns**: <code>AsyncGenerator.&lt;{keys: Array.&lt;string&gt;}&gt;</code> - an async generator which yields a
+ { keys } object at every iteration. 
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | <code>object</code> | list options |
+| options.match | <code>string</code> | a glob pattern that supports '*' to filter keys. |
+| options.countHint | <code>number</code> | an approximate number on how many items to return per iteration. Default: 100, min: 10, max: 1000. |
+
+**Example** 
+```js
+for await (const { keys } of state.list({ match: 'abc*' })) {
+ console.log(keys)
+ }
+```
 <a name="validate"></a>
 
 ## validate(schema, data) ⇒ <code>object</code>
@@ -132,6 +172,18 @@ Validates json according to a schema.
 | schema | <code>object</code> | the AJV schema |
 | data | <code>object</code> | the json data to test |
 
+<a name="handleResponse"></a>
+
+## handleResponse(response, params) ⇒ <code>void</code>
+Handle a network response.
+
+**Kind**: global function 
+
+| Param | Type | Description |
+| --- | --- | --- |
+| response | <code>Response</code> | a fetch Response |
+| params | <code>object</code> | the params to the network call |
+
 <a name="init"></a>
 
 ## init([config]) ⇒ [<code>Promise.&lt;AdobeState&gt;</code>](#AdobeState)

lib/AdobeState.js

@@ -1,4 +1,3 @@
-/* eslint-disable jsdoc/no-undefined-types */
 /*
 Copyright 2024 Adobe. All rights reserved.
 This file is licensed to you under the Apache License, Version 2.0 (the "License");
@@ -10,6 +9,7 @@ the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTA
 OF ANY KIND, either express or implied. See the License for the specific language
 governing permissions and limitations under the License.
 */
+/* eslint-disable jsdoc/no-undefined-types */
 const cloneDeep = require('lodash.clonedeep')
 const logger = require('@adobe/aio-lib-core-logging')('@adobe/aio-lib-state', { provider: 'debug' })
 const { HttpExponentialBackoff } = require('@adobe/aio-lib-core-networking')
@@ -457,7 +457,7 @@ class AdobeState {
  * keys.
  * @param {number} options.countHint an approximate number on how many items
  * to return per iteration. Default: 100, min: 10, max: 1000.
- * @returns {AsyncGenerator<{ keys: [] }>} an async generator which yields a
+ * @returns {AsyncGenerator<{ keys: string[] }>} an async generator which yields a
  * { keys } object at every iteration.
  * @memberof AdobeState
  */

package.json

@@ -17,6 +17,9 @@
  "typings": "jsdoc -t node_modules/tsd-jsdoc/dist -r lib -d . && replace-in-file /declare/g export types.d.ts --isRegex",
  "generate-docs": "npm run jsdoc && npm run typings"
  },
+ "pre-commit": [
+ "generate-docs"
+ ],
  "author": "Adobe Inc.",
  "license": "Apache-2.0",
  "engines": {
@@ -47,6 +50,7 @@
  "eslint-plugin-promise": "^6",
  "jest": "^29",
  "jsdoc-to-markdown": "^8.0.0",
+ "pre-commit": "^1.2.2",
  "replace-in-file": "^7.0.1",
  "stdout-stderr": "^0.1.13",
  "tsd-jsdoc": "^2.4.0"

types.d.ts

@@ -37,10 +37,24 @@ export type AdobeStateGetReturnValue = {
  */
 export function validate(schema: any, data: any): any;
 
+/**
+ * Handle a network response.
+ * @param response - a fetch Response
+ * @param params - the params to the network call
+ */
+export function handleResponse(response: Response, params: any): void;
+
 /**
  * Cloud State Management
  */
 export class AdobeState {
+ /**
+ * Gets the regional endpoint for an endpoint.
+ * @param endpoint - the endpoint to test
+ * @param region - the region to set
+ * @returns the endpoint, with the correct region
+ */
+ getRegionalEndpoint(endpoint: string, region: string): string;
  /**
  * Retrieves the state value for given key.
  * If the key doesn't exist returns undefined.
@@ -59,7 +73,7 @@ export class AdobeState {
  /**
  * Deletes a state key-value pair
  * @param key - state key identifier
- * @returns key of deleted state or `null` if state does not exists
+ * @returns key of deleted state or `null` if state does not exist
  */
  delete(key: string): Promise<string>;
  /**
@@ -77,6 +91,25 @@ export class AdobeState {
  * @returns namespace stats or false if not exists
  */
  stats(): Promise<{ bytesKeys: number; bytesValues: number; keys: number; } | boolean>;
+ /**
+ * List keys, returns an iterator. Every iteration returns a batch of
+ * approximately `countHint` keys.
+ * @example
+ * for await (const { keys } of state.list({ match: 'abc*' })) {
+ * console.log(keys)
+ * }
+ * @param options - list options
+ * @param options.match - a glob pattern that supports '*' to filter
+ * keys.
+ * @param options.countHint - an approximate number on how many items
+ * to return per iteration. Default: 100, min: 10, max: 1000.
+ * @returns an async generator which yields a
+ * { keys } object at every iteration.
+ */
+ list(options: {
+ match: string;
+ countHint: number;
+ }): AsyncGenerator<{ keys: string[]; }>;
 }
 
 /**