From e964a1caa61af6263f9b805f112ed1c15e90480f Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Wed, 16 Nov 2022 15:00:30 +0330 Subject: [PATCH 1/8] prepare docs. --- README.md | 86 ++------------------------------------------ docs/index.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++ docs/package.json | 5 +++ docs/sidebars.js | 7 ++++ 4 files changed, 105 insertions(+), 84 deletions(-) create mode 100644 docs/index.md create mode 100644 docs/package.json create mode 100644 docs/sidebars.js diff --git a/README.md b/README.md index ca8d54d..a564690 100644 --- a/README.md +++ b/README.md @@ -7,91 +7,9 @@ This library provides an interoperability layer for reactive streams. -## Reactive Streams `Producer` and `Subscriber` +## Documentation -**ZIO** integrates with [Reactive Streams](http://reactivestreams.org) by providing conversions from `zio.stream.Stream` to `org.reactivestreams.Publisher` -and from `zio.stream.Sink` to `org.reactivestreams.Subscriber` and vice versa. Simply import `import zio.interop.reactivestreams._` to make the -conversions available. - -## Examples - -First, let's get a few imports out of the way. - -```scala mdoc:silent -import org.reactivestreams.example.unicast._ -import zio._ -import zio.interop.reactivestreams._ -import zio.stream._ - -val runtime = new DefaultRuntime {} -``` - -We use the following `Publisher` and `Subscriber` for the examples: - -```scala mdoc -val publisher = new RangePublisher(3, 10) -val subscriber = new SyncSubscriber[Int] { - override protected def whenNext(v: Int): Boolean = { - print(s"$v, ") - true - } -} -``` - -### Publisher to Stream - -A `Publisher` used as a `Stream` buffers up to `qSize` elements. If possible, `qSize` should be -a power of two for best performance. The default is 16. - -```scala mdoc -val streamFromPublisher = publisher.toStream(qSize = 16) -runtime.unsafeRun( - streamFromPublisher.run(Sink.collectAll[Integer]) -) -``` - -### Subscriber to Sink - -When running a `Stream` to a `Subscriber`, a side channel is needed for signalling failures. -For this reason `toSink` returns a tuple of `Promise` and `Sink`. The `Promise` must be failed -on `Stream` failure. The type parameter on `toSink` is the error type of *the Stream*. - -```scala mdoc -val asSink = subscriber.toSink[Throwable] -val failingStream = Stream.range(3, 13) ++ Stream.fail(new RuntimeException("boom!")) -runtime.unsafeRun( - asSink.flatMap { case (errorP, sink) => - failingStream.run(sink).catchAll(errorP.fail) - } -) -``` - -### Stream to Publisher - -```scala mdoc -val stream = Stream.range(3, 13) -runtime.unsafeRun( - stream.toPublisher.flatMap { publisher => - UIO(publisher.subscribe(subscriber)) - } -) -``` - -### Sink to Subscriber - -`toSubscriber` returns a `Subscriber` and an `IO` which completes with the result of running the -`Sink` or the error if the `Publisher` fails. -A `Sink` used as a `Subscriber` buffers up to `qSize` elements. If possible, `qSize` should be -a power of two for best performance. The default is 16. - -```scala mdoc -val sink = Sink.collectAll[Integer] -runtime.unsafeRun( - sink.toSubscriber(qSize = 16).flatMap { case (subscriber, result) => - UIO(publisher.subscribe(subscriber)) *> result - } -) -``` +[Homepage](https://zio.dev/zio-interop-reactivestreams) [Badge-CI]: https://github.com/zio/interop-reactive-streams/workflows/CI/badge.svg [Badge-SonatypeReleases]: https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-interop-reactivestreams_2.12.svg "Sonatype Releases" diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..17db00f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,91 @@ +--- +id: index +title: "Introduction to ZIO Interop Reactive Streams" +sidebar_label: "ZIO Interop Reactive Streams" +--- + +## Reactive Streams `Producer` and `Subscriber` + +**ZIO** integrates with [Reactive Streams](http://reactivestreams.org) by providing conversions from `zio.stream.Stream` to `org.reactivestreams.Publisher` +and from `zio.stream.Sink` to `org.reactivestreams.Subscriber` and vice versa. Simply import `import zio.interop.reactivestreams._` to make the +conversions available. + +## Examples + +First, let's get a few imports out of the way. + +```scala +import org.reactivestreams.example.unicast._ +import zio._ +import zio.interop.reactivestreams._ +import zio.stream._ + +val runtime = new DefaultRuntime {} +``` + +We use the following `Publisher` and `Subscriber` for the examples: + +```scala +val publisher = new RangePublisher(3, 10) +val subscriber = new SyncSubscriber[Int] { + override protected def whenNext(v: Int): Boolean = { + print(s"$v, ") + true + } +} +``` + +### Publisher to Stream + +A `Publisher` used as a `Stream` buffers up to `qSize` elements. If possible, `qSize` should be +a power of two for best performance. The default is 16. + +```scala +val streamFromPublisher = publisher.toStream(qSize = 16) +runtime.unsafeRun( + streamFromPublisher.run(Sink.collectAll[Integer]) +) +``` + +### Subscriber to Sink + +When running a `Stream` to a `Subscriber`, a side channel is needed for signalling failures. +For this reason `toSink` returns a tuple of `Promise` and `Sink`. The `Promise` must be failed +on `Stream` failure. The type parameter on `toSink` is the error type of *the Stream*. + +```scala +val asSink = subscriber.toSink[Throwable] +val failingStream = Stream.range(3, 13) ++ Stream.fail(new RuntimeException("boom!")) +runtime.unsafeRun( + asSink.flatMap { case (errorP, sink) => + failingStream.run(sink).catchAll(errorP.fail) + } +) +``` + +### Stream to Publisher + +```scala +val stream = Stream.range(3, 13) +runtime.unsafeRun( + stream.toPublisher.flatMap { publisher => + UIO(publisher.subscribe(subscriber)) + } +) +``` + +### Sink to Subscriber + +`toSubscriber` returns a `Subscriber` and an `IO` which completes with the result of running the +`Sink` or the error if the `Publisher` fails. +A `Sink` used as a `Subscriber` buffers up to `qSize` elements. If possible, `qSize` should be +a power of two for best performance. The default is 16. + +```scala +val sink = Sink.collectAll[Integer] +runtime.unsafeRun( + sink.toSubscriber(qSize = 16).flatMap { case (subscriber, result) => + UIO(publisher.subscribe(subscriber)) *> result + } +) +``` diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..d4d7a01 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,5 @@ +{ + "name": "@zio.dev/zio-interop-reactivestreams", + "description": "ZIO Interop Reactive Streams Documentation", + "license": "Apache-2.0" +} diff --git a/docs/sidebars.js b/docs/sidebars.js new file mode 100644 index 0000000..b485cd2 --- /dev/null +++ b/docs/sidebars.js @@ -0,0 +1,7 @@ +const sidebars = { + sidebar: [ + "index" + ] +}; + +module.exports = sidebars; From 64928e7facf085a8e3b97c2b36e42500b2e548e2 Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Wed, 16 Nov 2022 15:01:59 +0330 Subject: [PATCH 2/8] ignore .idea. --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index cf53196..d3e5f23 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ .metals .sbtopts .vscode +.idea metals.sbt project/.sbt project/metals.sbt From b5a290227942b5862949f9b141093ff18e9f4282 Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Wed, 16 Nov 2022 15:02:43 +0330 Subject: [PATCH 3/8] update docs. --- docs/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/index.md b/docs/index.md index 17db00f..7119a95 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,8 @@ title: "Introduction to ZIO Interop Reactive Streams" sidebar_label: "ZIO Interop Reactive Streams" --- +This library provides an interoperability layer for reactive streams. + ## Reactive Streams `Producer` and `Subscriber` **ZIO** integrates with [Reactive Streams](http://reactivestreams.org) by providing conversions from `zio.stream.Stream` to `org.reactivestreams.Publisher` From 82df638ec0fb995e72529d8d1c6dd858a0085216 Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Wed, 16 Nov 2022 15:03:12 +0330 Subject: [PATCH 4/8] install zio-sbt-website plugin. --- build.sbt | 16 +++++++++++++++- project/plugins.sbt | 3 +++ 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/build.sbt b/build.sbt index 7775126..48f4cf5 100644 --- a/build.sbt +++ b/build.sbt @@ -3,7 +3,7 @@ import BuildHelper._ inThisBuild( List( organization := "dev.zio", - homepage := Some(url("https://zio.dev")), + homepage := Some(url("https://zio.dev/zio-interop-reactivestreams")), licenses := List("Apache-2.0" -> url("http://www.apache.org/licenses/LICENSE-2.0")), developers := List( Developer( @@ -63,3 +63,17 @@ lazy val interopReactiveStreams = project Seq("org.scala-lang.modules" %% "scala-collection-compat" % collCompatVersion % Test) } ) + +lazy val docs = project + .in(file("zio-interop-reactivestreams-docs")) + .settings( + publish / skip := true, + moduleName := "zio-interop-reactivestreams-docs", + scalacOptions -= "-Yno-imports", + scalacOptions -= "-Xfatal-warnings", + libraryDependencies ++= Seq( + "dev.zio" %% "zio" % zioVersion + ) + ) + .dependsOn(interopReactiveStreams) + .enablePlugins(WebsitePlugin) diff --git a/project/plugins.sbt b/project/plugins.sbt index 51f6b7f..46e05ba 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -6,3 +6,6 @@ addSbtPlugin("com.github.cb372" % "sbt-explicit-dependencies" % "0.2.16") addSbtPlugin("org.portable-scala" % "sbt-crossproject" % "1.0.0") addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.6.0") addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.4.2") +addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.0.0+84-6fd7d64e-SNAPSHOT") + +resolvers += Resolver.sonatypeRepo("public") From 60ca0b94437439e3559115f22ad0754adc80f3b9 Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Wed, 16 Nov 2022 15:05:26 +0330 Subject: [PATCH 5/8] update ci. --- .github/workflows/ci.yml | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 777e40a..730b677 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -46,9 +46,22 @@ jobs: - name: Run tests run: sbt ++${{ matrix.scala }}! test + website: + runs-on: ubuntu-20.04 + timeout-minutes: 60 + steps: + - name: Checkout current branch + uses: actions/checkout@v3.1.0 + - name: Setup Scala and Java + uses: olafurpg/setup-scala@v13 + - name: Cache scala dependencies + uses: coursier/cache-action@v6 + - name: Check Document Generation + run: sbt docs/compileDocs + publish: runs-on: ubuntu-20.04 - needs: [lint, test] + needs: [lint, test, website] if: github.event_name != 'pull_request' steps: - name: Checkout current branch From 6c0ee9ccd6d287a29c2a26e1e01adb3f0d46b2f0 Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Wed, 16 Nov 2022 15:05:45 +0330 Subject: [PATCH 6/8] generate site workflow. --- .github/workflows/site.yml | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .github/workflows/site.yml diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml new file mode 100644 index 0000000..ccd31cf --- /dev/null +++ b/.github/workflows/site.yml @@ -0,0 +1,28 @@ +# This file was autogenerated using `zio-sbt` via `sbt generateGithubWorkflow` +# task and should be included in the git repository. Please do not edit +# it manually. + +name: website + +on: + release: + types: [ published ] + +jobs: + publish-docs: + runs-on: ubuntu-20.04 + timeout-minutes: 30 + steps: + - uses: actions/checkout@v3.1.0 + with: + fetch-depth: 0 + - name: Setup Scala and Java + uses: olafurpg/setup-scala@v13 + - uses: actions/setup-node@v3 + with: + node-version: '16.x' + registry-url: 'https://registry.npmjs.org' + - name: Publishing Docs to NPM Registry + run: sbt sbt/publishToNpm + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} From 50fbae1760dff98b14f1cc7515e22ed257e3a79c Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Wed, 16 Nov 2022 15:35:50 +0330 Subject: [PATCH 7/8] a commit to triger the ci again. --- docs/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index ba46fdc..4e53ff7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -73,8 +73,7 @@ stream.toPublisher.flatMap { publisher => `toSubscriber` returns a `Subscriber` and an `IO` which completes with the result of running the `Sink` or the error if the `Publisher` fails. -A `Sink` used as a `Subscriber` buffers up to `qSize` elements. If possible, `qSize` should be -a power of two for best performance. The default is 16. +A `Sink` used as a `Subscriber` buffers up to `qSize` elements. If possible, `qSize` should be a power of two for best performance. The default is 16. ```scala val sink = Sink.collectAll[Integer] From 4cf186a0fc75f8186ab3ac735d6516299997647e Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Wed, 16 Nov 2022 15:42:08 +0330 Subject: [PATCH 8/8] another commit to run ci. --- docs/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 4e53ff7..c71ee47 100644 --- a/docs/index.md +++ b/docs/index.md @@ -71,8 +71,7 @@ stream.toPublisher.flatMap { publisher => ### Sink to Subscriber -`toSubscriber` returns a `Subscriber` and an `IO` which completes with the result of running the -`Sink` or the error if the `Publisher` fails. +`toSubscriber` returns a `Subscriber` and an `IO` which completes with the result of running the `Sink` or the error if the `Publisher` fails. A `Sink` used as a `Subscriber` buffers up to `qSize` elements. If possible, `qSize` should be a power of two for best performance. The default is 16. ```scala