@typed/fx 2.0.0-beta.1 → 2.0.0-beta.11

package/dist/Fx/constructors/periodic.js

@@ -3,10 +3,39 @@ import { fromSchedule } from "./fromSchedule.js";
 /**
  * Creates an Fx that emits a `void` value periodically.
  *
+ * @remarks
+ * ## Why
+ *
+ * Common interval work can use Effect's
+ * [Schedule](https://effect.website/docs/v4/api/effect/Schedule) clock and
+ * interruption semantics rather than an unmanaged platform timer.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction starts no clock. A run waits `period` before the first emission and
+ * again between every subsequent emission. The run fiber owns the schedule; no ticks
+ * continue after interruption.
+ *
+ * @example
+ * ```ts
+ * import { Effect, Fiber } from "effect"
+ * import * as TestClock from "effect/testing/TestClock"
+ * import { collectUpTo, periodic } from "@typed/fx/Fx"
+ *
+ * const program = Effect.gen(function* () {
+ *   const fiber = yield* Effect.forkChild(collectUpTo(periodic("1 second"), 1))
+ *   yield* TestClock.adjust("999 millis")
+ *   const beforeFirstPeriod = fiber.pollUnsafe()
+ *   yield* TestClock.adjust("1 millis")
+ *   const firstTick = yield* Fiber.join(fiber)
+ *   return { beforeFirstPeriod, firstTick }
+ * })
+ * ```
+ *
  * @param period - The duration between emissions.
  * @returns An `Fx` that emits repeatedly.
  * @since 1.0.0
- * @category constructors
+ * @category Time and rate
  */
 export const periodic = (period) => 
 /*#__PURE__*/ fromSchedule(spaced(period));

package/dist/Fx/constructors/succeed.d.ts

@@ -2,30 +2,102 @@ import type { Fx } from "../Fx.js";
 /**
  * Creates an Fx that emits a single value and then completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * A known value can enter `Fx` composition without adding failure or service
+ * requirements.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction stores the value. Each run offers it exactly once, waits for the sink
+ * handler, and completes without acquiring resources.
+ *
+ * @example
+ * ```ts
+ * import { collectAll, succeed } from "@typed/fx/Fx"
+ *
+ * const program = collectAll(succeed({ status: "ready" }))
+ * ```
+ *
  * @param value - The value to emit.
  * @returns An `Fx` that emits the value.
  * @since 1.0.0
- * @category constructors
+ * @category Value sources
  */
 export declare const succeed: <A>(value: A) => Fx<A>;
 /**
- * An Fx that emits `null` and then completes.
+ * An Fx that emits `null` exactly once and then completes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared constant avoids repeatedly spelling `succeed(null)` in optional-value
+ * compositions. It is also exported as `null`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each run performs one sink delivery and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { first, succeedNull } from "@typed/fx/Fx"
+ *
+ * const program = first(succeedNull)
+ * ```
+ *
  * @since 1.0.0
- * @category constructors
+ * @category Value sources
  */
 export declare const succeedNull: Fx<null, never, never>;
 export { succeedNull as null };
 /**
- * An Fx that emits `undefined` and then completes.
+ * An Fx that emits `undefined` exactly once and then completes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared constant avoids repeatedly spelling `succeed(undefined)` in optional
+ * compositions. It is also exported as `undefined`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each run performs one sink delivery and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { first, succeedUndefined } from "@typed/fx/Fx"
+ *
+ * const program = first(succeedUndefined)
+ * ```
+ *
  * @since 1.0.0
- * @category constructors
+ * @category Value sources
  */
 export declare const succeedUndefined: Fx<undefined, never, never>;
 export { succeedUndefined as undefined };
 /**
- * An Fx that emits `void` and then completes.
+ * An Fx that emits `void` exactly once and then completes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared constant is a completion pulse for operations whose payload is
+ * irrelevant. It is also exported as `void`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each run performs one sink delivery and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { drain, succeedVoid } from "@typed/fx/Fx"
+ *
+ * const program = drain(succeedVoid)
+ * ```
+ *
  * @since 1.0.0
- * @category constructors
+ * @category Value sources
  */
 export declare const succeedVoid: Fx<void, never, never>;
 export { succeedVoid as void };

package/dist/Fx/constructors/succeed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"succeed.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/succeed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,EAAE,CAAC,CAAC,CACc,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,WAAW,wBAAsB,CAAC;AAC/C,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC;AAE/B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAAgC,CAAC;AAC9D,OAAO,EAAE,gBAAgB,IAAI,SAAS,EAAE,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,WAAW,wBAAwB,CAAC;AACjD,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC"}
+{"version":3,"file":"succeed.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/succeed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,CAAC,KAAG,EAAE,CAAC,CAAC,CACc,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,wBAAsB,CAAC;AAC/C,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,gBAAgB,6BAAgC,CAAC;AAC9D,OAAO,EAAE,gBAAgB,IAAI,SAAS,EAAE,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,wBAAwB,CAAC;AACjD,OAAO,EAAE,WAAW,IAAI,IAAI,EAAE,CAAC"}

package/dist/Fx/constructors/succeed.js

@@ -2,31 +2,103 @@ import { make } from "./make.js";
 /**
  * Creates an Fx that emits a single value and then completes.
  *
+ * @remarks
+ * ## Why
+ *
+ * A known value can enter `Fx` composition without adding failure or service
+ * requirements.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction stores the value. Each run offers it exactly once, waits for the sink
+ * handler, and completes without acquiring resources.
+ *
+ * @example
+ * ```ts
+ * import { collectAll, succeed } from "@typed/fx/Fx"
+ *
+ * const program = collectAll(succeed({ status: "ready" }))
+ * ```
+ *
  * @param value - The value to emit.
  * @returns An `Fx` that emits the value.
  * @since 1.0.0
- * @category constructors
+ * @category Value sources
  */
 export const succeed = (value) => 
 /*#__PURE__*/ make((sink) => sink.onSuccess(value));
 /**
- * An Fx that emits `null` and then completes.
+ * An Fx that emits `null` exactly once and then completes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared constant avoids repeatedly spelling `succeed(null)` in optional-value
+ * compositions. It is also exported as `null`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each run performs one sink delivery and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { first, succeedNull } from "@typed/fx/Fx"
+ *
+ * const program = first(succeedNull)
+ * ```
+ *
  * @since 1.0.0
- * @category constructors
+ * @category Value sources
  */
 export const succeedNull = succeed(null);
 export { succeedNull as null };
 /**
- * An Fx that emits `undefined` and then completes.
+ * An Fx that emits `undefined` exactly once and then completes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared constant avoids repeatedly spelling `succeed(undefined)` in optional
+ * compositions. It is also exported as `undefined`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each run performs one sink delivery and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { first, succeedUndefined } from "@typed/fx/Fx"
+ *
+ * const program = first(succeedUndefined)
+ * ```
+ *
  * @since 1.0.0
- * @category constructors
+ * @category Value sources
  */
 export const succeedUndefined = succeed(undefined);
 export { succeedUndefined as undefined };
 /**
- * An Fx that emits `void` and then completes.
+ * An Fx that emits `void` exactly once and then completes.
+ *
+ * @remarks
+ * ## Why
+ *
+ * The shared constant is a completion pulse for operations whose payload is
+ * irrelevant. It is also exported as `void`.
+ *
+ * ## Ownership and lifetime
+ *
+ * Each run performs one sink delivery and acquires no resources.
+ *
+ * @example
+ * ```ts
+ * import { drain, succeedVoid } from "@typed/fx/Fx"
+ *
+ * const program = drain(succeedVoid)
+ * ```
+ *
  * @since 1.0.0
- * @category constructors
+ * @category Value sources
  */
 export const succeedVoid = succeed(void 0);
 export { succeedVoid as void };

package/dist/Fx/constructors/suspend.d.ts

@@ -1,3 +1,31 @@
 import type { Fx } from "../Fx.js";
+/**
+ * Defers creation of an `Fx` until each run begins.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Recursive producers and producers whose definition depends on fresh mutable state
+ * need laziness at the `Fx` boundary, not merely laziness of a value emission.
+ *
+ * ## Ownership and lifetime
+ *
+ * `fx` is not evaluated during construction. It is evaluated once per run inside
+ * `Effect.suspend`; thrown exceptions become Effect defects, and the returned
+ * producer is owned and interrupted as part of that same run.
+ *
+ * @example
+ * ```ts
+ * import { collectAll, succeed, suspend } from "@typed/fx/Fx"
+ *
+ * let next = 0
+ * const source = suspend(() => succeed(++next))
+ * const firstRun = collectAll(source)
+ * const secondRun = collectAll(source)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Value sources
+ */
 export declare const suspend: <A, E, R>(fx: () => Fx<A, E, R>) => Fx<A, E, R>;
 //# sourceMappingURL=suspend.d.ts.map

package/dist/Fx/constructors/suspend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suspend.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/suspend.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CACJ,CAAC"}
+{"version":3,"file":"suspend.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/suspend.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CACJ,CAAC"}

package/dist/Fx/constructors/suspend.js

@@ -1,3 +1,31 @@
 import * as Effect from "effect/Effect";
 import { make } from "./make.js";
+/**
+ * Defers creation of an `Fx` until each run begins.
+ *
+ * @remarks
+ * ## Why
+ *
+ * Recursive producers and producers whose definition depends on fresh mutable state
+ * need laziness at the `Fx` boundary, not merely laziness of a value emission.
+ *
+ * ## Ownership and lifetime
+ *
+ * `fx` is not evaluated during construction. It is evaluated once per run inside
+ * `Effect.suspend`; thrown exceptions become Effect defects, and the returned
+ * producer is owned and interrupted as part of that same run.
+ *
+ * @example
+ * ```ts
+ * import { collectAll, succeed, suspend } from "@typed/fx/Fx"
+ *
+ * let next = 0
+ * const source = suspend(() => succeed(++next))
+ * const firstRun = collectAll(source)
+ * const secondRun = collectAll(source)
+ * ```
+ *
+ * @since 1.0.0
+ * @category Value sources
+ */
 export const suspend = (fx) => make((sink) => Effect.suspend(() => fx().run(sink)));

package/dist/Fx/constructors/sync.d.ts

@@ -0,0 +1,32 @@
+import type { Fx } from "../Fx.js";
+/**
+ * Lazily evaluates a synchronous function once for each Fx run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `sync` is the direct constructor for one value that must be computed at run time,
+ * such as a fresh DOM node or a snapshot read from an imperative API. Unlike
+ * `succeed`, it does not evaluate the function while the Fx is being assembled.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction performs no work. Each run evaluates `evaluate` exactly once in the
+ * run's fiber, emits its result, and completes after the Sink handles it. A thrown
+ * exception is an Effect defect; use `Fx.fromEffect(Effect.try(...))` when failure is
+ * expected and belongs in the typed error channel.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const element = Fx.sync(() => document.createElement("div"))
+ * ```
+ *
+ * @param evaluate - The synchronous function evaluated once per run.
+ * @returns An Fx that emits the freshly evaluated value.
+ * @since 2.0.0
+ * @category Value sources
+ */
+export declare const sync: <A>(evaluate: () => A) => Fx<A>;
+//# sourceMappingURL=sync.d.ts.map

package/dist/Fx/constructors/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/Fx/constructors/sync.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,UAAU,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,YAAY,MAAM,CAAC,KAAG,EAAE,CAAC,CAAC,CAAsC,CAAC"}

package/dist/Fx/constructors/sync.js

@@ -0,0 +1,32 @@
+import * as Effect from "effect/Effect";
+import { fromEffect } from "./fromEffect.js";
+/**
+ * Lazily evaluates a synchronous function once for each Fx run.
+ *
+ * @remarks
+ * ## Why
+ *
+ * `sync` is the direct constructor for one value that must be computed at run time,
+ * such as a fresh DOM node or a snapshot read from an imperative API. Unlike
+ * `succeed`, it does not evaluate the function while the Fx is being assembled.
+ *
+ * ## Ownership and lifetime
+ *
+ * Construction performs no work. Each run evaluates `evaluate` exactly once in the
+ * run's fiber, emits its result, and completes after the Sink handles it. A thrown
+ * exception is an Effect defect; use `Fx.fromEffect(Effect.try(...))` when failure is
+ * expected and belongs in the typed error channel.
+ *
+ * @example
+ * ```ts
+ * import { Fx } from "@typed/fx"
+ *
+ * const element = Fx.sync(() => document.createElement("div"))
+ * ```
+ *
+ * @param evaluate - The synchronous function evaluated once per run.
+ * @returns An Fx that emits the freshly evaluated value.
+ * @since 2.0.0
+ * @category Value sources
+ */
+export const sync = (evaluate) => fromEffect(Effect.sync(evaluate));