From a567e3782cef13d60a303bd9cadcd85b62eff05a Mon Sep 17 00:00:00 2001 From: ztimson Date: Fri, 5 Jan 2024 15:57:45 -0500 Subject: [PATCH] Updated documentation --- .github/workflows/build.yaml | 7 +++++ README.md | 51 +++++++++++++++++++++++++++++------- package.json | 2 +- src/persist.ts | 19 +++++++++++--- 4 files changed, 66 insertions(+), 13 deletions(-) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index e46c7d1..1b0ceb4 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -77,3 +77,10 @@ jobs: - name: Upload to Registry uses: ztimson/actions/npm/publish@develop + + - name: Upload to NPM + uses: ztimson/actions/npm/publish@develop + with: + owner: ztimson + registry: https://registry.npmjs.org + token: ${{secrets.NPM_TOKEN}} diff --git a/README.md b/README.md index 787d242..6a6f893 100644 --- a/README.md +++ b/README.md @@ -47,11 +47,11 @@ Persist is an updated version of [webstorage-decorators](https://git.zakscode.com/ztimson/webstorage-decorators), a library which saves variables to local or session storage. This library aims to improve upon the original's limitations by using the new [Proxy Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Improvements include: - - Supports both objects & decorators + - Supports both OOP & Decorator patterns - Proxy object ensures all changes are tracked including impure functions - [Proto]types and functions can be preserved by passing the `type` option -JavaScript's decorators are currently undergoing changes to the API overseen by [TC39](https://tc39.es) and currently have no support for property decorators. [Experimental decorators](https://www.typescriptlang.org/tsconfig#experimentalDecorators) must be enabled to work properly. +**Disclaimer:** JavaScript's decorators are currently undergoing changes to the API overseen by [TC39](https://tc39.es) and currently have no support for property decorators. [Experimental decorators](https://www.typescriptlang.org/tsconfig#experimentalDecorators) must be enabled to work properly. ### Examples @@ -186,7 +186,7 @@ console.log(theme.value); // Output: light | `options` | [`PersistOptions`](../Home.md#persistoptions) | Configure using [PersistOptions](../Home.md#persistoptions) | -#### Properties +###### Properties | Name | Type | Description | |-----------|--------------------------------------------------|-------------------------------------------------------------| @@ -216,15 +216,19 @@ Save current value to storage ##### watch -Register callback to listen for changes +Callback function which is run when there are changes `watch(fn: (value: T) => void): void` -#### Parameters +###### Parameters -| Name | Type | -| :------ | :------ | -| `fn` | (`value`: `T`) => `any` | +| Name | Type | Description | +|------|-------------------------|---------------------------------------------------------------------------------------| +| `fn` | (`value`: `T`) => `any` | Callback will run on each change; it's passed the next value & it's return is ignored | + +###### Returns + +`() => void` - Function which will unsubscribe the watch/callback when called ##### toString @@ -238,7 +242,7 @@ Return value as JSON string ##### valueOf -Return current value +Current value `valueOf(): T` @@ -255,8 +259,37 @@ Return current value +Create a proxy object which wraps your data so any changes can be intercepted & synced with storage. + +Your data is stored under the value property and should always be accessed/modified through it. + +#### Example + +```ts +class Theme { + // This property will automatically sync with localStorage + @Persist({default: 'os'}) current!: string; + + constructor() { + console.log(this.current); // Output: os + this.current == localStorage.getItem('Thene.current'); // True + this.current = 'light'; + console.log(this.current); // Output: light + } +} + +``` + +#### Constructor + `persist(options?: {key?: string} & PersistOptions)` +| Argument | Type | Description | +|-----------|--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------| +| `options` | `{key: string}` & [`PersistOptions`](../Home.md#persistoptions) | Configure using [PersistOptions](../Home.md#persistoptions). Storage key can also be ovverriden by passing `key` as an option | + + +
diff --git a/package.json b/package.json index a03ba3e..980017c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "persist", - "version": "1.0.2", + "version": "1.0.3", "description": "Sync variables with the local/session storage using proxy objects & decorators", "repository": "https://git.zakscode.com/ztimson/persistance", "author": "Zak Timson", diff --git a/src/persist.ts b/src/persist.ts index d2c140c..4b3caa0 100644 --- a/src/persist.ts +++ b/src/persist.ts @@ -94,17 +94,30 @@ export class Persist { } else this.value = this.options.default || undefined; } - /** Callback to listen for changes */ + /** + * Callback function which is run when there are changes + * + * @param {(value: T) => any} fn Callback will run on each change; it's passed the next value & it's return is ignored + * @returns {() => void} Function which will unsubscribe the watch/callback when called + */ watch(fn: (value: T) => any): () => void { const index = Object.keys(this.watches).length; this.watches[index] = fn; return () => { delete this.watches[index]; }; } - /** Return value as JSON string */ + /** + * Return value as JSON string + * + * @returns {string} Stringified object as JSON + */ toString() { return JSON.stringify(this.value); } - /** Return current value */ + /** + * Return current value + * + * @returns {T} Current value + */ valueOf() { return this.value; } }