feat: null type (plexinc#337)

Author: noahsilas

docs/api/types.md

@@ -223,6 +223,38 @@ schema({
 });
 ```
 
+## `null`
+
+Creates a `null` type. Use discouraged. Typically used in conjunction with
+another type when applying a schema to a collection that already contains
+`null` values in a field.
+
+Usage of `null` as a value in Mongo is discouraged, as it makes some
+common query patterns ambiguous: `find({ myField: null })` will match
+documents that have the `myField` value set to the literal `null` _or_
+that match `{ myField: { $exists: false } }`.
+
+To match documents with a literal `null` value you must query with
+`{ myField: { $type: 10 } }` (where `10` is the [BSON null type
+constant](https://www.mongodb.com/docs/manual/reference/bson-types/))
+
+**Parameters:**
+
+| Name               | Type             | Attribute |
+| ------------------ | ---------------- | --------- |
+| `options`          | `GenericOptions` | optional  |
+| `options.required` | `boolean`        | optional  |
+
+**Example:**
+
+```ts
+import { schema, types } from 'papr';
+
+schema({
+  nullableNumber: types.oneOf([types.number(), types.null()]),
+});
+```
+
 ## `number`
 
 Creates a number type.

src/__tests__/schema.test.ts

@@ -466,6 +466,10 @@ describe('schema', () => {
         decimalRequired: types.decimal({ required: true }),
         enumOptional: types.enum([...Object.values(TEST_ENUM), null]),
         enumRequired: types.enum(Object.values(TEST_ENUM), { required: true }),
+        nullOptional: types.null(),
+        nullRequired: types.null({ required: true }),
+        nullableOneOfOptional: types.oneOf([types.number(), types.null()]),
+        nullableOneOfRequired: types.oneOf([types.number(), types.null()], { required: true }),
         numberOptional: types.number(),
         numberRequired: types.number({ required: true }),
         objectGenericOptional: types.objectGeneric(types.number()),
@@ -595,6 +599,18 @@ describe('schema', () => {
         enumRequired: {
           enum: ['foo', 'bar'],
         },
+        nullOptional: {
+          type: 'null',
+        },
+        nullRequired: {
+          type: 'null',
+        },
+        nullableOneOfOptional: {
+          oneOf: [{ type: 'number' }, { type: 'null' }],
+        },
+        nullableOneOfRequired: {
+          oneOf: [{ type: 'number' }, { type: 'null' }],
+        },
         numberOptional: {
           type: 'number',
         },
@@ -684,6 +700,8 @@ describe('schema', () => {
         'dateRequired',
         'decimalRequired',
         'enumRequired',
+        'nullRequired',
+        'nullableOneOfRequired',
         'numberRequired',
         'objectGenericRequired',
         'objectIdRequired',
@@ -719,6 +737,10 @@ describe('schema', () => {
       decimalRequired: Decimal128;
       enumOptional?: TEST_ENUM | null;
       enumRequired: TEST_ENUM;
+      nullOptional?: null;
+      nullRequired: null;
+      nullableOneOfOptional?: null | number;
+      nullableOneOfRequired?: null | number;
       numberOptional?: number;
       numberRequired: number;
       objectGenericOptional?: { [key: string]: number | undefined };
@@ -815,6 +837,10 @@ describe('schema', () => {
         dateRequired: types.date({ required: true }),
         enumOptional: types.enum([...Object.values(TEST_ENUM), null]),
         enumRequired: types.enum(Object.values(TEST_ENUM), { required: true }),
+        nullOptional: types.null({ required: false }),
+        nullRequired: types.null({ required: true }),
+        nullableOneOfOptional: types.oneOf([types.number(), types.null()], { required: false }),
+        nullableOneOfRequired: types.oneOf([types.number(), types.null()], { required: true }),
         numberOptional: types.number({ required: false }),
         numberRequired: types.number({ required: true }),
         objectGenericOptional: types.objectGeneric(types.number({ required: false })),
@@ -938,6 +964,18 @@ describe('schema', () => {
         enumRequired: {
           enum: ['foo', 'bar'],
         },
+        nullOptional: {
+          type: 'null',
+        },
+        nullRequired: {
+          type: 'null',
+        },
+        nullableOneOfOptional: {
+          oneOf: [{ type: 'number' }, { type: 'null' }],
+        },
+        nullableOneOfRequired: {
+          oneOf: [{ type: 'number' }, { type: 'null' }],
+        },
         numberOptional: {
           type: 'number',
         },
@@ -1026,6 +1064,8 @@ describe('schema', () => {
         'constantRequired',
         'dateRequired',
         'enumRequired',
+        'nullRequired',
+        'nullableOneOfRequired',
         'numberRequired',
         'objectGenericRequired',
         'objectIdRequired',
@@ -1059,6 +1099,10 @@ describe('schema', () => {
       dateRequired: Date;
       enumOptional?: TEST_ENUM | null;
       enumRequired: TEST_ENUM;
+      nullOptional?: null;
+      nullRequired: null;
+      nullableOneOfOptional?: null | number;
+      nullableOneOfRequired: null | number;
       numberOptional?: number;
       numberRequired: number;
       objectGenericOptional?: { [key: string]: number | undefined };

src/__tests__/types.test.ts

@@ -101,6 +101,37 @@ describe('types', () => {
       });
     });
 
+    describe('null', () => {
+      test('default', () => {
+        const value = types.null();
+
+        expect(value).toEqual({
+          type: 'null',
+        });
+        expectType<null | undefined>(value);
+        expectType<typeof value>(undefined);
+      });
+
+      test('required', () => {
+        const value = types.null({ required: true });
+
+        expect(value).toEqual({
+          $required: true,
+          type: 'null',
+        });
+        expectType<null>(value);
+        // @ts-expect-error `value` should not be undefined
+        expectType<typeof value>(undefined);
+      });
+
+      test('options', () => {
+        types.null({ required: true });
+
+        // @ts-expect-error invalid option
+        types.number({ maxLength: 1 });
+      });
+    });
+
     describe('number', () => {
       test('default', () => {
         const value = types.number();

src/types.ts

@@ -47,6 +47,7 @@ type BSONType =
   | 'boolean'
   | 'date'
   | 'decimal'
+  | 'null'
   | 'number'
   | 'object'
   | 'objectId'
@@ -432,6 +433,32 @@ export default {
    */
   enum: enumType,
 
+  /**
+   * Creates a `null` type. Use discouraged. Typically used in conjunction with
+   * another type when applying a schema to a collection that already contains
+   * `null` values in a field.
+   *
+   * Usage of `null` as a value in Mongo is discouraged, as it makes some
+   * common query patterns ambiguous: `find({ myField: null })` will match
+   * documents that have the `myField` value set to the literal `null` _or_
+   * that match `{ myField: { $exists: false } }`.
+   *
+   * To match documents with a literal `null` value you must query with
+   * `{ myField: { $type: 10 } }` (where `10` is the [BSON null type
+   * constant](https://www.mongodb.com/docs/manual/reference/bson-types/))
+   *
+   * @param [options] {GenericOptions}
+   * @param [options.required] {boolean}
+   *
+   * @example
+   * import { schema, types } from 'papr';
+   *
+   * schema({
+   *   nullableNumber: types.oneOf([ types.number(), types.null() ]),
+   * });
+   */
+  null: createSimpleType<null>('null'),
+
   /**
    * Creates a number type.
    *