feature(persist): add method getOptions on persist api and update documentation#1075 (GitHub)

diff --git a/src/middleware/persist.ts b/src/middleware/persist.ts
index 3f2008c..d81e629 100644
--- a/src/middleware/persist.ts
+++ b/src/middleware/persist.ts
@@ -85,6 +85,7 @@ interface StorePersist<S extends State, Ps> {
     hasHydrated: () => boolean
     onHydrate: (fn: PersistListener<S>) => () => void
     onFinishHydration: (fn: PersistListener<S>) => () => void
+    getOptions: () => Partial<PersistOptions<S, Ps>>
   }
 }
 
@@ -276,6 +277,7 @@ const persistImpl: PersistImpl = (config, baseOptions) => (set, get, api) => {
     clearStorage: () => {
       storage?.removeItem(options.name)
     },
+    getOptions: () => options,
     rehydrate: () => hydrate() as Promise<void>,
     hasHydrated: () => hasHydrated,
     onHydrate: (cb) => {

diff --git a/tests/persistSync.test.tsx b/tests/persistSync.test.tsx
index 3cece94..aebe09e 100644
--- a/tests/persistSync.test.tsx
+++ b/tests/persistSync.test.tsx
@@ -381,6 +381,23 @@ describe('persist middleware with sync configuration', () => {
     )
   })
 
+  it('can access the options through the api', () => {
+    const storage = {
+      getItem: () => null,
+      setItem: jest.fn(),
+      removeItem: () => {},
+    }
+
+    const useStore = create(
+      persist(() => ({ count: 0 }), {
+        name: 'test-storage',
+        getStorage: () => storage,
+      })
+    )
+    expect(useStore.persist.getOptions().name).toBeDefined()
+    expect(useStore.persist.getOptions().name).toBe('test-storage')
+  })
+
   it('can change the options through the api', () => {
     const setItemSpy = jest.fn()
 

Truncated excerpt: showing 80 of 550 lines

diff --git a/docs/persisting-store-data.md b/docs/persisting-store-data.md
new file mode 100644
index 0000000..1ea4b1f
--- /dev/null
+++ b/docs/persisting-store-data.md
@@ -0,0 +1,543 @@
+# Persist middleware
+
+The persist middleware enables you to store your Zustand state in a storage (e.g. `localStorage`, `AsyncStorage`, `IndexedDB`, etc...) thus persisting it's data.
+
+Note that this middleware does support both synchronous storages (e.g. `localStorage`) and asynchronous storages (e.g. `AsyncStorage`), but using an asynchronous storage does come with a cost.
+See [Hydration and asynchronous storages](#Hydration-and-asynchronous-storages) for more details.
+
+Quick example:
+
+```ts
+import create from 'zustand'
+import { persist } from 'zustand/middleware'
+
+export const useStore = create(
+  persist(
+    (set, get) => ({
+      fishes: 0,
+      addAFish: () => set({ fishes: get().fishes + 1 }),
+    }),
+    {
+      name: 'food-storage', // name of item in the storage (must be unique)
+      getStorage: () => sessionStorage, // (optional) by default the 'localStorage' is used
+    }
+  )
+)
+```
+
+See [Options](#Options) for more details.
+
+## Options
+
+### `name`
+
+This is the only required option.
+The given name is going to be the key used to store your Zustand state in the storage, so it must be unique.
+
+### `getStorage`
+
+> Default: `() => localStorage`
+
+Enables you to use your own storage.
+Simply pass a function that returns the storage you want to use.
+
+Example:
+
+```ts
+export const useStore = create(
+  persist(
+    (set, get) => ({
+      // ...
+    }),
+    {
+      // ...
+      getStorage: () => AsyncStorage,
+    }
+  )
+)
+```
+
+The given storage must match the following interface:
+
+```ts
+interface Storage {
+  getItem: (name: string) => string | null | Promise<string | null>
+  setItem: (name: string, value: string) => void | Promise<void>
+  removeItem: (name: string) => void | Promise<void>
+}
+```
+
+### `serialize`
+
+> Schema: `(state: Object) => string | Promise<string>`
+
+> Default: `(state) => JSON.stringify(state)`