effect-app 4.0.0-beta.26 → 4.0.0-beta.261

package/src/client.ts

@@ -1,6 +1,7 @@
 // codegen:start {preset: barrel, include: ./client/*.ts}
-export * from "./client/apiClientFactory.js"
-export * from "./client/clientFor.js"
-export * from "./client/errors.js"
-export * from "./client/makeClient.js"
+export * from "./client/apiClientFactory.ts"
+export * from "./client/clientFor.ts"
+export * from "./client/errors.ts"
+export * from "./client/InvalidationKeys.ts"
+export * from "./client/makeClient.ts"
 // codegen:end

package/src/http/Request.ts

@@ -1,4 +1,4 @@
-import { Option } from "effect"
+import * as Option from "effect/Option"
 import type { HttpClientResponse } from "effect/unstable/http/HttpClientResponse"
 import * as Effect from "../Effect.js"
 import { HttpClient, HttpClientError, HttpClientRequest, HttpHeaders } from "./internal/lib.js"

package/src/ids.ts

@@ -1,7 +1,8 @@
 import { brandedStringId, type Codec, NonEmptyString255, StringId, type StringIdBrand, withDefaultMake } from "effect-app/Schema"
 import type { B } from "effect-app/Schema/schema"
+import * as Effect from "effect/Effect"
 import type { Simplify } from "effect/Types"
-import { S } from "./index.js"
+import * as S from "./Schema.js"
 import { extendM } from "./utils.js"
 
 export interface RequestIdBrand extends StringIdBrand {
@@ -9,20 +10,46 @@ export interface RequestIdBrand extends StringIdBrand {
 }
 
 export type RequestId = NonEmptyString255
-// a request id may be made from a span id, which does not comply with StringId schema.
+/**
+ * Schema for a request id.
+ *
+ * A request id may be made from a span id, which does not comply with the
+ * `StringId` schema (hence the looser `NonEmptyString255` base).
+ *
+ * `.withConstructorDefault` => fresh `StringId` (construction-only; not
+ * applied during decode — cannot be used to JIT-migrate database fields).
+ * See `./Schema/ext.ts` for the full policy note.
+ */
 export const RequestId = extendM(
   Object
     .assign(Object.create(NonEmptyString255) as {}, NonEmptyString255 as unknown as Codec<NonEmptyString255, string>),
   (s) => {
-    const make = StringId.make as () => NonEmptyString255
+    function make(): NonEmptyString255
+    function make(input: string, options?: S.MakeOptions): NonEmptyString255
+    function make(input?: string, options?: S.MakeOptions): NonEmptyString255 {
+      const id = input === undefined ? StringId.make() : StringId.make(input, options)
+      return id as NonEmptyString255
+    }
     return ({
       make,
-      withDefault: s.pipe(S.withDefaultConstructor(make))
+      /**
+       * Construction-only default: fresh `StringId`. Applied only when the
+       * field is omitted from `.make(...)` input. NOT applied during decode —
+       * cannot be used to JIT-migrate database fields. See `./Schema/ext.ts`
+       * file-level note.
+       */
+      withConstructorDefault: S.withConstructorDefault(Effect.sync(make))(s as typeof s & S.WithoutConstructorDefault)
     })
   }
 )
   .pipe(withDefaultMake)
 
 export interface UserProfileIdBrand extends Simplify<B.Brand<"UserProfileId"> & StringIdBrand> {}
-export type UserProfileId = StringId & UserProfileIdBrand
+export type UserProfileId = string & UserProfileIdBrand
+/**
+ * Branded `StringId` for user profiles.
+ *
+ * Exposes `.withConstructorDefault` (fresh id) — construction-only; not
+ * applied during decode. See `./Schema/ext.ts` for the full policy note.
+ */
 export const UserProfileId = brandedStringId<UserProfileId>()

package/src/index.ts

@@ -1,23 +1,19 @@
+// eslint-disable-next-line import/no-unassigned-import
 import "./builtin.js"
 
-import * as ServiceMap from "./ServiceMap.js"
-
 export * as Fnc from "./Function.js"
 export * as Utils from "./utils.js"
 
 export * as Array from "./Array.js"
+export * as Config from "./Config.js"
+export * as ConfigProvider from "./ConfigProvider.js"
+export * as Context from "./Context.js"
 export * as Effect from "./Effect.js"
 export * as Layer from "./Layer.js"
+export * as Model from "./Model.js"
 export * as NonEmptySet from "./NonEmptySet.js"
-export * as ServiceMap from "./ServiceMap.js"
 export * as Set from "./Set.js"
-
-export {
-  /**
-   * @deprecated use ServiceMap directly instead
-   */
-  ServiceMap as Context
-}
+export * as Store from "./Store.js"
 
 export { type NonEmptyArray, type NonEmptyReadonlyArray } from "./Array.js"
 
@@ -26,5 +22,6 @@ export * from "effect"
 export type * as Types from "./Types.js"
 
 export * as SecretURL from "./Config/SecretURL.js"
+export * as RpcX from "./rpc.js"
 export * as S from "./Schema.js"
 export { copy } from "./utils.js"

package/src/middleware.ts

@@ -1,21 +1,25 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { ServiceMap } from "effect-app"
-import { RpcX } from "./rpc.js"
+import * as Context from "effect-app/Context"
+import { RpcMiddleware } from "./rpc.js"
 
-export class DevMode extends ServiceMap.Reference("DevMode", { defaultValue: () => false }) {}
+export class DevMode extends Context.Reference("DevMode", { defaultValue: () => false }) {}
 
-export class RequestCacheMiddleware
-  extends RpcX.RpcMiddleware.Tag<RequestCacheMiddleware>()("RequestCacheMiddleware")
-{}
+export class RequestCacheMiddleware extends RpcMiddleware.Tag<RequestCacheMiddleware>()("RequestCacheMiddleware") {}
 
 export class ConfigureInterruptibilityMiddleware
-  extends RpcX.RpcMiddleware.Tag<ConfigureInterruptibilityMiddleware>()("ConfigureInterruptibilityMiddleware")
+  extends RpcMiddleware.Tag<ConfigureInterruptibilityMiddleware>()("ConfigureInterruptibilityMiddleware")
 {}
 
-export class LoggerMiddleware extends RpcX.RpcMiddleware.Tag<LoggerMiddleware>()("LoggerMiddleware") {}
+export class LoggerMiddleware extends RpcMiddleware.Tag<LoggerMiddleware>()("LoggerMiddleware") {}
 
-export class DevModeMiddleware extends RpcX.RpcMiddleware.Tag<DevModeMiddleware>()("DevModeMiddleware") {}
+export class DevModeMiddleware extends RpcMiddleware.Tag<DevModeMiddleware>()("DevModeMiddleware") {}
 
+/**
+ * Generic middlewares attached by `makeRouter` to every request.
+ *
+ * Invalidation key wrap/unwrap is handled by the routing layer (server) and the
+ * api client factory (client) directly — there is no middleware tag for it.
+ */
 export const DefaultGenericMiddlewares = [
   RequestCacheMiddleware,
   ConfigureInterruptibilityMiddleware,

package/src/rpc/Invalidation.ts

@@ -0,0 +1,261 @@
+import * as Ref from "effect/Ref"
+import { Rpc } from "effect/unstable/rpc"
+import { type ClientForOptions, makeQueryKey } from "../client/clientFor.js"
+import * as Context from "../Context.js"
+import * as Effect from "../Effect.js"
+import * as S from "../Schema.js"
+
+/**
+ * Shorthand for a handler-derived invalidation key.
+ * Accepts an RPC handler object so `add(GetMe)` is equivalent to
+ * `add(makeQueryKey(GetMe))`.
+ */
+export type InvalidationKeyInput = InvalidationKey | { readonly id: string; readonly options?: ClientForOptions }
+
+const normalizeKey = (input: InvalidationKeyInput): InvalidationKey => {
+  if (Array.isArray(input)) return input
+  const handler = input as { id: string; options?: ClientForOptions }
+  return makeQueryKey(handler.options ? { id: handler.id, options: handler.options } : { id: handler.id })
+}
+
+// Disambiguates `add` overloads: a `string[]` means a single key; an array
+// containing arrays-or-objects means a batch of inputs.
+const isBatch = (
+  input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>
+): input is ReadonlyArray<InvalidationKeyInput> =>
+  Array.isArray(input) && input.length > 0 && typeof input[0] !== "string"
+
+const normalizeInputs = (
+  input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>
+): ReadonlyArray<InvalidationKey> => isBatch(input) ? input.map(normalizeKey) : [normalizeKey(input)]
+
+/**
+ * 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
+export type InvalidationKeySegment = S.Schema.Type<typeof InvalidationKeySegment>
+
+/** Schema for a single invalidation key – an array of segments compatible with TanStack Query `queryKey`. */
+export const InvalidationKey = S.Array(InvalidationKeySegment)
+export type InvalidationKey = S.Schema.Type<typeof InvalidationKey>
+
+/** Schema for the full set of invalidation keys – an array of `InvalidationKey`. */
+export const InvalidationKeys = S.Array(InvalidationKey)
+export type InvalidationKeys = S.Schema.Type<typeof InvalidationKeys>
+
+/** Metadata included in every command response for server-driven cache invalidation. */
+export const CommandMetaData = S.Struct({ invalidateQueries: InvalidationKeys })
+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 const CommandResponseWithMetaData = <S extends S.Top>(success: S) =>
+  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 = <E extends S.Top>(error: E) =>
+  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 = <S extends S.Top>(success: S) =>
+  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 })
+  ])
+
+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 const StreamFailureChunk = <E extends S.Top>(error: E) =>
+  S.Struct({ _tag: S.Literal("error"), error, metadata: CommandMetaData })
+
+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 const Invalidates = Context.Reference<ReadonlyArray<InvalidationKey>>(
+  "effect-app/rpc/Invalidates",
+  { defaultValue: () => [] }
+)
+export type Invalidates = typeof Invalidates
+
+/** The shape of the per-request service that accumulates invalidation keys. */
+export interface InvalidationSetService {
+  readonly add: (
+    input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>
+  ) => 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.add(key)` as a shorthand to skip `.use(_ => _.add(key))`. The
+ * underlying service is still available via `.use` / `.useSync` for advanced cases.
+ *
+ * `add` accepts an RPC handler directly (e.g. `UserRsc.GetMe`) — its query key is derived via
+ * `makeQueryKey` so keys stay in sync with the actual query definitions. Raw `InvalidationKey`
+ * arrays and arrays of either form are also accepted.
+ *
+ * ```ts
+ * import * as Effect from "effect/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)
+ *
+ *   // single handler
+ *   yield* Invalidation.InvalidationSet.add(UserRsc.GetMe)
+ *
+ *   // batch
+ *   if (cart.isCheckedOut) {
+ *     yield* Invalidation.InvalidationSet.add([CartRsc.GetCartStats, UserRsc.GetMe])
+ *   }
+ *
+ *   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.
+ */
+const InvalidationSetRef = Context.Reference<InvalidationSetService>(
+  "effect-app/rpc/InvalidationSet",
+  {
+    defaultValue: () => ({
+      add: (_input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>) => Effect.void,
+      get: Effect.succeed([] as ReadonlyArray<InvalidationKey>),
+      drain: Effect.succeed([] as ReadonlyArray<InvalidationKey>)
+    })
+  }
+)
+export const InvalidationSet = Object.assign(InvalidationSetRef, {
+  /**
+   * Shortcut for `InvalidationSet.use(_ => _.add(input))`. Accepts a single
+   * `InvalidationKeyInput` or an array of them.
+   */
+  add: (input: InvalidationKeyInput | ReadonlyArray<InvalidationKeyInput>) =>
+    InvalidationSetRef.use((_) => _.add(input))
+})
+export type InvalidationSet = typeof InvalidationSetRef
+
+/** Creates a fresh `InvalidationSet` implementation backed by a `Ref`. */
+export const makeInvalidationSet = (ref: Ref.Ref<ReadonlyArray<InvalidationKey>>): InvalidationSetService => ({
+  add: (input) => Ref.update(ref, (keys) => [...keys, ...normalizeInputs(input)]),
+  get: Ref.get(ref),
+  drain: Ref.getAndSet(ref, [])
+})
+
+/**
+ * `Rpc.Custom` definition for command RPCs that wrap the success/error schemas
+ * with `CommandResponseWithMetaData` / `CommandFailureWithMetaData`. The wrap
+ * lets server forward accumulated invalidation keys on both success and
+ * handler-thrown failure paths. Middleware-thrown errors bypass the wrap
+ * (the handler never ran, so no metadata) and flow raw at the Cause level —
+ * the client decodes them via the `rpc.middlewares[*].error` failure-union
+ * channel of `Rpc.exitSchema`.
+ */
+// eslint-disable-next-line import/namespace
+export interface CommandRpc extends Rpc.Custom {
+  readonly out: Rpc.Custom.Out<
+    ReturnType<typeof CommandResponseWithMetaData<this["success"] & S.Top>>,
+    ReturnType<typeof CommandFailureWithMetaData<this["error"] & S.Top>>
+  >
+}
+
+/**
+ * Custom Rpc constructor for command RPCs.
+ * Wraps the success schema with `CommandResponseWithMetaData` and the error
+ * schema with `CommandFailureWithMetaData`.
+ */
+export const makeCommandRpc = Rpc.custom<CommandRpc>(({ defect, error, success }) => ({
+  success: CommandResponseWithMetaData(success),
+  error: CommandFailureWithMetaData(error),
+  defect
+}))
+
+/**
+ * `Rpc.Custom` definition for stream RPCs that wrap the success/error schemas
+ * with `StreamResponseChunk` / `StreamFailureChunk`.
+ */
+// eslint-disable-next-line import/namespace
+export interface StreamRpc extends Rpc.Custom {
+  readonly out: Rpc.Custom.Out<
+    ReturnType<typeof StreamResponseChunk<this["success"] & S.Top>>,
+    ReturnType<typeof StreamFailureChunk<this["error"] & S.Top>>
+  >
+}
+
+/**
+ * Custom Rpc constructor for stream RPCs.
+ * Wraps the success schema with `StreamResponseChunk` and
+ * the error schema with `StreamFailureChunk`.
+ */
+export const makeStreamRpc = Rpc.custom<StreamRpc>(({ defect, error, success }) => ({
+  success: StreamResponseChunk(success),
+  error: StreamFailureChunk(error),
+  defect
+}))