feat(cli): Add support for nullable<T> (#5601)

fern-api · Jan 14, 2025 · 6970850 · 6970850
1 parent 151378b
commit 6970850
Show file tree

Hide file tree

Showing 73 changed files with 6,011 additions and 228 deletions.
diff --git a/fern/pages/changelogs/cli/2025-01-14.mdx b/fern/pages/changelogs/cli/2025-01-14.mdx
@@ -0,0 +1,12 @@
+## 0.48.0
+**`(feat):`** Adds support for nullable types in the Fern definition, such as the following:
+
+```yaml
+types:
+  User:
+    properties:
+      name: string
+      email: nullable<string>
+```
+
+
diff --git a/...api-importers/openapi/openapi-ir-parser/src/openapi/v3/extensions/getFernTypeExtension.ts b/...api-importers/openapi/openapi-ir-parser/src/openapi/v3/extensions/getFernTypeExtension.ts
@@ -280,6 +280,19 @@ export function getSchemaFromFernType({
                           inline: undefined
                       })
                     : undefined,
+            nullable: (itemType) =>
+                itemType != null
+                    ? SchemaWithExample.nullable({
+                          nameOverride,
+                          generatedName,
+                          title,
+                          value: itemType,
+                          description,
+                          availability,
+                          groupName,
+                          inline: undefined
+                      })
+                    : undefined,
             set: (itemType) =>
                 itemType != null
                     ? SchemaWithExample.array({

diff --git a/packages/cli/cli/versions.yml b/packages/cli/cli/versions.yml
@@ -1,3 +1,18 @@
+- changelogEntry:
+  - summary: |
+      Adds support for nullable types in the Fern definition, such as the following:
+
+      ```yaml
+      types:
+        User:
+          properties:
+            name: string
+            email: nullable<string>
+      ```
+    type: feat
+  irVersion: 53
+  version: 0.48.0
+
 - changelogEntry:
   - summary: |
       The IR now pulls in additional request properties from the OAuth getToken endpoint to support custom OAuth schemas.

diff --git a/packages/cli/fern-definition/ir-to-jsonschema/src/converters/containerToJsonSchema.ts b/packages/cli/fern-definition/ir-to-jsonschema/src/converters/containerToJsonSchema.ts
@@ -31,6 +31,13 @@ export function convertContainerToJsonSchema({
                     { type: "null" }
                 ]
             };
+        case "nullable":
+            return {
+                oneOf: [
+                    convertTypeReferenceToJsonSchema({ typeReference: container.nullable, context }),
+                    { type: "null" }
+                ]
+            };
         case "set":
             return {
                 type: "array",

diff --git a/packages/cli/fern-definition/schema/src/utils/RawContainerType.ts b/packages/cli/fern-definition/schema/src/utils/RawContainerType.ts
@@ -1,5 +1,6 @@
 export const RawContainerType = {
     optional: "optional",
+    nullable: "nullable",
     set: "set",
     list: "list",
     map: "map",

diff --git a/packages/cli/fern-definition/schema/src/utils/recursivelyVisitRawTypeReference.ts b/packages/cli/fern-definition/schema/src/utils/recursivelyVisitRawTypeReference.ts
@@ -9,6 +9,7 @@ export interface RecursiveRawTypeReferenceVisitor<R> {
     list: (valueType: R) => R;
     set: (valueType: R) => R;
     optional: (valueType: R) => R;
+    nullable: (valueType: R) => R;
     literal: (literal: Literal) => R;
     named: (named: string) => R;
     unknown: () => R;
@@ -66,6 +67,8 @@ export function recursivelyVisitRawTypeReference<R>({
                 ),
             optional: (valueType) =>
                 visitor.optional(recursivelyVisitRawTypeReference({ type: valueType, _default, validation, visitor })),
+            nullable: (valueType) =>
+                visitor.nullable(recursivelyVisitRawTypeReference({ type: valueType, _default, validation, visitor })),
             literal: visitor.literal,
             named: visitor.named,
             unknown: visitor.unknown

diff --git a/packages/cli/fern-definition/schema/src/utils/visitRawTypeReference.ts b/packages/cli/fern-definition/schema/src/utils/visitRawTypeReference.ts
@@ -10,6 +10,7 @@ export const FernContainerRegex = {
     LIST: /^list<\s*(.*)\s*>$/,
     SET: /^set<\s*(.*)\s*>$/,
     OPTIONAL: /^optional<\s*(.*)\s*>$/,
+    NULLABLE: /^nullable<\s*(.*)\s*>$/,
     LITERAL: /^literal<\s*(?:"(.*)"|(true|false))\s*>$/
 };
 
@@ -19,6 +20,7 @@ export interface RawTypeReferenceVisitor<R> {
     list: (valueType: string) => R;
     set: (valueType: string) => R;
     optional: (valueType: string) => R;
+    nullable: (valueType: string) => R;
     literal: (literal: Literal) => R;
     named: (named: string) => R;
     unknown: () => R;
@@ -175,6 +177,11 @@ export function visitRawTypeReference<R>({
         return visitor.optional(optionalMatch[1]);
     }
 
+    const nullableMatch = type.match(FernContainerRegex.NULLABLE);
+    if (nullableMatch?.[1] != null) {
+        return visitor.nullable(nullableMatch[1]);
+    }
+
     const literalMatch = type.match(FernContainerRegex.LITERAL);
     if (literalMatch?.[1] != null) {
         return visitor.literal(Literal.string(literalMatch[1]));

diff --git a/packages/cli/fern-definition/validator/src/ComplexQueryParamTypeDetector.ts b/packages/cli/fern-definition/validator/src/ComplexQueryParamTypeDetector.ts
@@ -113,6 +113,7 @@ export class ComplexQueryParamTypeDetector {
                     )
                 );
             case "optional":
+            case "nullable":
             case "list":
             case "set":
                 return this.isResolvedReferenceComplex({
@@ -254,6 +255,7 @@ export class ComplexQueryParamTypeDetector {
                     })
                 );
             case "optional":
+            case "nullable":
             case "list":
             case "set":
                 return this.isComplex({

diff --git a/...definition/validator/src/rules/no-undefined-type-reference/no-undefined-type-reference.ts b/...definition/validator/src/rules/no-undefined-type-reference/no-undefined-type-reference.ts
@@ -199,6 +199,7 @@ function getAllNamedTypes({
             list: (namesInValueType) => namesInValueType,
             set: (namesInValueType) => namesInValueType,
             optional: (namesInValueType) => namesInValueType,
+            nullable: (namesInValueType) => namesInValueType,
             literal: () => [],
             named: (named) => {
                 const reference = parseReferenceToTypeName({

diff --git a/packages/cli/generation/ir-generator/src/converters/type-declarations/convertExampleType.ts b/packages/cli/generation/ir-generator/src/converters/type-declarations/convertExampleType.ts
@@ -303,6 +303,25 @@ export function convertTypeReferenceExample({
                     })
                 );
             },
+            nullable: (itemType) => {
+                return ExampleTypeReferenceShape.container(
+                    ExampleContainer.nullable({
+                        nullable:
+                            resolvedExample != null
+                                ? convertTypeReferenceExample({
+                                      example: resolvedExample,
+                                      fileContainingExample: fileContainingResolvedExample,
+                                      rawTypeBeingExemplified: itemType,
+                                      fileContainingRawTypeReference,
+                                      typeResolver,
+                                      exampleResolver,
+                                      workspace
+                                  })
+                                : undefined,
+                        valueType: fileContainingRawTypeReference.parseTypeReference(itemType)
+                    })
+                );
+            },
             literal: (literal) => {
                 switch (literal.type) {
                     case "boolean":

diff --git a/...ion/ir-generator/src/converters/type-declarations/getReferencedTypesFromRawDeclaration.ts b/...ion/ir-generator/src/converters/type-declarations/getReferencedTypesFromRawDeclaration.ts
@@ -117,6 +117,7 @@ export function getReferencedTypesFromRawDeclaration({
                 map: ({ keyType, valueType }) => [...keyType, ...valueType],
                 list: (valueType) => valueType,
                 optional: (valueType) => valueType,
+                nullable: (valueType) => valueType,
                 set: (valueType) => valueType,
                 named: (name) => [name],
                 literal: () => [],

diff --git a/packages/cli/generation/ir-generator/src/dynamic-snippets/DynamicSnippetsConverter.ts b/packages/cli/generation/ir-generator/src/dynamic-snippets/DynamicSnippetsConverter.ts
@@ -331,6 +331,8 @@ export class DynamicSnippetsConverter {
                 });
             case "optional":
                 return DynamicSnippets.TypeReference.optional(this.convertTypeReference(container.optional));
+            case "nullable":
+                return DynamicSnippets.TypeReference.nullable(this.convertTypeReference(container.nullable));
             case "set":
                 return DynamicSnippets.TypeReference.set(this.convertTypeReference(container.set));
             case "literal":

diff --git a/packages/cli/generation/ir-generator/src/examples/generator/generateContainerExample.ts b/packages/cli/generation/ir-generator/src/examples/generator/generateContainerExample.ts
@@ -96,6 +96,30 @@ export function generateContainerExample({
                 jsonExample: example.jsonExample
             };
         }
+        case "nullable": {
+            if (skipOptionalProperties) {
+                return generateEmptyContainerExample({ containerType });
+            }
+            const example = generateTypeReferenceExample({
+                fieldName,
+                typeReference: containerType.nullable,
+                maxDepth,
+                currentDepth: currentDepth + 1,
+                typeDeclarations,
+                skipOptionalProperties
+            });
+            if (example.type === "failure") {
+                return generateEmptyContainerExample({ containerType });
+            }
+            return {
+                type: "success",
+                example: ExampleContainer.nullable({
+                    nullable: example.example,
+                    valueType: containerType.nullable
+                }),
+                jsonExample: example.jsonExample
+            };
+        }
         case "set": {
             const example = generateTypeReferenceExample({
                 fieldName,
@@ -206,6 +230,16 @@ export function generateEmptyContainerExample({
                 jsonExample: undefined
             };
         }
+        case "nullable": {
+            return {
+                type: "success",
+                example: ExampleContainer.nullable({
+                    nullable: undefined,
+                    valueType: containerType.nullable
+                }),
+                jsonExample: undefined
+            };
+        }
         case "set": {
             return {
                 type: "success",

diff --git a/packages/cli/generation/ir-generator/src/examples/validateTypeReferenceExample.ts b/packages/cli/generation/ir-generator/src/examples/validateTypeReferenceExample.ts
@@ -214,6 +214,21 @@ export function validateTypeReferenceExample({
                     depth: depth + 1
                 });
             },
+            nullable: (itemType) => {
+                if (example == null) {
+                    return [];
+                }
+                return validateTypeReferenceExample({
+                    rawTypeReference: itemType,
+                    example,
+                    typeResolver,
+                    exampleResolver,
+                    file,
+                    workspace,
+                    breadcrumbs,
+                    depth: depth + 1
+                });
+            },
             unknown: () => {
                 return [];
             },
@@ -488,6 +503,15 @@ function areResolvedTypesEquivalent({ expected, actual }: { expected: ResolvedTy
                             ? actual.container.itemType
                             : actual
                 });
+            case "nullable":
+                // special case: if expected is a nullable but actual is not, that's okay
+                return areResolvedTypesEquivalent({
+                    expected: expected.container.itemType,
+                    actual:
+                        actual._type === "container" && actual.container._type === "nullable"
+                            ? actual.container.itemType
+                            : actual
+                });
             case "map":
                 return (
                     actual._type === "container" &&

diff --git a/packages/cli/generation/ir-generator/src/filterExamples.ts b/packages/cli/generation/ir-generator/src/filterExamples.ts
@@ -111,6 +111,23 @@ function filterExampleTypeReference({
                           }
                         : undefined;
                 },
+                nullable: (n) => {
+                    const filteredNullableTypReference =
+                        n.nullable != null
+                            ? filterExampleTypeReference({ filteredIr, exampleTypeReference: n.nullable })
+                            : undefined;
+                    return filteredNullableTypReference != null
+                        ? {
+                              ...exampleTypeReference,
+                              shape: ExampleTypeReferenceShape.container(
+                                  ExampleContainer.nullable({
+                                      nullable: filteredNullableTypReference,
+                                      valueType: n.valueType
+                                  })
+                              )
+                          }
+                        : undefined;
+                },
                 map: (m) => ({
                     ...exampleTypeReference,
                     shape: ExampleTypeReferenceShape.container(

diff --git a/packages/cli/generation/ir-generator/src/filtered-ir/IrGraph.ts b/packages/cli/generation/ir-generator/src/filtered-ir/IrGraph.ts
@@ -706,6 +706,9 @@ function populateReferencesFromContainer(
         optional: (optionalType) => {
             populateReferencesFromTypeReference(optionalType, referencedTypes, referencedSubpackages);
         },
+        nullable: (nullableType) => {
+            populateReferencesFromTypeReference(nullableType, referencedTypes, referencedSubpackages);
+        },
         set: (setType) => {
             populateReferencesFromTypeReference(setType, referencedTypes, referencedSubpackages);
         },

diff --git a/packages/cli/generation/ir-generator/src/resolvers/ResolvedType.ts b/packages/cli/generation/ir-generator/src/resolvers/ResolvedType.ts
@@ -49,6 +49,7 @@ export declare type ResolvedContainerType =
     | ResolvedContainerType.Map
     | ResolvedContainerType.List
     | ResolvedContainerType.Optional
+    | ResolvedContainerType.Nullable
     | ResolvedContainerType.Set
     | ResolvedContainerType.Literal;
 
@@ -69,6 +70,11 @@ export declare namespace ResolvedContainerType {
         itemType: ResolvedType;
     }
 
+    interface Nullable {
+        _type: "nullable";
+        itemType: ResolvedType;
+    }
+
     interface Set {
         _type: "set";
         itemType: ResolvedType;

diff --git a/packages/cli/generation/ir-generator/src/resolvers/TypeResolver.ts b/packages/cli/generation/ir-generator/src/resolvers/TypeResolver.ts
@@ -181,6 +181,19 @@ export class TypeResolverImpl implements TypeResolver {
                               )
                           }
                         : undefined,
+                nullable: (itemType) =>
+                    itemType != null
+                        ? {
+                              _type: "container",
+                              container: {
+                                  _type: "nullable",
+                                  itemType
+                              },
+                              originalTypeReference: TypeReference.container(
+                                  ContainerType.nullable(itemType.originalTypeReference)
+                              )
+                          }
+                        : undefined,
                 set: (itemType) =>
                     itemType != null
                         ? {

diff --git a/packages/cli/generation/ir-generator/src/utils/parseInlineType.ts b/packages/cli/generation/ir-generator/src/utils/parseInlineType.ts
@@ -25,6 +25,7 @@ export function parseInlineType({ type, file, _default, validation }: parseInlin
             list: (valueType) => TypeReference.container(ContainerType.list(valueType)),
             set: (valueType) => TypeReference.container(ContainerType.set(valueType)),
             optional: (valueType) => TypeReference.container(ContainerType.optional(valueType)),
+            nullable: (valueType) => TypeReference.container(ContainerType.nullable(valueType)),
             literal: (literal) => TypeReference.container(ContainerType.literal(literal)),
             named: (namedType) =>
                 TypeReference.named({

diff --git a/packages/cli/generation/ir-migrations/package.json b/packages/cli/generation/ir-migrations/package.json
@@ -86,6 +86,7 @@
     "@fern-fern/ir-v51-sdk": "0.0.1",
     "@fern-fern/ir-v52-sdk": "0.0.1",
     "@fern-fern/ir-v53-sdk": "0.0.1",
+    "@fern-fern/ir-v54-sdk": "0.0.1",
     "@fern-fern/ir-v6-model": "0.0.33",
     "@fern-fern/ir-v7-model": "0.0.2",
     "@fern-fern/ir-v8-model": "0.0.1",

diff --git a/packages/cli/generation/ir-migrations/src/IntermediateRepresentationMigrator.ts b/packages/cli/generation/ir-migrations/src/IntermediateRepresentationMigrator.ts
@@ -57,6 +57,7 @@ import { V51_TO_V50_MIGRATION } from "./migrations/v51-to-v50/migrateFromV51ToV5
 import { V52_TO_V51_MIGRATION } from "./migrations/v52-to-v51/migrateFromV52ToV51";
 import { V53_TO_V52_MIGRATION } from "./migrations/v53-to-v52/migrateFromV53ToV52";
 import { V54_TO_V53_MIGRATION } from "./migrations/v54-to-v53/migrateFromV54ToV53";
+import { V55_TO_V54_MIGRATION } from "./migrations/v55-to-v54/migrateFromV55ToV54";
 import { GeneratorWasNeverUpdatedToConsumeNewIR, GeneratorWasNotCreatedYet, IrMigration } from "./types/IrMigration";
 
 export function getIntermediateRepresentationMigrator(): IntermediateRepresentationMigrator {
@@ -298,6 +299,7 @@ const IntermediateRepresentationMigrator = {
 
 export const INTERMEDIATE_REPRESENTATION_MIGRATOR = IntermediateRepresentationMigrator.Builder
     // put new migrations here
+    .withMigration(V55_TO_V54_MIGRATION)
     .withMigration(V54_TO_V53_MIGRATION)
     .withMigration(V53_TO_V52_MIGRATION)
     .withMigration(V52_TO_V51_MIGRATION)

diff --git a/packages/cli/generation/ir-migrations/src/ir-serialization/IrSerialization.ts b/packages/cli/generation/ir-migrations/src/ir-serialization/IrSerialization.ts
@@ -1,4 +1,4 @@
-export { serialization as V54 } from "@fern-api/ir-sdk";
+export { serialization as V55 } from "@fern-api/ir-sdk";
 export * as V23 from "@fern-fern/ir-v23-sdk/serialization";
 export * as V24 from "@fern-fern/ir-v24-sdk/serialization";
 export * as V25 from "@fern-fern/ir-v25-sdk/serialization";
@@ -30,3 +30,4 @@ export * as V50 from "@fern-fern/ir-v50-sdk/serialization";
 export * as V51 from "@fern-fern/ir-v51-sdk/serialization";
 export * as V52 from "@fern-fern/ir-v52-sdk/serialization";
 export * as V53 from "@fern-fern/ir-v53-sdk/serialization";
+export * as V54 from "@fern-fern/ir-v54-sdk/serialization";