Handle GraphQL nulls from "optional" fields as undefined

GraphQL's / Nest's decorators have `nullable` option,
which means the value can be null or omitted.
Which naturally translates to null or undefined in JS.

We actually care about this distinction, though, especially on update mutations.
undefined means no change.
null means clear the value.

We carelessly allowed both meaningly that nulls could mistakenly be stored in lots of spots that are unexpected.
Granted, this only would happen in Neo4j, as Gel's schema checks would prevent this.

Going forward we have a new `optional` option as a sibling to `nullable`.
`optional` lets the field be omitted or undefined. GraphQL can still give us nulls, but be will we convert them to undefined.
`nullable` continues to let null & undefined through.

Author: CarsonF

src/common/id-field.ts

@@ -1,16 +1,20 @@
 import { applyDecorators } from '@nestjs/common';
-import { Field, FieldOptions, ID as IDType } from '@nestjs/graphql';
+import { ID as IDType } from '@nestjs/graphql';
 import { ValidationOptions } from 'class-validator';
 import { IsAny, IsNever, Tagged } from 'type-fest';
 import type { ResourceName, ResourceNameLike } from '~/core';
+import { OptionalField, OptionalFieldOptions } from './optional-field';
 import { IsId } from './validators';
 
 export const IdField = ({
   validation,
   ...options
-}: FieldOptions & { validation?: ValidationOptions } = {}) =>
+}: OptionalFieldOptions & { validation?: ValidationOptions } = {}) =>
   applyDecorators(
-    Field(() => IDType, options),
+    OptionalField(() => IDType, {
+      optional: false,
+      ...options,
+    }),
     IsId(validation),
   );
 

src/common/index.ts

@@ -27,6 +27,7 @@ export * from './lazy-ref';
 export * from './lazy-record';
 export { DateField, DateTimeField } from './luxon.graphql';
 export * from './map-or-else';
+export * from './optional-field';
 export * from './order.enum';
 export * from './pagination.input';
 export * from './pagination-list';

src/common/luxon.graphql.ts

@@ -1,9 +1,10 @@
 import { applyDecorators } from '@nestjs/common';
-import { CustomScalar, Field, FieldOptions, Scalar } from '@nestjs/graphql';
+import { CustomScalar, Scalar } from '@nestjs/graphql';
 import { stripIndent } from 'common-tags';
 import { Kind, ValueNode } from 'graphql';
 import { DateTime, Settings } from 'luxon';
 import { InputException } from './exceptions';
+import { OptionalField, OptionalFieldOptions } from './optional-field';
 import { CalendarDate } from './temporal';
 import { Transform } from './transform.decorator';
 import { ValidateBy } from './validators/validateBy';
@@ -24,9 +25,12 @@ const IsIsoDate = () =>
     },
   });
 
-export const DateTimeField = (options?: FieldOptions) =>
+export const DateTimeField = (options?: OptionalFieldOptions) =>
   applyDecorators(
-    Field(() => DateTime, options),
+    OptionalField(() => DateTime, {
+      optional: false,
+      ...options,
+    }),
     Transform(
       ({ value }) => {
         try {
@@ -43,9 +47,12 @@ export const DateTimeField = (options?: FieldOptions) =>
     IsIsoDate(),
   );
 
-export const DateField = (options?: FieldOptions) =>
+export const DateField = (options?: OptionalFieldOptions) =>
   applyDecorators(
-    Field(() => CalendarDate, options),
+    OptionalField(() => CalendarDate, {
+      optional: false,
+      ...options,
+    }),
     Transform(
       ({ value }) => {
         try {

src/common/name-field.ts

@@ -7,9 +7,24 @@ import { MinLength } from 'class-validator';
 import { DbSort } from './db-sort.decorator';
 import { Transform } from './transform.decorator';
 
-export const NameField = (options: FieldOptions = {}) =>
+type NameFieldParams = FieldOptions & {
+  /**
+   * If true, values can be omitted/undefined or null.
+   * This will override `optional` if truthy.
+   */
+  nullable?: true;
+  /**
+   * If true, values can be omitted/undefined but not null.
+   */
+  optional?: true;
+};
+
+export const NameField = (options: NameFieldParams = {}) =>
   applyDecorators(
-    InferredTypeOrStringField(options),
+    InferredTypeOrStringField({
+      ...options,
+      nullable: options.optional ?? options.nullable,
+    }),
     Transform(({ value }) => {
       if (value === undefined) {
         return undefined;
@@ -18,14 +33,16 @@ export const NameField = (options: FieldOptions = {}) =>
         // Treat null & empty strings as null
         return value?.trim() || null;
       }
+      if (options.optional && value === null) {
+        // Treat null as an omitted value
+        return undefined;
+      }
       // Null & empty string treated as MinLength validation error
       return value?.trim() ?? '';
     }),
     DbSort((value) => `apoc.text.clean(${value})`),
     // Using this instead of @IsNotEmpty, as this allows nulls.
-    MinLength(1, {
-      message: 'Cannot be empty',
-    }),
+    MinLength(1, { message: 'Cannot be empty' }),
   );
 
 /**

src/common/optional-field.ts

@@ -0,0 +1,48 @@
+import { applyDecorators } from '@nestjs/common';
+import { Field, FieldOptions } from '@nestjs/graphql';
+import { NullableList } from '@nestjs/graphql/dist/interfaces/base-type-options.interface';
+import { Transform } from 'class-transformer';
+
+export type OptionalFieldOptions = FieldOptions & {
+  /**
+   * If true, values can be omitted/undefined or null.
+   * This will override `optional` if truthy.
+   */
+  nullable?: boolean | NullableList;
+  /**
+   * If true, values can be omitted/undefined but not null.
+   */
+  optional?: boolean;
+  transform?: (value: any) => unknown;
+};
+
+/**
+ * A field that is optional/omissible/can be undefined.
+ * Whether it can be explicitly null is based on `nullable`.
+ */
+export function OptionalField(
+  typeFn: () => any,
+  options?: OptionalFieldOptions,
+): PropertyDecorator;
+export function OptionalField(
+  options?: OptionalFieldOptions,
+): PropertyDecorator;
+export function OptionalField(...args: any) {
+  const typeFn: (() => any) | undefined =
+    typeof args[0] === 'function' ? (args[0] as () => any) : undefined;
+  const options: OptionalFieldOptions | undefined =
+    typeof args[0] === 'function' ? args[1] : args[0];
+  const opts = {
+    ...options,
+    nullable: options?.nullable ?? options?.optional ?? true,
+  };
+  return applyDecorators(
+    typeFn ? Field(typeFn, opts) : Field(opts),
+    Transform(({ value }) => {
+      if (!options?.nullable && (options?.optional ?? true) && value == null) {
+        return undefined;
+      }
+      return options?.transform ? options.transform(value) : value;
+    }),
+  );
+}

src/common/rich-text.scalar.ts

@@ -1,5 +1,5 @@
 import { applyDecorators } from '@nestjs/common';
-import { Field, FieldOptions, ObjectType } from '@nestjs/graphql';
+import { ObjectType } from '@nestjs/graphql';
 import { setToStringTag } from '@seedcompany/common';
 import { markSkipClassTransformation } from '@seedcompany/nest';
 import { IsObject } from 'class-validator';
@@ -9,7 +9,7 @@ import { GraphQLJSONObject } from 'graphql-scalars';
 import { isEqual } from 'lodash';
 import { JsonObject } from 'type-fest';
 import { SecuredProperty } from '~/common/secured-property';
-import { Transform } from './transform.decorator';
+import { OptionalField, OptionalFieldOptions } from './optional-field';
 
 function hashId(name: string) {
   return createHash('shake256', { outputLength: 5 }).update(name).digest('hex');
@@ -76,11 +76,14 @@ export class RichTextDocument {
 setToStringTag(RichTextDocument, 'RichText');
 markSkipClassTransformation(RichTextDocument);
 
-export const RichTextField = (options?: FieldOptions) =>
+export const RichTextField = (options?: OptionalFieldOptions) =>
   applyDecorators(
-    Field(() => RichTextScalar, options),
-    IsObject(),
-    Transform(({ value }) => RichTextDocument.fromMaybe(value)),
+    OptionalField(() => RichTextScalar, {
+      optional: false,
+      ...options,
+      transform: RichTextDocument.fromMaybe,
+    }),
+    IsObject(), // TODO validate empty blocks becomes null becomes validation error
   );
 
 /** @internal */

src/common/sensitivity.enum.ts

@@ -1,10 +1,10 @@
 import { applyDecorators } from '@nestjs/common';
-import { Field, FieldOptions } from '@nestjs/graphql';
 import { EnumType, makeEnum } from '@seedcompany/nest';
 import { Transform } from 'class-transformer';
 import { uniq } from 'lodash';
 import { rankSens } from '~/core/database/query';
 import { DbSort } from './db-sort.decorator';
+import { OptionalField, OptionalFieldOptions } from './optional-field';
 
 export type Sensitivity = EnumType<typeof Sensitivity>;
 export const Sensitivity = makeEnum({
@@ -13,9 +13,12 @@ export const Sensitivity = makeEnum({
   exposeOrder: true,
 });
 
-export const SensitivityField = (options: FieldOptions = {}) =>
+export const SensitivityField = (options?: OptionalFieldOptions) =>
   applyDecorators(
-    Field(() => Sensitivity, options),
+    OptionalField(() => Sensitivity, {
+      optional: false,
+      ...options,
+    }),
     DbSort(rankSens),
   );
 

src/components/comments/dto/update-comment.dto.ts

@@ -7,7 +7,7 @@ export abstract class UpdateCommentInput {
   @IdField()
   readonly id: ID;
 
-  @RichTextField({ nullable: true })
+  @RichTextField({ optional: true })
   readonly body?: RichTextDocument;
 }
 

src/components/engagement/dto/update-engagement.dto.ts

@@ -7,6 +7,7 @@ import {
   DateField,
   ID,
   IdField,
+  OptionalField,
   RichTextDocument,
   RichTextField,
 } from '~/common';
@@ -40,7 +41,7 @@ export abstract class UpdateEngagement {
 
   readonly initialEndDate?: CalendarDate | null;
 
-  @Field(() => EngagementStatus, { nullable: true })
+  @OptionalField(() => EngagementStatus)
   readonly status?: EngagementStatus;
 
   @RichTextField({ nullable: true })
@@ -79,10 +80,10 @@ export abstract class UpdateLanguageEngagement extends UpdateEngagement {
   @Field(() => String, { nullable: true })
   readonly historicGoal?: string | null;
 
-  @Field(() => LanguageMilestone, { nullable: true })
+  @OptionalField(() => LanguageMilestone)
   readonly milestoneReached?: LanguageMilestone;
 
-  @Field(() => AIAssistedTranslation, { nullable: true })
+  @OptionalField(() => AIAssistedTranslation)
   readonly usingAIAssistedTranslation?: AIAssistedTranslation;
 }
 

src/components/ethno-art/dto/update-ethno-art.dto.ts

@@ -10,7 +10,7 @@ export abstract class UpdateEthnoArt {
   @IdField()
   readonly id: ID;
 
-  @NameField({ nullable: true })
+  @NameField({ optional: true })
   readonly name?: string;
 
   @ScriptureField({ nullable: true })