effect-app 4.0.0-beta.18 → 4.0.0-beta.180

package/dist/rpc/Invalidation.d.ts

@@ -0,0 +1,490 @@
+import * as Ref from "effect/Ref";
+import * as Context from "../Context.js";
+import * as Effect from "../Effect.js";
+import * as S from "../Schema.js";
+/**
+ * A single segment within an `InvalidationKey` array.
+ * Accepts any JSON-compatible value: string, number, boolean, null,
+ * arrays and objects recursively — matching TanStack Query's `queryKey` element type.
+ */
+export declare const InvalidationKeySegment: S.Codec<S.Json, S.Json, never, never>;
+export type InvalidationKeySegment = S.Schema.Type<typeof InvalidationKeySegment>;
+/** Schema for a single invalidation key – an array of segments compatible with TanStack Query `queryKey`. */
+export declare const InvalidationKey: S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+};
+export type InvalidationKey = S.Schema.Type<typeof InvalidationKey>;
+/** Schema for the full set of invalidation keys – an array of `InvalidationKey`. */
+export declare const InvalidationKeys: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+}> & {
+    withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+        withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+    }>>;
+    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+        withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+    }>>;
+};
+export type InvalidationKeys = S.Schema.Type<typeof InvalidationKeys>;
+/** Metadata included in every command response for server-driven cache invalidation. */
+export declare const CommandMetaData: S.Struct<{
+    readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+        withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+    }> & {
+        withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }>>;
+        withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }>>;
+    };
+}>;
+export type CommandMetaData = S.Schema.Type<typeof CommandMetaData>;
+/**
+ * Wraps a command's success schema so that the wire format carries both the `payload`
+ * (the handler's actual return value) and `metadata` (server-driven cache invalidation keys).
+ * Transparent to users: the server handler returns the plain payload and the client receives
+ * the plain payload — wrapping/unwrapping is handled internally by the routing layer.
+ */
+export declare const CommandResponseWithMetaData: <S extends S.Top>(success: S) => S.Struct<{
+    readonly payload: S;
+    readonly metadata: S.Struct<{
+        readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+        };
+    }>;
+}> & ({} extends (import("effect/Schema").Struct.MakeIn_<{
+    readonly payload: S;
+    readonly metadata: S.Struct<{
+        readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+        };
+    }>;
+}, (S extends {
+    readonly "~type.optionality": "optional";
+} ? "payload" : never) | (S extends {
+    readonly "~type.constructor.default": "with-default";
+} ? "payload" : never)> extends infer T ? { [K in keyof T]: T[K]; } : never) ? {
+    make(input?: (import("effect/Schema").Struct.MakeIn_<{
+        readonly payload: S;
+        readonly metadata: S.Struct<{
+            readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+            };
+        }>;
+    }, (S extends {
+        readonly "~type.optionality": "optional";
+    } ? "payload" : never) | (S extends {
+        readonly "~type.constructor.default": "with-default";
+    } ? "payload" : never)> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never) | undefined, options?: S.MakeOptions): import("effect/Schema").Struct.Type_<{
+        readonly payload: S;
+        readonly metadata: S.Struct<{
+            readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+            };
+        }>;
+    }, S extends {
+        readonly "~type.optionality": "optional";
+    } ? "payload" : never, S extends {
+        readonly "~type.mutability": "mutable";
+    } ? "payload" : never> extends infer T_2 ? { [K in keyof T_2]: T_2[K]; } : never;
+} : {});
+/**
+ * Wraps a command's failure schema so that the wire format carries both the `error`
+ * (the handler's actual failure value) and `metadata` (server-driven cache invalidation keys
+ * accumulated thus far before the failure occurred).
+ * Transparent to users: the server handler fails with the plain error and the client receives
+ * the plain error — wrapping/unwrapping is handled internally by the routing layer.
+ */
+export declare const CommandFailureWithMetaData: <E extends S.Top>(error: E) => S.Struct<{
+    readonly _tag: S.Literal<"CommandFailureWithMetaData">;
+    readonly error: E;
+    readonly metadata: S.Struct<{
+        readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+        };
+    }>;
+}> & ({} extends (import("effect/Schema").Struct.MakeIn_<{
+    readonly _tag: S.Literal<"CommandFailureWithMetaData">;
+    readonly error: E;
+    readonly metadata: S.Struct<{
+        readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+        };
+    }>;
+}, (E extends {
+    readonly "~type.optionality": "optional";
+} ? "error" : never) | (E extends {
+    readonly "~type.constructor.default": "with-default";
+} ? "error" : never)> extends infer T ? { [K in keyof T]: T[K]; } : never) ? {
+    make(input?: (import("effect/Schema").Struct.MakeIn_<{
+        readonly _tag: S.Literal<"CommandFailureWithMetaData">;
+        readonly error: E;
+        readonly metadata: S.Struct<{
+            readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+            };
+        }>;
+    }, (E extends {
+        readonly "~type.optionality": "optional";
+    } ? "error" : never) | (E extends {
+        readonly "~type.constructor.default": "with-default";
+    } ? "error" : never)> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never) | undefined, options?: S.MakeOptions): import("effect/Schema").Struct.Type_<{
+        readonly _tag: S.Literal<"CommandFailureWithMetaData">;
+        readonly error: E;
+        readonly metadata: S.Struct<{
+            readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+            };
+        }>;
+    }, E extends {
+        readonly "~type.optionality": "optional";
+    } ? "error" : never, E extends {
+        readonly "~type.mutability": "mutable";
+    } ? "error" : never> extends infer T_2 ? { [K in keyof T_2]: T_2[K]; } : never;
+} : {});
+/**
+ * Stream chunk schema for stream responses with metadata.
+ * Each item is either a data value, an intermediate "metadata" signal carrying cache
+ * invalidation keys accumulated since the previous drain, or a final "done" signal.
+ * Transparent to users: stream handlers return plain values and clients receive plain values —
+ * wrapping/unwrapping is handled internally by the routing layer.
+ *
+ * The "done" chunk is always the last item in the stream and carries any remaining invalidation
+ * keys. An optional "metadata" chunk may appear after any "value" chunk and carries keys
+ * accumulated since the last drain (V3: mid-stream invalidation).
+ */
+export declare const StreamResponseChunk: <S extends S.Top>(success: S) => S.Union<readonly [S.Struct<{
+    readonly _tag: S.Literal<"value">;
+    readonly value: S;
+}> & ({} extends (import("effect/Schema").Struct.MakeIn_<{
+    readonly _tag: S.Literal<"value">;
+    readonly value: S;
+}, (S extends {
+    readonly "~type.optionality": "optional";
+} ? "value" : never) | (S extends {
+    readonly "~type.constructor.default": "with-default";
+} ? "value" : never)> extends infer T ? { [K in keyof T]: T[K]; } : never) ? {
+    make(input?: (import("effect/Schema").Struct.MakeIn_<{
+        readonly _tag: S.Literal<"value">;
+        readonly value: S;
+    }, (S extends {
+        readonly "~type.optionality": "optional";
+    } ? "value" : never) | (S extends {
+        readonly "~type.constructor.default": "with-default";
+    } ? "value" : never)> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never) | undefined, options?: S.MakeOptions): import("effect/Schema").Struct.Type_<{
+        readonly _tag: S.Literal<"value">;
+        readonly value: S;
+    }, S extends {
+        readonly "~type.optionality": "optional";
+    } ? "value" : never, S extends {
+        readonly "~type.mutability": "mutable";
+    } ? "value" : never> extends infer T_2 ? { [K in keyof T_2]: T_2[K]; } : never;
+} : {}), S.Struct<{
+    readonly _tag: S.Literal<"metadata">;
+    readonly metadata: S.Struct<{
+        readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+        };
+    }>;
+}>, S.Struct<{
+    readonly _tag: S.Literal<"done">;
+    readonly metadata: S.Struct<{
+        readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+        };
+    }>;
+}>]>;
+export type StreamResponseChunk<A> = {
+    readonly _tag: "value";
+    readonly value: A;
+} | {
+    readonly _tag: "metadata";
+    readonly metadata: CommandMetaData;
+} | {
+    readonly _tag: "done";
+    readonly metadata: CommandMetaData;
+};
+/**
+ * Stream chunk schema for stream failures with metadata.
+ * Used to signal a stream failure while still carrying cache invalidation keys
+ * accumulated thus far.
+ */
+export declare const StreamFailureChunk: <E extends S.Top>(error: E) => S.Struct<{
+    readonly _tag: S.Literal<"error">;
+    readonly error: E;
+    readonly metadata: S.Struct<{
+        readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+        };
+    }>;
+}> & ({} extends (import("effect/Schema").Struct.MakeIn_<{
+    readonly _tag: S.Literal<"error">;
+    readonly error: E;
+    readonly metadata: S.Struct<{
+        readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+        }> & {
+            withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+            withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }>>;
+        };
+    }>;
+}, (E extends {
+    readonly "~type.optionality": "optional";
+} ? "error" : never) | (E extends {
+    readonly "~type.constructor.default": "with-default";
+} ? "error" : never)> extends infer T ? { [K in keyof T]: T[K]; } : never) ? {
+    make(input?: (import("effect/Schema").Struct.MakeIn_<{
+        readonly _tag: S.Literal<"error">;
+        readonly error: E;
+        readonly metadata: S.Struct<{
+            readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+            };
+        }>;
+    }, (E extends {
+        readonly "~type.optionality": "optional";
+    } ? "error" : never) | (E extends {
+        readonly "~type.constructor.default": "with-default";
+    } ? "error" : never)> extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never) | undefined, options?: S.MakeOptions): import("effect/Schema").Struct.Type_<{
+        readonly _tag: S.Literal<"error">;
+        readonly error: E;
+        readonly metadata: S.Struct<{
+            readonly invalidateQueries: S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+            }> & {
+                withDefault: S.withConstructorDefault<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+                withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.$Array<S.Codec<S.Json, S.Json, never, never>> & {
+                    withDefault: S.withConstructorDefault<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                    withDecodingDefaultType: S.withDecodingDefaultType<S.$Array<S.Codec<S.Json, S.Json, never, never>>>;
+                }>>;
+            };
+        }>;
+    }, E extends {
+        readonly "~type.optionality": "optional";
+    } ? "error" : never, E extends {
+        readonly "~type.mutability": "mutable";
+    } ? "error" : never> extends infer T_2 ? { [K in keyof T_2]: T_2[K]; } : never;
+} : {});
+export type StreamFailureChunk<E> = {
+    readonly _tag: "error";
+    readonly error: E;
+    readonly metadata: CommandMetaData;
+};
+/**
+ * Context annotation for declaring static cache invalidation keys on a low-level `Rpc` definition.
+ * These keys are always included in the command response metadata, regardless of the handler logic.
+ *
+ * Prefer using `makeQueryKey` over raw string arrays to stay in sync with the actual query
+ * definitions without manual string maintenance:
+ *
+ * ```ts
+ * import { makeQueryKey } from "effect-app/client"
+ * import { Invalidation } from "effect-app/rpc"
+ * import * as UserRsc from "../User/index.js"  // separate module to avoid circular deps
+ *
+ * class UpdateProfile extends Rpc.make("UpdateProfile", { ... })
+ *   .annotate(Invalidation.Invalidates, [makeQueryKey(UserRsc.GetMe), makeQueryKey(UserRsc.GetProfile)]) {}
+ * ```
+ *
+ * **Circular dependency note:** if mutations and queries live in the same file you may hit a
+ * circular reference at evaluation time. The idiomatic fix is to move mutations into their own
+ * module (e.g. `User/mutations.ts`) that directly imports the relevant query classes rather than
+ * re-exporting them through a barrel.
+ *
+ * For the higher-level `Command`/`Query` builders from `makeRpcClient`, use the
+ * `invalidatesQueries` callback argument instead (it receives the same query keys at runtime).
+ */
+export declare const Invalidates: Context.Reference<readonly (readonly S.Json[])[]>;
+export type Invalidates = typeof Invalidates;
+/** The shape of the per-request service that accumulates invalidation keys. */
+export interface InvalidationSetService {
+    readonly add: (key: InvalidationKey) => Effect.Effect<void>;
+    readonly get: Effect.Effect<ReadonlyArray<InvalidationKey>>;
+    /**
+     * V3: Reads all currently accumulated keys and resets the bucket to empty.
+     * Used by the stream routing layer to emit intermediate "metadata" chunks
+     * without re-sending keys that have already been forwarded to the client.
+     */
+    readonly drain: Effect.Effect<ReadonlyArray<InvalidationKey>>;
+}
+/**
+ * Request-scoped service for accumulating invalidation keys dynamically inside a handler.
+ * Provided by `InvalidationMiddlewareLive` for every RPC call; has a no-op default so it is
+ * safe to use even when the HTTP middleware is absent (tests, workers, etc.).
+ *
+ * Use `InvalidationSet.use(_ => _.add(key))` (or `.useSync` for non-Effect callbacks) as a
+ * shorthand instead of yielding the service manually.
+ *
+ * Prefer `makeQueryKey` over raw string arrays so invalidation keys stay in sync with the
+ * actual query definitions automatically:
+ *
+ * ```ts
+ * import { makeQueryKey } from "effect-app/client"
+ * import { Effect } from "effect"
+ * import { Invalidation } from "effect-app/rpc"
+ * import * as CartRsc from "../Cart/queries.js"
+ * import * as UserRsc from "../User/queries.js"
+ *
+ * const handler = Effect.fnUntraced(function*(req: UpdateCartRequest) {
+ *   const cart = yield* CartRepo.save(req.cart)
+ *
+ *   // Stage 1 – unconditional: always invalidate after saving
+ *   yield* Invalidation.InvalidationSet.use(_ => _.add(makeQueryKey(UserRsc.GetMe)))
+ *
+ *   // Stage 2 – conditional: only if the cart changed state
+ *   if (cart.isCheckedOut) {
+ *     yield* Invalidation.InvalidationSet.use(_ => _.add(makeQueryKey(CartRsc.GetCartStats)))
+ *   }
+ *
+ *   return cart
+ * })
+ * ```
+ *
+ * You can combine static (`Invalidates` annotation) and dynamic (`InvalidationSet.use`) keys:
+ * the annotation pre-populates the set before the handler runs; dynamic additions accumulate
+ * throughout the handler. All keys are included in the command response metadata.
+ */
+export declare const InvalidationSet: Context.Reference<InvalidationSetService>;
+export type InvalidationSet = typeof InvalidationSet;
+/** Creates a fresh `InvalidationSet` implementation backed by a `Ref`. */
+export declare const makeInvalidationSet: (ref: Ref.Ref<ReadonlyArray<InvalidationKey>>) => InvalidationSetService;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiSW52YWxpZGF0aW9uLmQudHMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvcnBjL0ludmFsaWRhdGlvbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssR0FBRyxNQUFNLFlBQVksQ0FBQTtBQUNqQyxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQTtBQUN4QyxPQUFPLEtBQUssTUFBTSxNQUFNLGNBQWMsQ0FBQTtBQUN0QyxPQUFPLEtBQUssQ0FBQyxNQUFNLGNBQWMsQ0FBQTtBQUVqQzs7OztHQUlHO0FBQ0gsZUFBTyxNQUFNLHNCQUFzQix1Q0FBUyxDQUFBO0FBQzVDLE1BQU0sTUFBTSxzQkFBc0IsR0FBRyxDQUFDLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxPQUFPLHNCQUFzQixDQUFDLENBQUE7QUFFakYsNkdBQTZHO0FBQzdHLGVBQU8sTUFBTSxlQUFlOzs7Q0FBa0MsQ0FBQTtBQUM5RCxNQUFNLE1BQU0sZUFBZSxHQUFHLENBQUMsQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLE9BQU8sZUFBZSxDQUFDLENBQUE7QUFFbkUsb0ZBQW9GO0FBQ3BGLGVBQU8sTUFBTSxnQkFBZ0I7Ozs7Ozs7Ozs7OztDQUEyQixDQUFBO0FBQ3hELE1BQU0sTUFBTSxnQkFBZ0IsR0FBRyxDQUFDLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxPQUFPLGdCQUFnQixDQUFDLENBQUE7QUFFckUsd0ZBQXdGO0FBQ3hGLGVBQU8sTUFBTSxlQUFlOzs7Ozs7Ozs7Ozs7OztFQUFvRCxDQUFBO0FBQ2hGLE1BQU0sTUFBTSxlQUFlLEdBQUcsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxJQUFJLENBQUMsT0FBTyxlQUFlLENBQUMsQ0FBQTtBQUVuRTs7Ozs7R0FLRztBQUNILGVBQU8sTUFBTSwyQkFBMkIsR0FBSSxDQUFDLFNBQVMsQ0FBQyxDQUFDLEdBQUcsV0FBVyxDQUFDOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7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

package/dist/rpc/Invalidation.d.ts.map

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

package/dist/rpc/Invalidation.js

@@ -0,0 +1,129 @@
+import * as Ref from "effect/Ref";
+import * as Context from "../Context.js";
+import * as Effect from "../Effect.js";
+import * as S from "../Schema.js";
+/**
+ * A single segment within an `InvalidationKey` array.
+ * Accepts any JSON-compatible value: string, number, boolean, null,
+ * arrays and objects recursively — matching TanStack Query's `queryKey` element type.
+ */
+export const InvalidationKeySegment = S.Json;
+/** Schema for a single invalidation key – an array of segments compatible with TanStack Query `queryKey`. */
+export const InvalidationKey = S.Array(InvalidationKeySegment);
+/** Schema for the full set of invalidation keys – an array of `InvalidationKey`. */
+export const InvalidationKeys = S.Array(InvalidationKey);
+/** Metadata included in every command response for server-driven cache invalidation. */
+export const CommandMetaData = S.Struct({ invalidateQueries: InvalidationKeys });
+/**
+ * Wraps a command's success schema so that the wire format carries both the `payload`
+ * (the handler's actual return value) and `metadata` (server-driven cache invalidation keys).
+ * Transparent to users: the server handler returns the plain payload and the client receives
+ * the plain payload — wrapping/unwrapping is handled internally by the routing layer.
+ */
+export const CommandResponseWithMetaData = (success) => S.Struct({ payload: success, metadata: CommandMetaData });
+/**
+ * Wraps a command's failure schema so that the wire format carries both the `error`
+ * (the handler's actual failure value) and `metadata` (server-driven cache invalidation keys
+ * accumulated thus far before the failure occurred).
+ * Transparent to users: the server handler fails with the plain error and the client receives
+ * the plain error — wrapping/unwrapping is handled internally by the routing layer.
+ */
+export const CommandFailureWithMetaData = (error) => S.Struct({ _tag: S.Literal("CommandFailureWithMetaData"), error, metadata: CommandMetaData });
+/**
+ * Stream chunk schema for stream responses with metadata.
+ * Each item is either a data value, an intermediate "metadata" signal carrying cache
+ * invalidation keys accumulated since the previous drain, or a final "done" signal.
+ * Transparent to users: stream handlers return plain values and clients receive plain values —
+ * wrapping/unwrapping is handled internally by the routing layer.
+ *
+ * The "done" chunk is always the last item in the stream and carries any remaining invalidation
+ * keys. An optional "metadata" chunk may appear after any "value" chunk and carries keys
+ * accumulated since the last drain (V3: mid-stream invalidation).
+ */
+export const StreamResponseChunk = (success) => S.Union([
+    S.Struct({ _tag: S.Literal("value"), value: success }),
+    S.Struct({ _tag: S.Literal("metadata"), metadata: CommandMetaData }),
+    S.Struct({ _tag: S.Literal("done"), metadata: CommandMetaData })
+]);
+/**
+ * Stream chunk schema for stream failures with metadata.
+ * Used to signal a stream failure while still carrying cache invalidation keys
+ * accumulated thus far.
+ */
+export const StreamFailureChunk = (error) => S.Struct({ _tag: S.Literal("error"), error, metadata: CommandMetaData });
+/**
+ * Context annotation for declaring static cache invalidation keys on a low-level `Rpc` definition.
+ * These keys are always included in the command response metadata, regardless of the handler logic.
+ *
+ * Prefer using `makeQueryKey` over raw string arrays to stay in sync with the actual query
+ * definitions without manual string maintenance:
+ *
+ * ```ts
+ * import { makeQueryKey } from "effect-app/client"
+ * import { Invalidation } from "effect-app/rpc"
+ * import * as UserRsc from "../User/index.js"  // separate module to avoid circular deps
+ *
+ * class UpdateProfile extends Rpc.make("UpdateProfile", { ... })
+ *   .annotate(Invalidation.Invalidates, [makeQueryKey(UserRsc.GetMe), makeQueryKey(UserRsc.GetProfile)]) {}
+ * ```
+ *
+ * **Circular dependency note:** if mutations and queries live in the same file you may hit a
+ * circular reference at evaluation time. The idiomatic fix is to move mutations into their own
+ * module (e.g. `User/mutations.ts`) that directly imports the relevant query classes rather than
+ * re-exporting them through a barrel.
+ *
+ * For the higher-level `Command`/`Query` builders from `makeRpcClient`, use the
+ * `invalidatesQueries` callback argument instead (it receives the same query keys at runtime).
+ */
+export const Invalidates = Context.Reference("effect-app/rpc/Invalidates", { defaultValue: () => [] });
+/**
+ * Request-scoped service for accumulating invalidation keys dynamically inside a handler.
+ * Provided by `InvalidationMiddlewareLive` for every RPC call; has a no-op default so it is
+ * safe to use even when the HTTP middleware is absent (tests, workers, etc.).
+ *
+ * Use `InvalidationSet.use(_ => _.add(key))` (or `.useSync` for non-Effect callbacks) as a
+ * shorthand instead of yielding the service manually.
+ *
+ * Prefer `makeQueryKey` over raw string arrays so invalidation keys stay in sync with the
+ * actual query definitions automatically:
+ *
+ * ```ts
+ * import { makeQueryKey } from "effect-app/client"
+ * import { Effect } from "effect"
+ * import { Invalidation } from "effect-app/rpc"
+ * import * as CartRsc from "../Cart/queries.js"
+ * import * as UserRsc from "../User/queries.js"
+ *
+ * const handler = Effect.fnUntraced(function*(req: UpdateCartRequest) {
+ *   const cart = yield* CartRepo.save(req.cart)
+ *
+ *   // Stage 1 – unconditional: always invalidate after saving
+ *   yield* Invalidation.InvalidationSet.use(_ => _.add(makeQueryKey(UserRsc.GetMe)))
+ *
+ *   // Stage 2 – conditional: only if the cart changed state
+ *   if (cart.isCheckedOut) {
+ *     yield* Invalidation.InvalidationSet.use(_ => _.add(makeQueryKey(CartRsc.GetCartStats)))
+ *   }
+ *
+ *   return cart
+ * })
+ * ```
+ *
+ * You can combine static (`Invalidates` annotation) and dynamic (`InvalidationSet.use`) keys:
+ * the annotation pre-populates the set before the handler runs; dynamic additions accumulate
+ * throughout the handler. All keys are included in the command response metadata.
+ */
+export const InvalidationSet = Context.Reference("effect-app/rpc/InvalidationSet", {
+    defaultValue: () => ({
+        add: (_key) => Effect.void,
+        get: Effect.succeed([]),
+        drain: Effect.succeed([])
+    })
+});
+/** Creates a fresh `InvalidationSet` implementation backed by a `Ref`. */
+export const makeInvalidationSet = (ref) => ({
+    add: (key) => Ref.update(ref, (keys) => [...keys, key]),
+    get: Ref.get(ref),
+    drain: Ref.getAndSet(ref, [])
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiSW52YWxpZGF0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3JwYy9JbnZhbGlkYXRpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLEdBQUcsTUFBTSxZQUFZLENBQUE7QUFDakMsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUE7QUFDeEMsT0FBTyxLQUFLLE1BQU0sTUFBTSxjQUFjLENBQUE7QUFDdEMsT0FBTyxLQUFLLENBQUMsTUFBTSxjQUFjLENBQUE7QUFFakM7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLHNCQUFzQixHQUFHLENBQUMsQ0FBQyxJQUFJLENBQUE7QUFHNUMsNkdBQTZHO0FBQzdHLE1BQU0sQ0FBQyxNQUFNLGVBQWUsR0FBRyxDQUFDLENBQUMsS0FBSyxDQUFDLHNCQUFzQixDQUFDLENBQUE7QUFHOUQsb0ZBQW9GO0FBQ3BGLE1BQU0sQ0FBQyxNQUFNLGdCQUFnQixHQUFHLENBQUMsQ0FBQyxLQUFLLENBQUMsZUFBZSxDQUFDLENBQUE7QUFHeEQsd0ZBQXdGO0FBQ3hGLE1BQU0sQ0FBQyxNQUFNLGVBQWUsR0FBRyxDQUFDLENBQUMsTUFBTSxDQUFDLEVBQUUsaUJBQWlCLEVBQUUsZ0JBQWdCLEVBQUUsQ0FBQyxDQUFBO0FBR2hGOzs7OztHQUtHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sMkJBQTJCLEdBQUcsQ0FBa0IsT0FBVSxFQUFFLEVBQUUsQ0FDekUsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxFQUFFLE9BQU8sRUFBRSxPQUFPLEVBQUUsUUFBUSxFQUFFLGVBQWUsRUFBRSxDQUFDLENBQUE7QUFFM0Q7Ozs7OztHQU1HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sMEJBQTBCLEdBQUcsQ0FBa0IsS0FBUSxFQUFFLEVBQUUsQ0FDdEUsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUMsT0FBTyxDQUFDLDRCQUE0QixDQUFDLEVBQUUsS0FBSyxFQUFFLFFBQVEsRUFBRSxlQUFlLEVBQUUsQ0FBQyxDQUFBO0FBRS9GOzs7Ozs7Ozs7O0dBVUc7QUFDSCxNQUFNLENBQUMsTUFBTSxtQkFBbUIsR0FBRyxDQUFrQixPQUFVLEVBQUUsRUFBRSxDQUNqRSxDQUFDLENBQUMsS0FBSyxDQUFDO0lBQ04sQ0FBQyxDQUFDLE1BQU0sQ0FBQyxFQUFFLElBQUksRUFBRSxDQUFDLENBQUMsT0FBTyxDQUFDLE9BQU8sQ0FBQyxFQUFFLEtBQUssRUFBRSxPQUFPLEVBQUUsQ0FBQztJQUN0RCxDQUFDLENBQUMsTUFBTSxDQUFDLEVBQUUsSUFBSSxFQUFFLENBQUMsQ0FBQyxPQUFPLENBQUMsVUFBVSxDQUFDLEVBQUUsUUFBUSxFQUFFLGVBQWUsRUFBRSxDQUFDO0lBQ3BFLENBQUMsQ0FBQyxNQUFNLENBQUMsRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUMsRUFBRSxRQUFRLEVBQUUsZUFBZSxFQUFFLENBQUM7Q0FDakUsQ0FBQyxDQUFBO0FBT0o7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLGtCQUFrQixHQUFHLENBQWtCLEtBQVEsRUFBRSxFQUFFLENBQzlELENBQUMsQ0FBQyxNQUFNLENBQUMsRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxPQUFPLENBQUMsRUFBRSxLQUFLLEVBQUUsUUFBUSxFQUFFLGVBQWUsRUFBRSxDQUFDLENBQUE7QUFJMUU7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBdUJHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sV0FBVyxHQUFHLE9BQU8sQ0FBQyxTQUFTLENBQzFDLDRCQUE0QixFQUM1QixFQUFFLFlBQVksRUFBRSxHQUFHLEVBQUUsQ0FBQyxFQUFFLEVBQUUsQ0FDM0IsQ0FBQTtBQWVEOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0FvQ0c7QUFDSCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsT0FBTyxDQUFDLFNBQVMsQ0FDOUMsZ0NBQWdDLEVBQ2hDO0lBQ0UsWUFBWSxFQUFFLEdBQUcsRUFBRSxDQUFDLENBQUM7UUFDbkIsR0FBRyxFQUFFLENBQUMsSUFBcUIsRUFBRSxFQUFFLENBQUMsTUFBTSxDQUFDLElBQUk7UUFDM0MsR0FBRyxFQUFFLE1BQU0sQ0FBQyxPQUFPLENBQUMsRUFBb0MsQ0FBQztRQUN6RCxLQUFLLEVBQUUsTUFBTSxDQUFDLE9BQU8sQ0FBQyxFQUFvQyxDQUFDO0tBQzVELENBQUM7Q0FDSCxDQUNGLENBQUE7QUFHRCwwRUFBMEU7QUFDMUUsTUFBTSxDQUFDLE1BQU0sbUJBQW1CLEdBQUcsQ0FBQyxHQUE0QyxFQUEwQixFQUFFLENBQUMsQ0FBQztJQUM1RyxHQUFHLEVBQUUsQ0FBQyxHQUFHLEVBQUUsRUFBRSxDQUFDLEdBQUcsQ0FBQyxNQUFNLENBQUMsR0FBRyxFQUFFLENBQUMsSUFBSSxFQUFFLEVBQUUsQ0FBQyxDQUFDLEdBQUcsSUFBSSxFQUFFLEdBQUcsQ0FBQyxDQUFDO0lBQ3ZELEdBQUcsRUFBRSxHQUFHLENBQUMsR0FBRyxDQUFDLEdBQUcsQ0FBQztJQUNqQixLQUFLLEVBQUUsR0FBRyxDQUFDLFNBQVMsQ0FBQyxHQUFHLEVBQUUsRUFBRSxDQUFDO0NBQzlCLENBQUMsQ0FBQSJ9