effect-app 4.0.0-beta.99 → 4.0.0

package/src/rpc/MiddlewareMaker.ts

@@ -1,18 +1,18 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { Effect, Layer, type Schema, Schema as S, type Scope } from "effect"
 import { type NonEmptyArray, type NonEmptyReadonlyArray } from "effect/Array"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import { Rpc, type RpcGroup, type RpcSchema } from "effect/rpc"
+import { type HandlersFrom } from "effect/rpc/RpcGroup"
+import * as S from "effect/Schema"
+import type * as Scope from "effect/Scope"
 import { type Simplify } from "effect/Types"
-import { Rpc, type RpcGroup, type RpcSchema } from "effect/unstable/rpc"
-import { type HandlersFrom } from "effect/unstable/rpc/RpcGroup"
-import { type RequestId } from "effect/unstable/rpc/RpcMessage"
-import * as Context from "../Context.js"
-import { type HttpHeaders } from "../http.js"
-import { PreludeLogger } from "../logger.js"
-import { type TypeTestId } from "../TypeTest.js"
-import { typedValuesOf } from "../utils.js"
-import { type GetContextConfig, type RequestContextMapTagAny, type RpcContextMap } from "./RpcContextMap.js"
-import { type AddMiddleware, type AnyDynamic, type RpcDynamic, type RpcMiddlewareV4, type TagClassAny } from "./RpcMiddleware.js"
-import * as RpcMiddlewareX from "./RpcMiddleware.js"
+import * as Context from "../Context.ts"
+import { PreludeLogger } from "../logger.ts"
+import { type TypeTestId } from "../TypeTest.ts"
+import { type GetContextConfig, type RequestContextMapTagAny, type RpcContextMap } from "./RpcContextMap.ts"
+import { type AddMiddleware, type AnyDynamic, type RpcDynamic, type RpcMiddlewareV4, type TagClassAny } from "./RpcMiddleware.ts"
+import * as RpcMiddlewareX from "./RpcMiddleware.ts"
 
 // adapter for effect/rpc v3 middleware provides. (in effect-smol (v4), it's just a Service Identifier, no tags.)
 // hm?
@@ -94,7 +94,7 @@ export namespace MiddlewareMaker {
     : never
     : never
 
-  export type Errors<T> = T extends TagClassAny ? T extends { error: S.Top } ? S.Schema.Type<T["error"]>
+  export type Errors<T> = T extends TagClassAny ? T extends { error: S.Top } ? T["error"]["Type"]
     : never
     : never
 
@@ -170,9 +170,9 @@ export interface BuildingMiddleware<
 > {
   rpc: <
     const Tag extends string,
-    Payload extends Schema.Top | Schema.Struct.Fields = typeof Schema.Void,
-    Success extends Schema.Top = typeof Schema.Void,
-    Error extends Schema.Top = typeof Schema.Never,
+    Payload extends S.Top | S.Struct.Fields = typeof S.Void,
+    Success extends S.Top = typeof S.Void,
+    Error extends S.Top = typeof S.Never,
     const Stream extends boolean = false,
     Config extends GetContextConfig<RequestContextMap> = {}
   >(tag: Tag, options?: {
@@ -181,16 +181,16 @@ export interface BuildingMiddleware<
     readonly error?: Error
     readonly stream?: Stream
     readonly config?: Config
-    readonly primaryKey?: [Payload] extends [Schema.Struct.Fields] ? ((
-        payload: Payload extends Schema.Struct.Fields ? Simplify<Schema.Struct<Payload>["Type"]> : Payload["Type"]
+    readonly primaryKey?: [Payload] extends [S.Struct.Fields] ? ((
+        payload: Payload extends S.Struct.Fields ? Simplify<S.Struct<Payload>["Type"]> : Payload["Type"]
       ) => string)
       : never
   }) =>
     & Rpc.Rpc<
       Tag,
-      Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
+      Payload extends S.Struct.Fields ? S.Struct<Payload> : Payload,
       Stream extends true ? RpcSchema.Stream<Success, Error> : Success,
-      Stream extends true ? typeof Schema.Never : Error
+      Stream extends true ? typeof S.Never : Error
     >
     & { readonly config: Config }
 
@@ -259,10 +259,10 @@ export type MiddlewaresBuilder<
     : { new(_: never): {} }
     : { new(_: never): {} })
 
-const middlewareMaker = <
+const middlewareMaker = Effect.fnUntraced(function*<
   MiddlewareProviders extends ReadonlyArray<MiddlewareMaker.Any>
->(middlewares: MiddlewareProviders): Effect.Effect<
-  RpcMiddlewareV4<
+>(middlewares: MiddlewareProviders) {
+  type Middleware = RpcMiddlewareV4<
     MiddlewareMaker.ManyProvided<MiddlewareProviders>,
     MiddlewareMaker.ManyErrors<MiddlewareProviders>,
     Exclude<
@@ -271,42 +271,32 @@ const middlewareMaker = <
     > extends never ? never
       : Exclude<MiddlewareMaker.ManyRequired<MiddlewareProviders>, MiddlewareMaker.ManyProvided<MiddlewareProviders>>
   >
-> => {
+  type Next = Parameters<Middleware>[0]
+  type Options = Parameters<Middleware>[1]
+
   // we want to run them in reverse order because latter middlewares will provide context to former ones
-  middlewares = middlewares.toReversed() as any
-
-  return Effect.gen(function*() {
-    const context = yield* Effect.context()
-
-    // returns a Effect/RpcMiddlewareV4 with Scope.Scope in requirements
-    // v4: wrap middleware takes (effect, options) as two params instead of a single options bag
-    return (
-      next: Effect.Effect<any, any, any>,
-      options: {
-        readonly clientId: number
-        readonly requestId: RequestId
-        readonly rpc: Rpc.AnyWithProps
-        readonly payload: unknown
-        readonly headers: HttpHeaders.Headers
-      }
-    ) => {
-      // we start with the actual handler
-      let handler = next
-
-      // inspired from Effect/RpcMiddleware
-      for (const tag of middlewares) {
-        // use the tag to get the middleware from context
-        const middleware = Context.getUnsafe(context, tag)
-
-        // wrap the current handler, allowing the middleware to run before and after it
-        handler = PreludeLogger.logDebug("Applying middleware wrap " + tag.key).pipe(
-          Effect.andThen(middleware(handler, options))
-        ) as any
-      }
-      return handler
+  const reversed = middlewares.toReversed()
+  const context = yield* Effect.context()
+
+  // returns a Effect/RpcMiddlewareV4 with Scope.Scope in requirements
+  // v4: wrap middleware takes (effect, options) as two params instead of a single options bag
+  return (next: Next, options: Options) => {
+    // we start with the actual handler
+    let handler = next
+
+    // inspired from Effect/RpcMiddleware
+    for (const tag of reversed) {
+      // use the tag to get the middleware from context
+      const middleware = Context.getUnsafe(context, tag)
+
+      // wrap the current handler, allowing the middleware to run before and after it
+      handler = PreludeLogger.logDebug("Applying middleware wrap " + tag.key).pipe(
+        Effect.andThen(middleware(handler, options))
+      ) as any
     }
-  }) as any
-}
+    return handler
+  }
+})
 
 const makeMiddlewareBasic = <Self>() =>
 // by setting RequestContextMap beforehand, execute contextual typing does not fuck up itself to anys
@@ -322,7 +312,26 @@ const makeMiddlewareBasic = <Self>() =>
   // reverse middlewares and wrap one after the other
   const middleware = middlewareMaker(make)
 
-  const failures = make.map((_) => _.error).filter(Boolean)
+  // Per-middleware error: union of the static `error` on the tag (if any) AND
+  // the rcm config entry pointed at by the middleware's `dynamic.key` (if any).
+  // Reason: middlewares declared with `dynamic: RequestContextMap.get("foo")`
+  // don't set a static `error` field — at runtime their `.error` defaults to
+  // `S.Never`. Without pulling from rcm, the composite middleware's
+  // `.error` collapses to `Never`, and `Rpc.exitSchema` (which walks
+  // `rpc.middlewares[*].error` to build the wire failure union) can't decode
+  // the actual middleware-thrown error type. Critical for stream rpcs whose
+  // top-level `errorSchema` is force-set to `Never` by effect-rpc.
+  const isMeaningfulError = (e: S.Top | undefined): e is S.Top => e !== undefined && e !== null && e !== S.Never
+  const rcmRecord = rcm as Record<string, RpcContextMap.Any>
+  const failures: Array<S.Top> = make.flatMap((_) => {
+    const out: Array<S.Top> = []
+    if (isMeaningfulError(_.error)) out.push(_.error)
+    const key = _.dynamic?.key as string | undefined
+    if (key && rcmRecord[key] && isMeaningfulError(rcmRecord[key].error)) {
+      out.push(rcmRecord[key].error)
+    }
+    return out
+  })
   const provides = make.flatMap((_) => !_.provides ? [] : Array.isArray(_.provides) ? _.provides : [_.provides])
   const requires = make
     .flatMap((_) => !_.requires ? [] : Array.isArray(_.requires) ? _.requires : [_.requires])
@@ -358,10 +367,11 @@ const makeMiddlewareBasic = <Self>() =>
     .effect(
       MiddlewareMaker,
       middleware as Effect.Effect<
-        any,
-        Effect.Error<typeof middleware>,
-        Effect.Services<typeof middleware>
+        any
       >
+      // todo; they dont change the type..
+      //  Effect.Error<typeof middleware>,
+      //  Effect.Services<typeof middleware>
     )
 
   // add to the tag a default implementation
@@ -380,7 +390,7 @@ export const Tag = <Self>() =>
   const Id extends string,
   RequestContextMap extends RequestContextMapTagAny
 >(id: Id, rcm: RequestContextMap): MiddlewaresBuilder<Self, Id, RequestContextMap["config"]> => {
-  let allMiddleware: MiddlewareMaker.Any[] = []
+  const allMiddleware: MiddlewareMaker.Any[] = []
   const requestContext = Context.Service<"RequestContextConfig", GetContextConfig<RequestContextMap["config"]>>(
     "RequestContextConfig"
   )
@@ -389,9 +399,9 @@ export const Tag = <Self>() =>
     // rpc with config
     rpc: <
       const Tag extends string,
-      Payload extends Schema.Top | Schema.Struct.Fields = typeof Schema.Void,
-      Success extends Schema.Top = typeof Schema.Void,
-      Error extends Schema.Top = typeof Schema.Never,
+      Payload extends S.Top | S.Struct.Fields = typeof S.Void,
+      Success extends S.Top = typeof S.Void,
+      Error extends S.Top = typeof S.Never,
       const Stream extends boolean = false,
       Config extends GetContextConfig<RequestContextMap["config"]> = {}
     >(tag: Tag, options?: {
@@ -400,35 +410,32 @@ export const Tag = <Self>() =>
       readonly error?: Error
       readonly stream?: Stream
       readonly config?: Config
-      readonly primaryKey?: [Payload] extends [Schema.Struct.Fields] ? ((
-          payload: Payload extends Schema.Struct.Fields ? Simplify<Schema.Struct<Payload>["Type"]> : Payload["Type"]
+      readonly primaryKey?: [Payload] extends [S.Struct.Fields] ? ((
+          payload: Payload extends S.Struct.Fields ? Simplify<S.Struct<Payload>["Type"]> : Payload["Type"]
         ) => string)
         : never
     }):
       & Rpc.Rpc<
         Tag,
-        Payload extends Schema.Struct.Fields ? Schema.Struct<Payload> : Payload,
+        Payload extends S.Struct.Fields ? S.Struct<Payload> : Payload,
         // TODO: enhance `Error`. type based on middleware config.
         Stream extends true ? RpcSchema.Stream<Success, Error> : Success,
-        Stream extends true ? typeof Schema.Never : Error
+        Stream extends true ? typeof S.Never : Error
       >
       & { config: Config } =>
     {
       const config = options?.config ?? {} as Config
 
-      // based on the config, we must enhance (union) or set failures.
-      // TODO: we should only include errors that are relevant based on the middleware config.ks
-      const error = options?.error
-      const errors = typedValuesOf(rcm.config).map((_) => _.error).filter((_) => _ && _ !== S.Never) // TODO: only the errors relevant based on config
-      const allErrors = error ? [error, ...errors] : errors
-      const [firstError, ...restErrors] = allErrors
-      const newError = firstError ? S.Union([firstError, ...restErrors]) : S.Never
-
+      // The rpc's `error` schema carries ONLY the request's own declared errors.
+      // Middleware errors (rcm-derived) reach the wire via the middleware tag
+      // attached to the rpc group later (`RpcGroup.middleware(...)` at the
+      // routing/client level), and are unioned into the failure schema by
+      // `Rpc.exitSchema`'s `rpc.middlewares[*].error` walk.
       // @ts-expect-error — TypeScript can't prove Simplify<T> ≡ { [K in keyof T]: T[K] } for unresolved generics (primaryKey)
       const rpc = Rpc.make(tag, {
         ...options?.payload !== undefined ? { payload: options.payload } : {},
         ...options?.success !== undefined ? { success: options.success } : {},
-        error: newError,
+        ...options?.error !== undefined ? { error: options.error } : {},
         ...options?.stream !== undefined ? { stream: options.stream } : {},
         ...options?.primaryKey !== undefined ? { primaryKey: options.primaryKey } : {}
       }) as any
@@ -438,7 +445,7 @@ export const Tag = <Self>() =>
     middleware: (...middlewares: any[]) => {
       for (const mw of middlewares) {
         // recall that we run middlewares in reverse order
-        allMiddleware = [mw, ...allMiddleware]
+        allMiddleware.unshift(mw)
       }
       return allMiddleware.filter((m) => !!m.dynamic).length !== Object.keys(rcm.config).length
         // for sure, until all the dynamic middlewares are provided it's non sensical to call makeMiddlewareBasic

package/src/rpc/README.md

@@ -3,7 +3,7 @@
 The extensions use V4 format of RPC middleware:
 
 - supports `requires` besides `provides`
-- `requires` and `provides`  should be set as second generic argument: `Tag<Self, Config>`.
+- `requires` and `provides` should be set as second generic argument: `Tag<Self, Config>`.
 - `wrap: true` is the default, there is no classic `provides: Tag`
 
 ## Features
@@ -34,7 +34,7 @@ NOTE: perhaps not as useful anymore if support for dynamic middleware gets integ
 
 ## Examples
 
-See  [tests](../../../infra/test/rpc-multi-middleware.test.ts)
+See [tests](../../../infra/test/rpc-multi-middleware.test.ts)
 
 ## Future
 

package/src/rpc/RpcContextMap.ts

@@ -2,10 +2,10 @@
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
-import { type Schema as S } from "effect"
-import { type AnyWithProps } from "effect/unstable/rpc/Rpc"
-import * as Context from "../Context.js"
-import { type RpcDynamic } from "./RpcMiddleware.js"
+import { type AnyWithProps } from "effect/rpc/Rpc"
+import type * as S from "effect/Schema"
+import * as Context from "../Context.ts"
+import { type RpcDynamic } from "./RpcMiddleware.ts"
 
 type Values<T extends Record<any, any>> = T[keyof T]
 

package/src/rpc/RpcMiddleware.ts

@@ -1,18 +1,21 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type Effect, type Schema, type Schema as S, type Scope, type Stream } from "effect"
 import { type NonEmptyReadonlyArray } from "effect/Array"
-import { type Rpc, RpcMiddleware } from "effect/unstable/rpc"
-import { type TypeId } from "effect/unstable/rpc/RpcMiddleware"
-import type * as Context from "../Context.js"
-import { type GetEffectContext, type RpcContextMap } from "./RpcContextMap.js"
+import type * as Effect from "effect/Effect"
+import { type Rpc, RpcMiddleware } from "effect/rpc"
+import { type TypeId } from "effect/rpc/RpcMiddleware"
+import type * as S from "effect/Schema"
+import type * as Scope from "effect/Scope"
+import type * as Stream from "effect/Stream"
+import type * as Context from "../Context.ts"
+import { type GetEffectContext, type RpcContextMap } from "./RpcContextMap.ts"
 
 export type RpcMiddlewareV4<Provides, E, Requires> = RpcMiddleware.RpcMiddleware<Provides, E, Requires>
 
 export type RpcOptionsOriginal = {
   readonly optional?: boolean
-  readonly error?: Schema.Top
+  readonly error?: S.Top
   readonly requiredForClient?: boolean
 }
 
@@ -40,7 +43,7 @@ export interface TagClassAny extends RpcMiddleware.AnyService {
   readonly optional: boolean
   readonly provides: any
   readonly requires: any
-  readonly error: Schema.Top
+  readonly error: S.Top
   readonly dynamic?: RpcDynamic<any, any> | undefined
   readonly dependsOn?: NonEmptyReadonlyArray<AnyDynamic> | undefined
 }
@@ -50,27 +53,29 @@ export declare namespace TagClass {
    * @since 1.0.0
    * @category models
    */
-  export type FailureSchema<Options> = Options extends { readonly error: Schema.Top; readonly optional?: false }
+  export type FailureSchema<Options> = Options extends { readonly error: S.Top; readonly optional?: false }
     ? Options["error"]
     // actually not, the Failure depends on Dynamic Middleware Configuration!
     // : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? A["error"]
-    : typeof Schema.Never
+    : typeof S.Never
 
   /**
    * @since 1.0.0
    * @category models
    */
-  export type Failure<Options> = Options extends { readonly error: Schema.Codec<infer _A>; readonly optional?: false }
-    ? _A
+  export type Failure<Options> = Options extends { readonly error: S.Codec<infer _A>; readonly optional?: false } ? _A
     // actually not, the Failure depends on Dynamic Middleware Configuration!
-    : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? S.Schema.Type<A["error"]>
+    : Options extends { readonly dynamic: RpcDynamic<any, infer A> } ? A["error"]["Type"]
     : never
 
   /**
    * @since 1.0.0
    * @category models
    */
-  export type FailureContext<Options> = Schema.Codec.DecodingServices<FailureSchema<Options>>
+  // Avoid `S.Codec.DecodingServices<X> = X extends Top ? X["DecodingServices"] : never`:
+  // tsgo fails to reduce it here and leaves `unknown`. `FailureSchema<Options>` is
+  // always `S.Top` (either `Options["error"]` or `typeof S.Never`), so read directly.
+  export type FailureContext<Options> = FailureSchema<Options>["DecodingServices"]
 
   /**
    * @since 1.0.0

package/src/rpc.ts

@@ -1,4 +1,4 @@
-export * as RpcX from "./rpc.js"
-export * as MiddlewareMaker from "./rpc/MiddlewareMaker.js"
-export * as RpcContextMap from "./rpc/RpcContextMap.js"
-export * as RpcMiddleware from "./rpc/RpcMiddleware.js"
+export * as Invalidation from "./rpc/Invalidation.ts"
+export * as MiddlewareMaker from "./rpc/MiddlewareMaker.ts"
+export * as RpcContextMap from "./rpc/RpcContextMap.ts"
+export * as RpcMiddleware from "./rpc/RpcMiddleware.ts"

package/src/runtime.ts

@@ -0,0 +1,57 @@
+import * as Exit from "effect/Exit"
+import { flow } from "effect/Function"
+import * as Logger from "effect/Logger"
+import * as ManagedRuntime from "effect/ManagedRuntime"
+import { CauseException } from "./client/errors.ts"
+import { type Context } from "./Context.ts"
+import * as Effect from "./Effect.ts"
+import * as Layer from "./Layer.ts"
+
+export const makeAppRuntime = Effect.fnUntraced(function*<A, E>(layer: Layer.Layer<A, E>) {
+  const l = layer.pipe(
+    Layer.provide(Logger.layer([Logger.consolePretty()])),
+    Layer.orDie
+  )
+  const mrt = ManagedRuntime.make(l)
+  yield* mrt.contextEffect
+  return Object.assign(mrt, {
+    [Symbol.dispose]() {
+      return Effect.runSync(mrt.disposeEffect)
+    },
+
+    [Symbol.asyncDispose]() {
+      return mrt.dispose()
+    }
+  }) // as we initialise here, there is no more error left.
+})
+
+export function initializeSync<A, E>(layer: Layer.Layer<A, E>) {
+  const runtime = Effect.runSync(makeAppRuntime(layer))
+  return runtime
+}
+
+export function initializeAsync<A, E>(layer: Layer.Layer<A, E>) {
+  return Effect
+    .runPromise(makeAppRuntime(layer))
+}
+
+// we wrap into CauseException because we want to keep the full cause of the failure.
+export const makeRunPromise = <T>(services: Context<T>) =>
+  flow(Effect.runPromiseExitWith(services), (_) =>
+    _.then(
+      Exit.match({
+        onFailure: (cause) => Promise.reject(new CauseException(cause, "runPromise")),
+        onSuccess: (value) => Promise.resolve(value)
+      })
+    ))
+
+export const makeRunSync = <T>(services: Context<T>) =>
+  flow(
+    Effect.runSyncExitWith(services),
+    Exit.match({
+      onFailure: (cause) => {
+        throw new CauseException(cause, "runSync")
+      },
+      onSuccess: (value) => value
+    })
+  )

package/src/setupRequest.ts

@@ -0,0 +1,138 @@
+import { SqlClient } from "effect/sql"
+import * as Tracer from "effect/Tracer"
+import { DataDependencyRecorder } from "./DataDependencies.ts"
+import * as Effect from "./Effect.ts"
+import * as Layer from "./Layer.ts"
+import * as Option from "./Option.ts"
+import { LocaleRef, RequestContext, spanAttributes } from "./RequestContext.ts"
+import * as RequestScopedDependencies from "./RequestScopedDependencies.ts"
+import { NonEmptyString255 } from "./Schema.ts"
+import { ContextMapContainer, storeId } from "./Store.ts"
+
+const withSqlTransaction = <R, E, A>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
+  Effect.serviceOption(SqlClient.SqlClient).pipe(
+    Effect.flatMap(Option.match({
+      onNone: () => self,
+      onSome: (sql) => sql.withTransaction(self).pipe(Effect.orDie)
+    }))
+  )
+
+export const getRequestContext = Effect
+  .all({
+    span: Effect.currentSpan.pipe(Effect.orDie),
+    locale: LocaleRef,
+    namespace: storeId
+  })
+  .pipe(
+    Effect.map(({ locale, namespace, span }) =>
+      RequestContext.make({
+        span: Tracer.externalSpan(span),
+        locale,
+        namespace,
+        name: NonEmptyString255(span.name)
+      })
+    )
+  )
+
+export const getRC = Effect.all({
+  locale: LocaleRef,
+  namespace: storeId
+})
+
+const withRequestSpan = (name = "request", options?: Tracer.SpanOptions) => <R, E, A>(f: Effect.Effect<A, E, R>) =>
+  Effect.andThen(
+    getRC,
+    (ctx) =>
+      f.pipe(
+        Effect.withSpan(name, {
+          ...options,
+          attributes: { ...spanAttributes({ ...ctx, name: NonEmptyString255(name) }), ...options?.attributes }
+        }, {
+          captureStackTrace: options?.captureStackTrace ?? false
+        }),
+        // TODO: false
+        // request context info is picked up directly in the logger for annotations.
+        Effect.withLogSpan(name)
+      )
+  )
+
+export interface SetupRequestOptions {
+  readonly withTransaction?: boolean
+}
+
+export const requestStateLayer = RequestScopedDependencies.layer(ContextMapContainer, DataDependencyRecorder)
+
+// Build `layer` against the ambient (request) scope rather than a sub-scope of the
+// returned Effect. Required when the returned value is a streaming HttpServerResponse:
+// the response body keeps producing chunks (and using layer-provided state) after the
+// Effect returns, so a sub-scope would close too early and run finalizers mid-stream.
+export const provideOnRequestScope =
+  <ROut, E2, RIn>(layer: Layer.Layer<ROut, E2, RIn>) => <A, E, R>(self: Effect.Effect<A, E, R>) =>
+    Effect.gen(function*() {
+      const requestScope = yield* Effect.scope
+      // Fresh MemoMap per request: `Layer.buildWithScope` would otherwise reuse
+      // the ambient MemoMap living on the HTTP server fiber, sharing the built
+      // value (e.g. ContextMap) across every request handled by that server.
+      const memoMap = yield* Layer.makeMemoMap
+      const ctx = yield* Layer.buildWithMemoMap(layer, memoMap, requestScope)
+      return yield* Effect.provide(self, ctx)
+    })
+
+export const setupRequestContextFromCurrent =
+  (name = "request", options?: Tracer.SpanOptions & SetupRequestOptions) => <R, E, A>(self: Effect.Effect<A, E, R>) =>
+    self
+      .pipe(
+        options?.withTransaction === true ? withSqlTransaction : (_) => _,
+        withRequestSpan(name, options),
+        Effect.provide(requestStateLayer, { local: true })
+      )
+
+// Streaming variant: binds ContextMapContainer to the ambient (request) scope so its
+// finalizer (clear()) runs only after the response body is fully drained, not when the
+// outer Effect returns its HttpServerResponse value. Use for handlers that return a
+// streaming HttpServerResponse (e.g. SSE) — see RequestContextMiddleware for context.
+export const setupStreamingRequestContextFromCurrent =
+  (name = "request", options?: Tracer.SpanOptions & SetupRequestOptions) => <R, E, A>(self: Effect.Effect<A, E, R>) =>
+    self.pipe(
+      options?.withTransaction === true ? withSqlTransaction : (_) => _,
+      withRequestSpan(name, options),
+      provideOnRequestScope(requestStateLayer)
+    )
+
+// TODO: consider integrating Effect.withParentSpan
+export function setupRequestContext<R, E, A>(
+  self: Effect.Effect<A, E, R>,
+  requestContext: RequestContext,
+  options?: SetupRequestOptions
+) {
+  const layer = Layer.mergeAll(
+    requestStateLayer,
+    Layer.succeed(LocaleRef, requestContext.locale),
+    Layer.succeed(storeId, requestContext.namespace)
+  )
+  return self
+    .pipe(
+      options?.withTransaction === true ? withSqlTransaction : (_) => _,
+      withRequestSpan(requestContext.name),
+      Effect.provide(layer, { local: true })
+    )
+}
+
+export function setupRequestContextWithCustomSpan<R, E, A>(
+  self: Effect.Effect<A, E, R>,
+  requestContext: RequestContext,
+  name: string,
+  options?: Tracer.SpanOptions & SetupRequestOptions
+) {
+  const layer = Layer.mergeAll(
+    requestStateLayer,
+    Layer.succeed(LocaleRef, requestContext.locale),
+    Layer.succeed(storeId, requestContext.namespace)
+  )
+  return self
+    .pipe(
+      options?.withTransaction === true ? withSqlTransaction : (_) => _,
+      withRequestSpan(name, options),
+      Effect.provide(layer, { local: true })
+    )
+}

package/src/toast.ts

@@ -0,0 +1,54 @@
+import * as Context from "./Context.ts"
+import { accessEffectFn } from "./Context.ts"
+import * as Effect from "./Effect.ts"
+import * as Option from "./Option.ts"
+
+export type ToastId = string | number
+export type ToastOpts = { id?: ToastId; timeout?: number; groupId?: string; requestId?: string }
+export type ToastOptsInternal = { id?: ToastId | null; timeout?: number; groupId?: string; requestId?: string }
+
+export type UseToast = () => {
+  error: (this: void, message: string, options?: ToastOpts) => ToastId
+  warning: (this: void, message: string, options?: ToastOpts) => ToastId
+  success: (this: void, message: string, options?: ToastOpts) => ToastId
+  info: (this: void, message: string, options?: ToastOpts) => ToastId
+  dismiss: (this: void, id: ToastId) => void
+}
+
+export class CurrentToastId extends Context.Opaque<CurrentToastId, { toastId: ToastId }>()("CurrentToastId") {}
+
+/** fallback to CurrentToastId when available unless id is explicitly set to a value or null */
+export const wrap = (toast: ReturnType<UseToast>) => {
+  const wrap = (toastHandler: (message: string, options?: ToastOpts) => ToastId) => {
+    return (message: string, options?: ToastOptsInternal) =>
+      Effect.serviceOption(CurrentToastId).pipe(
+        Effect.flatMap((currentToast) =>
+          Effect.sync(() => {
+            const { id: _id, ...rest } = options ?? {}
+            const id = _id !== undefined
+              ? _id ?? undefined
+              : Option.getOrUndefined(Option.map(currentToast, (_) => _.toastId))
+            // when id is undefined, we may end up with no toast at all..
+            return toastHandler(message, id !== undefined ? { ...rest, id } : rest)
+          })
+        )
+      )
+  }
+  return {
+    error: wrap(toast.error),
+    info: wrap(toast.info),
+    success: wrap(toast.success),
+    warning: wrap(toast.warning),
+    dismiss: (toastId: ToastId) => Effect.sync(() => toast.dismiss(toastId))
+  }
+}
+
+type ToastShape = ReturnType<typeof wrap>
+
+export class Toast extends Context.Opaque<Toast, ToastShape>()("Toast") {
+  static readonly error = accessEffectFn(this, "error")
+  static readonly info = accessEffectFn(this, "info")
+  static readonly success = accessEffectFn(this, "success")
+  static readonly warning = accessEffectFn(this, "warning")
+  static readonly dismiss = accessEffectFn(this, "dismiss")
+}