Consider: Rename .grab to .select

[gksander]

.grab as a method name is a bit odd, and is an artifact of the early experimental phases of the project. I'd like to phase that out by:

• introducing a .select method that shadows .grab.
• update documentation to use .select instead of .grab
• add a console warning to .grab calls, pointing the user to .select
• in the future, fully deprecate .grab and remove it from the codebase.

Also consider overloading this function and join grabOne's functionally with it.

[nonphoto]

grabOne might be called property or prop (as in lodash), if you're looking for suggestions. I think it makes sense to keep it as it's own function so it's clear what its doing at a glance.

[littlemilkstudio]

Is this still open for discussion? or are things pretty settled? with the .select method existing here now based off of sanity's select() method it makes this a little more complex to reason about.

I guess there are some discrepancies in naming that we could unify if we want to. If we wanted to go more off of a GROQ convention, we could do .grab() -> .project() & leave .select() as is. Or we could choose to deviate from GROQ based naming conventions and rename .select() -> .conditional().

I guess another interesting api feature to help reason about things would be spread/merge, which would be nice to adopt here in the near future

Personally, I think it might be nice to base naming as closely to one api source as possible. Whether that be GROQ, Zod or whatever else.

Coming into the library, I found it helpful when methods were named more closely resembling their GROQ counter parts to make it easier to reason about the underlying GROQ query that's being built and referencing any relevant GROQ documentation. That being said, I agree that .project() sounds a little funky, and maybe it's fine that .grab() is our only deviation from GROQ naming conventions because of that 🤷