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

package/dist/HashRing.d.ts

@@ -5,6 +5,11 @@ declare const TypeId: "~effect/cluster/HashRing";
  * A weighted consistent-hashing ring for assigning inputs to nodes with stable
  * remapping as nodes are added or removed.
  *
+ * **When to use**
+ *
+ * Use to maintain a mutable weighted hash ring for routing keys or shards to
+ * nodes identified by `PrimaryKey`.
+ *
  * **Details**
  *
  * Nodes are identified by their `PrimaryKey` value and can be iterated from the
@@ -23,6 +28,24 @@ export interface HashRing<A extends PrimaryKey.PrimaryKey> extends Pipeable, Ite
 /**
  * Checks whether a value is a `HashRing`.
  *
+ * **When to use**
+ *
+ * Use to narrow an `unknown` value before treating it as a `HashRing`, such as
+ * values crossing an untyped boundary.
+ *
+ * **Details**
+ *
+ * The guard checks for the module's internal `TypeId` property and narrows to
+ * `HashRing<any>`.
+ *
+ * **Gotchas**
+ *
+ * This is a structural type-id check; it does not validate the ring's `nodes`,
+ * `ring`, or weight state.
+ *
+ * @see {@link HashRing} for the type narrowed by this guard
+ * @see {@link make} for creating an empty `HashRing`
+ *
  * @category guards
  * @since 3.19.0
  */
@@ -30,11 +53,19 @@ export declare const isHashRing: (u: unknown) => u is HashRing<any>;
 /**
  * Creates an empty `HashRing`.
  *
+ * **When to use**
+ *
+ * Use to create an empty weighted consistent-hashing ring with the default or
+ * custom virtual-point density.
+ *
  * **Details**
  *
  * `baseWeight` controls how many virtual points are added for a node with
  * weight `1`; it defaults to `128` and is clamped to at least `1`.
  *
+ * @see {@link add} for registering one node after creation
+ * @see {@link addMany} for registering several nodes after creation
+ *
  * @category constructors
  * @since 3.19.0
  */
@@ -45,6 +76,10 @@ export declare const make: <A extends PrimaryKey.PrimaryKey>(options?: {
  * Add new nodes to the ring. If a node already exists in the ring, it
  * will be updated. For example, you can use this to update the node's weight.
  *
+ * **When to use**
+ *
+ * Use to register or update several nodes in a `HashRing` at the same weight.
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -53,6 +88,10 @@ export declare const addMany: {
      * Add new nodes to the ring. If a node already exists in the ring, it
      * will be updated. For example, you can use this to update the node's weight.
      *
+     * **When to use**
+     *
+     * Use to register or update several nodes in a `HashRing` at the same weight.
+     *
      * @category combinators
      * @since 3.19.0
      */
@@ -63,6 +102,10 @@ export declare const addMany: {
      * Add new nodes to the ring. If a node already exists in the ring, it
      * will be updated. For example, you can use this to update the node's weight.
      *
+     * **When to use**
+     *
+     * Use to register or update several nodes in a `HashRing` at the same weight.
+     *
      * @category combinators
      * @since 3.19.0
      */
@@ -74,6 +117,24 @@ export declare const addMany: {
  * Add a new node to the ring. If the node already exists in the ring, it
  * will be updated. For example, you can use this to update the node's weight.
  *
+ * **When to use**
+ *
+ * Use to register one node in a `HashRing` so lookups and shard assignments can
+ * return it, or to update that node's weight.
+ *
+ * **Details**
+ *
+ * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
+ * clamped to at least `0.1`.
+ *
+ * **Gotchas**
+ *
+ * This mutates and returns the same ring instance.
+ *
+ * @see {@link addMany} for adding or updating several nodes
+ * @see {@link remove} for unregistering a node
+ * @see {@link has} for checking primary-key membership
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -82,6 +143,24 @@ export declare const add: {
      * Add a new node to the ring. If the node already exists in the ring, it
      * will be updated. For example, you can use this to update the node's weight.
      *
+     * **When to use**
+     *
+     * Use to register one node in a `HashRing` so lookups and shard assignments can
+     * return it, or to update that node's weight.
+     *
+     * **Details**
+     *
+     * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
+     * clamped to at least `0.1`.
+     *
+     * **Gotchas**
+     *
+     * This mutates and returns the same ring instance.
+     *
+     * @see {@link addMany} for adding or updating several nodes
+     * @see {@link remove} for unregistering a node
+     * @see {@link has} for checking primary-key membership
+     *
      * @category combinators
      * @since 3.19.0
      */
@@ -92,6 +171,24 @@ export declare const add: {
      * Add a new node to the ring. If the node already exists in the ring, it
      * will be updated. For example, you can use this to update the node's weight.
      *
+     * **When to use**
+     *
+     * Use to register one node in a `HashRing` so lookups and shard assignments can
+     * return it, or to update that node's weight.
+     *
+     * **Details**
+     *
+     * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
+     * clamped to at least `0.1`.
+     *
+     * **Gotchas**
+     *
+     * This mutates and returns the same ring instance.
+     *
+     * @see {@link addMany} for adding or updating several nodes
+     * @see {@link remove} for unregistering a node
+     * @see {@link has} for checking primary-key membership
+     *
      * @category combinators
      * @since 3.19.0
      */
@@ -102,6 +199,23 @@ export declare const add: {
 /**
  * Removes the node from the ring. No-op's if the node does not exist.
  *
+ * **When to use**
+ *
+ * Use to remove a node that has left the pool so future lookups and shard
+ * assignments stop returning it.
+ *
+ * **Details**
+ *
+ * Removal matches by `PrimaryKey.value`, so any value with the same primary key
+ * removes the same ring member.
+ *
+ * **Gotchas**
+ *
+ * This mutates and returns the same ring instance.
+ *
+ * @see {@link add} for registering or updating a node
+ * @see {@link has} for checking membership by primary key
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -109,6 +223,23 @@ export declare const remove: {
     /**
      * Removes the node from the ring. No-op's if the node does not exist.
      *
+     * **When to use**
+     *
+     * Use to remove a node that has left the pool so future lookups and shard
+     * assignments stop returning it.
+     *
+     * **Details**
+     *
+     * Removal matches by `PrimaryKey.value`, so any value with the same primary key
+     * removes the same ring member.
+     *
+     * **Gotchas**
+     *
+     * This mutates and returns the same ring instance.
+     *
+     * @see {@link add} for registering or updating a node
+     * @see {@link has} for checking membership by primary key
+     *
      * @category combinators
      * @since 3.19.0
      */
@@ -116,6 +247,23 @@ export declare const remove: {
     /**
      * Removes the node from the ring. No-op's if the node does not exist.
      *
+     * **When to use**
+     *
+     * Use to remove a node that has left the pool so future lookups and shard
+     * assignments stop returning it.
+     *
+     * **Details**
+     *
+     * Removal matches by `PrimaryKey.value`, so any value with the same primary key
+     * removes the same ring member.
+     *
+     * **Gotchas**
+     *
+     * This mutates and returns the same ring instance.
+     *
+     * @see {@link add} for registering or updating a node
+     * @see {@link has} for checking membership by primary key
+     *
      * @category combinators
      * @since 3.19.0
      */
@@ -124,6 +272,20 @@ export declare const remove: {
 /**
  * Checks whether the ring contains a node with the same `PrimaryKey` value.
  *
+ * **When to use**
+ *
+ * Use to check whether a node value is already registered in a ring by its
+ * `PrimaryKey` value.
+ *
+ * **Details**
+ *
+ * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
+ * matching is by primary key, not object identity or weight.
+ *
+ * @see {@link add} for registering or updating nodes
+ * @see {@link remove} for removing nodes by the same primary-key identity
+ * @see {@link get} for routing an input string to a node
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -131,6 +293,20 @@ export declare const has: {
     /**
      * Checks whether the ring contains a node with the same `PrimaryKey` value.
      *
+     * **When to use**
+     *
+     * Use to check whether a node value is already registered in a ring by its
+     * `PrimaryKey` value.
+     *
+     * **Details**
+     *
+     * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
+     * matching is by primary key, not object identity or weight.
+     *
+     * @see {@link add} for registering or updating nodes
+     * @see {@link remove} for removing nodes by the same primary-key identity
+     * @see {@link get} for routing an input string to a node
+     *
      * @category combinators
      * @since 3.19.0
      */
@@ -138,6 +314,20 @@ export declare const has: {
     /**
      * Checks whether the ring contains a node with the same `PrimaryKey` value.
      *
+     * **When to use**
+     *
+     * Use to check whether a node value is already registered in a ring by its
+     * `PrimaryKey` value.
+     *
+     * **Details**
+     *
+     * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
+     * matching is by primary key, not object identity or weight.
+     *
+     * @see {@link add} for registering or updating nodes
+     * @see {@link remove} for removing nodes by the same primary-key identity
+     * @see {@link get} for routing an input string to a node
+     *
      * @category combinators
      * @since 3.19.0
      */
@@ -147,6 +337,14 @@ export declare const has: {
  * Gets the node which should handle the given input. Returns undefined if
  * the hashring has no elements with weight.
  *
+ * **When to use**
+ *
+ * Use to route a single string input key to the current ring member responsible
+ * for that key.
+ *
+ * @see {@link getShards} for assigning fixed shard indexes instead of routing
+ * one input string at a time
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -156,6 +354,11 @@ export declare const get: <A extends PrimaryKey.PrimaryKey>(self: HashRing<A>, i
  * balance the number of shards allocated to each node. Returns undefined if
  * the hashring has no elements with weight.
  *
+ * **When to use**
+ *
+ * Use to precompute ownership for a fixed number of shard indexes across the
+ * current ring members.
+ *
  * @category combinators
  * @since 3.19.0
  */

package/dist/HashRing.d.ts.map

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

package/dist/HashRing.js

@@ -69,6 +69,24 @@ const TypeId = "~effect/cluster/HashRing";
 /**
  * Checks whether a value is a `HashRing`.
  *
+ * **When to use**
+ *
+ * Use to narrow an `unknown` value before treating it as a `HashRing`, such as
+ * values crossing an untyped boundary.
+ *
+ * **Details**
+ *
+ * The guard checks for the module's internal `TypeId` property and narrows to
+ * `HashRing<any>`.
+ *
+ * **Gotchas**
+ *
+ * This is a structural type-id check; it does not validate the ring's `nodes`,
+ * `ring`, or weight state.
+ *
+ * @see {@link HashRing} for the type narrowed by this guard
+ * @see {@link make} for creating an empty `HashRing`
+ *
  * @category guards
  * @since 3.19.0
  */
@@ -76,11 +94,19 @@ export const isHashRing = u => hasProperty(u, TypeId);
 /**
  * Creates an empty `HashRing`.
  *
+ * **When to use**
+ *
+ * Use to create an empty weighted consistent-hashing ring with the default or
+ * custom virtual-point density.
+ *
  * **Details**
  *
  * `baseWeight` controls how many virtual points are added for a node with
  * weight `1`; it defaults to `128` and is clamped to at least `1`.
  *
+ * @see {@link add} for registering one node after creation
+ * @see {@link addMany} for registering several nodes after creation
+ *
  * @category constructors
  * @since 3.19.0
  */
@@ -110,6 +136,10 @@ const Proto = {
  * Add new nodes to the ring. If a node already exists in the ring, it
  * will be updated. For example, you can use this to update the node's weight.
  *
+ * **When to use**
+ *
+ * Use to register or update several nodes in a `HashRing` at the same weight.
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -152,6 +182,24 @@ function addNodesToRing(self, keys, weight) {
  * Add a new node to the ring. If the node already exists in the ring, it
  * will be updated. For example, you can use this to update the node's weight.
  *
+ * **When to use**
+ *
+ * Use to register one node in a `HashRing` so lookups and shard assignments can
+ * return it, or to update that node's weight.
+ *
+ * **Details**
+ *
+ * Nodes are matched by `PrimaryKey.value`. The weight defaults to `1` and is
+ * clamped to at least `0.1`.
+ *
+ * **Gotchas**
+ *
+ * This mutates and returns the same ring instance.
+ *
+ * @see {@link addMany} for adding or updating several nodes
+ * @see {@link remove} for unregistering a node
+ * @see {@link has} for checking primary-key membership
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -159,6 +207,23 @@ export const add = /*#__PURE__*/dual(args => isHashRing(args[0]), (self, node, o
 /**
  * Removes the node from the ring. No-op's if the node does not exist.
  *
+ * **When to use**
+ *
+ * Use to remove a node that has left the pool so future lookups and shard
+ * assignments stop returning it.
+ *
+ * **Details**
+ *
+ * Removal matches by `PrimaryKey.value`, so any value with the same primary key
+ * removes the same ring member.
+ *
+ * **Gotchas**
+ *
+ * This mutates and returns the same ring instance.
+ *
+ * @see {@link add} for registering or updating a node
+ * @see {@link has} for checking membership by primary key
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -175,6 +240,20 @@ export const remove = /*#__PURE__*/dual(2, (self, node) => {
 /**
  * Checks whether the ring contains a node with the same `PrimaryKey` value.
  *
+ * **When to use**
+ *
+ * Use to check whether a node value is already registered in a ring by its
+ * `PrimaryKey` value.
+ *
+ * **Details**
+ *
+ * Membership is checked with `self.nodes.has(PrimaryKey.value(node))`, so
+ * matching is by primary key, not object identity or weight.
+ *
+ * @see {@link add} for registering or updating nodes
+ * @see {@link remove} for removing nodes by the same primary-key identity
+ * @see {@link get} for routing an input string to a node
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -183,6 +262,14 @@ export const has = /*#__PURE__*/dual(2, (self, node) => self.nodes.has(PrimaryKe
  * Gets the node which should handle the given input. Returns undefined if
  * the hashring has no elements with weight.
  *
+ * **When to use**
+ *
+ * Use to route a single string input key to the current ring member responsible
+ * for that key.
+ *
+ * @see {@link getShards} for assigning fixed shard indexes instead of routing
+ * one input string at a time
+ *
  * @category combinators
  * @since 3.19.0
  */
@@ -199,6 +286,11 @@ export const get = (self, input) => {
  * balance the number of shards allocated to each node. Returns undefined if
  * the hashring has no elements with weight.
  *
+ * **When to use**
+ *
+ * Use to precompute ownership for a fixed number of shard indexes across the
+ * current ring members.
+ *
  * @category combinators
  * @since 3.19.0
  */

package/dist/HashRing.js.map

@@ -1 +1 @@
-{"version":3,"file":"HashRing.js","names":["dual","Hash","PipeInspectableProto","Iterable","hasProperty","PrimaryKey","TypeId","isHashRing","u","make","options","self","Object","create","Proto","baseWeight","Math","max","totalWeightCache","nodes","Map","ring","Symbol","iterator","map","values","n","toJSON","_id","get","addMany","args","weight","keys","toRemove","node","key","value","entry","Set","add","set","push","filter","has","addNodesToRing","round","i","j","length","string","sort","a","b","remove","delete","input","undefined","index","getIndexForInput","getShards","count","shards","Array","allocations","remaining","exclude","distances","shard","hash","shardHashes","distance","nodeCount","maxPerNode","floor","allAtMax","size","forEach","len","mid","lo","hi","distA","abs","distB","range"],"sources":["../src/HashRing.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"HashRing.js","names":["dual","Hash","PipeInspectableProto","Iterable","hasProperty","PrimaryKey","TypeId","isHashRing","u","make","options","self","Object","create","Proto","baseWeight","Math","max","totalWeightCache","nodes","Map","ring","Symbol","iterator","map","values","n","toJSON","_id","get","addMany","args","weight","keys","toRemove","node","key","value","entry","Set","add","set","push","filter","has","addNodesToRing","round","i","j","length","string","sort","a","b","remove","delete","input","undefined","index","getIndexForInput","getShards","count","shards","Array","allocations","remaining","exclude","distances","shard","hash","shardHashes","distance","nodeCount","maxPerNode","floor","allAtMax","size","forEach","len","mid","lo","hi","distA","abs","distB","range"],"sources":["../src/HashRing.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/Inspectable.d.ts

@@ -1,6 +1,10 @@
 /**
  * Symbol used by Node.js for custom object inspection.
  *
+ * **When to use**
+ *
+ * Use to implement Node.js custom inspection for a value.
+ *
  * **Details**
  *
  * This symbol is recognized by Node.js's `util.inspect()` function and the REPL
@@ -33,6 +37,10 @@ export declare const NodeInspectSymbol: unique symbol;
  * This symbol type is used to implement custom inspection behavior in Node.js
  * environments.
  *
+ * **When to use**
+ *
+ * Use to type methods keyed by the Node.js custom inspection symbol.
+ *
  * **Example** (Typing custom Node inspection)
  *
  * ```ts
@@ -57,6 +65,10 @@ export type NodeInspectSymbol = typeof NodeInspectSymbol;
 /**
  * Interface for objects that can be inspected and provide custom string representations.
  *
+ * **When to use**
+ *
+ * Use to define values with custom string, JSON, and Node.js inspection output.
+ *
  * **Details**
  *
  * Objects implementing this interface can control how they appear in debugging contexts,
@@ -102,6 +114,11 @@ export interface Inspectable {
 /**
  * Safely converts a value to a JSON-serializable representation.
  *
+ * **When to use**
+ *
+ * Use when you need a safe, JSON-serializable representation of a value
+ * without risking unhandled errors.
+ *
  * **Details**
  *
  * This function attempts to extract JSON data from objects that implement the
@@ -109,6 +126,8 @@ export interface Inspectable {
  * For objects that don't have a `toJSON` method, it applies redaction to
  * protect sensitive information.
  *
+ * @see {@link toStringUnknown} for converting unknown values to strings
+ *
  * @category converting
  * @since 4.0.0
  */
@@ -116,6 +135,10 @@ export declare const toJson: (input: unknown) => unknown;
 /**
  * Converts an unknown value to a string for diagnostics.
  *
+ * **When to use**
+ *
+ * Use to produce a diagnostic string from a value whose runtime type is unknown.
+ *
  * **Details**
  *
  * Strings are returned unchanged. Objects are formatted as JSON using the
@@ -129,6 +152,10 @@ export declare const toStringUnknown: (u: unknown, whitespace?: number | string
 /**
  * A base prototype object that implements the {@link Inspectable} interface.
  *
+ * **When to use**
+ *
+ * Use as a prototype for plain objects that should share standard inspectable behavior.
+ *
  * **Details**
  *
  * This object provides default implementations for the {@link Inspectable} methods.
@@ -162,6 +189,10 @@ export declare const BaseProto: Inspectable;
 /**
  * Abstract base class that implements the Inspectable interface.
  *
+ * **When to use**
+ *
+ * Use as a base class for inspectable objects that define their own JSON representation.
+ *
  * **Details**
  *
  * This class provides a convenient way to create inspectable objects by extending it.
@@ -204,6 +235,10 @@ export declare abstract class Class {
     /**
      * Returns a JSON representation of this object.
      *
+     * **When to use**
+     *
+     * Use to provide the JSON representation consumed by inherited inspection methods.
+     *
      * **Details**
      *
      * Subclasses must implement this method to define how the object
@@ -215,12 +250,20 @@ export declare abstract class Class {
     /**
      * Node.js custom inspection method.
      *
+     * **When to use**
+     *
+     * Use to expose the class JSON representation to Node.js inspection.
+     *
      * @since 2.0.0
      */
     [NodeInspectSymbol](): unknown;
     /**
      * Returns a formatted string representation of this object.
      *
+     * **When to use**
+     *
+     * Use to format the class JSON representation as a string.
+     *
      * @since 2.0.0
      */
     toString(): string;

package/dist/Inspectable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Inspectable.d.ts","sourceRoot":"","sources":["../src/Inspectable.ts"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,iBAAiB,eAA2C,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,IAAI,MAAM,CAAA;IAClB,MAAM,IAAI,OAAO,CAAA;IACjB,CAAC,iBAAiB,CAAC,IAAI,OAAO,CAAA;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,KAAG,OAevC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,EAAE,aAAY,MAAM,GAAG,MAAM,GAAG,SAAa,KAAG,MASzF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,SAAS,EAAE,WAUvB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,8BAAsB,KAAK;IACzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO;IAC1B;;;;OAIG;IACH,CAAC,iBAAiB,CAAC;IAGnB;;;;OAIG;IACH,QAAQ;CAGT"}
+{"version":3,"file":"Inspectable.d.ts","sourceRoot":"","sources":["../src/Inspectable.ts"],"names":[],"mappings":"AAqEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,iBAAiB,eAA2C,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,IAAI,MAAM,CAAA;IAClB,MAAM,IAAI,OAAO,CAAA;IACjB,CAAC,iBAAiB,CAAC,IAAI,OAAO,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,KAAG,OAevC,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,GAAI,GAAG,OAAO,EAAE,aAAY,MAAM,GAAG,MAAM,GAAG,SAAa,KAAG,MASzF,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,SAAS,EAAE,WAUvB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,8BAAsB,KAAK;IACzB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO;IAC1B;;;;;;;;OAQG;IACH,CAAC,iBAAiB,CAAC;IAGnB;;;;;;;;OAQG;IACH,QAAQ;CAGT"}