diff --git a/README.md b/README.md index 30e68d8..5b3f3f4 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,19 @@ # BearMetalStore -A no-dep, lightweight, simple store for storing data in a JSON file. +A no-dep, lightweight, synchronous store for storing data in a JSON file. ## Usage ```ts -import { BearMetalStore } from "https://deno.land/x/bearmetalstore@v0.0.1/mod.ts"; +import { BearMetalStore } from "@bearmetal/store"; const store = new BearMetalStore(); store.set("key", "value"); console.log(store.get("key")); + +store.close(); ``` ## API @@ -25,3 +27,21 @@ Creates a new store. - `storePath?: string` The path to the store file. + +### Environment Variables + +- `BEAR_METAL_STORE_PATH` + + The path to the store file. Can be used instead of the `storePath` parameter. + If neither is provided, the store will be stored in `./BearMetal/store.json`. + +### Events + +The store will dispatch a custom event with the name +`"bm:refresh-store" + storePath` when the store is updated. This can be used to +trigger a refresh of the store in other parts of the application. + +## Permisions + +Read and write access to the store file is required. Environment access to the +"BEAR_METAL_STORE_PATH" variable is required. diff --git a/store.ts b/store.ts index 6a2e402..c21ffa9 100644 --- a/store.ts +++ b/store.ts @@ -1,9 +1,37 @@ const REFRESH_EVENT = "bm:refresh-store"; +/** + * A no-dep, lightweight, simple store for storing data in a JSON file. + * usage: + * ```ts + * import { BearMetalStore } from "@bearmetal/store"; + * + * const store = new BearMetalStore(); + * + * store.set("key", "value"); + * + * console.log(store.get("key")); + * + * store.close(); + * ``` + * + * It's recommended to use the `using` syntax to ensure the store is disposed + * of when it's no longer needed. + * ```ts + * using store = new BearMetalStore(); + * + * store.set("key", "value"); + * + * console.log(store.get("key")); + * ``` + */ export class BearMetalStore { private store: Record = {}; private storePath: string; + /** + * @description The name of the event that is dispatched when the store is updated. + */ public readonly EVENT_NAME: string; constructor(storePath?: string) { @@ -15,15 +43,28 @@ export class BearMetalStore { globalThis.addEventListener(this.EVENT_NAME, this.readIn); } + /** + * @param key + * @returns The value stored at the key, or undefined if the key doesn't exist. + */ public get(key: string): string | number | boolean { return this.store[key]; } + /** + * @description Sets the value of the key to the value. + * @param key + * @param value + */ public set(key: string, value: string | number | boolean): void { this.store[key] = value; this.writeOut(); } + /** + * @description Deletes the key and its value. + * @param key + */ public delete(key: string): void { delete this.store[key]; this.writeOut(); @@ -42,4 +83,11 @@ export class BearMetalStore { this.writeOut(); globalThis.removeEventListener(this.EVENT_NAME, this.readIn); } + + /** + * @description Closes the store and disposes of the event listener. + */ + public close() { + this[Symbol.dispose](); + } }