Feat: Make IndexInterface generic. createIndex and getIndex generic support (#442)

* fix: allow to type the search response when using index search query

* chore: update documentation

* fix: fallback on any type if no type provided

* chore: let Typescript infer promise return type

* feat: make IndexInterface generic

- revert generic on search method in favor of generic on Interface
- following methods are now generic: search, getDocuments, getDocument, addDocuments, updateDocuments

* feat: update Index Class with generic passed to IndexInterface.

* test: let TS infer promise return type

* feat: MeiliSearchInterface getIndex and createIndex support generic

* fix: incorrect document type.

* feat: add more soundness to Document<T>

* test: let TS inference

* chore: update readme to show generic usage

Co-authored-by: cvermand <[email protected]>

Author: emyann

README.md

@@ -315,7 +315,7 @@ A GitHub Action will be triggered and push the package on [npm](https://www.npmj
 
 - Make a search request:
 
-`client.getIndex('xxx').search<T = any>(query: string, options?: SearchParams): Promise<SearchResponse<T>>`
+`client.getIndex<T>('xxx').search(query: string, options?: SearchParams): Promise<SearchResponse<T>>`
 
 ### Indexes <!-- omit in toc -->
 
@@ -325,15 +325,15 @@ A GitHub Action will be triggered and push the package on [npm](https://www.npmj
 
 - Create new index:
 
-`client.createIndex(uid: string, options?: IndexOptions): Promise<Index>`
+`client.createIndex<T>(uid: string, options?: IndexOptions): Promise<Index<T>>`
 
 - Get index object:
 
-`client.getIndex(uid: string): Indexes`
+`client.getIndex<T>(uid: string): Index<T>`
 
 - Get or create index if it does not exist
 
-`client.getOrCreateIndex(uid: string, options?: IndexOptions): Promise<Index>`
+`client.getOrCreateIndex<T>(uid: string, options?: IndexOptions): Promise<Index<T>>`
 
 - Show Index information:
 
@@ -369,19 +369,19 @@ A GitHub Action will be triggered and push the package on [npm](https://www.npmj
 
 - Add or replace multiple documents:
 
-`index.addDocuments(documents: object[]): Promise<EnqueuedUpdate>`
+`index.addDocuments(documents: Document<T>[]): Promise<EnqueuedUpdate>`
 
 - Add or update multiple documents:
 
-`index.updateDocuments(documents: object[]): Promise<EnqueuedUpdate>`
+`index.updateDocuments(documents: Document<T>[]): Promise<EnqueuedUpdate>`
 
 - Get Documents:
 
-`index.getDocuments(params: getDocumentsParams): Promise<object[]>`
+`index.getDocuments(params: getDocumentsParams): Promise<Document<T>[]>`
 
 - Get one document:
 
-`index.getDocument(documentId: string): Promise<object>`
+`index.getDocument(documentId: string): Promise<Document<T>>`
 
 - Delete one document:
 

src/index.ts

@@ -12,7 +12,7 @@ import MeiliAxiosWrapper from './meili-axios-wrapper'
 import * as Types from './types'
 import { sleep } from './utils'
 
-class Index extends MeiliAxiosWrapper implements Types.IndexInterface {
+class Index<T> extends MeiliAxiosWrapper implements Types.IndexInterface<T> {
   uid: string
   constructor(config: Types.Config, uid: string) {
     super(config)
@@ -72,7 +72,7 @@ class Index extends MeiliAxiosWrapper implements Types.IndexInterface {
    * @memberof Index
    * @method search
    */
-  async search<T = any>(
+  async search(
     query: string,
     options?: Types.SearchParams
   ): Promise<Types.SearchResponse<T>> {
@@ -197,7 +197,7 @@ class Index extends MeiliAxiosWrapper implements Types.IndexInterface {
    */
   async getDocuments(
     options?: Types.GetDocumentsParams
-  ): Promise<Types.Document[]> {
+  ): Promise<Types.Document<T>[]> {
     const url = `/indexes/${this.uid}/documents`
     let attr
     if (options !== undefined && Array.isArray(options.attributesToRetrieve)) {
@@ -217,7 +217,7 @@ class Index extends MeiliAxiosWrapper implements Types.IndexInterface {
    * @memberof Index
    * @method getDocument
    */
-  async getDocument(documentId: string | number): Promise<Types.Document> {
+  async getDocument(documentId: string | number): Promise<Types.Document<T>> {
     const url = `/indexes/${this.uid}/documents/${documentId}`
 
     return await this.get(url)
@@ -229,7 +229,7 @@ class Index extends MeiliAxiosWrapper implements Types.IndexInterface {
    * @method addDocuments
    */
   async addDocuments(
-    documents: Types.Document[],
+    documents: Types.Document<T>[],
     options?: Types.AddDocumentParams
   ): Promise<Types.EnqueuedUpdate> {
     const url = `/indexes/${this.uid}/documents`
@@ -245,7 +245,7 @@ class Index extends MeiliAxiosWrapper implements Types.IndexInterface {
    * @method updateDocuments
    */
   async updateDocuments(
-    documents: Types.Document[],
+    documents: Types.Document<T>[],
     options?: Types.AddDocumentParams
   ): Promise<Types.EnqueuedUpdate> {
     const url = `/indexes/${this.uid}/documents`

src/meilisearch.ts

@@ -24,19 +24,19 @@ class Meilisearch extends MeiliAxiosWrapper
    * @memberof Meilisearch
    * @method getIndex
    */
-  getIndex(indexUid: string): Index {
-    return new Index(this.config, indexUid)
+  getIndex<T = any>(indexUid: string): Index<T> {
+    return new Index<T>(this.config, indexUid)
   }
 
   /**
    * Get an index or create it if it does not exist
    * @memberof Meilisearch
    * @method getOrCreateIndex
    */
-  async getOrCreateIndex(
+  async getOrCreateIndex<T = any>(
     uid: string,
     options: Types.IndexOptions = {}
-  ): Promise<Index> {
+  ): Promise<Index<T>> {
     try {
       const index = await this.createIndex(uid, options)
       return index
@@ -64,10 +64,10 @@ class Meilisearch extends MeiliAxiosWrapper
    * @memberof Meilisearch
    * @method createIndex
    */
-  async createIndex(
+  async createIndex<T = any>(
     uid: string,
     options: Types.IndexOptions = {}
-  ): Promise<Index> {
+  ): Promise<Index<T>> {
     const url = '/indexes'
 
     const index = await this.post(url, { ...options, uid })

src/types.ts

@@ -51,7 +51,7 @@ export interface AddDocumentParams {
   primaryKey?: string
 }
 
-export type FacetFilter = string | FacetFilter[];
+export type FacetFilter = string | FacetFilter[]
 
 export interface SearchParams {
   offset?: number
@@ -105,9 +105,20 @@ export interface GetDocumentsParams {
   attributesToRetrieve?: string[]
 }
 
-export interface Document<T = any> {
-  [attribute: string]: T
-}
+export type DocumentLike = { [Key in string]?: DocumentField }
+export interface DocumentArray extends Array<DocumentField> {}
+export type DocumentField =
+  | string
+  | number
+  | boolean
+  | null
+  | DocumentLike
+  | DocumentArray
+
+export type Document<T> = DocumentLike &
+  {
+    [key in keyof T]: T[key]
+  }
 
 /*
  ** Settings
@@ -225,10 +236,13 @@ export interface SysInfoPretty {
 
 export interface MeiliSearchInterface extends MeiliAxiosWrapper {
   config: Config
-  getIndex: (indexUid: string) => Index
-  getOrCreateIndex: (uid: string, options?: IndexOptions) => Promise<Index>
+  getIndex: <T>(indexUid: string) => Index<T>
+  getOrCreateIndex: <T>(
+    uid: string,
+    options?: IndexOptions
+  ) => Promise<Index<T>>
   listIndexes: () => Promise<IndexResponse[]>
-  createIndex: (uid: string, options?: IndexOptions) => Promise<Index>
+  createIndex: <T>(uid: string, options?: IndexOptions) => Promise<Index<T>>
   getKeys: () => Promise<Keys>
   isHealthy: () => Promise<boolean>
   setHealthy: () => Promise<void>
@@ -240,26 +254,23 @@ export interface MeiliSearchInterface extends MeiliAxiosWrapper {
   prettySysInfo: () => Promise<SysInfoPretty>
 }
 
-export interface IndexInterface extends MeiliAxiosWrapperInterface {
+export interface IndexInterface<T = any> extends MeiliAxiosWrapperInterface {
   uid: string
   getUpdateStatus: (updateId: number) => Promise<Update>
   getAllUpdateStatus: () => Promise<Update[]>
-  search: <T = any>(
-    query: string,
-    options?: SearchParams
-  ) => Promise<SearchResponse<T>>
+  search: (query: string, options?: SearchParams) => Promise<SearchResponse<T>>
   show: () => Promise<IndexResponse>
   updateIndex: (indexData: IndexOptions) => Promise<IndexResponse>
   deleteIndex: () => Promise<string>
   getStats: () => Promise<IndexStats>
-  getDocuments: (options?: GetDocumentsParams) => Promise<Document[]>
-  getDocument: (documentId: string | number) => Promise<Document>
+  getDocuments: (options?: GetDocumentsParams) => Promise<Document<T>[]>
+  getDocument: (documentId: string | number) => Promise<Document<T>>
   addDocuments: (
-    documents: Document[],
+    documents: Document<T>[],
     options?: AddDocumentParams
   ) => Promise<EnqueuedUpdate>
   updateDocuments: (
-    documents: Document[],
+    documents: Document<T>[],
     options?: AddDocumentParams
   ) => Promise<EnqueuedUpdate>
   deleteDocument: (documentId: string | number) => Promise<EnqueuedUpdate>
@@ -310,16 +321,16 @@ export interface MeiliAxiosWrapperInterface {
     url: string,
     config?: AxiosRequestConfig
   ) => Promise<R>
-  post: ((
+  post: (<T = any>(
     url: string,
     data: IndexRequest,
     config?: AxiosRequestConfig
-  ) => Promise<Index>) &
-  (<T = any, R = AxiosResponse<EnqueuedUpdate>>(
-    url: string,
-    data?: T,
-    config?: AxiosRequestConfig
-  ) => Promise<R>)
+  ) => Promise<Index<T>>) &
+    (<T = any, R = AxiosResponse<EnqueuedUpdate>>(
+      url: string,
+      data?: T,
+      config?: AxiosRequestConfig
+    ) => Promise<R>)
   put: <T = any, R = AxiosResponse<T>>(
     url: string,
     data?: any,

tests/client_tests.ts

@@ -37,11 +37,9 @@ describe.each([
       await expect(client.listIndexes()).resolves.toHaveLength(0)
     })
     test(`${permission} key: create with no primary key`, async () => {
-      await client
-        .createIndex(uidNoPrimaryKey.uid)
-        .then((response: Types.Index) => {
-          expect(response).toHaveProperty('uid', uidNoPrimaryKey.uid)
-        })
+      await client.createIndex(uidNoPrimaryKey.uid).then((response) => {
+        expect(response).toHaveProperty('uid', uidNoPrimaryKey.uid)
+      })
 
       await client
         .getIndex(uidNoPrimaryKey.uid)
@@ -55,8 +53,10 @@ describe.each([
     })
     test(`${permission} key: create with primary key`, async () => {
       await client
-        .createIndex(uidAndPrimaryKey.uid, { primaryKey: uidAndPrimaryKey.primaryKey })
-        .then((response: Types.Index) => {
+        .createIndex(uidAndPrimaryKey.uid, {
+          primaryKey: uidAndPrimaryKey.primaryKey,
+        })
+        .then((response) => {
           expect(response).toHaveProperty('uid', uidAndPrimaryKey.uid)
         })
       await client
@@ -138,9 +138,11 @@ describe.each([
     })
 
     test(`${permission} key: create index with already existing uid should fail`, async () => {
-      await expect(client.createIndex(uidAndPrimaryKey.uid, { primaryKey: uidAndPrimaryKey.primaryKey })).rejects.toThrowError(
-        `index already exists`
-      )
+      await expect(
+        client.createIndex(uidAndPrimaryKey.uid, {
+          primaryKey: uidAndPrimaryKey.primaryKey,
+        })
+      ).rejects.toThrowError(`index already exists`)
     })
 
     test(`${permission} key: create index with missing uid should fail`, async () => {
@@ -224,14 +226,16 @@ describe.each([{ client: publicClient, permission: 'Public' }])(
         )
       })
       test(`${permission} key: try to create Index with primary key and be denied`, async () => {
-        await expect(client.createIndex(uidAndPrimaryKey.uid, { primaryKey: uidAndPrimaryKey.primaryKey })).rejects.toThrowError(
-          `Invalid API key: ${PUBLIC_KEY}`
-        )
+        await expect(
+          client.createIndex(uidAndPrimaryKey.uid, {
+            primaryKey: uidAndPrimaryKey.primaryKey,
+          })
+        ).rejects.toThrowError(`Invalid API key: ${PUBLIC_KEY}`)
       })
       test(`${permission} key: try to create Index with NO primary key and be denied`, async () => {
-        await expect(client.createIndex(uidNoPrimaryKey.uid)).rejects.toThrowError(
-          `Invalid API key: ${PUBLIC_KEY}`
-        )
+        await expect(
+          client.createIndex(uidNoPrimaryKey.uid)
+        ).rejects.toThrowError(`Invalid API key: ${PUBLIC_KEY}`)
       })
       test(`${permission} key: try to get index info and be denied`, async () => {
         await expect(
@@ -245,7 +249,9 @@ describe.each([{ client: publicClient, permission: 'Public' }])(
       })
       test(`${permission} key: try to update index and be denied`, async () => {
         await expect(
-          client.getIndex(uidAndPrimaryKey.uid).updateIndex({ primaryKey: uidAndPrimaryKey.primaryKey })
+          client
+            .getIndex(uidAndPrimaryKey.uid)
+            .updateIndex({ primaryKey: uidAndPrimaryKey.primaryKey })
         ).rejects.toThrowError(`Invalid API key: ${PUBLIC_KEY}`)
       })
     })
@@ -284,14 +290,16 @@ describe.each([{ client: anonymousClient, permission: 'No' }])(
         )
       })
       test(`${permission} key: try to create an index with primary key and be denied`, async () => {
-        await expect(client.createIndex(uidAndPrimaryKey.uid, { primaryKey: uidAndPrimaryKey.primaryKey })).rejects.toThrowError(
-          `You must have an authorization token`
-        )
+        await expect(
+          client.createIndex(uidAndPrimaryKey.uid, {
+            primaryKey: uidAndPrimaryKey.primaryKey,
+          })
+        ).rejects.toThrowError(`You must have an authorization token`)
       })
       test(`${permission} key: try to create an index with NO primary key and be denied`, async () => {
-        await expect(client.createIndex(uidNoPrimaryKey.uid)).rejects.toThrowError(
-          `You must have an authorization token`
-        )
+        await expect(
+          client.createIndex(uidNoPrimaryKey.uid)
+        ).rejects.toThrowError(`You must have an authorization token`)
       })
       test(`${permission} key: try to get index info and be denied`, async () => {
         await expect(
@@ -305,7 +313,9 @@ describe.each([{ client: anonymousClient, permission: 'No' }])(
       })
       test(`${permission} key: try to update index and be denied`, async () => {
         await expect(
-          client.getIndex(uidAndPrimaryKey.uid).updateIndex({ primaryKey: uidAndPrimaryKey.primaryKey })
+          client
+            .getIndex(uidAndPrimaryKey.uid)
+            .updateIndex({ primaryKey: uidAndPrimaryKey.primaryKey })
         ).rejects.toThrowError(`You must have an authorization token`)
       })
     })