Add optional

docs/modules/Codec.ts.md

@@ -34,6 +34,7 @@ Added in v2.2.3
   - [lazy](#lazy)
   - [mapLeftWithInput](#mapleftwithinput)
   - [nullable](#nullable)
+  - [optional](#optional)
   - [partial](#partial)
   - [readonly](#readonly)
   - [record](#record)
@@ -226,6 +227,16 @@ export declare function nullable<I, O, A>(or: Codec<I, O, A>): Codec<null | I, n
 
 Added in v2.2.3
 
+## optional
+
+**Signature**
+
+```ts
+export declare const optional: <I, O, A>(codec: Codec<I, O, A>) => Codec<I, O, Option<A>>
+```
+
+Added in v2.2.17
+
 ## partial
 
 **Signature**

docs/modules/Decoder.ts.md

@@ -44,6 +44,7 @@ Added in v2.2.7
   - [lazy](#lazy)
   - [mapLeftWithInput](#mapleftwithinput)
   - [nullable](#nullable)
+  - [optional](#optional)
   - [parse](#parse)
   - [partial](#partial)
   - [readonly](#readonly)
@@ -307,6 +308,16 @@ export declare const nullable: <I, A>(or: Decoder<I, A>) => Decoder<I, A>
 
 Added in v2.2.7
 
+## optional
+
+**Signature**
+
+```ts
+export declare const optional: <I, A>(or: Decoder<I, A>) => Decoder<I, O.Option<A>>
+```
+
+Added in v2.2.17
+
 ## parse
 
 **Signature**

docs/modules/Encoder.ts.md

@@ -30,6 +30,7 @@ Added in v2.2.3
   - [intersect](#intersect)
   - [lazy](#lazy)
   - [nullable](#nullable)
+  - [optional](#optional)
   - [partial](#partial)
   - [readonly](#readonly)
   - [record](#record)
@@ -128,6 +129,16 @@ export declare function nullable<O, A>(or: Encoder<O, A>): Encoder<null | O, nul
 
 Added in v2.2.3
 
+## optional
+
+**Signature**
+
+```ts
+export declare const optional: <O, A>(or: Encoder<O, A>) => Encoder<O, O.Option<A>>
+```
+
+Added in v2.2.17
+
 ## partial
 
 **Signature**

dtslint/ts3.5/Codec.ts

@@ -113,3 +113,10 @@ const S2 = _.struct({ _tag: _.literal('B'), b: _.number })
 _.sum('_tag')({ A: S1, B: S2 })
 // // $ExpectError
 // _.sum('_tag')({ A: S1, B: S1 })
+
+//
+// optional
+//
+
+// $ExpectType Codec<string | undefined, string | undefined, Option<number>>
+_.optional(NumberFromString)

dtslint/ts3.5/Decoder.ts

@@ -158,3 +158,10 @@ _.readonly(
     a: _.string
   })
 )
+
+//
+// optional
+//
+
+// $ExpectType Decoder<string | undefined, Option<number>>
+_.optional(NumberFromString)

dtslint/ts3.5/Encoder.ts

@@ -102,3 +102,10 @@ const B: E.Encoder<BOut, B> = E.lazy(() =>
     as: E.array(A)
   })
 )
+
+//
+// optional
+//
+
+// $ExpectType Encoder<string | undefined, Option<number>>
+E.optional(NumberToString)

src/Codec.ts

@@ -11,6 +11,7 @@
 import { identity, Refinement } from 'fp-ts/lib/function'
 import { Invariant3 } from 'fp-ts/lib/Invariant'
 import { pipe } from 'fp-ts/lib/pipeable'
+import { Option } from 'fp-ts/lib/Option'
 import * as D from './Decoder'
 import * as E from './Encoder'
 import { Literal } from './Schemable'
@@ -310,6 +311,13 @@ export function lazy<I, O, A>(id: string, f: () => Codec<I, O, A>): Codec<I, O,
  */
 export const readonly: <I, O, A>(codec: Codec<I, O, A>) => Codec<I, O, Readonly<A>> = identity
 
+/**
+ * @category combinators
+ * @since 2.2.17
+ */
+export const optional: <I, O, A>(codec: Codec<I, O, A>) => Codec<I | undefined, O | undefined, Option<A>> = (codec) =>
+  make(D.optional(codec), E.optional(codec))
+
 /**
  * @category combinators
  * @since 2.2.8

src/Decoder.ts

@@ -15,6 +15,7 @@ import * as E from 'fp-ts/lib/Either'
 import { identity, Refinement } from 'fp-ts/lib/function'
 import { Functor2 } from 'fp-ts/lib/Functor'
 import { MonadThrow2C } from 'fp-ts/lib/MonadThrow'
+import * as O from 'fp-ts/lib/Option'
 import { pipe } from 'fp-ts/lib/pipeable'
 import * as DE from './DecodeError'
 import * as FS from './FreeSemigroup'
@@ -380,6 +381,14 @@ export const lazy: <I, A>(id: string, f: () => Decoder<I, A>) => Decoder<I, A> =
  */
 export const readonly: <I, A>(decoder: Decoder<I, A>) => Decoder<I, Readonly<A>> = identity
 
+/**
+ * @category combinators
+ * @since 2.2.17
+ */
+export const optional: <I, A>(or: Decoder<I, A>) => Decoder<I | undefined, O.Option<A>> = (or) => ({
+  decode: (i) => (i === undefined ? E.right(O.none) : pipe(i, or.decode, E.map(O.some)))
+})
+
 // -------------------------------------------------------------------------------------
 // non-pipeables
 // -------------------------------------------------------------------------------------

src/Encoder.ts

@@ -11,7 +11,8 @@
 import { Contravariant2 } from 'fp-ts/lib/Contravariant'
 import { Category2 } from 'fp-ts/lib/Category'
 import { memoize, intersect_ } from './Schemable'
-import { identity } from 'fp-ts/lib/function'
+import { flow, identity } from 'fp-ts/lib/function'
+import * as O from 'fp-ts/lib/Option'
 
 // -------------------------------------------------------------------------------------
 // model
@@ -168,6 +169,14 @@ export function lazy<O, A>(f: () => Encoder<O, A>): Encoder<O, A> {
  */
 export const readonly: <O, A>(decoder: Encoder<O, A>) => Encoder<O, Readonly<A>> = identity
 
+/**
+ * @category combinators
+ * @since 2.2.17
+ */
+export const optional: <O, A>(or: Encoder<O, A>) => Encoder<O | undefined, O.Option<A>> = (or) => ({
+  encode: flow(O.map(or.encode), O.toUndefined)
+})
+
 // -------------------------------------------------------------------------------------
 // non-pipeables
 // -------------------------------------------------------------------------------------

test/Codec.ts

@@ -5,6 +5,7 @@ import { pipe } from 'fp-ts/lib/pipeable'
 import * as DE from '../src/DecodeError'
 import * as FS from '../src/FreeSemigroup'
 import * as E from 'fp-ts/lib/Either'
+import * as O from 'fp-ts/lib/Option'
 import * as H from './helpers'
 
 const codecNumberFromString: _.Codec<string, string, number> = _.make(
@@ -626,6 +627,29 @@ describe('Codec', () => {
     })
   })
 
+  describe('optional', () => {
+    describe('decode', () => {
+      it('should decode a valid input', () => {
+        const codec = _.optional(codecNumberFromString)
+        assert.deepStrictEqual(codec.decode(undefined), D.success(O.none))
+        assert.deepStrictEqual(codec.decode('1'), D.success(O.some(1)))
+      })
+
+      it('should reject an invalid input', () => {
+        const codec = _.optional(codecNumberFromString)
+        assert.deepStrictEqual(codec.decode('a'), D.failure('a', 'parsable to a number'))
+      })
+    })
+
+    describe('encode', () => {
+      it('should encode a value', () => {
+        const codec = _.optional(codecNumberFromString)
+        assert.deepStrictEqual(codec.encode(O.some(1)), '1')
+        assert.deepStrictEqual(codec.encode(O.none), undefined)
+      })
+    })
+  })
+
   it('#453', () => {
     const Base64: _.Codec<string, string, string> = {
       decode: (s) =>

test/Decoder.ts

@@ -1,5 +1,6 @@
 import * as assert from 'assert'
 import * as E from 'fp-ts/lib/Either'
+import * as O from 'fp-ts/lib/Option'
 import { pipe } from 'fp-ts/lib/pipeable'
 import * as DE from '../src/DecodeError'
 import * as FS from '../src/FreeSemigroup'
@@ -529,6 +530,19 @@ describe('Decoder', () => {
     })
   })
 
+  describe('optional', () => {
+    it('should decode a valid input', () => {
+      const decoder = pipe(H.decoderNumberFromString, _.optional)
+      assert.deepStrictEqual(decoder.decode(undefined), _.success(O.none))
+      assert.deepStrictEqual(decoder.decode('1'), _.success(O.some(1)))
+    })
+
+    it('should reject an invalid input', () => {
+      const decoder = pipe(H.decoderNumberFromString, _.optional)
+      assert.deepStrictEqual(decoder.decode('a'), E.left(FS.of(DE.leaf('a', 'parsable to a number'))))
+    })
+  })
+
   // -------------------------------------------------------------------------------------
   // utils
   // -------------------------------------------------------------------------------------

test/Encoder.ts

@@ -1,6 +1,7 @@
 import * as assert from 'assert'
 import * as E from '../src/Encoder'
 import { pipe } from 'fp-ts/lib/pipeable'
+import * as O from 'fp-ts/lib/Option'
 import * as H from './helpers'
 
 describe('Encoder', () => {
@@ -103,4 +104,10 @@ describe('Encoder', () => {
       bs: [{ b: 1, as: [{ a: '2', bs: [] }] }]
     })
   })
+
+  it('optional', () => {
+    const encoder = pipe(H.encoderNumberToString, E.optional)
+    assert.deepStrictEqual(encoder.encode(O.none), undefined)
+    assert.deepStrictEqual(encoder.encode(O.some(1)), '1')
+  })
 })