Skip to content

Commit

Permalink
new version 2.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@arthurgermano
arthurgermano committed Aug 12, 2022
1 parent 391fa28 commit e4460ed
Show file tree
Hide file tree
Showing 25 changed files with 5,044 additions and 863 deletions.
151 changes: 95 additions & 56 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@

SPA Storage makes it ease to send and retrieve information to browser storage and forage.
You can choose witch one to use and configure how it will behave.
FORAGE is default!

## Index

Expand All @@ -16,21 +15,25 @@ FORAGE is default!
- [Example](#example)
- [SVELTE USAGE](#svelte-usage)
- [PINIA USAGE](#pinia-usage)
- [Methods Exported and Signatures](#methods-exported-and-signatures)
- [Main Methods Exported and Signatures](#main-methods-exported-and-signatures)
- [Storage Methods](#storage-methods)
- [Svelte Methods](#svelte-methods)
- [Pinia Methods](#pinia-methods)


## Features

- Ease Configuration
- Set Keys with Timeout
- Set Keys with Encryption
- Key Chain of Expire Keys
- Integration with Svelte
- Integration with Pinia - VueJS
- Simple Encryption of Information

## Install

To install Svelte Router on your svelte app:
To install SPA Storage Plugin on your app:

with npm

Expand All @@ -41,22 +44,15 @@ npm i spa-storage
### Example

```javascript

// importing spaStorage
import spaStorage from "spa-storage";

// configure options
const STORE = spaStorage("forage", {
encrypted: true,
IDX_DB_NAME: `SS_DB_`,
IDX_DB_STORE: `SS_IDX_STORE_`,
EXPIRE_KEYS: `SS_EXPIRE_KEYS`,
VERSION: 1,
DESCRIPTION: `SS_DB_DESCRIPTOR_1`,
CHECK_EXPIRED_KEYS_INTERVAL: 5000,
});

// export it as simple as that!
export default STORE;
import { spaStorage, svelteFunctions, piniaFunctions } from "spa-storage";

// starting forage to use IndexedDB
spaStorage.startForage(undefined, { name: "SS_MY_CUSTOM_NAME", storeName: "SS_CUSTOM_STORE_NAME" });

// starting storage to use localStorage
export { spaStorage, svelteFunctions, piniaFunctions };

```

Expand All @@ -67,34 +63,28 @@ Now to use it you have just to import it in your stores and use!
```javascript
// DEFINING APP STORE! It could be any store!
// importing spaStorage configured as above
import SS from "./storage.js";
import { writable } from "svelte/store";
import { assign } from "../helpers.js"; // same as cloneDeep from lodash
import { svelteFunctions as SF } from "./storage.js";

const STORAGE_KEY = "APP_STORE";
const STORAGE_KEY = "SS_APP_STORE";

const storeTemplate = {
menuOpened: false,
themeDark: false,
};

const store = writable(structuredClone(storeTemplate));
const store = writable(assign({}, storeTemplate));

// ------------------------------------------------------------------------------------------------
// -------------- darkTheme Property ------------------------------------------------------------

async function setThemeDark(themeDark) {

// this is just a shortcut to update a key inside SVELTE STORE - doesn't update the key into
// the browser value
SS.updateStoreKey(store, { themeDark });

// THIS updates the value inside the storage chosen - FORAGE is default!
await SS.setSvelteStoreInStorage(store.subscribe, STORAGE_KEY, undefined, [
"menuOpened",
]);
SF.updateStoreKey(store, { themeDark });
await SF.setSvelteStoreInStorage(store, STORAGE_KEY);
}

function getThemeDark() {
return SS.getStoreKey(store, "themeDark");
return SF.getStoreKey(store, "themeDark");
}

// ------------------------------------------------------------------------------------------------
Expand All @@ -105,19 +95,26 @@ Now to retrieve the information - when you first load the app

```javascript

import SS from "../storage.js";

// importing store defined above..
import appStr from "./app/index.js";

// defining a better naming after import
// this file in this example will contain all stores of the application
export const appStore = { ...appStr };

import { svelteFunctions as SF } from "./storage.js";
import appStore from "./app.js";

export let IS_READY = false;
export async function loadStores() {
if (IS_READY) return true;

try {
// now that we have the store defined we can retrieve information from the browser navigator
// this will load the information from the browser to the app store
await SF.getSvelteStoreInStorage(appStore.store, appStore.STORAGE_KEY);
IS_READY = true;
return true;
} catch (error) {
console.error(error);
throw error;
}
}

// now that we have the store defined we can retrieve information from the browser navigator
// this will load the information from the browser to the app store
await SS.getSvelteStoreInStorage(appStr.update, appStr.STORAGE_KEY);
export { appStore };

```

Expand All @@ -134,12 +131,12 @@ import useAppStore from "./app.js";
export const appStore = useAppStore();

// loading from browser information to the Pinia store
await getPiniaStoreInStorage(appStore.$patch, appStore.$id);
await getPiniaStoreInStorage(appStore, appStore.$id);

// now you can use subscribe to listen any changes and update the store automatically
// as below
await setPiniaStoreInStorage(
appStore.$subscribe,
appStore,
appStore.$id,
undefined,
[
Expand All @@ -151,10 +148,35 @@ await setPiniaStoreInStorage(

```

## Methods Exported and Signatures
## Main Methods Exported and Signatures

### Storage Methods

```javascript

// ----------------------------- startStorage ---------------------------------------------------

function startStorage(config = {})
// config.encrypted - true or false
// config.expireKeysKey - the name of the key that will be used to store the expire keys
// config.checkExpiredKeysInterval - the interval in milliseconds to check for expired keys

// ----------------------------- startForage ----------------------------------------------------

function startForage(config = {}, forageConfig)
// config.encrypted - true or false
// config.expireKeysKey - the name of the key that will be used to store the expire keys
// config.checkExpiredKeysInterval - the interval in milliseconds to check for expired keys

// forageConfig.name - the name of the database
// forageConfig.storeName - the name of the store
// forageConfig.version - the version of the database
// forageConfig.description - the description of the database

// ----------------------------- configure ------------------------------------------------------

function configure(config = {}, forageConfig)

// ----------------------------- getItem --------------------------------------------------------

function getItem (key) // retrieves a key from the browser storage
Expand Down Expand Up @@ -193,19 +215,28 @@ async function clearKeyList(keyList)
// IT IS CALLED AUTOMATICALLY EVERY INTERVAL SET BY CHECK_EXPIRED_KEYS_INTERVAL
async function removeExpiredKeys()


```

### Svelte Methods

```javascript

// ----------------------------- SvelteStorage --------------------------------------------------
// ----------------------------- setSvelteStoreInStorage ----------------------------------------

async function setSvelteStoreInStorage(
subscribe, // function to subscribe to the SVELTE store
store, // function to subscribe to the SVELTE store
key, // key to be updated in the browser storage
timeout, // time in milliseconds to expire the key - if not set will be forever
ignoreKeys = [] // array of keys to ignore when updating the browser storage - this will be as the keys never existed
options: {
timeout, // time in milliseconds to expire the key - if not set will be forever
ignoreKeys = [] // array of keys to ignore when updating the browser storage - this will be as the keys never existed
}
)

// ----------------------------- getSvelteStoreInStorage ----------------------------------------

async function getSvelteStoreInStorage(update, key) // retrieves a key from the browser storage
async function getSvelteStoreInStorage(store, key) // retrieves a key from the browser storage
// update - function to update the SVELTE store
// key - key to retrieve

Expand All @@ -230,20 +261,28 @@ function updateStoreKey(store, objectKeyValue, storeStateSubstitute) // updates
// objectKeyValue - object with the key and value to update
// storeStateSubstitute - if informed will replace the store state with this value

```

### Pinia Methods

```javascript

// ----------------------------- PiniaStorage ---------------------------------------------------
// ----------------------------- setPiniaStoreInStorage -----------------------------------------

async function setPiniaStoreInStorage(
$subscribe, // function to subscribe to the Pinia store
store, // store to subscribe to the Pinia store
key, // key to be updated in the browser storage
timeout, // time in milliseconds to expire the key - if not set will be forever
ignoreKeys = [] // array of keys to ignore when updating the browser storage - this will be as the keys never existed
options: {
timeout, // time in milliseconds to expire the key - if not set will be forever
ignoreKeys = [] // array of keys to ignore when updating the browser storage - this will be as the keys never existed
}
)

// ----------------------------- getPiniaStoreInStorage -----------------------------------------

async function getPiniaStoreInStorage($patch, key) // retrieves a key from the browser storage
// $patch - function to update the Pinia store
async function getPiniaStoreInStorage(store, key) // retrieves a key from the browser storage
// store - function to update the Pinia store
// key - key to retrieve


Expand Down
Loading

0 comments on commit e4460ed

Please sign in to comment.