effect-app 4.0.0-beta.2 → 4.0.0-beta.200

package/src/Schema.ts

@@ -1,22 +1,22 @@
-import { Array, Option, pipe, SchemaAST, type Tracer } from "effect"
+import { SchemaAST, type Tracer } from "effect"
 import * as S from "effect/Schema"
+import { type Simplify } from "effect/Struct"
+import type { RequiredKeys } from "effect/Types"
 import type { NonEmptyReadonlyArray } from "./Array.js"
 import { fakerArb } from "./faker.js"
-import { Email as EmailT } from "./Schema/email.js"
-import { withDefaultMake } from "./Schema/ext.js"
-import { PhoneNumber as PhoneNumberT } from "./Schema/phoneNumber.js"
-import type { AST } from "./Schema/schema.js"
-import { extendM } from "./utils.js"
+import { Email as EmailT, type Email as EmailType } from "./Schema/email.js"
+import { concurrencyUnbounded, withDefaultMake, withDefaultParseOptions } from "./Schema/ext.js"
+import { PhoneNumber as PhoneNumberT, type PhoneNumber as PhoneNumberType } from "./Schema/phoneNumber.js"
+import { type AST } from "./Schema/schema.js"
+import { copy, extendM, type StructuralCopyOrigin } from "./utils.js"
 
 export * from "effect/Schema"
-// v4: TaggedError renamed to TaggedErrorClass
-export { TaggedErrorClass as TaggedError } from "effect/Schema"
 
 export * from "./Schema/Class.js"
-export { Class, TaggedClass } from "./Schema/Class.js"
+export { Class, ErrorClass, Opaque, TaggedClass, TaggedErrorClass } from "./Schema/Class.js"
 
 export { fromBrand, nominal } from "./Schema/brand.js"
-export { Array, Boolean, Date, Literal, Map, NullOr, Number, ReadonlyMap, ReadonlySet } from "./Schema/ext.js"
+export { Array, Boolean, Date, DateFromString, DateValid, Finite, Literals, NullOr, Number, ReadonlyMap, ReadonlySet } from "./Schema/ext.js"
 export { Int, NonNegativeInt } from "./Schema/numbers.js"
 
 export * from "./Schema/email.js"
@@ -25,14 +25,217 @@ export * from "./Schema/moreStrings.js"
 export * from "./Schema/numbers.js"
 export * from "./Schema/phoneNumber.js"
 export * from "./Schema/schema.js"
+export * from "./Schema/SpecialJsonSchema.js"
+export * from "./Schema/SpecialOpenApi.js"
 export * from "./Schema/strings.js"
 export { NonEmptyString } from "./Schema/strings.js"
 
 export * as SchemaIssue from "effect/SchemaIssue"
-export * as SchemaParser from "effect/SchemaParser"
+
+export const decodeEffectConcurrently: typeof S.decodeEffect = withDefaultParseOptions(S.decodeEffect)
+export const decodeUnknownEffectConcurrently: typeof S.decodeUnknownEffect = withDefaultParseOptions(
+  S.decodeUnknownEffect
+)
+export * as SchemaParser from "./Schema/SchemaParser.js"
 
 export { Void as Void_ } from "effect/Schema"
 
+// ---------------------------------------------------------------------------
+// Struct / NonEmptyArray / Record
+// ---------------------------------------------------------------------------
+
+export function Struct<const Fields extends S.Struct.Fields>(
+  fields: Fields
+): Struct<Fields> {
+  const result = S.Struct(fields).annotate(concurrencyUnbounded)
+  const allowVoidMake = (schema: any): any => {
+    // Normalize omitted input to an empty object so optional/default-only structs can be constructed with make().
+    const origMake: any = schema.make
+    const origMakeOption: any = schema.makeOption
+    const origMakeEffect: any = schema.makeEffect
+    schema.make = function(this: any, input: any, options?: any) {
+      return origMake.call(this, input === undefined ? {} : input, options)
+    }
+    schema.makeOption = function(this: any, input: any, options?: any) {
+      return origMakeOption.call(this, input === undefined ? {} : input, options)
+    }
+    schema.makeEffect = function(this: any, input: any, options?: any) {
+      return origMakeEffect.call(this, input === undefined ? {} : input, options)
+    }
+    return schema
+  }
+  // eslint-disable-next-line @typescript-eslint/unbound-method, @typescript-eslint/no-unsafe-assignment
+  const origMapFields: any = result.mapFields
+  // eslint-disable-next-line @typescript-eslint/unbound-method, @typescript-eslint/no-unsafe-assignment
+  const origAnnotate: any = result.annotate
+  // eslint-disable-next-line @typescript-eslint/unbound-method, @typescript-eslint/no-unsafe-assignment
+  const origAnnotateKey: any = result.annotateKey
+
+  const preserveCopyAndMethods = (schema: any): any => {
+    schema.copy = copy
+    schema.mapFields = function(this: any, f: any, options?: any) {
+      return (result as any).mapFields.call(this, f, options)
+    }
+    schema.annotate = function(this: any, annotations?: any) {
+      return (result as any).annotate.call(this, annotations)
+    }
+    schema.annotateKey = function(this: any, annotations?: any) {
+      return (result as any).annotateKey.call(this, annotations)
+    }
+    return allowVoidMake(schema)
+  }
+  ;(result as any).mapFields = function(this: any, f: any, options?: any) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    const mapped = origMapFields.call(this, f, options).annotate(concurrencyUnbounded)
+    return preserveCopyAndMethods(mapped)
+  }
+  ;(result as any).annotate = function(this: any, annotations?: any) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    const annotated = origAnnotate.call(this, annotations)
+    return preserveCopyAndMethods(annotated)
+  }
+  ;(result as any).annotateKey = function(this: any, annotations?: any) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+    const annotated = origAnnotateKey.call(this, annotations)
+    return preserveCopyAndMethods(annotated)
+  }
+  ;(result as any).copy = copy
+  allowVoidMake(result)
+  return result as Struct<Fields>
+}
+
+export interface Struct<Fields extends S.Struct.Fields> extends
+  S.Bottom<
+    Struct.Type<Fields>,
+    Struct.Encoded<Fields>,
+    Struct.DecodingServices<Fields>,
+    Struct.EncodingServices<Fields>,
+    AST.Objects,
+    // Rebuild is what's returned from annotate etc
+    Struct<Fields>,
+    Struct.MakeIn<Fields>,
+    Struct.Iso<Fields>
+  >
+{
+  /**
+   * The field definitions of this struct. Spread them into a new struct to
+   * reuse fields across schemas.
+   *
+   * **Example** (Reusing fields across structs)
+   *
+   * ```ts
+   * import { Schema } from "effect"
+   *
+   * const Timestamped = Schema.Struct({
+   *   createdAt: Schema.Date,
+   *   updatedAt: Schema.Date
+   * })
+   *
+   * const User = Schema.Struct({
+   *   ...Timestamped.fields,
+   *   name: Schema.String,
+   *   email: Schema.String
+   * })
+   * ```
+   */
+  readonly fields: Fields
+  /**
+   * Returns a new struct with the fields modified by the provided function.
+   *
+   * **Options**
+   *
+   * - `unsafePreserveChecks` - if `true`, keep any `.check(...)` constraints
+   *   that were attached to the original union. Defaults to `false`.
+   *
+   *   **Warning**: This is an unsafe operation. Since `mapFields`
+   *   transformations change the schema type, the original refinement functions
+   *   may no longer be valid or safe to apply to the transformed schema. Only
+   *   use this option if you have verified that your refinements remain correct
+   *   after the transformation.
+   */
+  mapFields<To extends Struct.Fields>(
+    f: (fields: Fields) => To,
+    options?: {
+      readonly unsafePreserveChecks?: boolean | undefined
+    } | undefined
+  ): Struct<Simplify<Readonly<To>>>
+
+  // added copy
+  readonly copy: StructuralCopyOrigin<Struct.Type<Fields>>
+}
+
+export declare namespace Struct {
+  export type Fields = S.Struct.Fields
+  export type Type<F extends S.Struct.Fields> = S.Struct.Type<F>
+  export type Encoded<F extends S.Struct.Fields> = S.Struct.Encoded<F>
+  export type DecodingServices<F extends S.Struct.Fields> = S.Struct.DecodingServices<F>
+  export type EncodingServices<F extends S.Struct.Fields> = S.Struct.EncodingServices<F>
+  // changed; all optional allows void
+  export type MakeIn<F extends S.Struct.Fields> = RequiredKeys<S.Struct.MakeIn<F>> extends never
+    ? void | S.Struct.MakeIn<F>
+    : S.Struct.MakeIn<F>
+  export type Iso<F extends S.Struct.Fields> = S.Struct.Iso<F>
+}
+
+export type StructNestedEncodedError<T> = {
+  readonly _tag: "StructNestedEncodedError"
+  readonly message: "Expected a Struct schema or a schema with from.Encoded"
+  readonly schema: T
+}
+
+export type StructNestedEncoded<T> = T extends { fields: infer Fields extends S.Struct.Fields } ? Struct.Encoded<Fields>
+  : T extends { readonly from: { readonly Encoded: infer Encoded } } ? Encoded
+  : StructNestedEncodedError<T>
+
+export function NonEmptyArray<Value extends S.Top>(value: Value): S.NonEmptyArray<Value> {
+  return S.NonEmptyArray(value).annotate(concurrencyUnbounded)
+}
+
+export function TaggedStruct<const Tag extends SchemaAST.LiteralValue, const Fields extends S.Struct.Fields>(
+  value: Tag,
+  fields: Fields
+): TaggedStruct<Tag, Fields> {
+  return Struct({ _tag: S.tag(value), ...fields }) as any
+}
+export interface TaggedStruct<Tag extends SchemaAST.LiteralValue, Fields extends S.Struct.Fields>
+  extends Struct<{ readonly _tag: S.tag<Tag> } & Fields>
+{}
+export declare namespace TaggedStruct {
+  export type Fields = S.Struct.Fields
+  export type Type<Tag extends SchemaAST.LiteralValue, F extends S.Struct.Fields> = S.Struct.Type<
+    { readonly _tag: S.tag<Tag> } & F
+  >
+  export type Encoded<Tag extends SchemaAST.LiteralValue, F extends S.Struct.Fields> = S.Struct.Encoded<
+    { readonly _tag: S.tag<Tag> } & F
+  >
+  export type DecodingServices<Tag extends SchemaAST.LiteralValue, F extends S.Struct.Fields> =
+    S.Struct.DecodingServices<
+      { readonly _tag: S.tag<Tag> } & F
+    >
+  export type EncodingServices<Tag extends SchemaAST.LiteralValue, F extends S.Struct.Fields> =
+    S.Struct.EncodingServices<
+      { readonly _tag: S.tag<Tag> } & F
+    >
+  export type MakeIn<Tag extends SchemaAST.LiteralValue, F extends S.Struct.Fields> = S.Struct.MakeIn<
+    { readonly _tag: S.tag<Tag> } & F
+  >
+  export type Iso<Tag extends SchemaAST.LiteralValue, F extends S.Struct.Fields> = S.Struct.Iso<
+    { readonly _tag: S.tag<Tag> } & F
+  >
+}
+
+export function Record<Key extends S.Record.Key, Value extends S.Top>(
+  key: Key,
+  value: Value
+): S.$Record<Key, Value> {
+  return S.Record(key, value).annotate(concurrencyUnbounded)
+}
+export declare namespace Record {
+  export type Key = S.Record.Key
+  export type Type<K extends S.Record.Key, V extends S.Top> = S.Record.Type<K, V>
+  export type Encoded<K extends S.Record.Key, V extends S.Top> = S.Record.Encoded<K, V>
+}
+
 export const SpanId = Symbol()
 export type SpanId = typeof SpanId
 
@@ -40,127 +243,167 @@ export interface WithOptionalSpan {
   [SpanId]?: Tracer.Span
 }
 
+const makeEmail = S.decodeSync(EmailT as any) as (value: string) => EmailType
+const makePhoneNumber = S.decodeSync(PhoneNumberT as any) as (value: string) => PhoneNumberType
+
 export const Email = EmailT
   .pipe(
     S.annotate({
       // eslint-disable-next-line @typescript-eslint/unbound-method
-      arbitrary: (): any => (fc: any) => fakerArb((faker) => faker.internet.exampleEmail)(fc).map(Email)
+      toArbitrary: () => (fc) => fakerArb((faker) => faker.internet.exampleEmail)(fc).map(makeEmail)
     }),
     withDefaultMake
   )
 
-export type Email = EmailT
+export type Email = EmailType
 
 export const PhoneNumber = PhoneNumberT
   .pipe(
     S.annotate({
-      arbitrary: (): any => (fc: any) =>
+      toArbitrary: () => (fc) =>
         // eslint-disable-next-line @typescript-eslint/unbound-method
-        fakerArb((faker) => faker.phone.number)(fc).map(PhoneNumber)
+        fakerArb((faker) => faker.phone.number)(fc).map(makePhoneNumber)
     }),
     withDefaultMake
   )
 
-export const makeIs = <A extends { _tag: string }, I, R>(
-  schema: S.Codec<A, I, R>
-) => {
-  // In v4, transformations are stored as encoding on nodes, not as wrapper nodes.
-  // Union member ASTs are directly Objects (TypeLiteral equivalent).
-  if (SchemaAST.isUnion(schema.ast)) {
-    return schema.ast.types.reduce((acc: any, t: AST.AST) => {
-      if (!SchemaAST.isObjects(t)) return acc
-      const tag = Array.findFirst(t.propertySignatures, (_: any) => {
-        if (_.name === "_tag" && SchemaAST.isLiteral(_.type)) {
-          return Option.some(_.type)
-        }
-        return Option.none()
-      })
-      const ast = Option.getOrUndefined(tag)
-      if (!ast) {
-        return acc
-      }
-      return {
-        ...acc,
-        [String((ast as SchemaAST.Literal).literal)]: (x: { _tag: string }) =>
-          x._tag === (ast as SchemaAST.Literal).literal
-      }
-    }, {} as Is<A>)
-  }
-  throw new Error("Unsupported")
-}
+export type PhoneNumber = PhoneNumberType
 
-export const makeIsAnyOf = <A extends { _tag: string }, I, R>(
-  schema: S.Codec<A, I, R>
-): IsAny<A> => {
-  if (SchemaAST.isUnion(schema.ast)) {
-    return <Keys extends A["_tag"][]>(...keys: Keys) => (a: A): a is ExtractUnion<A, ElemType<Keys>> =>
-      keys.includes(a._tag)
-  }
-  throw new Error("Unsupported")
+// Copied from SchemaAST.collectSentinels (marked @internal in effect).
+// Returns all { key, literal } pairs that can discriminate a union member.
+const getTagFromAST = (schema: S.Top): string => {
+  const sentinels = collectSentinelsFromAST(schema.ast)
+  const sentinel = sentinels.find((s) => s.key === "_tag")
+  if (sentinel !== undefined && typeof sentinel.literal === "string") return sentinel.literal
+  throw new Error("No _tag literal found on schema member")
 }
 
-export type ExtractUnion<A extends { _tag: string }, Tags extends A["_tag"]> = Extract<A, Record<"_tag", Tags>>
-export type Is<A extends { _tag: string }> = { [K in A as K["_tag"]]: (a: A) => a is K }
-export type ElemType<A> = A extends Array<infer E> ? E : never
-export interface IsAny<A extends { _tag: string }> {
-  <Keys extends A["_tag"][]>(...keys: Keys): (a: A) => a is ExtractUnion<A, ElemType<Keys>>
+function collectSentinelsFromAST(
+  ast: SchemaAST.AST
+): Array<{ key: PropertyKey; literal: SchemaAST.LiteralValue | symbol }> {
+  switch (ast._tag) {
+    case "Declaration": {
+      const s = ast.annotations?.["~sentinels"]
+      return Array.isArray(s) ? s : []
+    }
+    case "Objects":
+      return ast.propertySignatures.flatMap(
+        (ps): Array<{ key: PropertyKey; literal: SchemaAST.LiteralValue | symbol }> => {
+          const type = ps.type
+          if (!SchemaAST.isOptional(type)) {
+            if (SchemaAST.isLiteral(type)) return [{ key: ps.name, literal: type.literal }]
+            if (SchemaAST.isUniqueSymbol(type)) return [{ key: ps.name, literal: type.symbol }]
+          }
+          return []
+        }
+      )
+    case "Suspend":
+      return collectSentinelsFromAST(ast.thunk())
+    default:
+      return []
+  }
 }
 
-export const taggedUnionMap = <
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Members extends readonly (S.Top & { fields: { _tag: S.tag<string> } })[]
->(
-  self: Members
-) =>
-  self.reduce((acc, key) => {
-    // TODO: v4 migration — PropertySignatureDeclaration removed, need v4 AST traversal
-    const ast = key.fields._tag.ast as any
-    const tag = ((ast.type ?? ast) as SchemaAST.Literal).literal as string // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
-    ;(acc as any)[tag] = key as any
-    return acc
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  }, {} as any)
-
 export const tags = <
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Members extends NonEmptyReadonlyArray<(S.Top & { fields: { _tag: S.tag<string> } })>
+  Members extends NonEmptyReadonlyArray<(S.Top & { readonly Type: { readonly _tag: string } })>
 >(
   self: Members
 ) =>
-  S.Literals(self.map((key) => {
-    // TODO: v4 migration — PropertySignatureDeclaration removed, need v4 AST traversal
-    const ast = key.fields._tag.ast as any
-    const tag = ((ast.type ?? ast) as SchemaAST.Literal).literal
-    return tag
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  })) as any
-
-export const ExtendTaggedUnion = <A extends { _tag: string }, I, R>(
-  schema: S.Codec<A, I, R>
-) =>
-  extendM(
-    schema,
-    (_) => ({
-      is: S.is(schema as any),
-      isA: makeIs(_ as any),
-      isAnyOf: makeIsAnyOf(_ as any) /*, map: taggedUnionMap(a) */
-    })
-  )
+  S.Literals(
+    self.map(getTagFromAST) as {
+      [Index in keyof Members]: Members[Index]["Type"]["_tag"]
+    }
+  ) as S.Literals<
+    {
+      [Index in keyof Members]: Members[Index]["Type"]["_tag"]
+    }
+  >
 
-export const TaggedUnion = <
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Members extends readonly (S.Top & { fields: { _tag: S.tag<any> } })[]
->(...a: Members) =>
-  pipe(
-    S.Union(a),
-    (_) =>
-      extendM(_, (_) => ({
-        is: S.is(_ as any),
-        isA: makeIs(_ as any),
-        isAnyOf: makeIsAnyOf(_ as any),
-        tagMap: taggedUnionMap(a),
-        tags: tags(a as any)
-      }))
-  )
+type TaggedUnionMembers = NonEmptyReadonlyArray<
+  S.Top & { readonly Type: { readonly _tag: string } }
+>
+
+type TaggedUnionTags<Members extends TaggedUnionMembers> = S.Literals<
+  {
+    [Index in keyof Members]: Members[Index]["Type"]["_tag"]
+  }
+>
 
-export type PhoneNumber = PhoneNumberT
+type TaggedPropertyKeys<A, Members extends TaggedUnionMembers> = {
+  [K in keyof A & string]: A[K] extends Members[number]["Type"] ? K : never
+}[keyof A & string]
+
+type PropertyGuardsFor<
+  Members extends TaggedUnionMembers,
+  K extends string,
+  A
+> =
+  & {
+    readonly [M in Members[number] as `is${M["Type"]["_tag"]}`]: (
+      target: A
+    ) => target is A & { readonly [P in K]: M["Type"] }
+  }
+  & {
+    readonly isAnyOf: <const Tags extends ReadonlyArray<Members[number]["Type"]["_tag"]>>(
+      tags: Tags
+    ) => (
+      target: A
+    ) => target is A & { readonly [P in K]: Extract<Members[number]["Type"], { readonly _tag: Tags[number] }> }
+  }
+
+type PropertyGuards<
+  Members extends TaggedUnionMembers,
+  K extends string
+> =
+  & {
+    readonly [M in Members[number] as `is${M["Type"]["_tag"]}`]: <
+      T extends { readonly [P in K]: Members[number]["Type"] }
+    >(target: T) => target is T & { readonly [P in K]: M["Type"] }
+  }
+  & {
+    readonly isAnyOf: <const Tags extends ReadonlyArray<Members[number]["Type"]["_tag"]>>(
+      tags: Tags
+    ) => <T extends { readonly [P in K]: Members[number]["Type"] }>(
+      target: T
+    ) => target is T & { readonly [P in K]: Extract<Members[number]["Type"], { readonly _tag: Tags[number] }> }
+  }
+
+type TaggedUnionWithTags<Members extends TaggedUnionMembers> = S.toTaggedUnion<"_tag", Members> & {
+  readonly tags: TaggedUnionTags<Members>
+  readonly generateGuards: <K extends string>(property: K) => PropertyGuards<Members, K>
+  readonly generateGuardsFor: <A>() => <K extends TaggedPropertyKeys<A, Members>>(
+    property: K
+  ) => PropertyGuardsFor<Members, K, A>
+}
+
+const extendTaggedUnionWithTags = <Members extends TaggedUnionMembers>(
+  schema: S.Union<Members>
+): TaggedUnionWithTags<Members> =>
+  extendM(schema.pipe(S.toTaggedUnion("_tag")), (tagged) => {
+    const makeGuards = (property: string) => {
+      const result: any = {}
+      const guards: Record<string, (u: unknown) => boolean> = tagged.guards
+      for (const tag of Object.keys(guards)) {
+        const guard = guards[tag]!
+        result[`is${tag}`] = (target: any) => guard(target[property])
+      }
+      result.isAnyOf = (memberTags: Array<string>) => {
+        const check = tagged.isAnyOf(memberTags)
+        return (target: any) => check(target[property])
+      }
+      return result
+    }
+    return {
+      tags: tags(schema.members),
+      generateGuards: makeGuards,
+      generateGuardsFor: () => makeGuards
+    }
+  })
+
+export const ExtendTaggedUnion = <Members extends TaggedUnionMembers>(
+  schema: S.Union<Members>
+): TaggedUnionWithTags<Members> => extendTaggedUnionWithTags(schema)
+
+export const TaggedUnion = <
+  Members extends TaggedUnionMembers
+>(members: Members): TaggedUnionWithTags<Members> => extendTaggedUnionWithTags(S.Union(members))

package/src/client/InvalidationKeys.ts

@@ -0,0 +1,50 @@
+import * as Ref from "effect/Ref"
+import * as Context from "../Context.js"
+import * as Effect from "../Effect.js"
+import type { InvalidationKey } from "../rpc/Invalidation.js"
+
+export type { InvalidationKey }
+/** Shape of the per-mutation service that accumulates server-provided invalidation keys. */
+export interface InvalidationKeysService {
+  readonly add: (key: InvalidationKey) => Effect.Effect<void>
+  readonly get: Effect.Effect<ReadonlyArray<InvalidationKey>>
+}
+
+/**
+ * Context.Reference that accumulates invalidation keys received from the server via the
+ * `x-invalidate` HTTP response header.
+ *
+ * The default is a no-op: when not explicitly provided (e.g. outside a mutation wrapper)
+ * all calls are ignored. The mutation wrapper in `@effect-app/vue` provides a real
+ * implementation backed by a `Ref`.
+ */
+export const InvalidationKeysFromServer = Context.Reference<InvalidationKeysService>(
+  "effect-app/client/InvalidationKeysFromServer",
+  {
+    defaultValue: () => ({
+      add: (_key: InvalidationKey) => Effect.void,
+      get: Effect.succeed([] as ReadonlyArray<InvalidationKey>)
+    })
+  }
+)
+export type InvalidationKeysFromServer = typeof InvalidationKeysFromServer
+
+/**
+ * Creates a fresh `InvalidationKeysService` implementation backed by a `Ref`.
+ *
+ * @param ref - The `Ref` that stores the accumulated keys.
+ * @param onAdded - V3: Optional Effect run after a key is added. Use to trigger mid-stream
+ *   query invalidation without waiting for the stream to complete.
+ */
+export const makeInvalidationKeysService = (
+  ref: Ref.Ref<ReadonlyArray<InvalidationKey>>,
+  onAdded?: (key: InvalidationKey) => Effect.Effect<void>
+): InvalidationKeysService => ({
+  // When onAdded is set, fire it immediately without accumulating in the ref —
+  // the key is handled on arrival and must not be re-processed at stream end.
+  add: (key) =>
+    onAdded
+      ? onAdded(key)
+      : Ref.update(ref, (keys) => [...keys, key]),
+  get: Ref.get(ref)
+})