effect 2.0.0-next.37 → 2.0.0-next.38

package/dist/TestClock-ab72e391.esm.js

@@ -0,0 +1,565 @@
+import { p as prepend, s as map$1, v as sort, h as isNonEmpty, j as headNonEmpty, t as tailNonEmpty, e as empty$1 } from './Chunk-4c1f4599.esm.js';
+import { T as Tag, g as get$1 } from './Context-c41aa832.esm.js';
+import { d as decode, t as toMillis, s as seconds, m as millis } from './Duration-98bca14c.esm.js';
+import { e as equals } from './Equal-2a99fde3.esm.js';
+import { i as isDone, a as isSuspended } from './FiberStatus-7a24d5ef.esm.js';
+import { p as pipe, i as identity, b as constVoid, d as dual } from './Function-12511160.esm.js';
+import { e as empty, s as set$1 } from './HashMap-6c230bde.esm.js';
+import { C as ClockTypeId, c as currentServices, a as clockTag } from './defaultServices-b9ca1236.esm.js';
+import { m as map, z as zipRight, f as flatMap, d as deferredMake, b as deferredAwait, g as deferredSucceed, c as asUnit, j as succeed, V as fail, Y as interruptible, aj as as, $ as interruptFiber, J as zip, aU as zipWith, aP as yieldNow, p as unit, v as fiberRefGetWith, s as sync } from './core-64ab7ff5.esm.js';
+import { r as reduce, aL as logWarning, a0 as delay, a1 as sleep$1, al as filterOrFail, E as eventually, s as gen } from './core-effect-57445976.esm.js';
+import { q as makeSynchronized } from './circular-08fb0138.esm.js';
+import { V as zipLeftOptions, E as fork, J as withClockScoped, q as addFinalizer } from './fiberRuntime-bfcf5f49.esm.js';
+import { U as scoped } from './layer-35828af7.esm.js';
+import { e as get, E as unsafeGet, c as set, h as modify, d as unsafeMake } from './Ref-5eefaff1.esm.js';
+import { e as updateSomeEffect } from './synchronizedRef-1ceb6bd3.esm.js';
+import { O as Order } from './Number-4b836a09.esm.js';
+import { s as some, n as none } from './Option-df40d2b9.esm.js';
+import { m as mapInput } from './Order-a875fe30.esm.js';
+import { a as TestAnnotations } from './TestAnnotations-39f7e011.esm.js';
+import { a as TestLive } from './TestLive-61a5e471.esm.js';
+
+/** @internal */
+
+/** @internal */
+const OP_SUSPENDED_WARNING_DATA_START = "Start";
+
+/** @internal */
+
+/** @internal */
+const OP_SUSPENDED_WARNING_DATA_PENDING = "Pending";
+
+/** @internal */
+
+/** @internal */
+const OP_SUSPENDED_WARNING_DATA_DONE = "Done";
+
+/** @internal */
+
+/** @internal */
+
+/** @internal */
+
+/** @internal */
+
+/**
+ * State indicating that a test has not adjusted the clock.
+ *
+ * @internal
+ */
+const start$1 = {
+  _tag: OP_SUSPENDED_WARNING_DATA_START
+};
+
+/**
+ * State indicating that a test has adjusted the clock but a fiber is still
+ * running with a reference to the fiber that will display the warning
+ * message.
+ *
+ * @internal
+ */
+const pending$1 = fiber => {
+  return {
+    _tag: OP_SUSPENDED_WARNING_DATA_PENDING,
+    fiber
+  };
+};
+
+/**
+ * State indicating that the warning message has already been displayed.
+ *
+ * @internal
+ */
+const done$1 = {
+  _tag: OP_SUSPENDED_WARNING_DATA_DONE
+};
+
+/** @internal */
+const isStart$1 = self => {
+  return self._tag === OP_SUSPENDED_WARNING_DATA_START;
+};
+
+/** @internal */
+const isPending$1 = self => {
+  return self._tag === OP_SUSPENDED_WARNING_DATA_PENDING;
+};
+
+/**
+ * `WarningData` describes the state of the warning message that is displayed
+ * if a test is using time by is not advancing the `TestClock`. The possible
+ * states are `Start` if a test has not used time, `Pending` if a test has
+ * used time but has not adjusted the `TestClock`, and `Done` if a test has
+ * adjusted the `TestClock` or the warning message has already been displayed.
+ *
+ * @internal
+ */
+
+/** @internal */
+const OP_WARNING_DATA_START = "Start";
+
+/** @internal */
+
+/** @internal */
+const OP_WARNING_DATA_PENDING = "Pending";
+
+/** @internal */
+
+/** @internal */
+const OP_WARNING_DATA_DONE = "Done";
+
+/** @internal */
+
+/** @internal */
+
+/** @internal */
+
+/** @internal */
+
+/**
+ * State indicating that a test has not used time.
+ *
+ * @internal
+ */
+const start = {
+  _tag: OP_WARNING_DATA_START
+};
+
+/**
+ * State indicating that a test has used time but has not adjusted the
+ * `TestClock` with a reference to the fiber that will display the warning
+ * message.
+ *
+ * @internal
+ */
+const pending = fiber => {
+  return {
+    _tag: OP_WARNING_DATA_PENDING,
+    fiber
+  };
+};
+
+/**
+ * State indicating that a test has used time or the warning message has
+ * already been displayed.
+ *
+ * @internal
+ */
+const done = {
+  _tag: OP_WARNING_DATA_DONE
+};
+
+/** @internal */
+const isStart = self => {
+  return self._tag === OP_WARNING_DATA_START;
+};
+
+/** @internal */
+const isPending = self => {
+  return self._tag === OP_WARNING_DATA_PENDING;
+};
+
+/**
+ * @since 2.0.0
+ */
+
+/**
+ * A `TestClock` makes it easy to deterministically and efficiently test effects
+ * involving the passage of time.
+ *
+ * Instead of waiting for actual time to pass, `sleep` and methods implemented
+ * in terms of it schedule effects to take place at a given clock time. Users
+ * can adjust the clock time using the `adjust` and `setTime` methods, and all
+ * effects scheduled to take place on or before that time will automatically be
+ * run in order.
+ *
+ * For example, here is how we can test `Effect.timeout` using `TestClock`:
+ *
+ * ```ts
+ * import * as Duration from "effect/Duration"
+ * import * as Effect from "effect/Effect"
+ * import * as Fiber from "effect/Fiber"
+ * import * as TestClock from "effect/TestClock"
+ * import * as Option from "effect/Option"
+ *
+ * Effect.gen(function*() {
+ *   const fiber = yield* pipe(
+ *     Effect.sleep(Duration.minutes(5)),
+ *     Effect.timeout(Duration.minutes(1)),
+ *     Effect.fork
+ *   )
+ *   yield* TestClock.adjust(Duration.minutes(1))
+ *   const result = yield* Fiber.join(fiber)
+ *   assert.deepStrictEqual(result, Option.none())
+ * })
+ * ```
+ *
+ * Note how we forked the fiber that `sleep` was invoked on. Calls to `sleep`
+ * and methods derived from it will semantically block until the time is set to
+ * on or after the time they are scheduled to run. If we didn't fork the fiber
+ * on which we called sleep we would never get to set the time on the line
+ * below. Thus, a useful pattern when using `TestClock` is to fork the effect
+ * being tested, then adjust the clock time, and finally verify that the
+ * expected effects have been performed.
+ *
+ * @since 2.0.0
+ */
+
+/**
+ * `Data` represents the state of the `TestClock`, including the clock time.
+ *
+ * @since 2.0.1
+ */
+
+/**
+ * @since 2.0.0
+ */
+const makeData = (instant, sleeps) => ({
+  instant,
+  sleeps
+});
+
+/**
+ * @since 2.0.0
+ */
+const TestClock = /*#__PURE__*/Tag( /*#__PURE__*/Symbol.for("effect/TestClock"));
+
+/**
+ * The warning message that will be displayed if a test is using time but is
+ * not advancing the `TestClock`.
+ *
+ * @internal
+ */
+const warning = "Warning: A test is using time, but is not advancing " + "the test clock, which may result in the test hanging. Use TestClock.adjust to " + "manually advance the time.";
+
+/**
+ * The warning message that will be displayed if a test is advancing the clock
+ * but a fiber is still running.
+ *
+ * @internal
+ */
+const suspendedWarning = "Warning: A test is advancing the test clock, " + "but a fiber is not suspending, which may result in the test hanging. Use " + "TestAspect.diagnose to identity the fiber that is not suspending.";
+
+/** @internal */
+class TestClockImpl {
+  [ClockTypeId] = ClockTypeId;
+  constructor(clockState, live, annotations, warningState, suspendedWarningState) {
+    this.clockState = clockState;
+    this.live = live;
+    this.annotations = annotations;
+    this.warningState = warningState;
+    this.suspendedWarningState = suspendedWarningState;
+    this.currentTimeMillis = map(get(this.clockState), data => data.instant);
+    this.currentTimeNanos = map(get(this.clockState), data => BigInt(data.instant * 1000000));
+  }
+
+  /**
+   * Unsafely returns the current time in milliseconds.
+   */
+  unsafeCurrentTimeMillis() {
+    return unsafeGet(this.clockState).instant;
+  }
+
+  /**
+   * Unsafely returns the current time in nanoseconds.
+   */
+  unsafeCurrentTimeNanos() {
+    return BigInt(unsafeGet(this.clockState).instant * 1000000);
+  }
+
+  /**
+   * Returns the current clock time in milliseconds.
+   */
+
+  /**
+   * Returns the current clock time in nanoseconds.
+   */
+
+  /**
+   * Saves the `TestClock`'s current state in an effect which, when run, will
+   * restore the `TestClock` state to the saved state.
+   */
+  save() {
+    return map(get(this.clockState), data => set(this.clockState, data));
+  }
+  /**
+   * Sets the current clock time to the specified instant. Any effects that
+   * were scheduled to occur on or before the new time will be run in order.
+   */
+  setTime(instant) {
+    return zipRight(this.warningDone(), this.run(() => instant));
+  }
+  /**
+   * Semantically blocks the current fiber until the clock time is equal to or
+   * greater than the specified duration. Once the clock time is adjusted to
+   * on or after the duration, the fiber will automatically be resumed.
+   */
+  sleep(durationInput) {
+    const duration = decode(durationInput);
+    return flatMap(deferredMake(), deferred => pipe(modify(this.clockState, data => {
+      const end = data.instant + toMillis(duration);
+      if (end > data.instant) {
+        return [true, makeData(data.instant, pipe(data.sleeps, prepend([end, deferred])))];
+      }
+      return [false, data];
+    }), flatMap(shouldAwait => shouldAwait ? pipe(this.warningStart(), zipRight(deferredAwait(deferred))) : pipe(deferredSucceed(deferred, void 0), asUnit))));
+  }
+  /**
+   * Returns a list of the times at which all queued effects are scheduled to
+   * resume.
+   */
+  sleeps() {
+    return map(get(this.clockState), data => map$1(data.sleeps, _ => _[0]));
+  }
+  /**
+   * Increments the current clock time by the specified duration. Any effects
+   * that were scheduled to occur on or before the new time will be run in
+   * order.
+   */
+  adjust(durationInput) {
+    const duration = decode(durationInput);
+    return zipRight(this.warningDone(), this.run(n => n + toMillis(duration)));
+  }
+  /**
+   * Increments the current clock time by the specified duration. Any effects
+   * that were scheduled to occur on or before the new time will be run in
+   * order.
+   */
+  adjustWith(durationInput) {
+    const duration = decode(durationInput);
+    return effect => zipLeftOptions(effect, this.adjust(duration), {
+      concurrent: true
+    });
+  }
+  /**
+   * Returns a set of all fibers in this test.
+   */
+  supervisedFibers() {
+    return this.annotations.supervisedFibers();
+  }
+  /**
+   * Captures a "snapshot" of the identifier and status of all fibers in this
+   * test other than the current fiber. Fails with the `Unit` value if any of
+   * these fibers are not done or suspended. Note that because we cannot
+   * synchronize on the status of multiple fibers at the same time this
+   * snapshot may not be fully consistent.
+   */
+  freeze() {
+    return flatMap(this.supervisedFibers(), fibers => pipe(fibers, reduce(empty(), (map, fiber) => pipe(fiber.status(), flatMap(status => {
+      if (isDone(status)) {
+        return succeed(set$1(map, fiber.id(), status));
+      }
+      if (isSuspended(status)) {
+        return succeed(set$1(map, fiber.id(), status));
+      }
+      return fail(void 0);
+    })))));
+  }
+  /**
+   * Forks a fiber that will display a warning message if a test is using time
+   * but is not advancing the `TestClock`.
+   */
+  warningStart() {
+    return updateSomeEffect(this.warningState, data => isStart(data) ? some(pipe(this.live.provide(pipe(logWarning(warning), delay(seconds(5)))), interruptible, fork, map(fiber => pending(fiber)))) : none());
+  }
+  /**
+   * Cancels the warning message that is displayed if a test is using time but
+   * is not advancing the `TestClock`.
+   */
+  warningDone() {
+    return updateSomeEffect(this.warningState, warningData => {
+      if (isStart(warningData)) {
+        return some(succeed(done));
+      }
+      if (isPending(warningData)) {
+        return some(pipe(interruptFiber(warningData.fiber), as(done)));
+      }
+      return none();
+    });
+  }
+  /**
+   * Returns whether all descendants of this fiber are done or suspended.
+   */
+  suspended() {
+    return pipe(this.freeze(), zip(this.live.provide(pipe(sleep$1(millis(5)), zipRight(this.freeze())))), flatMap(([first, last]) => equals(first, last) ? succeed(first) : fail(void 0)));
+  }
+  /**
+   * Polls until all descendants of this fiber are done or suspended.
+   */
+  awaitSuspended() {
+    return pipe(this.suspendedWarningStart(), zipRight(pipe(this.suspended(), zipWith(pipe(this.live.provide(sleep$1(millis(10))), zipRight(this.suspended())), equals), filterOrFail(identity, constVoid), eventually)), zipRight(this.suspendedWarningDone()));
+  }
+  /**
+   * Forks a fiber that will display a warning message if a test is advancing
+   * the `TestClock` but a fiber is not suspending.
+   */
+  suspendedWarningStart() {
+    return updateSomeEffect(this.suspendedWarningState, suspendedWarningData => {
+      if (isStart$1(suspendedWarningData)) {
+        return some(pipe(this.live.provide(pipe(logWarning(suspendedWarning), zipRight(set(this.suspendedWarningState, done$1)), delay(seconds(5)))), interruptible, fork, map(fiber => pending$1(fiber))));
+      }
+      return none();
+    });
+  }
+  /**
+   * Cancels the warning message that is displayed if a test is advancing the
+   * `TestClock` but a fiber is not suspending.
+   */
+  suspendedWarningDone() {
+    return updateSomeEffect(this.suspendedWarningState, suspendedWarningData => {
+      if (isPending$1(suspendedWarningData)) {
+        return some(pipe(interruptFiber(suspendedWarningData.fiber), as(start$1)));
+      }
+      return none();
+    });
+  }
+  /**
+   * Runs all effects scheduled to occur on or before the specified instant,
+   * which may depend on the current time, in order.
+   */
+  run(f) {
+    return pipe(this.awaitSuspended(), zipRight(pipe(modify(this.clockState, data => {
+      const end = f(data.instant);
+      const sorted = pipe(data.sleeps, sort(pipe(Order, mapInput(_ => _[0]))));
+      if (isNonEmpty(sorted)) {
+        const [instant, deferred] = headNonEmpty(sorted);
+        if (instant <= end) {
+          return [some([end, deferred]), makeData(instant, tailNonEmpty(sorted))];
+        }
+      }
+      return [none(), makeData(end, data.sleeps)];
+    }), flatMap(option => {
+      switch (option._tag) {
+        case "None":
+          {
+            return unit;
+          }
+        case "Some":
+          {
+            const [end, deferred] = option.value;
+            return pipe(deferredSucceed(deferred, void 0), zipRight(yieldNow()), zipRight(this.run(() => end)));
+          }
+      }
+    }))));
+  }
+}
+
+/**
+ * @since 2.0.0
+ */
+const live = data => scoped(TestClock, gen(function* ($) {
+  const live = yield* $(TestLive);
+  const annotations = yield* $(TestAnnotations);
+  const clockState = yield* $(sync(() => unsafeMake(data)));
+  const warningState = yield* $(makeSynchronized(start));
+  const suspendedWarningState = yield* $(makeSynchronized(start$1));
+  const testClock = new TestClockImpl(clockState, live, annotations, warningState, suspendedWarningState);
+  yield* $(withClockScoped(testClock));
+  yield* $(addFinalizer(() => zipRight(testClock.warningDone(), testClock.suspendedWarningDone())));
+  return testClock;
+}));
+
+/**
+ * @since 2.0.0
+ */
+const defaultTestClock = /*#__PURE__*/live( /*#__PURE__*/makeData( /*#__PURE__*/new Date(0).getTime(), /*#__PURE__*/empty$1()));
+
+/**
+ * Accesses a `TestClock` instance in the context and increments the time
+ * by the specified duration, running any actions scheduled for on or before
+ * the new time in order.
+ *
+ * @since 2.0.0
+ */
+const adjust = durationInput => {
+  const duration = decode(durationInput);
+  return testClockWith(testClock => testClock.adjust(duration));
+};
+
+/**
+ * @since 2.0.0
+ */
+const adjustWith = /*#__PURE__*/dual(2, (effect, durationInput) => {
+  const duration = decode(durationInput);
+  return testClockWith(testClock => testClock.adjustWith(duration)(effect));
+});
+
+/**
+ * Accesses a `TestClock` instance in the context and saves the clock
+ * state in an effect which, when run, will restore the `TestClock` to the
+ * saved state.
+ *
+ * @since 2.0.0
+ */
+const save = () => testClockWith(testClock => testClock.save());
+
+/**
+ * Accesses a `TestClock` instance in the context and sets the clock time
+ * to the specified `Instant`, running any actions scheduled for on or before
+ * the new time in order.
+ *
+ * @since 2.0.0
+ */
+const setTime = instant => testClockWith(testClock => testClock.setTime(instant));
+
+/**
+ * Semantically blocks the current fiber until the clock time is equal to or
+ * greater than the specified duration. Once the clock time is adjusted to
+ * on or after the duration, the fiber will automatically be resumed.
+ *
+ * @since 2.0.0
+ */
+const sleep = durationInput => {
+  const duration = decode(durationInput);
+  return testClockWith(testClock => testClock.sleep(duration));
+};
+
+/**
+ * Accesses a `TestClock` instance in the context and returns a list of
+ * times that effects are scheduled to run.
+ *
+ * @since 2.0.0
+ */
+const sleeps = () => testClockWith(testClock => testClock.sleeps());
+
+/**
+ * Retrieves the `TestClock` service for this test.
+ *
+ * @since 2.0.0
+ */
+const testClock = () => testClockWith(succeed);
+
+/**
+ * Retrieves the `TestClock` service for this test and uses it to run the
+ * specified workflow.
+ *
+ * @since 2.0.0
+ */
+const testClockWith = f => fiberRefGetWith(currentServices, services => f(pipe(services, get$1(clockTag))));
+
+/**
+ * Accesses the current time of a `TestClock` instance in the context in
+ * milliseconds.
+ *
+ * @since 2.0.0
+ */
+const currentTimeMillis = /*#__PURE__*/testClockWith(testClock => testClock.currentTimeMillis);
+
+var TestClock$1 = /*#__PURE__*/Object.freeze({
+  __proto__: null,
+  makeData: makeData,
+  TestClock: TestClock,
+  TestClockImpl: TestClockImpl,
+  live: live,
+  defaultTestClock: defaultTestClock,
+  adjust: adjust,
+  adjustWith: adjustWith,
+  save: save,
+  setTime: setTime,
+  sleep: sleep,
+  sleeps: sleeps,
+  testClock: testClock,
+  testClockWith: testClockWith,
+  currentTimeMillis: currentTimeMillis
+});
+
+export { TestClock$1 as T, TestClock as a, TestClockImpl as b, adjust as c, defaultTestClock as d, adjustWith as e, setTime as f, sleep as g, sleeps as h, testClockWith as i, currentTimeMillis as j, live as l, makeData as m, save as s, testClock as t };