Merge #861

861: Allows passed API key to be a callback function r=bidoubiwa a=a11rew

# Pull Request

## Related issue
Fixes #765 

## What does this PR do?
- Adds support for passing function as API key
- Documents this feature in the README
- Adds validation for `instantMeiliSearch` parameters
	- Ensures hostUrl is a string and throws an error if otherwise
	- Ensures apiKey is a string or a function that returns a string, throws errors if otherwise
- Adds tests for `instantMeiliSearch` parameters validation 

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


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

Author: 3 people

README.md

@@ -75,6 +75,11 @@ const searchClient = instantMeiliSearch(
 )
 ```
 
+### Parameters
+
+- `Host` - URL of Meilisearch instance
+- `API Key` - Meilisearch access API Key. This can either be a string or a synchronous function that returns a string. ⚠️ Prefer using a key with only [search permissions](https://docs.meilisearch.com/learn/security/master_api_keys.html#master-key-and-api-keys) as it is used on your front-end.
+
 ## 💅 Customization
 
 `instant-meilisearch` offers some options you can set to further fit your needs.
@@ -1089,4 +1094,4 @@ If you want to know more about the development workflow or want to contribute, p
 
 <hr>
 
-**Meilisearch** provides and maintains many **SDKs and Integration tools** like this one. We want to provide everyone with an **amazing search experience for any kind of project**. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the [integration-guides](https://github.com/meilisearch/integration-guides) repository.
+**Meilisearch** provides and maintains many **SDKs and Integration tools** like this one. We want to provide everyone with an **amazing search experience for any kind of project**. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the [integration-guides](https://github.com/meilisearch/integration-guides) repository.

src/client/instant-meilisearch-client.ts

@@ -15,20 +15,32 @@ import {
 import { createSearchContext } from '../contexts'
 import { SearchCache, cacheFirstFacetDistribution } from '../cache/'
 import { constructClientAgents } from './agents'
+import { validateInstantMeiliSearchParams } from '../utils'
 
 /**
- * Instanciate SearchClient required by instantsearch.js.
- *
+ * apiKey callback definition
+ * @callback apiKeyCallback
+ * @returns {string} - The apiKey to use
+ */
+
+/**
+ * Instantiate SearchClient required by instantsearch.js.
  * @param  {string} hostUrl
- * @param  {string} apiKey
+ * @param  {string | apiKeyCallback} apiKey
  * @param  {InstantMeiliSearchOptions={}} meiliSearchOptions
  * @returns {InstantMeiliSearchInstance}
  */
 export function instantMeiliSearch(
   hostUrl: string,
-  apiKey = '',
+  apiKey: string | (() => string) = '',
   instantMeiliSearchOptions: InstantMeiliSearchOptions = {}
 ): InstantMeiliSearchInstance {
+  // Validate parameters
+  validateInstantMeiliSearchParams(hostUrl, apiKey)
+
+  // Resolve possible function to get apiKey
+  apiKey = getApiKey(apiKey)
+
   const clientAgents = constructClientAgents(
     instantMeiliSearchOptions.clientAgents
   )
@@ -104,3 +116,24 @@ export function instantMeiliSearch(
     },
   }
 }
+
+/**
+ * Resolves apiKey if it is a function
+ * @param  {string | apiKeyCallback} apiKey
+ * @returns {string} api key value
+ */
+function getApiKey(apiKey: string | (() => string)): string {
+  // If apiKey is function, call it to get the apiKey
+  if (typeof apiKey === 'function') {
+    const apiKeyFnValue = apiKey()
+    if (typeof apiKeyFnValue !== 'string') {
+      throw new TypeError(
+        'Provided apiKey function (2nd parameter) did not return a string, expected string'
+      )
+    }
+
+    return apiKeyFnValue
+  }
+
+  return apiKey
+}

src/utils/index.ts

@@ -2,3 +2,4 @@ export * from './array'
 export * from './string'
 export * from './number'
 export * from './object'
+export * from './validate'

src/utils/validate.ts

@@ -0,0 +1,29 @@
+/**
+ * apiKey callback definition
+ * @callback apiKeyCallback
+ * @returns {string} - The apiKey to use
+ */
+
+/**
+ * Validates host and apiKey parameters, throws if invalid
+ * @param hostUrl
+ * @param apiKey
+ */
+export function validateInstantMeiliSearchParams(
+  hostUrl: string,
+  apiKey: string | (() => string)
+) {
+  // Validate host url
+  if (typeof hostUrl !== 'string') {
+    throw new TypeError(
+      'Provided hostUrl value (1st parameter) is not a string, expected string'
+    )
+  }
+
+  // Validate api key
+  if (typeof apiKey !== 'string' && typeof apiKey !== 'function') {
+    throw new TypeError(
+      'Provided apiKey value (2nd parameter) is not a string or a function, expected string or function'
+    )
+  }
+}

tests/instantiation.tests.ts

@@ -0,0 +1,43 @@
+import { instantMeiliSearch } from '../src'
+
+describe('InstantMeiliSearch instantiation', () => {
+  test('instantiation with required params returns InstantMeiliSearchInstance', () => {
+    const searchClient = instantMeiliSearch(
+      'http://localhost:7700',
+      'masterKey'
+    )
+
+    expect(searchClient).toBeTruthy()
+  })
+
+  test('instantiation with function as apiKey returns InstantMeiliSearchInstance', () => {
+    const searchClient = instantMeiliSearch('http://localhost:7700', () => {
+      return 'masterKey'
+    })
+
+    expect(searchClient).toBeTruthy()
+  })
+
+  test('instantiation without hostUrl throws error', () => {
+    expect(() => {
+      // @ts-expect-error
+      instantMeiliSearch(undefined, 'masterKey')
+    }).toThrow(TypeError)
+  })
+
+  test('instantiation without apiKey as function or string throws error', () => {
+    expect(() => {
+      // @ts-expect-error
+      instantMeiliSearch('http://localhost:7700', 123)
+    }).toThrow(TypeError)
+  })
+
+  test('instantiation with function that does not return string as apiKey throws error', () => {
+    expect(() => {
+      // @ts-expect-error
+      instantMeiliSearch('http://localhost:7700', () => {
+        return 123
+      })
+    }).toThrow(TypeError)
+  })
+})