No clear migration guide for v5 and no explicit typing

[WavyWalk]

We want to migrate to v4 from v5, but migrating even this snippet is problematic:

const object = await algoliasearch(algoliaApplicationId, algoliaApiKey)
      .initIndex(productsAlgoliaIndex)
      .getObjects<AlgoliaRecord>(productIds)

I see in source code that getObjects exist in v5 but one can't pass index and it's not in docs, and there's no index in types.

Also types are not straightforward (I get that it's generated but still), so rules like @typescript-eslint/no-unsafe-assignment fail because of any's in unions.

As well not sure how to proceed with now failing type checks for react instantsearch because things like:
hitsPerPage, analyticsTags on <Configure /> reference the types of v5 which do not have it.

Do you recommend to migrate now or wait till there will be a proper migration guide and types will be improved?

[OutdatedGuy]

You need to update your code using this documentation. It doesn't feel complete so it sucks. You might have to view code documentation/intellisense from your code editor/IDE.

Before:

import algoliasearch from "algoliasearch";

const object = await algoliasearch(algoliaApplicationId, algoliaApiKey)
  .initIndex(productsAlgoliaIndex)
  .getObjects<AlgoliaRecord>(productIds);

After:

import { algoliasearch } from "algoliasearch";

const object = await algoliasearch(algoliaApplicationId, algoliaApiKey)
  .getObjects<AlgoliaRecord>({
    requests: [
      {
        indexName: productsAlgoliaIndex,
        objectID: productId1,
      },
      {
        indexName: productsAlgoliaIndex,
        objectID: productId2,
      },
      // ...
    ],
  });

[shortcuts]

Hey @WavyWalk thanks for using the v5 client already, and sorry for the lack of documentation, we are currently working on providing snippets and guides! (and thanks @OutdatedGuy for the help :D)

I see in source code that getObjects exist in v5 but one can't pass index and it's not in docs, and there's no index in types.

The initIndex of the previous version was kind of magical syntactic sugar (and not suited for generated clients too), as mentioned here, every methods are now available at the root of the client, if you were using one via initIndex before, it will now expect an indexName parameter if it's a single-index method, or an indexName in the requests if it's a multi-index method

In the meantime of the guides being available, you can browse our API reference which includes a code snippet for every methods of the client, for every languages.

As well not sure how to proceed with now failing type checks for react instantsearch because things like:
hitsPerPage, analyticsTags on reference the types of v5 which do not have it.

I'll investigate this but since I'm not super familiar with RIS cc @Haroenv

Do you recommend to migrate now or wait till there will be a proper migration guide and types will be improved?

Did you find any wrong typings or something that would prevent you from migrating? If so, I can fix those and help you move forward :) Otherwise I think it would be mostly migrating method signatures which (I hope) shouldn't be too different

[Haroenv]

for React InstantSearch, ensure you're on the very latest version, if you're on an older version this may not be inferred right. In my testing it also worked completely as expected, but maybe we missed a case? please make a full reproduction if anything isn't inferred as expected

[WavyWalk]

Here's repo with reproduction of the issues I mentioned:
https://github.com/WavyWalk/reproduce-algolia-v5

• hitsPerPage, analyticsTags are missing on types for properties of react instant search Configure
• type definitions break @typescript-eslint/no-redundant-type-constituents rule
• because of that as well this rule will break @typescript-eslint/no-unsafe-assignmen

all you can see in https://github.com/WavyWalk/reproduce-algolia-v5/blob/master/src/App.tsx

[Haroenv]

Oh no, you're right! I'm just realising that a last fix for the types was only done in algolia/instantsearch#6270 which isn't merged yet. I'll get right on making sure CI passes there (unrelated failure) and we can release a fix soon

[WavyWalk]

regarding getObjects:

I see that objects can be fetched from multiple indexes and hence it accept array of index objectID pairs,

but if I pass hundreds of pairs with same index will it still make one call?

.getObjects<AlgoliaRecord>({
    requests: [
      {
        indexName: productsAlgoliaIndex,
        objectID: productId1,
      },
      {
        indexName: productsAlgoliaIndex,
        objectID: productId2,
      },
      // ...
    ],

more natural would be, does it support it?:

requests: [
      {
        indexName: someIndex,
        objectIds: Array<string>,
      },
      {
        indexName: otherIndex,
        objectID: Array<string>,
      }

```]

[shortcuts]

Hey

regarding getObjects:

I see that objects can be fetched from multiple indexes and hence it accept array of index objectID pairs,

but if I pass hundreds of pairs with same index will it still make one call?

Yes

more natural would be, does it support it?:

Those new clients are meant to be closer to the API, so this signatures is exactly what is expected from the REST endpoint

[MattIPv4]

👋 Not to pile on here, but please could an actual migration guide be published here, that documents the actual signature changes for methods?

For example, it turns out browseObjects now takes an aggregator method, not batch, and the data passed to that method is of a different shape to before (an object containing a hits array, rather than just an array). Or take setSettings which now takes the settings as a nested indexSettings method and forwardToReplicas as part of the first object, not a second object. I had to inspect the source to find these things, and I should not have to do that when a migration guide supposedly exists...

Even the bits that are documented currently aren't great... wait was removed on methods and the replacements in the guide link out to documentation for the Python library. Even if they did link to the JS docs, it doesn't appear to be a 1:1 mapping of the methods -- if I call saveObjects I don't just get back taskID or an object containing it, instead I get back an array of objects containing task IDs... and so I need to manually call waitForTask for each one? This seems like a huge step back for DX...

I would complain far less if the documentation actually existed for the methods, but that doesn't exist either (sans a select few methods classed as "helpers" or unless you rely on code samples in the REST API docs which seem to be missing a bunch of options [like forwardToReplicas mentioned earlier])... so between no migration guide and no actual documentation, trying to upgrade to this new major is incredibly painful at present.

[Haroenv]

The React InstantSearch issue is solved now, thanks for holding on. The teams responsible are talking about how to add more migration guides etc., but in the mean time don't feel pressured to update if it's too complicated or unclear for you, v4 will continue to work for a long time (v3 even still works now).