Support for relaxed types (#10)

Author: daniel-chambers

CHANGELOG.md

@@ -4,6 +4,8 @@ This changelog documents the changes between release versions.
 ## main
 Changes to be included in the next upcoming release
 
+* Support for "relaxed types" ([#10](https://github.com/hasura/ndc-nodejs-lambda/pull/10))
+
 ## v0.13.0
 - Add support for treating 'true | false' as a Boolean type ([#7](https://github.com/hasura/ndc-nodejs-lambda/pull/7))
 

README.md

@@ -147,6 +147,41 @@ These types are unsupported as function parameter types or return types for func
 * [`void`](https://www.typescriptlang.org/docs/handbook/2/functions.html#void), [`object`](https://www.typescriptlang.org/docs/handbook/2/functions.html#object), [`unknown`](https://www.typescriptlang.org/docs/handbook/2/functions.html#unknown), [`never`](https://www.typescriptlang.org/docs/handbook/2/functions.html#never), [`any`](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any) types - to accept and return arbitrary JSON, use `sdk.JSONValue` instead
 * `null` and `undefined` - unless used in a union with a single other type
 
+### Relaxed Types
+"Relaxed types" are types that are otherwise unsupported, but instead of being rejected are instead converted into opaque custom scalar types. These scalar types are entirely unvalidated when used as input (ie. the caller of the function can send arbitrary JSON values), making it incumbent on the function itself to ensure the incoming value for that relaxed type actually matches its type. Because relaxed types are represented as custom scalar types, in GraphQL you will be unable to select into the type, if it is an object, and will only be able to select the whole thing.
+
+Relaxed types are designed to be an escape hatch to help people get up and running using existing code quickly, where their existing code uses types that are unsupported. They are **not intended to be used long term**. You should prefer to modify your code to use only supported types. To opt into using relaxed types, one must apply the `@allowrelaxedtypes` JSDoc tag to the function that will be using the unsupported types.
+
+The following unsupported types are allowed when using relaxed types, and will be converted into opaque unvalidated scalar types:
+
+* Union types
+* Tuple types
+* Types with index signatures
+* The `any` and `unknown` types
+
+Here's an example of a function that uses some relaxed types:
+
+```typescript
+/**
+ * @allowrelaxedtypes
+ * @readonly
+ */
+export function findEmptyRecords(record: Record<string, string>): { emptyKeys: string[] } | string {
+  const emptyKeys: string[] = [];
+  const entries = Object.entries(record);
+
+  if (entries.length === 0)
+    return "Error: record was empty";
+
+  for (const [key, value] of entries) {
+    if (value === "")
+      emptyKeys.push(key);
+  }
+
+  return { emptyKeys };
+}
+```
+
 ### Error handling
 By default, unhandled errors thrown from functions are caught by the Lambda SDK host, and an `InternalServerError` is returned to Hasura. The details of the uncaught error (the message and stack trace) is captured and will be logged in the OpenTelemetry trace associated with the GraphQL request. However, the GraphQL API caller will receive a generic "internal error" response to their query. This is to ensure internal error details are not leaked to GraphQL API clients.
 

ndc-lambda-sdk/src/connector.ts

@@ -1,7 +1,7 @@
 import * as sdk from "@hasura/ndc-sdk-typescript";
 import { JSONSchemaObject } from "@json-schema-tools/meta-schema";
 import path from "node:path"
-import { FunctionsSchema, getNdcSchema } from "./schema";
+import { FunctionsSchema, getNdcSchema, printRelaxedTypesWarning } from "./schema";
 import { deriveSchema, printCompilerDiagnostics, printFunctionIssues } from "./inference";
 import { RuntimeFunctions, executeMutation, executeQuery } from "./execution";
 
@@ -45,6 +45,7 @@ export function createConnector(options: ConnectorOptions): sdk.Connector<RawCon
       const schemaResults = deriveSchema(functionsFilePath);
       printCompilerDiagnostics(schemaResults.compilerDiagnostics);
       printFunctionIssues(schemaResults.functionIssues);
+      printRelaxedTypesWarning(schemaResults.functionsSchema);
       return {
         functionsSchema: schemaResults.functionsSchema
       }

ndc-lambda-sdk/src/execution.ts

@@ -107,7 +107,7 @@ export function prepareArguments(args: Record<string, unknown>, functionDefiniti
   return functionDefinition.arguments.map(argDef => coerceArgumentValue(args[argDef.argumentName], argDef.type, [argDef.argumentName], objectTypes));
 }
 
-function coerceArgumentValue(value: unknown, type: schema.TypeDefinition, valuePath: string[], objectTypeDefinitions: schema.ObjectTypeDefinitions): unknown {
+function coerceArgumentValue(value: unknown, type: schema.TypeReference, valuePath: string[], objectTypeDefinitions: schema.ObjectTypeDefinitions): unknown {
   switch (type.type) {
     case "array":
       if (!isArray(value))
@@ -128,7 +128,7 @@ function coerceArgumentValue(value: unknown, type: schema.TypeDefinition, valueP
       }
     case "named":
       if (type.kind === "scalar") {
-        if (schema.isBuiltInScalarTypeDefinition(type))
+        if (schema.isBuiltInScalarTypeReference(type))
           return convertBuiltInNdcJsonScalarToJsScalar(value, valuePath, type);
         // Scalars are currently treated as opaque values, which is a bit dodgy
         return value;
@@ -211,7 +211,7 @@ function buildCausalStackTrace(error: Error): string {
   return stackTrace;
 }
 
-export function reshapeResultToNdcResponseValue(value: unknown, type: schema.TypeDefinition, valuePath: string[], fields: Record<string, sdk.Field> | "AllColumns", objectTypes: schema.ObjectTypeDefinitions): unknown {
+export function reshapeResultToNdcResponseValue(value: unknown, type: schema.TypeReference, valuePath: string[], fields: Record<string, sdk.Field> | "AllColumns", objectTypes: schema.ObjectTypeDefinitions): unknown {
   switch (type.type) {
     case "array":
       if (isArray(value)) {
@@ -268,7 +268,7 @@ export function reshapeResultToNdcResponseValue(value: unknown, type: schema.Typ
   }
 }
 
-function convertBuiltInNdcJsonScalarToJsScalar(value: unknown, valuePath: string[], scalarType: schema.BuiltInScalarTypeDefinition): string | number | boolean | BigInt | Date | schema.JSONValue {
+function convertBuiltInNdcJsonScalarToJsScalar(value: unknown, valuePath: string[], scalarType: schema.BuiltInScalarTypeReference): string | number | boolean | BigInt | Date | schema.JSONValue {
   switch (scalarType.name) {
     case schema.BuiltInScalarTypeName.String:
       if (typeof value === "string") {