@typed/fx 1.17.4 → 1.18.0

package/src/Sink.ts

@@ -1,17 +1,274 @@
-import * as Cause from '@effect/io/Cause'
-import * as Effect from '@effect/io/Effect'
+/**
+ * Sink is a data structure that represents a place to send failures and successes
+ * over time in an effectful manner.
+ * @since 1.18.0
+ */
 
-export interface Sink<R, E, A> {
-  readonly event: (a: A) => Effect.Effect<R, never, void>
-  readonly error: (e: Cause.Cause<E>) => Effect.Effect<R, never, void>
+import type { Context } from "@typed/context"
+import * as Cause from "effect/Cause"
+import * as Clock from "effect/Clock"
+import * as Effect from "effect/Effect"
+import * as Either from "effect/Either"
+import { dual } from "effect/Function"
+import type * as Tracer from "effect/Tracer"
+
+/**
+ * Sink is a data structure that represents a place to send failures and successes
+ * over time in an effectful manner.
+ * @since 1.18.0
+ * @category models
+ */
+export interface Sink<E, A> extends WithContext<never, E, A> {}
+
+/**
+ * Construct a Sink that can be used to handle failures and successes.
+ * @since 1.18.0
+ * @category constructors
+ */
+export function Sink<E, A>(
+  onFailure: (cause: Cause.Cause<E>) => Effect.Effect<never, never, unknown>,
+  onSuccess: (a: A) => Effect.Effect<never, never, unknown>
+): Sink<E, A> {
+  return {
+    onFailure,
+    onSuccess
+  }
+}
+
+/**
+ * @since 1.18.0
+ */
+export namespace Sink {
+  /**
+   * Extract the Error type from a Sink
+   * @since 1.18.0
+   */
+  export type Error<T> = T extends Sink<infer E, any> ? E : never
+
+  /**
+   * Extract the Success type from a Sink
+   * @since 1.18.0
+   */
+  export type Success<T> = T extends Sink<any, infer A> ? A : never
 }
 
-export function Sink<A, R, E, R2>(
-  event: (a: A) => Effect.Effect<R, never, void>,
-  error: (e: Cause.Cause<E>) => Effect.Effect<R2, never, void>,
-): Sink<R | R2, E, A> {
+/**
+ * A Sink that can be used to handle failures and successes with a Context.
+ * @since 1.18.0
+ * @category models
+ */
+export interface WithContext<R, E, A> {
+  readonly onFailure: (cause: Cause.Cause<E>) => Effect.Effect<R, never, unknown>
+  readonly onSuccess: (a: A) => Effect.Effect<R, never, unknown>
+}
+
+/**
+ * Construct a Sink that can be used to handle failures and successes with a Context.
+ * @since 1.18.0
+ * @category constructors
+ */
+export function WithContext<R, E, A, R2>(
+  onFailure: (cause: Cause.Cause<E>) => Effect.Effect<R, never, unknown>,
+  onSuccess: (a: A) => Effect.Effect<R2, never, unknown>
+): WithContext<R | R2, E, A> {
   return {
-    event,
-    error,
+    onFailure,
+    onSuccess
   }
 }
+
+/**
+ * @since 1.18.0
+ */
+export namespace WithContext {
+  /**
+   * Extract the Context type from a Sink
+   * @since 1.18.0
+   */
+  export type Context<T> = T extends WithContext<infer R, any, any> ? R : never
+
+  /**
+   * Extract the Error type from a Sink
+   * @since 1.18.0
+   */
+  export type Error<T> = T extends WithContext<any, infer E, any> ? E : never
+
+  /**
+   * Extract the Success type from a Sink
+   * @since 1.18.0
+   */
+  export type Success<T> = T extends WithContext<any, any, infer A> ? A : never
+}
+
+/**
+ * Provide a Context to a Sink
+ * @since 1.18.0
+ * @category context
+ */
+export function provide<R, E, A>(sink: WithContext<R, E, A>, ctx: Context<R>): Sink<E, A> {
+  return Sink(
+    (cause) => Effect.provide(sink.onFailure(cause), ctx),
+    (a) => Effect.provide(sink.onSuccess(a), ctx)
+  )
+}
+
+/**
+ * A Sink which can be utilized to exit early from an Fx.
+ * Useful for operators the end the stream early.
+ * @since 1.18.0
+ * @category models
+ */
+export interface WithEarlyExit<E, A> extends Sink<E, A> {
+  readonly earlyExit: Effect.Effect<never, never, void>
+}
+
+/**
+ * Transform the input value of a Sink.
+ * @since 1.18.0
+ * @category combinators
+ */
+export const map: {
+  <B, A>(f: (b: B) => A): <R, E>(sink: WithContext<R, E, A>) => WithContext<R, E, B>
+  <R, E, A, B>(sink: WithContext<R, E, A>, f: (b: B) => A): WithContext<R, E, B>
+} = dual(2, function map<R, E, A, B>(
+  sink: WithContext<R, E, A>,
+  f: (b: B) => A
+): WithContext<R, E, B> {
+  return WithContext(
+    sink.onFailure,
+    (a) => sink.onSuccess(f(a))
+  )
+})
+
+/**
+ * Transform the input value of a Sink using an Effect.
+ * @since 1.18.0
+ * @category combinators
+ */
+export const mapEffect: {
+  <B, R2, E, A>(f: (b: B) => Effect.Effect<R2, E, A>): <R>(sink: WithContext<R, E, A>) => WithContext<R | R2, E, B>
+  <R, E, A, R2, B>(sink: WithContext<R, E, A>, f: (b: B) => Effect.Effect<R2, E, A>): WithContext<R | R2, E, B>
+} = dual(2, function mapEffect<R, E, A, R2, B>(
+  sink: WithContext<R, E, A>,
+  f: (b: B) => Effect.Effect<R2, E, A>
+): WithContext<R | R2, E, B> {
+  return WithContext(
+    sink.onFailure,
+    (b) => Effect.matchCauseEffect(f(b), sink)
+  )
+})
+
+/**
+ * Transform the input Cause of a Sink.
+ * @since 1.18.0
+ * @category combinators
+ */
+export const mapErrorCause: {
+  <E2, E, A>(f: (e: Cause.Cause<E2>) => Cause.Cause<E>): <R>(sink: WithContext<R, E, A>) => WithContext<R, E2, A>
+  <R, E, A, E2>(sink: WithContext<R, E, A>, f: (e: Cause.Cause<E2>) => Cause.Cause<E>): WithContext<R, E2, A>
+} = dual(2, function mapErrorCause<E, A, E2>(
+  sink: Sink<E, A>,
+  f: (e: Cause.Cause<E2>) => Cause.Cause<E>
+): Sink<E2, A> {
+  return Sink(
+    (cause) => sink.onFailure(f(cause)),
+    sink.onSuccess
+  )
+})
+
+/**
+ * Transform the input Cause of a Sink using an Effect.
+ * @since 1.18.0
+ * @category combinators
+ */
+export const mapErrorCauseEffect: {
+  <E2, R2, E, A>(
+    f: (e: Cause.Cause<E2>) => Effect.Effect<R2, E, Cause.Cause<E>>
+  ): <R>(sink: WithContext<R, E, A>) => WithContext<R | R2, E2, A>
+  <R, E, A, R2, E2>(
+    sink: WithContext<R, E, A>,
+    f: (e: Cause.Cause<E2>) => Effect.Effect<R2, E, Cause.Cause<E>>
+  ): WithContext<R | R2, E2, A>
+} = dual(2, function mapErrorCauseEffect<R, E, A, R2, E2>(
+  sink: WithContext<R, E, A>,
+  f: (e: Cause.Cause<E2>) => Effect.Effect<R2, E, Cause.Cause<E>>
+): WithContext<R | R2, E2, A> {
+  return WithContext(
+    (cause) => Effect.matchCauseEffect(f(cause), WithContext(sink.onFailure, sink.onFailure)),
+    sink.onSuccess
+  )
+})
+
+/**
+ * Transform the input Error of a Sink.
+ * @since 1.18.0
+ * @category combinators
+ */
+export const mapError: {
+  <E2, E, A>(f: (e: E2) => E): <R>(sink: WithContext<R, E, A>) => WithContext<R, E2, A>
+  <R, E, A, E2>(sink: WithContext<R, E, A>, f: (e: E2) => E): WithContext<R, E2, A>
+} = dual(2, function mapError<R, E, A, E2>(
+  sink: WithContext<R, E, A>,
+  f: (e: E2) => E
+): WithContext<R, E2, A> {
+  return WithContext(
+    (cause) => sink.onFailure(Cause.map(cause, f)),
+    sink.onSuccess
+  )
+})
+
+/**
+ * Transform the input Error of a Sink using an Effect.
+ * @since 1.18.0
+ * @category combinators
+ */
+export const mapErrorEffect: {
+  <E2, R2, E, A>(f: (e: E2) => Effect.Effect<R2, E, E>): <R>(sink: WithContext<R, E, A>) => WithContext<R | R2, E, A>
+  <R, E, A, R2, E2>(sink: WithContext<R, E, A>, f: (e: E2) => Effect.Effect<R2, E, E>): WithContext<R | R2, E, A>
+} = dual(2, function mapErrorEffect<R, E, A, R2, E2>(
+  sink: WithContext<R, E, A>,
+  f: (e: E2) => Effect.Effect<R2, E, E>
+): WithContext<R | R2, E2, A> {
+  return mapErrorCauseEffect(sink, (cause: Cause.Cause<E2>) =>
+    Either.match(Cause.failureOrCause(cause), {
+      onLeft: (e2) => Effect.map(f(e2), Cause.fail),
+      onRight: (cause) => Effect.succeed(cause)
+    }))
+})
+
+/**
+ * Set the span a Sink will use to append events to.
+ * @since 1.18.0
+ * @category tracing
+ */
+export const setSpan: {
+  (span: Tracer.Span): <R, E, A>(self: WithContext<R, E, A>) => WithContext<R, E, A>
+  <R, E, A>(self: WithContext<R, E, A>, span: Tracer.Span): WithContext<R, E, A>
+} = dual(2, function withSpan<R, E, A>(
+  self: WithContext<R, E, A>,
+  span: Tracer.Span
+): WithContext<R, E, A> {
+  return WithContext(
+    (cause) =>
+      addEvent(self.onFailure(cause), "fx.failure", span, {
+        "cause": Cause.pretty(cause)
+      }),
+    (a) =>
+      addEvent(self.onSuccess(a), "fx.success", span, {
+        "value": JSON.stringify(a)
+      })
+  )
+})
+
+const addEvent = <R, E, A>(
+  effect: Effect.Effect<R, E, A>,
+  name: string,
+  span: Tracer.Span,
+  attributes: Record<string, unknown>
+): Effect.Effect<R, E, A> =>
+  Effect.flatMap(Clock.currentTimeNanos, (time) =>
+    Effect.suspend(() => {
+      span.event(name, time, attributes)
+
+      return effect
+    }))

package/src/Stream.ts

@@ -0,0 +1,128 @@
+/**
+ * Additional Stream integrations with Fx.
+ * @since 1.18.0
+ */
+import * as Cause from "effect/Cause"
+import * as Chunk from "effect/Chunk"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import { dual } from "effect/Function"
+import * as Option from "effect/Option"
+import * as Queue from "effect/Queue"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import * as Fx from "./Fx"
+import { Sink } from "./Sink"
+
+/**
+ * Convert an Fx to a Stream
+ * @since 1.18.0
+ * @category conversions
+ */
+export function toStream<R, E, A>(fx: Fx.Fx<R, E, A>): Stream.Stream<R, E, A> {
+  return Stream.asyncScoped<R | Scope.Scope, E, A>((emit) =>
+    Fx.run(
+      fx,
+      Sink(
+        (cause) => Effect.promise(() => emit(Effect.failCause(Cause.map(cause, Option.some)))),
+        (a) => Effect.promise(() => emit(Effect.succeed(Chunk.of(a))))
+      )
+    )
+      .pipe(
+        Effect.zipRight(Effect.promise(() => emit(Effect.fail(Option.none())))),
+        Effect.forkScoped
+      )
+  )
+}
+
+/**
+ * Convert an Fx to a Stream using a Queue to buffer values
+ * that have not yet been pulled.
+ * @since 1.18.0
+ * @category conversions
+ */
+export const toStreamQueued: {
+  <E, A, R2, E2>(
+    make: Effect.Effect<R2, E2, Queue.Queue<Exit.Exit<Option.Option<E>, A>>>
+  ): <R>(fx: Fx.Fx<R, E, A>) => Stream.Stream<R | R2, E | E2, A>
+
+  <R, E, A, R2, E2>(
+    fx: Fx.Fx<R, E, A>,
+    make: Effect.Effect<R2, E2, Queue.Queue<Exit.Exit<Option.Option<E>, A>>>
+  ): Stream.Stream<R | R2, E | E2, A>
+} = dual(2, function toStreamQueued<R, E, A, R2, E2>(
+  fx: Fx.Fx<R, E, A>,
+  make: Effect.Effect<R2, E2, Queue.Queue<Exit.Exit<Option.Option<E>, A>>>
+): Stream.Stream<R | R2, E | E2, A> {
+  return Stream.flattenExitOption(Stream.unwrapScoped(Effect.gen(function*(_) {
+    const queue = yield* _(make)
+
+    yield* _(
+      fx,
+      Fx.mapError(Option.some),
+      Fx.exit,
+      Fx.toEnqueue(queue),
+      Effect.ensuring(queue.offer(Exit.fail(Option.none()))),
+      Effect.forkScoped
+    )
+
+    return Stream.fromQueue(queue)
+  })))
+})
+
+/**
+ * Convert an Fx to a Stream using a sliding Queue to buffer values
+ * that have not yet been pulled.
+ * @since 1.18.0
+ * @category conversions
+ */
+export const toStreamSliding: {
+  (capacity: number): <R, E, A>(fx: Fx.Fx<R, E, A>) => Stream.Stream<R, E, A>
+  <R, E, A>(fx: Fx.Fx<R, E, A>, capacity: number): Stream.Stream<R, E, A>
+} = dual(
+  2,
+  function toStreamSliding<R, E, A>(fx: Fx.Fx<R, E, A>, capacity: number): Stream.Stream<R, E, A> {
+    return toStreamQueued(fx, Queue.sliding(capacity))
+  }
+)
+
+/**
+ * Convert an Fx to a Stream using a dropping Queue to buffer values
+ * that have not yet been pulled.
+ * @since 1.18.0
+ * @category conversions
+ */
+export const toStreamDropping: {
+  (capacity: number): <R, E, A>(fx: Fx.Fx<R, E, A>) => Stream.Stream<R, E, A>
+  <R, E, A>(fx: Fx.Fx<R, E, A>, capacity: number): Stream.Stream<R, E, A>
+} = dual(
+  2,
+  function toStreamDropping<R, E, A>(fx: Fx.Fx<R, E, A>, capacity: number): Stream.Stream<R, E, A> {
+    return toStreamQueued(fx, Queue.dropping(capacity))
+  }
+)
+
+/**
+ * Convert an Fx to a Stream using a bounded Queue to buffer values
+ * that have not yet been pulled.
+ * @since 1.18.0
+ * @category conversions
+ */
+export const toStreamBounded: {
+  (capacity: number): <R, E, A>(fx: Fx.Fx<R, E, A>) => Stream.Stream<R, E, A>
+  <R, E, A>(fx: Fx.Fx<R, E, A>, capacity: number): Stream.Stream<R, E, A>
+} = dual(
+  2,
+  function toStreamBounded<R, E, A>(fx: Fx.Fx<R, E, A>, capacity: number): Stream.Stream<R, E, A> {
+    return toStreamQueued(fx, Queue.bounded(capacity))
+  }
+)
+
+/**
+ * Convert a Stream to an Fx of chunks
+ * @since 1.18.0
+ * @category conversions
+ */
+export function chunked<R, E, A>(stream: Stream.Stream<R, E, A>): Fx.Fx<R, E, Chunk.Chunk<A>> {
+  return Fx.fromSink((sink) => Effect.catchAllCause(Stream.runForEachChunk(stream, sink.onSuccess), sink.onFailure))
+}

package/src/Subject.ts

@@ -1,37 +1,143 @@
-import * as Effect from '@effect/io/Effect'
-import * as Fiber from '@effect/io/Fiber'
+/**
+ * Subjects are the basis for sharing events between multiple consumers in an effecient manner
+ * and for event-bus-like functionality.
+ * @since 1.18.0
+ */
 
-import type { Fx, Sink } from './Fx.js'
-import { HoldFx } from './hold.js'
-import { MulticastFx } from './multicast.js'
-import { never } from './never.js'
+import * as C from "@typed/context"
+import type { Cause } from "effect/Cause"
+import * as Effect from "effect/Effect"
+import type * as Layer from "effect/Layer"
+import { type Fx, ToFx } from "./Fx"
+import { provide } from "./internal/core"
+import * as internal from "./internal/core-subject"
+import { fromFxEffect } from "./internal/fx"
+import type { WithContext } from "./Sink"
 
-export interface Subject<E, A> extends Fx<never, E, A>, Sink<never, E, A> {
-  readonly end: () => Effect.Effect<never, never, void>
+/**
+ * A Subject is an Fx which is also a Sink, and can be used to
+ * broadcast events to many consumers.
+ * @since 1.18.0
+ * @category models
+ */
+export interface Subject<R, E, A> extends Fx<R, E, A>, WithContext<R, E, A> {
+  readonly subscriberCount: Effect.Effect<R, never, number>
+  readonly interrupt: Effect.Effect<R, never, void>
 }
 
-export function makeSubject<E, A>(): Subject<E, A> {
-  return new SubjectImpl<E, A>()
-}
+/**
+ * @since 1.18.0
+ */
+export namespace Subject {
+  /**
+   * A Contextual wrapper around a Subject
+   * @since 1.18.0
+   * @category models
+   */
+  export interface Tagged<I, E, A> extends Subject<I, E, A> {
+    readonly tag: C.Tagged<I, Subject<never, E, A>>
+
+    readonly interrupt: Effect.Effect<I, never, void>
+
+    readonly provide: (
+      replay?: number
+    ) => <R2, E2, B>(effect: Effect.Effect<R2, E2, B>) => Effect.Effect<Exclude<R2, I>, E2, B>
 
-export function makeHoldSubject<E, A>(): Subject<E, A> {
-  return new HoldSubjectImpl<E, A>()
+    readonly provideFx: (
+      replay?: number
+    ) => <R2, E2, B>(fx: Fx<R2, E2, B>) => Fx<Exclude<R2, I>, E2, B>
+
+    readonly make: (replay?: number) => Layer.Layer<never, never, I>
+  }
 }
 
-export class SubjectImpl<E, A> extends MulticastFx<never, E, A> implements Subject<E, A> {
-  constructor() {
-    super(never<E, A>())
+/**
+ * Constructs a Subject that can be used to broadcast events to many consumers.
+ * @since 1.18.0
+ * @category constructors
+ */
+export const make: <E, A>() => Subject<never, E, A> = internal.makeSubject
+
+/**
+ * Constructs a Subject that can be used to broadcast events to many consumers.
+ * If a previous event has been consumed previously, any "late" subscribers will
+ * receive that previous event.
+ * @since 1.18.0
+ * @category constructors
+ */
+export const makeHold: <E, A>() => Subject<never, E, A> = internal.makeHoldSubject
+
+/**
+ * Constructs a Subject that can be used to broadcast events to many consumers.
+ * If a previous event has been consumed previously, any "late" subscribers will
+ * receive _up to_ `capacity` previous events.
+ * @since 1.18.0
+ * @category constructors
+ */
+export const makeReplay: <E, A>(capacity: number) => Subject<never, E, A> = internal.makeReplaySubject
+
+/**
+ * Construct a contextual Subject
+ * @since 1.18.0
+ * @category constructors
+ */
+export function tagged<E, A>(): {
+  <const I extends C.IdentifierFactory<any>>(identifier: I): Subject.Tagged<C.IdentifierOf<I>, E, A>
+  <const I>(identifier: I): Subject.Tagged<C.IdentifierOf<I>, E, A>
+} {
+  function makeTagged<const I extends C.IdentifierFactory<any>>(
+    identifier: I
+  ): Subject.Tagged<C.IdentifierOf<I>, E, A>
+  function makeTagged<const I>(identifier: I): Subject.Tagged<C.IdentifierOf<I>, E, A>
+  function makeTagged<const I>(identifier: I): Subject.Tagged<C.IdentifierOf<I>, E, A> {
+    return new ContextImpl(C.Tagged<I, Subject<never, E, A>>(identifier))
   }
 
-  readonly end = () =>
-    Effect.suspend(() => (this.fiber ? Fiber.interrupt(this.fiber) : Effect.unit))
+  return makeTagged
 }
 
-export class HoldSubjectImpl<E, A> extends HoldFx<never, E, A> implements Subject<E, A> {
-  constructor() {
-    super(never<E, A>())
+class ContextImpl<I, E, A> extends ToFx<I, E, A> implements Subject.Tagged<I, E, A> {
+  interrupt: Subject.Tagged<I, E, A>["interrupt"]
+  subscriberCount: Subject.Tagged<I, E, A>["subscriberCount"]
+
+  constructor(readonly tag: C.Tagged<I, Subject<never, E, A>>) {
+    super()
+
+    this.onFailure = this.onFailure.bind(this)
+    this.onSuccess = this.onSuccess.bind(this)
+    this.provide = this.provide.bind(this)
+    this.make = this.make.bind(this)
+    this.interrupt = tag.withEffect((subject) => subject.interrupt)
+    this.subscriberCount = tag.withEffect((subject) => subject.subscriberCount)
   }
 
-  readonly end = () =>
-    Effect.suspend(() => (this.fiber ? Fiber.interrupt(this.fiber) : Effect.unit))
+  toFx() {
+    return fromFxEffect(this.tag)
+  }
+
+  onFailure(cause: Cause<E>) {
+    return this.tag.withEffect((subject) => subject.onFailure(cause))
+  }
+
+  onSuccess(a: A) {
+    return this.tag.withEffect((subject) => subject.onSuccess(a))
+  }
+
+  make(replay?: number): Layer.Layer<never, never, I> {
+    return this.tag.layer(Effect.sync(() => {
+      if (replay === undefined || replay <= 0) {
+        return make<E, A>()
+      } else if (replay === 1) {
+        return makeHold<E, A>()
+      } else {
+        return makeReplay<E, A>(replay)
+      }
+    }))
+  }
+
+  provide: (replay?: number) => <R2, E2, B>(effect: Effect.Effect<R2, E2, B>) => Effect.Effect<Exclude<R2, I>, E2, B> =
+    (replay) => (effect) => Effect.provide(effect, this.make(replay))
+
+  provideFx: (replay?: number) => <R2, E2, B>(fx: Fx<R2, E2, B>) => Fx<Exclude<R2, I>, E2, B> = (replay) => (fx) =>
+    provide(fx, this.make(replay))
 }

package/src/TypeId.ts

@@ -0,0 +1,47 @@
+/**
+ * @since 1.18.0
+ * @category symbols
+ */
+export const TypeId = Symbol.for("./Fx")
+
+/**
+ * @since 1.18.0
+ * @category symbols
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * @since 1.18.0
+ * @category symbols
+ */
+export const RefSubjectTypeId = Symbol.for("./RefSubject")
+
+/**
+ * @since 1.18.0
+ * @category symbols
+ */
+export type RefSubjectTypeId = typeof RefSubjectTypeId
+
+/**
+ * @since 1.18.0
+ * @category symbols
+ */
+export const ComputedTypeId = Symbol.for("./Computed")
+
+/**
+ * @since 1.18.0
+ * @category symbols
+ */
+export type ComputedTypeId = typeof ComputedTypeId
+
+/**
+ * @since 1.18.0
+ * @category symbols
+ */
+export const FilteredTypeId = Symbol.for("./Filtered")
+
+/**
+ * @since 1.18.0
+ * @category symbols
+ */
+export type FilteredTypeId = typeof FilteredTypeId