effect 4.0.0-rc.112 → 4.0.0-rc.113

package/dist/unstable/arbitrary/Arbitrary.js

@@ -0,0 +1,238 @@
+/**
+ * Derives, samples, and checks generated values from Effect Schema.
+ *
+ * @since 4.0.0
+ */
+import * as Cause from "../../Cause.js";
+import * as Formatter from "../../Formatter.js";
+import { dual } from "../../Function.js";
+import * as Internal from "../../internal/arbitrary/runner.js";
+import { hasProperty } from "../../Predicate.js";
+/**
+ * Runtime type identifier for `Arbitrary` values.
+ *
+ * @category type IDs
+ * @since 4.0.0
+ */
+export const TypeId = Internal.TypeId;
+/**
+ * Checks whether a value is an `Arbitrary`.
+ *
+ * **When to use**
+ *
+ * Use when accepting both Arbitrary values and other input descriptions.
+ *
+ * @category guards
+ * @since 4.0.0
+ */
+export const isArbitrary = u => hasProperty(u, TypeId);
+/**
+ * Formats an unsuccessful property-check result as a diagnostic message, returning `undefined` for a passed result.
+ *
+ * **When to use**
+ *
+ * Use when integrating `checkEffect` with a test runner or another reporting interface.
+ *
+ * @category converting
+ * @since 4.0.0
+ */
+export function formatCheckFailure(result) {
+  switch (result._tag) {
+    case "Passed":
+      return undefined;
+    case "Falsified":
+      return `Property falsified after ${result.runs} run(s) and ${result.shrinks} shrink(s)\n` + `Shrunk input: ${Formatter.format(result.shrunkInput, {
+        space: 2
+      })}\n` + `${result.failure._tag === "ReturnedFalse" ? "Failure: returned false" : `Failure: ${Cause.isCause(result.failure.error) ? Cause.pretty(result.failure.error) : Formatter.format(result.failure.error, {
+        space: 2
+      })}`}\n` + `Replay: ${result.replay}`;
+    case "Exhausted":
+      return `Property exhausted after ${result.runs} run(s) and ${result.discards} discard(s)\n` + `Seed: ${Formatter.format(result.seed, {
+        space: 2
+      })}`;
+    case "ReplayMismatch":
+      return `Property replay failed: ${result.reason}`;
+  }
+}
+/**
+ * Derives an `Arbitrary` from the decoded `Type` of a Schema.
+ *
+ * **When to use**
+ *
+ * Use when you want Schema-aware generation without exposing a third-party property-testing engine.
+ *
+ * **Details**
+ *
+ * When `options.shrink` is provided, generated roots still come from Schema derivation, while the callback defines the
+ * complete shrink tree. Invalid candidates are skipped and count against `maxShrinks` without reaching the property.
+ *
+ * **Gotchas**
+ *
+ * Derivation is immediate and throws when the current unstable implementation cannot compile the Schema or prove a
+ * finite route through a recursive component.
+ *
+ * A custom shrinker replaces Schema-derived shrinking. It is evaluated lazily after a property failure and must be
+ * synchronous, deterministic, terminating, and free of mutation.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export function schema(schema, options) {
+  return Internal.schema(schema, options);
+}
+/**
+ * Creates an `Arbitrary` that always generates `value` and has no shrink candidates.
+ *
+ * **When to use**
+ *
+ * Use when a branch of dependent generation should produce an already constructed value.
+ *
+ * **Gotchas**
+ *
+ * Every generation returns the same value. Objects are not cloned, so properties must not mutate them.
+ *
+ * @see {@link flatMap} for selecting dependent Arbitraries
+ * @category constructors
+ * @since 4.0.0
+ */
+export function Constant(value) {
+  return Internal.constant(value);
+}
+/**
+ * Transforms every generated value and its shrink candidates.
+ *
+ * **When to use**
+ *
+ * Use when you want to derive generated values from an existing `Arbitrary` without changing its generation or shrink
+ * structure.
+ *
+ * @category mapping
+ * @since 4.0.0
+ */
+export const map = /*#__PURE__*/dual(2, (self, f) => Internal.map(self, f));
+/**
+ * Keeps generated values and shrink candidates that satisfy a predicate or refinement.
+ *
+ * **When to use**
+ *
+ * Use when a condition cannot be expressed constructively by the source Schema or after values have been transformed.
+ *
+ * **Gotchas**
+ *
+ * Rejected generated values count against `maxDiscards`. Prefer Schema checks when possible because the Schema compiler
+ * may generate matching values directly.
+ *
+ * @see {@link filterMap} for transforming and filtering simultaneously
+ * @category filtering
+ * @since 4.0.0
+ */
+export const filter = /*#__PURE__*/dual(2, (self, predicate) => Internal.filter(self, predicate));
+/**
+ * Transforms accepted generated values and discards rejected values.
+ *
+ * **When to use**
+ *
+ * Use when transformation and validation need to happen in one step after constructing an `Arbitrary`.
+ *
+ * **Gotchas**
+ *
+ * Failed filters discard generated roots and count against `maxDiscards`. Failures are not exposed in sampling or
+ * checking results.
+ *
+ * @see {@link map} for transformations that cannot reject
+ * @see {@link filter} for retaining original values that satisfy a condition
+ * @category filtering
+ * @since 4.0.0
+ */
+export const filterMap = /*#__PURE__*/dual(2, (self, f) => Internal.filterMap(self, f));
+/**
+ * Sequentially selects an `Arbitrary` from a generated value.
+ *
+ * **When to use**
+ *
+ * Use when the domain or shape of a generated value depends on another generated value.
+ *
+ * **Details**
+ *
+ * Shrinking first tries smaller source values and regenerates their dependent Arbitraries. It then shrinks the
+ * selected dependent value. After a dependent shrink is selected, source shrinking is closed for that branch.
+ *
+ * **Gotchas**
+ *
+ * The callback must be synchronous, deterministic, and terminating. It can be evaluated again during shrinking and
+ * replay. Deriving a Schema inside the callback also repeats that derivation, so precompile finite dependent
+ * Arbitraries when possible.
+ *
+ * @see {@link map} for total transformations that do not select another Arbitrary
+ * @see {@link Constant} for dependent branches that return an existing value
+ * @category sequencing
+ * @since 4.0.0
+ */
+export const flatMap = /*#__PURE__*/dual(2, (self, f) => Internal.flatMap(self, f));
+/**
+ * Combines Arbitraries into one `Arbitrary` whose generated value mirrors the input shape.
+ *
+ * **When to use**
+ *
+ * Use when you need to generate several independent values together.
+ *
+ * **Details**
+ *
+ * Accepts a tuple or array, an iterable, or a record of Arbitraries. Tuple positions and record keys are preserved in
+ * the generated value. Members are generated in a randomized internal order so recursive members share the generation
+ * budget fairly, while shrinking changes one member at a time.
+ *
+ * **Gotchas**
+ *
+ * Iterable inputs are consumed when `all` is called. If any member discards a generated root, the complete generated
+ * value is discarded.
+ *
+ * @category constructors
+ * @since 4.0.0
+ */
+export function all(input) {
+  return Internal.all(input);
+}
+/**
+ * Generates a bounded collection of values from an `Arbitrary`.
+ *
+ * **When to use**
+ *
+ * Use when you need generated examples without running a property.
+ *
+ * @category running
+ * @since 4.0.0
+ */
+export function sampleEffect(self, options) {
+  return Internal.sampleEffect(self, options);
+}
+/**
+ * Checks a pure or effectful property and shrinks the first falsification.
+ *
+ * **When to use**
+ *
+ * Use when you want deterministic, interruptible property checking with typed property failures and replay.
+ *
+ * **Details**
+ *
+ * Returning `false` and failing an Effect are shrinkable falsifications. Shrinking preserves which of these two
+ * failure classes caused the initial falsification. Typed error values may change while shrinking and are not compared
+ * for equality. Defects and interruption continue through the returned Effect instead of becoming `CheckResult`
+ * values.
+ *
+ * **Gotchas**
+ *
+ * Properties must treat generated values as immutable. The runner does not clone values before evaluation, so
+ * mutation can change reported shrunk inputs or interfere with shrinking and replay.
+ *
+ * A property must also produce the same outcome for the same input and initial environment. The runner may evaluate
+ * it repeatedly and does not restore mutable services between evaluations. Stateful properties should acquire and
+ * release an independent fixture inside each evaluation.
+ *
+ * @category running
+ * @since 4.0.0
+ */
+export function checkEffect(self, property, options) {
+  return Internal.checkEffect(self, property, options);
+}
+//# sourceMappingURL=Arbitrary.js.map

package/dist/unstable/arbitrary/Arbitrary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Arbitrary.js","names":[],"sources":["../../../src/unstable/arbitrary/Arbitrary.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/unstable/arbitrary/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @since 4.0.0
+ */
+/**
+ * @since 4.0.0
+ */
+export * as Arbitrary from "./Arbitrary.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/unstable/arbitrary/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/unstable/arbitrary/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,OAAO,KAAK,SAAS,MAAM,gBAAgB,CAAA"}

package/dist/unstable/arbitrary/index.js

@@ -0,0 +1,9 @@
+/**
+ * @since 4.0.0
+ */
+// @barrel: Auto-generated exports. Do not edit manually.
+/**
+ * @since 4.0.0
+ */
+export * as Arbitrary from "./Arbitrary.js";
+//# sourceMappingURL=index.js.map

package/dist/unstable/arbitrary/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/unstable/arbitrary/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAK,SAAS,MAAM,gBAAgB","ignoreList":[]}