fix(evaluator): handle numerical addition/subtraction from datetime (#316)

### Description

Adds support for add/subtract operations where the left operand is a datetime string and the right operand is a number. If a valid datetime string is passed the type is a string, while for any invalid datatime values the type is null. Based on this we return a `string-null` union.

This fixes the underlying issue reported in sanity-io/sanity#8255 where the generated type for the following query would not be correct:

```
(dateTime("2025-03-01T00:00:00Z") + 60) > dateTime("2024-03-01T00:00:00Z")
```

it now yields a `boolean-null` union, as is correct since an invalid dateTime string would result in `null` any comparison operation that includes a `null` operand evaluates to `null`.

https://linear.app/sanity/issue/CLDX-3609/groq-js-support-datetime-numerical-operations-in-type-evaluator

### What to review

The code

### Testing

Have tested the whole typegen flow in a local project with both a simple subtraction and a subtraction as part of a comparison operation. Also added a test for the case that failed before, with `dateTime(...) - number`.

Author: kbrabrand

src/typeEvaluator/functions.ts

@@ -4,7 +4,7 @@ import {optimizeUnions} from './optimizations'
 import type {Scope} from './scope'
 import {walk} from './typeEvaluate'
 import {createGeoJson, mapNode, nullUnion} from './typeHelpers'
-import type {NullTypeNode, TypeNode} from './types'
+import {STRING_TYPE_DATETIME, type NullTypeNode, type TypeNode} from './types'
 
 function unionWithoutNull(unionTypeNode: TypeNode): TypeNode {
   if (unionTypeNode.type === 'union') {
@@ -140,10 +140,10 @@ export function handleFuncCallNode(node: FuncCallNode, scope: Scope): TypeNode {
       })
     }
     case 'dateTime.now': {
-      return {type: 'string'}
+      return {type: 'string', [STRING_TYPE_DATETIME]: true}
     }
     case 'global.now': {
-      return {type: 'string'}
+      return {type: 'string', [STRING_TYPE_DATETIME]: true}
     }
     case 'global.defined': {
       const arg = walk({node: node.args[0], scope})
@@ -233,11 +233,12 @@ export function handleFuncCallNode(node: FuncCallNode, scope: Scope): TypeNode {
 
       return mapNode(arg, scope, (arg) => {
         if (arg.type === 'unknown') {
-          return nullUnion({type: 'string'})
+          return nullUnion({type: 'string', [STRING_TYPE_DATETIME]: true})
         }
 
         if (arg.type === 'string') {
-          return nullUnion({type: 'string'}) // we don't know wether the string is a valid date or not, so we return a [null, string]-union
+          // we don't know whether the string is a valid date or not, so we return a [null, string]-union
+          return nullUnion({type: 'string', [STRING_TYPE_DATETIME]: true})
         }
 
         return {type: 'null'} satisfies NullTypeNode

src/typeEvaluator/typeEvaluate.ts

@@ -33,20 +33,21 @@ import {match} from './matching'
 import {optimizeUnions} from './optimizations'
 import {Context, Scope} from './scope'
 import {isFuncCall, mapNode, nullUnion, resolveInline} from './typeHelpers'
-import type {
-  ArrayTypeNode,
-  BooleanTypeNode,
-  Document,
-  NullTypeNode,
-  NumberTypeNode,
-  ObjectAttribute,
-  ObjectTypeNode,
-  PrimitiveTypeNode,
-  Schema,
-  StringTypeNode,
-  TypeNode,
-  UnionTypeNode,
-  UnknownTypeNode,
+import {
+  STRING_TYPE_DATETIME,
+  type ArrayTypeNode,
+  type BooleanTypeNode,
+  type Document,
+  type NullTypeNode,
+  type NumberTypeNode,
+  type ObjectAttribute,
+  type ObjectTypeNode,
+  type PrimitiveTypeNode,
+  type Schema,
+  type StringTypeNode,
+  type TypeNode,
+  type UnionTypeNode,
+  type UnknownTypeNode,
 } from './types'
 
 const $trace = debug('typeEvaluator:evaluate:trace')
@@ -616,6 +617,10 @@ function handleOpCallNode(node: OpCallNode, scope: Scope): TypeNode {
                   : undefined,
             }
           }
+          // datetime + number -> datetime (datetimes are represented as strings with STRING_TYPE_DATETIME marker)
+          if (left.type === 'string' && left[STRING_TYPE_DATETIME] && right.type === 'number') {
+            return {type: 'string', [STRING_TYPE_DATETIME]: true}
+          }
 
           if (left.type === 'number' && right.type === 'number') {
             return {
@@ -647,6 +652,10 @@ function handleOpCallNode(node: OpCallNode, scope: Scope): TypeNode {
           if (left.type === 'unknown' || right.type === 'unknown') {
             return nullUnion({type: 'number'})
           }
+          // datetime - number -> datetime (datetimes are represented as strings with STRING_TYPE_DATETIME marker)
+          if (left.type === 'string' && left[STRING_TYPE_DATETIME] && right.type === 'number') {
+            return {type: 'string', [STRING_TYPE_DATETIME]: true}
+          }
           if (left.type === 'number' && right.type === 'number') {
             return {
               type: 'number',

src/typeEvaluator/types.ts

@@ -21,12 +21,17 @@ export interface TypeDeclaration {
 /** A schema consisting of a list of Document or TypeDeclaration items, allowing for complex type definitions. */
 export type Schema = (Document | TypeDeclaration)[]
 
+/** Symbol to mark a string type as a datetime */
+export const STRING_TYPE_DATETIME = Symbol('groq-js.type.string_datetime')
+
 /** Describes a type node for string values, optionally including a value. If a value is provided it will always be the given string value. */
 export interface StringTypeNode {
   /** can be used to identify the type of the node, in this case it's always 'string' */
   type: 'string'
   /** an optional value of the string, if provided it will always be the given string value */
   value?: string
+  /** marks this string as a datetime type for arithmetic operations */
+  [STRING_TYPE_DATETIME]?: true
 }
 
 /** Describes a type node for number values, optionally including a value. If a value is provided it will always be the given numeric value.*/

test/typeEvaluate.test.ts

@@ -3735,6 +3735,17 @@ t.test('splatting array', (t) => {
   t.end()
 })
 
+t.test('dateTime with numerical operation', (t) => {
+  const query = `(global::dateTime("2025-03-01T00:00:00Z") + 60) > global::dateTime("2024-03-01T00:00:00Z")`
+  const ast = parse(query)
+  const res = typeEvaluate(ast, schemas)
+  t.same(res, {
+    type: 'union',
+    of: [{type: 'boolean', value: undefined}, {type: 'null'}],
+  })
+  t.end()
+})
+
 function findSchemaType(name: string): TypeNode {
   const type = schemas.find((s) => s.name === name)
   if (!type) {