add Schema.headNonEmpty on Schema.NonEmptyArray (#3983)

Co-authored-by: Giulio Canti <giulio.canti@gmail.com>

Author: 2 people

.changeset/violet-spoons-compare.md

@@ -0,0 +1,5 @@
+---
+"effect": minor
+---
+
+Add Schema.headNonEmpty for Schema.NonEmptyArray

packages/effect/src/Schema.ts

@@ -6117,6 +6117,19 @@ export const head = <A, I, R>(self: Schema<ReadonlyArray<A>, I, R>): SchemaClass
     { strict: true, decode: array_.head, encode: option_.match({ onNone: () => [], onSome: array_.of }) }
   )
 
+/**
+ * Get the first element of a `NonEmptyReadonlyArray`.
+ *
+ * @category NonEmptyReadonlyArray transformations
+ * @since 3.12.0
+ */
+export const headNonEmpty = <A, I, R>(self: Schema<array_.NonEmptyReadonlyArray<A>, I, R>): SchemaClass<A, I, R> =>
+  transform(
+    self,
+    getNumberIndexedAccess(typeSchema(self)),
+    { strict: true, decode: array_.headNonEmpty, encode: array_.of }
+  )
+
 /**
  * Retrieves the first element of a `ReadonlyArray`.
  *

packages/effect/test/Schema/Schema/Array/headNonEmpty.test.ts

@@ -0,0 +1,26 @@
+import * as S from "effect/Schema"
+import * as Util from "effect/test/Schema/TestUtils"
+import { describe, it } from "vitest"
+
+describe("headNonEmpty", () => {
+  it("decoding", async () => {
+    const schema = S.headNonEmpty(S.NonEmptyArray(S.NumberFromString))
+    await Util.expectDecodeUnknownSuccess(schema, ["1"], 1)
+    await Util.expectDecodeUnknownFailure(
+      schema,
+      ["a"],
+      `(readonly [NumberFromString, ...NumberFromString[]] <-> number | number)
+└─ Encoded side transformation failure
+   └─ readonly [NumberFromString, ...NumberFromString[]]
+      └─ [0]
+         └─ NumberFromString
+            └─ Transformation process failure
+               └─ Expected NumberFromString, actual "a"`
+    )
+  })
+
+  it("encoding", async () => {
+    const schema = S.headNonEmpty(S.NonEmptyArray(S.NumberFromString))
+    await Util.expectEncodeSuccess(schema, 1, ["1"])
+  })
+})