@typed/fx 2.0.0-beta.3 → 2.0.0-beta.5

package/dist/Fx/combinators/gen.d.ts

@@ -1,20 +1,39 @@
 import * as Effect from "effect/Effect";
 import type { Fx } from "../Fx.js";
-/** Extract error type from Yieldable (Effect v4) */
-type _YE<Y> = Y extends Effect.Yieldable<any, any, infer E, any> ? E : never;
-/** Extract services type from Yieldable (Effect v4) */
-type _YS<Y> = Y extends Effect.Yieldable<any, any, any, infer R> ? R : never;
 /**
- * Creates an Fx using a generator function (Effect.gen style).
+ * Builds an Fx by yielding Effects and returning the Fx to run afterward.
  *
- * This allows writing Fx code in a synchronous-looking style, using `yield*` to composition.
- * Note: The generator yields Effects, and the result is an Fx.
+ * @remarks
+ * ## Why
+ *
+ * Setup logic often needs Effect services or failures before it can choose a
+ * push producer. Generator notation keeps that dependency-aware setup linear
+ * while preserving the returned Fx's success, error, and service channels.
+ *
+ * ## Ownership and lifetime
+ *
+ * The generator is lazy: it runs for each subscription. Yielded Effects run
+ * first; only their returned Fx is then subscribed. A setup failure prevents
+ * the Fx from starting, and interruption cancels the active phase. Resources
+ * acquired by yielded Effects must not escape unless managed independently;
+ * use {@link genScoped} when setup and the returned Fx share a Scope.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { gen } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const greeting = gen(function* () {
+ *   const name = yield* Effect.succeed("Typed")
+ *   return succeed(`Hello, ${name}`)
+ * })
+ * ```
  *
  * @param f - The generator function.
  * @returns An `Fx` representing the result of the generator.
  * @since 1.0.0
  * @category combinators
  */
-export declare const gen: <Yield extends Effect.Yieldable<any, any, any, any>, Return extends Fx.Any>(f: () => Generator<Yield, Return, any>) => Fx<Fx.Success<Return>, Fx.Error<Return> | _YE<Yield>, Fx.Services<Return> | _YS<Yield>>;
-export {};
+export declare const gen: <Yield extends Effect.Effect<any, any, any>, Return extends Fx.Any>(f: () => Generator<Yield, Return, any>) => Fx<Fx.Success<Return>, Fx.Error<Return> | ([Yield] extends [never] ? never : Effect.Error<Yield>), Fx.Services<Return> | ([Yield] extends [never] ? never : Effect.Services<Yield>)>;
 //# sourceMappingURL=gen.d.ts.map

package/dist/Fx/combinators/gen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gen.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/gen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC,oDAAoD;AACpD,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAC7E,uDAAuD;AACvD,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE7E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,GAAG,GAAI,KAAK,SAAS,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,MAAM,SAAS,EAAE,CAAC,GAAG,EAC3F,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,KACrC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,CAC3D,CAAC"}
+{"version":3,"file":"gen.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/gen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,GAAG,GAAI,KAAK,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,MAAM,SAAS,EAAE,CAAC,GAAG,KAChF,MAAM,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,KACrC,EAAE,CACH,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EAClB,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAC1E,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CACxD,CAAC"}

package/dist/Fx/combinators/gen.js

@@ -1,10 +1,34 @@
 import * as Effect from "effect/Effect";
 import { unwrap } from "./unwrap.js";
 /**
- * Creates an Fx using a generator function (Effect.gen style).
+ * Builds an Fx by yielding Effects and returning the Fx to run afterward.
  *
- * This allows writing Fx code in a synchronous-looking style, using `yield*` to composition.
- * Note: The generator yields Effects, and the result is an Fx.
+ * @remarks
+ * ## Why
+ *
+ * Setup logic often needs Effect services or failures before it can choose a
+ * push producer. Generator notation keeps that dependency-aware setup linear
+ * while preserving the returned Fx's success, error, and service channels.
+ *
+ * ## Ownership and lifetime
+ *
+ * The generator is lazy: it runs for each subscription. Yielded Effects run
+ * first; only their returned Fx is then subscribed. A setup failure prevents
+ * the Fx from starting, and interruption cancels the active phase. Resources
+ * acquired by yielded Effects must not escape unless managed independently;
+ * use {@link genScoped} when setup and the returned Fx share a Scope.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { gen } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const greeting = gen(function* () {
+ *   const name = yield* Effect.succeed("Typed")
+ *   return succeed(`Hello, ${name}`)
+ * })
+ * ```
  *
  * @param f - The generator function.
  * @returns An `Fx` representing the result of the generator.

package/dist/Fx/combinators/genScoped.d.ts

@@ -1,20 +1,43 @@
 import * as Effect from "effect/Effect";
-import type * as Scope from "effect/Scope";
 import type { Fx } from "../Fx.js";
-/** Extract error type from Yieldable (Effect v4) */
-type _YE<Y> = Y extends Effect.Yieldable<any, any, infer E, any> ? E : never;
-/** Extract services type from Yieldable (Effect v4) */
-type _YS<Y> = Y extends Effect.Yieldable<any, any, any, infer R> ? R : never;
+import { Scope } from "effect";
 /**
- * Creates a scoped Fx using a generator function.
+ * Builds an Fx with a subscription-owned Scope shared by setup and streaming.
  *
- * Similar to `gen`, but also handles resource management via Scope.
+ * @remarks
+ * ## Why
+ *
+ * Resourceful setup must remain alive while the returned producer runs and be
+ * released when that subscription ends. `genScoped` supplies that exact
+ * acquisition-to-stream lifetime while removing `Scope` from the public
+ * service requirement.
+ *
+ * ## Ownership and lifetime
+ *
+ * Every subscription creates one child Scope, runs the generator inside it,
+ * then runs the returned Fx in the same Scope. Normal completion, failure,
+ * defect, or interruption closes the Scope and its finalizers. Setup failures
+ * prevent streaming; all non-Scope errors and services remain in the result.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { genScoped } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const resourceful = genScoped(function* () {
+ *   const handle = yield* Effect.acquireRelease(
+ *     Effect.succeed({ open: true }),
+ *     () => Effect.void
+ *   )
+ *   return succeed(handle.open)
+ * })
+ * ```
  *
  * @param f - The generator function.
  * @returns An `Fx` representing the result of the generator.
  * @since 1.0.0
  * @category combinators
  */
-export declare const genScoped: <Yield extends Effect.Yieldable<any, any, any, any>, A, E, R>(f: () => Generator<Yield, Fx<A, E, R>, any>) => Fx<A, E | _YE<Yield>, Exclude<R | _YS<Yield>, Scope.Scope>>;
-export {};
+export declare const genScoped: <Yield extends Effect.Effect<any, any, any>, Return extends Fx.Any>(f: () => Generator<Yield, Return, any>) => Fx<Fx.Success<Return>, Fx.Error<Return> | ([Yield] extends [never] ? never : Effect.Error<Yield>), Exclude<Fx.Services<Return> | ([Yield] extends [never] ? never : Effect.Services<Yield>), Scope.Scope>>;
 //# sourceMappingURL=genScoped.d.ts.map

package/dist/Fx/combinators/genScoped.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"genScoped.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/genScoped.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC,oDAAoD;AACpD,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAC7E,uDAAuD;AACvD,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE7E;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,SAAS,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EACnF,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,KAC1C,EAAE,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CACzB,CAAC"}
+{"version":3,"file":"genScoped.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/genScoped.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAEnC,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,SAAS,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,MAAM,SAAS,EAAE,CAAC,GAAG,KACtF,MAAM,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,KACrC,EAAE,CACH,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EAClB,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAC1E,OAAO,CACL,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAChF,KAAK,CAAC,KAAK,CACZ,CAC6B,CAAC"}

package/dist/Fx/combinators/genScoped.js

@@ -1,9 +1,37 @@
 import * as Effect from "effect/Effect";
 import { unwrapScoped } from "./unwrapScoped.js";
 /**
- * Creates a scoped Fx using a generator function.
+ * Builds an Fx with a subscription-owned Scope shared by setup and streaming.
  *
- * Similar to `gen`, but also handles resource management via Scope.
+ * @remarks
+ * ## Why
+ *
+ * Resourceful setup must remain alive while the returned producer runs and be
+ * released when that subscription ends. `genScoped` supplies that exact
+ * acquisition-to-stream lifetime while removing `Scope` from the public
+ * service requirement.
+ *
+ * ## Ownership and lifetime
+ *
+ * Every subscription creates one child Scope, runs the generator inside it,
+ * then runs the returned Fx in the same Scope. Normal completion, failure,
+ * defect, or interruption closes the Scope and its finalizers. Setup failures
+ * prevent streaming; all non-Scope errors and services remain in the result.
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { genScoped } from "@typed/fx/Fx"
+ * import { succeed } from "@typed/fx/Fx"
+ *
+ * const resourceful = genScoped(function* () {
+ *   const handle = yield* Effect.acquireRelease(
+ *     Effect.succeed({ open: true }),
+ *     () => Effect.void
+ *   )
+ *   return succeed(handle.open)
+ * })
+ * ```
  *
  * @param f - The generator function.
  * @returns An `Fx` representing the result of the generator.

package/dist/Fx/combinators/grouped.d.ts

@@ -0,0 +1,89 @@
+import type { NonEmptyReadonlyArray } from "effect/Array";
+import * as Cause from "effect/Cause";
+import * as Duration from "effect/Duration";
+import * as Scope from "effect/Scope";
+import type { Fx } from "../Fx.js";
+/**
+ * Partitions the stream into non-empty arrays of size `n`. The final array
+ * may be smaller if there are leftover elements.
+ * The size must be a positive safe integer. A group can retain up to `n`
+ * values, so callers own the memory policy for valid sizes. Invalid sizes
+ * fail with `Cause.IllegalArgumentError`.
+ *
+ * Matches Effect `Stream.grouped`.
+ *
+ * @remarks
+ * ## Why
+ * `grouped` exposes fixed-size batching without changing source order. Full groups contain exactly
+ * `n` values. Because failure is delivered to the Sink while `Fx.run` remains infallible, any
+ * partial group is flushed after the source run returns even if a failure was delivered first.
+ *
+ * ## Ownership and lifetime
+ * Each run retains at most `n` values and releases its buffer after the final flush or interruption.
+ * Invalid sizes deliver failure before source acquisition. A terminal observer may interrupt before
+ * the post-failure flush, but a Sink that handles the Cause can receive the partial group afterward.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ * const program = Effect.gen(function* () {
+ *   const deliveries = yield* Ref.make<Array<string>>([])
+ *   const source = Fx.make<number, string>((sink) =>
+ *     sink.onSuccess(1).pipe(Effect.andThen(sink.onFailure(Cause.fail("boom"))))
+ *   )
+ *   yield* Fx.grouped(source, 2).run(Sink.make(
+ *     () => Ref.update(deliveries, (xs) => [...xs, "failure"]),
+ *     (group) => Ref.update(deliveries, (xs) => [...xs, `group:${group.join(",")}`])
+ *   ))
+ *   return yield* Ref.get(deliveries) // ["failure", "group:1"]
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const grouped: {
+    (n: number): <A, E, R>(self: Fx<A, E, R>) => Fx<NonEmptyReadonlyArray<A>, E | Cause.IllegalArgumentError, R>;
+    <A, E, R>(self: Fx<A, E, R>, n: number): Fx<NonEmptyReadonlyArray<A>, E | Cause.IllegalArgumentError, R>;
+};
+/**
+ * Partitions the stream into arrays, emitting when `n` is reached or `duration`
+ * elapses after the first element of the current group.
+ * The size must be a positive safe integer. A group can retain up to `n`
+ * values, so callers own the memory policy for valid sizes. Invalid sizes
+ * fail with `Cause.IllegalArgumentError`.
+ *
+ * Matches Effect `Stream.groupedWithin`.
+ *
+ * @remarks
+ * ## Why
+ * `groupedWithin` bounds a batch by both cardinality and time. The timer starts with the first value,
+ * and whichever boundary wins emits the ordered non-empty group and resets both buffer and timer.
+ * A partial group is also flushed when the source run returns, including after delivered failure.
+ *
+ * ## Ownership and lifetime
+ * Each run retains at most `n` values and at most one timer fiber in the required Scope. A source
+ * failure is Sink delivery, so `flushNow` still runs afterward unless the consumer interrupts the
+ * run. Flushing or interruption cancels the timer; invalid sizes fail before subscription.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ * const source = Fx.make<number, string>((sink) =>
+ *   sink.onSuccess(1).pipe(Effect.andThen(sink.onFailure(Cause.fail("boom"))))
+ * )
+ * const program = Fx.groupedWithin(source, 2, "1 hour").run(
+ *   Sink.make(Effect.logError, (group) => Effect.log(group))
+ * ) // logs the failure, then flushes [1]
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export declare const groupedWithin: {
+    (n: number, duration: Duration.Input): <A, E, R>(self: Fx<A, E, R>) => Fx<NonEmptyReadonlyArray<A>, E | Cause.IllegalArgumentError, R | Scope.Scope>;
+    <A, E, R>(self: Fx<A, E, R>, n: number, duration: Duration.Input): Fx<NonEmptyReadonlyArray<A>, E | Cause.IllegalArgumentError, R | Scope.Scope>;
+};
+//# sourceMappingURL=grouped.d.ts.map

package/dist/Fx/combinators/grouped.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grouped.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/grouped.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAEtC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAK5C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AAItC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAOnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CACE,CAAC,EAAE,MAAM,GACR,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACT,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACd,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,MAAM,GACR,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC;CA8BpE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,aAAa,EAAE;IAC1B,CACE,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE,QAAQ,CAAC,KAAK,GACvB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACT,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KACd,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACnF,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACN,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACjB,CAAC,EAAE,MAAM,EACT,QAAQ,EAAE,QAAQ,CAAC,KAAK,GACvB,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,oBAAoB,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;CA8DlF,CAAC"}

package/dist/Fx/combinators/grouped.js

@@ -0,0 +1,146 @@
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import { dual } from "effect/Function";
+import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
+import { make as makeSink } from "../../Sink/Sink.js";
+import { fail } from "../constructors/fail.js";
+import { make } from "../constructors/make.js";
+import { extendScope } from "../internal/scope.js";
+const isGroupSize = (n) => Number.isSafeInteger(n) && n > 0;
+const invalidGroupSize = () => new Cause.IllegalArgumentError("Group size must be a positive safe integer");
+/**
+ * Partitions the stream into non-empty arrays of size `n`. The final array
+ * may be smaller if there are leftover elements.
+ * The size must be a positive safe integer. A group can retain up to `n`
+ * values, so callers own the memory policy for valid sizes. Invalid sizes
+ * fail with `Cause.IllegalArgumentError`.
+ *
+ * Matches Effect `Stream.grouped`.
+ *
+ * @remarks
+ * ## Why
+ * `grouped` exposes fixed-size batching without changing source order. Full groups contain exactly
+ * `n` values. Because failure is delivered to the Sink while `Fx.run` remains infallible, any
+ * partial group is flushed after the source run returns even if a failure was delivered first.
+ *
+ * ## Ownership and lifetime
+ * Each run retains at most `n` values and releases its buffer after the final flush or interruption.
+ * Invalid sizes deliver failure before source acquisition. A terminal observer may interrupt before
+ * the post-failure flush, but a Sink that handles the Cause can receive the partial group afterward.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect, Ref } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ * const program = Effect.gen(function* () {
+ *   const deliveries = yield* Ref.make<Array<string>>([])
+ *   const source = Fx.make<number, string>((sink) =>
+ *     sink.onSuccess(1).pipe(Effect.andThen(sink.onFailure(Cause.fail("boom"))))
+ *   )
+ *   yield* Fx.grouped(source, 2).run(Sink.make(
+ *     () => Ref.update(deliveries, (xs) => [...xs, "failure"]),
+ *     (group) => Ref.update(deliveries, (xs) => [...xs, `group:${group.join(",")}`])
+ *   ))
+ *   return yield* Ref.get(deliveries) // ["failure", "group:1"]
+ * })
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const grouped = dual(2, (self, n) => {
+    if (!isGroupSize(n)) {
+        return fail(invalidGroupSize());
+    }
+    const size = n;
+    return make((sink) => Effect.gen(function* () {
+        const buffer = [];
+        yield* self.run(makeSink(sink.onFailure, (a) => {
+            buffer.push(a);
+            if (buffer.length >= size) {
+                const group = buffer.splice(0, size);
+                return sink.onSuccess(group);
+            }
+            return Effect.void;
+        }));
+        if (buffer.length > 0) {
+            yield* sink.onSuccess(buffer);
+        }
+    }));
+});
+/**
+ * Partitions the stream into arrays, emitting when `n` is reached or `duration`
+ * elapses after the first element of the current group.
+ * The size must be a positive safe integer. A group can retain up to `n`
+ * values, so callers own the memory policy for valid sizes. Invalid sizes
+ * fail with `Cause.IllegalArgumentError`.
+ *
+ * Matches Effect `Stream.groupedWithin`.
+ *
+ * @remarks
+ * ## Why
+ * `groupedWithin` bounds a batch by both cardinality and time. The timer starts with the first value,
+ * and whichever boundary wins emits the ordered non-empty group and resets both buffer and timer.
+ * A partial group is also flushed when the source run returns, including after delivered failure.
+ *
+ * ## Ownership and lifetime
+ * Each run retains at most `n` values and at most one timer fiber in the required Scope. A source
+ * failure is Sink delivery, so `flushNow` still runs afterward unless the consumer interrupts the
+ * run. Flushing or interruption cancels the timer; invalid sizes fail before subscription.
+ *
+ * @example
+ * ```ts
+ * import { Cause, Effect } from "effect"
+ * import { Fx, Sink } from "@typed/fx"
+ * const source = Fx.make<number, string>((sink) =>
+ *   sink.onSuccess(1).pipe(Effect.andThen(sink.onFailure(Cause.fail("boom"))))
+ * )
+ * const program = Fx.groupedWithin(source, 2, "1 hour").run(
+ *   Sink.make(Effect.logError, (group) => Effect.log(group))
+ * ) // logs the failure, then flushes [1]
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
+export const groupedWithin = dual(3, (self, n, duration) => {
+    if (!isGroupSize(n)) {
+        return fail(invalidGroupSize());
+    }
+    const size = n;
+    return make(Effect.fn(function* (sink) {
+        const ctx = yield* Effect.context();
+        const scope = Context.get(ctx, Scope.Scope);
+        const buffer = yield* Ref.make([]);
+        const timer = yield* Ref.make(null);
+        const clearTimer = Effect.flatMap(Ref.getAndSet(timer, null), (fiber) => fiber ? Fiber.interrupt(fiber) : Effect.void);
+        const emitBuffer = Effect.gen(function* () {
+            const group = yield* Ref.getAndSet(buffer, []);
+            if (group.length > 0) {
+                yield* sink.onSuccess(group);
+            }
+        });
+        const flushNow = clearTimer.pipe(Effect.andThen(emitBuffer));
+        const flushFromTimer = Ref.set(timer, null).pipe(Effect.andThen(emitBuffer));
+        const arm = Effect.flatMap(Effect.forkIn(Effect.sleep(duration).pipe(Effect.andThen(flushFromTimer)), scope, {
+            startImmediately: true,
+            uninterruptible: false,
+        }), (fiber) => Ref.set(timer, fiber));
+        yield* self.run(makeSink(sink.onFailure, (a) => Effect.gen(function* () {
+            const nextLength = yield* Ref.modify(buffer, (current) => {
+                current.push(a);
+                return [current.length, current];
+            });
+            if (nextLength === 1) {
+                yield* arm;
+            }
+            if (nextLength >= size) {
+                yield* flushNow;
+            }
+        })));
+        yield* flushNow;
+    }, extendScope));
+});

package/dist/Fx/combinators/index.d.ts

@@ -1,9 +1,32 @@
+/**
+ * Re-exports the complete public Fx combinator vocabulary.
+ *
+ * @remarks
+ * Importing this module performs no work. Each operation remains lazy until its returned `Fx` is
+ * run, and its leaf declaration documents cardinality, ordering, state, failure, services, and
+ * interruption semantics.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { map, take } from "@typed/fx/Fx"
+ *
+ * const firstLabel = Fx.fromIterable([1, 2]).pipe(map(String), take(1))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export * from "./catch.js";
 export * from "./changesWithEffect.js";
 export * from "./causes.js";
 export * from "./compact.js";
+export * from "./concatMap.js";
 export * from "./continueWith.js";
 export * from "./dropUntil.js";
+export * from "./debounce.js";
+export * from "./delay.js";
+export * from "./during.js";
 export * from "./additive.js";
 export * from "./ensuring.js";
 export * from "./exhaustLatestMap.js";
@@ -26,6 +49,7 @@ export * from "./flatMapEffect.js";
 export * from "./flip.js";
 export * from "./gen.js";
 export * from "./genScoped.js";
+export * from "./grouped.js";
 export * from "./keyed.js";
 export * from "./loop.js";
 export * from "./loopCause.js";
@@ -40,23 +64,34 @@ export * from "./mergeOrdered.js";
 export * from "./onError.js";
 export * from "./onExit.js";
 export * from "./onInterrupt.js";
+export * from "./pairwise.js";
 export * from "./provide.js";
+export * from "./race.js";
+export * from "./repeat.js";
 export * from "./result.js";
+export * from "./retry.js";
+export * from "./sample.js";
 export * from "./scan.js";
 export * from "./skip.js";
 export * from "./skipRepeats.js";
 export * from "./skipWhile.js";
 export * from "./skipRepeatsWith.js";
 export * from "./slice.js";
+export * from "./since.js";
 export * from "./switchMap.js";
 export * from "./switchMapEffect.js";
 export * from "./take.js";
 export * from "./takeUntil.js";
 export * from "./takeWhile.js";
 export * from "./tapEffect.js";
+export * from "./throttle.js";
+export * from "./timeout.js";
 export * from "./tuple.js";
+export * from "./until.js";
 export * from "./unwrap.js";
 export * from "./unwrapScoped.js";
 export * from "./when.js";
+export * from "./withLatestFrom.js";
+export * from "./withSpan.js";
 export * from "./zip.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/Fx/combinators/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/Fx/combinators/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,cAAc,YAAY,CAAC;AAC3B,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC"}

package/dist/Fx/combinators/index.js

@@ -1,9 +1,32 @@
+/**
+ * Re-exports the complete public Fx combinator vocabulary.
+ *
+ * @remarks
+ * Importing this module performs no work. Each operation remains lazy until its returned `Fx` is
+ * run, and its leaf declaration documents cardinality, ordering, state, failure, services, and
+ * interruption semantics.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ * import { map, take } from "@typed/fx/Fx"
+ *
+ * const firstLabel = Fx.fromIterable([1, 2]).pipe(map(String), take(1))
+ * ```
+ *
+ * @since 1.0.0
+ * @category combinators
+ */
 export * from "./catch.js";
 export * from "./changesWithEffect.js";
 export * from "./causes.js";
 export * from "./compact.js";
+export * from "./concatMap.js";
 export * from "./continueWith.js";
 export * from "./dropUntil.js";
+export * from "./debounce.js";
+export * from "./delay.js";
+export * from "./during.js";
 export * from "./additive.js";
 export * from "./ensuring.js";
 export * from "./exhaustLatestMap.js";
@@ -26,6 +49,7 @@ export * from "./flatMapEffect.js";
 export * from "./flip.js";
 export * from "./gen.js";
 export * from "./genScoped.js";
+export * from "./grouped.js";
 export * from "./keyed.js";
 export * from "./loop.js";
 export * from "./loopCause.js";
@@ -40,22 +64,33 @@ export * from "./mergeOrdered.js";
 export * from "./onError.js";
 export * from "./onExit.js";
 export * from "./onInterrupt.js";
+export * from "./pairwise.js";
 export * from "./provide.js";
+export * from "./race.js";
+export * from "./repeat.js";
 export * from "./result.js";
+export * from "./retry.js";
+export * from "./sample.js";
 export * from "./scan.js";
 export * from "./skip.js";
 export * from "./skipRepeats.js";
 export * from "./skipWhile.js";
 export * from "./skipRepeatsWith.js";
 export * from "./slice.js";
+export * from "./since.js";
 export * from "./switchMap.js";
 export * from "./switchMapEffect.js";
 export * from "./take.js";
 export * from "./takeUntil.js";
 export * from "./takeWhile.js";
 export * from "./tapEffect.js";
+export * from "./throttle.js";
+export * from "./timeout.js";
 export * from "./tuple.js";
+export * from "./until.js";
 export * from "./unwrap.js";
 export * from "./unwrapScoped.js";
 export * from "./when.js";
+export * from "./withLatestFrom.js";
+export * from "./withSpan.js";
 export * from "./zip.js";