From: Eduardo San Martin Morote <posva13@gmail.com>
Date: Mon, 3 May 2021 10:43:56 +0000 (+0200)
Subject: refactor(types): expose types as needed
X-Git-Tag: v0.4.0~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c70932a88dc25c8872b261a35cc813710aff0300;p=thirdparty%2Fvuejs%2Fpinia.git

refactor(types): expose types as needed
---

diff --git a/src/index.ts b/src/index.ts
index 1bbc646b..f121a2cc 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -13,6 +13,8 @@ export {
   StoreDefinition,
   GenericStore,
   StoreWithGetters,
+  GettersTree,
+  _Method,
   StoreWithActions,
   StoreWithState,
   PiniaCustomProperties,
@@ -27,6 +29,13 @@ export {
   mapGetters,
   MapStoresCustomization,
   setMapStoreSuffix,
+  _MapActionsObjectReturn,
+  _MapActionsReturn,
+  _MapStateObjectReturn,
+  _MapStateReturn,
+  _MapWritableStateObjectReturn,
+  _MapWritableStateReturn,
+  _Spread,
 } from './mapHelpers'
 
 // TODO: remove in beta
diff --git a/src/mapHelpers.ts b/src/mapHelpers.ts
index 72b8f27e..8726f7fa 100644
--- a/src/mapHelpers.ts
+++ b/src/mapHelpers.ts
@@ -2,7 +2,7 @@ import type Vue from 'vue'
 import {
   GenericStore,
   GettersTree,
-  Method,
+  _Method,
   StateTree,
   Store,
   StoreDefinition,
@@ -44,15 +44,18 @@ type StoreObject<S> = S extends StoreDefinition<
     }
   : {}
 
-type Spread<A extends readonly any[]> = A extends [infer L, ...infer R]
-  ? StoreObject<L> & Spread<R>
+/**
+ * @internal
+ */
+export type _Spread<A extends readonly any[]> = A extends [infer L, ...infer R]
+  ? StoreObject<L> & _Spread<R>
   : unknown
 
 function getCachedStore<
   Id extends string = string,
   S extends StateTree = StateTree,
   G extends GettersTree<S> = GettersTree<S>,
-  A = Record<string, Method>
+  A = Record<string, _Method>
 >(
   vm: ComponentPublicInstance,
   useStore: StoreDefinition<Id, S, G, A>
@@ -103,7 +106,7 @@ export function setMapStoreSuffix(
  */
 export function mapStores<Stores extends any[]>(
   ...stores: [...Stores]
-): Spread<Stores> {
+): _Spread<Stores> {
   if (__DEV__ && Array.isArray(stores[0])) {
     console.warn(
       `[🍍]: Directly pass all stores to "mapStores()" without putting them in an array:\n` +
@@ -122,14 +125,20 @@ export function mapStores<Stores extends any[]>(
       return getCachedStore(this, useStore)
     }
     return reduced
-  }, {} as Spread<Stores>)
+  }, {} as _Spread<Stores>)
 }
 
-type MapStateReturn<S extends StateTree, G extends GettersTree<S>> = {
+/**
+ * @internal
+ */
+export type _MapStateReturn<S extends StateTree, G extends GettersTree<S>> = {
   [key in keyof S | keyof G]: () => Store<string, S, G, {}>[key]
 }
 
-type MapStateObjectReturn<
+/**
+ * @internal
+ */
+export type _MapStateObjectReturn<
   Id extends string,
   S extends StateTree,
   G extends GettersTree<S>,
@@ -194,7 +203,7 @@ export function mapState<
 >(
   useStore: StoreDefinition<Id, S, G, A>,
   keyMapper: KeyMapper
-): MapStateObjectReturn<Id, S, G, A, 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
@@ -226,7 +235,7 @@ export function mapState<
 >(
   useStore: StoreDefinition<Id, S, G, A>,
   keys: Array<keyof S | keyof G>
-): MapStateReturn<S, G>
+): _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
@@ -247,14 +256,14 @@ export function mapState<
 >(
   useStore: StoreDefinition<Id, S, G, A>,
   keysOrMapper: Array<keyof S | keyof G> | KeyMapper
-): MapStateReturn<S, G> | MapStateObjectReturn<Id, S, G, A, KeyMapper> {
+): _MapStateReturn<S, G> | _MapStateObjectReturn<Id, S, G, A, KeyMapper> {
   return Array.isArray(keysOrMapper)
     ? keysOrMapper.reduce((reduced, key) => {
         reduced[key] = function (this: ComponentPublicInstance) {
           return getCachedStore(this, useStore)[key]
         } as () => any
         return reduced
-      }, {} as MapStateReturn<S, G>)
+      }, {} as _MapStateReturn<S, G>)
     : Object.keys(keysOrMapper).reduce((reduced, key: keyof KeyMapper) => {
         reduced[key] = function (this: ComponentPublicInstance) {
           const store = getCachedStore(this, useStore)
@@ -266,7 +275,7 @@ export function mapState<
             : store[storeKey as keyof S | keyof G]
         }
         return reduced
-      }, {} as MapStateObjectReturn<Id, S, G, A, KeyMapper>)
+      }, {} as _MapStateObjectReturn<Id, S, G, A, KeyMapper>)
 }
 
 /**
@@ -275,11 +284,17 @@ export function mapState<
  */
 export const mapGetters = mapState
 
-type MapActionsReturn<A> = {
+/**
+ * @internal
+ */
+export type _MapActionsReturn<A> = {
   [key in keyof A]: Store<string, StateTree, {}, A>[key]
 }
 
-type MapActionsObjectReturn<A, T extends Record<string, keyof A>> = {
+/**
+ * @internal
+ */
+export type _MapActionsObjectReturn<A, T extends Record<string, keyof A>> = {
   [key in keyof T]: Store<string, StateTree, {}, A>[T[key]]
 }
 
@@ -317,7 +332,7 @@ export function mapActions<
 >(
   useStore: StoreDefinition<Id, S, G, A>,
   keyMapper: KeyMapper
-): MapActionsObjectReturn<A, KeyMapper>
+): _MapActionsObjectReturn<A, KeyMapper>
 /**
  * Allows directly using actions from your store without using the composition
  * API (`setup()`) by generating an object to be spread in the `methods` field
@@ -349,7 +364,7 @@ export function mapActions<
 >(
   useStore: StoreDefinition<Id, S, G, A>,
   keys: Array<keyof A>
-): MapActionsReturn<A>
+): _MapActionsReturn<A>
 /**
  * Allows directly using actions from your store without using the composition
  * API (`setup()`) by generating an object to be spread in the `methods` field
@@ -367,17 +382,17 @@ export function mapActions<
 >(
   useStore: StoreDefinition<Id, S, G, A>,
   keysOrMapper: Array<keyof A> | KeyMapper
-): MapActionsReturn<A> | MapActionsObjectReturn<A, KeyMapper> {
+): _MapActionsReturn<A> | _MapActionsObjectReturn<A, KeyMapper> {
   return Array.isArray(keysOrMapper)
     ? keysOrMapper.reduce((reduced, key) => {
         reduced[key] = function (
           this: ComponentPublicInstance,
           ...args: any[]
         ) {
-          return (getCachedStore(this, useStore)[key] as Method)(...args)
+          return (getCachedStore(this, useStore)[key] as _Method)(...args)
         } as Store<string, StateTree, {}, A>[keyof A]
         return reduced
-      }, {} as MapActionsReturn<A>)
+      }, {} as _MapActionsReturn<A>)
     : Object.keys(keysOrMapper).reduce((reduced, key: keyof KeyMapper) => {
         reduced[key] = function (
           this: ComponentPublicInstance,
@@ -386,17 +401,23 @@ export function mapActions<
           return getCachedStore(this, useStore)[keysOrMapper[key]](...args)
         } as Store<string, StateTree, {}, A>[keyof KeyMapper[]]
         return reduced
-      }, {} as MapActionsObjectReturn<A, KeyMapper>)
+      }, {} as _MapActionsObjectReturn<A, KeyMapper>)
 }
 
-type MapWritableStateReturn<S extends StateTree> = {
+/**
+ * @internal
+ */
+export type _MapWritableStateReturn<S extends StateTree> = {
   [key in keyof S]: {
     get: () => Store<string, S, {}, {}>[key]
     set: (value: Store<string, S, {}, {}>[key]) => any
   }
 }
 
-type MapWritableStateObjectReturn<
+/**
+ * @internal
+ */
+export type _MapWritableStateObjectReturn<
   S extends StateTree,
   T extends Record<string, keyof S>
 > = {
@@ -423,7 +444,7 @@ export function mapWritableState<
 >(
   useStore: StoreDefinition<Id, S, G, A>,
   keyMapper: KeyMapper
-): MapWritableStateObjectReturn<S, KeyMapper>
+): _MapWritableStateObjectReturn<S, 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
@@ -440,7 +461,7 @@ export function mapWritableState<
 >(
   useStore: StoreDefinition<Id, S, G, A>,
   keys: Array<keyof S>
-): MapWritableStateReturn<S>
+): _MapWritableStateReturn<S>
 /**
  * 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
@@ -458,7 +479,7 @@ export function mapWritableState<
 >(
   useStore: StoreDefinition<Id, S, G, A>,
   keysOrMapper: Array<keyof S> | KeyMapper
-): MapWritableStateReturn<S> | MapWritableStateObjectReturn<S, KeyMapper> {
+): _MapWritableStateReturn<S> | _MapWritableStateObjectReturn<S, KeyMapper> {
   return Array.isArray(keysOrMapper)
     ? keysOrMapper.reduce((reduced, key) => {
         // @ts-ignore
@@ -472,7 +493,7 @@ export function mapWritableState<
           },
         }
         return reduced
-      }, {} as MapWritableStateReturn<S>)
+      }, {} as _MapWritableStateReturn<S>)
     : Object.keys(keysOrMapper).reduce((reduced, key: keyof KeyMapper) => {
         // @ts-ignore
         reduced[key] = {
@@ -487,5 +508,5 @@ export function mapWritableState<
           },
         }
         return reduced
-      }, {} as MapWritableStateObjectReturn<S, KeyMapper>)
+      }, {} as _MapWritableStateObjectReturn<S, KeyMapper>)
 }
diff --git a/src/rootStore.ts b/src/rootStore.ts
index 11127d88..4590074d 100644
--- a/src/rootStore.ts
+++ b/src/rootStore.ts
@@ -6,7 +6,7 @@ import {
   PiniaCustomProperties,
   GenericStore,
   GettersTree,
-  Method,
+  _Method,
   Store,
   DefineStoreOptions,
 } from './types'
@@ -43,7 +43,7 @@ export interface PiniaPluginContext<
   Id extends string = string,
   S extends StateTree = StateTree,
   G extends GettersTree<S> = GettersTree<S>,
-  A = Record<string, Method>
+  A = Record<string, _Method>
 > {
   /**
    * pinia instance.
@@ -70,6 +70,12 @@ export interface PiniaPluginContext<
  * Plugin to extend every store
  */
 export interface PiniaStorePlugin {
+  /**
+   * Plugin to extend every store. Returns an object to extend the store or
+   * nothing.
+   *
+   * @param context - Context
+   */
   (context: PiniaPluginContext): Partial<PiniaCustomProperties> | void
 }
 
diff --git a/src/store.ts b/src/store.ts
index d72f91ce..b73a6a01 100644
--- a/src/store.ts
+++ b/src/store.ts
@@ -19,7 +19,7 @@ import {
   StoreWithGetters,
   Store,
   StoreWithActions,
-  Method,
+  _Method,
   StateDescriptor,
   StoreDefinition,
   GettersTree,
@@ -215,7 +215,7 @@ function buildStoreToUse<
   Id extends string,
   S extends StateTree,
   G extends GettersTree<S>,
-  A extends Record<string, Method>
+  A extends Record<string, _Method>
 >(
   partialStore: StoreWithState<Id, S>,
   descriptor: StateDescriptor<S>,
@@ -321,7 +321,7 @@ export function defineStore<
         storeAndDescriptor[1],
         id,
         getters as GettersTree<S> | undefined,
-        actions as Record<string, Method> | undefined,
+        actions as Record<string, _Method> | undefined,
         // @ts-expect-error: because of the extend on Actions
         options
       )
@@ -342,7 +342,7 @@ export function defineStore<
         storeAndDescriptor[1],
         id,
         getters as GettersTree<S> | undefined,
-        actions as Record<string, Method> | undefined,
+        actions as Record<string, _Method> | undefined,
         // @ts-expect-error: because of the extend on Actions
         options
       )
diff --git a/src/types.ts b/src/types.ts
index d0d9fa39..ca1b1dd0 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -87,7 +87,12 @@ export interface StoreWithState<Id extends string, S extends StateTree> {
   $subscribe(callback: SubscriptionCallback<S>): () => void
 }
 
-export type Method = (...args: any[]) => any
+/**
+ * Generic type for a function that can infer arguments and return type
+ *
+ * @internal
+ */
+export type _Method = (...args: any[]) => any
 
 // export type StoreAction<P extends any[], R> = (...args: P) => R
 // export interface StoreAction<P, R> {
@@ -149,7 +154,16 @@ export interface StoreDefinition<
   G extends GettersTree<S>,
   A /* extends Record<string, StoreAction> */
 > {
+  /**
+   * Returns a store, creates it if necessary.
+   *
+   * @param pinia - Pinia instance to retrieve the store
+   */
   (pinia?: Pinia | null | undefined): Store<Id, S, G, A>
+
+  /**
+   * Id of the store. Used by map helpers.
+   */
   $id: Id
 }
 
@@ -160,7 +174,7 @@ export type GenericStore = Store<
   string,
   StateTree,
   GettersTree<StateTree>,
-  Record<string, Method>
+  Record<string, _Method>
 >
 
 /**
@@ -170,7 +184,7 @@ export type GenericStoreDefinition = StoreDefinition<
   string,
   StateTree,
   GettersTree<StateTree>,
-  Record<string, Method>
+  Record<string, _Method>
 >
 
 /**
@@ -180,9 +194,14 @@ export interface PiniaCustomProperties<
   Id extends string = string,
   S extends StateTree = StateTree,
   G extends GettersTree<S> = GettersTree<S>,
-  A = Record<string, Method>
+  A = Record<string, _Method>
 > {}
 
+/**
+ * Type of an object of Getters that infers the argument
+ *
+ * @internal
+ */
 export type GettersTree<S extends StateTree> = Record<
   string,
   ((state: S) => any) | (() => any)
@@ -198,10 +217,21 @@ export interface DefineStoreOptions<
   G extends GettersTree<S>,
   A /* extends Record<string, StoreAction> */
 > {
+  /**
+   * Unique string key to identify the store across the application.
+   */
   id: Id
+  /**
+   * Function to create a fresh state.
+   */
   state?: () => S
+  /**
+   * Optional object of getters.
+   */
   getters?: G & ThisType<S & StoreWithGetters<G> & PiniaCustomProperties>
-  // allow actions use other actions
+  /**
+   * Optional object of actions.
+   */
   actions?: A &
     ThisType<
       A &