@zio.dev/zio-blocks 0.0.33 → 0.0.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. package/adr/2026-07-18-data-migration.md +123 -0
  2. package/guides/async-getting-started.md +687 -0
  3. package/guides/compile-time-resource-safety-with-scope.md +21 -16
  4. package/guides/getting-started-with-mux.md +1395 -0
  5. package/guides/query-dsl-extending.md +161 -102
  6. package/guides/query-dsl-fluent-builder.md +217 -157
  7. package/guides/query-dsl-reified-optics.md +12 -10
  8. package/guides/query-dsl-sql.md +640 -165
  9. package/guides/sql-checked-interpolation.md +173 -0
  10. package/guides/sql-transactions.md +286 -0
  11. package/guides/telemetry-guide.md +1130 -0
  12. package/guides/zio-schema-migration.md +29 -22
  13. package/index.md +248 -389
  14. package/package.json +1 -1
  15. package/plans/config-follow-up-prs.md +188 -0
  16. package/plans/config-pr-assessment-roadmap.md +310 -0
  17. package/reference/MuxDataFlow.jsx +250 -0
  18. package/reference/async.md +1499 -0
  19. package/reference/chunk.md +3533 -308
  20. package/reference/codegen/case-class.md +436 -0
  21. package/reference/codegen/emitter-config.md +383 -0
  22. package/reference/codegen/examples.md +664 -0
  23. package/reference/codegen/field.md +316 -0
  24. package/reference/codegen/index.md +317 -0
  25. package/reference/codegen/scala-emitter.md +392 -0
  26. package/reference/codegen/scala-file.md +276 -0
  27. package/reference/codegen/sealed-trait.md +408 -0
  28. package/reference/codegen/type-definition.md +340 -0
  29. package/reference/codegen/type-ref.md +201 -0
  30. package/reference/combinators.md +347 -117
  31. package/reference/config/config-decoder.md +460 -0
  32. package/reference/config/config-source.md +489 -0
  33. package/reference/config/errors.md +278 -0
  34. package/reference/config/flags.md +369 -0
  35. package/reference/config/formats.md +314 -0
  36. package/reference/config/index.md +304 -0
  37. package/reference/config/rollout.md +336 -0
  38. package/reference/context.md +9 -52
  39. package/reference/data-migration.md +269 -0
  40. package/reference/datastar/attributes.md +302 -0
  41. package/reference/datastar/events.md +234 -0
  42. package/reference/datastar/index.md +256 -0
  43. package/reference/datastar/signals.md +230 -0
  44. package/reference/datastar/sse.md +295 -0
  45. package/reference/datastar.md +346 -0
  46. package/reference/docs.md +1461 -345
  47. package/reference/endpoint/auth-type.md +146 -0
  48. package/reference/endpoint/bulk-creation.md +96 -0
  49. package/reference/endpoint/endpoint.md +297 -0
  50. package/reference/endpoint/http-codec.md +249 -0
  51. package/reference/endpoint/index.md +745 -0
  52. package/reference/endpoint/path-codec.md +225 -0
  53. package/reference/endpoint/route-pattern.md +194 -0
  54. package/reference/endpoint/route-tree.md +111 -0
  55. package/reference/endpoint/segment-codec.md +199 -0
  56. package/reference/html.md +1424 -0
  57. package/reference/htmx/attribute-values.md +359 -0
  58. package/reference/htmx/hx-encoding.md +111 -0
  59. package/reference/htmx/hx-params.md +204 -0
  60. package/reference/htmx/hx-swap.md +276 -0
  61. package/reference/htmx/hx-sync.md +251 -0
  62. package/reference/htmx/hx-target.md +314 -0
  63. package/reference/htmx/hx-trigger.md +457 -0
  64. package/reference/htmx/hx-url-update.md +239 -0
  65. package/reference/htmx/index.md +807 -0
  66. package/reference/htmx/response-headers.md +240 -0
  67. package/reference/http-model/headers.md +735 -0
  68. package/reference/http-model/index.md +49 -0
  69. package/reference/http-model/model.md +1517 -0
  70. package/reference/http-model/schema-codecs.md +522 -0
  71. package/reference/http-model/schema.md +750 -0
  72. package/reference/http-model/server-sent-event.md +341 -0
  73. package/reference/jwt.md +195 -0
  74. package/reference/maybe.md +943 -0
  75. package/reference/media-type.md +2 -2
  76. package/reference/mux.md +254 -0
  77. package/reference/mux.mdx +828 -0
  78. package/reference/openapi.md +1351 -0
  79. package/reference/projection.md +654 -0
  80. package/reference/resource-management/defer-handle.md +1 -1
  81. package/reference/resource-management/resource.md +31 -98
  82. package/reference/resource-management/scope.md +28 -220
  83. package/reference/resource-management/wire.md +5 -55
  84. package/reference/ringbuffer/MpmcDiagram.jsx +717 -0
  85. package/reference/ringbuffer/MpscDiagram.jsx +618 -0
  86. package/reference/ringbuffer/SpmcDiagram.jsx +680 -0
  87. package/reference/ringbuffer/SpscDiagram.jsx +677 -0
  88. package/reference/ringbuffer/advanced.mdx +109 -0
  89. package/reference/ringbuffer/index.mdx +145 -0
  90. package/reference/ringbuffer/mpmc.mdx +185 -0
  91. package/reference/ringbuffer/mpsc.mdx +164 -0
  92. package/reference/ringbuffer/spmc.mdx +108 -0
  93. package/reference/ringbuffer/spsc.mdx +416 -0
  94. package/reference/{allows.md → schema/allows.md} +4 -100
  95. package/reference/{binding-resolver.md → schema/binding-resolver.md} +1 -1
  96. package/reference/{binding.md → schema/binding.md} +3 -4
  97. package/reference/schema/built-in-codecs/avro.md +451 -0
  98. package/reference/schema/built-in-codecs/bson.md +510 -0
  99. package/reference/schema/built-in-codecs/csv.md +564 -0
  100. package/reference/schema/built-in-codecs/index.md +77 -0
  101. package/reference/schema/built-in-codecs/json/index.md +295 -0
  102. package/reference/schema/built-in-codecs/json/json-config.md +217 -0
  103. package/reference/{json-patch.md → schema/built-in-codecs/json/json-patch.md} +5 -5
  104. package/reference/{json-schema.md → schema/built-in-codecs/json/json-schema.md} +14 -47
  105. package/reference/schema/built-in-codecs/json/json-selection.md +322 -0
  106. package/reference/{json.md → schema/built-in-codecs/json/json.md} +32 -64
  107. package/reference/schema/built-in-codecs/messagepack.md +508 -0
  108. package/reference/schema/built-in-codecs/thrift.md +433 -0
  109. package/reference/schema/built-in-codecs/toon.md +1078 -0
  110. package/reference/{xml.md → schema/built-in-codecs/xml.md} +13 -9
  111. package/reference/schema/built-in-codecs/yaml.md +552 -0
  112. package/reference/{codec.md → schema/codec.md} +11 -11
  113. package/reference/{dynamic-optic.md → schema/dynamic-optic.md} +196 -5
  114. package/reference/{dynamic-schema.md → schema/dynamic-schema.md} +8 -8
  115. package/reference/schema/format.md +92 -0
  116. package/reference/schema/index.md +52 -0
  117. package/reference/schema/migration.md +297 -0
  118. package/reference/{modifier.md → schema/modifier.md} +58 -7
  119. package/reference/{optics.md → schema/optics.md} +2 -2
  120. package/reference/{patch.md → schema/patch.md} +1 -1
  121. package/{path-interpolator.md → reference/schema/path-interpolator.md} +167 -72
  122. package/reference/schema/reflect-transformer.md +140 -0
  123. package/reference/{schema-evolution → schema/schema-evolution}/as.md +8 -8
  124. package/reference/{schema-evolution → schema/schema-evolution}/index.md +2 -2
  125. package/reference/{schema-evolution → schema/schema-evolution}/into.md +8 -8
  126. package/reference/{schema-expr.md → schema/schema-expr.md} +110 -175
  127. package/reference/schema/schema-search.md +263 -0
  128. package/reference/{schema.md → schema/schema.md} +22 -2
  129. package/reference/{structural-types.md → schema/structural-types.md} +1 -1
  130. package/reference/{type-class-derivation.md → schema/type-class-derivation.md} +63 -1
  131. package/reference/smithy.md +1032 -0
  132. package/reference/sql/db-codec-deriver.md +71 -0
  133. package/reference/sql/db-codec.md +687 -0
  134. package/reference/sql/db-con.md +271 -0
  135. package/reference/sql/db-connection.md +153 -0
  136. package/reference/sql/db-param-writer.md +77 -0
  137. package/reference/sql/db-param.md +66 -0
  138. package/reference/sql/db-result-reader.md +148 -0
  139. package/reference/sql/db-tx.md +114 -0
  140. package/reference/sql/db-value.md +41 -0
  141. package/reference/sql/ddl.md +85 -0
  142. package/reference/sql/frag.md +288 -0
  143. package/reference/sql/index.md +341 -0
  144. package/reference/sql/repo.md +600 -0
  145. package/reference/sql/sql-dialect.md +73 -0
  146. package/reference/sql/sql-logger.md +62 -0
  147. package/reference/sql/sql-name-mapper.md +70 -0
  148. package/reference/sql/table-metadata.md +134 -0
  149. package/reference/sql/table.md +448 -0
  150. package/reference/sql/transactor-zio.md +399 -0
  151. package/reference/sql/transactor.md +363 -0
  152. package/reference/sql-zio.md +112 -0
  153. package/reference/streams/core/index.md +32 -0
  154. package/reference/streams/core/pipeline.md +854 -0
  155. package/reference/streams/core/sink.md +1404 -0
  156. package/reference/streams/core/stream.md +3236 -0
  157. package/reference/streams/execution-and-compatibility/async-execution.md +822 -0
  158. package/reference/streams/execution-and-compatibility/index.md +35 -0
  159. package/reference/streams/execution-and-compatibility/platform-differences.md +297 -0
  160. package/reference/streams/execution-and-compatibility/scala-2-compatibility.md +88 -0
  161. package/reference/streams/execution-and-compatibility/zero-boxing.md +393 -0
  162. package/reference/streams/index.md +726 -0
  163. package/reference/streams/primitives/index.md +30 -0
  164. package/reference/streams/primitives/reader.md +1992 -0
  165. package/reference/streams/primitives/writer.md +1201 -0
  166. package/reference/telemetry/common/any-value.md +90 -0
  167. package/reference/telemetry/common/attribute-key.md +87 -0
  168. package/reference/telemetry/common/attributes.md +118 -0
  169. package/reference/telemetry/common/index.md +39 -0
  170. package/reference/telemetry/common/instrumentation-scope.md +24 -0
  171. package/reference/telemetry/common/resource.md +34 -0
  172. package/reference/telemetry/index.md +311 -0
  173. package/reference/telemetry/logging/index.md +197 -0
  174. package/reference/telemetry/logging/log-enrichment.md +72 -0
  175. package/reference/telemetry/logging/log-formatter.md +100 -0
  176. package/reference/telemetry/logging/log-record-processor.md +56 -0
  177. package/reference/telemetry/logging/log-record.md +44 -0
  178. package/reference/telemetry/logging/log-writer.md +64 -0
  179. package/reference/telemetry/logging/logger-provider.md +142 -0
  180. package/reference/telemetry/logging/logger.md +83 -0
  181. package/reference/telemetry/logging/severity.md +62 -0
  182. package/reference/telemetry/metrics/index.md +150 -0
  183. package/reference/telemetry/metrics/instruments.md +183 -0
  184. package/reference/telemetry/metrics/labeled-instruments.md +74 -0
  185. package/reference/telemetry/metrics/meter-provider.md +76 -0
  186. package/reference/telemetry/metrics/meter.md +98 -0
  187. package/reference/telemetry/metrics/metric-data.md +57 -0
  188. package/reference/telemetry/otel/custom-exporter.md +216 -0
  189. package/reference/telemetry/otel/index.md +212 -0
  190. package/reference/telemetry/tracing/index.md +155 -0
  191. package/reference/telemetry/tracing/sampler.md +89 -0
  192. package/reference/telemetry/tracing/span-builder.md +57 -0
  193. package/reference/telemetry/tracing/span-context.md +39 -0
  194. package/reference/telemetry/tracing/span-data.md +32 -0
  195. package/reference/telemetry/tracing/span-kind.md +55 -0
  196. package/reference/telemetry/tracing/span-processor.md +53 -0
  197. package/reference/telemetry/tracing/span-status.md +47 -0
  198. package/reference/telemetry/tracing/span.md +117 -0
  199. package/reference/telemetry/tracing/tracer-provider.md +91 -0
  200. package/reference/telemetry/tracing/tracer.md +52 -0
  201. package/reference/typeid.md +5 -83
  202. package/sidebars.js +376 -43
  203. package/undocumented-report.md +528 -270
  204. package/reference/formats.md +0 -694
  205. package/reference/http-model.md +0 -1716
  206. package/reference/streams.md +0 -989
  207. package/ringbuffer.md +0 -249
  208. /package/reference/{json-differ.md → schema/built-in-codecs/json/json-differ.md} +0 -0
  209. /package/reference/{dynamic-value.md → schema/dynamic-value.md} +0 -0
  210. /package/reference/{lazy.md → schema/lazy.md} +0 -0
  211. /package/reference/{reflect.md → schema/reflect.md} +0 -0
  212. /package/reference/{registers.md → schema/registers.md} +0 -0
  213. /package/reference/{schema-error.md → schema/schema-error.md} +0 -0
  214. /package/reference/{syntax.md → schema/syntax.md} +0 -0
  215. /package/reference/{validation.md → schema/validation.md} +0 -0
@@ -36,13 +36,13 @@ Without Resources, managing complex initialization and cleanup is tedious and er
36
36
  Add the ZIO Blocks Scope module to your `build.sbt`:
37
37
 
38
38
  ```scala
39
- libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.33"
39
+ libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.55"
40
40
  ```
41
41
 
42
42
  For cross-platform (Scala.js):
43
43
 
44
44
  ```scala
45
- libraryDependencies += "dev.zio" %%% "zio-blocks-scope" % "0.0.33"
45
+ libraryDependencies += "dev.zio" %%% "zio-blocks-scope" % "0.0.55"
46
46
  ```
47
47
 
48
48
  Supported Scala versions: 2.13.x and 3.x.
@@ -608,6 +608,35 @@ implicit class ResourceOps[A](private val r: Resource[A]) {
608
608
  }
609
609
  ```
610
610
 
611
+ ### `Resource#use` — Acquire, Use, and Finalize
612
+
613
+ For top-level application code, `use` provides a lighter API than spelling out
614
+ `Scope.global.scoped` and `allocate` directly:
615
+
616
+ ```scala
617
+ trait Resource[+A] {
618
+ def use[B](f: A => B)(implicit ev: Unscoped[B]): B
619
+ }
620
+ ```
621
+
622
+ Example:
623
+
624
+ ```scala
625
+ import zio.blocks.scope._
626
+
627
+ class HttpServer extends AutoCloseable {
628
+ def start(): Unit = println("server started")
629
+ def close(): Unit = println("server stopped")
630
+ }
631
+
632
+ val serverResource = Resource.fromAutoCloseable(new HttpServer)
633
+
634
+ serverResource.use(_.start())
635
+ ```
636
+
637
+ `use` still creates a global scope under the hood, acquires the resource,
638
+ runs the callback, and guarantees finalization when the callback returns.
639
+
611
640
  To allocate a resource and use its value inside a scope:
612
641
 
613
642
  ```scala
@@ -701,22 +730,6 @@ cd zio-blocks
701
730
  This example demonstrates creating and automatically cleaning up temporary files using Resource's lifecycle management. It shows how Resource ensures files are closed even if exceptions occur:
702
731
 
703
732
  ```scala title="scope-examples/src/main/scala/scope/examples/TempFileHandlingExample.scala"
704
- /*
705
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
706
- *
707
- * Licensed under the Apache License, Version 2.0 (the "License");
708
- * you may not use this file except in compliance with the License.
709
- * You may obtain a copy of the License at
710
- *
711
- * http://www.apache.org/licenses/LICENSE-2.0
712
- *
713
- * Unless required by applicable law or agreed to in writing, software
714
- * distributed under the License is distributed on an "AS IS" BASIS,
715
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
716
- * See the License for the specific language governing permissions and
717
- * limitations under the License.
718
- */
719
-
720
733
  package scope.examples
721
734
 
722
735
  import zio.blocks.scope._
@@ -814,22 +827,6 @@ sbt "scope-examples/runMain scope.examples.tempFileHandlingExample"
814
827
  This example demonstrates the acquire-release pattern using Resource to manage database connections. It shows proper connection initialization and guaranteed cleanup:
815
828
 
816
829
  ```scala title="scope-examples/src/main/scala/scope/examples/DatabaseConnectionExample.scala"
817
- /*
818
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
819
- *
820
- * Licensed under the Apache License, Version 2.0 (the "License");
821
- * you may not use this file except in compliance with the License.
822
- * You may obtain a copy of the License at
823
- *
824
- * http://www.apache.org/licenses/LICENSE-2.0
825
- *
826
- * Unless required by applicable law or agreed to in writing, software
827
- * distributed under the License is distributed on an "AS IS" BASIS,
828
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
829
- * See the License for the specific language governing permissions and
830
- * limitations under the License.
831
- */
832
-
833
830
  package scope.examples
834
831
 
835
832
  import zio.blocks.scope._
@@ -967,22 +964,6 @@ sbt "scope-examples/runMain scope.examples.runDatabaseExample"
967
964
  This example demonstrates Resource.shared to create a singleton logger instance that is automatically cleaned up only when the last service releases it. Shows reference counting in action:
968
965
 
969
966
  ```scala title="scope-examples/src/main/scala/scope/examples/CachingSharedLoggerExample.scala"
970
- /*
971
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
972
- *
973
- * Licensed under the Apache License, Version 2.0 (the "License");
974
- * you may not use this file except in compliance with the License.
975
- * You may obtain a copy of the License at
976
- *
977
- * http://www.apache.org/licenses/LICENSE-2.0
978
- *
979
- * Unless required by applicable law or agreed to in writing, software
980
- * distributed under the License is distributed on an "AS IS" BASIS,
981
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
982
- * See the License for the specific language governing permissions and
983
- * limitations under the License.
984
- */
985
-
986
967
  package scope.examples
987
968
 
988
969
  import zio.blocks.scope._
@@ -1134,22 +1115,6 @@ sbt "scope-examples/runMain scope.examples.runCachingExample"
1134
1115
  This example demonstrates using Resource.shared for a database connection pool—an expensive resource that should exist exactly once. Shows how multiple services safely share the same pool instance with automatic cleanup:
1135
1116
 
1136
1117
  ```scala title="scope-examples/src/main/scala/scope/examples/ConnectionPoolExample.scala"
1137
- /*
1138
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1139
- *
1140
- * Licensed under the Apache License, Version 2.0 (the "License");
1141
- * you may not use this file except in compliance with the License.
1142
- * You may obtain a copy of the License at
1143
- *
1144
- * http://www.apache.org/licenses/LICENSE-2.0
1145
- *
1146
- * Unless required by applicable law or agreed to in writing, software
1147
- * distributed under the License is distributed on an "AS IS" BASIS,
1148
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1149
- * See the License for the specific language governing permissions and
1150
- * limitations under the License.
1151
- */
1152
-
1153
1118
  package scope.examples
1154
1119
 
1155
1120
  import zio.blocks.scope._
@@ -1307,22 +1272,6 @@ sbt "scope-examples/runMain scope.examples.connectionPoolExample"
1307
1272
  This example demonstrates combining Resource with transaction boundaries. Shows how to manage resources (connections, transactions) that must be coordinated across scopes with proper rollback on failure:
1308
1273
 
1309
1274
  ```scala title="scope-examples/src/main/scala/scope/examples/TransactionBoundaryExample.scala"
1310
- /*
1311
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1312
- *
1313
- * Licensed under the Apache License, Version 2.0 (the "License");
1314
- * you may not use this file except in compliance with the License.
1315
- * You may obtain a copy of the License at
1316
- *
1317
- * http://www.apache.org/licenses/LICENSE-2.0
1318
- *
1319
- * Unless required by applicable law or agreed to in writing, software
1320
- * distributed under the License is distributed on an "AS IS" BASIS,
1321
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1322
- * See the License for the specific language governing permissions and
1323
- * limitations under the License.
1324
- */
1325
-
1326
1275
  package scope.examples
1327
1276
 
1328
1277
  import zio.blocks.scope._
@@ -1475,22 +1424,6 @@ sbt "scope-examples/runMain scope.examples.runTransactionBoundaryExample"
1475
1424
  This example demonstrates Resource.from macro to automatically build a complex dependency graph with multiple services. Shows automatic wiring of constructor dependencies and cleanup in correct LIFO order:
1476
1425
 
1477
1426
  ```scala title="scope-examples/src/main/scala/scope/examples/LayeredWebServiceExample.scala"
1478
- /*
1479
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1480
- *
1481
- * Licensed under the Apache License, Version 2.0 (the "License");
1482
- * you may not use this file except in compliance with the License.
1483
- * You may obtain a copy of the License at
1484
- *
1485
- * http://www.apache.org/licenses/LICENSE-2.0
1486
- *
1487
- * Unless required by applicable law or agreed to in writing, software
1488
- * distributed under the License is distributed on an "AS IS" BASIS,
1489
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1490
- * See the License for the specific language governing permissions and
1491
- * limitations under the License.
1492
- */
1493
-
1494
1427
  package scope.examples
1495
1428
 
1496
1429
  import zio.blocks.scope._
@@ -55,7 +55,7 @@ If you've used `try/finally`, `Using`, or ZIO's `Scope`, this is the same proble
55
55
  Add the following dependency to your `build.sbt`:
56
56
 
57
57
  ```scala
58
- libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.33"
58
+ libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.55"
59
59
  ```
60
60
 
61
61
  Supported Scala versions: **2.13.x** and **3.x**.
@@ -811,24 +811,40 @@ final class App(service: UserService) {
811
811
 
812
812
  // Wire describes the dependency graph: App -> UserService -> Database -> Config
813
813
  // Resource.from uses the Wire to automatically construct the entire graph
814
- Scope.global.scoped { scope =>
815
- import scope._
816
- val config = Config("jdbc:postgres://localhost/db")
817
- val app = allocate(Resource.from[App](
818
- Wire(config)
819
- ))
820
- $(app)(_.run())
821
- // All resources (Database, App) clean up automatically in reverse order
822
- }
814
+ val config = Config("jdbc:postgres://localhost/db")
815
+ val appResource = Resource.from[App](
816
+ Wire(config)
817
+ )
818
+
819
+ appResource.use(_.run())
820
+ // All resources (Database, App) clean up automatically in reverse order
823
821
  ```
824
822
 
825
823
  For more details on `Wire` sharing strategies, resource composition, and advanced DI patterns, see the [Wire reference](./wire.md) and [Resource reference](./resource.md).
826
824
 
827
825
  ## Best Practices
828
826
 
829
- ### Entry point pattern — use `Scope.global.scoped` at the top level
827
+ ### Entry point pattern — use `Resource#use` for app startup, `Scope.global.scoped` for manual scope control
828
+
829
+ For application entrypoints, prefer the lighter `Resource#use` API when you
830
+ have a root resource:
831
+
832
+ ```scala
833
+ import zio.blocks.scope._
834
+
835
+ class App {
836
+ def run(): Unit = println("running")
837
+ }
838
+
839
+ val appResource: Resource[App] = Resource(new App)
840
+
841
+ appResource.use(_.run())
842
+ ```
843
+
844
+ Reach for `Scope.global.scoped` directly when you need manual control over
845
+ multiple allocations, child scopes, lowering, or explicit `$` access.
830
846
 
831
- Wrap your entire application's resource acquisition in a single lexical scope:
847
+ That lower-level form still looks like this:
832
848
 
833
849
  ```scala
834
850
  import zio.blocks.scope._
@@ -1080,22 +1096,6 @@ cd zio-blocks
1080
1096
  This example demonstrates how to allocate a database connection within a scope, ensure proper cleanup, and handle the connection's lifecycle safely.
1081
1097
 
1082
1098
  ```scala title="scope-examples/src/main/scala/scope/examples/DatabaseConnectionExample.scala"
1083
- /*
1084
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1085
- *
1086
- * Licensed under the Apache License, Version 2.0 (the "License");
1087
- * you may not use this file except in compliance with the License.
1088
- * You may obtain a copy of the License at
1089
- *
1090
- * http://www.apache.org/licenses/LICENSE-2.0
1091
- *
1092
- * Unless required by applicable law or agreed to in writing, software
1093
- * distributed under the License is distributed on an "AS IS" BASIS,
1094
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1095
- * See the License for the specific language governing permissions and
1096
- * limitations under the License.
1097
- */
1098
-
1099
1099
  package scope.examples
1100
1100
 
1101
1101
  import zio.blocks.scope._
@@ -1231,22 +1231,6 @@ sbt "scope-examples/runMain runDatabaseExample"
1231
1231
  This example demonstrates allocating multiple connections from a pool within the same scope and ensuring all are cleaned up correctly.
1232
1232
 
1233
1233
  ```scala title="scope-examples/src/main/scala/scope/examples/ConnectionPoolExample.scala"
1234
- /*
1235
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1236
- *
1237
- * Licensed under the Apache License, Version 2.0 (the "License");
1238
- * you may not use this file except in compliance with the License.
1239
- * You may obtain a copy of the License at
1240
- *
1241
- * http://www.apache.org/licenses/LICENSE-2.0
1242
- *
1243
- * Unless required by applicable law or agreed to in writing, software
1244
- * distributed under the License is distributed on an "AS IS" BASIS,
1245
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1246
- * See the License for the specific language governing permissions and
1247
- * limitations under the License.
1248
- */
1249
-
1250
1234
  package scope.examples
1251
1235
 
1252
1236
  import zio.blocks.scope._
@@ -1402,22 +1386,6 @@ sbt "scope-examples/runMain scope.examples.connectionPoolExample"
1402
1386
  This example shows how to allocate temporary file resources and ensure they are automatically cleaned up when the scope closes, even if errors occur.
1403
1387
 
1404
1388
  ```scala title="scope-examples/src/main/scala/scope/examples/TempFileHandlingExample.scala"
1405
- /*
1406
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1407
- *
1408
- * Licensed under the Apache License, Version 2.0 (the "License");
1409
- * you may not use this file except in compliance with the License.
1410
- * You may obtain a copy of the License at
1411
- *
1412
- * http://www.apache.org/licenses/LICENSE-2.0
1413
- *
1414
- * Unless required by applicable law or agreed to in writing, software
1415
- * distributed under the License is distributed on an "AS IS" BASIS,
1416
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1417
- * See the License for the specific language governing permissions and
1418
- * limitations under the License.
1419
- */
1420
-
1421
1389
  package scope.examples
1422
1390
 
1423
1391
  import zio.blocks.scope._
@@ -1513,22 +1481,6 @@ sbt "scope-examples/runMain scope.examples.tempFileHandlingExample"
1513
1481
  This example demonstrates managing database transactions within a scope, showing how to handle commit and rollback operations correctly.
1514
1482
 
1515
1483
  ```scala title="scope-examples/src/main/scala/scope/examples/TransactionBoundaryExample.scala"
1516
- /*
1517
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1518
- *
1519
- * Licensed under the Apache License, Version 2.0 (the "License");
1520
- * you may not use this file except in compliance with the License.
1521
- * You may obtain a copy of the License at
1522
- *
1523
- * http://www.apache.org/licenses/LICENSE-2.0
1524
- *
1525
- * Unless required by applicable law or agreed to in writing, software
1526
- * distributed under the License is distributed on an "AS IS" BASIS,
1527
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1528
- * See the License for the specific language governing permissions and
1529
- * limitations under the License.
1530
- */
1531
-
1532
1484
  package scope.examples
1533
1485
 
1534
1486
  import zio.blocks.scope._
@@ -1679,22 +1631,6 @@ sbt "scope-examples/runMain scope.examples.runTransactionBoundaryExample"
1679
1631
  This example shows how to build an HTTP client pipeline with interceptors for logging, authentication, and error handling, all managed within a scope.
1680
1632
 
1681
1633
  ```scala title="scope-examples/src/main/scala/scope/examples/HttpClientPipelineExample.scala"
1682
- /*
1683
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1684
- *
1685
- * Licensed under the Apache License, Version 2.0 (the "License");
1686
- * you may not use this file except in compliance with the License.
1687
- * You may obtain a copy of the License at
1688
- *
1689
- * http://www.apache.org/licenses/LICENSE-2.0
1690
- *
1691
- * Unless required by applicable law or agreed to in writing, software
1692
- * distributed under the License is distributed on an "AS IS" BASIS,
1693
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1694
- * See the License for the specific language governing permissions and
1695
- * limitations under the License.
1696
- */
1697
-
1698
1634
  package scope.examples
1699
1635
 
1700
1636
  import zio.blocks.scope._
@@ -1818,22 +1754,6 @@ sbt "scope-examples/runMain scope.examples.httpClientPipelineExample"
1818
1754
  This example demonstrates allocating a logger once at the top level and sharing it across multiple services, ensuring it is properly closed when the application shuts down.
1819
1755
 
1820
1756
  ```scala title="scope-examples/src/main/scala/scope/examples/CachingSharedLoggerExample.scala"
1821
- /*
1822
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1823
- *
1824
- * Licensed under the Apache License, Version 2.0 (the "License");
1825
- * you may not use this file except in compliance with the License.
1826
- * You may obtain a copy of the License at
1827
- *
1828
- * http://www.apache.org/licenses/LICENSE-2.0
1829
- *
1830
- * Unless required by applicable law or agreed to in writing, software
1831
- * distributed under the License is distributed on an "AS IS" BASIS,
1832
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1833
- * See the License for the specific language governing permissions and
1834
- * limitations under the License.
1835
- */
1836
-
1837
1757
  package scope.examples
1838
1758
 
1839
1759
  import zio.blocks.scope._
@@ -1983,22 +1903,6 @@ sbt "scope-examples/runMain scope.examples.runCachingExample"
1983
1903
  This example shows how to build a multi-layered web service using Scope for dependency injection, allocating services at different layers and passing them down through child scopes.
1984
1904
 
1985
1905
  ```scala title="scope-examples/src/main/scala/scope/examples/LayeredWebServiceExample.scala"
1986
- /*
1987
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
1988
- *
1989
- * Licensed under the Apache License, Version 2.0 (the "License");
1990
- * you may not use this file except in compliance with the License.
1991
- * You may obtain a copy of the License at
1992
- *
1993
- * http://www.apache.org/licenses/LICENSE-2.0
1994
- *
1995
- * Unless required by applicable law or agreed to in writing, software
1996
- * distributed under the License is distributed on an "AS IS" BASIS,
1997
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1998
- * See the License for the specific language governing permissions and
1999
- * limitations under the License.
2000
- */
2001
-
2002
1906
  package scope.examples
2003
1907
 
2004
1908
  import zio.blocks.scope._
@@ -2119,22 +2023,6 @@ sbt "scope-examples/runMain scope.examples.layeredWebServiceExample"
2119
2023
  This example demonstrates loading configuration from a file within a scope, ensuring the file handle is properly closed when no longer needed.
2120
2024
 
2121
2025
  ```scala title="scope-examples/src/main/scala/scope/examples/ConfigReaderExample.scala"
2122
- /*
2123
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
2124
- *
2125
- * Licensed under the Apache License, Version 2.0 (the "License");
2126
- * you may not use this file except in compliance with the License.
2127
- * You may obtain a copy of the License at
2128
- *
2129
- * http://www.apache.org/licenses/LICENSE-2.0
2130
- *
2131
- * Unless required by applicable law or agreed to in writing, software
2132
- * distributed under the License is distributed on an "AS IS" BASIS,
2133
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2134
- * See the License for the specific language governing permissions and
2135
- * limitations under the License.
2136
- */
2137
-
2138
2026
  package scope.examples
2139
2027
 
2140
2028
  import zio.blocks.scope._
@@ -2263,22 +2151,6 @@ sbt "scope-examples/runMain scope.examples.runConfigReaderExample"
2263
2151
  This example shows how to build a plugin system that discovers and loads plugins dynamically, managing their lifecycle with scopes.
2264
2152
 
2265
2153
  ```scala title="scope-examples/src/main/scala/scope/examples/PluginArchitectureExample.scala"
2266
- /*
2267
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
2268
- *
2269
- * Licensed under the Apache License, Version 2.0 (the "License");
2270
- * you may not use this file except in compliance with the License.
2271
- * You may obtain a copy of the License at
2272
- *
2273
- * http://www.apache.org/licenses/LICENSE-2.0
2274
- *
2275
- * Unless required by applicable law or agreed to in writing, software
2276
- * distributed under the License is distributed on an "AS IS" BASIS,
2277
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2278
- * See the License for the specific language governing permissions and
2279
- * limitations under the License.
2280
- */
2281
-
2282
2154
  package scope.examples
2283
2155
 
2284
2156
  import zio.blocks.scope._
@@ -2406,22 +2278,6 @@ sbt "scope-examples/runMain scope.examples.pluginArchitectureExample"
2406
2278
  This example demonstrates how Scope enforces thread ownership, preventing cross-thread scope misuse and illustrating the difference between owned and unowned scopes.
2407
2279
 
2408
2280
  ```scala title="scope-examples/src/main/scala/scope/examples/ThreadOwnershipExample.scala"
2409
- /*
2410
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
2411
- *
2412
- * Licensed under the Apache License, Version 2.0 (the "License");
2413
- * you may not use this file except in compliance with the License.
2414
- * You may obtain a copy of the License at
2415
- *
2416
- * http://www.apache.org/licenses/LICENSE-2.0
2417
- *
2418
- * Unless required by applicable law or agreed to in writing, software
2419
- * distributed under the License is distributed on an "AS IS" BASIS,
2420
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2421
- * See the License for the specific language governing permissions and
2422
- * limitations under the License.
2423
- */
2424
-
2425
2281
  package scope.examples
2426
2282
 
2427
2283
  import zio.blocks.scope._
@@ -2591,22 +2447,6 @@ sbt "scope-examples/runMain runThreadOwnershipExample"
2591
2447
  This example shows how to detect and handle circular dependencies in resource management, illustrating how scopes help prevent subtle bugs in complex dependency graphs.
2592
2448
 
2593
2449
  ```scala title="scope-examples/src/main/scala/scope/examples/CircularDependencyDemoExample.scala"
2594
- /*
2595
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
2596
- *
2597
- * Licensed under the Apache License, Version 2.0 (the "License");
2598
- * you may not use this file except in compliance with the License.
2599
- * You may obtain a copy of the License at
2600
- *
2601
- * http://www.apache.org/licenses/LICENSE-2.0
2602
- *
2603
- * Unless required by applicable law or agreed to in writing, software
2604
- * distributed under the License is distributed on an "AS IS" BASIS,
2605
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2606
- * See the License for the specific language governing permissions and
2607
- * limitations under the License.
2608
- */
2609
-
2610
2450
  package scope.examples
2611
2451
 
2612
2452
  import zio.blocks.scope._
@@ -2730,22 +2570,6 @@ sbt "scope-examples/runMain scope.examples.circularDependencyDemoExample"
2730
2570
  This example demonstrates how to integrate Scope with legacy libraries that don't natively support resource management, using wrapper resources and the `leak` escape hatch when necessary.
2731
2571
 
2732
2572
  ```scala title="scope-examples/src/main/scala/scope/examples/LegacyLibraryInteropExample.scala"
2733
- /*
2734
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
2735
- *
2736
- * Licensed under the Apache License, Version 2.0 (the "License");
2737
- * you may not use this file except in compliance with the License.
2738
- * You may obtain a copy of the License at
2739
- *
2740
- * http://www.apache.org/licenses/LICENSE-2.0
2741
- *
2742
- * Unless required by applicable law or agreed to in writing, software
2743
- * distributed under the License is distributed on an "AS IS" BASIS,
2744
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2745
- * See the License for the specific language governing permissions and
2746
- * limitations under the License.
2747
- */
2748
-
2749
2573
  package scope.examples
2750
2574
 
2751
2575
  import zio.blocks.scope._
@@ -2872,22 +2696,6 @@ sbt "scope-examples/runMain scope.examples.legacyLibraryInteropExample"
2872
2696
  This example shows how to use Scope to manage test fixtures and resources in integration tests, ensuring automatic cleanup between test runs and proper resource finalization.
2873
2697
 
2874
2698
  ```scala title="scope-examples/src/main/scala/scope/examples/IntegrationTestHarnessExample.scala"
2875
- /*
2876
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
2877
- *
2878
- * Licensed under the Apache License, Version 2.0 (the "License");
2879
- * you may not use this file except in compliance with the License.
2880
- * You may obtain a copy of the License at
2881
- *
2882
- * http://www.apache.org/licenses/LICENSE-2.0
2883
- *
2884
- * Unless required by applicable law or agreed to in writing, software
2885
- * distributed under the License is distributed on an "AS IS" BASIS,
2886
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2887
- * See the License for the specific language governing permissions and
2888
- * limitations under the License.
2889
- */
2890
-
2891
2699
  package scope.examples
2892
2700
 
2893
2701
  import zio.blocks.scope._
@@ -92,13 +92,13 @@ Scope.global.scoped { scope =>
92
92
  Add the following dependency to your `build.sbt`:
93
93
 
94
94
  ```scala
95
- libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.33"
95
+ libraryDependencies += "dev.zio" %% "zio-blocks-scope" % "0.0.55"
96
96
  ```
97
97
 
98
98
  For cross-platform (Scala.js):
99
99
 
100
100
  ```scala
101
- libraryDependencies += "dev.zio" %%% "zio-blocks-scope" % "0.0.33"
101
+ libraryDependencies += "dev.zio" %%% "zio-blocks-scope" % "0.0.55"
102
102
  ```
103
103
 
104
104
  Supported Scala versions: 2.13.x and 3.x.
@@ -496,11 +496,7 @@ val appResource: Resource[App] = Resource.from[App](
496
496
  Wire(AppConfig("jdbc:postgres://localhost/db"))
497
497
  )
498
498
 
499
- Scope.global.scoped { scope =>
500
- import scope._
501
- val app = allocate(appResource)
502
- $(app)(_.run())
503
- }
499
+ appResource.use(_.run())
504
500
  ```
505
501
 
506
502
  When `Resource.from` composes wires, it respects the sharing strategy:
@@ -509,6 +505,8 @@ When `Resource.from` composes wires, it respects the sharing strategy:
509
505
 
510
506
  The macro detects cycles, duplicate providers, and missing dependencies at compile time.
511
507
 
508
+ The `AppConfig` leaf above is hardcoded, which is rarely what a real graph wants. `Config.wire[A]` produces a `Wire.Shared[ConfigSource, A]` that decodes `A` from an injected `ConfigSource`, so configuration becomes a node in the graph rather than something resolved before it — see [Config](../config/index.md).
509
+
512
510
  ## Comparison with Alternatives
513
511
 
514
512
  | Feature | Wire | Manual Passing | Service Locator |
@@ -535,22 +533,6 @@ cd zio-blocks
535
533
  Basic wire construction demonstrates how to create and use `Wire` for dependency injection. View the example source code:
536
534
 
537
535
  ```scala title="scope-examples/src/main/scala/wire/WireBasicExample.scala"
538
- /*
539
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
540
- *
541
- * Licensed under the Apache License, Version 2.0 (the "License");
542
- * you may not use this file except in compliance with the License.
543
- * You may obtain a copy of the License at
544
- *
545
- * http://www.apache.org/licenses/LICENSE-2.0
546
- *
547
- * Unless required by applicable law or agreed to in writing, software
548
- * distributed under the License is distributed on an "AS IS" BASIS,
549
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
550
- * See the License for the specific language governing permissions and
551
- * limitations under the License.
552
- */
553
-
554
536
  package wire
555
537
 
556
538
  import zio.blocks.scope._
@@ -654,22 +636,6 @@ sbt "scope-examples/runMain wire.wireBasicExample"
654
636
  Comparing shared vs unique semantics shows how shared wires reuse the same instance across dependents, while unique wires create fresh instances. View the example:
655
637
 
656
638
  ```scala title="scope-examples/src/main/scala/wire/WireSharedUniqueExample.scala"
657
- /*
658
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
659
- *
660
- * Licensed under the Apache License, Version 2.0 (the "License");
661
- * you may not use this file except in compliance with the License.
662
- * You may obtain a copy of the License at
663
- *
664
- * http://www.apache.org/licenses/LICENSE-2.0
665
- *
666
- * Unless required by applicable law or agreed to in writing, software
667
- * distributed under the License is distributed on an "AS IS" BASIS,
668
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
669
- * See the License for the specific language governing permissions and
670
- * limitations under the License.
671
- */
672
-
673
639
  package wire
674
640
 
675
641
  import zio.blocks.scope._
@@ -775,22 +741,6 @@ sbt "scope-examples/runMain wire.wireSharedUniqueExample"
775
741
  Manual wire construction demonstrates how to use `fromFunction` for custom construction logic. View the example:
776
742
 
777
743
  ```scala title="scope-examples/src/main/scala/wire/WireFromFunctionExample.scala"
778
- /*
779
- * Copyright 2024-2026 John A. De Goes and the ZIO Contributors
780
- *
781
- * Licensed under the Apache License, Version 2.0 (the "License");
782
- * you may not use this file except in compliance with the License.
783
- * You may obtain a copy of the License at
784
- *
785
- * http://www.apache.org/licenses/LICENSE-2.0
786
- *
787
- * Unless required by applicable law or agreed to in writing, software
788
- * distributed under the License is distributed on an "AS IS" BASIS,
789
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
790
- * See the License for the specific language governing permissions and
791
- * limitations under the License.
792
- */
793
-
794
744
  package wire
795
745
 
796
746
  import zio.blocks.scope._