Nullable reference types in F#

docs/fsharp/language-reference/generics/constraints.md

@@ -21,6 +21,7 @@ There are several different constraints you can apply to limit the types that ca
 |----------|------|-----------|
 |Type Constraint|*type-parameter* :> *type*|The provided type must be equal to or derived from the type specified, or, if the type is an interface, the provided type must implement the interface.|
 |Null Constraint|*type-parameter* : null|The provided type must support the null literal. This includes all .NET object types but not F# list, tuple, function, class, record, or union types.|
+|Not Null Constraint|*type-parameter* : not null|The provided type must not support the null literal. This disallows both `null` annotated types and types which have null as their representation value (such as the option type). This does allow value types, since those can never be null.|
 |Explicit Member Constraint|[(]*type-parameter* [or ... or *type-parameter*)] : (*member-signature*)|At least one of the type arguments provided must have a member that has the specified signature; not intended for common use. Members must be either explicitly defined on the type or part of an implicit type extension to be valid targets for an Explicit Member Constraint.|
 |Constructor Constraint|*type-parameter* : ( new : unit -> 'a )|The provided type must have a parameterless constructor.|
 |Value Type Constraint|*type-parameter* : struct|The provided type must be a .NET value type.|
@@ -54,6 +55,10 @@ type Class2<'T when 'T :> System.IComparable> =
 type Class3<'T when 'T : null> =
     class end
 
+// Not Null constraint
+type Class3<'T when 'T : not null> =
+    class end
+
 // Member constraint with instance member
 type Class5<'T when 'T : (member Method1 : 'T -> int)> =
     class end

docs/fsharp/language-reference/pattern-matching.md

@@ -210,6 +210,15 @@ The following example uses the null pattern and the variable pattern.
 
 [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-2/snippet4817.fs)]
 
+Null pattern is also recommended for the F# 9 [nullability capabilities](./values/null-values.md#null-values-starting-with-f-9):
+
+```fsharp
+let len (str: string | null) =
+    match str with
+    | null -> -1
+    | s -> s.Length
+```
+
 ## Nameof pattern
 
 The `nameof` pattern matches against a string when its value is equal to the expression that follows the `nameof` keyword. for example:

docs/fsharp/language-reference/values/null-values.md

@@ -7,7 +7,7 @@ ms.date: 08/15/2020
 
 This topic describes how the null value is used in F#.
 
-## Null Value
+## Null Values Prior To F# 9
 
 The null value is not normally used in F# for values or variables. However, null appears as an abnormal value in certain situations. If a type is defined in F#, null is not permitted as a regular value unless the [AllowNullLiteral](https://fsharp.github.io/fsharp-core-docs/reference/fsharp-core-allownullliteralattribute.html#Value) attribute is applied to the type. If a type is defined in some other .NET language, null is a possible value, and when you are interoperating with such types, your F# code might encounter null values.
 
@@ -31,6 +31,70 @@ You can use the following code to check if an arbitrary value is null.
 
 [!code-fsharp[Main](~/samples/snippets/fsharp/lang-ref-1/snippet703.fs)]
 
+## Null Values starting with F# 9
+
+In F# 9, extra capabilities are added to the language to deal with reference types which can have `null` as a value. Those are off by default - to turn them on, the following property must be put in your project file:
+
+```xml
+<Nullable>enable</Nullable>
+```
+
+To explicitly opt-in into nullability, a type declaration has to be suffixed with the new syntax:
+
+```fsharp
+type | null
+```
+
+The bar symbol `|` has the meaning of a logical OR in the syntax, building a union of two disjoint sets of types: the underlying type, and the nullable reference. This is the same syntactical symbol which is used for declaring multiple cases of an F# discriminated union: `type AB = A | B` carries the meaning of either `A`, or `B`.
+
+The nullable annotation `| null` can be used at all places where a reference type would be normally used:
+
+- Fields of union types, record types and custom types.
+- Type aliases to existing types.
+- Type applications of a generic type.
+- Explicit type annotations to let bindings, parameters or return types.
+- Type annotations to object-programming constructs like members, properties or fields.
+
+```fsharp
+type AB = A | B
+type AbNull = AB | null
+
+type RecordField = { X: string | null }
+type TupleField = string * string | null
+
+type NestedGenerics = { Z : List<List<string | null> | null> | null }
+```
+
+The bar symbol `|` does have other usages in F# which might lead to syntactical ambiguities. In such cases, parentheses are needed around the null-annotated type:
+
+```fsharp
+// Unexpected symbol '|' (directly before 'null') in member definition
+type DUField = N of string | null
+```
+
+Wrapping the same type into a pair of `( )` parentheses fixes the issue:
+
+```fsharp
+type DUField = N of (string | null)
+```
+
+When used in pattern matching, `|` is used to separate different pattern matching clauses.
+
+```fsharp
+match x with
+| ?: string | null -> ...
+```
+
+This snippet is actually equivalent to code first doing a type test against the `string` type, and then having a separate clause for handling null:
+
+```fsharp
+match x with
+| ?: string 
+| null -> ...
+```
+
+Note that the extra null related capabilities were added to the language for the interoperability purposes. Using `| null` within F# code is not considered idiomatic for denoting missing information - for that purpose, use options (as described above). Read more about null-related [conventions](../../style-guide/conventions.md#nulls-and-default-values) in the style guide.
+
 ## See also
 
 - [Values](index.md)

docs/fsharp/style-guide/component-design-guidelines.md

@@ -693,11 +693,65 @@ let checkNonNull argName (arg: obj) =
     | null -> nullArg argName
     | _ -> ()
 
-let checkNonNull` argName (arg: obj) =
+let checkNonNull' argName (arg: obj) =
     if isNull arg then nullArg argName
     else ()
 ```
 
+Starting with F# 9, you can leverage the new `| null` [syntax](../language-reference/values/null-values.md#null-values-starting-with-f-9) to make the compiler indicate possible null values and where they need handling. The above code will then start producing warnings:
+
+```fsharp
+let checkNonNull argName (arg: obj) =
+    match arg with
+    // nullness warning: the type 'obj' does not support 'null'
+    | null -> nullArg argName
+    | _ -> ()
+
+let checkNonNull' argName (arg: obj) =
+    // nullness warning: the type 'obj' does not support 'null'
+    if isNull arg then nullArg argName 
+    else ()
+```
+
+To address the warnings, you need to explicitly specify `null` as a possible argument value:
+
+```fsharp
+let checkNonNull argName (arg: obj | null) =
+    match arg with
+    | null -> nullArg argName
+    | _ -> ()
+
+let checkNonNull' argName (arg: obj | null) =
+    if isNull arg then nullArg argName 
+    else ()
+```
+
+On the other hand, you'll get a warning if the compiler detects that a possible null value is not handled:
+
+```fsharp
+let printLineLength (s: string) =
+    printfn "%i" s.Length
+
+let readLineFromStream (sr: System.IO.StreamReader) =
+    let line = sr.ReadLine()
+    // nullness warning: The types 'string' and 'string | null'
+    // do not have equivalent nullability
+    printLineLength line
+```
+
+These warnings should be addressed using idiomatic F# [null pattern](../language-reference/pattern-matching.md#null-pattern) via pattern matching:
+
+```fsharp
+let printLineLength (s: string) =
+    printfn "%i" s.Length
+
+let readLineFromStream (sr: System.IO.StreamReader) =
+    let line = sr.ReadLine()
+    match line with
+    | null -> ()
+    | s -> printLineLength s
+```
+
 #### Avoid using tuples as return values
 
 Instead, prefer returning a named type holding the aggregate data, or using out parameters to return multiple values. Although tuples and struct tuples exist in .NET (including C# language support for struct tuples), they will most often not provide the ideal and expected API for .NET developers.

docs/fsharp/style-guide/conventions.md

@@ -687,6 +687,39 @@ module Array =
 
 For legacy reasons some string functions in FSharp.Core still treat nulls as empty strings and do not fail on null arguments. However do not take this as guidance, and do not adopt coding patterns that attribute any semantic meaning to "null".
 
+### Leverage F# 9 null syntax at the API boundaries
+
+F# 9 adds [syntax](../language-reference/values/null-values.md#null-values-starting-with-f-9) to explicitly state that a value can be null. It's designed to be used on the API boundaries, to make the compiler indicate the places where null handling null is missing.
+
+Here is an example of the valid usage of the syntax:
+
+```fsharp
+let processStream (stream: System.IO.StreamReader) =
+    let processLine (line: string | null) =
+        match line with
+        | null -> (); false
+        | s -> printfn "%s" s; true
+
+    while processLine(stream.ReadLine()) do ()
+    stream.Close()
+```
+
+**Avoid** propagating nulls further down your F# code:
+
+```fsharp
+let getLineFromStream (stream: System.IO.StreamReader) : string | null =
+    stream.ReadLine()
+```
+
+**Instead**, use idiomatic F# means (e.g., options):
+
+```fsharp
+let getLineFromStream (stream: System.IO.StreamReader) : string option =
+    match stream.ReadLine() with
+    | null -> None
+    | s -> Some s
+```
+
 ## Object programming
 
 F# has full support for objects and object-oriented (OO) concepts. Although many OO concepts are powerful and useful, not all of them are ideal to use. The following lists offer guidance on categories of OO features at a high level.