From fb4db65e71ba890c229d585637a01b32d0b38ac4 Mon Sep 17 00:00:00 2001 From: Moritz Raho Date: Wed, 19 Jun 2024 10:52:59 +0200 Subject: [PATCH] fix: types api doc and types, add commit hook (#168) --- doc/api.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++- lib/AdobeState.js | 4 ++-- package.json | 4 ++++ types.d.ts | 35 +++++++++++++++++++++++++++++- 4 files changed, 93 insertions(+), 4 deletions(-) diff --git a/doc/api.md b/doc/api.md index 74b08f2..59a7596 100644 --- a/doc/api.md +++ b/doc/api.md @@ -12,6 +12,9 @@
validate(schema, data) ⇒ object

Validates json according to a schema.

+
handleResponse(response, params) ⇒ void
+

Handle a network response.

+
init([config]) ⇒ Promise.<AdobeState>

Initializes and returns the key-value-store SDK.

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) ⇒ string* * *[.get(key)](#AdobeState+get) ⇒ [Promise.<AdobeStateGetReturnValue>](#AdobeStateGetReturnValue)* * *[.put(key, value, [options])](#AdobeState+put) ⇒ Promise.<string>* * *[.delete(key)](#AdobeState+delete) ⇒ Promise.<string>* * *[.deleteAll()](#AdobeState+deleteAll) ⇒ Promise.<boolean>* * *[.any()](#AdobeState+any) ⇒ Promise.<boolean>* * *[.stats()](#AdobeState+stats) ⇒ Promise.<({bytesKeys: number, bytesValues: number, keys: number}\|boolean)>* + * *[.list(options)](#AdobeState+list) ⇒ AsyncGenerator.<{keys: Array.<string>}>* + + + +### *adobeState.getRegionalEndpoint(endpoint, region) ⇒ string* +Gets the regional endpoint for an endpoint. + +**Kind**: instance method of [AdobeState](#AdobeState) +**Returns**: string - the endpoint, with the correct region + +| Param | Type | Description | +| --- | --- | --- | +| endpoint | string | the endpoint to test | +| region | string | the region to set | @@ -92,7 +110,7 @@ Creates or updates a state key-value pair Deletes a state key-value pair **Kind**: instance method of [AdobeState](#AdobeState) -**Returns**: Promise.<string> - key of deleted state or `null` if state does not exists +**Returns**: Promise.<string> - key of deleted state or `null` if state does not exist | Param | Type | Description | | --- | --- | --- | @@ -119,6 +137,28 @@ Get stats. **Kind**: instance method of [AdobeState](#AdobeState) **Returns**: Promise.<({bytesKeys: number, bytesValues: number, keys: number}\|boolean)> - namespace stats or false if not exists + + +### *adobeState.list(options) ⇒ AsyncGenerator.<{keys: Array.<string>}>* +List keys, returns an iterator. Every iteration returns a batch of +approximately `countHint` keys. + +**Kind**: instance method of [AdobeState](#AdobeState) +**Returns**: AsyncGenerator.<{keys: Array.<string>}> - an async generator which yields a + { keys } object at every iteration. + +| Param | Type | Description | +| --- | --- | --- | +| options | object | list options | +| options.match | string | a glob pattern that supports '*' to filter keys. | +| options.countHint | number | 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) + } +``` ## validate(schema, data) ⇒ object @@ -132,6 +172,18 @@ Validates json according to a schema. | schema | object | the AJV schema | | data | object | the json data to test | + + +## handleResponse(response, params) ⇒ void +Handle a network response. + +**Kind**: global function + +| Param | Type | Description | +| --- | --- | --- | +| response | Response | a fetch Response | +| params | object | the params to the network call | + ## init([config]) ⇒ [Promise.<AdobeState>](#AdobeState) diff --git a/lib/AdobeState.js b/lib/AdobeState.js index 59cbac3..edbd29f 100644 --- a/lib/AdobeState.js +++ b/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 */ diff --git a/package.json b/package.json index 07feb48..ec47b41 100644 --- a/package.json +++ b/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" diff --git a/types.d.ts b/types.d.ts index f5f4528..cb3f287 100644 --- a/types.d.ts +++ b/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; /** @@ -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[]; }>; } /**