add requiredToOptional function to Schema module, closes #2881

.changeset/mean-cycles-impress.md

@@ -0,0 +1,5 @@
+---
+"@effect/schema": patch
+---
+
+add `requiredToOptional` function to `Schema` module, closes #2881

packages/schema/README.md

@@ -2882,15 +2882,15 @@ console.log(Product.make({ name: "Laptop", price: 999, quantity: 2 })) // { name
 
 ### Optional Fields Primitives
 
-The `optional` API is based on two primitives: `pptionalToOptional` and `optionalToRequired`. These primitives are incredibly useful for defining property signatures with more precision.
+The `optional` API is based on two primitives: `optionalToOptional` and `optionalToRequired`. These primitives are incredibly useful for defining property signatures with more precision.
 
 #### optionalToOptional
 
-The `pptionalToOptional` API is used to manage the transformation from an optional field to another optional field. With this, we can control both the output type and the presence or absence of the field.
+The `optionalToOptional` API is used to manage the transformation from an optional field to another optional field. With this, we can control both the output type and the presence or absence of the field.
 
 For example a common use case is to equate a specific value in the source field with the absence of value in the destination field.
 
-Here's the signature of the `pptionalToOptional` API:
+Here's the signature of the `optionalToOptional` API:
 
 ```ts
 export const optionalToOptional = <FA, FI, FR, TA, TI, TR>(
@@ -3000,6 +3000,51 @@ const encode = Schema.encodeSync(schema)
 console.log(encode({ a: "foo" })) // Output: { a: 'foo' }
 ```
 
+#### requiredToOptional
+
+This API allows developers to specify how a field that is normally required can be treated as optional based on custom logic.
+
+```ts
+export const requiredToOptional = <FA, FI, FR, TA, TI, TR>(
+ from: Schema<FA, FI, FR>,
+ to: Schema<TA, TI, TR>,
+ options: {
+ readonly decode: (fa: FA) => Option.Option<TI>
+ readonly encode: (o: Option.Option<TI>) => FA
+ }
+): PropertySignature<"?:", TA, never, ":", FI, false, FR | TR>
+```
+
+- **`from` and `to` Schemas**: Define the starting and ending schemas for the transformation.
+- **`decode`**: Custom logic for transforming the required input into an optional output.
+- **`encode`**: Defines how to handle the potentially optional input when encoding it back to a required output.
+
+**Example**
+
+Let's look at a practical example where a field `name` that is typically required can be considered optional if it's an empty string during decoding, and ensure there is always a value during encoding by providing a default.
+
+```ts
+import { Schema } from "@effect/schema"
+import { Option } from "effect"
+
+const schema = Schema.Struct({
+ name: Schema.requiredToOptional(Schema.String, Schema.String, {
+ decode: Option.liftPredicate((s) => s !== ""), // empty string is considered as absent
+ encode: Option.getOrElse(() => "")
+ })
+})
+
+const decode = Schema.decodeUnknownSync(schema)
+
+console.log(decode({ name: "John" })) // Output: { name: 'John' }
+console.log(decode({ name: "" })) // Output: {}
+
+const encode = Schema.encodeSync(schema)
+
+console.log(encode({ name: "John" })) // { name: 'John' }
+console.log(encode({})) // Output: { name: '' }
+```
+
 ### Renaming Properties
 
 ```ts

packages/schema/dtslint/Context.ts

@@ -167,13 +167,27 @@ S.NonEmptyArray(aContext)
 // $ExpectType PropertySignature<":", string, never, ":", string, false, "aContext">
 S.propertySignature(aContext)
 
+// ---------------------------------------------
+// optionalToOptional
+// ---------------------------------------------
+
+// $ExpectType PropertySignature<"?:", string, never, "?:", string, false, "aContext">
+S.optionalToOptional(aContext, S.String, { decode: (o) => o, encode: (o) => o })
+
 // ---------------------------------------------
 // optionalToRequired
 // ---------------------------------------------
 
 // $ExpectType PropertySignature<":", string, never, "?:", string, false, "aContext">
 S.optionalToRequired(aContext, S.String, { decode: Option.getOrElse(() => ""), encode: Option.some })
 
+// ---------------------------------------------
+// requiredToOptional
+// ---------------------------------------------
+
+// $ExpectType PropertySignature<"?:", string, never, ":", string, false, "aContext">
+S.requiredToOptional(aContext, S.String, { decode: Option.some, encode: Option.getOrElse(() => "") })
+
 // ---------------------------------------------
 // optional
 // ---------------------------------------------

packages/schema/dtslint/Schema.ts

@@ -2454,3 +2454,37 @@ S.asSchema(MyTaggedStruct)
 
 // $ExpectType [props: { readonly _tag?: "Product"; readonly name: string; readonly category?: "Electronics"; readonly price: number; }]
 hole<Parameters<typeof MyTaggedStruct["make"]>>()
+
+// ---------------------------------------------
+// optionalToOptional
+// ---------------------------------------------
+
+// $ExpectType Schema<{ readonly a?: string; }, { readonly a?: string; }, "a">
+S.asSchema(S.Struct({ a: S.optionalToOptional(aContext, S.String, { decode: (o) => o, encode: (o) => o }) }))
+
+// $ExpectType Struct<{ a: PropertySignature<"?:", string, never, "?:", string, false, "a">; }>
+S.Struct({ a: S.optionalToOptional(aContext, S.String, { decode: (o) => o, encode: (o) => o }) })
+
+// ---------------------------------------------
+// optionalToRequired
+// ---------------------------------------------
+
+// $ExpectType Schema<{ readonly a: string; }, { readonly a?: string; }, "a">
+S.asSchema(
+ S.Struct({ a: S.optionalToRequired(aContext, S.String, { decode: Option.getOrElse(() => ""), encode: Option.some }) })
+)
+
+// $ExpectType Struct<{ a: PropertySignature<":", string, never, "?:", string, false, "a">; }>
+S.Struct({ a: S.optionalToRequired(aContext, S.String, { decode: Option.getOrElse(() => ""), encode: Option.some }) })
+
+// ---------------------------------------------
+// requiredToOptional
+// ---------------------------------------------
+
+// $ExpectType Schema<{ readonly a?: string; }, { readonly a: string; }, "a">
+S.asSchema(
+ S.Struct({ a: S.requiredToOptional(aContext, S.String, { decode: Option.some, encode: Option.getOrElse(() => "") }) })
+)
+
+// $ExpectType Struct<{ a: PropertySignature<"?:", string, never, ":", string, false, "a">; }>
+S.Struct({ a: S.requiredToOptional(aContext, S.String, { decode: Option.some, encode: Option.getOrElse(() => "") }) })

packages/schema/src/Schema.ts

@@ -1812,7 +1812,7 @@ export const fromKey: {
 })
 
 /**
- * Converts an optional property to a required one through a transformation `Option -> Option`.
+ * Converts an optional property to a required one through a transformation `Option -> Type`.
  *
  * - `decode`: `none` as argument means the value is missing in the input.
  * - `encode`: `none` as return value means the value will be missing in the output.
@@ -1837,6 +1837,32 @@ export const optionalToRequired = <FA, FI, FR, TA, TI, TR>(
  )
  )
 
+/**
+ * Converts an optional property to a required one through a transformation `Type -> Option`.
+ *
+ * - `decode`: `none` as return value means the value will be missing in the output.
+ * - `encode`: `none` as argument means the value is missing in the input.
+ *
+ * @category PropertySignature
+ * @since 1.0.0
+ */
+export const requiredToOptional = <FA, FI, FR, TA, TI, TR>(
+ from: Schema<FA, FI, FR>,
+ to: Schema<TA, TI, TR>,
+ options: {
+ readonly decode: (fa: FA) => option_.Option<TI>
+ readonly encode: (o: option_.Option<TI>) => FA
+ }
+): PropertySignature<"?:", TA, never, ":", FI, false, FR | TR> =>
+ makePropertySignature(
+ new PropertySignatureTransformation(
+ new FromPropertySignature(from.ast, false, true, {}, undefined),
+ new ToPropertySignature(to.ast, true, true, {}, undefined),
+ option_.flatMap(options.decode),
+ (o) => option_.some(options.encode(o))
+ )
+ )
+
 /**
  * Converts an optional property to another optional property through a transformation `Option -> Option`.
  *

packages/schema/test/Schema/optionalToRequired.test.ts

@@ -8,9 +8,13 @@ describe("optionalToRequired", () => {
  const ps = S.optionalToRequired(
  S.NumberFromString,
  S.BigIntFromNumber,
- { decode: Option.getOrElse(() => 0), encode: Option.some }
+ { decode: Option.getOrElse(() => 0), encode: Option.liftPredicate((n) => n !== 0) }
  )
  const schema = S.Struct({ a: ps })
+ await Util.expectDecodeUnknownSuccess(schema, {}, { a: 0n })
  await Util.expectDecodeUnknownSuccess(schema, { a: "1" }, { a: 1n })
+
+ await Util.expectEncodeSuccess(schema, { a: 0n }, {})
+ await Util.expectEncodeSuccess(schema, { a: 1n }, { a: "1" })
  })
 })

packages/schema/test/Schema/requiredToOptional.test.ts

@@ -0,0 +1,20 @@
+import * as S from "@effect/schema/Schema"
+import * as Util from "@effect/schema/test/TestUtils"
+import * as Option from "effect/Option"
+import { describe, it } from "vitest"
+
+describe("requiredToOptional", () => {
+ it("two transformation schemas", async () => {
+ const ps = S.requiredToOptional(
+ S.NumberFromString,
+ S.BigIntFromNumber,
+ { decode: Option.liftPredicate((n) => n !== 0), encode: Option.getOrElse(() => 0) }
+ )
+ const schema = S.Struct({ a: ps })
+ await Util.expectDecodeUnknownSuccess(schema, { a: "0" }, {})
+ await Util.expectDecodeUnknownSuccess(schema, { a: "1" }, { a: 1n })
+
+ await Util.expectEncodeSuccess(schema, {}, { a: "0" })
+ await Util.expectEncodeSuccess(schema, { a: 1n }, { a: "1" })
+ })
+})