New: Extract from Laminar repo

- Add various build files, update docs, make changelog, etc. - Change package name to com.raquo.airstream
raquo · Apr 13, 2018 · 469ad52 · 469ad52
1 parent 24fd261
commit 469ad52
Show file tree

Hide file tree

Showing 67 changed files with 301 additions and 164 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,5 @@
+target
+.idea
+
+.DS_Store
+
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,5 @@
+# Changelog
+
+#### v0.1 – Apr 2018
+
+Initial release. First version extracted from Laminar repo.
diff --git a/LICENSE.md b/LICENSE.md
@@ -0,0 +1,10 @@
+# The MIT License (MIT)
+
+Copyright 2018 Nikita Gazarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
diff --git a/.../laminar/experimental/airstream/README.md → README.md b/.../laminar/experimental/airstream/README.md → README.md
@@ -1,5 +1,10 @@
 # Airstream
 
+![Maven Central](https://img.shields.io/maven-central/v/com.raquo/airstream_sjs0.6_2.12.svg)
+
+```
+"com.raquo" %%% "airstream" % "0.1"
+```
 
 Airstream is a small state propagation and streaming library. Primary differences from other solutions:
 
@@ -19,16 +24,44 @@ Airstream has a very generic design, but is primarily intended to serve as a rea
 I created Airstream because I found existing solutions were not suitable for building reactive UI components. My original need for Airstream is to replace the old reactive layer of [Laminar](https://github.com/raquo/Laminar), but I'll be happy to see it used by other reactive UI libraries as well. Laminar in general is well modularized, and you can definitely reuse other bits and pieces of it, for example [Scala DOM Types](https://github.com/raquo/scala-dom-types).
 
 
-## Community
 
-Please use [github issues](https://github.com/raquo/Laminar/issues) for bugs, feature requests, as well as all kinds of discussions, including questions on usage and roadmap. I think this will work better than spreading thin across gitter / stackoverflow / etc. You can _watch_ this project on github to get issue updates if you're interested in following discussions.
+## Table of Contents
 
-Note: Airstream is only temporarily located in Laminar's repo. This is just for my own rapid development convenience. While Laminar does depend on Airstream, Airstream has no knowledge of Laminar at all. Airstream is designed as an independent project, and I will move it out when the next version of Laminar is released.
+* [Community](#community)
+* [Documentation](#documentation)
+  * [EventStream](#eventstream)
+  * [Laziness](#laziness)
+    * [Starting Observables](#starting-observables)
+    * [Stopping Observables](#stopping-observables)
+    * [Memory Management Implications](#memory-management-implications)
+  * [Signal](#signal)
+  * [State](#state)
+  * [Relationship between EventStream, Signal, and State](#relationship-between-eventstream-signal-and-state)
+  * [Ownership](#ownership)
+    * [Ownership & Memory Management](#ownership-memory-management)
+      * [State Considerations](#state-considerations)
+      * [Subscription Considerations](#subscription-considerations)
+  * [Sources of Events](#sources-of-events)
+    * [EventStream.fromSeq](#eventstream-fromseq)
+    * [EventStream.periodic](#eventstream-periodic)
+    * [EventBus](#eventbus)
+    * [Var](#var)
+    * [Custom Observables](#custom-observables)
+  * [FRP Glitches](#frp-glitches)
+    * [Other Libraries](#other-libraries)
+    * [Topological Rank](#topological-rank)
+    * [Transactions](#transactions)
+    * [Merge Glitch-By-Design](#merge-glitch-by-design)
+  * [Operators](#operators)
+  * [Error Handling](#error-handling)
+* [Limitations](#limitations)
+* [My Related Projects](#my-related-projects)
 
 
-## Table of Contents
 
-TODO[Docs] compile this when the docs stabilize
+## Community
+
+Please use [github issues](https://github.com/raquo/Airstream/issues) for bugs, feature requests, as well as all kinds of discussions, including questions on usage and roadmap. I think this will work better than spreading thin across gitter / stackoverflow / etc. You can _watch_ this project on github to get issue updates if you're interested in following discussions.
 
 
 
@@ -280,7 +313,7 @@ In practice this is not a problem because everyone knows not to keep references
 We understand how events propagate through streams, signals and state, but the events in Airstream have to originate somewhere, right?
 
 
-#### `EventStream.fromSeq`
+#### EventStream.fromSeq
 
 ```scala
 object EventStream {
@@ -294,12 +327,12 @@ This method creates an event stream that synchronously emits events from the pro
 Each event is emitted in a separate transaction, meaning that the propagation of the previous event will fully complete before the propagation of the new event starts.
 
 
-#### `EventStream.periodic`
+#### EventStream.periodic
 
 TODO[API] – implement this.
 
 
-#### `EventBus`
+#### EventBus
 
 `new EventBus[MyEvent]` is the general-purpose way to create a stream on which you can manually trigger events. EventBus exposes two properties:
 
@@ -331,7 +364,7 @@ val barWriter: WriteBus[Bar] = eventBus.writer.filterWriter(isGoodFoo).mapWriter
 Now you can send `Bar` events to `barWriter`, and they will appear in `eventBus` processed with `barToFoo` then and filtered by `isGoodFoo`. This is useful when you want to get events from a child component, but the child component does not or should not know what `Foo` is. Generally if you don't need such separation of concerns, you can just `map`/`filter` the stream that's feeding the EventBus instead.
 
 
-#### `Var`
+#### Var
 
 `Var(initialValue)` is a State that you can update manually. It exposes a `writer`, similar to `EventBus`.
 
@@ -447,7 +480,7 @@ TODO[API] Error handling is not yet implemented, but will be soon, it's a priori
 ## My Related Projects
 
 - [Laminar](https://github.com/raquo/Laminar) – Efficient reactive UI library for Scala.js that uses Airstream
-- [XStream.scala](https://github.com/raquo/XStream.scala) – Scala.js interface to the streaming library previously used by Laminar
+- [XStream.scala](https://github.com/raquo/XStream.scala) – streaming library used by Laminar before Airstream
 
 Other building blocks of Laminar:
 
@@ -465,4 +498,4 @@ Nikita Gazarov – [raquo.com](http://raquo.com)
 
 ## License
 
-Airstream is provided under the [MIT license](https://github.com/raquo/Laminar/blob/master/LICENSE.md).
+Airstream is provided under the [MIT license](https://github.com/raquo/Airstream/blob/master/LICENSE.md).
diff --git a/build.sbt b/build.sbt
@@ -0,0 +1,15 @@
+enablePlugins(ScalaJSPlugin)
+
+enablePlugins(ScalaJSBundlerPlugin)
+
+libraryDependencies ++= Seq(
+  "org.scala-js" %%% "scalajs-dom" % "0.9.4", // This has no runtime cost. We only use it for `Debug.log` // @TODO[Elegance] Reconsider
+  "org.scalatest" %%% "scalatest" % "3.0.4" % Test
+)
+
+useYarn := true
+
+scalaJSUseMainModuleInitializer := true
+
+emitSourceMaps := false
+
diff --git a/jitpack.yml b/jitpack.yml
@@ -0,0 +1,2 @@
+install:
+   - sbt +publishM2
diff --git a/project/build.properties b/project/build.properties
@@ -0,0 +1 @@
+sbt.version = 0.13.15
diff --git a/project/plugins.sbt b/project/plugins.sbt
@@ -0,0 +1,12 @@
+logLevel := Level.Warn
+
+addSbtPlugin("org.scala-js" % "sbt-scalajs" % "0.6.19")
+
+addSbtPlugin("ch.epfl.scala" % "sbt-scalajs-bundler" % "0.7.0")
+
+addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.0.0")
+
+addSbtPlugin("com.github.gseitz" % "sbt-release" % "1.0.4")
+
+addSbtPlugin("org.xerial.sbt" % "sbt-sonatype" % "1.1")
+
diff --git a/release.sbt b/release.sbt
@@ -0,0 +1,52 @@
+name := "Airstream"
+
+normalizedName := "airstream"
+
+organization := "com.raquo"
+
+scalaVersion := "2.12.4"
+
+crossScalaVersions := Seq("2.11.12", "2.12.4")
+
+homepage := Some(url("https://github.com/raquo/Airstream"))
+
+licenses += ("MIT", url("https://github.com/raquo/Airstream/blob/master/LICENSE.md"))
+
+scmInfo := Some(
+  ScmInfo(
+    url("https://github.com/raquo/Airstream"),
+    "scm:[email protected]/raquo/Airstream.git"
+  )
+)
+
+developers := List(
+  Developer(
+    id = "raquo",
+    name = "Nikita Gazarov",
+    email = "[email protected]",
+    url = url("http://raquo.com")
+  )
+)
+
+sonatypeProfileName := "com.raquo"
+
+publishMavenStyle := true
+
+publishArtifact in Test := false
+
+publishTo := {
+  val nexus = "https://oss.sonatype.org/"
+  if (isSnapshot.value)
+    Some("snapshots" at nexus + "content/repositories/snapshots")
+  else
+    Some("releases"  at nexus + "service/local/staging/deploy/maven2")
+}
+
+releaseCrossBuild := true
+
+pomIncludeRepository := { _ => false }
+
+useGpg := true
+
+releasePublishArtifactsAction := PgpKeys.publishSigned.value
+
diff --git a/...tal/airstream/core/InternalObserver.scala → ...quo/airstream/core/InternalObserver.scala b/...tal/airstream/core/InternalObserver.scala → ...quo/airstream/core/InternalObserver.scala
@@ -1,4 +1,4 @@
-package com.raquo.laminar.experimental.airstream.core
+package com.raquo.airstream.core
 
 trait InternalObserver[-A] {
 

diff --git a/...ental/airstream/core/LazyObservable.scala → ...raquo/airstream/core/LazyObservable.scala b/...ental/airstream/core/LazyObservable.scala → ...raquo/airstream/core/LazyObservable.scala
@@ -1,6 +1,6 @@
-package com.raquo.laminar.experimental.airstream.core
+package com.raquo.airstream.core
 
-import com.raquo.laminar.experimental.airstream.ownership.Owner
+import com.raquo.airstream.ownership.Owner
 
 /** LazyObservable only starts when it gets its first observer (internal or external),
   * and stops when it loses its last observer (again, internal or external).

diff --git a/...tal/airstream/core/MemoryObservable.scala → ...quo/airstream/core/MemoryObservable.scala b/...tal/airstream/core/MemoryObservable.scala → ...quo/airstream/core/MemoryObservable.scala
@@ -1,7 +1,7 @@
-package com.raquo.laminar.experimental.airstream.core
+package com.raquo.airstream.core
 
-import com.raquo.laminar.experimental.airstream.eventstream.{EventStream, MapEventStream}
-import com.raquo.laminar.experimental.airstream.ownership.Owner
+import com.raquo.airstream.eventstream.{EventStream, MapEventStream}
+import com.raquo.airstream.ownership.Owner
 
 /** An observable that remembers its current value */
 trait MemoryObservable[+A] extends Observable[A] {

diff --git a/...erimental/airstream/core/Observable.scala → ...com/raquo/airstream/core/Observable.scala b/...erimental/airstream/core/Observable.scala → ...com/raquo/airstream/core/Observable.scala
@@ -1,9 +1,9 @@
-package com.raquo.laminar.experimental.airstream.core
+package com.raquo.airstream.core
 
-import com.raquo.laminar.experimental.airstream.eventstream.{EventStream, FlattenEventStream}
-import com.raquo.laminar.experimental.airstream.ownership.{Owned, Owner}
-import com.raquo.laminar.experimental.airstream.state.State
-import com.raquo.laminar.experimental.airstream.util.GlobalCounter
+import com.raquo.airstream.eventstream.{EventStream, FlattenEventStream}
+import com.raquo.airstream.ownership.{Owned, Owner}
+import com.raquo.airstream.state.State
+import com.raquo.airstream.util.GlobalCounter
 
 import scala.scalajs.js
 

diff --git a/...rimental/airstream/core/Observation.scala → ...om/raquo/airstream/core/Observation.scala b/...rimental/airstream/core/Observation.scala → ...om/raquo/airstream/core/Observation.scala
@@ -1,3 +1,3 @@
-package com.raquo.laminar.experimental.airstream.core
+package com.raquo.airstream.core
 
 class Observation[A](val observable: Observable[A], val value: A)
diff --git a/...xperimental/airstream/core/Observer.scala → ...a/com/raquo/airstream/core/Observer.scala b/...xperimental/airstream/core/Observer.scala → ...a/com/raquo/airstream/core/Observer.scala
@@ -1,4 +1,4 @@
-package com.raquo.laminar.experimental.airstream.core
+package com.raquo.airstream.core
 
 import org.scalajs.dom
 

diff --git a/...imental/airstream/core/Subscription.scala → ...m/raquo/airstream/core/Subscription.scala b/...imental/airstream/core/Subscription.scala → ...m/raquo/airstream/core/Subscription.scala
@@ -1,6 +1,6 @@
-package com.raquo.laminar.experimental.airstream.core
+package com.raquo.airstream.core
 
-import com.raquo.laminar.experimental.airstream.ownership.{Owned, Owner}
+import com.raquo.airstream.ownership.{Owned, Owner}
 
 abstract class Subscription private[core] (
   override protected[this] val owner: Owner

diff --git a/...ental/airstream/core/SyncObservable.scala → ...raquo/airstream/core/SyncObservable.scala b/...ental/airstream/core/SyncObservable.scala → ...raquo/airstream/core/SyncObservable.scala
@@ -1,4 +1,4 @@
-package com.raquo.laminar.experimental.airstream.core
+package com.raquo.airstream.core
 
 /** Observable that can become pending for the purpose of synchronization */
 trait SyncObservable[+A] extends Observable[A] {

diff --git a/...rimental/airstream/core/Transaction.scala → ...om/raquo/airstream/core/Transaction.scala b/...rimental/airstream/core/Transaction.scala → ...om/raquo/airstream/core/Transaction.scala
@@ -1,6 +1,6 @@
-package com.raquo.laminar.experimental.airstream.core
+package com.raquo.airstream.core
 
-import com.raquo.laminar.experimental.airstream.util.{GlobalCounter, JsPriorityQueue}
+import com.raquo.airstream.util.{GlobalCounter, JsPriorityQueue}
 import org.scalajs.dom
 
 import scala.scalajs.js

diff --git a/...imental/airstream/eventbus/EventBus.scala → ...m/raquo/airstream/eventbus/EventBus.scala b/...imental/airstream/eventbus/EventBus.scala → ...m/raquo/airstream/eventbus/EventBus.scala
@@ -1,6 +1,6 @@
-package com.raquo.laminar.experimental.airstream.eventbus
+package com.raquo.airstream.eventbus
 
-import com.raquo.laminar.experimental.airstream.eventstream.EventStream
+import com.raquo.airstream.eventstream.EventStream
 
 /** EventBus combines a WriteBus and a stream of its events.
   *

diff --git a/...l/airstream/eventbus/EventBusSource.scala → ...o/airstream/eventbus/EventBusSource.scala b/...l/airstream/eventbus/EventBusSource.scala → ...o/airstream/eventbus/EventBusSource.scala
@@ -1,7 +1,7 @@
-package com.raquo.laminar.experimental.airstream.eventbus
+package com.raquo.airstream.eventbus
 
-import com.raquo.laminar.experimental.airstream.eventstream.EventStream
-import com.raquo.laminar.experimental.airstream.ownership.{Owned, Owner}
+import com.raquo.airstream.eventstream.EventStream
+import com.raquo.airstream.ownership.{Owned, Owner}
 
 // @TODO[Naming] Maybe something with "Subscription"? Although nah...
 class EventBusSource[A](

diff --git a/...l/airstream/eventbus/EventBusStream.scala → ...o/airstream/eventbus/EventBusStream.scala b/...l/airstream/eventbus/EventBusStream.scala → ...o/airstream/eventbus/EventBusStream.scala
@@ -1,7 +1,7 @@
-package com.raquo.laminar.experimental.airstream.eventbus
+package com.raquo.airstream.eventbus
 
-import com.raquo.laminar.experimental.airstream.core.{InternalObserver, Transaction}
-import com.raquo.laminar.experimental.airstream.eventstream.EventStream
+import com.raquo.airstream.core.{InternalObserver, Transaction}
+import com.raquo.airstream.eventstream.EventStream
 import org.scalajs.dom
 
 import scala.scalajs.js

diff --git a/...imental/airstream/eventbus/WriteBus.scala → ...m/raquo/airstream/eventbus/WriteBus.scala b/...imental/airstream/eventbus/WriteBus.scala → ...m/raquo/airstream/eventbus/WriteBus.scala
@@ -1,8 +1,8 @@
-package com.raquo.laminar.experimental.airstream.eventbus
+package com.raquo.airstream.eventbus
 
-import com.raquo.laminar.experimental.airstream.core.{Observer, Transaction}
-import com.raquo.laminar.experimental.airstream.eventstream.EventStream
-import com.raquo.laminar.experimental.airstream.ownership.Owner
+import com.raquo.airstream.core.{Observer, Transaction}
+import com.raquo.airstream.eventstream.EventStream
+import com.raquo.airstream.ownership.Owner
 
 class WriteBus[A] extends Observer[A] {
 

diff --git a/...eam/eventstream/CombineEventStream2.scala → ...eam/eventstream/CombineEventStream2.scala b/...eam/eventstream/CombineEventStream2.scala → ...eam/eventstream/CombineEventStream2.scala
@@ -1,6 +1,6 @@
-package com.raquo.laminar.experimental.airstream.eventstream
+package com.raquo.airstream.eventstream
 
-import com.raquo.laminar.experimental.airstream.features.{CombineObservable, InternalParentObserver}
+import com.raquo.airstream.features.{CombineObservable, InternalParentObserver}
 
 /** Stream that combines the latest values from two streams into a tuple.
   * Only fires after both streams have sent a value.

diff --git a/...eam/eventstream/DebounceEventStream.scala → ...eam/eventstream/DebounceEventStream.scala b/...eam/eventstream/DebounceEventStream.scala → ...eam/eventstream/DebounceEventStream.scala
@@ -1,7 +1,7 @@
-package com.raquo.laminar.experimental.airstream.eventstream
+package com.raquo.airstream.eventstream
 
-import com.raquo.laminar.experimental.airstream.core.Transaction
-import com.raquo.laminar.experimental.airstream.features.SingleParentObservable
+import com.raquo.airstream.core.Transaction
+import com.raquo.airstream.features.SingleParentObservable
 
 import scala.scalajs.js
 import scala.scalajs.js.timers.SetTimeoutHandle

diff --git a/...stream/eventstream/DelayEventStream.scala → ...stream/eventstream/DelayEventStream.scala b/...stream/eventstream/DelayEventStream.scala → ...stream/eventstream/DelayEventStream.scala
@@ -1,7 +1,7 @@
-package com.raquo.laminar.experimental.airstream.eventstream
+package com.raquo.airstream.eventstream
 
-import com.raquo.laminar.experimental.airstream.features.SingleParentObservable
-import com.raquo.laminar.experimental.airstream.core.{Observable, Transaction}
+import com.raquo.airstream.features.SingleParentObservable
+import com.raquo.airstream.core.{Observable, Transaction}
 
 import scala.scalajs.js
 

diff --git a/...l/airstream/eventstream/EventStream.scala → ...o/airstream/eventstream/EventStream.scala b/...l/airstream/eventstream/EventStream.scala → ...o/airstream/eventstream/EventStream.scala
@@ -1,9 +1,9 @@
-package com.raquo.laminar.experimental.airstream.eventstream
+package com.raquo.airstream.eventstream
 
-import com.raquo.laminar.experimental.airstream.core.{LazyObservable, MemoryObservable}
-import com.raquo.laminar.experimental.airstream.ownership.Owner
-import com.raquo.laminar.experimental.airstream.signal.{FoldSignal, Signal, SignalFromEventStream}
-import com.raquo.laminar.experimental.airstream.state.{MapState, State}
+import com.raquo.airstream.core.{LazyObservable, MemoryObservable}
+import com.raquo.airstream.ownership.Owner
+import com.raquo.airstream.signal.{FoldSignal, Signal, SignalFromEventStream}
+import com.raquo.airstream.state.{MapState, State}
 
 trait EventStream[+A] extends LazyObservable[A] {
 

diff --git a/...tream/eventstream/FilterEventStream.scala → ...tream/eventstream/FilterEventStream.scala b/...tream/eventstream/FilterEventStream.scala → ...tream/eventstream/FilterEventStream.scala
@@ -1,7 +1,7 @@
-package com.raquo.laminar.experimental.airstream.eventstream
+package com.raquo.airstream.eventstream
 
-import com.raquo.laminar.experimental.airstream.features.SingleParentObservable
-import com.raquo.laminar.experimental.airstream.core.{Observer, Transaction}
+import com.raquo.airstream.features.SingleParentObservable
+import com.raquo.airstream.core.{Observer, Transaction}
 
 /** This stream fires a subset of the events fired by its parent */
 class FilterEventStream[A](