Merge pull request #36 from MacFJA/new-shorthand

Add new store shorthand

Author: MacFJA

.docs/Examples/04-Encrypted-Storage.md

@@ -23,3 +23,7 @@ _**NOTE:** The encryption is not well adapted for cookie storage, as the data is
     const nickname = persist(writable("John"), storage, "myapp-nickname")
 </script>
 ```
+
+## Encryption key
+
+https://www.allkeysgenerator.com/Random/Security-Encryption-Key-Generator.aspx

.docs/Examples/05-Use-Persisted-Store.md

@@ -0,0 +1,166 @@
+---
+name: Usage of persistent store
+order: 5
+---
+
+# Usage of persistent store
+
+There are a multiple way to use/create persistent stores.
+
+## The long and configurable way
+
+This method allow to configure the storage by first creating it.
+This is particular useful for LocalStorage, SessionStorage, EncryptedStorage and ChromeStorage that have configuration.
+
+_**NOTE:** It's the only way to use EncryptedStorage and ChromeStorage_
+
+### Function call
+
+```typescript
+import {writable} from "svelte/store"
+
+const persistedStore = persist(
+    writable("my value"),
+    <<storageCreateFunction()>>,
+    "my-data-key"
+)
+```
+
+With:
+
+-   `writable("my value")` the store you want to persist
+-   `<<storageCreateFunction()>>` one of
+    -   `createLocalStorage`
+    -   `createSessionStorage`
+    -   `createCookieStorage`
+    -   `createIndexedDBStorage`
+    -   `createEncryptedStorage`
+    -   `createChromeStorage`
+-   `"my-data-key"` the key that will identify the store in the storage
+
+### Functions signatures
+
+```typescript
+declare function persist<T>(store: Writable<T>, storage: StorageInterface<T>, key: string): PersistentStore<T>
+
+declare function createLocalStorage<T>(listenExternalChanges?: boolean): StorageInterface<T>
+declare function createSessionStorage<T>(listenExternalChanges?: boolean): StorageInterface<T>
+declare function createCookieStorage(): StorageInterface<any>
+declare function createIndexedDBStorage<T>(): SelfUpdateStorageInterface<T>
+declare function createEncryptedStorage<T>(
+    wrapped: StorageInterface<T>,
+    encryptionKey: string
+): StorageInterface<T> | SelfUpdateStorageInterface<T>
+declare function createChromeStorage<T>(
+    storageType?: CHROME_STORAGE_TYPE,
+    listenExternalChanges?: boolean
+): SelfUpdateStorageInterface<T>
+```
+
+-   `createLocalStorage` and `createSessionStorage` take a boolean as theirs first parameter (`false` by default). If set to `true` the storage will listen for changes (of the stored value) in other pages
+-   `createEncryptedStorage` have 2 parameters, the first one is the storage that you want to encrypt, the second is the encryption key to use
+-   `createChromeStorage` have 2 optional parameters, the first one this the type of storage (local storage by default), the second (`false` by default) if set to `true` the storage will listen for changes (of the stored value) in other pages
+
+## Preconfigured storage way
+
+This method allow to use pre-created storage, configured with default options.
+This avoids creating multiple times the same storage
+
+### Function call
+
+```typescript
+import {writable} from "svelte/store"
+
+const persistedStore = <<persistFunction>>(
+    writable("my value"),
+    "my-data-key"
+)
+```
+
+With:
+
+-   `writable("my value")` the store you want to persist
+-   `<<persistFunction>>` one of
+    -   `persistBrowserLocal`
+    -   `persistBrowserSession`
+    -   `persistCookie`
+-   `"my-data-key"` the key that will identify the store in the storage
+
+### Functions signatures
+
+```typescript
+declare function persistBrowserLocal<T>(store: Writable<T>, key: string): PersistentStore<T>
+declare function persistBrowserSession<T>(store: Writable<T>, key: string): PersistentStore<T>
+declare function persistCookie<T>(store: Writable<T>, cookieName: string): PersistentStore<T>
+```
+
+## Short way
+
+This method allow to quickly create a writable store without the boilerplate of creating a Svelte store and a Storage.
+
+### Function call
+
+```typescript
+const persistedStore = <<writableFunction>>(
+    "my-data-key",
+    "my value"
+)
+```
+
+With:
+
+-   `"my value"` the value store you want to persist
+-   `<<writableFunction>>` one of
+    -   `localWritable`
+    -   `writable`
+    -   `sessionWritable`
+    -   `cookieWritable`
+-   `"my-data-key"` the key that will identify the store in the storage
+
+### Functions signatures
+
+```typescript
+declare function localWritable<T>(key: string, initialValue?: T): PersistentStore<T>
+declare function writable<T>(key: string, initialValue?: T): PersistentStore<T>
+declare function sessionWritable<T>(key: string, initialValue?: T): PersistentStore<T>
+declare function cookieWritable<T>(key: string, initialValue?: T): PersistentStore<T>
+```
+
+-   `writable` is an alias to `localWritable`
+
+---
+
+## About long format advantages
+
+The long format allow you to use High order function principle.
+
+The `persist` (and also `persistCookie`, `persistBrowserSession`, `persistBrowserLocal`) function is a high order function: it takes a parameter and return an augmented version of it.
+
+As High order function return an augmented version of their parameter, they can be chained.
+
+Imagine we have another lib that enhance a store (like `@macfja/svelte-invalidable`) we can chain them:
+
+```typescript
+import { invalidable } from "@macfja/svelte-invalidable"
+import { persistBrowserLocal } from "@macfja/svelte-persistent-store"
+import { writable } from "svelte/store"
+
+const myStore = persistBrowserLocal(
+    invalidable(writable(0), () => Math.random()),
+    "last-random"
+)
+
+// $myStore will return a number
+// myStore.invalidate() (added by @macfja/svelte-invalidable) still work
+// The value or myStore is saved in the browser localStorage
+```
+
+With the full format (`persist` only) you can also add encryption to a storage
+
+```typescript
+import { persist, createLocalStorage, createEncryptedStorage } from "@macfja/svelte-persistent-store"
+import { writable } from "svelte/store"
+
+const storage = createEncryptedStorage(createLocalStorage(), "5368566D597133743677397A24432646")
+const myStore = persist(writable(0), storage, "my-data-key")
+```

.docs/README.md

@@ -6,6 +6,7 @@
 -   [Reuse a store](Examples/02-Reuse-Store.md)
 -   [Self updated Storage](Examples/03-Self-Update-Storage.md)
 -   [Encrypt persisted data](Examples/04-Encrypted-Storage.md)
+-   [Usage of persistent store](Examples/05-Use-Persisted-Store.md)
 
 ## How to
 

.docs/tsconfig.json

@@ -9,5 +9,6 @@
         "declarationDir": "../types",
         "sourceMap": false
     },
+    "stripInternal": true,
     "files": ["../src/index.ts"]
 }

CHANGELOG.md

@@ -6,6 +6,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- New function to create store (`localWritable`, `writable`, `sessionWritable`, `cookieWritable`)
+
+### Changed
+
+- (dev) Move wrappers (+shorthand) to a dedicated file
+
 ## [2.2.1]
 
 ### Fixed

README.md

@@ -40,6 +40,17 @@ $title = "My Document"
 // if you reload the page the value of $title is 'My Document'
 ```
 
+```javascript
+import { writable } from "@macfja/svelte-persistent-store"
+
+// Create a wriatble store, persisted in browser LocalStorage, with the key `name`
+let name = writable("name", "John")
+
+$name = "Jeanne Doe"
+
+// if you reload the page the value of $name is 'Jeanne Doe'
+```
+
 ## Features
 
 -   Multiple storages (Allow to have the best suited usage depending on your use case)

src/alias.ts

@@ -0,0 +1,76 @@
+import { writable as svelteWritable } from "svelte/store"
+import type { Writable, StartStopNotifier } from "svelte/store"
+
+import type { PersistentStore, StorageInterface } from "./core"
+import { createCookieStorage, createLocalStorage, createSessionStorage, persist } from "./core"
+
+const sharedCookieStorage = createCookieStorage(),
+  sharedLocalStorage: StorageInterface<any> = createLocalStorage(),
+  sharedSessionStorage: StorageInterface<any> = createSessionStorage()
+
+/**
+ * Persist a store into a cookie
+ * @param {Writable<*>} store The store to enhance
+ * @param {string} cookieName The name of the cookie
+ */
+export function persistCookie<T>(store: Writable<T>, cookieName: string): PersistentStore<T> {
+  return persist(store, sharedCookieStorage, cookieName)
+}
+/**
+ * Persist a store into the browser session storage
+ * @param {Writable<*>} store The store to enhance
+ * @param {string} key The name of the key in the browser session storage
+ */
+export function persistBrowserSession<T>(store: Writable<T>, key: string): PersistentStore<T> {
+  return persist(store, sharedSessionStorage, key)
+}
+/**
+ * Persist a store into the browser local storage
+ * @param {Writable<*>} store The store to enhance
+ * @param {string} key The name of the key in the browser local storage
+ */
+export function persistBrowserLocal<T>(store: Writable<T>, key: string): PersistentStore<T> {
+  return persist(store, sharedLocalStorage, key)
+}
+
+/**
+ * Create a standard Svelte store persisted in Browser LocalStorage
+ * @param {string} key The key of the data to persist
+ * @param {*} [initialValue] The initial data of the store
+ * @param {StartStopNotifier<*>} [start] start and stop notifications for subscriptions
+ * @return {PersistentStore<*>}
+ */
+export function localWritable<T>(key: string, initialValue?: T, start?: StartStopNotifier<T>): PersistentStore<T> {
+  return persistBrowserLocal(svelteWritable(initialValue, start), key)
+}
+/**
+ * Create a standard Svelte store persisted in Browser LocalStorage.
+ * (Alias of [[localWritable]])
+ * @param {string} key The key of the data to persist
+ * @param {*} [initialValue] The initial data of the store
+ * @param {StartStopNotifier<*>} [start] start and stop notifications for subscriptions
+ * @return {PersistentStore<*>}
+ */
+export function writable<T>(key: string, initialValue?: T, start?: StartStopNotifier<T>): PersistentStore<T> {
+  return localWritable(key, initialValue, start)
+}
+/**
+ * Create a standard Svelte store persisted in Browser SessionStorage
+ * @param {string} key The key of the data to persist
+ * @param {*} [initialValue] The initial data of the store
+ * @param {StartStopNotifier<*>} [start] start and stop notifications for subscriptions
+ * @return {PersistentStore<*>}
+ */
+export function sessionWritable<T>(key: string, initialValue?: T, start?: StartStopNotifier<T>): PersistentStore<T> {
+  return persistBrowserSession(svelteWritable(initialValue, start), key)
+}
+/**
+ * Create a standard Svelte store persisted in cookie
+ * @param {string} key The key of the data to persist
+ * @param {*} [initialValue] The initial data of the store
+ * @param {StartStopNotifier<*>} [start] start and stop notifications for subscriptions
+ * @return {PersistentStore<*>}
+ */
+export function cookieWritable<T>(key: string, initialValue?: T, start?: StartStopNotifier<T>): PersistentStore<T> {
+  return persistCookie(svelteWritable(initialValue, start), key)
+}

src/core.ts

@@ -49,7 +49,7 @@ const warnStorageNotFound = (storageName) => {
  * Add a class to the allowed list of classes to be serialized
  * @param classDef The class to add to the list
  */
-export const addSerializableClass = (classDef: ClassDefinition<any>): void => {
+export function addSerializableClass(classDef: ClassDefinition<any>): void {
   addSerializable(classDef)
 }
 
@@ -216,34 +216,6 @@ function createListenerFunctions<T>(
   }
 }
 
-const sharedCookieStorage = createCookieStorage(),
-  sharedLocalStorage: StorageInterface<any> = createLocalStorage(),
-  sharedSessionStorage: StorageInterface<any> = createSessionStorage()
-/**
- * Persist a store into a cookie
- * @param {Writable<*>} store The store to enhance
- * @param {string} cookieName The name of the cookie
- */
-export function persistCookie<T>(store: Writable<T>, cookieName: string): PersistentStore<T> {
-  return persist(store, sharedCookieStorage, cookieName)
-}
-/**
- * Persist a store into the browser session storage
- * @param {Writable<*>} store The store to enhance
- * @param {string} key The name of the key in the browser session storage
- */
-export function persistBrowserSession<T>(store: Writable<T>, key: string): PersistentStore<T> {
-  return persist(store, sharedSessionStorage, key)
-}
-/**
- * Persist a store into the browser local storage
- * @param {Writable<*>} store The store to enhance
- * @param {string} key The name of the key in the browser local storage
- */
-export function persistBrowserLocal<T>(store: Writable<T>, key: string): PersistentStore<T> {
-  return persist(store, sharedLocalStorage, key)
-}
-
 function getBrowserStorage(browserStorage: Storage, listenExternalChanges = false): SelfUpdateStorageInterface<any> {
   const listenerFunction = (event: StorageEvent) => {
     const eventKey = event.key

src/index.ts

@@ -7,12 +7,18 @@ export {
   createSessionStorage,
   createIndexedDBStorage,
   persist,
-  persistBrowserLocal,
-  persistBrowserSession,
-  persistCookie,
   disableWarnings,
   setSerialization,
 } from "./core"
+export {
+  persistBrowserLocal,
+  persistBrowserSession,
+  persistCookie,
+  localWritable,
+  writable,
+  sessionWritable,
+  cookieWritable,
+} from "./alias"
 export type { CHROME_STORAGE_TYPE, PersistentStore, StorageInterface, SelfUpdateStorageInterface } from "./core"
 export { createEncryptionStorage, createEncryptedStorage, noEncryptionBehavior } from "./encryption"
 export type { NO_ENCRYPTION_BEHAVIOR, Encryption, GCMEncryption } from "./encryption"

tsdocs.config.js

@@ -2,4 +2,6 @@
 module.exports = {
   customPages: "./.docs",
   tsconfig: "./.docs/tsconfig.json",
+  stripInternal: true,
+  changelog: "CHANGELOG.md",
 }