effect 4.0.5 → 4.0.7

package/src/reactivity/AtomRegistry.ts

@@ -15,12 +15,14 @@ import * as Effect from "../Effect.ts"
 import * as Exit from "../Exit.ts"
 import * as Fiber from "../Fiber.ts"
 import { constVoid, dual } from "../Function.ts"
+import { shouldHydrate } from "../internal/hydration.ts"
 import * as Layer from "../Layer.ts"
 import * as Option from "../Option.ts"
 import { hasProperty } from "../Predicate.ts"
 import * as Queue from "../Queue.ts"
 import type { Scheduler, SchedulerDispatcher } from "../Scheduler.ts"
 import { MixedScheduler } from "../Scheduler.ts"
+import * as Schema from "../Schema.ts"
 import * as Scope from "../Scope.ts"
 import * as Stream from "../Stream.ts"
 import * as Result from "./AsyncResult.ts"
@@ -130,7 +132,7 @@ export interface Node<A> {
  */
 export const make = (
   options?: {
-    readonly initialValues?: Iterable<readonly [Atom.Atom<any>, any]> | undefined
+    readonly initialValues?: Iterable<readonly [Atom.Atom<any>, any, Atom.InitialValueOptions?]> | undefined
     readonly scheduleTask?: ((f: () => void) => () => void) | undefined
     readonly timeoutResolution?: number | undefined
     readonly defaultIdleTTL?: number | undefined
@@ -170,7 +172,7 @@ export const AtomRegistry = Context.Service<AtomRegistry>(TypeId)
  * @since 4.0.0
  */
 export const layerOptions = (options?: {
-  readonly initialValues?: Iterable<readonly [Atom.Atom<any>, any]> | undefined
+  readonly initialValues?: Iterable<readonly [Atom.Atom<any>, any, Atom.InitialValueOptions?]> | undefined
   readonly scheduleTask?: ((f: () => void) => () => void) | undefined
   readonly timeoutResolution?: number | undefined
   readonly defaultIdleTTL?: number | undefined
@@ -251,23 +253,7 @@ export const toStream: {
 } = dual(
   2,
   <A>(self: AtomRegistry, atom: Atom.Atom<A>) =>
-    Stream.callback<// -----------------------------------------------------------------------------
-    // conversions
-    // -----------------------------------------------------------------------------
-
-    /**
-     * Converts an atom in this registry into a stream.
-     *
-     * **Details**
-     *
-     * The stream emits the current value immediately, emits subsequent changes, and
-     * unsubscribes from the registry when the stream scope closes.
-     *
-     * @stability unstable
-     * @category converting
-     * @since 4.0.0
-     */
-    A>((queue) =>
+    Stream.callback<A>((queue) =>
       Effect.suspend(() => {
         const fiber = Fiber.getCurrent()!
         const scope = Context.getUnsafe(fiber.context, Scope.Scope)
@@ -494,7 +480,7 @@ class RegistryImpl implements AtomRegistry {
   onNodeRemoved?: ((node: Node<any>) => void) | undefined
 
   constructor(
-    initialValues?: Iterable<readonly [Atom.Atom<any>, any]>,
+    initialValues?: Iterable<readonly [Atom.Atom<any>, any, Atom.InitialValueOptions?]>,
     scheduleTask?: (cb: () => void) => () => void,
     timeoutResolution?: number,
     defaultIdleTTL?: number
@@ -511,12 +497,12 @@ class RegistryImpl implements AtomRegistry {
       this.timeoutResolution = timeoutResolution ?? 1000
     }
     if (initialValues !== undefined) {
-      for (const [atom, value] of initialValues) {
+      for (const [atom, value, options] of initialValues) {
         let target = atom
         while (target.initialValueTarget) {
           target = target.initialValueTarget
         }
-        this.ensureNode(target).setInitialValue(value)
+        this.ensureNode(target).setInitialValue(value, options?.skipInitialRun)
       }
     }
   }
@@ -603,15 +589,21 @@ class RegistryImpl implements AtomRegistry {
     if (typeof key === "string" && this.preloadedSerializable.has(key)) {
       const encoded = this.preloadedSerializable.get(key)
       this.preloadedSerializable.delete(key)
-      const decoded = (atom as any as Atom.Serializable<any>)[SerializableTypeId].decode(encoded)
+      const serializable = (atom as any as Atom.Serializable<any>)[SerializableTypeId]
+      let decoded: A
+      try {
+        decoded = serializable.decode(encoded as Schema.Json)
+      } catch (error) {
+        if (Schema.isSchemaError(error)) return node
+        throw error
+      }
       let target = atom
       while (target.initialValueTarget) {
         target = target.initialValueTarget
       }
-      if (target === atom) {
-        node.setValue(decoded)
-      } else {
-        this.ensureNode(target).setInitialValue(decoded)
+      const targetNode = target === atom ? node : this.ensureNode(target)
+      if (shouldHydrate(targetNode._value, decoded)) {
+        targetNode.setInitialValue(decoded, serializable.skipInitialRun)
       }
     }
     return node
@@ -629,7 +621,9 @@ class RegistryImpl implements AtomRegistry {
   }
 
   invalidateAtom = <A>(atom: Atom.Atom<A>): void => {
-    this.ensureNode(atom).invalidate()
+    const node = this.ensureNode(atom)
+    node.skipInitialRun = false
+    node.invalidate()
   }
 
   scheduleAtomRemoval(atom: Atom.Atom<any>): void {
@@ -780,6 +774,10 @@ class NodeImpl<A> {
   lifetime: Lifetime<A> | undefined
   writeContext: WriteContextImpl<A>
   preserveInitialValueOnBuild = false
+  skipInitialRun = false
+  // the parents, and their lifetimes, of a build that kept the seed without
+  // reaching the effect, such as one waiting for a runtime
+  keptParents: Array<readonly [NodeImpl<any>, Lifetime<any> | undefined]> | undefined
   invalidatedDuringBuild = false
   failed = false
 
@@ -866,6 +864,9 @@ class NodeImpl<A> {
     if (this.lifetime === lifetime && (this.state & NodeFlags.waitingForValue) !== 0) {
       if (this.preserveInitialValueOnBuild) {
         this.preserveInitialValueOnBuild = false
+        if (this.skipInitialRun) {
+          this.keptParents = Array.from(this.parents, (parent) => [parent, parent.lifetime] as const)
+        }
         this.failed = false
         this.state = NodeState.valid
       } else {
@@ -939,9 +940,10 @@ class NodeImpl<A> {
     return Option.some(this._value)
   }
 
-  setInitialValue(value: A): void {
+  setInitialValue(value: A, skipInitialRun = false): void {
     if ((this.state & NodeFlags.initialized) === 0) {
       this.preserveInitialValueOnBuild = true
+      this.skipInitialRun = skipInitialRun
       this.state = NodeState.stale
       this._value = value
       if (this.listeners.size > 0) {
@@ -1100,6 +1102,25 @@ class NodeImpl<A> {
   }
 }
 
+/**
+ * Whether the build keeps the node's seeded value instead of running its
+ * effect or stream. Consumed by the first run, so later rebuilds run it. A
+ * parent rebuilt since the seed was kept, such as a reconfigured runtime, is a
+ * real change and runs it too.
+ *
+ * @internal
+ */
+export const consumeSkipInitialRun = (ctx: Atom.AtomContext): boolean => {
+  const lifetime = ctx as Lifetime<any>
+  const node = lifetime.node
+  if (!node.skipInitialRun) return false
+  const keptParents = node.keptParents
+  node.skipInitialRun = false
+  node.keptParents = undefined
+  return !lifetime.isFn && !Result.isInitial(node._value) &&
+    (keptParents === undefined || keptParents.every(([parent, lifetime]) => parent.lifetime === lifetime))
+}
+
 interface Lifetime<A> extends Atom.AtomContext {
   isFn: boolean
   readonly node: NodeImpl<A>

package/src/reactivity/AtomRpc.ts

@@ -15,7 +15,6 @@ import * as Duration from "../Duration.ts"
 import * as Effect from "../Effect.ts"
 import * as Headers from "../http/Headers.ts"
 import * as Layer from "../Layer.ts"
-import type { ReadonlyRecord } from "../Record.ts"
 import type * as Rpc from "../rpc/Rpc.ts"
 import * as RpcClient from "../rpc/RpcClient.ts"
 import { RpcClientError } from "../rpc/RpcClientError.ts"
@@ -68,10 +67,7 @@ export interface AtomRpcClient<Self, Id extends string, Rpcs extends Rpc.Any> ex
     : Atom.AtomResultFn<
       {
         readonly payload: Rpc.PayloadConstructor<Rpcs>
-        readonly reactivityKeys?:
-          | ReadonlyArray<unknown>
-          | ReadonlyRecord<string, ReadonlyArray<unknown>>
-          | undefined
+        readonly reactivityKeys?: Reactivity.KeysInput | undefined
         readonly headers?: Headers.Input | undefined
       },
       _Success["Type"],
@@ -84,10 +80,7 @@ export interface AtomRpcClient<Self, Id extends string, Rpcs extends Rpc.Any> ex
     payload: Rpc.PayloadConstructor<Rpc.ExtractTag<Rpcs, Tag>>,
     options?: {
       readonly headers?: Headers.Input | undefined
-      readonly reactivityKeys?:
-        | ReadonlyArray<unknown>
-        | ReadonlyRecord<string, ReadonlyArray<unknown>>
-        | undefined
+      readonly reactivityKeys?: Reactivity.KeysInput | undefined
       readonly timeToLive?: Duration.Input | undefined
       readonly serializationKey?: string | undefined
     }
@@ -196,10 +189,7 @@ export const Service = <Self>() =>
     const rpc = options.group.requests.get(tag)! as any as Rpc.AnyWithProps
     return self.runtime.fn<{
       readonly payload: Rpc.PayloadConstructor<Rpc.ExtractTag<Rpcs, Tag>>
-      readonly reactivityKeys?:
-        | ReadonlyArray<unknown>
-        | ReadonlyRecord<string, ReadonlyArray<unknown>>
-        | undefined
+      readonly reactivityKeys?: Reactivity.KeysInput | undefined
       readonly headers?: Headers.Input | undefined
     }>()(
       Effect.fnUntraced(function*({ headers, payload, reactivityKeys }) {
@@ -211,7 +201,7 @@ export const Service = <Self>() =>
       })
     ).pipe(
       Atom.serializable({
-        key: `AtomRpc:mutation:${tag}`,
+        key: `AtomRpc:mutation:${JSON.stringify([id, tag])}`,
         schema: AsyncResult.Schema({
           success: rpc.successSchema,
           error: makeErrorSchema(rpc)
@@ -264,10 +254,7 @@ export const Service = <Self>() =>
     payload: Rpc.PayloadConstructor<Rpc.ExtractTag<Rpcs, Tag>>,
     options?: {
       readonly headers?: Headers.Input | undefined
-      readonly reactivityKeys?:
-        | ReadonlyArray<unknown>
-        | ReadonlyRecord<string, ReadonlyArray<unknown>>
-        | undefined
+      readonly reactivityKeys?: Reactivity.KeysInput | undefined
       readonly timeToLive?: Duration.Input | undefined
       readonly serializationKey?: string | undefined
     }
@@ -294,10 +281,7 @@ interface QueryKey {
   tag: string
   payload: any
   headers: Headers.Headers | undefined
-  reactivityKeys:
-    | ReadonlyArray<unknown>
-    | ReadonlyRecord<string, ReadonlyArray<unknown>>
-    | undefined
+  reactivityKeys: Reactivity.KeysInput | undefined
   timeToLive: Duration.Duration | undefined
   serializationKey: string | undefined
 }

package/src/reactivity/Hydration.ts

@@ -11,6 +11,8 @@
  * @stability unstable
  * @since 4.0.0
  */
+import { shouldHydrate } from "../internal/hydration.ts"
+import * as Option from "../Option.ts"
 import * as Schema from "../Schema.ts"
 import * as AsyncResult from "./AsyncResult.ts"
 import * as Atom from "./Atom.ts"
@@ -61,6 +63,18 @@ const encodeOrSkip = (
   }
 }
 
+const decodeOrSkip = (
+  atom: Atom.Serializable<any>,
+  value: unknown
+): unknown => {
+  try {
+    return atom[Atom.SerializableTypeId].decode(value as Schema.Json)
+  } catch (error) {
+    if (Schema.isSchemaError(error)) return Skipped
+    throw error
+  }
+}
+
 /**
  * Encodes the serializable atoms currently stored in a registry into dehydrated
  * state.
@@ -156,25 +170,52 @@ export const hydrate = (
   for (const datom of (dehydratedState as Iterable<DehydratedAtomValue>)) {
     registry.setSerializable(datom.key, datom.value)
 
+    // Apply hydration immediately to existing subscribers.
+    const existing = registry.getNodes().get(datom.key)
+    if (existing !== undefined) registry.ensureNode(existing.atom)
+
     // If there's a resultPromise, it means this was in Initial state when dehydrated
     // and we should wait for it to resolve to a non-Initial state, then update the registry
     if (!datom.resultPromise) continue
     datom.resultPromise.then((resolvedValue) => {
-      if (resolvedValue === Skipped) return
       // Try to update the existing node directly instead of using setSerializable
-      const nodes = registry.getNodes()
-      const node = nodes.get(datom.key)
-      if (node) {
-        // Decode the resolved value using the node's atom serializable decoder
-        const atom = node.atom as any
-        if (atom[Atom.SerializableTypeId]) {
-          const decoded = atom[Atom.SerializableTypeId].decode(resolvedValue)
-          ;(node as any).setValue(decoded)
+      const node = registry.getNodes().get(datom.key)
+      if (resolvedValue !== Skipped) {
+        if (node === undefined) {
+          // Fallback to setSerializable if node doesn't exist yet
+          registry.setSerializable(datom.key, resolvedValue)
+          return
+        }
+        const decoded = decodeOrSkip(node.atom as any, resolvedValue)
+        if (decoded !== Skipped) {
+          if (shouldHydrate(Option.getOrUndefined(node.valueOption()), decoded)) {
+            ;(node as any).setValue(decoded)
+          }
+          return
         }
-      } else {
-        // Fallback to setSerializable if node doesn't exist yet
-        registry.setSerializable(datom.key, resolvedValue)
       }
+
+      // The result is unusable, so release the hydrated Initial and compute on the client
+      registry.preloadedSerializable.delete(datom.key)
+      if (node === undefined) return
+      let target = node.atom
+      while (target.initialValueTarget) {
+        target = target.initialValueTarget
+      }
+      if (target !== node.atom) {
+        releaseInitial(registry.ensureNode(target))
+      } // Derived atoms may not have read their source yet, so invalidate them directly too
+
+      releaseInitial(node)
     })
   }
 }
+
+const releaseInitial = (node: AtomRegistry.Node<any>): void => {
+  const internal = node as any
+  // An unbuilt target can hold hydration through preserveInitialValueOnBuild,
+  // which valueOption does not expose. Only release an Initial, not newer client results.
+  if (!AsyncResult.isAsyncResult(internal._value) || !AsyncResult.isInitial(internal._value)) return
+  internal.preserveInitialValueOnBuild = false
+  internal.invalidate()
+}

package/src/reactivity/Reactivity.ts

@@ -40,6 +40,71 @@ export type TypeId = "~effect/reactivity/Reactivity"
  */
 export const TypeId: TypeId = "~effect/reactivity/Reactivity"
 
+/**
+ * Registry of reactivity keys and the ID type each key accepts.
+ *
+ * **Details**
+ *
+ * The registry is empty by default, and every key name and ID is accepted.
+ * Once an application declares keys through module augmentation, the public
+ * reactivity APIs (`Reactivity.mutation`, `Reactivity.query`,
+ * `Reactivity.stream`, `Reactivity.invalidate`, `Atom`, `AtomHttpApi`,
+ * `AtomRpc`, `SqlClient.reactive` and `EventLog.groupReactivity`) only accept
+ * declared key names, and record IDs must match the declared ID type. Declare
+ * a key as `never` if it is only used in array form.
+ *
+ * **Gotchas**
+ *
+ * Only applications should augment this interface, never libraries. The
+ * augmentation applies to the whole program, so a library declaring keys would
+ * switch every consumer to strict keys.
+ *
+ * Methods on the `Reactivity` service still accept any key, for code that only
+ * knows its keys at runtime.
+ *
+ * **Example** (Declaring reactivity keys)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect } from "effect"
+ * import { Reactivity } from "effect/reactivity"
+ *
+ * declare module "effect/reactivity/Reactivity" {
+ *   interface Keys {
+ *     readonly users: number
+ *     readonly events: never
+ *   }
+ * }
+ *
+ * // Invalidates the `users` query with ID 1 and every `events` query
+ * const program = Effect.succeed("saved").pipe(
+ *   Reactivity.mutation({ users: [1] }),
+ *   Effect.andThen(Reactivity.invalidate(["events"]))
+ * )
+ * ```
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Keys {}
+
+/**
+ * Keys accepted by the public reactivity APIs.
+ *
+ * **Details**
+ *
+ * With no keys declared in {@link Keys}, any array of keys or record of key IDs
+ * is accepted. Once keys are declared, only declared key names and their ID
+ * types are accepted.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export type KeysInput = [keyof Keys] extends [never]
+  ? ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
+  : ReadonlyArray<keyof Keys> | { readonly [K in keyof Keys]?: ReadonlyArray<Keys[K]> }
+
 /**
  * Registers handlers and reruns queries when their keys are invalidated.
  *
@@ -96,12 +161,21 @@ export const Reactivity: Context.Service<Reactivity, Reactivity> = Context.Servi
 export const make = Effect.sync(() => {
   const handlers = new Map<number | string, Set<() => void>>()
 
+  const runHandlers = (hashes: Iterable<string | number>): void => {
+    const ran = new Set<() => void>()
+    for (const hash of hashes) {
+      handlers.get(hash)?.forEach((run) => {
+        if (ran.has(run)) return
+        ran.add(run)
+        run()
+      })
+    }
+  }
+
   const invalidateUnsafe = (keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>): void => {
-    keysToHashes(keys, (hash) => {
-      const set = handlers.get(hash)
-      if (set === undefined) return
-      set.forEach((run) => run())
-    })
+    const hashes = new Set<string | number>()
+    keysToHashes(keys, (hash) => hashes.add(hash))
+    runHandlers(hashes)
   }
 
   const invalidate = (
@@ -162,9 +236,15 @@ export const make = Effect.sync(() => {
 
       let running = false
       let pending = false
+      let stopped = false
       const handleExit = (exit: Exit.Exit<A, E>) => {
         if (exit._tag === "Failure") {
+          stopped = true
+          pending = false
+          running = false
+          cancel()
           Queue.failCauseUnsafe(results, exit.cause)
+          return
         } else {
           Queue.offerUnsafe(results, exit.value)
         }
@@ -177,6 +257,7 @@ export const make = Effect.sync(() => {
       }
 
       function run() {
+        if (stopped) return
         if (running) {
           pending = true
           return
@@ -206,15 +287,7 @@ export const make = Effect.sync(() => {
       const pending = new Set<string | number>()
       return effect.pipe(
         Effect.provideService(PendingInvalidation, pending),
-        Effect.onExit((_) =>
-          Effect.sync(() => {
-            pending.forEach((hash) => {
-              const set = handlers.get(hash)
-              if (set === undefined) return
-              set.forEach((run) => run())
-            })
-          })
-        )
+        Effect.onExit((_) => Effect.sync(() => runHandlers(pending)))
       )
     })
 
@@ -257,9 +330,7 @@ export const mutation: {
    * @category accessors
    * @since 4.0.0
    */
-  (
-    keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
-  ): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | Reactivity>
+  (keys: KeysInput): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R | Reactivity>
   /**
    * Wraps an effect so the supplied keys are invalidated after the effect succeeds.
    *
@@ -271,13 +342,10 @@ export const mutation: {
    * @category accessors
    * @since 4.0.0
    */
-  <A, E, R>(
-    effect: Effect.Effect<A, E, R>,
-    keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
-  ): Effect.Effect<A, E, R | Reactivity>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, keys: KeysInput): Effect.Effect<A, E, R | Reactivity>
 } = dual(2, <A, E, R>(
   effect: Effect.Effect<A, E, R>,
-  keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
+  keys: KeysInput
 ): Effect.Effect<A, E, R | Reactivity> => Reactivity.use((_) => _.mutation(keys, effect)))
 
 /**
@@ -305,9 +373,7 @@ export const query: {
    * @category accessors
    * @since 4.0.0
    */
-  (
-    keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
-  ): <A, E, R>(
+  (keys: KeysInput): <A, E, R>(
     effect: Effect.Effect<A, E, R>
   ) => Effect.Effect<Queue.Dequeue<A, E>, never, R | Scope.Scope | Reactivity>
   /**
@@ -322,13 +388,10 @@ export const query: {
    * @category accessors
    * @since 4.0.0
    */
-  <A, E, R>(
-    effect: Effect.Effect<A, E, R>,
-    keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
-  ): Effect.Effect<Queue.Dequeue<A, E>, never, R | Scope.Scope | Reactivity>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, keys: KeysInput): Effect.Effect<Queue.Dequeue<A, E>, never, R | Scope.Scope | Reactivity>
 } = dual(2, <A, E, R>(
   effect: Effect.Effect<A, E, R>,
-  keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
+  keys: KeysInput
 ): Effect.Effect<Queue.Dequeue<A, E>, never, R | Scope.Scope | Reactivity> =>
   Reactivity.use((r) => r.query(keys, effect)))
 
@@ -357,9 +420,7 @@ export const stream: {
    * @category accessors
    * @since 4.0.0
    */
-  (
-    keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
-  ): <A, E, R>(effect: Effect.Effect<A, E, R>) => Stream.Stream<A, E, Exclude<R, Scope.Scope> | Reactivity>
+  (keys: KeysInput): <A, E, R>(effect: Effect.Effect<A, E, R>) => Stream.Stream<A, E, Exclude<R, Scope.Scope> | Reactivity>
   /**
    * Runs an effect as a stream of query results tied to the supplied invalidation
    * keys.
@@ -372,13 +433,10 @@ export const stream: {
    * @category accessors
    * @since 4.0.0
    */
-  <A, E, R>(
-    effect: Effect.Effect<A, E, R>,
-    keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
-  ): Stream.Stream<A, E, Exclude<R, Scope.Scope> | Reactivity>
+  <A, E, R>(effect: Effect.Effect<A, E, R>, keys: KeysInput): Stream.Stream<A, E, Exclude<R, Scope.Scope> | Reactivity>
 } = dual(2, <A, E, R>(
   effect: Effect.Effect<A, E, R>,
-  keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
+  keys: KeysInput
 ): Stream.Stream<A, E, Exclude<R, Scope.Scope> | Reactivity> =>
   Reactivity.use((r) => r.query(keys, effect)).pipe(
     Effect.map(Stream.fromQueue),
@@ -398,7 +456,7 @@ export const stream: {
  * @since 4.0.0
  */
 export const invalidate = (
-  keys: ReadonlyArray<unknown> | ReadonlyRecord<string, ReadonlyArray<unknown>>
+  keys: KeysInput
 ): Effect.Effect<void, never, Reactivity> => Reactivity.use((r) => r.invalidate(keys))
 
 /**

package/src/rpc/Rpc.ts

@@ -23,6 +23,7 @@ import * as Predicate from "../Predicate.ts"
 import * as PrimaryKey from "../PrimaryKey.ts"
 import type * as Queue from "../Queue.ts"
 import * as Schema from "../Schema.ts"
+import * as SchemaAST from "../SchemaAST.ts"
 import type { Stream } from "../Stream.ts"
 import type * as Struct from "../Struct.ts"
 import type { NoInfer } from "../Types.ts"
@@ -1194,6 +1195,26 @@ export const exitSchema = <R extends Any>(
   return schema as any
 }
 
+/**
+ * Annotation that sets the schema parse options used by `RpcClient` and
+ * `RpcServer` when encoding and decoding an RPC's payload, success values,
+ * stream chunks, and exits.
+ *
+ * **Details**
+ *
+ * The default value is `SchemaAST.defaultParseOptions`. Set `concurrency` to
+ * parse product elements concurrently, which lets decoding transformations that
+ * call `Effect.request` share `RequestResolver` batches. Annotate a single RPC
+ * with `annotate`, or every RPC in a group with `RpcGroup.annotateRpcs`.
+ *
+ * @stability unstable
+ * @category annotations
+ * @since 4.0.0
+ */
+export const ParseOptions = Context.Reference<SchemaAST.ParseOptions>("effect/rpc/Rpc/ParseOptions", {
+  defaultValue: () => SchemaAST.defaultParseOptions
+})
+
 const WrapperTypeId = "~effect/rpc/Rpc/Wrapper"
 
 /**