Merge pull request #487 from hamiltoes/ts/typed-base-models

typescript: add base model typing

Author: marshallswain

docs/composition-api.md

@@ -779,6 +779,21 @@ export default new Router({
 
 Now, the `Post.vue` file only requires to have a `prop` named `id`.  Vue Router will pass the params from the route as props to the component.  See the [first useGet example](#useget) for a component that would work with the above route.  The vue-router documentation has more information about [Passing Props to Route Components](https://router.vuejs.org/guide/essentials/passing-props.html#passing-props-to-route-components)
 
+### Composing with Model types
+
+Both `useGet` and `useFind` have an optional type parameter for the Model type which is used as the type for the returned item(s).
+
+```ts
+// Destructure Model class from global models object
+const { User } = Vue.$FeathersVuex.api
+
+// use useGet with User Model
+useGet<typeof User.prototype>(/* ... */)
+
+// use useFind with User Model
+useFind<typeof User.prototype>(/* ... */)
+```
+
 ## Conventions for Development
 
 ### Params are Computed

docs/model-classes.md

@@ -51,6 +51,77 @@ User.instanceDefaults = function() {
 }
 ```
 
+### BaseModel typing
+
+BaseModel typing gives helpful IDE autocomplete and errors when using Model classes.
+
+Since Feathers-Vuex doesn't know what your data looks like, you will need to help define your underlying model data's interface.
+
+By default, Model classes are `string` indexable with value of type `any`. This isn't super helpful...
+
+```ts
+// Just like before, we define our class as an extension of BaseModel
+class User extends BaseModel { /* ... */ }
+
+// Augment the User Model interface
+interface User {
+  email: string
+  password: string
+}
+```
+
+Now, whenever we access a `User` model, all fields defined in the interface will be available in IDE auto-complete/intellisense along with the model methods/props.
+
+If you already have a User interface defined under a different name, just define a new interface with the same name as your Model class like so
+
+```ts
+// if our User interface already exists as UserRecord
+interface User extends UserRecord {}
+```
+
+To further enhance typing, you can augment FeathersVuex types to aid development in other parts of your app. It's important to note the differences in the following example if you do or do not setup a `serverAlias`.
+
+```ts
+// src/store/user.store.ts
+import { ServiceState } from 'feathers-vuex'
+
+class User extends BaseModel { /* ... */ }
+interface User { /* ... */ }
+const servicePath = 'users'
+
+declare module "feathers-vuex" {
+  interface FeathersVuexStoreState {
+    [servicePath]: ServiceState<User>
+  }
+
+  // Only if you setup FeathersVuex without a serverAlias!!
+  interface FeathersVuexGlobalModels {
+    User: typeof User
+  }
+}
+
+// Only if you setup FeathersVuex with a serverAlias!!
+declare module "src/store" {
+  interface MyApiModels {
+    User: typeof User
+  }
+}
+```
+
+If you have setup a `serverAlias`, you need to add the following to `src/store/index.ts`.
+
+```ts
+// src/store/index.ts
+export interface MyApiModels { /* Let each service augment this interface */ }
+declare module "feathers-vuex" {
+  interface FeathersVuexGlobalModels {
+    'my-api-name': MyApiModels
+  }
+}
+```
+
+Replace `my-api-name` with the `serverAlias` you used when setting up FeathersVuex.
+
 ## Model attributes
 
 The following attributes are available on each model:

src/auth-module/auth-module.state.ts

@@ -3,13 +3,15 @@ eslint
 @typescript-eslint/explicit-function-return-type: 0,
 @typescript-eslint/no-explicit-any: 0
 */
+import { AuthState } from './types'
+
 export default function setupAuthState({
   userService,
   serverAlias,
   responseEntityField = 'user',
   entityIdField = 'userId'
 }) {
-  const state = {
+  const state: AuthState = {
     accessToken: null, // The JWT
     payload: null, // The JWT payload
     entityIdField,
@@ -21,6 +23,7 @@ export default function setupAuthState({
     errorOnAuthenticate: null,
     errorOnLogout: null,
     user: null, // For a reactive user object, use the `user` getter.
+    userService: null,
     serverAlias
   }
   // If a userService string was passed, add a user attribute

src/auth-module/types.ts

@@ -2,11 +2,14 @@ export interface AuthState {
   accessToken: string
   payload: {}
   entityIdField: string
+  responseEntityField: string
 
   isAuthenticatePending: boolean
   isLogoutPending: boolean
 
   errorOnAuthenticate: Error
   errorOnLogout: Error
   user: {}
+  userService: string
+  serverAlias: string
 }

src/index.ts

@@ -18,9 +18,21 @@ import prepareMakeAuthPlugin from './auth-module/make-auth-plugin'
 import useFind from './useFind'
 import useGet from './useGet'
 
-import { FeathersVuexOptions, HandleEvents } from './service-module/types'
+import {
+  FeathersVuexOptions,
+  HandleEvents,
+  Model,
+  ModelStatic,
+  ModelSetupContext,
+  Id,
+  FeathersVuexStoreState,
+  FeathersVuexGlobalModels,
+  GlobalModels,
+} from './service-module/types'
 import { initAuth, hydrateApi } from './utils'
 import { FeathersVuex } from './vue-plugin/vue-plugin'
+import { ServiceState } from './service-module/service-module.state'
+import { AuthState } from './auth-module/types'
 const events = ['created', 'patched', 'updated', 'removed']
 
 const defaults: FeathersVuexOptions = {
@@ -73,7 +85,7 @@ export default function feathersVuex(feathers, options: FeathersVuexOptions) {
     BaseModel,
     makeAuthPlugin,
     FeathersVuex,
-    models,
+    models: models as GlobalModels,
     clients
   }
 }
@@ -92,5 +104,13 @@ export {
   models,
   clients,
   useFind,
-  useGet
+  useGet,
+  AuthState,
+  Id,
+  Model,
+  ModelStatic,
+  ModelSetupContext,
+  ServiceState,
+  FeathersVuexGlobalModels,
+  FeathersVuexStoreState,
 }