docs: wip hehe

diff --git a/docs/introduction.md b/docs/introduction.md
index 9996eb0b21ec6fff0bfc98b9785441817fbcadb4..2d35876c2fdda242a6c65fe60b9c2c2b8b8f8c76 100644 (file)
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -1,6 +1,6 @@
 # Introduction
 
-Pinia [started](https://github.com/posva/pinia/commit/06aeef54e2cad66696063c62829dac74e15fd19e) as an experiment to redesign what a Store for Vue could look like with the [Composition API](https://github.com/vuejs/composition-api) around November 2019. Since then, the initial principles are still the same, but Pinia works for both Vue 2 and Vue 3. The API is the same for both except for _installation_ and _SSR_, and these docs are targeted to Vue 3 **with notes about Vue 2** whenever necessary so it can be used no matter if you are using Vue 2 or Vue 3!
+Pinia [started](https://github.com/posva/pinia/commit/06aeef54e2cad66696063c62829dac74e15fd19e) as an experiment to redesign what a Store for Vue could look like with the [Composition API](https://github.com/vuejs/composition-api) around November 2019. Since then, the initial principles are still the same, but Pinia works for both Vue 2 and Vue 3 **and doesn't require you to use the composition API**. The API is the same for both except for _installation_ and _SSR_, and these docs are targeted to Vue 3 **with notes about Vue 2** whenever necessary so it can be used no matter if you are using Vue 2 or Vue 3!
 
 ## Basic example
 
@@ -9,7 +9,7 @@ You start by creating a store:
 ```js
 import { defineStore } from 'pinia'
 
-export const useCounter = defineStore({
+export const useCounterStore = defineStore({
   id: 'counter',
   state() {
     return { count: 0 }
@@ -24,7 +24,7 @@ And then you _use_ it in a component:
 ```js
 export default {
   setup() {
-    const counter = useCounter()
+    const counter = useCounterStore()
 
     counter.count++
     // with autocompletion ✨
@@ -33,7 +33,36 @@ export default {
 }
 ```
 
-<!-- TODO: or if you prefer using the options api, use `mapStores` -->
+If you are still not into `setup()` and Composition API, don't worry, Pinia also support a similar set of [_map helpers_ like Vuex](https://vuex.vuejs.org/guide/state.html#the-mapstate-helper). You define stores the same way but then use `mapStores()`, `mapState()`, or `mapActions()`:
+
+```js
+const useCounterStore = defineStore({
+  id: 'counter',
+  state: () => ({ count: 0 }),
+  getters: { double: state => state.count * 2 },
+  actions: {
+    increment() {
+      this.count++
+    }
+  }
+})
+const useUserStore = defineStore({ id: 'user' })
+
+export default {
+  computed: {
+    // other computed properties
+    // ...
+    // gives access to this.counterStore and this.userStore
+    ...mapStores(useCounterStore, useUserStore)
+    // gives read access to this.count and this.double
+    ...mapState(useCounterStore, ['count', 'double']),
+  },
+  methods: {
+    // gives access to this.increment()
+    ...mapActions(useCounterStore, ['increment']),
+  },
+}
+```
 
 ## Why _Pinia_
 

diff --git a/src/mapHelpers.ts b/src/mapHelpers.ts
index e9b6de65772dc089e6fe649336f3055975094622..51cab55cf16a1b576cb1ace862b83ed117fafda9 100644 (file)
--- a/src/mapHelpers.ts
+++ b/src/mapHelpers.ts
@@ -357,3 +357,72 @@ export function mapActions<
         return reduced
       }, {} as MapActionsObjectReturn<A, KeyMapper>)
 }
+
+/**
+ * Same as `mapState()` but creates computed setters as well so the state can be
+ * modified. Differently from `mapState()`, only `state` properties can be
+ * added.
+ *
+ * @param useStore - store to map from
+ * @param keyMapper - object of state properties
+ */
+export function mapWritableState<
+  Id extends string,
+  S extends StateTree,
+  G,
+  A,
+  KeyMapper extends Record<string, keyof S>
+>(
+  useStore: StoreDefinition<Id, S, G, A>,
+  keyMapper: KeyMapper
+): MapStateObjectReturn<Id, S, G, A, KeyMapper>
+/**
+ * Allows using state and getters from one store without using the composition
+ * API (`setup()`) by generating an object to be spread in the `computed` field
+ * of a component.
+ *
+ * @param useStore - store to map from
+ * @param keys - array of state properties
+ */
+export function mapWritableState<Id extends string, S extends StateTree, G, A>(
+  useStore: StoreDefinition<Id, S, G, A>,
+  keys: Array<keyof S>
+): MapStateReturn<S, G>
+/**
+ * Allows using state and getters from one store without using the composition
+ * API (`setup()`) by generating an object to be spread in the `computed` field
+ * of a component.
+ *
+ * @param useStore - store to map from
+ * @param keysOrMapper - array or object
+ */
+export function mapWritableState<
+  Id extends string,
+  S extends StateTree,
+  G,
+  A,
+  KeyMapper extends Record<string, keyof S>
+>(
+  useStore: StoreDefinition<Id, S, G, A>,
+  keysOrMapper: Array<keyof S> | KeyMapper
+): MapStateReturn<S, G> | MapStateObjectReturn<Id, S, G, A, KeyMapper> {
+  return Array.isArray(keysOrMapper)
+    ? keysOrMapper.reduce((reduced, key) => {
+        reduced[key] = {
+          get(this: ComponentInstance) {
+            return getCachedStore(this, useStore)[key]
+          },
+          set() {},
+        }
+        return reduced
+      }, {} as MapStateReturn<S, G>)
+    : Object.keys(keysOrMapper).reduce((reduced, key: keyof KeyMapper) => {
+        reduced[key] = {
+          get(this: ComponentInstance) {
+            return getCachedStore(this, useStore)[keysOrMapper[key]]
+          },
+          set() {},
+        }
+        return reduced
+      }, {} as MapStateObjectReturn<Id, S, G, A, KeyMapper>)
+}