@@ -69,26 +69,6 @@ that interface.
6969Polymorphic operations utilizing the abstract interface can go in the
7070parent module `Streamly.Data.Stream`.
7171
72−Concrete/monomorphic pure stream modules would be placed in:
73−
74−* `Streamly.Data.Stream.Serial`
75−* `Streamly.Data.Stream.WSerial`
76−* `Streamly.Data.Stream.ZipSerial`
77−* ...
78−
79−Monadic/effectful streams could go in:
80−
81−* `Streamly.Data.StreamM.Serial`
82−* `Streamly.Data.StreamM.WSerial`
83−* `Streamly.Data.StreamM.Async`
84−* ...
85−
86−Pure streams are just a special case of monadic streams.
87−
88−We could possibly use the same type named `Stream` for all stream types, as we
89−also have all the operation names also same and we distinguish only by the
90−module name.
91−
9272## Constrained Modules
9373
9474Some modules represent operations on a type which constrain a type using a type
@@ -110,26 +90,8 @@ rather than putting the `PrimArray` under a `Prim` hierarchy.
11090Streamly.Internal.Data.Array.Boxed
11191Streamly.Internal.Data.Array.Prim
11292Streamly.Internal.Data.Array.Prim.Pinned
113−
114−Streamly.Internal.Data.ArrayM.Boxed
115−Streamly.Internal.Data.ArrayM.Prim
116−Streamly.Internal.Data.ArrayM.Prim.Pinned
11793```
11894
119−Pure arrays are just a special case of mutable arrays.
120−
121−We use the name `ArrayM` insted of `MArray` consistent with the naming
122−of monadic operations like `mapM` and also because `Array` and `ArrayM`
123−are listed together in alphabetical listing, plus camel case naming of the
124−latter is clearer to read.
125−
126−We could use an `IsArray` type class, like `IsStream`, but it will
127−require the `Prim` constraint on all polymorphic operations, rendering
128−it of little use. So the `Array` module, unlike in streams, is just a
129−name space placeholder here. We could assign the `Array` module to the
130−Boxed array module but, having an explicit `Boxed` module along with
131−other types of arrays keeps naming explicit and clearer.
132−
13395## Common Modules
13496
13597Some modules represent common types or utility functions that are shared across
@@ -193,3 +155,76 @@ We have the following module hierarchy under Streamly:
193155
194156* Network: This name space is for APIs that access data from remote computers
195157 over the network.
158+
159+## Stream modules
160+
161+By default the streaming modules are effectful. The basic effectful
162+stream types are:
163+
164+* `Streamly.Data.Stream`
165+* `Streamly.Data.Stream.Async`
166+* `Streamly.Data.Stream.Ahead`
167+* `Streamly.Data.Stream.Parallel`
168+* `Streamly.Data.Stream.IsStream` -- polymorphic operations
169+* `Streamly.Data.Stream.Using` -- e.g. mapMUsing consMAsync
170+
171+The above streams have an append-like multi-stream combining behavior
172+i.e. `concatMap` and `bind` would by default evaluate the streams one
173+after another. Alternative implementations of `concatMap` and `bind` are
174+possible. We can either use rebindable syntax to use a different bind or
175+define newtypes with a different bind behavior, all other operations for
176+these remain the same as the base type:
177+
178+* `Streamly.Data.Stream.Zip`
179+* `Streamly.Data.Stream.Interleaved`
180+* `Streamly.Data.Stream.RoundRobin`
181+* `Streamly.Data.Stream.Async.Zip`
182+* `Streamly.Data.Stream.Async.Interleaved`
183+* `Streamly.Data.Stream.Async.RoundRobin`
184+* ...
185+
186+Pure streams are a special case of effectful streams and go in
187+specialized modules suffixed with `Pure`:
188+
189+* `Streamly.Data.Stream.Pure`
190+* `Streamly.Data.Stream.Zip.Pure`
191+* `Streamly.Data.Stream.Interleaved.Pure`
192+* `Streamly.Data.Stream.RoundRobin.Pure`
193+* ...
194+
195+We could possibly use the same type named `Stream` for all stream
196+types, as the names of all stream operation are also the same and we
197+distinguish only by the module name.
198+
199+## Array modules
200+
201+Similarly, the Array modules would go in:
202+
203+* `Streamly.Data.Array`
204+* `Streamly.Data.Array.Prim`
205+* `Streamly.Data.Array.Prim.Pinned`
206+* ...
207+
208+Pure arrays are just a special case of mutable arrays:
209+
210+* `Streamly.Data.Array.Pure`
211+* `Streamly.Data.Array.Prim.Pure`
212+* `Streamly.Data.Array.Prim.Pinned.Pure`
213+* ...
214+
215+## Stream and Fold Channels (SVar)
216+
217+* `Streamly.Data.Stream.Channel`
218+* `Streamly.Data.Stream.Channel.Prim`
219+* `Streamly.Data.Fold.Channel`
220+* `Streamly.Data.Fold.Channel.Prim`
221+
222+## Mutable variables
223+
224+* `Streamly.Data.MutVar.Prim`
225+
226+## Strict Data
227+
228+* `Streamly.Data.Tuple.Strict`
229+* `Streamly.Data.Maybe.Strict`
230+* `Streamly.Data.Either.Strict`