# ZIO Blocks > Type-safe, modular building blocks for Scala This file contains links to documentation sections following the llmstxt.org standard. ## Table of Contents - [ADR-001: SQL Data Migration Architecture](https://zioblocks.com/adr/adr-001-data-migration.md): Accepted - [Schema in a Nutshell](https://zioblocks.com/getting-started/concepts/schema.md): The core idea of the Schema block: describe a data type once, then read and write it as JSON, YAML and other formats without writing codecs. - [Scope in a Nutshell](https://zioblocks.com/getting-started/concepts/scope.md): The core idea of the Scope block: open files, connections and other resources inside a region of code that closes them for you, with lifetimes chec... - [Streams in a Nutshell](https://zioblocks.com/getting-started/concepts/streams.md): The core idea of the Streams block: describe a pipeline over data that arrives piece by piece, with typed errors and safe resources, then run it. - [Wire and Context in a Nutshell](https://zioblocks.com/getting-started/concepts/wire-and-context.md): The core idea of dependency injection in ZIO Blocks: Wire builds services from their constructors at compile time, and Context holds values by type. - [Your First Five Minutes with ZIO Blocks](https://zioblocks.com/getting-started/first-five-minutes.md): Run one small program that uses three blocks together: Schema decodes JSON, Scope closes a file, and Chunk summarizes the data. - [How ZIO Blocks Thinks](https://zioblocks.com/getting-started/how-zio-blocks-thinks.md): The design every ZIO Blocks module shares: libraries instead of a framework, plain values instead of an effect type, one artifact per block, and ch... - [What Is ZIO Blocks?](https://zioblocks.com/getting-started/index.md): A short tour of ZIO Blocks: what it is, the ideas behind it, and which block solves which problem. - [How to Add ZIO Blocks to Your Build](https://zioblocks.com/getting-started/installation.md): Pick the ZIO Blocks modules you need and add them to an sbt or scala-cli build, for any Scala version and for Scala.js. - [Use ZIO Blocks with ZIO, cats-effect or Plain Scala](https://zioblocks.com/getting-started/use-with-effect-systems.md): Where ZIO Blocks calls go in a plain Scala program and in an application built on ZIO or cats-effect: pure calls, blocking calls, resources, Async ... - [Where Next](https://zioblocks.com/getting-started/where-next.md): What to read after Getting Started: tutorials by goal, how-to guides, migration guides and the reference. - [Add Interactivity to a Page with HTMX](https://zioblocks.com/guides/add-interactivity-with-htmx.md): Turn a server-rendered book page into a live search with typed hx-* attributes: debounced input, a category filter and HTML fragments. - [Getting Started with Async](https://zioblocks.com/guides/async-getting-started.md): Learn to create, compose, and run async effects in Scala with the zero-allocation Async[A] type. - [How to Avoid Allocation on Hot Paths](https://zioblocks.com/guides/avoid-allocation-on-hot-paths.md): Keep streams on primitive lanes, read and build Chunks without boxing, swap Option for Maybe, pre-bind metric labels, and measure each change. - [Build a Live Counter and Dashboard with Datastar](https://zioblocks.com/guides/build-a-live-dashboard-with-datastar.md): Build a Datastar weather station: a button that posts its signals, a server that patches the page, and a dashboard streamed over one open connection. - [How to Build a Query from Optional Search Filters](https://zioblocks.com/guides/build-a-query-from-optional-search-filters.md): Turn a search form with optional fields into one parameterized SQL query with a WHERE clause, ordering and paging, using Frag. - [How to Build a Schema Registry with DynamicSchema](https://zioblocks.com/guides/build-a-schema-registry.md): Store versioned event schemas as data, check incoming events against them, rebind them to Scala types, and compare versions. - [Compile-Time Resource Safety with Scope](https://zioblocks.com/guides/compile-time-resource-safety-with-scope.md): Manage resources with Scope so the compiler rejects leaked or misused ones, then share them through dependency injection with Wire. - [Coming from PureConfig, Typesafe Config or zio-config](https://zioblocks.com/guides/config-library-migration.md): Move a PureConfig, Typesafe Config or zio-config application to ZIO Blocks config while keeping its existing application.conf. - [How to Connect to PostgreSQL with a Connection Pool](https://zioblocks.com/guides/connect-to-postgresql-with-a-connection-pool.md): Set up a HikariCP pool for PostgreSQL, build a JdbcTransactor on it, size it for virtual threads and close it with a Scope. - [How to Correlate Logs and Traces Across Services](https://zioblocks.com/guides/correlate-logs-and-traces.md): Carry the trace id from a checkout service to a payment service in HTTP headers, so every log line of one request shares one trace id. - [How to Customize JSON Field Names, ADT Encoding and Optional Fields](https://zioblocks.com/guides/customize-json-encoding.md): Change the JSON shape a Schema produces: snake_case names, renamed fields, type discriminators, null handling and strict decoding. - [How to Derive Your Own Type Class from a Schema](https://zioblocks.com/guides/derive-your-own-type-class.md): Write a Deriver for your own type class, here a log redactor that masks sensitive fields, and derive it for any type with a Schema. - [How to Compute, Store and Replay Changes with Diff and Patch](https://zioblocks.com/guides/diff-and-patch.md): Diff two versions of a value, store the patch as JSON, apply it with the right PatchMode, replay an edit history, and send JSON patches. - [How to Encode and Decode Records with Avro](https://zioblocks.com/guides/encode-and-decode-records-with-avro.md): Derive an Avro codec for order events, write the .avsc schema, encode and decode records and streams, and read the bytes with Apache Avro. - [Evolve Your Data: Change Your Types with Into, As and Migration](https://zioblocks.com/guides/evolve-your-data.md): Validate incoming data with Into, convert between versions both ways with As, and rename stored fields with a compile-checked Migration. - [How to Feed Configuration into a Wire Dependency Graph](https://zioblocks.com/guides/feed-config-into-a-wire-graph.md): Give each service in a Wire graph its own typed, checked settings from one layered ConfigSource, and shut everything down in order. - [How to Fix Common Scope and Wire Compile Errors](https://zioblocks.com/guides/fix-scope-and-wire-compile-errors.md): Look up a Scope or Wire compile error by its message, see why the macro rejected your code, and apply the fix. - [How to Generate JSON Schema from a Type and Validate Payloads Against It](https://zioblocks.com/guides/generate-json-schema-and-validate-payloads.md): Derive a draft 2020-12 JSON Schema contract from a case class, publish it, and validate raw JSON payloads against it or an external schema. - [Generate Scala Code from a Smithy Model](https://zioblocks.com/guides/generate-scala-code-from-smithy.md): Build a small generator that parses a Smithy model, maps its shapes to Scala types and emits Schema-ready source for Scala 3 and Scala 2. - [How to Generate Scala Types from an OpenAPI Spec at Build Time](https://zioblocks.com/guides/generate-scala-types-from-openapi.md): Turn the component schemas of an OpenAPI document into Schema-ready Scala case classes, enums and sealed traits on every sbt build. - [How to Generate Service Traits from Smithy Operations or OpenAPI Paths](https://zioblocks.com/guides/generate-service-traits-from-smithy-or-openapi.md): Map each Smithy operation or OpenAPI path to a method of a Scala service trait, with a sealed error type, using the codegen IR. - [Getting Started with Mux](https://zioblocks.com/guides/getting-started-with-mux.md): Learn how to manage multiplexed bidirectional message streams with capacity limits. - [Guides](https://zioblocks.com/guides/index.md): Step-by-step guides to building with ZIO Blocks. - [Instrument a Program with Logs, Traces and Metrics](https://zioblocks.com/guides/instrument-a-program-with-logs-traces-and-metrics.md): Add structured logs, nested spans, a counter and a histogram to a batch job, switch to JSON logs, and test the spans. - [How to Issue and Verify JWTs](https://zioblocks.com/guides/issue-and-verify-jwts.md): Sign JWTs with HMAC, RSA or EdDSA keys, verify iss, aud and exp with a fixed clock, and reject tampered or hostile tokens. - [Coming from circe, zio-json or jsoniter-scala](https://zioblocks.com/guides/json-library-migration.md): Move JSON codecs from circe, zio-json or jsoniter-scala to one ZIO Blocks Schema, keeping your field names, discriminators and custom formats. - [How to Read and Modify JSON Without Case Classes](https://zioblocks.com/guides/json-without-case-classes.md): Parse JSON into a tree, read and change values by path, print it back, and decode only the part you need into a case class. - [How to Send Compact Data to an LLM with TOON and Parse the Reply](https://zioblocks.com/guides/llm-data-with-toon.md): Encode records as tabular TOON for an LLM prompt, then decode the model's TOON reply back into case classes. - [How to Load Configuration Files on the JVM and in the Browser](https://zioblocks.com/guides/load-configuration-files.md): Load HOCON, JSON and YAML configuration files into a typed case class, split them with includes, load them safely, and run the same settings in the... - [How to Map Custom Column Types](https://zioblocks.com/guides/map-custom-column-types.md): Store newtypes, opaque types, enums, JSON documents, PostgreSQL arrays and timestamps in SQL columns with the ZIO Blocks sql module. - [Coming from Magnum or doobie](https://zioblocks.com/guides/migrate-from-magnum-or-doobie.md): Move a Magnum or doobie data-access layer to the ZIO Blocks sql module: concept map, side-by-side rewrites and a checklist. - [How to Migrate Table Rows to a New Version Online](https://zioblocks.com/guides/migrate-table-rows-online.md): Convert every row of a live table to a new row type with SmallMigrator or LargeMigrator while the application keeps reading and writing. - [Navigate and Update Nested Data with Optics](https://zioblocks.com/guides/nested-data-with-optics.md): Read and update fields deep inside immutable Scala data with lenses, optionals and traversals, without nested copy calls. - [One Type, Many Formats: Export a Catalog as JSON, YAML, CSV, XML, MessagePack, TOON and Avro](https://zioblocks.com/guides/one-type-many-formats.md): Derive JSON, YAML, XML, TOON, MessagePack, Avro and CSV codecs from one Schema and round-trip a book catalog through each. - [How to Override the Codec for One Type Everywhere](https://zioblocks.com/guides/override-codec-for-one-type.md): Encode LocalDate (or any type) your own way in every derived codec by registering one custom codec on the deriver. - [How to Process Binary Data Without Boxing](https://zioblocks.com/guides/process-binary-data-without-boxing.md): Read binary files, buffers and InputStreams as unboxed Long and Double streams, aggregate them, write them back and measure allocation. - [How to Protect an Endpoint with JWT Bearer Tokens](https://zioblocks.com/guides/protect-endpoints-with-jwt.md): Let only signed-in users call an http-model endpoint: read the bearer token, verify the JWT, and answer 401 or 403 correctly. - [How to Protect Pages with Basic Auth or a Session Cookie](https://zioblocks.com/guides/protect-pages-with-basic-auth-or-a-session-cookie.md): Protect http-model pages two ways: check HTTP Basic credentials with a 401 challenge, or log in with a form and an HttpOnly session cookie. - [Query DSL](https://zioblocks.com/guides/query-dsl/index.md): A type-safe query language built on reified optics, from expressions to a fluent SQL builder. - [Query DSL with Reified Optics — Part 3: Extending the Expression Language](https://zioblocks.com/guides/query-dsl-extending.md): Add SQL predicates such as IN, BETWEEN, IS NULL and LIKE, aggregate functions and CASE WHEN to the query language with your own Expr type. - [Query DSL with Reified Optics — Part 4: A Fluent SQL Builder](https://zioblocks.com/guides/query-dsl-fluent-builder.md): Build type-safe SELECT, UPDATE, INSERT and DELETE statements with a fluent builder that takes both SchemaExpr and Expr conditions without manual li... - [Query DSL with Reified Optics — Part 1: Expressions](https://zioblocks.com/guides/query-dsl-reified-optics.md): Write type-safe, composable query expressions over any schema-equipped type using reified optics: comparisons, boolean logic, arithmetic, strings a... - [Query DSL with Reified Optics — Part 2: SQL Generation](https://zioblocks.com/guides/query-dsl-sql.md): Turn query expressions into SQL WHERE clauses, SELECT statements and parameterized queries, then inspect the generated SQL, preview migration SQL a... - [How to Read and Write CSV and TSV Files](https://zioblocks.com/guides/read-and-write-csv-and-tsv-files.md): Read CSV and TSV files into case classes by header name, report every bad row, write records back out and process large files row by row. - [How to Read and Write JSON Lines with Streams](https://zioblocks.com/guides/read-and-write-json-lines.md): Read a JSON Lines (NDJSON) file as a stream of typed records, skip or fail on bad lines with their line numbers, and write records back one per line. - [How to Read and Write YAML Documents](https://zioblocks.com/guides/read-and-write-yaml.md): Read YAML files into case classes, write CI-style YAML from Scala values, convert to JSON, and guard against the YAML that schema-yaml silently mis... - [Coming from cats-effect Resource, ZIO Scope/ZLayer, macwire or Using](https://zioblocks.com/guides/resource-and-di-migration.md): Move resource handling and dependency wiring from cats-effect, ZIO, macwire or scala.util.Using to ZIO Blocks Scope, Resource and Wire. - [How to Return HTMX Fragments, Full Pages and Response Headers](https://zioblocks.com/guides/return-htmx-fragments-and-response-headers.md): Answer one URL with a full page or an htmx fragment, update a second spot out of band, and steer the browser with typed HX-* response headers. - [How to Roll Out a Feature Gradually with Flags](https://zioblocks.com/guides/roll-out-feature-gradually.md): Ship a feature to 10% of readers, target one region, widen the rollout at runtime, and test the code that reads the flag. - [How to Run a Mux over a Real Socket](https://zioblocks.com/guides/run-a-mux-over-a-socket.md): Carry several independent streams over one TCP connection with a zio-blocks Mux: framing, reader and writer loops, half-close, back-pressure and sh... - [How to Run Streams Without Blocking](https://zioblocks.com/guides/run-streams-without-blocking.md): Swap blocking stream terminals for their Async twins, do async work per element, and run the same pipeline on Scala.js, including a ReadableStream ... - [How to Send Server-Sent Events with http-model](https://zioblocks.com/guides/send-server-sent-events.md): Stream Server-Sent Events from a ZIO Blocks http-model Response through the JDK HTTP server to curl and the browser's EventSource. - [How to Serve http-model Requests with the JDK HTTP Server](https://zioblocks.com/guides/serve-http-model-requests.md): Serve a Request => Response function built on ZIO Blocks http-model with the HTTP server that ships with the JDK. - [Build a Small JSON Backend from Blocks](https://zioblocks.com/guides/small-json-backend-from-blocks.md): Combine schema, config, scope, sql, http-model and telemetry into one small bookstore JSON backend, from settings to shutdown. - [sql(table) Checked Interpolation](https://zioblocks.com/guides/sql-checked-interpolation.md): > **Note**: Checked form is `StringContext(...).sql(table, ...)(...)`; no `sqlChecked` alias (removed pre-1.0). - [How to Use the sql Module from a ZIO Application](https://zioblocks.com/guides/sql-from-zio.md): Provide a ZIO Blocks transactor as a ZLayer, run queries off ZIO's main threads, and mix database writes with other effects in one transaction. - [SQL Transactions: Isolation, Read-Only and Savepoints](https://zioblocks.com/guides/sql-transactions.md): This guide covers ZIO Blocks' SQL transaction system: how `transact` works under the hood, which isolation levels are available on each database, a... - [How to Store and Search Vector Embeddings in PostgreSQL](https://zioblocks.com/guides/store-and-search-vector-embeddings.md): Store embeddings in a pgvector column with a DbCodec built on String, search by nearest neighbour, pick a distance operator and add an HNSW index. - [How to Store Case Classes in MongoDB](https://zioblocks.com/guides/store-case-classes-in-mongodb.md): Derive a BSON codec from a Schema, store support tickets in MongoDB with the Java driver, and pick how sealed traits and options are stored. - [How to Stream Files and Sockets Without Leaking Resources](https://zioblocks.com/guides/stream-files-and-sockets.md): Read files, NIO channels and sockets as streams that close their handles on success, failure, early stop and missing input. - [How to Stream Large Query Results](https://zioblocks.com/guides/stream-large-query-results.md): Read a large SQL result set as a stream of row chunks, aggregate it, export it to a file and handle its errors without loading every row. - [Coming from fs2, ZIO Streams or Ox](https://zioblocks.com/guides/streaming-library-migration.md): Move streaming pipelines from fs2, ZIO Streams or Ox to ZIO Blocks Stream, Sink and Pipeline, without an effect system. - [Telemetry: Architecture, Patterns, and Real-World Usage](https://zioblocks.com/guides/telemetry-guide.md): Understand how the logging, tracing and metrics pipeline works, then wire it into a production service with sampling, exporters and ordered shutdown. - [How to Test Database Code Against SQLite](https://zioblocks.com/guides/test-database-code-against-sqlite.md): Give every test its own SQLite database, create the schema from code, seed fixtures and roll back writes in ZIO Test specs. - [How to Test Code That Logs, Traces and Records Metrics](https://zioblocks.com/guides/test-telemetry.md): Capture spans, log records and counter values in memory during tests, assert on them, and keep tests from leaking into each other. - [How to Tune JSON Encoding and Decoding for Throughput](https://zioblocks.com/guides/tune-json-throughput.md): Decode JSON straight from bytes, buffers and streams, reuse derived codecs, size reader and writer buffers, and measure with JMH. - [How to Turn a Paginated API into a Stream](https://zioblocks.com/guides/turn-a-paginated-api-into-a-stream.md): Walk a page-by-page API with Stream.unfold or Stream.unfoldAsync, stop on the last page, decode each item and report failed requests as typed errors. - [Build a Typed Configuration Loader](https://zioblocks.com/guides/typed-config-loader.md): Load a typed case class from YAML, environment overrides and defaults, report every error at once, and see where each value came from. - [How to Upsert Rows and Paginate with Keyset Cursors](https://zioblocks.com/guides/upsert-and-paginate-with-keyset-cursors.md): Insert or update rows in one statement, choose which columns an upsert changes, and walk large tables page by page with keyset cursors. - [How to Use Iron Refined Types and Typed IDs with Schema](https://zioblocks.com/guides/use-iron-refined-types-and-typed-ids.md): Derive Schema and JSON codecs for case classes with Iron refined fields, read constraint failures, and keep entity IDs apart with one generic Id type. - [How to Use Scala 3 Named Tuples with Schema](https://zioblocks.com/guides/use-named-tuples-with-schema.md): Derive a Schema for a Scala 3 named tuple, round-trip it through JSON, update fields with optics and convert it to a case class. - [How to Use ZIO Blocks in a ZIO or cats-effect Application](https://zioblocks.com/guides/use-zio-blocks-in-zio-or-cats-effect.md): Call ZIO Blocks from a ZIO or cats-effect app: blocking calls, resources, Async and streams, with cancellation and cleanup carried across. - [How to Validate Query Parameters and Headers and Answer 400](https://zioblocks.com/guides/validate-query-parameters-and-headers.md): Read query parameters and headers as typed values with http-model-schema and answer bad input with a JSON 400 that names every problem. - [How to Define Validated Newtypes and Collect Every Validation Error](https://zioblocks.com/guides/validated-newtypes.md): Wrap ISBNs, titles and prices in types that only a check can build, enforce the check in every codec, and report all errors at once. - [How to Wrap Callback and Future-Based APIs in Async](https://zioblocks.com/guides/wrap-callback-and-future-apis.md): Bring Future, CompletionStage, JS Promise and callback APIs into Async, and cancel the underlying call when the Async is cancelled. - [How to Write a Codec for a New Wire Format](https://zioblocks.com/guides/write-a-codec-for-a-new-wire-format.md): Write a BinaryCodec and its Deriver for a format ZIO Blocks doesn't ship, report decode errors with paths, and package it as a BinaryFormat. - [How to Write an OpenAPI Document and Export It as JSON or YAML](https://zioblocks.com/guides/write-and-export-openapi.md): Describe a REST API as a typed OpenAPI value, generate its schemas from the same Schema used for JSON, and export it as JSON and YAML. - [How to Write Joins and Inspect the Generated SQL](https://zioblocks.com/guides/write-joins-and-inspect-generated-sql.md): Join related tables with SqlQuery and Rel, read the rows as tuples, and print or dump the SQL each join generates. - [Render Your First Server-Side HTML Page](https://zioblocks.com/guides/your-first-html-page.md): Build a book detail page with the ZIO Blocks HTML DSL, escape user input, add CSS and JSON state, and save it as an HTML file. - [Your First Schema: Round-Trip a Type Through JSON](https://zioblocks.com/guides/your-first-schema.md): Describe a Scala type once with Schema, then encode it to JSON, decode it back, and read decode errors. - [Build Your First Database Repository on SQLite](https://zioblocks.com/guides/your-first-sqlite-repository.md): Connect to SQLite, derive a table and a repository from one schema, write your own queries and roll back a transaction. - [Your First Streaming Pipeline: Turn a Sales Log into a Report](https://zioblocks.com/guides/your-first-streaming-pipeline.md): Read a bookstore's sales log with a Stream, parse, filter and batch it, sum it with a Sink, and recover from a bad line. - [Migrating from ZIO Schema to ZIO Blocks Schema](https://zioblocks.com/guides/zio-schema-migration.md): Port a ZIO Schema 1.x application to ZIO Blocks Schema by mapping its schemas, annotations, codecs and DynamicValue usage to the new equivalents. - [ZIO Blocks](https://zioblocks.com/overview.md): **Modular building blocks for modern Scala applications—no effect system required.** - [Async](https://zioblocks.com/reference/async.md): Reference for the ZIO Blocks async module: Async[A], Pollable, Completer, Async.Running, and Cancelable. - [Chunk](https://zioblocks.com/reference/chunk.md): `Chunk[A]` is an **immutable, indexed sequence** of elements of type `A`. Unlike `Array`, `Chunk` provides a purely functional interface with optim... - [CaseClass](https://zioblocks.com/reference/codegen/case-class.md): `CaseClass` represents an immutable case class in the IR. Use it when generating Scala code from data models, APIs, or structured data—it's the mos... - [EmitterConfig](https://zioblocks.com/reference/codegen/emitter-config.md): `EmitterConfig` controls how `ScalaEmitter` formats Scala code. Customize indentation, import sorting, trailing commas, and target Scala version (2... - [Complete Examples](https://zioblocks.com/reference/codegen/examples.md): This page shows complete, runnable examples demonstrating realistic code generation workflows. Each example builds IR models from scratch and emits... - [Field](https://zioblocks.com/reference/codegen/field.md): `Field` represents a class field (constructor parameter) in the IR. Combine a name with a type reference, optionally adding default values and modi... - [Code Generation](https://zioblocks.com/reference/codegen/index.md): `zio-blocks-codegen` is a **generic, domain-agnostic Scala code generation library**. It provides an intermediate representation (IR) for building ... - [ScalaEmitter](https://zioblocks.com/reference/codegen/scala-emitter.md): `ScalaEmitter` is the core emission engine that converts IR models to formatted Scala source code. It provides the main entry point and methods to ... - [ScalaFile](https://zioblocks.com/reference/codegen/scala-file.md): `ScalaFile` is the root IR node representing a complete Scala source file. It holds everything needed to emit a compilable file: the package declar... - [SealedTrait](https://zioblocks.com/reference/codegen/sealed-trait.md): `SealedTrait` represents a sealed trait in the IR—a sum type (algebraic data type) that enumerates all possible cases. It's essential for modeling ... - [TypeDefinition](https://zioblocks.com/reference/codegen/type-definition.md): `TypeDefinition` is a sealed trait that represents any Scala type definition—case classes, sealed traits, enums, objects, newtypes, type aliases, a... - [TypeRef](https://zioblocks.com/reference/codegen/type-ref.md): `TypeRef` represents a reference to a Scala type in the IR. It captures both simple types (like `String`, `Int`) and generic types (like `List[Stri... - [Combinators](https://zioblocks.com/reference/combinators.md): The `combinators` module provides compile-time typeclasses for composing and decomposing values in type-safe ways. Each module focuses on a specifi... - [Concurrency](https://zioblocks.com/reference/concurrency/index.md): Introduction to the Concurrency blocks of ZIO Blocks: Async, Mux and RingBuffer. - [ConfigDecoder](https://zioblocks.com/reference/config/config-decoder.md): `ConfigDecoder[A]` reads a value of type `A` out of a `ConfigSource`, accumulating every failure instead of stopping at the first one. Instances ar... - [ConfigSource](https://zioblocks.com/reference/config/config-source.md): `ConfigSource` is a flat, string-keyed namespace of configuration values with dot-separated paths. It answers single-key lookups, enumerates keys u... - [Configuration Errors](https://zioblocks.com/reference/config/errors.md): `ConfigError` is the failure type for every configuration operation. It is a sealed hierarchy divided into four category traits, so code can match ... - [Flags](https://zioblocks.com/reference/config/flags.md): A flag is a named scalar whose value comes from outside the program. `StaticFlag[A]` resolves once at class-load time and never changes; `DynamicFl... - [File Formats](https://zioblocks.com/reference/config/formats.md): Three optional modules add file-format support: `config-yaml`, `config-json`, and `config-hocon`. Each contributes one constructor to the `ConfigSo... - [Configuration & Feature Flags](https://zioblocks.com/reference/config/index.md): `zio.blocks.config` loads typed configuration from string-keyed sources, tracks where every resolved value came from, and evaluates feature flags w... - [Rollout](https://zioblocks.com/reference/config/rollout.md): `Rollout` is the expression language behind dynamic flags. An expression is a semicolon-separated list of choices, each optionally targeted at a sl... - [Context](https://zioblocks.com/reference/context.md): `Context[+R]` is a type-indexed heterogeneous collection that stores values of different types, indexed by their types, with compile-time type safe... - [Data Migration](https://zioblocks.com/reference/data-migration.md): The `zio.blocks.data.migration` module provides three execution models for evolving database schemas online. It builds on [`Migration[A, B]`](./sch... - [Data Types](https://zioblocks.com/reference/data-types/index.md): Introduction to the Data Types blocks of ZIO Blocks: Chunk, Maybe and Combinators. - [Datastar Attributes](https://zioblocks.com/reference/datastar/attributes.md): `DatastarAttributes` supplies 27 `data*` helpers that make rendered HTML reactive. Each returns either a finished `Dom.Attribute` or a `DatastarAtt... - [Event Handlers](https://zioblocks.com/reference/datastar/events.md): `dataOn` opens the event side of the attribute DSL: sixteen predefined DOM events, fourteen chainable modifiers, and four case modifiers, all rende... - [Datastar](https://zioblocks.com/reference/datastar/index.md): `zio.http.datastar` builds [Datastar](https://data-star.dev) hypermedia applications: it renders the `data-*` attributes that make a page reactive,... - [Signal](https://zioblocks.com/reference/datastar/signals.md): `Signal[A]` is a named, typed handle on a piece of state that lives in the browser. `Signal#:=` pairs it with a value to produce a `SignalUpdate[A]... - [Server-Sent Events](https://zioblocks.com/reference/datastar/sse.md): `DatastarEvent` builds the events a server sends to patch a live page: replace elements, patch signals, execute a script, or remove elements. Each ... - [Dependency Injection](https://zioblocks.com/reference/dependency-injection/index.md): Introduction to the Dependency Injection blocks of ZIO Blocks: Wire for constructing a service and its dependencies, and Context for type-indexed c... - [ZIO Blocks Docs (Markdown)](https://zioblocks.com/reference/docs.md): ZIO Blocks Markdown is a **pure, zero-dependency GitHub Flavored Markdown library** providing an immutable ADT for markdown documents, a strict par... - [AuthType](https://zioblocks.com/reference/endpoint/auth-type.md): `AuthType` is a sealed trait that describes an HTTP authentication scheme as a first-class type parameter on `Endpoint`. Each `AuthType` variant ca... - [Bulk Endpoint Creation](https://zioblocks.com/reference/endpoint/bulk-creation.md): The `endpoints` macro (Scala 3 only; it is not in `zio-blocks-endpoint` 0.0.56, so add `zio-blocks-next-endpoint` and `-experimental` as described ... - [Endpoint](https://zioblocks.com/reference/endpoint/endpoint.md): `Endpoint[PathInput, Input, Err, Output, Auth]` is the top-level descriptor for an HTTP endpoint. It holds a typed route, three independent codec c... - [HttpCodec](https://zioblocks.com/reference/endpoint/http-codec.md): `HttpCodec[K, A]` is a composable, typed descriptor for HTTP request and response parts. The phantom type parameter `K` (either `CodecKind.Request`... - [Endpoint](https://zioblocks.com/reference/endpoint/index.md): `zio-blocks-endpoint` is a **pure, type-safe HTTP endpoint descriptor** for building clients, servers, and API documentation from a single source o... - [PathCodec](https://zioblocks.com/reference/endpoint/path-codec.md): `PathCodec[A]` is a composable descriptor for URL path structures. It holds a tree of segment codecs connected by concatenation and fallback nodes,... - [RoutePattern](https://zioblocks.com/reference/endpoint/route-pattern.md): `RoutePattern[A]` pairs an HTTP method with a typed path pattern. It is the primary routing descriptor in `zio-blocks-endpoint`: every `Endpoint` c... - [RouteTree](https://zioblocks.com/reference/endpoint/route-tree.md): `RouteTree[A]` is a routing trie keyed by HTTP method and path. It maps `(Method, Path)` pairs to values of type `A`, performing prefix-tree lookup... - [SegmentCodec](https://zioblocks.com/reference/endpoint/segment-codec.md): `SegmentCodec[A]` describes a single URL path segment. It supports basic typed segment kinds — `SegmentCodec.bool`, `SegmentCodec.int`, `SegmentCod... - [HTML](https://zioblocks.com/reference/html.md): `zio-blocks-html` is a **type-safe HTML templating library** providing immutable data structures and a fluent DSL for building HTML, CSS, and JavaS... - [Attribute Values and Infrastructure](https://zioblocks.com/reference/htmx/attribute-values.md): This section documents supporting attribute value types and infrastructure for the HTMX DSL. These types handle specialized data encoding, configur... - [HxEncoding](https://zioblocks.com/reference/htmx/hx-encoding.md): `HxEncoding` represents the `hx-encoding` attribute, controlling how form data is encoded when sent in an HTMX request. The primary use case is fil... - [HxParams](https://zioblocks.com/reference/htmx/hx-params.md): `HxParams` represents the `hx-params` attribute, controlling which form parameters are included in the HTMX request. Instead of sending all form fi... - [HxSwap](https://zioblocks.com/reference/htmx/hx-swap.md): `HxSwap` represents the `hx-swap` attribute, controlling how HTMX replaces DOM content after a successful response. It combines a base strategy (in... - [HxSync](https://zioblocks.com/reference/htmx/hx-sync.md): `HxSync` represents the `hx-sync` attribute, coordinating multiple HTMX requests by specifying how new requests interact with pending or running re... - [HxTarget](https://zioblocks.com/reference/htmx/hx-target.md): `HxTarget` represents the `hx-target` attribute and related selector-based attributes, declaring where HTMX applies the swap. It supports DOM trave... - [HxTrigger](https://zioblocks.com/reference/htmx/hx-trigger.md): `HxTrigger` represents the `hx-trigger` attribute, declaring which event fires an HTMX request. It combines an event name with optional modifiers t... - [HxUrlUpdate](https://zioblocks.com/reference/htmx/hx-url-update.md): `HxUrlUpdate` represents the `hx-push-url` and `hx-replace-url` attributes, controlling whether and how the browser's URL bar updates after an HTMX... - [HTMX](https://zioblocks.com/reference/htmx/index.md): `zio.http.htmx` is a **typed HTMX DSL** for building safe, compile-time HTMX attribute declarations within `zio.blocks.html`. It provides immutable... - [Request and Response Headers](https://zioblocks.com/reference/htmx/response-headers.md): `zio.http.htmx.headers` provides typed HTTP headers for the request/response side of an HTMX exchange: the headers HTMX sends with every request, a... - [Header](https://zioblocks.com/reference/http-model/headers.md): `Header` is the typed model of a single HTTP header field. Each of the 75 built-in headers is a case class or sealed ADT paired with a companion th... - [HTTP Model](https://zioblocks.com/reference/http-model/index.md): `zio-blocks-http-model` is a **pure, zero-dependency HTTP data model** for building HTTP clients and servers. It provides immutable types represent... - [HTTP Model](https://zioblocks.com/reference/http-model/model.md): `zio-blocks-http-model` is a **runtime-independent HTTP data model** for building HTTP clients and servers. It provides immutable types representin... - [HeaderCodec and QueryCodec](https://zioblocks.com/reference/http-model/schema-codecs.md): `HeaderCodec[A]` and `QueryCodec[A]` encode a whole value of type `A` into `Headers` or `QueryParams` and decode it back. Both are derived from `Sc... - [Schema-Based Typed Access](https://zioblocks.com/reference/http-model/schema.md): `zio-blocks-http-model-schema` adds **type-safe, validated extraction** of query parameters and headers to the core HTTP model. It provides extensi... - [ServerSentEvent](https://zioblocks.com/reference/http-model/server-sent-event.md): `ServerSentEvent[A]` is an immutable envelope for one Server-Sent Event: a payload of type `A` plus the three optional SSE metadata fields. `SseDat... - [Reference](https://zioblocks.com/reference/index.md): Reference pages for every ZIO Blocks module, grouped by area. - [JWT](https://zioblocks.com/reference/jwt.md): `zio-blocks-jwt` is a zero-dependency, cross-platform (JVM + Scala.js) JWT library for Scala 2.13 and Scala 3. - [Maybe](https://zioblocks.com/reference/maybe.md): `Maybe[A]` is a **low-allocation alternative to `Option[A]`** that uses a top-level `Absent` sentinel object to represent the absence of a value. O... - [MediaType](https://zioblocks.com/reference/media-type.md): `MediaType` is a **type-safe representation of IANA media types** (also known as MIME types). It captures structured metadata about content types i... - [Meta Programming](https://zioblocks.com/reference/meta-programming/index.md): Introduction to the Meta Programming blocks of ZIO Blocks: Schema, which describes data types as values, and TypeId, which keeps type identity at r... - [Mux](https://zioblocks.com/reference/mux.md): `zio-blocks-mux` is a **high-performance multiplexer for ID-multiplexed protocols** (HTTP/2, QUIC, WebSockets with multiplexing, and other stream-b... - [OpenAPI](https://zioblocks.com/reference/openapi.md): `zio-blocks-openapi` is a **complete, type-safe OpenAPI 3.1 data model** for building API documentation programmatically. It provides immutable cas... - [Persistence](https://zioblocks.com/reference/persistence/index.md): Introduction to the Persistence blocks of ZIO Blocks: the SQL module, its ZIO integration, data migration and event-sourced projections. - [EventStore[E]](https://zioblocks.com/reference/projection/event-store.md): The write side of the projection module: EventStore[E], the append-only log of events, with EventEnvelope and the SQLite implementation. - [Projection](https://zioblocks.com/reference/projection/index.md): Build event-sourced read models declaratively: transform an append-only event log into queryable per-entity stores. - [Migrating Read Models and Events](https://zioblocks.com/reference/projection/migration.md): What happens when the row type of a projection or the stored events change: how the engine notices a changed read model and rebuilds it, the add-co... - [ProjectionEngine](https://zioblocks.com/reference/projection/projection-engine.md): The runtime that runs projections: creating an engine, start and catch-up, queries, configuration, storage files and the SQLite connection cache. - [ProjectionStore[A]](https://zioblocks.com/reference/projection/projection-store.md): Where the engine keeps the rows of a read model, with its watermark and schema hash: ProjectionStore[A] and its SQLite and in-memory stores. - [Projection[A]](https://zioblocks.com/reference/projection/projection.md): Declarative descriptor for an event-sourced read model: defines event sources, routing, and handlers. - [Testing](https://zioblocks.com/reference/projection/testing.md): In-memory helpers for testing projections without SQLite: TestEngine, InMemoryProjectionStore, TestContext, and TestProjectionEngine. - [DeferHandle](https://zioblocks.com/reference/resource-management/defer-handle.md): `DeferHandle` is a handle returned by `Scope.defer` that allows cancelling a registered finalizer before the scope closes: - [Finalization](https://zioblocks.com/reference/resource-management/finalization.md): `Finalization` is the result of running all finalizers in a scope, collecting any errors that occurred during cleanup: - [Finalizer](https://zioblocks.com/reference/resource-management/finalizer.md): `Finalizer` is a minimal capability interface for registering cleanup actions. It exposes only the `Finalizer#defer` method, preventing code from a... - [Resource Management](https://zioblocks.com/reference/resource-management/index.md): Resource management and dependency injection are fundamental to building reliable, maintainable applications. ZIO Blocks provides three complementa... - [Resource](https://zioblocks.com/reference/resource-management/resource.md): `Resource[A]` is a **lazy recipe for managing resource lifecycles**, encapsulating both acquisition and finalization tied to a `Scope`. Resources d... - [Scope](https://zioblocks.com/reference/resource-management/scope.md): `Scope` is a **compile-time safe resource lifecycle manager** that tags allocated values with a scope-specific type, preventing use-after-close at ... - [Unscoped](https://zioblocks.com/reference/resource-management/unscoped.md): `Unscoped[A]` is a marker typeclass for types that can safely escape a scope without tracking. Types with an `Unscoped` instance are considered "sa... - [Wire](https://zioblocks.com/reference/resource-management/wire.md): `Wire[-In, +Out]` is a **compile-time safe recipe for constructing a service and its dependencies**. Wires describe how to construct an `Out` value... - [Advanced Topics](https://zioblocks.com/reference/ringbuffer/advanced.md): Ring buffers are **lock-free** but must be used correctly: - [RingBuffer](https://zioblocks.com/reference/ringbuffer/index.md): Ring buffers are **fixed-size, lock-free queues** for efficiently exchanging elements between producer and consumer threads with minimal contention... - [MPMC RingBuffer](https://zioblocks.com/reference/ringbuffer/mpmc.md): `MpmcRingBuffer[A]` is the fully general-purpose implementation for systems with multiple producer and consumer threads. It uses the **Vyukov/Dmitr... - [MPSC RingBuffer](https://zioblocks.com/reference/ringbuffer/mpsc.md): `MpscRingBuffer[A]` handles the inverse case: multiple producer threads safely offering elements to a single consumer thread. It uses a **hybrid de... - [SPMC RingBuffer](https://zioblocks.com/reference/ringbuffer/spmc.md): `SpmcRingBuffer[A]` allows a single producer thread to efficiently feed multiple consumer threads. It uses an **index-based algorithm** where slot ... - [SPSC RingBuffer](https://zioblocks.com/reference/ringbuffer/spsc.md): `SpscRingBuffer[A]` is optimized for the simplest and fastest case: exactly one producer thread and one consumer thread. It uses the **FastFlow** a... - [Allows](https://zioblocks.com/reference/schema/allows.md): `Allows[A, S]` is a compile-time capability token that proves, at the call site, that type `A` satisfies the structural grammar `S`. A capability t... - [BindingResolver](https://zioblocks.com/reference/schema/binding-resolver.md): `BindingResolver` is the **read-only interface for looking up bindings by type identity** during schema rebinding. Given a type `A`, a resolver sea... - [Binding](https://zioblocks.com/reference/schema/binding.md): `Binding` is a sealed trait in ZIO Blocks that provides the operational machinery for constructing and deconstructing values of schema-described ty... - [Avro Codec Module](https://zioblocks.com/reference/schema/built-in-codecs/avro.md): `zio-blocks-schema-avro` is a **schema-driven Avro codec module** for serializing and deserializing Scala types to and from Avro binary format. It ... - [BSON Codec Module](https://zioblocks.com/reference/schema/built-in-codecs/bson.md): `zio-blocks-schema-bson` is a **schema-driven BSON codec module** for serializing and deserializing Scala types to and from BSON (Binary JSON) form... - [CSV Codec Module](https://zioblocks.com/reference/schema/built-in-codecs/csv.md): `zio-blocks-schema-csv` is a **schema-driven CSV codec module** for serializing and deserializing Scala types to and from CSV format. It provides R... - [Built-in Formats and Codecs](https://zioblocks.com/reference/schema/built-in-codecs/index.md): ZIO Blocks Schema provides codec derivation for multiple serialization formats. Once you have a `Schema[A]`, formats can be passed to `Schema.deriv... - [JSON Codec](https://zioblocks.com/reference/schema/built-in-codecs/json/index.md): The JSON codec module provides complete, type-safe support for working with JSON data in ZIO Blocks. It includes an ADT for representing JSON value... - [JSON Configuration](https://zioblocks.com/reference/schema/built-in-codecs/json/json-config.md): The JSON codec module provides four configuration types for controlling encoding and decoding behavior: `WriterConfig`, `ReaderConfig`, `MergeStrat... - [JsonDiffer](https://zioblocks.com/reference/schema/built-in-codecs/json/json-differ.md): `JsonDiffer` is a **diff algorithm for JSON values** that computes the minimal [`JsonPatch`](./json-patch.md) transforming one `Json` value into an... - [JsonPatch](https://zioblocks.com/reference/schema/built-in-codecs/json/json-patch.md): `JsonPatch` is an **untyped, composable patch** for [`Json`](./json.md) values. It represents a sequence of operations that transform one `Json` va... - [JSON Schema](https://zioblocks.com/reference/schema/built-in-codecs/json/json-schema.md): `JsonSchema` provides first-class support for [JSON Schema 2020-12](https://json-schema.org/specification-links.html#2020-12) in ZIO Blocks. It ena... - [JsonSelection](https://zioblocks.com/reference/schema/built-in-codecs/json/json-selection.md): `JsonSelection` is a fluent wrapper type that enables composable, chainable navigation through JSON structures. It wraps `Either[SchemaError, Chunk... - [Json](https://zioblocks.com/reference/schema/built-in-codecs/json/json.md): `Json` is a type-safe, schema-free representation of JSON values that enables navigation, transformation, merging, and querying without losing fide... - [MessagePack Codec Module](https://zioblocks.com/reference/schema/built-in-codecs/messagepack.md): `zio-blocks-schema-messagepack` is a **schema-driven MessagePack codec module** for serializing and deserializing Scala types to and from MessagePa... - [Thrift Codec Module](https://zioblocks.com/reference/schema/built-in-codecs/thrift.md): `zio-blocks-schema-thrift` is a **schema-driven Thrift codec module** for serializing and deserializing Scala types to and from Thrift binary forma... - [TOON Codec Module](https://zioblocks.com/reference/schema/built-in-codecs/toon.md): `zio-blocks-schema-toon` is a **schema-driven TOON codec module** for serializing and deserializing Scala types to and from TOON format. It provide... - [XML Codec Module](https://zioblocks.com/reference/schema/built-in-codecs/xml.md): `Xml` is a **sealed trait representing XML nodes**. It provides a type-safe, immutable representation of all valid XML document structures includin... - [YAML Codec Module](https://zioblocks.com/reference/schema/built-in-codecs/yaml.md): `zio-blocks-schema-yaml` is a **schema-driven YAML codec module** for serializing and deserializing Scala types to and from YAML format. It provide... - [Codec](https://zioblocks.com/reference/schema/codec.md): `Codec[DecodeInput, EncodeOutput, Value]` is the base abstraction for encoding and decoding values between a specific input representation and a sp... - [DynamicOptic](https://zioblocks.com/reference/schema/dynamic-optic.md): `DynamicOptic` is a runtime path through nested data structures in ZIO Blocks. It is the untyped, - [DynamicSchema](https://zioblocks.com/reference/schema/dynamic-schema.md): `DynamicSchema` is a **type-erased schema container** that wraps a `Reflect.Unbound[_]` tree — all the structural information from a `Schema[A]` (f... - [DynamicValue](https://zioblocks.com/reference/schema/dynamic-value.md): `DynamicValue` is a schema-less, dynamically-typed representation of any structured value in ZIO Blocks. It provides a universal data model that ca... - [Format Type](https://zioblocks.com/reference/schema/format.md): A `Format` is an abstraction that bundles together everything needed to serialize and deserialize data in a specific format (JSON, Avro, MessagePac... - [ZIO Blocks Schema](https://zioblocks.com/reference/schema/index.md): ZIO Blocks Schema is the core type system and serialization framework that provides reified structural metadata for Scala data types. It enables ty... - [Lazy](https://zioblocks.com/reference/schema/lazy.md): The `Lazy[A]` data type represents a deferred computation that produces a value of type `A`. Unlike Scala's built-in `lazy val`, ZIO Blocks' `Lazy`... - [Migration](https://zioblocks.com/reference/schema/migration.md): `Migration[A, B]` is ZIO Blocks Schema's typed API for evolving data from one schema version to another. It wraps a [`DynamicMigration`](#dynamicmi... - [Modifier](https://zioblocks.com/reference/schema/modifier.md): `Modifier` is a sealed trait that provides a mechanism to attach metadata and configuration to schema elements. Modifiers serve as annotations for ... - [Optics](https://zioblocks.com/reference/schema/optics.md): Optics are a fundamental feature of ZIO Blocks that enable type-safe, composable access and modification of nested data structures. What sets ZIO B... - [Patching](https://zioblocks.com/reference/schema/patch.md): The Patching system in ZIO Blocks provides a type-safe, serializable way to describe and apply transformations to data structures. Unlike direct mu... - [Path Interpolator](https://zioblocks.com/reference/schema/path-interpolator.md): :::tip - [ReflectTransformer](https://zioblocks.com/reference/schema/reflect-transformer.md): `ReflectTransformer[F, G]` rewrites a `Reflect[F, A]` tree into a `Reflect[G, A]` tree, changing the binding-metadata type constructor from `F` to ... - [Reflect](https://zioblocks.com/reference/schema/reflect.md): The `Reflect` data type is the foundational data structure underlying ZIO Blocks. While `Schema[A]` is the user-facing API that wraps a `Reflect`, ... - [Register System](https://zioblocks.com/reference/schema/registers.md): The register system is one of the key innovations in ZIO Blocks (ZIO Schema 2) that enables **zero-allocation, box-free construction and deconstruc... - [SchemaError](https://zioblocks.com/reference/schema/schema-error.md): `SchemaError` is a **structured error type** for schema operations in ZIO Blocks. It represents one or more validation, conversion, or structural f... - [As](https://zioblocks.com/reference/schema/schema-evolution/as.md): `As[A, B]` is a **bidirectional conversion type class** that extends `Into[A, B]` with a reverse direction. In addition to converting `A → B` via `... - [Schema Evolution](https://zioblocks.com/reference/schema/schema-evolution/index.md): Schema evolution is the process of changing data structures over time while keeping existing data readable and systems interoperable. ZIO Blocks pr... - [Into](https://zioblocks.com/reference/schema/schema-evolution/into.md): `Into[-A, +B]` is a **one-way conversion type class** that converts values of type `A` into values of type `B`, returning `Either[SchemaError, B]` ... - [SchemaExpr](https://zioblocks.com/reference/schema/schema-expr.md): `SchemaExpr[A, B]` is a **schema-aware expression** that computes a result of type `B` from an input value of type `A`. It is invariant in both typ... - [Schema Search and Update](https://zioblocks.com/reference/schema/schema-search.md): `SchemaSearch` and `TypeSearch` are the two `DynamicOptic` node kinds that turn a path into a search: instead of naming one field, they match every... - [Schema](https://zioblocks.com/reference/schema/schema.md): `Schema[A]` is the primary data type in ZIO Blocks (ZIO Schema 2) that contains reified information about the structure of a Scala data type `A`, t... - [Structural Types](https://zioblocks.com/reference/schema/structural-types.md):