breaking: make urql atoms behave as close to urql-react bindings as possible

[RIP21]

Changelog:

• Changed APIs to be as close as possible to the urql official bindings.
• Mutations now are bound to only 1 query and will not suspend while fetching. Same way useMutation works in official bindings. Otherwise, it's quite unusable IMO. (covered by unit and playwright tests)
• Queries/Subscriptions no matter status or data (or suspend: true in client, will always suspend (I consider removing the data atom altogether as harmful API) (queries covered by tests, subscriptions are identical, so they aren't)
• Introduced Playwright tests as a more reliable and realistic testing technique. Especially in the case of suspense
• Unit tests that I kept are now using vitest. To avoid Typescript type-checking standing in a way of iterating on tests. The type-checking is still in place as a separate step. This also makes it so we don't type-check twice.
• Added testing-app that is used for playwright testing. It's not working without request mocking by the playwright on its own.

Why?

Current bindings are extremely far from being correct. I don't know how widely it's used and if used in production. There is no way to reexecute queries (there is no such way as refetching in URQL, only reexecute of operation with different context), the current refreshonly refreshes if the original context has requestPolicy being network-only or cache-and-network which is not how it suppose to be. It is also quite laggy causing hundreds of requests for some weird reason. These changes fix it all. Since they're using all the @urql/core APIs as correctly as I managed to understand (by looking through multiple exchanges, original react bindings source code, etc.), it works perfectly in tandem with original react bindings of URQL or independently. Cache and everything get reused, refreshed, etc. no matter what binding causes changes Jotai or URQL.

Two things that I didn't managed to align with URQL official binding.

• in case of reexecute with networkPolicy: "network-only"operation result (status) atom is not reporting { stale: true }. It just jumps directly to a new result. My debugging of source with subscribe and logging (or observable after conversion with toObserver), showed, that source actually emits it, but it's not coming to the component that uses that atom. Using requestPolicy: "cache-and-network" for refetch causes the reporting of { stale: true } while refetching. In URQL official binding behavior is exactly the same for both requestPolicies while reexecuting.
• In case of error and redirect to an error boundary. If refetch (retry) is triggered from the error boundary. URQL official bindings will suspend the tree while fetching showing loader fallback. In the case of Jotai binding it immediately shows the errored component causing it to error again due to if(opResult.error) throw opResult.error in it, making it returning back to ErrorBoundary instantly in the loop unless guarded with if(opResult.error && opResult.stale) return null which is suboptimal, as Suspense fallback is preferable.

I need help from @dai-shi to figure out how to suspend it during that recovery refetch (@kitten may hint smth) and, also, possibly, from both of you, to figure out why stale status is not getting reported even though the source reports that to the subscriber. It's important to notice, that suspense:true/false on urql client doesn't change either of these behaviors. Also, @kitten, will be glad if you will review refetching and other logic related to urql, as I feel that some of it is a bit redundant.

@dai-shi If merged I'll gladly update docs with a migration guide and examples.

Closes: #10

[codesandbox-ci[bot]]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit c39c426f4ccf8530699fbd146a38214f85ddedaf:

Sandbox	Source
React	Configuration
React Typescript	Configuration

[dai-shi]

Wow, your work looks great. We have been looking for a maintainer for jotai-urql and you should be the one.

[RIP21]

So @dai-shi yesterday I added an API that uses suspenseAtom that will allow users to rehydrate atoms with suspense false that will add an initialValue/Data into the atomWithObserver that effectively disables suspense for such users.

Also, I went ahead and removed the data atom. Also, I removed Action altogether. My logic behind it is that changes are already breaking enough, so trying to keep some backward compatibility is rather makes no sense at this point.

I also changed the API of all the atoms not to be multiple arguments, but a single object argument with multiple fields as it's easier to extend.

One thing I would wish to ship one day is getPause option that will allow for pausing of the query the same way as urql original client does. But I think it's rather a nice addition than what's absolutely needed now so I would postpone that to the next work.

[RIP21]

So @dai-shi I've added getPause functionality that is almost 1:1 to URQL bindings (slightly different as it's impossible to trigger the fetch while paused, yet possible to work around by unpausing the query, which is IMO more expected behavior)

I also improved typings with some powerful generic types so now only needed and required types are allowed. I also added tests and type-tests for all these things.

I think it's ready to be shipped. Please, review, comment, and merge if you can. Commit history is pretty clean, so up to you if it makes sense to squash it.

Let me know where I can contribute to the docs. Also, I'll be happy with some sort of contributor role, so I can trigger workflows and whatnot. Thanks!

[RIP21]

@dai-shi I need a bit of help from you.

For some reason when I make getVariables to be async function. And it makes all the atoms async as we want to await for them it in source atom to then chain all the way to the last one public to the user. But for some reason it starts to fail with r is not a function. Any clues?

I would want to ship this version and make it as a sepearted PR, so it's a bit clearer what I'm talking about, but if you can help in this one, then I'll be super happy to ship it with the support for async getVariables.

[dai-shi]

Also, I'll be happy with some sort of contributor role

Sent an invitation!

[dai-shi]

For some reason when I make getVariables to be async function. And it makes all the atoms async as we want to await for them it in source atom to then chain all the way to the last one public to the user. But for some reason it starts to fail with r is not a function. Any clues?

Hmm, no. We need to know what is r by disabling minification. (we should disable minification anyways. https://github.com/dai-shi/proxy-memoize/pull/66 )

I would want to ship this version and make it as a sepearted PR, so it's a bit clearer what I'm talking about, but if you can help in this one, then I'll be super happy to ship it with the support for async getVariables.

I don't think we could/should support async getVariables. In jotai-tanstack-query, we made a new wrapper function for async. Issue: https://github.com/jotaijs/jotai-tanstack-query/issues/21 PR: https://github.com/jotaijs/jotai-tanstack-query/pull/30

[RIP21]

Thanks for comments. Will address most. Will make separate workflow etc. Will look into tanstack query thingy you mentioned.

[RIP21]

So, I fixed:

• jotai-urql in the example
• gave up on support of async variables, so we can ship it
• fixed ci/cd (it makes no sense to make a playwright a separate workflow as it runs the entire suite in 2 seconds on CI)
• fixed eslint stuff (removed default config and fixed alias)

[dai-shi]

Cool. Let me go the second iteration with fresh eyes.

[RIP21]

@dai-shi updated everything as requested. Also added some comments here and there to clear things up. Also figured I don't need sourceAtom so inlined it into result atom.

[dai-shi]

@RIP21 Sounds good. Would you like to merge and release a minor bump? Or, do you want me to work on it this time?

[RIP21]

@dai-shi unsure if it's a minor bump :) As APIs and other stuff got changed completely and is pretty breaking. So it's your call whether it's a minor bump or not. But for me, it sounds like a major bump :)

And yeah, if you can, please release it. As I don't have time now to figure out how it all (publishing in this project) works :)

[dai-shi]

@RIP21

This hasn't reached v1 yet. We add breaking changes in v0.x.

I'll merge it and make v0.7.0 release. Just adding a tag should trigger the CD workflow.

[RIP21]

Gotcha. Ok then. Thanks :) I would need to update the docs for URQL Jotai.

Also, Jotai docs seem to be outdated and are still more about v1 than v2. Any plans to update that?

[dai-shi]

I would need to update the docs for URQL Jotai.

Thanks. Please open a PR there.

Also, Jotai docs seem to be outdated and are still more about v1 than v2. Any plans to update that?

We look for contributors. I think I updated at least, but there should be more fixes and improvements. You are more than welcome to help on it.

[dai-shi]

Published: https://www.npmjs.com/package/jotai-urql/v/0.7.0

(There were some errors of mine in cd.yml which is fixed in the main branch.)

[sandhose]

Just a heads-up that the published v0.7.0 has the typescript types in the wrong directory. They are in dist/src/src/index.d.ts, while the package.json references dist/src/index.d.ts

[dai-shi]

(Ahh, we don't have tests to cover that.)

@sandhose Do you know how to fix? dist/src/index.d.ts should be something we want.

[dai-shi]

Or, maybe we can fix package.json with dist/src/src/index.d.ts for now if it's easier.

[sandhose]

@dai-shi I think I managed to fix it in #12