@typed/fx 1.32.0 → 2.0.0-beta.1

package/src/Fx/Fx.ts

@@ -0,0 +1,164 @@
+import * as Effect from "effect/Effect";
+import { identity } from "effect/Function";
+import type { Layer } from "effect/Layer";
+import { effect } from "effect/Layer";
+import { type Pipeable, pipeArguments } from "effect/Pipeable";
+import type * as Scope from "effect/Scope";
+import * as ServiceMap from "effect/ServiceMap";
+import type * as Types from "effect/Types";
+import type * as Sink from "../Sink/Sink.js";
+import { provideServices } from "./combinators/provide.js";
+import { FxTypeId, isFx } from "./TypeId.js";
+
+/**
+ * `Fx` is a reactive stream of values that supports concurrency, error handling,
+ * and context management, fully integrated with the Effect ecosystem.
+ *
+ * Conceptually, an `Fx<A, E, R>` is a push-based stream that:
+ * - Emits values of type `A`
+ * - Can fail with an error of type `E`
+ * - Requires a context/environment of type `R`
+ *
+ * Unlike a standard `Effect` which produces a single value, `Fx` can produce
+ * 0, 1, or many values over time. It is similar to RxJS Observables or
+ * AsyncIterables, but built on top of Effect's fiber-based concurrency model.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Fx<A, E = never, R = never> extends Pipeable {
+  readonly [FxTypeId]: Fx.Variance<A, E, R>;
+  /**
+   * Runs the Fx stream by providing a Sink to consume the values.
+   * The result is an Effect that runs the stream process.
+   */
+  readonly run: <RSink>(sink: Sink.Sink<A, E, RSink>) => Effect.Effect<unknown, never, R | RSink>;
+}
+
+export declare namespace Fx {
+  /**
+   * Any Fx type with wildcards.
+   * @since 1.0.0
+   * @category models
+   */
+  export type Any = Fx<any, any, any>;
+
+  /**
+   * Variance markers for Fx types.
+   * @since 1.0.0
+   * @category models
+   */
+  export interface Variance<A, E, R> {
+    readonly _A: Types.Covariant<A>;
+    readonly _E: Types.Covariant<E>;
+    readonly _R: Types.Covariant<R>;
+  }
+
+  /**
+   * Extract the success type from an Fx.
+   * @since 1.0.0
+   * @category type-level
+   */
+  export type Success<T> = [T] extends [never]
+    ? never
+    : T extends Fx<infer _A, infer _E, infer _R>
+      ? _A
+      : never;
+
+  /**
+   * Extract the error type from an Fx.
+   * @since 1.0.0
+   * @category type-level
+   */
+  export type Error<T> = [T] extends [never]
+    ? never
+    : T extends Fx<infer _A, infer _E, infer _R>
+      ? _E
+      : never;
+
+  /**
+   * Extract the required services from an Fx.
+   * @since 1.0.0
+   * @category type-level
+   */
+  export type Services<T> = [T] extends [never]
+    ? never
+    : [T] extends [Fx<infer _A, infer _E, infer _R>]
+      ? _R
+      : never;
+
+  export interface Service<Self, Id extends string, A, E> extends Fx<A, E, Self> {
+    readonly id: Id;
+    readonly service: ServiceMap.Service<Self, Fx<A, E>>;
+    readonly make: <R = never>(
+      fx: Fx<A, E, R> | Effect.Effect<Fx<A, E, R>, E, R>,
+    ) => Layer<Self, E, Exclude<R, Scope.Scope>>;
+  }
+
+  export interface Class<Self, Id extends string, A, E> extends Service<Self, Id, A, E> {
+    new (): Service<Self, Id, A, E>;
+  }
+}
+
+/**
+ * Extract the success type from an Fx.
+ * @since 1.0.0
+ * @category type-level
+ */
+export type Success<T> = Fx.Success<T>;
+
+/**
+ * Extract the error type from an Fx.
+ * @since 1.0.0
+ * @category type-level
+ */
+export type Error<T> = Fx.Error<T>;
+
+/**
+ * Extract the required services from an Fx.
+ * @since 1.0.0
+ * @category type-level
+ */
+export type Services<T> = Fx.Services<T>;
+
+const VARIANCE: Fx.Variance<any, any, any> = {
+  _A: identity,
+  _E: identity,
+  _R: identity,
+};
+
+export function Service<Self, A, E = never>() {
+  return <const Id extends string>(id: Id): Fx.Class<Self, Id, A, E> => {
+    const service = ServiceMap.Service<Self, Fx<A, E>>(id);
+
+    // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+    return class FxService {
+      static readonly id = id;
+      static readonly service = service;
+
+      static readonly make = <R = never>(
+        fx: Fx<A, E, R> | Effect.Effect<Fx<A, E, R>, E, R>,
+      ): Layer<Self, E, Exclude<R, Scope.Scope>> =>
+        effect(
+          service,
+          Effect.gen(function* () {
+            const services = yield* Effect.services<R>();
+            const result = isFx(fx) ? fx : yield* fx;
+            return provideServices(result, services);
+          }),
+        );
+
+      static readonly [FxTypeId] = VARIANCE;
+      static readonly pipe = function (this: any) {
+        return pipeArguments(this, arguments);
+      };
+
+      static readonly run = <RSink>(sink: Sink.Sink<A, E, RSink>) =>
+        Effect.flatMap(service.asEffect(), (fx) => fx.run(sink));
+
+      constructor() {
+        return FxService;
+      }
+    } as unknown as Fx.Class<Self, Id, A, E>;
+  };
+}

package/src/Fx/TypeId.ts

@@ -0,0 +1,25 @@
+import { hasProperty } from "effect/Predicate";
+import type { Fx } from "./Fx.js";
+
+/**
+ * The unique type identifier for Fx.
+ * @since 1.0.0
+ * @category symbol
+ */
+export const FxTypeId = Symbol.for("@typed/fx/Fx");
+
+/**
+ * The unique type identifier type for Fx.
+ * @since 1.0.0
+ * @category symbol
+ */
+export type FxTypeId = typeof FxTypeId;
+
+/**
+ * Checks if a value is an Fx.
+ * @since 1.0.0
+ * @category guards
+ */
+export function isFx(u: unknown): u is Fx<any, any, any> {
+  return hasProperty(u, FxTypeId);
+}

package/src/Fx/combinators/additive.ts

@@ -0,0 +1,142 @@
+import { dual } from "effect/Function";
+import type { Fx } from "../Fx.js";
+import { continueWith } from "./continueWith.js";
+import { filter } from "./filter.js";
+import { map } from "./map.js";
+import { mergeAll } from "./mergeAll.js";
+import { zip } from "./zip.js";
+
+/**
+ * Merges two Fx streams into a single Fx that emits values from both streams
+ * concurrently. Order of emission is non-deterministic.
+ *
+ * **Completion:** The merged stream completes when **both** input streams have
+ * completed.
+ *
+ * **Errors:** The first failure from either stream fails the merged stream;
+ * the other stream is interrupted.
+ *
+ * @param that - The second Fx stream.
+ * @returns An Fx that emits values from both streams.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const merge: {
+  <A2, E2, R2>(that: Fx<A2, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A | A2, E | E2, R | R2>;
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A | A2, E | E2, R | R2>;
+} = dual(
+  2,
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A | A2, E | E2, R | R2> =>
+    mergeAll(self, that),
+);
+
+/**
+ * Concatenates two Fx streams: runs the first to completion, then runs the
+ * second. Emits all values from the first stream in order, then all values
+ * from the second stream in order.
+ *
+ * **Completion:** The concatenated stream completes when the **second** stream
+ * completes (the first must complete before the second starts).
+ *
+ * **Errors:** If the first stream fails, the concatenated stream fails and the
+ * second is never run. If the second stream fails, the concatenated stream
+ * fails after the first has already completed.
+ *
+ * @param that - The second Fx stream (run after the first completes).
+ * @returns An Fx that emits values from the first stream, then the second.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const concat: {
+  <A2, E2, R2>(that: Fx<A2, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A | A2, E | E2, R | R2>;
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A | A2, E | E2, R | R2>;
+} = dual(
+  2,
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A | A2, E | E2, R | R2> =>
+    continueWith(self, () => that),
+);
+
+/**
+ * Zips two Fx streams in strict lockstep and emits only the left value.
+ * Completes when the **first** of the two streams completes.
+ *
+ * @param that - The second Fx stream.
+ * @returns An Fx that emits values from the left stream only.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const zipLeft: {
+  <A2, E2, R2>(that: Fx<A2, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A, E | E2, R | R2>;
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A, E | E2, R | R2>;
+} = dual(
+  2,
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A, E | E2, R | R2> =>
+    map(zip(self, that), (pair) => pair[0]),
+);
+
+/**
+ * Zips two Fx streams in strict lockstep and emits only the right value.
+ * Completes when the **first** of the two streams completes.
+ *
+ * @param that - The second Fx stream.
+ * @returns An Fx that emits values from the right stream only.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const zipRight: {
+  <A2, E2, R2>(that: Fx<A2, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A2, E | E2, R | R2>;
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A2, E | E2, R | R2>;
+} = dual(
+  2,
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A2, E | E2, R | R2> =>
+    map(zip(self, that), (pair) => pair[1]),
+);
+
+type TaggedLeft<A> = { readonly _tag: "Left"; readonly value: A };
+type TaggedRight<A2> = { readonly _tag: "Right"; readonly value: A2 };
+
+/**
+ * Merges two Fx streams and emits only values from the left stream.
+ * Both streams run concurrently; completion when **both** complete.
+ *
+ * @param that - The second Fx stream (values are dropped).
+ * @returns An Fx that emits only values from the left stream.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const mergeLeft: {
+  <A2, E2, R2>(that: Fx<A2, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A, E | E2, R | R2>;
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A, E | E2, R | R2>;
+} = dual(
+  2,
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A, E | E2, R | R2> => {
+    const taggedLeft = map(self, (a: A): TaggedLeft<A> => ({ _tag: "Left", value: a }));
+    const taggedRight = map(that, (b: A2): TaggedRight<A2> => ({ _tag: "Right", value: b }));
+    const merged = mergeAll(taggedLeft, taggedRight);
+    const leftOnly = filter(merged, (x): x is TaggedLeft<A> => x._tag === "Left");
+    return map(leftOnly, (x) => x.value) as Fx<A, E | E2, R | R2>;
+  },
+);
+
+/**
+ * Merges two Fx streams and emits only values from the right stream.
+ * Both streams run concurrently; completion when **both** complete.
+ *
+ * @param that - The second Fx stream.
+ * @returns An Fx that emits only values from the right stream.
+ * @since 1.0.0
+ * @category combinators
+ */
+export const mergeRight: {
+  <A2, E2, R2>(that: Fx<A2, E2, R2>): <A, E, R>(self: Fx<A, E, R>) => Fx<A2, E | E2, R | R2>;
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A2, E | E2, R | R2>;
+} = dual(
+  2,
+  <A, E, R, A2, E2, R2>(self: Fx<A, E, R>, that: Fx<A2, E2, R2>): Fx<A2, E | E2, R | R2> => {
+    const taggedLeft = map(self, (a: A): TaggedLeft<A> => ({ _tag: "Left", value: a }));
+    const taggedRight = map(that, (b: A2): TaggedRight<A2> => ({ _tag: "Right", value: b }));
+    const merged = mergeAll(taggedLeft, taggedRight);
+    const rightOnly = filter(merged, (x): x is TaggedRight<A2> => x._tag === "Right");
+    return map(rightOnly, (x) => x.value) as Fx<A2, E | E2, R | R2>;
+  },
+);