Improve end-of-stream handling.

As discussed in issue #247.

docs/essentials/index.md

@@ -37,6 +37,26 @@ libraryDependencies += "dev.zio" %% "zio-nio" % "1.0.0-RC9"
  - **[Socket Channel](sockets.md)** — Provides API for remote communication with `InetSocket`s 
  - **[Character Sets](charsets.md)** - For encoding or decoding character data
 
+### End-Of-Stream Handling
+
+When reading from channels, the end of the stream may be reached at any time. This is indicated by the read effect failing with an `java.io.EOFException`. If you would prefer to explicitly represent the end-of-stream condition in the error channel, use the `eofCheck` extension method:
+
+```scala mdoc:silent
+import zio._
+import zio.blocking.Blocking
+import zio.nio.core._
+import zio.nio.core.channels._
+import zio.nio.core.file.Path
+import java.io.IOException
+
+val read100: ZIO[Blocking, Option[IOException], Chunk[Byte]] =
+  FileChannel.open(Path("foo.txt"))
+    .asSomeError
+    .flatMap(_.readChunk(100).eofCheck)
+```
+
+If the error is `None` if end-of-stream is reached, and it is `Some` if the read failed.
+
 ## References
 
  - [ZIO github page](http://github.com/zio/zio)

nio-core/src/main/scala/zio/nio/core/package.scala

@@ -2,6 +2,7 @@ package zio.nio
 
 import java.io.EOFException
 
+import com.github.ghik.silencer.silent
 import zio.{ IO, ZIO }
 
 package object core {
@@ -22,12 +23,20 @@ package object core {
   private[nio] def eofCheck(value: Long): IO[EOFException, Long] =
     if (value < 0L) IO.fail(new EOFException("Channel has reached the end of stream")) else IO.succeed(value)
 
-  /**
-   * Turns `EOFException` failures into a success with no result.
-   */
-  def eofOption[R, A, E <: Throwable](effect: ZIO[R, E, A]): ZIO[R, E, Option[A]] =
-    effect.asSome.catchSome {
-      case _: EOFException => ZIO.none
-    }
+  implicit final class EffectOps[-R, +E, +A](val effect: ZIO[R, E, A]) extends AnyVal {
+
+    /**
+     * Explicitly represent end-of-stream in the error channel.
+     *
+     * This will catch an `EOFException` failure from the effect and translate it to a failure of `None`.
+     * Other exception types are wrapped in `Some`.
+     */
+    @silent("parameter value ev in method .* is never used")
+    def eofCheck[E2 >: E](implicit ev: EOFException <:< E2): ZIO[R, Option[E2], A] =
+      effect.catchAll {
+        case _: EOFException => ZIO.fail(None)
+        case e               => ZIO.fail(Some(e))
+      }
+  }
 
 }

nio-core/src/test/scala/zio/nio/core/channels/ChannelSpec.scala

@@ -1,6 +1,8 @@
 package zio.nio.core.channels
 
-import zio.nio.core.{ BaseSpec, Buffer, SocketAddress }
+import java.io.{ EOFException, FileNotFoundException, IOException }
+
+import zio.nio.core.{ BaseSpec, Buffer, EffectOps, SocketAddress }
 import zio.test.{ suite, testM }
 import zio.{ IO, _ }
 import zio.test._
@@ -131,6 +133,18 @@ object ChannelSpec extends BaseSpec {
           _             <- client(addr)
           _             <- s2.join
         } yield assertCompletes
-      }
+      },
+      suite("explicit end-of-stream")(
+        testM("converts EOFException to None") {
+          assertM(IO.fail(new EOFException).eofCheck.run)(fails(isNone))
+        },
+        testM("converts non EOFException to Some") {
+          val e: IOException = new FileNotFoundException()
+          assertM(IO.fail(e).eofCheck.run)(fails(isSome(equalTo(e))))
+        },
+        testM("passes through success") {
+          assertM(IO.succeed(42).eofCheck.run)(succeeds(equalTo(42)))
+        }
+      )
     )
 }