fix(types): returns type casting

- Allow to use returns at the end of the call chain after a .single()
- Add deprecation warning to move toward explicit overrideTypes method
- Add cast checking basic logic, an array should be declared if the result is an array, an object if the result is an object

Author: avallete

src/PostgrestBuilder.ts

@@ -1,7 +1,12 @@
 // @ts-ignore
 import nodeFetch from '@supabase/node-fetch'
 
-import type { Fetch, PostgrestSingleResponse, PostgrestResponseSuccess } from './types'
+import type {
+  Fetch,
+  PostgrestSingleResponse,
+  PostgrestResponseSuccess,
+  CheckMatchingArrayTypes,
+} from './types'
 import PostgrestError from './PostgrestError'
 
 export default abstract class PostgrestBuilder<Result, ThrowOnError extends boolean = false>
@@ -209,4 +214,17 @@ export default abstract class PostgrestBuilder<Result, ThrowOnError extends bool
 
     return res.then(onfulfilled, onrejected)
   }
+
+  /**
+   * Override the type of the returned `data`.
+   *
+   * @typeParam NewResult - The new result type to override with
+   * @deprecated Use overrideTypes<yourType, { partial: false }>() method at the end of your call chain instead
+   */
+  returns<NewResult>(): PostgrestBuilder<CheckMatchingArrayTypes<Result, NewResult>, ThrowOnError> {
+    return this as unknown as PostgrestBuilder<
+      CheckMatchingArrayTypes<Result, NewResult>,
+      ThrowOnError
+    >
+  }
 }

src/PostgrestTransformBuilder.ts

@@ -1,6 +1,6 @@
 import PostgrestBuilder from './PostgrestBuilder'
 import { GetResult } from './select-query-parser/result'
-import { GenericSchema } from './types'
+import { GenericSchema, CheckMatchingArrayTypes } from './types'
 
 export default class PostgrestTransformBuilder<
   Schema extends GenericSchema,
@@ -307,18 +307,19 @@ export default class PostgrestTransformBuilder<
    * Override the type of the returned `data`.
    *
    * @typeParam NewResult - The new result type to override with
+   * @deprecated Use overrideTypes<yourType, { partial: false }>() method at the end of your call chain instead
    */
   returns<NewResult>(): PostgrestTransformBuilder<
     Schema,
     Row,
-    NewResult,
+    CheckMatchingArrayTypes<Result, NewResult>,
     RelationName,
     Relationships
   > {
     return this as unknown as PostgrestTransformBuilder<
       Schema,
       Row,
-      NewResult,
+      CheckMatchingArrayTypes<Result, NewResult>,
       RelationName,
       Relationships
     >

src/types.ts

@@ -1,4 +1,5 @@
 import PostgrestError from './PostgrestError'
+import { SelectQueryError } from './select-query-parser/utils'
 
 export type Fetch = typeof fetch
 
@@ -89,3 +90,24 @@ type ConditionalSimplifyDeep<
 type NonRecursiveType = BuiltIns | Function | (new (...arguments_: any[]) => unknown)
 type BuiltIns = Primitive | void | Date | RegExp
 type Primitive = null | undefined | string | number | boolean | symbol | bigint
+
+/**
+ * Utility type to check if array types match between Result and NewResult.
+ * Returns either the valid NewResult type or an error message type.
+ */
+export type CheckMatchingArrayTypes<Result, NewResult> =
+  // If the result is a QueryError we allow the user to override anyway
+  Result extends SelectQueryError<string>
+    ? NewResult
+    : // Otherwise, we check basic type matching (array should be override by array, object by object)
+    Result extends any[]
+    ? NewResult extends any[]
+      ? NewResult // Both are arrays - valid
+      : {
+          Error: 'Type mismatch: Cannot cast array result to a single object. Use .returns<Array<YourType>> for array results or .single() to convert the result to a single object'
+        }
+    : NewResult extends any[]
+    ? {
+        Error: 'Type mismatch: Cannot cast single object to array type. Remove Array wrapper from return type or make sure you are not using .single() up in the calling chain'
+      }
+    : NewResult // Neither are arrays - valid

test/returns.test-d.ts

@@ -0,0 +1,117 @@
+import { expectType } from 'tsd'
+import { PostgrestBuilder, PostgrestClient } from '../src/index'
+import { Database } from './types'
+import { TypeEqual } from 'ts-expect'
+
+const REST_URL = 'http://localhost:3000'
+const postgrest = new PostgrestClient<Database>(REST_URL)
+
+// Test returns() with different end methods
+{
+  // Test with single()
+  const singleResult = await postgrest
+    .from('users')
+    .select()
+    .single()
+    .returns<{ username: string }>()
+  if (singleResult.error) {
+    throw new Error(singleResult.error.message)
+  }
+  let result: typeof singleResult.data
+  let expected: { username: string }
+  expectType<TypeEqual<typeof result, typeof expected>>(true)
+
+  // Test with maybeSingle()
+  const maybeSingleResult = await postgrest
+    .from('users')
+    .select()
+    .maybeSingle()
+    .returns<{ username: string }>()
+  if (maybeSingleResult.error) {
+    throw new Error(maybeSingleResult.error.message)
+  }
+  let maybeSingleResultType: typeof maybeSingleResult.data
+  let maybeSingleExpected: { username: string }
+  expectType<TypeEqual<typeof maybeSingleResultType, typeof maybeSingleExpected>>(true)
+
+  // Test array to non-array type casting error
+  const invalidCastArray = (await postgrest.from('users').select().returns<{ username: string }>())
+    .data
+  expectType<typeof invalidCastArray>({
+    Error:
+      'Type mismatch: Cannot cast array result to a single object. Use .returns<Array<YourType>> for array results or .single() to convert the result to a single object',
+  })
+
+  // Test non-array to array type casting error
+  const invalidCastSingle = postgrest
+    .from('users')
+    .select()
+    .single()
+    .returns<{ username: string }[]>()
+  expectType<
+    PostgrestBuilder<
+      {
+        Error: 'Type mismatch: Cannot cast single object to array type. Remove Array wrapper from return type or make sure you are not using .single() up in the calling chain'
+      },
+      false
+    >
+  >(invalidCastSingle)
+
+  // Test with csv()
+  const csvResult = await postgrest.from('users').select().csv().returns<string>()
+  if (csvResult.error) {
+    throw new Error(csvResult.error.message)
+  }
+  let csvResultType: typeof csvResult.data
+  let csvExpected: string
+  expectType<TypeEqual<typeof csvResultType, typeof csvExpected>>(true)
+
+  // Test with throwOnError()
+  const throwResult = await postgrest
+    .from('users')
+    .select()
+    .returns<{ username: string }[]>()
+    .throwOnError()
+  let throwResultType: typeof throwResult.data
+  let throwExpected: { username: string }[]
+  expectType<TypeEqual<typeof throwResultType, typeof throwExpected>>(true)
+  let throwErrorType: typeof throwResult.error
+  let throwErrorExpected: null
+  expectType<TypeEqual<typeof throwErrorType, typeof throwErrorExpected>>(true)
+}
+
+// Test returns() with nested selects and relationships
+{
+  const result = await postgrest
+    .from('users')
+    .select('username, messages(id, content)')
+    .single()
+    .returns<{
+      username: string
+      messages: { id: number; content: string }[]
+    }>()
+  if (result.error) {
+    throw new Error(result.error.message)
+  }
+  let resultType: typeof result.data
+  let expected: {
+    username: string
+    messages: { id: number; content: string }[]
+  }
+  expectType<TypeEqual<typeof resultType, typeof expected>>(true)
+}
+
+// Test returns() with JSON operations
+{
+  const result = await postgrest
+    .from('users')
+    .select('data->settings')
+    .single()
+    .returns<{ settings: { theme: 'light' | 'dark' } }>()
+  if (result.error) {
+    throw new Error(result.error.message)
+  }
+  let resultType: typeof result.data
+  let expected: { settings: { theme: 'light' | 'dark' } }
+  expectType<TypeEqual<typeof resultType, typeof expected>>(true)
+}