Merge #756

756: Named exports r=bidoubiwa a=bidoubiwa

Fixes: #686
Based on: meilisearch/meilisearch-js-plugins#122

# Changes in README

To showcase named exports a few changes have been made in README and code-samples: 
- Separate ES, CJS and browser syntax for clarity
- Changed code-samples the same way

**These changes in the readme and code samples are open for discussion.**

# Named exports
MeiliSearch Js decided to go in the direction of new best practices in JS libraries by changing from default export to named export.

## New usage 

ES:
```javascript
import { MeiliSearch } from 'meilisearch' // ES
import DefaultMeiliSearch  from 'meilisearch' // ES

// new MeiliSearch(..)
// new DefaultMeiliSearch.MeiliSearch(..)
``` 

Node
```javascript
const { MeiliSearch } = require('meilisearch') // Node
const DefaultMeiliSearch = require('meilisearch') // Node

// new MeiliSearch(..)
// new DefaultMeiliSearch.MeiliSearch(..)
``` 

```javascript
MeiliSearch // browser
window.MeiliSearch // browser

// new MeiliSearch(..)
// new window.MeiliSearch(..)
``` 

### Typescript
```javascript
import { MeiliSearch, IndexResponse } from 'meilisearch' // ES
import DefaultMeiliSearch  from 'meilisearch' // ES

// IndexResponse
// DefaultMeiliSearch.IndexResponse
```

## Explanation

Default export brought a bunch of problems with it. Having as pros only easy of use (which becomes less and less true).

This is how it worked before this PR:

Most basic usage:
```javascript
import MeiliSearch from 'meilisearch' // ES
const MeiliSearch = require('meilisearch') // Node

// new MeiliSearch(...)
``` 

```js
window.MeiliSearch // browser
```

### Typescript
Where things got ugly: 

In typescript types are not exported by default as the default export is already used by `MeiliSearch`. 
Meaning you would have to do one of the following to get both MeiliSearch and a specific type.

```javascript
import MeiliSearch, { IndexResponse } from 'meilisearch'
```
Or this
```javascript
import MeiliSearch, * as Types from 'meilisearch'

// Types.IndexResponse
```

## Why the changes

Add to that, Some other arguments ( a [complete argument list is available here](meilisearch/meilisearch-js-plugins#122))

- `intellisense` does not work well with default export as it [lack in suggesting autocomplete](https://stackoverflow.com/questions/54427609/vscode-intellisense-not-fully-working-with-es6-imports)
- CommonJs interop. Without proper configuration of bundle, default export are weird to use in CJS. 
    ```javascript 
    const {default} = require('meilisearch');
    new default.MeiliSearch(...)
   ```
And other that you mind find in the linked github page.





Co-authored-by: Charlotte Vermandel <[email protected]>

Author: bors[bot]

.code-samples.meilisearch.yaml

@@ -293,10 +293,22 @@ getting_started_add_documents_md: |-
   $ yarn add meilisearch
   ```
 
+  **Import**
+
+  `require` syntax:
   ```js
-  const MeiliSearch = require('meilisearch')
+  const { MeiliSearch } = require('meilisearch')
   const movies = require('./movies.json')
+  ```
+
+  `import` syntax:
+  ```js
+  import { MeiliSearch } from 'meilisearch'
+  import movies from '../small_movies.json'
+  ```
 
+  **Use**
+  ```js
   const client = new MeiliSearch({ host: 'http://127.0.0.1:7700' })
   client.index('movie').addDocuments(movies)
     .then((res) => console.log(res))

README.md

@@ -70,36 +70,41 @@ NB: you can also download MeiliSearch from **Homebrew** or **APT**.
 
 ### Import <!-- omit in toc -->
 
-#### Front End or ESmodule <!-- omit in toc -->
+Depending on the environment on which you are using MeiliSearch, imports may differ.
+
+#### Import Syntax <!-- omit in toc -->
+
+Usage in a ES module environment:
 
 ```javascript
-import MeiliSearch from 'meilisearch'
+import { MeiliSearch } from 'meilisearch'
 
 const client = new MeiliSearch({
   host: 'http://127.0.0.1:7700',
   apiKey: 'masterKey',
 })
 ```
 
-#### HTML Import <!-- omit in toc -->
+#### Include Script Tag <!-- omit in toc -->
 
-```javascript
+Usage in an HTML (or alike) file:
+
+```html
 <script src="https://cdn.jsdelivr.net/npm/meilisearch@latest/dist/bundles/meilisearch.umd.js"></script>
 <script>
   const client = new MeiliSearch({
     host: 'http://127.0.0.1:7700',
     apiKey: 'masterKey',
   })
-  client.listIndexes().then(res => {
-    console.log({ res });
-  })
 </script>
 ```
 
-#### Back-End CommonJs <!-- omit in toc -->
+#### Require Syntax <!-- omit in toc -->
+
+Usage in a back-end node environment
 
 ```javascript
-const MeiliSearch = require('meilisearch')
+const { MeiliSearch } = require('meilisearch')
 
 const client = new MeiliSearch({
   host: 'http://127.0.0.1:7700',
@@ -116,9 +121,9 @@ To make this package work with React Native, please add the [react-native-url-po
 #### Add Documents <!-- omit in toc -->
 
 ```js
-const MeiliSearch = require('meilisearch')
-// Or if you are on a front-end environment:
-import MeiliSearch from 'meilisearch'
+const { MeiliSearch } = require('meilisearch')
+// Or if you are in a ES environment
+import { MeiliSearch } from 'meilisearch'
 
 ;(async () => {
   const client = new MeiliSearch({

examples/node/search_example.js

@@ -1,4 +1,4 @@
-const MeiliSearch = require('../../dist/bundles/meilisearch.umd.js')
+const { MeiliSearch } = require('../../dist/bundles/meilisearch.umd.js')
 const dataset = require('./small_movies.json')
 
 const config = {

examples/typescript-browser/package.json

@@ -4,7 +4,7 @@
   "description": "MeiliSearch Typescript Demo",
   "main": "index.js",
   "scripts": {
-    "build": "webpack"
+    "build": "webpack --resolveJsonModule"
   },
   "keywords": [
     "demo",

examples/typescript-browser/src/index.ts

@@ -1,4 +1,4 @@
-import MeiliSearch, { IndexResponse } from '../../../'
+import { MeiliSearch, IndexResponse } from '../../../'
 
 const config = {
   host: 'http://127.0.0.1:7700',

examples/typescript-browser/tsconfig.json

@@ -1,4 +1,6 @@
 {
   "compilerOptions": {
+    "resolveJsonModule": true,
+    "esModuleInterop": true
   }
 }

examples/typescript-browser/webpack.config.js

@@ -7,7 +7,7 @@ let config = {
     path: path.resolve(__dirname, './public'),
     filename: './bundle.js',
   },
-  mode: 'production',
+  mode: 'development',
   module: {
     rules: [
       {

examples/typescript-node/src/index.ts

@@ -1,4 +1,4 @@
-import MeiliSearch, { IndexResponse } from '../../../'
+import { MeiliSearch, IndexResponse } from '../../../'
 
 const config = {
   host: 'http://127.0.0.1:7700',

rollup.config.js

@@ -12,7 +12,6 @@ function getOutputFileName(fileName, isProd = false) {
 }
 
 const env = process.env.NODE_ENV || 'development'
-const LIB_NAME = 'MeiliSearch'
 const ROOT = resolve(__dirname, '.')
 
 const PLUGINS = [
@@ -22,7 +21,6 @@ const PLUGINS = [
       allowJs: false,
       includes: ['src'],
       exclude: ['tests', 'examples', '*.js', 'scripts'],
-      esModuleInterop: true,
     },
   }),
 ]
@@ -33,7 +31,8 @@ module.exports = [
     input: 'src/meilisearch.ts', // directory to transpilation of typescript
     external: ['cross-fetch', 'cross-fetch/polyfill'],
     output: {
-      name: LIB_NAME,
+      name: 'window',
+      extend: true,
       file: getOutputFileName(
         // will add .min. in filename if in production env
         resolve(ROOT, pkg.browser),
@@ -88,7 +87,7 @@ module.exports = [
           resolve(ROOT, pkg.module),
           env === 'production'
         ),
-        exports: 'default',
+        exports: 'named',
         format: 'es',
         sourcemap: env === 'production', // create sourcemap for error reporting in production mode
       },

src/meilisearch.ts

@@ -14,7 +14,7 @@ import HttpRequests from './http-requests'
 
 type createPath = (x: string | number) => string
 
-class MeiliSearch implements Types.MeiliSearchInterface {
+export class MeiliSearch implements Types.MeiliSearchInterface {
   config: Types.Config
   httpRequest: HttpRequests
   static apiRoutes: {
@@ -208,5 +208,3 @@ class MeiliSearch implements Types.MeiliSearchInterface {
     return await this.httpRequest.get<Types.EnqueuedDump>(url)
   }
 }
-
-export default MeiliSearch