feat add optional type

gcanti · Dec 17, 2022 · 95ed46f · 95ed46f
1 parent 9103e88
commit 95ed46f
Show file tree

Hide file tree

Showing 32 changed files with 349 additions and 3 deletions.
diff --git a/Decoder.md b/Decoder.md
@@ -6,6 +6,7 @@
 - [Combinators](#combinators)
   - [The `literal` constructor](#the-literal-constructor)
   - [The `nullable` combinator](#the-nullable-combinator)
+  - [The `optional` combinator](#the-optional-combinator)
   - [The `struct` combinator](#the-struct-combinator)
   - [The `partial` combinator](#the-partial-combinator)
   - [The `record` combinator](#the-record-combinator)
@@ -100,6 +101,14 @@ The `nullable` combinator describes a nullable value
 export const NullableString: D.Decoder<unknown, null | string> = D.nullable(D.string)
 ```
 
+## The `optional` combinator
+
+The `optional` combinator describes a optional value
+
+```ts
+export const OptionalString: D.Decoder<unknown, undefined | string> = D.optional(D.string)
+```
+
 ## The `struct` combinator
 
 The `struct` combinator describes an object with required fields.

diff --git a/Eq.md b/Eq.md
@@ -45,6 +45,7 @@ export const string: Eq<string> = {
 
 - `literal`
 - `nullable`
+- `optional`
 - `type`
 - `partial`
 - `record`

diff --git a/docs/modules/Codec.ts.md b/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 function optional<I, O, A>(or: Codec<I, O, A>): Codec<undefined | I, undefined | O, undefined | A>
+```
+
+Added in v2.3.0
+
 ## partial
 
 **Signature**

diff --git a/docs/modules/Decoder.ts.md b/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, A>
+```
+
+Added in v2.3.0
+
 ## parse
 
 **Signature**

diff --git a/docs/modules/Encoder.ts.md b/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 function optional<O, A>(or: Encoder<O, A>): Encoder<undefined | O, undefined | A>
+```
+
+Added in v2.3.0
+
 ## partial
 
 **Signature**

diff --git a/docs/modules/Eq.ts.md b/docs/modules/Eq.ts.md
@@ -24,6 +24,7 @@ Added in v2.2.2
   - [intersect](#intersect)
   - [lazy](#lazy)
   - [nullable](#nullable)
+  - [optional](#optional)
   - [partial](#partial)
   - [readonly](#readonly)
   - [record](#record)
@@ -89,6 +90,16 @@ export declare function nullable<A>(or: Eq<A>): Eq<null | A>
 
 Added in v2.2.2
 
+## optional
+
+**Signature**
+
+```ts
+export declare function optional<A>(or: Eq<A>): Eq<undefined | A>
+```
+
+Added in v2.3.0
+
 ## partial
 
 **Signature**

diff --git a/docs/modules/Guard.ts.md b/docs/modules/Guard.ts.md
@@ -27,6 +27,7 @@ Added in v2.2.0
   - [intersect](#intersect)
   - [lazy](#lazy)
   - [nullable](#nullable)
+  - [optional](#optional)
   - [partial](#partial)
   - [readonly](#readonly)
   - [record](#record)
@@ -132,6 +133,16 @@ export declare const nullable: <I, A extends I>(or: Guard<I, A>) => Guard<I, A>
 
 Added in v2.2.0
 
+## optional
+
+**Signature**
+
+```ts
+export declare const optional: <I, A extends I>(or: Guard<I, A>) => Guard<I, A>
+```
+
+Added in v2.3.0
+
 ## partial
 
 **Signature**

diff --git a/docs/modules/Kleisli.ts.md b/docs/modules/Kleisli.ts.md
@@ -34,6 +34,7 @@ Added in v2.2.7
   - [map](#map)
   - [mapLeftWithInput](#mapleftwithinput)
   - [nullable](#nullable)
+  - [optional](#optional)
   - [parse](#parse)
   - [refine](#refine)
   - [union](#union)
@@ -237,6 +238,18 @@ export declare function nullable<M extends URIS2, E>(
 
 Added in v2.2.7
 
+## optional
+
+**Signature**
+
+```ts
+export declare function optional<M extends URIS2, E>(
+  M: Applicative2C<M, E> & Bifunctor2<M>
+): <I>(onError: (i: I, e: E) => E) => <A>(or: Kleisli<M, I, E, A>) => Kleisli<M, undefined | I, E, undefined | A>
+```
+
+Added in v2.3.0
+
 ## parse
 
 **Signature**

diff --git a/docs/modules/Schemable.ts.md b/docs/modules/Schemable.ts.md
@@ -63,6 +63,7 @@ export interface Schemable<S> {
   readonly number: HKT<S, number>
   readonly boolean: HKT<S, boolean>
   readonly nullable: <A>(or: HKT<S, A>) => HKT<S, null | A>
+  readonly optional: <A>(or: HKT<S, A>) => HKT<S, undefined | A>
   /** @deprecated */
   readonly type: <A>(properties: { [K in keyof A]: HKT<S, A[K]> }) => HKT<S, { [K in keyof A]: A[K] }>
   readonly struct: <A>(properties: { [K in keyof A]: HKT<S, A[K]> }) => HKT<S, { [K in keyof A]: A[K] }>
@@ -95,6 +96,7 @@ export interface Schemable1<S extends URIS> {
   readonly number: Kind<S, number>
   readonly boolean: Kind<S, boolean>
   readonly nullable: <A>(or: Kind<S, A>) => Kind<S, null | A>
+  readonly optional: <A>(or: Kind<S, A>) => Kind<S, undefined | A>
   /** @deprecated */
   readonly type: <A>(properties: { [K in keyof A]: Kind<S, A[K]> }) => Kind<S, { [K in keyof A]: A[K] }>
   readonly struct: <A>(properties: { [K in keyof A]: Kind<S, A[K]> }) => Kind<S, { [K in keyof A]: A[K] }>
@@ -127,6 +129,7 @@ export interface Schemable2C<S extends URIS2, E> {
   readonly number: Kind2<S, E, number>
   readonly boolean: Kind2<S, E, boolean>
   readonly nullable: <A>(or: Kind2<S, E, A>) => Kind2<S, E, null | A>
+  readonly optional: <A>(or: Kind2<S, E, A>) => Kind2<S, E, undefined | A>
   /** @deprecated */
   readonly type: <A>(properties: { [K in keyof A]: Kind2<S, E, A[K]> }) => Kind2<S, E, { [K in keyof A]: A[K] }>
   readonly struct: <A>(properties: { [K in keyof A]: Kind2<S, E, A[K]> }) => Kind2<S, E, { [K in keyof A]: A[K] }>

diff --git a/docs/modules/TaskDecoder.ts.md b/docs/modules/TaskDecoder.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)
@@ -310,6 +311,16 @@ export declare const nullable: <I, A>(or: TaskDecoder<I, A>) => TaskDecoder<I, A
 
 Added in v2.2.7
 
+## optional
+
+**Signature**
+
+```ts
+export declare const optional: <I, A>(or: TaskDecoder<I, A>) => TaskDecoder<I, A>
+```
+
+Added in v2.3.0
+
 ## parse
 
 **Signature**

diff --git a/docs/modules/Type.ts.md b/docs/modules/Type.ts.md
@@ -24,6 +24,7 @@ Added in v2.2.3
   - [intersect](#intersect)
   - [lazy](#lazy)
   - [nullable](#nullable)
+  - [optional](#optional)
   - [partial](#partial)
   - [readonly](#readonly)
   - [record](#record)
@@ -95,6 +96,16 @@ export declare const nullable: <A>(or: Type<A>) => Type<A>
 
 Added in v2.2.3
 
+## optional
+
+**Signature**
+
+```ts
+export declare const optional: <A>(or: Type<A>) => Type<A>
+```
+
+Added in v2.3.0
+
 ## partial
 
 **Signature**

diff --git a/dtslint/ts3.5/Encoder.ts b/dtslint/ts3.5/Encoder.ts
@@ -26,6 +26,11 @@ export type OfTestOutput = E.OutputOf<typeof OfTest> // $ExpectType { a: string;
 //
 E.nullable(NumberToString) // $ExpectType Encoder<string | null, number | null>
 
+//
+// optional
+//
+E.optional(NumberToString) // $ExpectType Encoder<string | undefined, number | undefined>
+
 //
 // struct
 //

diff --git a/dtslint/ts3.5/Schema.ts b/dtslint/ts3.5/Schema.ts
@@ -53,6 +53,12 @@ make((S) => S.boolean) // $ExpectType Schema<boolean>
 
 make((S) => S.nullable(S.string)) // $ExpectType Schema<string | null>
 
+//
+// optional
+//
+
+make((S) => S.optional(S.string)) // $ExpectType Schema<string | undefined>
+
 //
 // struct
 //

diff --git a/package-lock.json b/package-lock.json
diff --git a/src/Codec.ts b/src/Codec.ts
@@ -142,6 +142,14 @@ export function nullable<I, O, A>(or: Codec<I, O, A>): Codec<null | I, null | O,
   return make(D.nullable(or), E.nullable(or))
 }
 
+/**
+ * @category combinators
+ * @since 2.3.0
+ */
+export function optional<I, O, A>(or: Codec<I, O, A>): Codec<undefined | I, undefined | O, undefined | A> {
+  return make(D.optional(or), E.optional(or))
+}
+
 /**
  * @category combinators
  * @since 2.2.15

diff --git a/src/Decoder.ts b/src/Decoder.ts
@@ -226,6 +226,14 @@ export const nullable: <I, A>(or: Decoder<I, A>) => Decoder<null | I, null | A>
   /*#__PURE__*/
   K.nullable(M)((u, e) => FS.concat(FS.of(DE.member(0, error(u, 'null'))), FS.of(DE.member(1, e))))
 
+/**
+ * @category combinators
+ * @since 2.3.0
+ */
+export const optional: <I, A>(or: Decoder<I, A>) => Decoder<undefined | I, undefined | A> =
+  /*#__PURE__*/
+  K.optional(M)((u, e) => FS.concat(FS.of(DE.member(0, error(u, 'undefined'))), FS.of(DE.member(1, e))))
+
 /**
  * @category combinators
  * @since 2.2.15
@@ -488,6 +496,7 @@ export const Schemable: S.Schemable2C<URI, unknown> = {
   number,
   boolean,
   nullable,
+  optional,
   type,
   struct,
   partial,

diff --git a/src/Encoder.ts b/src/Encoder.ts
@@ -39,6 +39,16 @@ export function nullable<O, A>(or: Encoder<O, A>): Encoder<null | O, null | A> {
   }
 }
 
+/**
+ * @category combinators
+ * @since 2.3.0
+ */
+export function optional<O, A>(or: Encoder<O, A>): Encoder<undefined | O, undefined | A> {
+  return {
+    encode: (a) => (a === undefined ? undefined : or.encode(a))
+  }
+}
+
 /**
  * @category combinators
  * @since 2.2.15

diff --git a/src/Eq.ts b/src/Eq.ts
@@ -89,6 +89,16 @@ export function nullable<A>(or: Eq<A>): Eq<null | A> {
   }
 }
 
+/**
+ * @category combinators
+ * @since 2.3.0
+ */
+export function optional<A>(or: Eq<A>): Eq<undefined | A> {
+  return {
+    equals: (x, y) => (x === undefined || y === undefined ? x === y : or.equals(x, y))
+  }
+}
+
 /**
  * @category combinators
  * @since 2.2.15
@@ -204,6 +214,7 @@ export const Schemable: Schemable1<E.URI> = {
   number,
   boolean,
   nullable,
+  optional,
   type,
   struct,
   partial,