effect 4.0.0-beta.70 → 4.0.0-beta.71

package/dist/unstable/sql/index.js

@@ -3,216 +3,38 @@
  */
 // @barrel: Auto-generated exports. Do not edit manually.
 /**
- * Effect SQL migration helpers for loading, ordering, and running schema
- * changes against a `SqlClient`.
- *
- * This module provides a migrator constructor plus loaders for common migration
- * layouts, including dynamic glob imports, Babel-style glob records, in-memory
- * records, and filesystem directories. It is intended for applications and
- * libraries that need to apply numbered SQL migrations on startup, in tests, or
- * as part of deployment tooling while keeping migration effects inside the
- * Effect environment.
- *
- * The migrator tracks applied migrations in a configurable table, defaults that
- * table to `effect_sql_migrations`, rejects duplicate migration ids, and only
- * runs migrations with an id greater than the latest recorded id. Pending
- * migrations are recorded and executed inside a `SqlClient` transaction; on
- * PostgreSQL the migrations table is explicitly locked, while other dialects
- * rely on the table's primary key or unique constraint to detect concurrent
- * runners. Migration effects should therefore be written to be transaction-aware,
- * and callers should account for dialect-specific DDL transaction behavior and
- * custom table names when coordinating schema dumps or external migration
- * tooling.
- *
  * @since 4.0.0
  */
 export * as Migrator from "./Migrator.js";
 /**
- * Defines the `SqlClient` service, the central runtime entry point for Effect's
- * unstable SQL support.
- *
- * A `SqlClient` combines the tagged-template statement constructor with a
- * scoped connection acquirer, dialect compiler, tracing attributes, optional row
- * transforms, reactive query helpers, and transaction management. Applications
- * typically consume it from `Context` to build parameterized queries, stream
- * rows, run raw driver operations, reserve a connection for lower-level work, or
- * wrap several query effects in `withTransaction`.
- *
- * Transactions are tracked through a per-client context service. Top-level
- * transactions acquire the configured transaction connection and issue the
- * dialect's begin/commit/rollback SQL; nested transactions reuse that
- * connection and rely on dialect-provided savepoint SQL. A query only joins a
- * transaction when it is run with the same client service, so avoid mixing
- * clients or manually reserved connections when atomicity matters. Dialect
- * integrations are also responsible for the compiler and transaction
- * statements, which means placeholder syntax, identifier escaping, row
- * transforms, savepoint support, and unprepared/raw statement behavior can
- * differ by database.
- *
  * @since 4.0.0
  */
 export * as SqlClient from "./SqlClient.js";
 /**
- * Defines the low-level SQL connection service and shared row/acquirer types
- * used by Effect's unstable SQL driver integrations.
- *
- * A `Connection` is the driver-facing layer underneath `SqlClient`: it executes
- * already-compiled SQL with positional parameters and exposes transformed row
- * results, raw driver results, streams, value arrays, and unprepared statement
- * execution. Most applications should work through `SqlClient`, while driver
- * integrations and advanced code use this module to provide scoped connection
- * acquisition, implement pooling, reserve a connection for a workflow, or adapt
- * a dialect-specific client into Effect.
- *
- * Connections are resources and should be acquired through an `Acquirer` in a
- * `Scope` so pool checkout, transaction pinning, and release semantics are
- * preserved. Transaction coordination lives at the `SqlClient` layer, so mixing
- * manually reserved connections with transactional client queries can bypass the
- * expected atomic boundary. Raw, unprepared, streaming, parameter, and row
- * transformation behavior ultimately comes from the driver and dialect; check
- * each integration for differences in placeholders, prepared statement support,
- * cursor lifetime, and result shapes.
- *
  * @since 4.0.0
  */
 export * as SqlConnection from "./SqlConnection.js";
 /**
- * Structured SQL errors used by the unstable SQL APIs.
- *
- * This module defines the top-level `SqlError` wrapper, the concrete
- * `SqlErrorReason` variants used by drivers and adapters, and helpers for
- * recognizing and classifying database failures. It is useful when turning
- * native driver errors into typed Effect failures, choosing retry policies from
- * `isRetryable`, or distinguishing user-facing query problems such as syntax
- * and constraint failures from infrastructure problems such as connection,
- * lock, statement timeout, deadlock, and serialization failures.
- *
- * Query, connection, and migration code should preserve the original cause and
- * operation metadata when constructing these errors. Retrying can be appropriate
- * for transient connection and concurrency failures, but syntax, authorization,
- * authentication, and constraint failures generally require changing the query,
- * credentials, permissions, or migration data. When classifying SQLite errors,
- * the helpers inspect `code` and `errno` values and extract unique constraint
- * names when available.
- *
  * @since 4.0.0
  */
 export * as SqlError from "./SqlError.js";
 /**
- * Builds SQL repositories and request resolvers from Effect schema models.
- *
- * Use this module when a `Model` describes rows in a concrete SQL table and
- * you want the common insert, update, find-by-id, and delete operations without
- * hand-writing the schema encoding, row decoding, and resolver batching each
- * time. The helpers are intended for model-backed tables where the model field
- * names line up with the encoded table columns and the chosen `idColumn` is
- * present in both the model fields and update schema.
- *
- * Returned rows are decoded with the full model schema, while insert and update
- * requests are encoded with the model's dedicated input schemas. Soft deletes
- * are opt-in via `softDeleteColumn`: reads and updates only see rows where that
- * column is `null`, and deletes set it to `CURRENT_TIMESTAMP` instead of
- * removing the row. Dialects with `returning` support return changed rows
- * directly; MySQL performs a follow-up `select`, so generated ids, defaults,
- * and trigger-updated values must be observable from that query.
- *
  * @since 4.0.0
  */
 export * as SqlModel from "./SqlModel.js";
 /**
- * Schema-aware `RequestResolver` helpers for SQL-backed data loading.
- *
- * This module bridges `Effect.request` with `SqlClient` by representing each
- * lookup or mutation as a `SqlRequest` and batching concurrent requests into a
- * single SQL operation. Request payloads are encoded with the request schema
- * before `execute` is called, and rows returned by the query are decoded with
- * the result schema before entries are completed.
- *
- * Use `ordered` when a query returns exactly one row per request in the same
- * order, `findById` for `where id in (...)` lookups, `grouped` for one-to-many
- * relationships, and `void` for inserts, updates, deletes, or other
- * side-effecting statements where no row is needed.
- *
- * **Gotchas**
- *
- * - `ordered` requires the result count and order to match the request batch.
- * - `grouped` and `findById` rely on stable request/result keys and fail
- *   missing requests with `NoSuchElementError`.
- * - Equal payloads are equal `SqlRequest`s, which enables request batching,
- *   deduplication, and cache reuse; model payload identity deliberately.
- * - Batches are split by the active SQL transaction connection, so requests
- *   made in different transactions are not resolved together.
- * - Queries like `where id in (...)` often return rows in database order; use
- *   `findById` or `grouped`, or preserve input order explicitly before choosing
- *   `ordered`.
- *
  * @since 4.0.0
  */
 export * as SqlResolver from "./SqlResolver.js";
 /**
- * Schema-driven helpers for wrapping SQL executions in typed query functions.
- *
- * This module connects `Schema` request and result definitions to an `execute`
- * callback that runs the actual SQL statement. The returned functions accept
- * the request schema's decoded `Type`, encode it to the SQL-facing `Encoded`
- * shape, run the callback, and then decode unknown driver rows through the
- * result schema. This is useful for repository methods, CRUD helpers, request
- * resolvers, and write operations where callers should work with domain values
- * instead of raw SQL parameters or rows.
- *
- * The `execute` callback always receives `Req["Encoded"]`, so schema
- * transformations, required encoding services, and database representations
- * such as nullable columns, JSON values, dates, and bigints must line up with
- * the statement builder and dialect in use. Result schemas decode the rows
- * returned by the driver after any SQL client row transforms; `findOne` and
- * `findOneOption` only inspect the first row, `findNonEmpty` requires at least
- * one row, and `void` discards any driver result after request encoding.
- *
  * @since 4.0.0
  */
 export * as SqlSchema from "./SqlSchema.js";
 /**
- * Low-level helpers for adapting push-based SQL row sources into Effect
- * streams.
- *
- * SQL drivers often expose large query results through cursors, event emitters,
- * or driver-specific streams that push rows as they arrive. This module
- * provides the small interop layer used by SQL integrations to turn those
- * producers into `Stream` values for `Statement.stream` and
- * `Connection.executeStream`, so callers can process large result sets
- * incrementally instead of materializing every row in memory.
- *
- * The adapter is scoped: driver cursors, query streams, or reserved
- * connections should be acquired in the registration effect and released with
- * finalizers. The internal queue is bounded and calls the producer's
- * `onPause`/`onResume` hooks when downstream consumption falls behind, but the
- * underlying driver still has to honor those hooks for backpressure to be
- * effective. Slow consumers may keep a database cursor and connection open for
- * the lifetime of the stream, so integrations should close or destroy driver
- * resources on interruption, failure, or normal completion and should signal
- * terminal events with `fail` or `end` exactly once.
- *
  * @since 4.0.0
  */
 export * as SqlStream from "./SqlStream.js";
 /**
- * Building blocks for Effect's unstable SQL statement API.
- *
- * This module defines the low-level `Statement` and `Fragment` model used by
- * SQL clients, the tagged-template `Constructor` for creating executable
- * parameterized statements, and dialect compilers that turn statement segments
- * into SQL text plus bind parameters. It also provides helpers for escaped
- * identifiers, `IN` lists, comma-separated clause fragments, record inserts and
- * updates, custom segments, and row or identifier transforms.
- *
- * In tagged templates, interpolated `Fragment`s and known `Segment`s are
- * spliced into the statement, while ordinary values become bound parameters. Use
- * identifiers for table and column names and the record helpers for generated
- * column lists; `literal` and `unsafe` insert SQL text directly and should only
- * be used with trusted SQL. Compilation is dialect-specific, caches rendered SQL
- * on the statement, and has a `withoutTransform` path for bypassing identifier
- * transforms, so compiled output can differ from normal transformed execution.
- *
  * @since 4.0.0
  */
 export * as Statement from "./Statement.js";

package/dist/unstable/sql/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Migrator","SqlClient","SqlConnection","SqlError","SqlModel","SqlResolver","SqlSchema","SqlStream","Statement"],"sources":["../../../src/unstable/sql/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,KAAKA,QAAQ,MAAM,eAAe;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AAEnD;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;;;;;;;;;;;;;;;;;;;AAqBA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;;;;;;;;;;;;;;;;;;;;;AAuBA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;;;;;;;;;;;;;;;;;;AAoBA,OAAO,KAAKC,SAAS,MAAM,gBAAgB","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Migrator","SqlClient","SqlConnection","SqlError","SqlModel","SqlResolver","SqlSchema","SqlStream","Statement"],"sources":["../../../src/unstable/sql/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAKA,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;AAGA,OAAO,KAAKC,aAAa,MAAM,oBAAoB;AAEnD;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAKC,WAAW,MAAM,kBAAkB;AAE/C;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB;AAE3C;;;AAGA,OAAO,KAAKC,SAAS,MAAM,gBAAgB","ignoreList":[]}

package/dist/unstable/workers/Transferable.d.ts

@@ -1,19 +1,33 @@
 /**
- * Utilities for marking the parts of worker messages that should be transferred
- * through `postMessage` instead of copied by the structured clone algorithm.
- *
- * This module is used with worker message schemas to collect
- * `globalThis.Transferable` values while encoding a message, so the worker
- * platform can pass the collected list as the `postMessage` transfer list.
- * Common cases include sending large `Uint8Array` payloads, `ImageData` pixel
- * buffers, or `MessagePort` channels without paying for an extra copy.
- *
- * Transferable annotations do not make an otherwise unsupported value
- * structured-cloneable; the encoded message still has to be valid for
- * `postMessage`. Transferring also moves ownership to the receiver, so buffers
- * are detached from the sender after the send completes. Be careful when a
- * typed array view shares a backing buffer with other data, since collecting
- * that buffer transfers ownership of the whole buffer.
+ * Marks encoded worker message fields that should move through `postMessage` as
+ * transfer-list entries.
+ *
+ * Worker messages still pass through schema encoding and structured clone, but
+ * schemas wrapped with `schema` can also report backing resources such as
+ * `ArrayBuffer`, `ImageData.data.buffer`, or `MessagePort` to a `Collector`.
+ * Worker platforms then pass the collected values as the transfer list for the
+ * same `postMessage` call, avoiding copies for large payloads and ports.
+ *
+ * **Mental model**
+ *
+ * A `Collector` is an optional context service. During encoding, `getterAddAll`
+ * and `schema` add transferable values when a collector is present and leave the
+ * encoded value unchanged. The built-in `Uint8Array`, `ImageData`, and
+ * `MessagePort` schemas are convenience wrappers around the same behavior.
+ *
+ * **Common tasks**
+ *
+ * Wrap a worker message field with `schema` when the transferable is nested or
+ * derived from the encoded value. Provide a fresh collector around each message
+ * encode, read or clear it after encoding, and pass the resulting list to the
+ * worker transport.
+ *
+ * **Gotchas**
+ *
+ * Transfer annotations do not make unsupported values structured-cloneable.
+ * Ownership moves to the receiver after `postMessage`, so buffers are detached
+ * from the sender. For typed array views, collecting `view.buffer` transfers the
+ * whole backing buffer, including bytes used by other views.
  *
  * @since 4.0.0
  */

package/dist/unstable/workers/Transferable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Transferable.d.ts","sourceRoot":"","sources":["../../../src/unstable/workers/Transferable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;;qBAU5B,CACf,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,KACjC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;2BACD,CAAC,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,KAAK,IAAI;mBACtD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;yBACvC,MAAM,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC;0BACnC,MAAM,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC;oBAC1C,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;;AAf/D;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,cASc;CAAG;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAAO,SAAS,CAAC,SAAS,CAmBzD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAoC,CAAA;AAElG;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GACjB,cAAc,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,KAC9C,MAAM,CAAC,MAAM,CAAC,IAAI,CAMjB,CAAA;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAC5B,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,KAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAQlB,CAAA;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,CAAE,SAClD,MAAM,CAAC,QAAQ,CACb,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAC3B,CAAC,CAAC,SAAS,CAAC,CACb;CACD;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB;;;;;;OAMG;IACH,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,CAAA;IAC/G;;;;;;OAMG;IACH,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAA;CAe5G,CAAA;AAOD;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAG7D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAGjE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAG1F,CAAA"}
+{"version":3,"file":"Transferable.d.ts","sourceRoot":"","sources":["../../../src/unstable/workers/Transferable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;;qBAU5B,CACf,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,KACjC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;2BACD,CAAC,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,KAAK,IAAI;mBACtD,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;yBACvC,MAAM,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC;0BACnC,MAAM,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC;oBAC1C,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;;AAf/D;;;;;;GAMG;AACH,qBAAa,SAAU,SAAQ,cASc;CAAG;AAEhD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAAO,SAAS,CAAC,SAAS,CAmBzD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,CAAoC,CAAA;AAElG;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GACjB,cAAc,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,KAC9C,MAAM,CAAC,MAAM,CAAC,IAAI,CAMjB,CAAA;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,CAAC,EAC5B,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,KAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAQlB,CAAA;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,CAAE,SAClD,MAAM,CAAC,QAAQ,CACb,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,EAC3B,CAAC,CAAC,SAAS,CAAC,CACb;CACD;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAE;IACnB;;;;;;OAMG;IACH,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,CAAA;IAC/G;;;;;;OAMG;IACH,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAA;CAe5G,CAAA;AAOD;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAG7D,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAGjE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,YAAY,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAG1F,CAAA"}

package/dist/unstable/workers/Transferable.js

@@ -1,19 +1,33 @@
 /**
- * Utilities for marking the parts of worker messages that should be transferred
- * through `postMessage` instead of copied by the structured clone algorithm.
- *
- * This module is used with worker message schemas to collect
- * `globalThis.Transferable` values while encoding a message, so the worker
- * platform can pass the collected list as the `postMessage` transfer list.
- * Common cases include sending large `Uint8Array` payloads, `ImageData` pixel
- * buffers, or `MessagePort` channels without paying for an extra copy.
- *
- * Transferable annotations do not make an otherwise unsupported value
- * structured-cloneable; the encoded message still has to be valid for
- * `postMessage`. Transferring also moves ownership to the receiver, so buffers
- * are detached from the sender after the send completes. Be careful when a
- * typed array view shares a backing buffer with other data, since collecting
- * that buffer transfers ownership of the whole buffer.
+ * Marks encoded worker message fields that should move through `postMessage` as
+ * transfer-list entries.
+ *
+ * Worker messages still pass through schema encoding and structured clone, but
+ * schemas wrapped with `schema` can also report backing resources such as
+ * `ArrayBuffer`, `ImageData.data.buffer`, or `MessagePort` to a `Collector`.
+ * Worker platforms then pass the collected values as the transfer list for the
+ * same `postMessage` call, avoiding copies for large payloads and ports.
+ *
+ * **Mental model**
+ *
+ * A `Collector` is an optional context service. During encoding, `getterAddAll`
+ * and `schema` add transferable values when a collector is present and leave the
+ * encoded value unchanged. The built-in `Uint8Array`, `ImageData`, and
+ * `MessagePort` schemas are convenience wrappers around the same behavior.
+ *
+ * **Common tasks**
+ *
+ * Wrap a worker message field with `schema` when the transferable is nested or
+ * derived from the encoded value. Provide a fresh collector around each message
+ * encode, read or clear it after encoding, and pass the resulting list to the
+ * worker transport.
+ *
+ * **Gotchas**
+ *
+ * Transfer annotations do not make unsupported values structured-cloneable.
+ * Ownership moves to the receiver after `postMessage`, so buffers are detached
+ * from the sender. For typed array views, collecting `view.buffer` transfers the
+ * whole backing buffer, including bytes used by other views.
  *
  * @since 4.0.0
  */

package/dist/unstable/workers/Transferable.js.map

@@ -1 +1 @@
-{"version":3,"file":"Transferable.js","names":["Context","Effect","dual","Schema","Getter","Collector","Service","makeCollectorUnsafe","tranferables","unsafeAddAll","transfers","push","unsafeRead","unsafeClear","prev","of","addAllUnsafe","addAll","transferables","sync","readUnsafe","read","clearUnsafe","clear","makeCollector","contextWith","services","collector","getOrUndefined","void","getterAddAll","f","transformOrFail","e","succeed","schema","self","annotate","toCodecJson","passthroughLink","pipe","decode","passthrough","encode","link","Any","ImageData","_","data","buffer","MessagePort","Uint8Array"],"sources":["../../../src/unstable/workers/Transferable.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"Transferable.js","names":["Context","Effect","dual","Schema","Getter","Collector","Service","makeCollectorUnsafe","tranferables","unsafeAddAll","transfers","push","unsafeRead","unsafeClear","prev","of","addAllUnsafe","addAll","transferables","sync","readUnsafe","read","clearUnsafe","clear","makeCollector","contextWith","services","collector","getOrUndefined","void","getterAddAll","f","transformOrFail","e","succeed","schema","self","annotate","toCodecJson","passthroughLink","pipe","decode","passthrough","encode","link","Any","ImageData","_","data","buffer","MessagePort","Uint8Array"],"sources":["../../../src/unstable/workers/Transferable.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/unstable/workers/Worker.d.ts

@@ -1,27 +1,40 @@
 /**
- * Client-side worker primitives shared by browser, Node, and Bun platform
- * packages.
- *
- * A `WorkerPlatform` turns a numeric worker id into a long-lived `Worker`
- * client using a runtime-specific `Spawner`. This module is the low-level
- * building block used by worker-backed RPC clients and by platform adapters
- * that need to communicate with dedicated workers, shared workers,
- * `MessagePort`s, worker threads, or child-process transports while keeping
- * setup, message handling, and cleanup inside `Effect` scopes.
- *
- * The worker protocol separates spawning from message delivery. Calls to
- * `send` made before the platform reports readiness are buffered and flushed
- * after `run` receives the ready signal, so a spawned worker must eventually be
- * run or buffered messages will never leave the client. Message values are
- * passed through `postMessage`, which means callers are responsible for
- * encoding payloads into values supported by the selected runtime's structured
- * clone implementation. Transfer lists can avoid copies for buffers, ports, or
- * other transferable values, but ownership moves to the worker and invalid
- * transfer lists surface as `WorkerSendError`s. Incoming messages are handled
- * by forking each handler invocation into the worker run's `FiberSet`, so
- * processing is concurrent rather than serialized; use an explicit queue,
- * semaphore, or protocol-level acknowledgement when ordering or back pressure
- * matters.
+ * Client-side worker primitives shared by browser, Node, and Bun adapters.
+ *
+ * This module defines the platform-neutral {@link Worker} client and the
+ * {@link WorkerPlatform} service that creates one for a numeric worker id.
+ * Platform packages provide the runtime-specific spawn, setup, listen, and
+ * cleanup logic; higher-level code uses the resulting worker to send messages
+ * and run an Effect handler for messages coming back from the worker.
+ *
+ * **Mental model**
+ *
+ * A {@link Spawner} locates or creates the native worker value, and
+ * {@link makePlatform} turns platform hooks into a scoped {@link Worker}.
+ * Sending and receiving are separate: `send` queues outbound values until
+ * `run` observes the platform ready signal, then `run` keeps the message loop
+ * alive and owns the cleanup scope for the active port.
+ *
+ * **Common tasks**
+ *
+ * Use {@link layerSpawner} to provide the runtime's worker lookup function,
+ * {@link makePlatform} to build browser, Node, Bun, or custom adapters, and
+ * {@link makeUnsafe} when an adapter already exposes the low-level platform
+ * protocol. Worker-backed RPC clients use these primitives to communicate with
+ * dedicated workers, shared workers, `MessagePort`s, worker threads, or child
+ * processes.
+ *
+ * **Gotchas**
+ *
+ * - Messages sent before readiness are buffered, so the returned worker must be
+ *   run or those messages never leave the client
+ * - Values pass through `postMessage`; callers must use values supported by
+ *   the selected runtime's structured clone implementation
+ * - Transfer lists can avoid copies, but ownership moves to the worker and
+ *   invalid transfer lists fail with `WorkerSendError`
+ * - Incoming messages are handled concurrently in the run fiber set; add a
+ *   queue, semaphore, or protocol acknowledgement when ordering or back
+ *   pressure matters
  *
  * @since 4.0.0
  */

package/dist/unstable/workers/Worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Worker.d.ts","sourceRoot":"","sources":["../../../src/unstable/workers/Worker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Worker.d.ts","sourceRoot":"","sources":["../../../src/unstable/workers/Worker.ts"],"names":[],"mappings":"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"}

package/dist/unstable/workers/Worker.js

@@ -1,27 +1,40 @@
 /**
- * Client-side worker primitives shared by browser, Node, and Bun platform
- * packages.
+ * Client-side worker primitives shared by browser, Node, and Bun adapters.
  *
- * A `WorkerPlatform` turns a numeric worker id into a long-lived `Worker`
- * client using a runtime-specific `Spawner`. This module is the low-level
- * building block used by worker-backed RPC clients and by platform adapters
- * that need to communicate with dedicated workers, shared workers,
- * `MessagePort`s, worker threads, or child-process transports while keeping
- * setup, message handling, and cleanup inside `Effect` scopes.
+ * This module defines the platform-neutral {@link Worker} client and the
+ * {@link WorkerPlatform} service that creates one for a numeric worker id.
+ * Platform packages provide the runtime-specific spawn, setup, listen, and
+ * cleanup logic; higher-level code uses the resulting worker to send messages
+ * and run an Effect handler for messages coming back from the worker.
  *
- * The worker protocol separates spawning from message delivery. Calls to
- * `send` made before the platform reports readiness are buffered and flushed
- * after `run` receives the ready signal, so a spawned worker must eventually be
- * run or buffered messages will never leave the client. Message values are
- * passed through `postMessage`, which means callers are responsible for
- * encoding payloads into values supported by the selected runtime's structured
- * clone implementation. Transfer lists can avoid copies for buffers, ports, or
- * other transferable values, but ownership moves to the worker and invalid
- * transfer lists surface as `WorkerSendError`s. Incoming messages are handled
- * by forking each handler invocation into the worker run's `FiberSet`, so
- * processing is concurrent rather than serialized; use an explicit queue,
- * semaphore, or protocol-level acknowledgement when ordering or back pressure
- * matters.
+ * **Mental model**
+ *
+ * A {@link Spawner} locates or creates the native worker value, and
+ * {@link makePlatform} turns platform hooks into a scoped {@link Worker}.
+ * Sending and receiving are separate: `send` queues outbound values until
+ * `run` observes the platform ready signal, then `run` keeps the message loop
+ * alive and owns the cleanup scope for the active port.
+ *
+ * **Common tasks**
+ *
+ * Use {@link layerSpawner} to provide the runtime's worker lookup function,
+ * {@link makePlatform} to build browser, Node, Bun, or custom adapters, and
+ * {@link makeUnsafe} when an adapter already exposes the low-level platform
+ * protocol. Worker-backed RPC clients use these primitives to communicate with
+ * dedicated workers, shared workers, `MessagePort`s, worker threads, or child
+ * processes.
+ *
+ * **Gotchas**
+ *
+ * - Messages sent before readiness are buffered, so the returned worker must be
+ *   run or those messages never leave the client
+ * - Values pass through `postMessage`; callers must use values supported by
+ *   the selected runtime's structured clone implementation
+ * - Transfer lists can avoid copies, but ownership moves to the worker and
+ *   invalid transfer lists fail with `WorkerSendError`
+ * - Incoming messages are handled concurrently in the run fiber set; add a
+ *   queue, semaphore, or protocol acknowledgement when ordering or back
+ *   pressure matters
  *
  * @since 4.0.0
  */

package/dist/unstable/workers/Worker.js.map

@@ -1 +1 @@
-{"version":3,"file":"Worker.js","names":["Context","Effect","FiberSet","Latch","Layer","Scope","WorkerError","WorkerSendError","WorkerPlatform","Service","makeUnsafe","options","send","run","handler","options_","onSpawn","void","msg","Spawner","layerSpawner","succeed","makePlatform","of","spawn","id","gen","currentPort","buffer","opts","uninterruptibleMask","restore","scopedWith","fnUntraced","scope","port","setup","worker","addFinalizer","sync","undefined","fiberSet","make","pipe","provide","runtime","ready","listen","emit","data","ensuring","open","openUnsafe","deferred","await","length","message","transfers","postMessage","join","suspend","push","cause","fail","reason"],"sources":["../../../src/unstable/workers/Worker.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"Worker.js","names":["Context","Effect","FiberSet","Latch","Layer","Scope","WorkerError","WorkerSendError","WorkerPlatform","Service","makeUnsafe","options","send","run","handler","options_","onSpawn","void","msg","Spawner","layerSpawner","succeed","makePlatform","of","spawn","id","gen","currentPort","buffer","opts","uninterruptibleMask","restore","scopedWith","fnUntraced","scope","port","setup","worker","addFinalizer","sync","undefined","fiberSet","make","pipe","provide","runtime","ready","listen","emit","data","ensuring","open","openUnsafe","deferred","await","length","message","transfers","postMessage","join","suspend","push","cause","fail","reason"],"sources":["../../../src/unstable/workers/Worker.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/unstable/workers/WorkerError.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkerError.d.ts","sourceRoot":"","sources":["../../../src/unstable/workers/WorkerError.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC,QAAA,MAAM,MAAM,EAAG,6BAAsC,CAAA;AAErD;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAA;AAElC;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,WAAqC,CAAA;;;;;;AAErF;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,qBAMpC;CAAG;;;;;;AAEL;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,oBAMnC;CAAG;;;;;;AAEL;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,uBAMtC;CAAG;;;;;;AAEL;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,uBAMtC;CAAG;AAEL;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,eAAe,GACf,kBAAkB,GAClB,kBAAkB,CAAA;AAEtB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,KAAK,CAAC;IAC3C,OAAO,gBAAgB;IACvB,OAAO,eAAe;IACtB,OAAO,kBAAkB;IACzB,OAAO,kBAAkB;CAC1B,CAKC,CAAA;;;;;AAEF;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,gBAG/B;gBAEY,KAAK,EAAE;QACjB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;KACnC;IAMD;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAS;IAElC,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF"}
+{"version":3,"file":"WorkerError.d.ts","sourceRoot":"","sources":["../../../src/unstable/workers/WorkerError.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAA;AAEzC,QAAA,MAAM,MAAM,EAAG,6BAAsC,CAAA;AAErD;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAA;AAElC;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,WAAqC,CAAA;;;;;;AAErF;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,qBAMpC;CAAG;;;;;;AAEL;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,oBAMnC;CAAG;;;;;;AAEL;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,uBAMtC;CAAG;;;;;;AAEL;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,uBAMtC;CAAG;AAEL;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,gBAAgB,GAChB,eAAe,GACf,kBAAkB,GAClB,kBAAkB,CAAA;AAEtB;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,KAAK,CAAC;IAC3C,OAAO,gBAAgB;IACvB,OAAO,eAAe;IACtB,OAAO,kBAAkB;IACzB,OAAO,kBAAkB;CAC1B,CAKC,CAAA;;;;;AAEF;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,gBAG/B;gBAEY,KAAK,EAAE;QACjB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;KACnC;IAMD;;;;OAIG;IACH,QAAQ,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAS;IAElC,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF"}

package/dist/unstable/workers/WorkerError.js

@@ -1,22 +1,38 @@
 /**
- * Typed error definitions for the unstable worker APIs.
+ * The `WorkerError` module defines the typed error model shared by the
+ * unstable worker APIs. Worker client and runner platforms use
+ * {@link WorkerError} when platform setup, sending, receiving, or
+ * runtime-specific worker behavior fails.
  *
- * `WorkerError` is the shared error channel for `WorkerPlatform` and
- * `WorkerRunnerPlatform` implementations. The nested reason identifies where a
- * platform failure happened: spawning or setting up a worker, sending through
- * `postMessage`, receiving worker events, or handling a runtime-specific
- * failure that does not fit the other categories. This is useful when building
- * worker-backed RPC clients and servers, implementing a platform adapter, or
- * recovering differently from startup, transport, and worker-exit failures.
+ * **Mental model**
  *
- * Worker transports cross browser, Node, Bun, and child-process runtimes, so the
- * original cause is best treated as diagnostic data. Spawn failures can mean the
- * runner is not actually executing inside a worker context, send failures often
- * come from structured-clone or transfer-list problems, and receive failures
- * may be reported as `messageerror`, `error`, or exit events depending on the
- * runtime. The `WorkerErrorReason` schema supports encoding and decoding the
- * tagged reasons, but message payloads still need to be valid for the selected
- * worker protocol and runtime.
+ * - {@link WorkerError} is the outer error exposed in worker effect error
+ *   channels
+ * - {@link WorkerErrorReason} records one tagged reason: spawn, send,
+ *   receive, or unknown
+ * - The outer error delegates `message` and `cause` to the nested reason
+ * - Reason schemas can be encoded and decoded when worker or RPC layers need
+ *   structured diagnostics
+ *
+ * **Common tasks**
+ *
+ * - Detect worker failures with {@link isWorkerError}
+ * - Classify startup and setup problems with {@link WorkerSpawnError}
+ * - Classify `postMessage` or transfer-list failures with
+ *   {@link WorkerSendError}
+ * - Classify inbound event, `messageerror`, or worker-exit failures with
+ *   {@link WorkerReceiveError}
+ * - Preserve runtime-specific failures that do not fit another case with
+ *   {@link WorkerUnknownError}
+ *
+ * **Gotchas**
+ *
+ * - The `cause` is diagnostic data and can have different shapes across
+ *   browser, Node, Bun, and child-process transports
+ * - A `WorkerSendError` often means the payload was invalid for the selected
+ *   structured-clone or transfer-list rules
+ * - A `WorkerSpawnError` can mean the runner code is not executing inside the
+ *   expected worker context
  *
  * @since 4.0.0
  */

package/dist/unstable/workers/WorkerError.js.map

@@ -1 +1 @@
-{"version":3,"file":"WorkerError.js","names":["hasProperty","Schema","TypeId","isWorkerError","u","WorkerSpawnError","ErrorClass","_tag","tag","message","String","cause","optional","Defect","WorkerSendError","WorkerReceiveError","WorkerUnknownError","WorkerErrorReason","Union","WorkerError","reason","constructor","props"],"sources":["../../../src/unstable/workers/WorkerError.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;AAsBA,SAASA,WAAW,QAAQ,oBAAoB;AAChD,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AAEzC,MAAMC,MAAM,GAAG,6BAAsC;AAUrD;;;;;;AAMA,OAAO,MAAMC,aAAa,GAAIC,CAAU,IAAuBJ,WAAW,CAACI,CAAC,EAAEF,MAAM,CAAC;AAErF;;;;;;AAMA,OAAM,MAAOG,gBAAiB,sBAAQJ,MAAM,CAACK,UAAU,CACrD,6CAA6C,CAC9C,CAAC;EACAC,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,kBAAkB,CAAC;EACpCC,OAAO,EAAER,MAAM,CAACS,MAAM;EACtBC,KAAK,eAAEV,MAAM,CAACW,QAAQ,CAACX,MAAM,CAACY,MAAM;CACrC,CAAC;AAEF;;;;;;AAMA,OAAM,MAAOC,eAAgB,sBAAQb,MAAM,CAACK,UAAU,CACpD,4CAA4C,CAC7C,CAAC;EACAC,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,iBAAiB,CAAC;EACnCC,OAAO,EAAER,MAAM,CAACS,MAAM;EACtBC,KAAK,eAAEV,MAAM,CAACW,QAAQ,CAACX,MAAM,CAACY,MAAM;CACrC,CAAC;AAEF;;;;;;;AAOA,OAAM,MAAOE,kBAAmB,sBAAQd,MAAM,CAACK,UAAU,CACvD,+CAA+C,CAChD,CAAC;EACAC,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,oBAAoB,CAAC;EACtCC,OAAO,EAAER,MAAM,CAACS,MAAM;EACtBC,KAAK,eAAEV,MAAM,CAACW,QAAQ,CAACX,MAAM,CAACY,MAAM;CACrC,CAAC;AAEF;;;;;;AAMA,OAAM,MAAOG,kBAAmB,sBAAQf,MAAM,CAACK,UAAU,CACvD,+CAA+C,CAChD,CAAC;EACAC,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,oBAAoB,CAAC;EACtCC,OAAO,EAAER,MAAM,CAACS,MAAM;EACtBC,KAAK,eAAEV,MAAM,CAACW,QAAQ,CAACX,MAAM,CAACY,MAAM;CACrC,CAAC;AAcF;;;;;;AAMA,OAAO,MAAMI,iBAAiB,gBAKzBhB,MAAM,CAACiB,KAAK,CAAC,CAChBb,gBAAgB,EAChBS,eAAe,EACfC,kBAAkB,EAClBC,kBAAkB,CACnB,CAAC;AAEF;;;;;;;AAOA,OAAM,MAAOG,WAAY,sBAAQlB,MAAM,CAACK,UAAU,CAAcJ,MAAM,CAAC,CAAC;EACtEK,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,aAAa,CAAC;EAC/BY,MAAM,EAAEH;CACT,CAAC;EACA;EACAI,YAAYC,KAEX;IACC,KAAK,CAAC;MACJ,GAAGA,KAAK;MACRX,KAAK,EAAEW,KAAK,CAACF,MAAM,CAACT;KACd,CAAC;EACX;EACA;;;;;EAKS,CAACT,MAAM,IAAYA,MAAM;EAElC,IAAaO,OAAOA,CAAA;IAClB,OAAO,IAAI,CAACW,MAAM,CAACX,OAAO;EAC5B","ignoreList":[]}
+{"version":3,"file":"WorkerError.js","names":["hasProperty","Schema","TypeId","isWorkerError","u","WorkerSpawnError","ErrorClass","_tag","tag","message","String","cause","optional","Defect","WorkerSendError","WorkerReceiveError","WorkerUnknownError","WorkerErrorReason","Union","WorkerError","reason","constructor","props"],"sources":["../../../src/unstable/workers/WorkerError.ts"],"sourcesContent":[null],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAASA,WAAW,QAAQ,oBAAoB;AAChD,OAAO,KAAKC,MAAM,MAAM,iBAAiB;AAEzC,MAAMC,MAAM,GAAG,6BAAsC;AAUrD;;;;;;AAMA,OAAO,MAAMC,aAAa,GAAIC,CAAU,IAAuBJ,WAAW,CAACI,CAAC,EAAEF,MAAM,CAAC;AAErF;;;;;;AAMA,OAAM,MAAOG,gBAAiB,sBAAQJ,MAAM,CAACK,UAAU,CACrD,6CAA6C,CAC9C,CAAC;EACAC,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,kBAAkB,CAAC;EACpCC,OAAO,EAAER,MAAM,CAACS,MAAM;EACtBC,KAAK,eAAEV,MAAM,CAACW,QAAQ,CAACX,MAAM,CAACY,MAAM;CACrC,CAAC;AAEF;;;;;;AAMA,OAAM,MAAOC,eAAgB,sBAAQb,MAAM,CAACK,UAAU,CACpD,4CAA4C,CAC7C,CAAC;EACAC,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,iBAAiB,CAAC;EACnCC,OAAO,EAAER,MAAM,CAACS,MAAM;EACtBC,KAAK,eAAEV,MAAM,CAACW,QAAQ,CAACX,MAAM,CAACY,MAAM;CACrC,CAAC;AAEF;;;;;;;AAOA,OAAM,MAAOE,kBAAmB,sBAAQd,MAAM,CAACK,UAAU,CACvD,+CAA+C,CAChD,CAAC;EACAC,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,oBAAoB,CAAC;EACtCC,OAAO,EAAER,MAAM,CAACS,MAAM;EACtBC,KAAK,eAAEV,MAAM,CAACW,QAAQ,CAACX,MAAM,CAACY,MAAM;CACrC,CAAC;AAEF;;;;;;AAMA,OAAM,MAAOG,kBAAmB,sBAAQf,MAAM,CAACK,UAAU,CACvD,+CAA+C,CAChD,CAAC;EACAC,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,oBAAoB,CAAC;EACtCC,OAAO,EAAER,MAAM,CAACS,MAAM;EACtBC,KAAK,eAAEV,MAAM,CAACW,QAAQ,CAACX,MAAM,CAACY,MAAM;CACrC,CAAC;AAcF;;;;;;AAMA,OAAO,MAAMI,iBAAiB,gBAKzBhB,MAAM,CAACiB,KAAK,CAAC,CAChBb,gBAAgB,EAChBS,eAAe,EACfC,kBAAkB,EAClBC,kBAAkB,CACnB,CAAC;AAEF;;;;;;;AAOA,OAAM,MAAOG,WAAY,sBAAQlB,MAAM,CAACK,UAAU,CAAcJ,MAAM,CAAC,CAAC;EACtEK,IAAI,eAAEN,MAAM,CAACO,GAAG,CAAC,aAAa,CAAC;EAC/BY,MAAM,EAAEH;CACT,CAAC;EACA;EACAI,YAAYC,KAEX;IACC,KAAK,CAAC;MACJ,GAAGA,KAAK;MACRX,KAAK,EAAEW,KAAK,CAACF,MAAM,CAACT;KACd,CAAC;EACX;EACA;;;;;EAKS,CAACT,MAAM,IAAYA,MAAM;EAElC,IAAaO,OAAOA,CAAA;IAClB,OAAO,IAAI,CAACW,MAAM,CAACX,OAAO;EAC5B","ignoreList":[]}