Adding option to provide a custom dereference function

[dios-david]

Adding an optional dereference function to evaluate options as discussed in #93

Some things I was wondering while working on this:

• Technically speaking we could return a document in this function which does not exist in the dataset at all. Is this something to address?
• Shall the dereference function receive the dataset (original or after fromJS transformation) as a second parameter, so it can be used when doing the lookup?
• We agreed to use PromiseLike<Document | null> as return value, but having this function as async isn't necessary needed. Shall we add support for sync return value as well?

[judofyr]

Looks good to me! Some notes:

• There could be value in having access to all the properties of the reference (e.g. if it's a weak reference), but we can safely add that later when needed.
• groq-js doesn't actually have a concept that _id (well, except that it's used for dereferencing) and _type are special so the Document is maybe a bit tangential. However I don't see much harm in it either.

[dios-david]

There could be value in having access to all the properties of the reference

This was my initial approach but then I saw that the current implementation does not have a concept of weak references, so I did not want to introduce that with these changes - as I would need to do some research before doing that.

groq-js doesn't actually have a concept that _id (well, except that it's used for dereferencing) and _type are special

Yeah well technically groq would work well if none of the documents have _id or _type. However, as _id is part of the spec and is actually used in the codebase (for dereferencing), I thought we should make that explicit in the types as well, other than using Record<string, unknown> everywhere.
_type is a bit different, but it's widely used in the portable text related functions so I thought it would be useful to make part of this type as well. Afaik _type can be basically present in all the nested objects, while _id could be only on the root-level of the document.
Another interesting thing is the reference object {_ref: string, weak?: boolean} which is not typed at all, but used in the code already (well, at least the _ref field).
I think having these things typed would help collaborators and new people to understand the codebase a bit easier, and would help anyone while working on this in general.

Anyway, thanks for the feedback!

[judofyr]

Hm, the tests appear to fail? Not fully sure why?

[dios-david]

It should be fine now 🤞 some the new types needed to be exported from the entrypoint. Also I found another warning (unnecessary import of t in testUtils.ts), I fixed that as well.

[stipsan]

Completely missed this, which is a shame because it looks like such a high value fix so I'll merge and release this right away if tests are passing 🙌
Thanks so much for your contributions @dios-david 💖

[github-actions]

🎉 This PR is included in version 1.2.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[stipsan]

@dios-david we've implemented this in @sanity/groq-store: sanity-io/groq-store@acd526a#diff-0156d1ba41b6a2c582b33d4780aa1857b3dfea7075f16f51a49922cc97ccda59