Add ability to quickly create enum params

Author: nekitk

README.md

@@ -68,6 +68,17 @@ Examples in this table assume query parameter named `qp`.
 | DelimitedArrayParam | string[] | `['a','b','c']` | `?qp=a_b_c'` |
 | DelimitedNumericArrayParam | number[] | `[1, 2, 3]` | `?qp=1_2_3'` |
 
+**Enum Param**
+
+You can define enum param using `createEnumParam`. It works as `StringParam` but restricts decoded output to a list of allowed strings: 
+
+```js
+import { createEnumParam } from 'serialize-query-params';
+
+// values other than 'asc' or 'desc' will be decoded as undefined
+const SortOrderEnumParam = createEnumParam(['asc', 'desc'])
+```
+
 **Setting a default value**
 
 If you'd like to have a default value, you can wrap your param with `withDefault()`:

src/__tests__/params-test.ts

@@ -11,6 +11,7 @@ import {
  NumericObjectParam,
  DelimitedArrayParam,
  DelimitedNumericArrayParam,
+ createEnumParam,
 } from '../index';
 
 describe('params', () => {
@@ -110,5 +111,11 @@ describe('params', () => {
  expect(DelimitedNumericArrayParam.encode([1, 2])).toBe('1_2');
  expect(DelimitedNumericArrayParam.decode('1_2')).toEqual([1, 2]);
  });
+ it('createEnumParam', () => {
+ const TestEnumParam = createEnumParam(['foo', 'bar'])
+ expect(TestEnumParam.encode('foo')).toBe('foo');
+ expect(TestEnumParam.decode('bar')).toBe('bar');
+ expect(TestEnumParam.decode('baz')).toBeUndefined();
+ });
  });
 });

src/__tests__/serialize-test.ts

@@ -7,6 +7,7 @@ import {
  decodeNumber,
  encodeString,
  decodeString,
+ decodeEnum,
  encodeJson,
  decodeJson,
  encodeArray,
@@ -146,6 +147,24 @@ describe('serialize', () => {
  expect(decodeString(['foo', 'bar'])).toBe('foo');
  });
  });
+
+ describe('decodeEnum', () => {
+ const enumValues = ['foo', 'bar']
+
+ it('produces the correct value', () => {
+ expect(decodeEnum('foo', enumValues)).toBe('foo');
+ expect(decodeEnum('bar', enumValues)).toBe('bar');
+ expect(decodeEnum('baz', enumValues)).toBeUndefined();
+ expect(decodeEnum('', enumValues)).toBeUndefined();
+ expect(decodeEnum(undefined, enumValues)).toBeUndefined();
+ expect(decodeEnum(null, enumValues)).toBeNull();
+ });
+
+ it('handles array of values', () => {
+ expect(decodeEnum(['foo', 'bar'], enumValues)).toBe('foo');
+ });
+ })
+
  describe('encodeJson', () => {
  it('produces the correct value', () => {
  const input = { test: '123', foo: [1, 2, 3] };

src/index.ts

@@ -9,6 +9,7 @@ export {
  decodeNumber,
  encodeString,
  decodeString,
+ decodeEnum,
  encodeJson,
  decodeJson,
  encodeArray,
@@ -38,6 +39,7 @@ export {
  NumericObjectParam,
  DelimitedArrayParam,
  DelimitedNumericArrayParam,
+ createEnumParam,
 } from './params';
 
 export {

src/params.ts

@@ -12,6 +12,16 @@ export const StringParam: QueryParamConfig<
  decode: Serialize.decodeString,
 };
 
+/**
+ * String enum
+ */
+export const createEnumParam = <T extends string>(
+ enumValues: T[]
+): QueryParamConfig<string | null | undefined, T | null | undefined> => ({
+ encode: Serialize.encodeString,
+ decode: input => Serialize.decodeEnum(input, enumValues),
+})
+
 /**
  * Numbers (integers or floats)
  */

src/serialize.ts

@@ -253,6 +253,25 @@ export function decodeString(
  return String(str);
 }
 
+/**
+ * Decodes an enum value while safely handling null and undefined values.
+ *
+ * If an array is provided, only the first entry is used.
+ *
+ * @param {String} input the encoded string
+ * @param {String[]} enumValues allowed enum values
+ * @return {String} the string value from enumValues
+ */
+export function decodeEnum<T extends string>(
+ input: string | (string | null)[] | null | undefined,
+ enumValues: T[]
+): T | null | undefined {
+ const str = decodeString(input)
+ if (str == null) return str
+ const isEnumMember = (str: string): str is T => enumValues.includes(str as any)
+ return isEnumMember(str) ? str : undefined
+}
+
 /**
  * Encodes anything as a JSON string.
  *