@zio.dev/zio-blocks 0.0.51 → 0.0.55

package/reference/config.md

@@ -1,158 +0,0 @@
----
-id: config
-title: "Config"
-sidebar_label: "Config"
----
-
-`zio.blocks.config` provides typed configuration loading, feature flags, provenance tracking, rollout selection, and source adapters for YAML, JSON, and HOCON. The module is synchronous and zero-dependency: configuration is loaded from `ConfigSource`, flags are read through `FlagSource`, and typed decoding is derived from `Schema[A]`.
-
-## Installation
-
-```scala
-libraryDependencies += "dev.zio" %% "zio-blocks-config" % "0.0.51"
-libraryDependencies += "dev.zio" %% "zio-blocks-config-yaml" % "0.0.51"
-libraryDependencies += "dev.zio" %% "zio-blocks-config-json" % "0.0.51"
-libraryDependencies += "dev.zio" %% "zio-blocks-config-hocon" % "0.0.51"
-```
-
-For Scala.js:
-
-```scala
-libraryDependencies += "dev.zio" %%% "zio-blocks-config" % "0.0.51"
-```
-
-Supported Scala versions: 2.13.x and 3.x.
-
-## Core Types
-
-At the center of the module are two source abstractions:
-
-```scala
-import zio.blocks.maybe.Maybe
-
-trait FlagSource {
-  def sourceId: String
-  def get(name: String): Maybe[SourceValue[String]]
-}
-
-trait ConfigSource extends FlagSource {
-  def get(key: String): Maybe[SourceValue[String]]
-  def all(prefix: String): Map[String, SourceValue[String]]
-}
-```
-
-`ConfigSource` extends `FlagSource`, so the same source can power both typed config loading and simple scalar flags.
-
-## Loading Typed Configuration
-
-Use `Config.load[A]` when you want a typed result and explicit errors:
-
-```scala
-import zio.blocks.config._
-import zio.blocks.scope.Unscoped
-
-final case class AppConfig(host: String, port: Int) derives Schema, Unscoped
-
-val source = ConfigSource.fromMap(
-  Map("app.host" -> "localhost", "app.port" -> "8080"),
-  "example"
-)
-
-val loaded = Config.load[AppConfig](source.prefix("app"))
-```
-
-The main entry points are:
-
-```scala
-Config.load[A](source)
-Config.loadOrThrow[A](source)
-Config.loadWithProvenance[A](source)
-```
-
-`Config.loadWithProvenance` returns a `ProvenanceMap[A]`, which lets you inspect where resolved values came from.
-
-## Wiring Config into Dependency Graphs
-
-For application wiring, prefer `Config.wire[A]` or `Config.wire[A](prefix)` so decoding stays inside the dependency graph instead of being done manually at startup:
-
-```scala
-Config.wire[AppConfig]
-Config.wire[AppConfig]("app")
-```
-
-That keeps `ConfigSource` as the injected input and the typed config as the derived output.
-
-## Working with Sources
-
-`ConfigSource` supports composition and key transformation:
-
-```scala
-val defaults = ConfigSource.fromMap(Map("db.host" -> "localhost"), "defaults")
-val env      = ConfigSource.fromMap(Map("db.port" -> "5432"), "env")
-
-val combined = env.orElse(defaults)
-val scoped   = combined.prefix("db")
-```
-
-Common adapters:
-
-- `ConfigSource.fromMap(...)`
-- `ConfigSource.fromYaml(...)`  (requires `config-yaml` dependency)
-- `ConfigSource.fromJson(...)`  (requires `config-json` dependency)
-- `ConfigSource.fromHocon(...)` (requires `config-hocon` dependency)
-
-## Static and Dynamic Flags
-
-`StaticFlag[A]` resolves once, during object initialization:
-
-```scala
-import zio.blocks.config._
-
-object poolSize extends StaticFlag[Int](10)
-
-val size: Int = poolSize()
-```
-
-`DynamicFlag[A]` keeps an updatable rollout expression and evaluates it on demand.
-
-`StaticFlag` names are derived from the Scala object's fully qualified name, so custom `FlagSource` registrations must use that exact key.
-
-`FlagSource.Registry` is consulted in registration order, so the first registered source wins when multiple sources provide the same flag.
-
-:::note
-Register `FlagSource`s before the first reference to a `StaticFlag` object. Once a static flag object is initialized, later registrations do not retroactively change its resolved value.
-:::
-
-## Rollout DSL
-
-`Rollout` selects values based on a path and an optional percentage bucket:
-
-```scala
-import zio.blocks.config._
-
-val bucket = Rollout.bucketFor("user-123")
-val choice = Rollout.select("true@prod/50%;false", "prod", bucket)
-```
-
-The percentage uses slash-separated syntax (`prod/50%`). For the example above, `choice` is `Maybe.present("true")` for roughly half of the `prod` buckets and `Maybe.present("false")` otherwise. Bare values act as catch-all fallbacks and should come last.
-
-## Provenance
-
-Every resolved value carries provenance information through `SourceValue` and `Provenance`:
-
-```scala
-val source = ConfigSource.fromMap(Map("db.host" -> "localhost"), "defaults")
-val host   = source.get("db.host")
-```
-
-`host` contains both the raw value and a `Provenance.Resolved` entry that records the source id and key.
-
-## Format Adapters
-
-The format modules flatten structured documents into dot-separated keys:
-
-- YAML: nested mappings become `a.b.c`
-- JSON: arrays are indexed as `items.0`, `items.1`, ...
-- HOCON: substitutions are resolved before flattening
-
-Use these adapters when you want the convenience of file formats but still want a single `ConfigSource` API for decoding, composition, and provenance.

package/reference/streams/concurrent-operators.md

@@ -1,106 +0,0 @@
----
-id: concurrent-operators
-title: "Concurrent Operators"
----
-
-ZIO Blocks Streams ships **three** concurrent operators that fan work across virtual threads while preserving the typed-error, synchronous, pull-based programming model. The calling thread still receives `Either[E, Z]` — no effect system is required.
-
-| Operator | Purpose |
-|---|---|
-| `Stream#mapPar(n)(f)` | Apply `f` to each element on up to `n` worker threads. Output is **unordered** (arrival order, not input order). |
-| `Stream.mergeAll(n)(streams)` | Drain up to `n` inner streams concurrently; interleave their elements as they arrive. |
-| `Stream#flatMapPar(n)(f)` | Per element, produce a sub-stream via `f`; drain up to `n` sub-streams concurrently. |
-
-All three operators are **JVM-only**. On Scala.js they degrade to sequential equivalents (`map`, `flatten`, `flatMap`).
-
-## Semantics
-
-**Output order.** Concurrent output is **unordered** with respect to input position. Elements arrive as workers complete, not in input order. If you need input order, use sequential `map` / `flatMap`.
-
-**Error propagation.** The first typed error from any worker or inner stream terminates all concurrent work and surfaces as `Left(e)` from the terminal operation. Defects (unexpected exceptions) propagate as thrown exceptions, same as sequential operators.
-
-**Resource safety.** All worker threads and ring-buffer queues are cleaned up deterministically when the consumer closes the reader, the stream errors, or the scope finalizes.
-
-**Primitive specialization.** Readers produced by concurrent operators preserve primitive specialization — `Int`, `Long`, `Float`, and `Double` streams use specialized lock-free queues internally, avoiding boxing in the concurrent handoff between threads.
-
-## Buffer sizing
-
-Concurrent operators use internal ring-buffer queues (default size **64**). Override with `Stream.bufferSize(n) { ... }` where `n` is a positive power of two:
-
-```
-Stream.bufferSize(256) {
-  Stream.range(0, 1_000_000).mapPar(8)(heavyComputation)
-}.runCollect
-```
-
-Larger buffers help when producers are bursty; smaller buffers reduce memory when many concurrent streams are active. The default is fine for most workloads.
-
-`Pipeline.buffer(n)` inserts a buffer of `n` elements between upstream and downstream (async handoff on JVM, sync on JS).
-
-## Examples
-
-### `mapPar`
-
-```
-// Apply an expensive function using 8 virtual threads.
-// Output order varies between runs.
-val result = Stream.range(0, 1000)
-  .mapPar(8)(n => { Thread.sleep(1); n * 2 })
-  .runCollect
-// result: Right(Chunk(...)) -- all 1000 elements, but not in 0,2,4,... order
-```
-
-### `mergeAll`
-
-```
-// Drain 10 streams concurrently, up to 4 at a time.
-val streams = Stream.fromIterable(
-  (0 until 10).map(i => Stream.range(i * 100, (i + 1) * 100))
-)
-val merged = Stream.mergeAll(4)(streams).runFold(0L)(_ + _)
-// merged: Right(499500) -- all elements consumed, order interleaved
-```
-
-### `flatMapPar`
-
-```
-// Each element spawns a sub-stream; up to 8 drained concurrently.
-val flat = Stream.range(0, 50)
-  .flatMapPar(8)(i => Stream.range(i * 20, (i + 1) * 20))
-  .runFold(0L)(_ + _)
-// flat: Right(499500)
-```
-
-### Error behaviour
-
-```
-// Typed error in a worker terminates all workers
-val err1 = Stream.range(0, 1000)
-  .flatMap(n => if (n == 500) Stream.fail("bad element") else Stream.succeed(n))
-  .mapPar(4)(identity)
-  .runCollect
-// err1: Left("bad element")
-
-// Error in one inner stream terminates mergeAll
-val err2 = Stream.mergeAll(4)(Stream.fromIterable(
-  List(Stream.range(0, 100), Stream.fail("inner error"), Stream.range(200, 300))
-)).runCollect
-// err2: Left("inner error")
-```
-
-## Guidelines
-
-- **Use `mapPar(n)(f)` for expensive per-element work** — network calls, CPU-bound computation, blocking I/O. Do not use it for trivially cheap functions (e.g. `_ + 1`); the thread-handoff overhead exceeds the parallelism benefit.
-- **Use `mergeAll(n)(streams)` for concurrent fan-in** — draining multiple independent sources (files, connections, partitions) simultaneously. Use `flatMapPar(n)(f)` when each input element produces a sub-stream to drain concurrently.
-- **Concurrent output is unordered.** If you need sorted results, apply `.runCollect.map(_.sorted)` or accumulate into a structure that handles ordering. If you need input-order preservation, use sequential `map` / `flatMap`.
-- **`mapPar`, `mergeAll`, and `flatMapPar` are JVM-only.** On JS they degrade to sequential equivalents.
-
-## Comparison with other libraries
-
-| Feature | ZB Streams | fs2 | Kyo | Ox | Pekko |
-|---|---|---|---|---|---|
-| Concurrent operators | `mapPar`, `mergeAll`, `flatMapPar` | `parEvalMap` | `mapParUnordered`* | `mapPar` | `mapAsync`, `flatMapMerge` |
-| Effect system required | No | Yes (cats-effect) | Yes (Kyo) | No (virtual threads) | Yes (Akka) |
-| Typed errors | `Either[E, Z]` | ApplicativeError | Kyo effects | Exceptions | No |
-
-\* Kyo's `mapParUnordered` forks a fiber per element (very slow for large streams). Kyo's `collectAll` merges streams but does not parallelize pure computation within them.