Add functional analogue of satisfies operator (Effect-TS#2080)

Co-authored-by: maksim.khramtsov <maksim.khramtsov@btsdigital.kz>
Co-authored-by: Michael Arnaldi <michael.arnaldi@effectful.co>

.changeset/mean-dancers-judge.md

@@ -0,0 +1,17 @@
+---
+"effect": patch
+---
+
+Add functional analogue of `satisfies` operator.
+This is a convenient operator to use in the `pipe` chain to localize type errors closer to their source.
+
+```ts
+import { satisfies } from "effect/Function"
+
+const test1 = satisfies<number>()(5 as const)
+      // ^? const test: 5
+
+      // @ts-expect-error
+const test2 = satisfies<string>()(5)
+      // ^? Argument of type 'number' is not assignable to parameter of type 'string'
+```

.gitignore

@@ -8,3 +8,4 @@ build/
 docs/
 scratchpad/
 .direnv/
+.idea/

packages/effect/src/Function.ts

@@ -202,6 +202,25 @@ export interface FunctionN<A extends ReadonlyArray<unknown>, B> {
  */
 export const identity = <A>(a: A): A => a
 
+/**
+ * A function that ensures that the type of an expression matches some type,
+ * without changing the resulting type of that expression.
+ *
+ * @example
+ * import { satisfies } from "effect/Function"
+ *
+ * const test1 = satisfies<number>()(5 as const)
+ *     //^? const test: 5
+ *     // @ts-expect-error
+ * const test2 = satisfies<string>()(5)
+ *     //^? Argument of type 'number' is not assignable to parameter of type 'string'
+ *
+ * assert.deepStrictEqual(satisfies<number>()(5), 5)
+ *
+ * @since 2.0.0
+ */
+export const satisfies = <A>() => <B extends A>(b: B) => b
+
 /**
  * Casts the result to the specified type.
  *

packages/effect/test/Function.test.ts

@@ -28,6 +28,12 @@ describe("Function", () => {
     deepStrictEqual(Function.unsafeCoerce, Function.identity)
   })
 
+  it("satisfies", () => {
+    deepStrictEqual(Function.satisfies<number>()(5), 5)
+    // @ts-expect-error
+    deepStrictEqual(Function.satisfies<string>()(5), 5)
+  })
+
   it("constant", () => {
     deepStrictEqual(Function.constant("a")(), "a")
   })