add array reading methods

README.md

@@ -80,3 +80,22 @@ If a number cannot be parsed, it will return `undefined`.
 
 Reads a number value from `process.env[key]`.
 If a number cannot be parsed, an error will be thrown.
+
+### .stringArray(key: string, separator: string = ','): string[] | undefined
+
+Reads a string array from `process.env[key]`.
+
+### .stringArrayOrThrow(key: string, separator: string = ','): string[]
+
+Reads a string array from `process.env[key]`.
+Throws an error if it's `undefined`.
+
+### .numberArray(key: string, separator: string = ','): number[] | undefined
+
+Reads a number array from `process.env[key]`.
+If any item cannot be parsed, it will return `undefined`.
+
+### .numberArrayOrThrow(key: string, separator: string = ','): number[]
+
+Reads a number array from `process.env[key]`.
+If any item cannot be parsed, an error will be thrown.

index.ts

@@ -4,6 +4,10 @@ import boolean from './src/boolean'
 import booleanOrThrow from './src/booleanOrThrow'
 import number from './src/number'
 import numberOrThrow from './src/numberOrThrow'
+import stringArray from './src/stringArray'
+import stringArrayOrThrow from './src/stringArrayOrThrow'
+import numberArray from './src/numberArray'
+import numberArrayOrThrow from './src/numberArrayOrThrow'
 
 const tsEnv = {
   string,
@@ -12,6 +16,10 @@ const tsEnv = {
   booleanOrThrow,
   number,
   numberOrThrow,
+  stringArray,
+  stringArrayOrThrow,
+  numberArray,
+  numberArrayOrThrow,
 }
 
 export default tsEnv

src/numberArray.ts

@@ -0,0 +1,15 @@
+export default (key: string, separator: string = ',') => {
+  const rawValue = process.env[key]
+
+  if (!rawValue) {
+    return undefined
+  }
+
+  const numberArray = rawValue.split(separator).map((s) => Number(s))
+
+  if (numberArray.some((n) => isNaN(n))) {
+    return undefined
+  }
+
+  return numberArray
+}

src/numberArrayOrThrow.ts

@@ -0,0 +1,5 @@
+import numberArray from './numberArray'
+import orThrow from './orThrow'
+
+export default (key: string, separator?: string) =>
+  orThrow((k) => numberArray(k, separator), 'number array')(key)

src/stringArray.ts

@@ -0,0 +1,9 @@
+export default (key: string, separator: string = ',') => {
+  const rawValue = process.env[key]
+
+  if (!rawValue) {
+    return undefined
+  }
+
+  return rawValue.split(separator)
+}

src/stringArrayOrThrow.ts

@@ -0,0 +1,5 @@
+import stringArray from './stringArray'
+import orThrow from './orThrow'
+
+export default (key: string, separator?: string) =>
+  orThrow((k) => stringArray(k, separator), 'string array')(key)

tests/index.test.ts

@@ -24,4 +24,20 @@ describe('tsEnv', () => {
   it('has .numberOrThrow() defined', () => {
     expect(tsEnv.numberOrThrow).toEqual(expect.any(Function))
   })
+
+  it('has .stringArray() defined', () => {
+    expect(tsEnv.stringArray).toEqual(expect.any(Function))
+  })
+
+  it('has .stringArrayOrThrow() defined', () => {
+    expect(tsEnv.stringArrayOrThrow).toEqual(expect.any(Function))
+  })
+
+  it('has .numberArray() defined', () => {
+    expect(tsEnv.numberArray).toEqual(expect.any(Function))
+  })
+
+  it('has .numberArrayOrThrow() defined', () => {
+    expect(tsEnv.numberArrayOrThrow).toEqual(expect.any(Function))
+  })
 })

tests/numberArray.test.ts

@@ -0,0 +1,32 @@
+import numberArray from '../src/numberArray'
+
+describe('numberArray()', () => {
+  const key = 'foo'
+  const originalEnv = process.env
+
+  beforeEach(() => {
+    process.env = {
+      ...originalEnv,
+    }
+  })
+
+  it('reads a comma separated array', () => {
+    process.env[key] = '0,1,2,-1.5'
+    expect(numberArray(key)).toEqual([0, 1, 2, -1.5])
+  })
+
+  it('reads a space separated array', () => {
+    const separator = ' '
+    process.env[key] = '0 1 2 -1.5'
+    expect(numberArray(key, separator)).toEqual([0, 1, 2, -1.5])
+  })
+
+  it('returns undefined if any item is not a number', () => {
+    process.env[key] = '0,1,2,foo'
+    expect(numberArray(key)).toBeUndefined()
+  })
+
+  it('returns undefined if a key is not defined', () => {
+    expect(numberArray(key)).toBeUndefined()
+  })
+})

tests/numberArrayOrThrow.test.ts

@@ -0,0 +1,15 @@
+import * as numberArrayModule from '../src/numberArray'
+import * as orThrowModule from '../src/orThrow'
+import numberArrayOrThrow from '../src/numberArrayOrThrow'
+
+jest.spyOn(numberArrayModule, 'default')
+jest.spyOn(orThrowModule, 'default')
+
+describe('.numberArrayOrThrow()', () => {
+  it('does something', () => {
+    process.env.foo = '0,1,2'
+    numberArrayOrThrow('foo')
+    expect(orThrowModule.default).toHaveBeenCalled()
+    expect(numberArrayModule.default).toHaveBeenCalled()
+  })
+})

tests/stringArray.test.ts

@@ -0,0 +1,27 @@
+import stringArray from '../src/stringArray'
+
+describe('stringArray()', () => {
+  const key = 'foo'
+  const originalEnv = process.env
+
+  beforeEach(() => {
+    process.env = {
+      ...originalEnv,
+    }
+  })
+
+  it('reads a comma separated array', () => {
+    process.env[key] = '0,1,2,foo bar'
+    expect(stringArray(key)).toEqual(['0', '1', '2', 'foo bar'])
+  })
+
+  it('reads a space separated array', () => {
+    const separator = ' '
+    process.env[key] = '0 1 2 foo bar'
+    expect(stringArray(key, separator)).toEqual(['0', '1', '2', 'foo', 'bar'])
+  })
+
+  it('returns undefined if a key is not defined', () => {
+    expect(stringArray(key)).toBeUndefined()
+  })
+})

tests/stringArrayOrThrow.test.ts

@@ -0,0 +1,15 @@
+import * as stringArrayModule from '../src/stringArray'
+import * as orThrowModule from '../src/orThrow'
+import stringArrayOrThrow from '../src/stringArrayOrThrow'
+
+jest.spyOn(stringArrayModule, 'default')
+jest.spyOn(orThrowModule, 'default')
+
+describe('.stringArrayOrThrow()', () => {
+  it('does something', () => {
+    process.env.foo = '0,1,2,foo bar'
+    stringArrayOrThrow('foo')
+    expect(orThrowModule.default).toHaveBeenCalled()
+    expect(stringArrayModule.default).toHaveBeenCalled()
+  })
+})