diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index b6acbef..e46c7d1 100644
--- a/.github/workflows/build.yaml
+++ b/.github/workflows/build.yaml
@@ -41,10 +41,6 @@ jobs:
uses: ztimson/actions/cache@develop
with:
pattern: dist
-
- - name: Upload Wiki
- uses: ztimson/actions/wiki@develop
-
tag:
name: Tag Version
needs: build
diff --git a/README.md b/README.md
index 9301252..5569b51 100644
--- a/README.md
+++ b/README.md
@@ -20,8 +20,7 @@
---
@@ -32,15 +31,54 @@
## Table of Contents
- [Persist](#top)
- [About](#about)
- - [Built With](#built-with)
+ - [Examples](#examples)
+ - [Built With](#built-with)
- [Setup](#setup)
- - [Production](#production)
- - [Development](#development)
+ - [Production](#production)
+ - [Development](#development)
+ - [Documentation](#documentation)
+ - [Classes](#classes)
+ - [Decorators](#decorators)
+ - [Types](#types)
- [License](#license)
## About
-Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+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 Objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy). Improvements include:
+ - Supports both objects & decorators
+ - 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.
+
+### Examples
+
+Using objects:
+```ts
+import {Persist} from 'ztimson/persist';
+
+// Proxy Object (Always access/modify using `.value`):
+let theme = new Persist('theme', {default: 'os'});
+
+console.log(theme.value) // Output: os
+theme.value = 'light'; // Changes will be synced to localStorage['theme'];
+```
+
+Using decorators:
+```ts
+import {persist} from 'ztimson/persist';
+
+// Using decorators
+class Theme {
+ @persist({key: 'theme', default: 'os'}) current!: string;
+}
+const theme = new Theme();
+
+console.log(theme.current); // Output: light
+theme.current = 'dark'; // You can ommit `.value` when using the decorator
+```
### Built With
[](https://typescriptlang.org/)
@@ -69,28 +107,8 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
...
}
```
-3. Use persist:
-```ts
-import {Persist} from 'ztimson/persist';
+3. Import & use, see [examples above](#examples)
-// Proxy Object (Always access/modify using `.value`):
-let theme = new Persist('theme', {default: 'os'});
-
-console.log(theme.value) // Output: os
-theme.value = 'light'; // Changes will be synced to localStorage['theme'];
-```
-```ts
-import {persist} from 'ztimson/persist';
-
-// Using decorators
-class Theme {
- @persist({key: 'theme', default: 'os'}) current!: string;
-}
-const theme = new Theme();
-
-console.log(theme.current); // Output: light
-theme.current = 'dark'; // You can ommit `.value` when using the decorator
-```
@@ -110,6 +128,135 @@ theme.current = 'dark'; // You can ommit `.value` when using the decorator
+## Documentation
+
+
+
+
+ Classes
+
+
+
+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
+import {Persist} from 'ztimson/persist'
+
+const theme = new Persist('theme.current', {default: 'os'});
+
+console.log(theme.value); // Output: os
+theme.value = 'light'; // Make sure you always use .value to access/modify data
+
+location.reload(); // Simulate refresh
+console.log(theme.value); // Output: light
+```
+
+#### Constructor
+
+`Persist(key: string, options?: PersistOptions)`
+
+| Argument | Type | Description |
+|-----------|--------------------------------------------------|-------------------------------------------------------------|
+| `key` | `string` | Primary key value will be stored under |
+| `options` | [`PersistOptions`](../Home.md#persistoptions) | Configure using [PersistOptions](../Home.md#persistoptions) |
+
+
+#### Properties
+
+| Name | Type | Description |
+|-----------|--------------------------------------------------|-------------------------------------------------------------|
+| `key` | `string` | Primary key value will be stored under |
+| `options` | [`PersistOptions`](../Home.md#persistoptions) | Configure using [PersistOptions](../Home.md#persistoptions) |
+| `value` | `T` | Current value |
+
+#### Methods
+
+##### clear
+
+Delete value from storage
+
+`clear(): void`
+
+##### load
+
+Load value from storage
+
+`load(): void`
+
+##### save
+
+Save current value to storage
+
+`save(): void`
+
+##### watch
+
+Register callback to listen for changes
+
+`watch(fn: (value: T) => void): void`
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `fn` | (`value`: `T`) => `any` |
+
+##### toString
+
+Return value as JSON string
+
+`toString(): string`
+
+###### Returns
+
+`string` - Stringified JSON object
+
+##### valueOf
+
+Return current value
+
+`valueOf(): T`
+
+###### Returns
+
+`T` - Current value
+
+
+
+
+
+
+ Decorators
+
+
+
+`persist(options?: {key?: string} & PersistOptions)`
+
+
+
+
+
+
+ Types
+
+
+
+`PersistOptions`
+
+Configurable options to change persistence behavior
+
+| Property | Type | Description |
+|------------|-----------|----------------------------------------------------------------------------------------|
+| `default?` | `T` | Default/Initial value if undefined |
+| `storage?` | `Storage` | Storage implementation, defaults to LocalStorage. Can also be used with SessionStorage |
+| `type?` | `any` | Force value to have \[proto\]type |
+
+
+
## License
Copyright © 2023 Zakary Timson | Available under MIT Licensing
diff --git a/package-lock.json b/package-lock.json
index 5d459eb..eefe8fc 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "persist",
- "version": "1.0.0",
+ "version": "1.0.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "persist",
- "version": "1.0.0",
+ "version": "1.0.1",
"license": "MIT",
"devDependencies": {
"@types/jest": "^29.5.11",
diff --git a/package.json b/package.json
index 2e20b44..a85afe7 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "persist",
- "version": "1.0.0",
+ "version": "1.0.1",
"description": "Sync variables with the local/session storage using proxy objects & decorators",
"repository": "https://git.zakscode.com/ztimson/persistance",
"author": "Zak Timson",
@@ -9,7 +9,7 @@
"types": "dist/index.d.ts",
"scripts": {
"build": "tsc && npm run build:docs",
- "build:docs": "npx typedoc --readme none --plugin typedoc-plugin-markdown --entryDocument Home.md --out docs src/index.ts",
+ "build:docs": "npx typedoc --readme none --out docs src/index.ts",
"test": "npx jest --verbose",
"test:coverage": "npx jest --verbose --coverage",
"watch": "npm run build && npx tsc --watch"
@@ -27,7 +27,6 @@
"jest-junit": "^16.0.0",
"ts-jest": "^29.1.1",
"typedoc": "^0.25.4",
- "typedoc-plugin-markdown": "^3.17.1",
"typescript": "^5.3.3"
},
"files": [
diff --git a/src/persist.ts b/src/persist.ts
index 7baa34d..8160541 100644
--- a/src/persist.ts
+++ b/src/persist.ts
@@ -1,5 +1,5 @@
/**
- * Configurations persistence behaviour
+ * Configurable options to change persistence behavior
*
* @group Options
*/
@@ -8,7 +8,7 @@ export type PersistOptions = {
default?: T,
/** Storage implementation, defaults to LocalStorage */
storage?: Storage,
- /** Force value to have prototype */
+ /** Force value to have [proto]type */
type?: any,
}
@@ -27,12 +27,15 @@ export type PersistOptions = {
* ```
*/
export class Persist {
+ /** Backend service to store data, must implement `Storage` interface */
+ private readonly storage!: Storage;
+ /** Listeners which should be notified on changes */
+ private watches: { [key: string]: Function } = {};
+
/** Private value field */
private _value!: T;
-
/** Current value or default if undefined */
get value(): T { return this._value !== undefined ? this._value : this.options?.default; }
-
/** Set value with proxy object wrapper to sync future changes */
set value(v: T | undefined) {
if(v == null || typeof v != 'object') this._value = v;
@@ -56,13 +59,8 @@ export class Persist {
this.save();
}
- /** Where data gets physically stored */
- private readonly storage!: Storage;
- /** Listeners which should be notified on changes */
- private watches: { [key: string]: Function } = {};
-
/**
- * @param {string} key Unique key value will be stored under
+ * @param {string} key Primary key value will be stored under
* @param {PersistOptions} options Configure using {@link PersistOptions}
*/
constructor(public readonly key: string, public options: PersistOptions = {}) {
@@ -101,8 +99,8 @@ export class Persist {
/** Return value as JSON string */
toString() { return JSON.stringify(this.value); }
- /** Return raw value */
- valueOf() { return this.value?.valueOf(); }
+ /** Return current value */
+ valueOf() { return this.value; }
/** Notify listeners of change */
private notify(value: T) {