feat: add meta as argument for key filter

[huozhi]

If the keys are non string, using filter will need to serialize the original keys to string, and do regext matching or string compare, adding a new argument meta for it, including serializedKey: string property for the filter to let user easily match the key

keyFilter(key: Key, meta: { serializedKey: string })

So that you can match the original key, or use regext to match the meta.serializedKey

mutate((key) => Array.isArray(key) && key[0].startsWith('/api'))
mutate((_key, meta) => /\/api/.test(meta.serializedKey))

In the future we can extend the meta with more info to match the keys more flexibily

[codesandbox-ci]

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 9d6086a:

Sandbox	Source
SWR-Basic	Configuration
SWR-States	Configuration
SWR-Infinite	Configuration
SWR-SSR	Configuration

[shuding]

My 2 cents: let's keep this on hold (I'm sorry!). The serialization process (under the hood called "stable hash") actually doesn't guarantee the result. That's also why we still expose it as unstable_serialize.

So I'm wondering if matching the hashed string is a good idea. Your example is actually the case: key[0].startsWith('/api') can't be expressed as /\/api/.test(meta.serializedKey). It's apparently wrong for keys like ['hey', '/api']. OK then naturally you start to think about how to match the serialized string with a regex confidentiality? It turns out that you can't because you don't know how it was hashed.

Some more examples:

useSWR({ id: 'foo' })
// ' will become " after serialization

useSWR(['/api/1', opts])
// opts might have any arbitrary content inside

How do you match these using the serialized key? The only conclusion I had is to never match serialized keys but match the original key, although it's more complicated.

[huozhi]

Make sense, let's close it for now! And encourage users to use the accurate matching or compare when mutate multiple keys while multiple shapes of keys existing.
cc @koba04 Maybe we could add this case to docs v2?

Encouraged ✔️

// matching array key
mutate((key) => key[0].startsWith('/api'), data)
// matching string key
mutate((key) => typeof key === 'string' && key.startsWith('/api'), data)

Discouraged ❌

// mutate all when key's type is unsure (array or string)
mutate((key: any) => /\/api/.test(key.toString()))

[koba04]

@huozhi
Yeah, that's great 👍 Let's add it to the v2 docs.
Should we check if the key is an array in the encouraged pattern?

- mutate((key) => key[0].startsWith('/api'), data)
+ mutate((key) => Array.isArray(key) && key[0].startsWith('/api'), data)

[huozhi]

@koba04 Yeah but only if you're using array key. The first 2 cases I posted are both the ways to go