Add Schema.ArrayEnsure (#1782)

Author: gcanti

.changeset/add-schema-array-ensure.md

@@ -0,0 +1,5 @@
+---
+"effect": patch
+---
+
+Add `Schema.ArrayEnsure`.

packages/effect/src/Schema.ts

@@ -3262,6 +3262,36 @@ export const NonEmptyArray = Struct_.lambda<NonEmptyArrayLambda>((schema) =>
   make(new AST.Arrays(false, [schema.ast], [schema.ast]), { schema })
 )
 
+/**
+ * @category Arrays
+ * @since 4.0.0
+ */
+export interface ArrayEnsure<S extends Top> extends decodeTo<$Array<toType<S>>, Union<readonly [S, $Array<S>]>> {}
+
+/**
+ * Decodes a single value or an array of values into an array.
+ *
+ * Decoding:
+ * - a single value is decoded as a one-element array
+ * - an array is decoded as-is
+ *
+ * Encoding:
+ * - a one-element array is encoded as a single value
+ * - arrays with more than one element are encoded as arrays
+ *
+ * @category Arrays
+ * @since 4.0.0
+ */
+export function ArrayEnsure<S extends Top>(schema: S): ArrayEnsure<S> {
+  return Union([schema, Array(schema)]).pipe(decodeTo(
+    Array(toType(schema)),
+    Transformation.transform({
+      decode: Arr.ensure,
+      encode: (array) => array.length === 1 ? array[0] : array
+    })
+  ))
+}
+
 /**
  * Schema type for an array with unique elements. Produced by {@link UniqueArray}.
  *

packages/effect/test/schema/Schema.test.ts

@@ -940,6 +940,28 @@ Unexpected key with value "c"
     })
   })
 
+  it("ArrayEnsure", async () => {
+    const schema = Schema.ArrayEnsure(Schema.FiniteFromString)
+    const asserts = new TestSchema.Asserts(schema)
+
+    const decoding = asserts.decoding()
+    await decoding.succeed("1", [1])
+    await decoding.succeed(["1", "2"], [1, 2])
+    await decoding.succeed([], [])
+    await decoding.fail(null, `Expected string | array, got null`)
+    await decoding.fail("a", `Expected a finite number, got NaN`)
+    await decoding.fail(
+      ["a"],
+      `Expected a finite number, got NaN
+  at [0]`
+    )
+
+    const encoding = asserts.encoding()
+    await encoding.succeed([], [])
+    await encoding.succeed([1], "1")
+    await encoding.succeed([1, 2], ["1", "2"])
+  })
+
   describe("NonEmptyArray", () => {
     it("should expose the item schema", () => {
       const schema = Schema.NonEmptyArray(Schema.String)