Docs and CI

Author: jamesdbrock

.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up a PureScript toolchain
+        uses: purescript-contrib/setup-purescript@main
+        with:
+          purescript: "unstable"
+          purs-tidy: "latest"
+
+      - name: Cache PureScript dependencies
+        uses: actions/cache@v2
+        with:
+          key: ${{ runner.os }}-spago-${{ hashFiles('**/*.dhall') }}
+          path: |
+            .spago
+            output
+      - name: Install dependencies
+        run: spago install
+
+      - name: Build source
+        run: spago build --no-install --purs-args '--censor-lib --strict'
+
+      - name: Install dev dependencies
+        run: spago -x spago-dev.dhall install
+
+      - name: Run tests
+        run: spago -x spago-dev.dhall test --no-install --exec-args <(head --bytes 1000000 /dev/zero)
+
+      # - name: Check formatting
+      #   run: purs-tidy check src test
+
+      - name: Verify Bower & Pulp
+        run: |
+          npm install bower pulp@16.0.0-0
+          npx bower install
+          npx pulp build -- --censor-lib --strict

README.md

@@ -1,4 +1,7 @@
 
 # node-streams-aff
 
+[![CI](https://github.com/jamesdbrock/purescript-node-streams-aff/workflows/CI/badge.svg?branch=main)](https://github.com/jamesdbrock/purescript-node-streams-aff/actions?query=workflow%3ACI+branch%3Amain)
+[![Pursuit](https://pursuit.purescript.org/packages/purescript-node-streams-aff/badge)](https://pursuit.purescript.org/packages/purescript-node-streams-aff)
+
 Asynchronous PureScript API for the [*Node.js* `stream` API](https://nodejs.org/docs/latest/api/stream.html).

src/Node/Stream/Aff.purs

@@ -99,6 +99,11 @@ import Node.Stream.Aff.Internal (onceDrain, onceEnd, onceError, onceReadable)
 
 
 -- | Wait until there is some data available from the stream.
+-- |
+-- | This function is not currently very useful because there is no way to
+-- | know when the stream has reached its end, and if this
+-- | function is called after the stream has ended then the call will
+-- | never complete.
 readSome
   :: forall m r
    . MonadAff m
@@ -181,7 +186,10 @@ readAll_ r canceller = liftAff <<< makeAff $ \res -> do
 -- | Wait for *N* bytes to become available from the stream.
 -- |
 -- | If more than *N* bytes are available on the stream, then
--- | only returns *N* bytes and leaves the rest in the stream’s internal buffer.
+-- | completes with *N* bytes and leaves the rest in the stream’s internal buffer.
+-- |
+-- | If the end of the stream is reached before *N* bytes are available,
+-- | then completes with less than *N* bytes.
 readN
   :: forall m r
    . MonadAff m
@@ -204,6 +212,8 @@ readN_ r canceller n = liftAff <<< makeAff $ \res -> do
 
   onceError r $ res <<< Left
 
+  -- The `end` event is sometimes raised after we have read N bytes, even
+  -- if there are more bytes in the stream?
   onceEnd r do
     ret <- liftST $ Array.ST.unsafeFreeze bufs
     res $ Right ret

test/Main.purs

@@ -1,8 +1,10 @@
 -- | How to test:
+-- |
 -- | ```
 -- | spago -x spago-dev.dhall test --exec-args <(head --bytes 1000000 /dev/zero)
 -- | ```
 -- |
+-- | We want to read from a file, not stdin, because stdin has no EOF.
 module Test.Main where
 
 import Prelude
@@ -27,8 +29,6 @@ import Test.Spec.Runner (runSpec)
 
 main :: Effect Unit
 main = unsafePartial $ do
-  -- We want to read from a file, not stdin, because stdin has no EOF.
-  -- But we currently have no way to detect EOF.
   runAff_ (either (show >>> Console.log) (\_ -> pure unit)) $ runSpec [consoleReporter] do
     describe "Node.Stream.Aff" do
       it "reads 1" do
@@ -38,10 +38,11 @@ main = unsafePartial $ do
         shouldEqual 500000 bytesRead1
         inputs2 <- readSome infile
         inputs3 <- readAll infile
-        -- TODO read after EOF hangs
+        let inputs = inputs1 <> inputs2 <> inputs3
+        -- TODO read after EOF will hang
         -- inputs4 <- readAll infile
         -- inputs4 <- readSome infile
-        let inputs = inputs1 <> inputs2 <> inputs3
+        -- inputs4 <- readN infile 10
         -- let inputs = inputs1 <> inputs2 <> inputs3 <> inputs4
         bytesRead :: Int
             <- liftEffect $ Array.foldM (\a b -> (a+_) <$> Buffer.size b) 0 inputs