feat: Support constant type (#312)

Author: joshuat

docs/api/types.md

@@ -103,6 +103,38 @@ schema({
 });
 ```
 
+## `constant`
+
+Creates a constant value. Useful for creating discriminated unions with the `oneOf` type.
+
+**Parameters:**
+
+| Name               | Type             | Attribute |
+| ------------------ | ---------------- | --------- |
+| `value`            | `TValue`         | required  |
+| `options`          | `GenericOptions` | optional  |
+| `options.required` | `boolean`        | optional  |
+
+**Example:**
+
+```ts
+import { schema, types } from 'papr';
+
+schema({
+  shape: types.oneOf([
+    types.object({
+      type: types.constant('circle' as const, { required: true }),
+      radius: types.number({ required: true }),
+    }),
+    types.object({
+      type: types.constant('rectangle' as const, { required: true }),
+      width: types.number({ required: true }),
+      length: types.number({ required: true }),
+    }),
+  ]),
+});
+```
+
 ## `date`
 
 Creates a date type.

src/__tests__/schema.test.ts

@@ -482,6 +482,8 @@ describe('schema', () => {
         binaryRequired: types.binary({ required: true }),
         booleanOptional: types.boolean(),
         booleanRequired: types.boolean({ required: true }),
+        constantOptional: types.constant(TEST_ENUM.FOO as const),
+        constantRequired: types.constant(TEST_ENUM.FOO as const, { required: true }),
         dateOptional: types.date(),
         dateRequired: types.date({ required: true }),
         enumOptional: types.enum([...Object.values(TEST_ENUM), null]),
@@ -589,6 +591,12 @@ describe('schema', () => {
         booleanRequired: {
           type: 'boolean',
         },
+        constantOptional: {
+          enum: ['foo'],
+        },
+        constantRequired: {
+          enum: ['foo'],
+        },
         createdAt: {
           bsonType: 'date',
         },
@@ -689,6 +697,7 @@ describe('schema', () => {
         'arrayRequired',
         'binaryRequired',
         'booleanRequired',
+        'constantRequired',
         'dateRequired',
         'enumRequired',
         'numberRequired',
@@ -718,6 +727,8 @@ describe('schema', () => {
       binaryRequired: Binary;
       booleanOptional?: boolean;
       booleanRequired: boolean;
+      constantOptional?: TEST_ENUM.FOO;
+      constantRequired: TEST_ENUM.FOO;
       dateOptional?: Date;
       dateRequired: Date;
       enumOptional?: TEST_ENUM | null;
@@ -815,6 +826,8 @@ describe('schema', () => {
         binaryRequired: types.binary({ required: true }),
         booleanOptional: types.boolean({ required: false }),
         booleanRequired: types.boolean({ required: true }),
+        constantOptional: types.constant(TEST_ENUM.FOO as const, { required: false }),
+        constantRequired: types.constant(TEST_ENUM.FOO as const, { required: true }),
         dateOptional: types.date({ required: false }),
         dateRequired: types.date({ required: true }),
         enumOptional: types.enum([...Object.values(TEST_ENUM), null]),
@@ -922,6 +935,12 @@ describe('schema', () => {
         booleanRequired: {
           type: 'boolean',
         },
+        constantOptional: {
+          enum: ['foo'],
+        },
+        constantRequired: {
+          enum: ['foo'],
+        },
         createdAt: {
           bsonType: 'date',
         },
@@ -1022,6 +1041,7 @@ describe('schema', () => {
         'arrayRequired',
         'binaryRequired',
         'booleanRequired',
+        'constantRequired',
         'dateRequired',
         'enumRequired',
         'numberRequired',
@@ -1051,6 +1071,8 @@ describe('schema', () => {
       binaryRequired: Binary;
       booleanOptional?: boolean;
       booleanRequired: boolean;
+      constantOptional?: TEST_ENUM.FOO;
+      constantRequired: TEST_ENUM.FOO;
       dateOptional?: Date;
       dateRequired: Date;
       enumOptional?: TEST_ENUM | null;

src/__tests__/types.test.ts

@@ -393,6 +393,29 @@ describe('types', () => {
       });
     });
 
+    describe('constant', () => {
+      test('default', () => {
+        const value = types.constant('foo' as const);
+
+        expect(value).toEqual({
+          enum: ['foo'],
+        });
+        expectType<'foo' | undefined>(value);
+      });
+
+      test('required', () => {
+        const value = types.constant('foo' as const, { required: true });
+
+        expect(value).toEqual({
+          $required: true,
+          enum: ['foo'],
+        });
+        expectType<'foo'>(value);
+        // @ts-expect-error `value` should not be undefined
+        expectType<typeof value>(undefined);
+      });
+    });
+
     describe('object', () => {
       test('default', () => {
         const value = types.object({

src/types.ts

@@ -136,6 +136,16 @@ function array<Item, Options extends ArrayOptions>(
   } as unknown as GetType<NonNullable<Item>[], Options>;
 }
 
+function constant<Value, Options extends GenericOptions>(
+  value: Value,
+  options?: Options
+): GetType<Value, Options> {
+  return {
+    ...(options?.required ? { $required: true } : {}),
+    enum: [value],
+  } as unknown as GetType<Value, Options>;
+}
+
 function enumType<Enum, Options extends GenericOptions>(
   values: Enum[],
   options?: Options
@@ -324,6 +334,32 @@ export default {
    */
   boolean: createSimpleType<boolean>('boolean'),
 
+  /**
+   * Creates a constant value. Useful for creating discriminated unions with the `oneOf` type.
+   *
+   * @param value {TValue}
+   * @param [options] {GenericOptions}
+   * @param [options.required] {boolean}
+   *
+   * @example
+   * import { schema, types } from 'papr';
+   *
+   * schema({
+   *   shape: types.oneOf([
+   *     types.object({
+   *       type: types.constant('circle' as const, { required: true }),
+   *       radius: types.number({ required: true }),
+   *     }),
+   *     types.object({
+   *       type: types.constant('rectangle' as const, { required: true }),
+   *       width: types.number({ required: true }),
+   *       length: types.number({ required: true }),
+   *     }),
+   *   ]),
+   * });
+   */
+  constant,
+
   /**
    * Creates a date type.
    *