From e950d6ba2deafbd35313f8c295668818dcaf7ee7 Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Sun, 22 Jan 2023 19:27:06 +0330 Subject: [PATCH] Update Introduction Section (#352) * update introduction section. * remove dependency to the project itself. * update scala versions. * remove extra option for semanticdb. * Revert "update scala versions." This reverts commit 81213ad5fbfa03b16a48d2cfa9836e57f7e89323. * create root project with subprojects. * add scaladoc support. * fmt. * ignore publishing docs. * Revert "ignore publishing docs." This reverts commit 612420304385cfb0fca33d6987c7564ba907fa87. --- .github/workflows/site.yml | 114 ++++++++++++---- README.md | 122 ++++++++++++++++-- build.sbt | 18 ++- docs/index.md | 16 ++- docs/sidebars.js | 8 +- project/BuildHelper.scala | 13 +- project/plugins.sbt | 2 +- .../interop/reactivestreams/Adapters.scala | 0 .../zio/interop/reactivestreams/package.scala | 0 .../PublisherToStreamSpec.scala | 0 .../SinkToSubscriberSpec.scala | 0 .../StreamToPublisherSpec.scala | 0 .../SubscriberToSinkSpec.scala | 0 13 files changed, 239 insertions(+), 54 deletions(-) rename {src => zio-interop-reactivestreams/src}/main/scala/zio/interop/reactivestreams/Adapters.scala (100%) rename {src => zio-interop-reactivestreams/src}/main/scala/zio/interop/reactivestreams/package.scala (100%) rename {src => zio-interop-reactivestreams/src}/test/scala/zio/interop/reactivestreams/PublisherToStreamSpec.scala (100%) rename {src => zio-interop-reactivestreams/src}/test/scala/zio/interop/reactivestreams/SinkToSubscriberSpec.scala (100%) rename {src => zio-interop-reactivestreams/src}/test/scala/zio/interop/reactivestreams/StreamToPublisherSpec.scala (100%) rename {src => zio-interop-reactivestreams/src}/test/scala/zio/interop/reactivestreams/SubscriberToSinkSpec.scala (100%) diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml index 9a0cbf9..cd9e602 100644 --- a/.github/workflows/site.yml +++ b/.github/workflows/site.yml @@ -1,28 +1,96 @@ -# 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. +# This file was autogenerated using `zio-sbt-website` via `sbt generateGithubWorkflow` +# task and should be included in the git repository. Please do not edit it manually. -name: website - -on: +name: Website +'on': + workflow_dispatch: {} release: - types: [ published ] - + types: + - published + push: + branches: + - master + pull_request: {} jobs: + build: + name: Build and Test + runs-on: ubuntu-latest + if: ${{ github.event_name == 'pull_request' }} + steps: + - name: Git Checkout + uses: actions/checkout@v3.3.0 + with: + fetch-depth: '0' + - name: Setup Scala + uses: actions/setup-java@v3.9.0 + with: + distribution: temurin + java-version: 17 + check-latest: true + - name: Check that site workflow is up to date + run: sbt docs/checkGithubWorkflow + - name: Check artifacts build process + run: sbt +publishLocal + - name: Check website build process + run: sbt docs/buildWebsite publish-docs: - runs-on: ubuntu-20.04 - timeout-minutes: 30 + name: Publish Docs + runs-on: ubuntu-latest + if: ${{ ((github.event_name == 'release') && (github.event.action == 'published')) || (github.event_name == 'workflow_dispatch') }} 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 docs/publishToNpm - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + - name: Git Checkout + uses: actions/checkout@v3.3.0 + with: + fetch-depth: '0' + - name: Setup Scala + uses: actions/setup-java@v3.9.0 + with: + distribution: temurin + java-version: 17 + check-latest: true + - name: Setup NodeJs + uses: actions/setup-node@v3 + with: + node-version: 16.x + registry-url: https://registry.npmjs.org + - name: Publish Docs to NPM Registry + run: sbt docs/publishToNpm + env: + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + generate-readme: + name: Generate README + runs-on: ubuntu-latest + if: ${{ (github.event_name == 'push') || ((github.event_name == 'release') && (github.event_name == 'published')) }} + steps: + - name: Git Checkout + uses: actions/checkout@v3.3.0 + with: + ref: ${{ github.head_ref }} + fetch-depth: '0' + - name: Setup Scala + uses: actions/setup-java@v3.9.0 + with: + distribution: temurin + java-version: 17 + check-latest: true + - name: Generate Readme + run: sbt docs/generateReadme + - name: Commit Changes + run: | + git config --local user.email "github-actions[bot]@users.noreply.github.com" + git config --local user.name "github-actions[bot]" + git add README.md + git commit -m "Update README.md" || echo "No changes to commit" + - name: Create Pull Request + uses: peter-evans/create-pull-request@v4.2.3 + with: + body: |- + Autogenerated changes after running the `sbt docs/generateReadme` command of the [zio-sbt-website](https://zio.dev/zio-sbt) plugin. + + I will automatically update the README.md file whenever there is new change for README.md, e.g. + - After each release, I will update the version in the installation section. + - After any changes to the "docs/index.md" file, I will update the README.md file accordingly. + branch: zio-sbt-website/update-readme + commit-message: Update README.md + delete-branch: true + title: Update README.md diff --git a/README.md b/README.md index 24c9c7c..78d1c2d 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,115 @@ -# Interop reactive streams +[//]: # (This file was autogenerated using `zio-sbt-website` plugin via `sbt generateReadme` command.) +[//]: # (So please do not edit it manually. Instead, change "docs/index.md" file or sbt setting keys) +[//]: # (e.g. "readmeDocumentation" and "readmeSupport".) -[![Project stage][Stage]][Stage-Page] -![CI][Badge-CI] -[![Releases][Badge-SonatypeReleases]][Link-SonatypeReleases] -[![Snapshots][Badge-SonatypeSnapshots]][Link-SonatypeSnapshots] +# ZIO Interop Reactive Streams This library provides an interoperability layer between ZIO and reactive streams. +[![Production Ready](https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/interop-reactive-streams/workflows/CI/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-interop-reactivestreams_2.13.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-interop-reactivestreams_2.13/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-interop-reactivestreams_2.13.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-interop-reactivestreams_2.13/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-interop-reactivestreams-docs_2.13/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-interop-reactivestreams-docs_2.13) [![ZIO Interop Reactive Streams](https://img.shields.io/github/stars/zio/interop-reactive-streams?style=social)](https://github.com/zio/interop-reactive-streams) + +## Introduction + +**ZIO** integrates with [Reactive Streams](http://reactive-streams.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. + +## Installation + +In order to use this library, we need to add the following line in our `build.sbt` file: + +```scala +libraryDependencies += "dev.zio" %% "zio-interop-reactive-streams" % "2.0.0" +``` + +## 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._ +``` + +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.toZIOStream(qSize = 16) +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 `toZIOSink` returns a tuple of a callback and a `Sink`. The callback must be used to signal `Stream` failure. The type parameter on `toZIOSink` is the error type of *the Stream*. + +```scala +val asSink = subscriber.toZIOSink[Throwable] +val failingStream = ZStream.range(3, 13) ++ ZStream.fail(new RuntimeException("boom!")) +ZIO.scoped { + asSink.flatMap { case (signalError, sink) => // FIXME + failingStream.run(sink).catchAll(signalError) + } +} +``` + +### Stream to Publisher + +```scala +val stream = Stream.range(3, 13) +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] +ZIO.scoped { + sink.toSubscriber(qSize = 16).flatMap { case (subscriber, result) => + UIO(publisher.subscribe(subscriber)) *> result + } +} +``` + ## Documentation -[Homepage](https://zio.dev/zio-interop-reactivestreams) +Learn more on the [ZIO Interop Reactive Streams homepage](https://zio.dev/zio-interop-reactivestreams)! + +## Contributing + +For the general guidelines, see ZIO [contributor's guide](https://zio.dev/about/contributing). + +## Code of Conduct + +See the [Code of Conduct](https://zio.dev/about/code-of-conduct) + +## Support + +Come chat with us on [![Badge-Discord]][Link-Discord]. + +[Badge-Discord]: https://img.shields.io/discord/629491597070827530?logo=discord "chat on discord" +[Link-Discord]: https://discord.gg/2ccFBr4 "Discord" + +## License -[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" -[Badge-SonatypeSnapshots]: https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-interop-reactivestreams_2.12.svg "Sonatype Snapshots" -[Link-Circle]: https://circleci.com/gh/zio/interop-reactive-streams/tree/master -[Link-SonatypeReleases]: https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-interop-reactivestreams_2.12/ "Sonatype Releases" -[Link-SonatypeSnapshots]: https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-interop-reactivestreams_2.12/ "Sonatype Snapshots" -[Stage]: https://img.shields.io/badge/Project%20Stage-Production%20Ready-brightgreen.svg -[Stage-Page]: https://github.com/zio/zio/wiki/Project-Stages +[License](LICENSE) diff --git a/build.sbt b/build.sbt index 97dacd4..814f914 100644 --- a/build.sbt +++ b/build.sbt @@ -40,8 +40,14 @@ val zioVersion = "2.0.5" val rsVersion = "1.0.4" val collCompatVersion = "2.7.0" +lazy val root = + project + .in(file(".")) + .settings(publish / skip := true) + .aggregate(interopReactiveStreams, docs) + lazy val interopReactiveStreams = project - .in(file(".")) + .in(file("zio-interop-reactivestreams")) .enablePlugins(BuildInfoPlugin) .settings(buildInfoSettings("zio.interop.reactivestreams")) .settings(stdSettings("zio-interop-reactivestreams")) @@ -69,13 +75,17 @@ lazy val interopReactiveStreams = project lazy val docs = project .in(file("zio-interop-reactivestreams-docs")) .settings( - publish / skip := true, - moduleName := "zio-interop-reactivestreams-docs", + moduleName := "zio-interop-reactivestreams-docs", scalacOptions -= "-Yno-imports", scalacOptions -= "-Xfatal-warnings", libraryDependencies ++= Seq( "dev.zio" %% "zio" % zioVersion - ) + ), + projectName := "ZIO Interop Reactive Streams", + mainModuleName := (interopReactiveStreams / moduleName).value, + projectStage := ProjectStage.ProductionReady, + ScalaUnidoc / unidoc / unidocProjectFilter := inProjects(interopReactiveStreams), + docsPublishBranch := "master" ) .dependsOn(interopReactiveStreams) .enablePlugins(WebsitePlugin) diff --git a/docs/index.md b/docs/index.md index c71ee47..b18924e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,11 +6,19 @@ sidebar_label: "ZIO Interop Reactive Streams" This library provides an interoperability layer between ZIO and reactive streams. -## Reactive Streams `Producer` and `Subscriber` +@PROJECT_BADGES@ -**ZIO** integrates with [Reactive Streams](http://reactive-streams.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. +## Introduction + +**ZIO** integrates with [Reactive Streams](http://reactive-streams.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. + +## Installation + +In order to use this library, we need to add the following line in our `build.sbt` file: + +```scala +libraryDependencies += "dev.zio" %% "zio-interop-reactive-streams" % "@VERSION@" +``` ## Examples diff --git a/docs/sidebars.js b/docs/sidebars.js index b485cd2..0796362 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,6 +1,12 @@ const sidebars = { sidebar: [ - "index" + { + type: "category", + label: "ZIO Interop Reactive Streams", + collapsed: false, + link: { type: "doc", id: "index" }, + items: [ ] + } ] }; diff --git a/project/BuildHelper.scala b/project/BuildHelper.scala index b001821..8138191 100644 --- a/project/BuildHelper.scala +++ b/project/BuildHelper.scala @@ -131,13 +131,12 @@ object BuildHelper { } def stdSettings(prjName: String) = Seq( - name := s"$prjName", - crossScalaVersions := Seq(Scala211, Scala212, Scala213), - ThisBuild / scalaVersion := Scala213, - scalacOptions := stdOptions ++ extraOptions(scalaVersion.value, optimize = !isSnapshot.value), - semanticdbEnabled := !(scalaVersion.value == ScalaDotty), // enable SemanticDB - semanticdbOptions += "-P:semanticdb:synthetics:on", - semanticdbVersion := scalafixSemanticdb.revision, // use Scalafix compatible version + name := s"$prjName", + crossScalaVersions := Seq(Scala211, Scala212, Scala213), + ThisBuild / scalaVersion := Scala213, + scalacOptions := stdOptions ++ extraOptions(scalaVersion.value, optimize = !isSnapshot.value), + semanticdbEnabled := !(scalaVersion.value == ScalaDotty), // enable SemanticDB + semanticdbVersion := scalafixSemanticdb.revision, // use Scalafix compatible version ThisBuild / scalafixScalaBinaryVersion := CrossVersion.binaryScalaVersion(scalaVersion.value), ThisBuild / scalafixDependencies ++= List( "com.github.liancheng" %% "organize-imports" % "0.6.0", diff --git a/project/plugins.sbt b/project/plugins.sbt index 0b21416..7878b2f 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -6,6 +6,6 @@ addSbtPlugin("com.github.cb372" % "sbt-explicit-dependencies" % "0.2.16") addSbtPlugin("org.portable-scala" % "sbt-crossproject" % "1.2.0") addSbtPlugin("de.heikoseeberger" % "sbt-header" % "5.9.0") addSbtPlugin("org.scalameta" % "sbt-scalafmt" % "2.5.0") -addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.0.0+84-6fd7d64e-SNAPSHOT") +addSbtPlugin("dev.zio" % "zio-sbt-website" % "0.3.2") resolvers += Resolver.sonatypeRepo("public") diff --git a/src/main/scala/zio/interop/reactivestreams/Adapters.scala b/zio-interop-reactivestreams/src/main/scala/zio/interop/reactivestreams/Adapters.scala similarity index 100% rename from src/main/scala/zio/interop/reactivestreams/Adapters.scala rename to zio-interop-reactivestreams/src/main/scala/zio/interop/reactivestreams/Adapters.scala diff --git a/src/main/scala/zio/interop/reactivestreams/package.scala b/zio-interop-reactivestreams/src/main/scala/zio/interop/reactivestreams/package.scala similarity index 100% rename from src/main/scala/zio/interop/reactivestreams/package.scala rename to zio-interop-reactivestreams/src/main/scala/zio/interop/reactivestreams/package.scala diff --git a/src/test/scala/zio/interop/reactivestreams/PublisherToStreamSpec.scala b/zio-interop-reactivestreams/src/test/scala/zio/interop/reactivestreams/PublisherToStreamSpec.scala similarity index 100% rename from src/test/scala/zio/interop/reactivestreams/PublisherToStreamSpec.scala rename to zio-interop-reactivestreams/src/test/scala/zio/interop/reactivestreams/PublisherToStreamSpec.scala diff --git a/src/test/scala/zio/interop/reactivestreams/SinkToSubscriberSpec.scala b/zio-interop-reactivestreams/src/test/scala/zio/interop/reactivestreams/SinkToSubscriberSpec.scala similarity index 100% rename from src/test/scala/zio/interop/reactivestreams/SinkToSubscriberSpec.scala rename to zio-interop-reactivestreams/src/test/scala/zio/interop/reactivestreams/SinkToSubscriberSpec.scala diff --git a/src/test/scala/zio/interop/reactivestreams/StreamToPublisherSpec.scala b/zio-interop-reactivestreams/src/test/scala/zio/interop/reactivestreams/StreamToPublisherSpec.scala similarity index 100% rename from src/test/scala/zio/interop/reactivestreams/StreamToPublisherSpec.scala rename to zio-interop-reactivestreams/src/test/scala/zio/interop/reactivestreams/StreamToPublisherSpec.scala diff --git a/src/test/scala/zio/interop/reactivestreams/SubscriberToSinkSpec.scala b/zio-interop-reactivestreams/src/test/scala/zio/interop/reactivestreams/SubscriberToSinkSpec.scala similarity index 100% rename from src/test/scala/zio/interop/reactivestreams/SubscriberToSinkSpec.scala rename to zio-interop-reactivestreams/src/test/scala/zio/interop/reactivestreams/SubscriberToSinkSpec.scala