wacom 21.1.25 → 21.2.0

package/README.md

@@ -713,224 +713,179 @@ httpService.unlock();
 
 ## [Store Service](#store-service)
 
-The `StoreService` manages local storage in a configurable manner. It can set, get, and remove items from storage, with support for asynchronous operations and JSON serialization.
+`StoreService` provides a unified, async-first API for working with storage (localStorage by default or a custom provider via config).
+It supports raw values, safe JSON handling, key prefixing, and optional lifecycle hooks.
 
-### Properties
-
-#### `_prefix: string`
-
-The prefix for storage keys.
+---
 
-### Methods
+### Key features
 
-#### `setPrefix(prefix: string): void`
+- async/await everywhere (no separate `*Async` methods)
+- optional side-effects via `options`
+- automatic JSON corruption handling
+- configurable storage backend
+- prefix support for namespacing
 
-Sets the prefix for storage keys.
-**Parameters**:
+---
 
-- `prefix` (string): The prefix to set.
+### Prefixing keys
 
-**Example**:
-
-```Typescript
-storeService.setPrefix('app_');
+```ts
+storeService.setPrefix("app_");
 ```
 
-#### `set(key: string, value: string, callback: () => void = () => {}, errCallback: () => void = () => {}): void`
-
-Sets a value in storage.
+All keys will be stored as `app_<key>` (plus global config prefix if defined).
 
-**Parameters**:
+---
 
-- `key` (string): The storage key.
-- `value` (string): The value to store.
-- `callback` (function): The callback to execute on success.
-- `errCallback` (function): The callback to execute on error.
+### set
 
-**Example**:
+Stores a raw string value.
 
-```Typescript
-storeService.set('key', 'value', () => console.log('Success'), () => console.log('Error'));
+```ts
+await storeService.set("token", "abc123");
 ```
 
-#### `setAsync(key: string, value: string): Promise<boolean>`
-
-Sets a value in storage asynchronously.
-
-**Parameters**:
-
-- `key` (string): The storage key.
-- `value` (string): The value to store.
-
-**Returns**:
-
-- `Promise<boolean>`: A promise that resolves to a boolean indicating success.
-
-**Example**:
+With hooks:
 
-```Typescript
-await storeService.setAsync('key', 'value');
+```ts
+await storeService.set("token", "abc123", {
+	onSuccess: () => console.log("saved"),
+	onError: console.error,
+});
 ```
 
-#### `get(key: string, callback: (value: string) => void = () => {}, errCallback: () => void = () => {}): void`
+**Returns:** `Promise<boolean>`
 
-Gets a value from storage.
-
-**Parameters**:
+---
 
-- `key` (string): The storage key.
-- `callback` (function): The callback to execute with the retrieved value.
-- `errCallback` (function): The callback to execute on error.
+### get
 
-**Example**:
+Retrieves a raw string value.
 
-```Typescript
-storeService.get('key', value => console.log(value), () => console.log('Error'));
+```ts
+const token = await storeService.get("token");
 ```
 
-#### `getAsync(key: string): Promise<string | null>`
-
-Gets a value from storage asynchronously.
-
-**Parameters**:
-
-- `key` (string): The storage key.
-
-**Returns**:
-
-- `Promise<string | null>`: A promise that resolves to the retrieved value or `null` if the key is missing.
-
-**Example**:
+With hooks:
 
-```Typescript
-const value = await storeService.getAsync('key');
+```ts
+const token = await storeService.get("token", {
+	onSuccess: (v) => console.log(v),
+	onError: console.error,
+});
 ```
 
-#### `setJson(key: string, value: any, callback: () => void = () => {}, errCallback: () => void = () => {}): void`
+**Returns:** `Promise<string | null>`
 
-Sets a JSON value in storage.
-
-**Parameters**:
+---
 
-- `key` (string): The storage key.
-- `value` (any): The value to store.
-- `callback` (function): The callback to execute on success.
-- `errCallback` (function): The callback to execute on error.
+### setJson
 
-**Example**:
+Stores a JSON-serializable value.
 
-```Typescript
-storeService.setJson('key', { data: 'value' }, () => console.log('Success'), () => console.log('Error'));
+```ts
+await storeService.setJson("profile", { name: "Den", role: "dev" });
 ```
 
-#### `setJsonAsync(key: string, value: any): Promise<boolean>`
-
-Sets a JSON value in storage asynchronously.
-
-**Parameters**:
-
-- `key` (string): The storage key.
-- `value` (any): The value to store.
+With hooks:
 
-**Returns**:
-
-- `Promise<boolean>`: A promise that resolves to a boolean indicating success.
-
-**Example**:
-
-```Typescript
-await storeService.setJsonAsync('key', { data: 'value' });
+```ts
+await storeService.setJson("profile", user, {
+	onSuccess: () => console.log("saved"),
+	onError: console.error,
+});
 ```
 
-#### `getJson(key: string, callback: (value: any) => void = () => {}, errCallback: () => void = () => {}): void`
+**Returns:** `Promise<boolean>`
 
-Gets a JSON value from storage.
+---
 
-**Parameters**:
+### getJson
 
-- `key` (string): The storage key.
-- `callback` (function): The callback to execute with the retrieved value.
-- `errCallback` (function): The callback to execute on error.
+Retrieves a JSON value safely.
 
-**Example**:
+- empty or missing → `null` (or `defaultValue`)
+- corrupted JSON → auto-cleared (by default)
 
-```Typescript
-storeService.getJson('key', value => console.log(value), () => console.log('Error'));
+```ts
+const profile = await storeService.getJson<User>("profile");
 ```
 
-#### `getJsonAsync<T = any>(key: string): Promise<T | null>`
-
-Gets a JSON value from storage asynchronously.
+With defaults and error handling:
 
-**Parameters**:
-
-- `key` (string): The storage key.
-
-**Returns**:
-
-- `Promise<T | null>`: A promise that resolves to the retrieved value.
-
-**Example**:
-
-```Typescript
-const value = await storeService.getJsonAsync('key');
+```ts
+const profile = await storeService.getJson<User>("profile", {
+	defaultValue: {},
+	onError: console.warn,
+});
 ```
 
-#### `remove(key: string, callback?: () => void, errCallback?: () => void): Promise<boolean>`
+Disable auto-clean:
 
-Removes a value from storage.
-
-**Parameters**:
+```ts
+await storeService.getJson("profile", {
+	clearOnError: false,
+});
+```
 
-- `key` (string): The storage key.
-- `callback` (function): The callback to execute on success.
-- `errCallback` (function): The callback to execute on error.
+**Returns:** `Promise<T | null>`
 
-**Returns**:
+---
 
-- `Promise<boolean>`: A promise that resolves to a boolean indicating success.
+### remove
 
-**Example**:
+Removes a single key.
 
-```Typescript
-await storeService.remove('key', () => console.log('Success'), () => console.log('Error'));
+```ts
+await storeService.remove("token");
 ```
 
-#### `clear(callback?: () => void, errCallback?: () => void): Promise<boolean>`
+With hooks:
 
-Clears all values from storage.
-
-**Parameters**:
+```ts
+await storeService.remove("token", {
+	onSuccess: () => console.log("removed"),
+	onError: console.error,
+});
+```
 
-- `callback` (function): The callback to execute on success.
-- `errCallback` (function): The callback to execute on error.
+**Returns:** `Promise<boolean>`
 
-**Returns**:
+---
 
-- `Promise<boolean>`: A promise that resolves to a boolean indicating success.
+### clear
 
-**Example**:
+Clears all stored values.
 
-```Typescript
-await storeService.clear(() => console.log('Success'), () => console.log('Error'));
+```ts
+await storeService.clear();
 ```
 
-#### `applyPrefix(key: string): string`
-
-Applies the configured prefix to a storage key.
+With hooks:
 
-**Parameters**:
+```ts
+await storeService.clear({
+	onSuccess: () => console.log("cleared"),
+	onError: console.error,
+});
+```
 
-- `key` (string): The storage key.
+**Returns:** `Promise<boolean>`
 
-**Returns**:
+---
 
-- `string`: The prefixed storage key.
+### Options object
 
-**Example**:
+All methods accept an optional `options` parameter:
 
-```Typescript
-const prefixedKey = storeService.applyPrefix('key');
+```ts
+interface StoreOptions<T = unknown> {
+	onSuccess?: (value?: T | null) => void;
+	onError?: (err: unknown) => void;
+	defaultValue?: T; // getJson only
+	clearOnError?: boolean; // getJson only (default: true)
+}
 ```
 
 ## [Meta Service](#meta-service)