feat(javascript): allow legacy signature for search method

Author: shortcuts

.github/workflows/check.yml

@@ -294,6 +294,10 @@ jobs:
         if: ${{ steps.cache.outputs.cache-hit != 'true' }}
         run: yarn cli build clients javascript algoliasearch
 
+      - name: Run 'algoliasearch' client tests
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        run: yarn workspace @experimental-api-clients-automation/algoliasearch test
+
       - name: Zip artifact before storing
         run: zip -r -y client-javascript-algoliasearch.zip clients/algoliasearch-client-javascript/packages/algoliasearch/ -x "**/node_modules**" "clients/algoliasearch-client-javascript/.yarn**" "**/.github**"
 

clients/algoliasearch-client-javascript/packages/algoliasearch/__tests__/algoliasearch.test.ts

@@ -0,0 +1,104 @@
+import type { EchoResponse } from '@experimental-api-clients-automation/client-common';
+import { echoRequester } from '@experimental-api-clients-automation/requester-node-http';
+
+import { algoliasearch, apiClientVersion } from '../builds/node';
+
+const client = algoliasearch('APP_ID', 'API_KEY', {
+  requester: echoRequester(),
+});
+
+describe('api', () => {
+  it('sets the user agent', async () => {
+    const req = (await client.post({
+      path: '/test',
+    })) as unknown as EchoResponse;
+
+    expect(req.algoliaAgent).toMatchInlineSnapshot(
+      `"Algolia%20for%20JavaScript%20(${apiClientVersion});%20Search%20(${apiClientVersion});%20Node.js%20(${process.versions.node})"`
+    );
+  });
+
+  it('throws with undefined API key', () => {
+    try {
+      algoliasearch('APP_ID', '');
+    } catch (e) {
+      expect((e as Error).message).toMatch('`apiKey` is missing.');
+    }
+  });
+
+  it('throws with undefined app ID', () => {
+    try {
+      algoliasearch('', 'API_KEY');
+    } catch (e) {
+      expect((e as Error).message).toMatch('`appId` is missing.');
+    }
+  });
+
+  it('provides the search client at the root of the API', () => {
+    expect(client.search).not.toBeUndefined();
+  });
+
+  it('provides an init method for the analytics client', () => {
+    expect(client.initAnalytics).not.toBeUndefined();
+  });
+
+  it('provides an init method for the personalization client', () => {
+    expect(client.initPersonalization).not.toBeUndefined();
+  });
+});
+
+/**
+ * We only test the legacy signature, as `algoliasearch` inherits methods from the `client-search`.
+ * The new signatures are already tested in the CTS.
+ */
+describe('search with legacy signature', () => {
+  it('allows searching for query', async () => {
+    const req = (await client.search([
+      {
+        indexName: 'theIndexName',
+      },
+    ])) as unknown as EchoResponse;
+
+    expect(req.path).toEqual('/1/indexes/*/queries');
+    expect(req.method).toEqual('POST');
+    expect(req.data).toEqual({ requests: [{ indexName: 'theIndexName' }] });
+    expect(req.searchParams).toStrictEqual(undefined);
+  });
+
+  it('allows searching for facet', async () => {
+    const req = (await client.search([
+      {
+        indexName: 'theIndexName',
+        type: 'facet',
+        facet: 'theFacet',
+      },
+    ])) as unknown as EchoResponse;
+
+    expect(req.path).toEqual('/1/indexes/*/queries');
+    expect(req.method).toEqual('POST');
+    expect(req.data).toEqual({
+      requests: [
+        { indexName: 'theIndexName', type: 'facet', facet: 'theFacet' },
+      ],
+    });
+    expect(req.searchParams).toStrictEqual(undefined);
+  });
+
+  it('accepts a `params` parameter for `searchParams`', async () => {
+    const req = (await client.search([
+      {
+        indexName: 'theIndexName',
+        params: {
+          hitsPerPage: 42,
+        },
+      },
+    ])) as unknown as EchoResponse;
+
+    expect(req.path).toEqual('/1/indexes/*/queries');
+    expect(req.method).toEqual('POST');
+    expect(req.data).toEqual({
+      requests: [{ indexName: 'theIndexName', hitsPerPage: 42 }],
+    });
+    expect(req.searchParams).toStrictEqual(undefined);
+  });
+});

clients/algoliasearch-client-javascript/packages/algoliasearch/jest.config.ts

@@ -0,0 +1,9 @@
+import type { Config } from '@jest/types';
+
+const config: Config.InitialOptions = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['__tests__'],
+};
+
+export default config;

clients/algoliasearch-client-javascript/packages/algoliasearch/package.json

@@ -12,7 +12,8 @@
   "browser": "dist/algoliasearch.cjs.browser.js",
   "types": "index.d.ts",
   "scripts": {
-    "clean": "rm -rf ./dist"
+    "clean": "rm -rf ./dist",
+    "test": "jest"
   },
   "dependencies": {
     "@experimental-api-clients-automation/client-analytics": "0.4.0",
@@ -23,7 +24,9 @@
     "@experimental-api-clients-automation/requester-node-http": "0.4.0"
   },
   "devDependencies": {
-    "@types/node": "16.11.26",
+    "@types/jest": "27.5.2",
+    "@types/node": "16.11.38",
+    "jest": "28.1.1",
     "typescript": "4.6.3"
   },
   "engines": {

clients/algoliasearch-client-javascript/packages/algoliasearch/tsconfig.json

@@ -1,8 +1,9 @@
 {
   "extends": "../../tsconfig.json",
   "compilerOptions": {
+    "types": ["node", "jest"],
     "outDir": "dist"
   },
   "include": ["builds/node.ts", "builds/browser.ts"],
-  "exclude": ["dist", "node_modules"]
+  "exclude": ["dist", "node_modules", "__tests__"]
 }

specs/search/paths/search/search.yml

@@ -4,6 +4,7 @@ post:
   operationId: search
   x-use-read-transporter: true
   x-cacheable: true
+  x-legacy-signature: true
   summary: Search multiple indices.
   description: Perform a search operation targeting one or many indices.
   requestBody:

templates/javascript/api-single.mustache

@@ -25,11 +25,16 @@ import { {{classname}} } from '{{filename}}';
 
 {{#operations}}
 import type {
-{{#operation}}
-{{#vendorExtensions.x-create-wrapping-object}}
-{{#lambda.titlecase}}{{nickname}}{{/lambda.titlecase}}Props,
-{{/vendorExtensions.x-create-wrapping-object}}
-{{/operation}}
+  {{#operation}}
+    {{#vendorExtensions}}
+      {{#x-create-wrapping-object}}
+        {{#lambda.titlecase}}{{nickname}}{{/lambda.titlecase}}Props,
+      {{/x-create-wrapping-object}}
+      {{#x-legacy-signature}}
+        LegacySearchMethodProps,
+      {{/x-legacy-signature}}
+    {{/vendorExtensions}}
+  {{/operation}}
 } from '../model/clientMethodProps';
 {{/operations}}
 
@@ -180,12 +185,16 @@ export function create{{capitalizedApiName}}({
         {{/x-create-wrapping-object}}
         {{#x-is-single-body-param}}
           {{#bodyParams}}
-            {{paramName}}: {{{dataType}}},
+            {{paramName}}: {{{dataType}}} {{#x-legacy-signature}} | LegacySearchMethodProps{{/x-legacy-signature}},
           {{/bodyParams}}
         {{/x-is-single-body-param}}
       {{/vendorExtensions}}
       requestOptions?: RequestOptions
         ) : Promise<{{{returnType}}}> {
+      {{#vendorExtensions.x-legacy-signature}}
+        {{> legacySearchCompatible/implementation}}
+      {{/vendorExtensions.x-legacy-signature}}
+
       {{#allParams}}
       {{#required}}
       if ({{#isBoolean}}{{paramName}} === null || {{paramName}} === undefined{{/isBoolean}}{{^isBoolean}}!{{paramName}}{{/isBoolean}}) {

templates/javascript/clientMethodProps.mustache

@@ -6,7 +6,9 @@ import { {{classname}} } from '{{filename}}';
 
 {{#operations}}
 {{#operation}}
-{{#vendorExtensions.x-create-wrapping-object}}
+
+{{#vendorExtensions}}
+{{#x-create-wrapping-object}}
 /**
  * Properties for the `{{nickname}}` method.
  */
@@ -20,7 +22,11 @@ export type {{#lambda.titlecase}}{{nickname}}{{/lambda.titlecase}}Props = {
     {{paramName}}{{^required}}?{{/required}}: {{{dataType}}};
   {{/allParams}}
 }
-{{/vendorExtensions.x-create-wrapping-object}}
+{{/x-create-wrapping-object}}
+
+{{#x-legacy-signature}}{{> legacySearchCompatible/model}}{{/x-legacy-signature}}
+
+{{/vendorExtensions}}
 
 {{/operation}}
 {{/operations}}

templates/javascript/legacySearchCompatible/implementation.mustache

@@ -0,0 +1,24 @@
+if (searchMethodParams && Array.isArray(searchMethodParams)) {
+  const newSignatureRequest: SearchMethodParams = {
+    requests: searchMethodParams.map(({ params, ...legacyRequest }) => {
+      if (legacyRequest.type === 'facet') {
+        return {
+          ...legacyRequest,
+          ...params,
+          type: 'facet',
+        };
+      }
+
+      return {
+        ...legacyRequest,
+        ...params,
+        facet: undefined,
+        maxFacetHits: undefined,
+        facetQuery: undefined,
+      };
+    }),
+  };
+
+  // eslint-disable-next-line no-param-reassign
+  searchMethodParams = newSignatureRequest;
+}

templates/javascript/legacySearchCompatible/model.mustache

@@ -0,0 +1,36 @@
+import type { SearchForFacetsOptions } from './searchForFacetsOptions';
+import type { SearchForHitsOptions } from './searchForHitsOptions';
+import { SearchParamsObject } from './searchParamsObject';
+
+/**
+ * In v4, the search parameters are wrapped in a `params` parameter.
+ *
+ * @deprecated The `search` method now accepts flat `searchParams` at the root of the method.
+ */
+type LegacySearchParams = {
+  params?: Exclude<SearchParamsObject, 'query'>;
+  query?: SearchParamsObject['query'];
+};
+
+/**
+ * In v4, the search parameters are wrapped in a `params` parameter.
+ *
+ * @deprecated The `search` method now accepts flat `searchParams` at the root of the method.
+ */
+type LegacySearchForFacets = LegacySearchParams & SearchForFacetsOptions;
+
+/**
+ * In v4, the search parameters are wrapped in a `params` parameter.
+ *
+ * @deprecated The `search` method now accepts flat `searchParams` at the root of the method.
+ */
+type LegacySearchForHits = LegacySearchParams & SearchForHitsOptions;
+
+type LegacySearchQuery = LegacySearchForFacets | LegacySearchForHits;
+
+/**
+ * Search method signature compatible with the `algoliasearch` v4 package. When using this signature, extra computation will be required to make it match the new signature.
+ *
+ * @deprecated This signature will be removed from the next major version, we recommend using the `SearchMethodParams` type for performances and future proof reasons.
+ */
+export type LegacySearchMethodProps = LegacySearchQuery[];

yarn.lock

@@ -1453,7 +1453,9 @@ __metadata:
     "@experimental-api-clients-automation/client-search": 0.4.0
     "@experimental-api-clients-automation/requester-browser-xhr": 0.4.0
     "@experimental-api-clients-automation/requester-node-http": 0.4.0
-    "@types/node": 16.11.26
+    "@types/jest": 27.5.2
+    "@types/node": 16.11.38
+    jest: 28.1.1
     typescript: 4.6.3
   languageName: unknown
   linkType: soft
@@ -4585,13 +4587,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@types/node@npm:16.11.26":
-  version: 16.11.26
-  resolution: "@types/node@npm:16.11.26"
-  checksum: 57757caaba3f0d95de82198cb276a1002c49b710108c932a1d02d7c91ff2fa57cfe2dd19fde60853b6dd90b0964b3cf35557981d2628e20aed6a909057aedfe6
-  languageName: node
-  linkType: hard
-
 "@types/node@npm:16.11.38":
   version: 16.11.38
   resolution: "@types/node@npm:16.11.38"