refactor: introduce instantsearch-core (#6371)

* feat: introduce `instantsearch-core` package

* Apply suggestions from code review

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

---------

Co-authored-by: Haroen Viaene <[email protected]>
Co-authored-by: Dhaya <[email protected]>

.circleci/config.yml

@@ -178,6 +178,7 @@ jobs:
             - packages/vue-instantsearch/vue2
             - packages/vue-instantsearch/vue3
             - packages/instantsearch-ui-components/dist
+            - packages/instantsearch-core/dist
 
   test metadata:
     <<: *defaults

.codesandbox/ci.json

@@ -15,7 +15,8 @@
     "packages/react-instantsearch-nextjs",
     "packages/vue-instantsearch",
     "packages/instantsearch.css",
-    "packages/instantsearch-ui-components"
+    "packages/instantsearch-ui-components",
+    "packages/instantsearch-core"
   ],
   "node": "16"
 }

.eslintrc.js

@@ -168,6 +168,10 @@ const config = {
         '@typescript-eslint/no-unnecessary-type-assertion': 'error',
         '@typescript-eslint/method-signature-style': 'error',
         '@typescript-eslint/unbound-method': 'error',
+        'import/no-unresolved': [
+          'error',
+          { ignore: ['instantsearch-core/types'] },
+        ],
       },
     },
     {

babel.config.js

@@ -146,6 +146,19 @@ module.exports = (api) => {
           ],
         ],
       },
+      {
+        test: 'packages/instantsearch-core',
+        plugins: [
+          [
+            '@babel/plugin-transform-runtime',
+            {
+              corejs: false,
+              helpers: true,
+              regenerator: false,
+            },
+          ],
+        ],
+      },
     ],
     // jsx is transpiled, so the comment should no longer be present in the final files
     shouldPrintComment: (value) => !value.startsWith('* @jsx'),

jest.config.js

@@ -54,6 +54,7 @@ const config = {
     '^instantsearch.js/(.*)$': '<rootDir>/packages/instantsearch.js/$1',
     '^instantsearch-ui-components/(.*)$':
       '<rootDir>/packages/instantsearch-ui-components/$1',
+    '^instantsearch-core/(.*)$': '<rootDir>/packages/instantsearch-core/$1',
   },
   modulePathIgnorePatterns: [
     '<rootDir>/packages/create-instantsearch-app/src/templates',

packages/instantsearch-core/CHANGELOG.md

@@ -0,0 +1 @@
+# Change Log

packages/instantsearch-core/README.md

@@ -0,0 +1,44 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+- [instantsearch-core](#instantsearch-core)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# instantsearch-core
+
+InstantSearch Core is an open-source UI library used by InstantSearch for common utilities and types.
+
+> Note: `instantsearch-core` exists for internal usage and isn't designed for public consumption.
+
+## Contributing
+
+We welcome all contributors, from casual to regular 💙
+
+- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
+- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
+- **Documentation**. Did you find a typo in the doc? [Open an issue][contributing-newissue] and we'll take care of it.
+- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].
+
+To start contributing to code, you need to:
+
+1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
+1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
+1.  Install the dependencies: `yarn`
+
+Please read [our contribution process](https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md) to learn more.
+
+## License
+
+InstantSearch Core is [MIT licensed](../../LICENSE).
+
+<!-- Links -->
+
+[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20InstantSearch+Core
+[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20InstantSearch+Core&title=Feature%20request%3A%20
+[contributing-newissue]: https://github.com/algolia/instantsearch/issues/new?labels=triage,Library%3A%20InstantSearch+Core
+[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20InstantSearch+Core%22
+[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20InstantSearch+Core%22
+[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20InstantSearch+Core%22

packages/instantsearch-core/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "instantsearch-core",
+  "version": "0.1.0",
+  "description": "Common utilities and types for InstantSearch.",
+  "types": "dist/es/index.d.ts",
+  "main": "dist/cjs/index.js",
+  "module": "dist/es/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/es/index.d.ts",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/es/index.js"
+    },
+    "./types": {
+      "types": "./types/index.d.ts",
+      "require": "./types/index.cjs",
+      "default": "./types/index.mjs"
+    }
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/algolia/instantsearch"
+  },
+  "author": {
+    "name": "Algolia, Inc.",
+    "url": "https://www.algolia.com"
+  },
+  "keywords": [
+    "algolia",
+    "components",
+    "fast",
+    "instantsearch",
+    "react",
+    "search"
+  ],
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "yarn build:cjs && yarn build:es && yarn build:types",
+    "build:es:base": "BABEL_ENV=es,disableHoisting babel src --root-mode upward --extensions '.js,.ts,.tsx' --out-dir dist/es --ignore '**/__tests__/**/*','**/__mocks__/**/*'",
+    "build:es": "yarn build:es:base --quiet",
+    "build:cjs": "BABEL_ENV=cjs,disableHoisting babel src --root-mode upward --extensions '.js,.ts,.tsx' --out-dir dist/cjs --ignore '**/__tests__/**/*','**/__mocks__/**/*' --quiet && ../../scripts/prepare-cjs.sh",
+    "build:types": "tsc -p ./tsconfig.declaration.json --outDir ./dist/es",
+    "version": "./scripts/version.cjs",
+    "watch:es": "yarn --silent build:es:base --watch"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.1.2",
+    "algoliasearch-helper": "3.22.5"
+  }
+}

packages/instantsearch-core/scripts/version.cjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const version = require('../package.json').version;
+
+fs.writeFileSync(
+  path.resolve(__dirname, '../src/version.ts'),
+  `export default '${version}';\n`
+);

packages/instantsearch-core/src/index.ts

@@ -0,0 +1,3 @@
+import version from './version';
+
+export { version };

packages/instantsearch-core/src/version.ts

@@ -0,0 +1 @@
+export default '0.1.0';

packages/instantsearch-core/tsconfig.declaration.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.declaration"
+}

packages/instantsearch-core/types/algoliasearch.d.ts

@@ -0,0 +1,3 @@
+export type * from 'algoliasearch-helper/types/algoliasearch.d.ts';
+
+export {};

packages/instantsearch-core/types/index.cjs

@@ -0,0 +1,3 @@
+// This file exists to ensure when someone imports `instantsearch-core/types`,
+// a file exists to be resolved. Normally, this will never be used.
+module.exports = {};

packages/instantsearch-core/types/index.d.ts

@@ -0,0 +1,4 @@
+export type * from './algoliasearch.d.ts';
+export type * from './insights.d.ts';
+export type * from './results.d.ts';
+export type * from './utils.d.ts';

packages/instantsearch-core/types/index.mjs

@@ -0,0 +1,3 @@
+// This file exists to ensure when someone imports `instantsearch-core/types`,
+// a file exists to be resolved. Normally, this will never be used.
+export {};

packages/instantsearch.js/src/types/insights.ts → packages/instantsearch-core/types/insights.d.ts

@@ -1,4 +1,4 @@
-import type { Hit } from './results';
+import type { Hit } from './results.d.ts';
 import type {
   InsightsMethodMap as _InsightsMethodMap,
   InsightsClient as _InsightsClient,

packages/instantsearch.js/src/types/results.ts → packages/instantsearch-core/types/results.d.ts

@@ -1,4 +1,4 @@
-import type { SearchOptions } from './algoliasearch';
+import type { SearchOptions } from './algoliasearch.d.ts';
 import type {
   PlainSearchParameters,
   RecommendParametersOptions,

packages/instantsearch.js/src/types/utils.ts → packages/instantsearch-core/types/utils.d.ts

@@ -3,16 +3,23 @@ export type HighlightedParts = {
   isHighlighted: boolean;
 };
 
-// https://stackoverflow.com/questions/48230773/how-to-create-a-partial-like-that-requires-a-single-property-to-be-set/48244432#48244432
+/**
+ * Makes at least one of an object property required.
+ * https://stackoverflow.com/questions/48230773/how-to-create-a-partial-like-that-requires-a-single-property-to-be-set/48244432#48244432
+ */
 export type AtLeastOne<
   TTarget,
   TMapped = { [Key in keyof TTarget]: Pick<TTarget, Key> }
 > = Partial<TTarget> & TMapped[keyof TMapped];
 
-// removes intermediary composed types in IntelliSense
+/**
+ * Removes intermediary composed types in IntelliSense
+ */
 export type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
 
-// Make certain keys in an object required
+/**
+ * Make certain keys in an object required.
+ */
 export type RequiredKeys<TObject, TKeys extends keyof TObject> = Expand<
   Required<Pick<TObject, TKeys>> & Omit<TObject, TKeys>
 >;

packages/instantsearch.js/package.json

@@ -31,6 +31,7 @@
     "@types/qs": "^6.5.3",
     "algoliasearch-helper": "3.22.5",
     "htm": "^3.0.0",
+    "instantsearch-core": "0.1.0",
     "instantsearch-ui-components": "0.9.0",
     "preact": "^10.10.0",
     "qs": "^6.5.1 < 6.10",

packages/instantsearch.js/src/connectors/dynamic-widgets/__tests__/connectDynamicWidgets-test.ts

@@ -20,8 +20,8 @@ import { index } from '../../../widgets';
 import connectHierarchicalMenu from '../../hierarchical-menu/connectHierarchicalMenu';
 import connectRefinementList from '../../refinement-list/connectRefinementList';
 
-import type { SearchResponse } from '../../../types/algoliasearch';
 import type { DynamicWidgetsConnectorParams } from '../connectDynamicWidgets';
+import type { SearchResponse } from 'instantsearch-core/types';
 
 expect.addSnapshotSerializer(widgetSnapshotSerializer);
 

packages/instantsearch.js/src/index.es.ts

@@ -69,4 +69,4 @@ import { carousel } from 'instantsearch.js/es/templates'`
 
 export default instantsearch;
 
-export * from './types';
+export type * from './types';

packages/instantsearch.js/src/types/connector.ts

@@ -1,8 +1,7 @@
-import type { InsightsClient } from './insights';
 import type { InstantSearch } from './instantsearch';
-import type { Hit } from './results';
 import type { UnknownWidgetParams, Widget, WidgetDescription } from './widget';
 import type { SearchResults } from 'algoliasearch-helper';
+import type { Hit, InsightsClient } from 'instantsearch-core/types';
 
 /**
  * The base renderer options. All render functions receive

packages/instantsearch.js/src/types/index.ts

@@ -1,24 +1,19 @@
-// internal
-export * from './utils';
-
-// Algolia-related
-// eslint-disable-next-line import/export
-export * from './algoliasearch';
-export * from './results';
+export type * from 'instantsearch-core/types';
 
 // component-related
-export * from './component';
+export type * from './component';
 
 // instantsearch-related
-export * from './instantsearch';
-export * from './middleware';
-export * from './router';
-export * from './insights';
+export type * from './instantsearch';
+export type * from './middleware';
+export type * from './router';
 
 // widget-related
-export * from './connector';
-export * from './widget-factory';
-export * from './widget';
-export * from './ui-state';
-export * from './render-state';
-export * from './templates';
+export type * from './connector';
+export type * from './widget-factory';
+export type * from './widget';
+export type * from './ui-state';
+export type * from './render-state';
+export type * from './templates';
+
+export {};

packages/instantsearch.js/src/types/middleware.ts

@@ -1,6 +1,6 @@
 import type InstantSearch from '../lib/InstantSearch';
 import type { UiState } from './ui-state';
-import type { AtLeastOne } from './utils';
+import type { AtLeastOne } from 'instantsearch-core/types';
 
 export type MiddlewareDefinition<TUiState extends UiState = UiState> = {
   /**

packages/instantsearch.js/src/types/widget.ts

@@ -1,15 +1,18 @@
 import type { IndexWidget } from '../widgets';
-import type { RecommendResponse } from './algoliasearch';
 import type { InstantSearch } from './instantsearch';
 import type { IndexRenderState, WidgetRenderState } from './render-state';
 import type { IndexUiState, UiState } from './ui-state';
-import type { Expand, RequiredKeys } from './utils';
 import type {
   AlgoliaSearchHelper as Helper,
   SearchParameters,
   SearchResults,
   RecommendParameters,
 } from 'algoliasearch-helper';
+import type {
+  RecommendResponse,
+  Expand,
+  RequiredKeys,
+} from 'instantsearch-core/types';
 
 export type ScopedResult = {
   indexId: string;

packages/instantsearch.js/src/widgets/dynamic-widgets/__tests__/dynamic-widgets-test.ts

@@ -19,7 +19,7 @@ import {
 } from '../../../../test/createWidget';
 import refinementList from '../../refinement-list/refinement-list';
 
-import type { SearchResponse } from '../../../types/algoliasearch';
+import type { SearchResponse } from 'instantsearch-core/types';
 
 expect.addSnapshotSerializer(widgetSnapshotSerializer);