Groq custom functions support

[tstikvoort]

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

Feature Request

Recently, custom functions have been introduced to GROQ recently. With custom functions, you can achieve smaller queryies compared to when you use fragments. It would be great if this package has support for custom functions.

See also: https://www.sanity.io/docs/content-lake/custom-groq-functions

[scottrippey]

It's a great idea, and I'd love to support it. Would you like to propose an example syntax? Or maybe some examples of GROQ functions that you would implement?

[scottrippey]

For defining a function, here's my thoughts.

I took this example from the docs:

fn ex::name($person) = $person -> { 
  "name": firstName + " " + lastName,
  age,
};
*[_type == 'post']{
  "author": ex::name(author)
}

Here's a proposed way to achieve this:

type FirstLast = {
  firstName: string,
  lastName: string
};
const fullName = q.defineFunction("ex::name")
  .param<FirstLast>("$person")
  .deref().project(q => ({
    name: q.raw('firstName + " " + lastname', q.string()),
    age: z.number(),
  }))

const query = q
  .usingFunction(fullName)
  .star.filterByType("movie").project(q => ({
    actorName: q.function("ex::name", "actor"), 
  }))

Defining the function:

• The hardest part in this syntax is the .param<T>(name).deref() part, because it's so verbose. But I can't think of a better syntax.
• The docs say you can only do one of these 4: $param{}, $param->{}, $param[]{}, $param[]->{}, so we'd support that by allowing variations like .param("$param").filter().deref().project({}). This helps support additional features in the future, if they add them.

Calling the function:

• q.function(...) is something I've wanted to support for a while, to call built-in functions like geo::distance etc.
  • However, defining the signature for all Sanity's built-in functions could be cumbersome; maybe we leave it to user-land
• There's various alternatives to the syntax to consider:
  • q.function("geo::distance")("point1", "point2")
  • q.functions.geo.distance("point1", "point2")
  • q.function(geo.distance, "point1", "point2")
• With the proposed syntax, we're forced to "register" each custom function via q.usingFunction(...)
  • This doesn't scale well. There's no "unused function" detection. If you use a function in a fragment, you'll be forced to reference it in the top-level.
  • It would be nice to support an automatic registry, so if q.function(fullName) is called (even in a nested scenario, or a fragment) then it will be added to the top-level query

[tstikvoort]

I like your enthusiasm! Yeah this seem to work. Indeed automatic registry of functions would be very cool! Calling functions in functions though is not possible yet https://www.sanity.io/docs/content-lake/custom-groq-functions#k141377be76ec

For my understanding, you need that FirstLast type for the projection in the function? Then it should also contain the age in your example right?

Regarding calling the function, it would be ideal if

• you would only be able to call functions that exist, so ideally you do not write "ex:someFunction" twice, or at least should be type safe.
• the argument that you can pass into the function would also be checked against your schema types.

[scottrippey]

Yes, in the example above, FIrstLast is the "parameter type", and it would be type-checked to ensure you only passed valid values. The output type would be retained, as { name: string, age: number }.

Regarding calling the function: everything in the above examples could be fully type-safe. Eg. calling q.function("ex::name", "author") would only allow "known" function names, and it would know that ex::name requires 1 parameter with type FirstLast. This is all doable!

[scottrippey]

Honestly, my biggest hesitation is simply this:

How useful are custom GROQ functions to GroqD users?

I understand how useful this is for GROQ itself, because it can eliminate repetition in queries. However, that's not really a problem with GroqD. We already have first-class support for fragments, which covers a nearly-identical use-case, and obviously we can use TypeScript functions to eliminate repetition.

The only difference I can really see, is that functions could result in a smaller query, if you're making the same projection multiple times in a single query.
This is a very small optimization, so I'm having a hard time justifying the added complexity to support this. WDYT?