React-instantsearch: Better API for <Configure />

[oyeanuj]

Do you want to request a feature or report a bug?
Feature

Feature: What is your use case for such a feature?
Using filters, facets in search.

Feature: What is your proposed API entry? The new option to add? What is the behavior?
The recommendation if needing to specify filters, or other configuration options is to use <Configure /> option. But it seems that <Configure /> just passes the parameters along.

Now when I was using it, it took me a fair bit of searching and guessing to ensure that I was formatting and passing the filters properly without any feedback from the component. (For eg, if I need to pass a single filter, it is unclear from the main docs how that translates to JSX prop - just a string, an array but as a string or an array with a single string.

So, I am wondering how you all feel about having a <Configure /> component which validates props and provides shapes to help debug and validate the parameters. And if debug=true is set, then it can validate the formatting of the filters, facets, scoring etc.

And if we go a step forward, a developer should mention what they want to filter on, and it should be the job of the <Configure /> component to construct the parameter format for the Algolia Search API.

<Configure 
  debug
  filterOn = [{ attribute: 'speed', value: 'snail' }]
  // similar things for facets, scoring etc....
/>

I feel like this would make the debugging and development experience when configuring queries a ton easier, and this sort of API would arguably be more of a React way?

Thoughts?

[Haroenv]

In most cases you'll be able to express it as a virtual refinementlist or a virtual menu, which is a lot more "react" than using configure: https://community.algolia.com/react-instantsearch/guide/Virtual_widgets.html

[Haroenv]

Proptype checking seems like a good idea, but then it means that we'll always need to update it on new functionalities of the API, which will be quite annoying for advanced usage (and usage in our dashboard) unless we add a final "catch-all" prop which can have any shape and would be merged with the others.

[oyeanuj]

@Haroenv

In most cases you'll be able to express it as a virtual refinementlist or a virtual menu, which is a lot more "react" than using configure: community.algolia.com/react-instantsearch/guide/Virtual_widgets.html

Unfortunately, this works well for those who can use widgets or have a design which accomodates the filtering. While that is probably the majority, it doesn't cover all the cases - especially when someone might need to use default facets, filters, scoring, or other configuration parameter.

Proptype checking seems like a good idea, but then it means that we'll always need to update it on new functionalities of the API, which will be quite annoying for advanced usage (and usage in our dashboard) unless we add a final "catch-all" prop which can have any shape and would be merged with the others.

Totally understand that, and I think that would be a viable solution. If anything, updating it with the new functionalities of the API could be a nice way to let the community know about the new possibilities 😄

[Haroenv]

I'm not sure if you completely understood my suggestion, virtual widgets are widgets which aren't displayed, but are acting as if it's a widget, or you can also just use the connector usually. Which filter are you trying to write? Configure really should be for simple settings or a last resort type of thing 😄

[oyeanuj]

Hm.. maybe I am not getting it. So, I have something like this right now:

<InstantSearch {..apiCredentials} >
    <Configure
      facetFilters = {[
        "category:-plant",
        "category:-animal",
        "category:-robot",
        "category:-humans",
      ]}  
    />
   <MyCustomAutoSuggest {..magic} />
/>

How would this be translated to the Virtual Menu?

[vvo]

@oyeanuj We don't do any type checking on the actual advanced filters of the API.

If your usecase is to preselect values from menus (without showing them) you can use this: https://community.algolia.com/react-instantsearch/guide/Default_refinements.html

If your usecase is to pass down some advanced filters like: "category:-plant AND category:-animal", you should use the basic filtering functionnality: https://www.algolia.com/doc/guides/searching/filtering/#basic-filtering

And use it like that:

    <Configure
      filter="category:-plant AND category:-animal"  
    />

Configure accepts any parameter from the rest api: https://www.algolia.com/doc/rest-api/search/#search-parameters

As you can see they are A LOT of them, so we rely on this and errors from the API rather than bundling typings on the search API in every language and frameworks.

Still, what you are saying is that you have used some tutorial that led you use Configure, then you used some bad forms of parameters (which ones?) and did not get any feedback from the library? At least there should have been an error in the console, if not let us know.

[oyeanuj]

@vvo Yes, I am using the Configure method like you mentioned above. And I didn't see any errors in the console either that the filter parameter was not formatted properly. Hence, the ask for an API that did some type/format checking. Though I do sympathize with the ask given the sheer number of parameters, I think it would help with making apps more robust :)

[Haroenv]

Maybe it can be stripped out in production

[vvo]

@oyeanuj To sum up this issue: errors from the API are not bubbling to the developer. Can you give us the exact parameters you tried to send via Configure? Thanks

[oyeanuj]

@vvo Sure, here are a couple of examples which are invalid but are processed:

<Configure
    facetFilters = "[type:-plant AND type:-animal]"
/>

<Configure
    facetFilters = "type:-plant AND type:-animal"
/>

[samouss]

Thanks for the sample! We should add some PropTypes on Configure for provide a feedback when the parameters are not considered as errors by the API. For example, facetFilters can be type as:

facetFilters: PropTypes.arrayOf(PropTypes.string)

We can do it for the most used parameters, filters, facetFilters, hitsPerPage, any other parameters which you might think. WDYT? @vvo @Haroenv

[Haroenv]

I agree, proptypes are simply warnings, but they should be turned off in production. It should always still be possible to use values not defined by the library

[vvo]

Can we create a single SearchParameters type that would be then generated and published for:

• proptypes
• flow
• typescript

So that we can just import that from in our various libraries? The challenge on typings search parameters from the API is avoiding duplication.

[Haroenv]

I have them partially typed in v4 of the api client, but planning to add it fully before release.

https://github.com/algolia/algoliasearch-client-javascript/blob/feat/v4-for-real-now/packages/algoliasearch/src/types.js#L90-L99

In definitelyTyped, it seems to be mostly correct, but I'm planning to move the typescript definition _into_ the definition.

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/algoliasearch/index.d.ts#L1620-L1928

It's still a hard question as to how to provide flow/typescript/propTypes without typing it three/two times