effect 4.0.0-beta.75 → 4.0.0-beta.76

package/dist/Schema.js

@@ -31,7 +31,7 @@
  * - Type guard: {@link is}
  * - Assertion: {@link asserts}
  * - Add constraints: `.check(...)` with filters like {@link isMinLength},
- *   {@link isGreaterThan}, {@link isPattern}, {@link isUUID}
+ *   {@link isGreaterThan}, {@link isPattern}, {@link isUUID}, {@link isGUID}
  * - Transform between schemas: {@link decodeTo}, {@link encodeTo}
  * - Add a default for missing keys: {@link withDecodingDefault}, {@link withDecodingDefaultKey}
  * - Create branded types: {@link brand}
@@ -3221,7 +3221,7 @@ export const isStringBigInt = SchemaAST.isStringBigInt;
  */
 export const isStringSymbol = SchemaAST.isStringSymbol;
 /**
- * Returns a RegExp for validating an RFC 4122 UUID.
+ * Returns a RegExp for validating an RFC 9562 / RFC 4122 UUID.
  *
  * Optionally specify a version 1-8. If no version is specified (`undefined`), all versions are supported.
  */
@@ -3229,15 +3229,24 @@ const getUUIDRegExp = version => {
   if (version) {
     return new globalThis.RegExp(`^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-${version}[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`);
   }
-  return /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$/;
+  return /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$/;
 };
 /**
- * Validates that a string is a valid Universally Unique Identifier (UUID).
- * Optionally specify a version (1-8) to validate against a specific UUID version.
- * If no version is specified (`undefined`), all versions are supported.
+ * Validates that a string is a strict Universally Unique Identifier (UUID).
+ *
+ * **When to use**
+ *
+ * Use when you need UUID semantics, including version and RFC variant bits,
+ * rather than only the dashed hexadecimal shape.
  *
  * **Details**
  *
+ * Without a version argument, this accepts UUID versions 1 through 8, the nil
+ * UUID (`00000000-0000-0000-0000-000000000000`), and the max UUID
+ * (`ffffffff-ffff-ffff-ffff-ffffffffffff`). With a version argument, this
+ * accepts only UUIDs with that version and RFC variant bits; nil and max UUIDs
+ * are not versioned UUIDs and do not match version-specific checks.
+ *
  * JSON Schema:
  *
  * This check corresponds to a `pattern` constraint in JSON Schema that matches
@@ -3248,6 +3257,7 @@ const getUUIDRegExp = version => {
  * When generating test data with fast-check, this applies a `patterns`
  * constraint to ensure generated strings match the UUID pattern.
  *
+ * @see {@link isGUID} for shape-only GUID validation.
  * @category String checks
  * @since 4.0.0
  */
@@ -3263,6 +3273,41 @@ export function isUUID(version, annotations) {
     ...annotations
   });
 }
+const GUID_REGEXP = /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/;
+/**
+ * Validates that a string has the GUID / UUID textual shape.
+ *
+ * **When to use**
+ *
+ * Use when you need to accept dashed hexadecimal identifiers without enforcing
+ * UUID version or variant bits.
+ *
+ * **Details**
+ *
+ * This check accepts strings in the `8-4-4-4-12` hexadecimal form. JSON Schema
+ * output includes the corresponding `pattern` constraint and intentionally does
+ * not include `format: "uuid"` because GUID validation is looser than UUID
+ * validation.
+ *
+ * Arbitrary:
+ *
+ * When generating test data with fast-check, this applies a `patterns`
+ * constraint to ensure generated strings match the GUID pattern.
+ *
+ * @see {@link isUUID} for strict UUID validation.
+ * @category String checks
+ * @since 4.0.0
+ */
+export function isGUID(annotations) {
+  return isPattern(GUID_REGEXP, {
+    expected: "a GUID",
+    meta: {
+      _tag: "isGUID",
+      regExp: GUID_REGEXP
+    },
+    ...annotations
+  });
+}
 /**
  * Validates that a string is a valid ULID (Universally Unique Lexicographically
  * Sortable Identifier).
@@ -5370,99 +5415,119 @@ function causeToFormatter(error, defect) {
   const causeReason = causeReasonToFormatter(error, defect);
   return t => `Cause([${t.reasons.map(causeReason).join(", ")}])`;
 }
-const ErrorJsonEncoded = /*#__PURE__*/Struct({
-  message: String,
-  name: /*#__PURE__*/optionalKey(String),
-  stack: /*#__PURE__*/optionalKey(String)
-});
+const getErrorOptionsKey = options => (options?.includeStack === true ? 1 : 0) | (options?.excludeCause === true ? 2 : 0);
+const getErrorOptions = key => {
+  switch (key) {
+    case 0:
+      return undefined;
+    case 1:
+      return {
+        includeStack: true
+      };
+    case 2:
+      return {
+        excludeCause: true
+      };
+    case 3:
+      return {
+        includeStack: true,
+        excludeCause: true
+      };
+  }
+};
+const errorSchemaCache = [];
 /**
  * Schema for JavaScript `Error` objects.
  *
  * **Details**
  *
  * Default JSON serializer:
- * Encodes an `Error` as an object with `message` and optional `name` properties,
- * and decodes that object back into an `Error`. The stack trace is omitted from
- * the encoded form for security.
  *
- * @category schemas
+ * Encodes an `Error` as an object with `message`, optional `name`, and optional
+ * `cause` properties, and decodes that object back into an `Error`. Stack
+ * traces are omitted by default for security. Pass `{ includeStack: true }` to
+ * include stack traces, or `{ excludeCause: true }` to omit causes.
+ *
+ * @category constructors
  * @since 4.0.0
  */
-export const Error = /*#__PURE__*/instanceOf(globalThis.Error, {
-  typeConstructor: {
-    _tag: "Error"
-  },
-  generation: {
-    runtime: `Schema.Error`,
-    Type: `globalThis.Error`
-  },
-  expected: "Error",
-  toCodecJson: () => link()(ErrorJsonEncoded, SchemaTransformation.errorFromErrorJsonEncoded()),
-  toArbitrary: () => fc => fc.string().map(message => new globalThis.Error(message))
-});
+export function Error(options) {
+  const key = getErrorOptionsKey(options);
+  const cached = errorSchemaCache[key];
+  if (cached !== undefined) {
+    return cached;
+  }
+  const normalizedOptions = getErrorOptions(key);
+  const schema = instanceOf(globalThis.Error, {
+    typeConstructor: {
+      _tag: "Error",
+      ...(normalizedOptions === undefined ? {} : {
+        options: normalizedOptions
+      })
+    },
+    generation: {
+      runtime: normalizedOptions !== undefined ? `Schema.Error(${format(normalizedOptions)})` : `Schema.Error()`,
+      Type: `globalThis.Error`
+    },
+    expected: "Error",
+    toCodecJson: () => link()(JsonError, SchemaTransformation.errorFromJsonError(normalizedOptions)),
+    toArbitrary: () => fc => fc.string().map(message => new globalThis.Error(message))
+  });
+  errorSchemaCache[key] = schema;
+  return schema;
+}
+const defectSchemaCache = [];
 /**
- * Schema for JavaScript `Error` objects that preserves stack traces in the JSON
+ * Schema for unexpected defect values represented as `unknown` with a JSON
  * encoded form.
  *
+ * **When to use**
+ *
+ * Use when you need a schema for `Cause` defects or other unexpected failures
+ * whose runtime value may be any value.
+ *
  * **Details**
  *
- * Default JSON serializer:
- * Encodes an `Error` as an object with `message`, optional `name`, and optional
- * `stack` properties, and decodes that object back into an `Error`.
+ * The encoded side is {@link Json}. During decoding, JSON objects with a string
+ * `message` property are decoded into JavaScript `Error` values, preserving a
+ * non-default `name` and any string `stack`. Other JSON values decode
+ * unchanged.
  *
- * @category schemas
- * @since 4.0.0
- */
-export const ErrorWithStack = /*#__PURE__*/instanceOf(globalThis.Error, {
-  typeConstructor: {
-    _tag: "ErrorWithStack"
-  },
-  generation: {
-    runtime: `Schema.ErrorWithStack`,
-    Type: `globalThis.Error`
-  },
-  expected: "Error",
-  toCodecJson: () => link()(ErrorJsonEncoded, SchemaTransformation.errorFromErrorJsonEncoded({
-    includeStack: true
-  })),
-  toArbitrary: () => fc => fc.string().map(message => new globalThis.Error(message))
-});
-const defectTransformation = /*#__PURE__*/new SchemaTransformation.Transformation(/*#__PURE__*/SchemaGetter.passthrough(), /*#__PURE__*/SchemaGetter.transform(u => {
-  try {
-    return JSON.parse(JSON.stringify(u));
-  } catch {
-    return format(u);
-  }
-}));
-/**
- * Schema for defect values, accepting either JavaScript `Error` values encoded
- * with `message` and optional `name`, or arbitrary unknown defect values.
+ * During encoding, JavaScript `Error` values encode to JSON objects with
+ * `name`, `message`, and optional `cause` properties. Pass
+ * `{ includeStack: true }` to include string stack traces in encoded `Error`
+ * defects, or `{ excludeCause: true }` to omit causes. Other values are
+ * serialized through Effect's JSON formatter and then parsed back into JSON
+ * when possible.
  *
- * **Details**
+ * **Gotchas**
  *
- * Default JSON serializer:
- * Unknown defects are serialized with `JSON.stringify` when possible and fall
- * back to Effect's formatted representation when JSON serialization fails.
+ * This schema is for carrying defects across JSON boundaries, not for
+ * preserving every JavaScript value exactly. Some values cannot round-trip
+ * unchanged:
  *
- * @category constructors
- * @since 3.10.0
- */
-export const Defect = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded.pipe(/*#__PURE__*/decodeTo(Error, /*#__PURE__*/SchemaTransformation.errorFromErrorJsonEncoded())), /*#__PURE__*/Any.pipe(/*#__PURE__*/decodeTo(/*#__PURE__*/Unknown.annotate({
-  toCodecJson: () => link()(Any, defectTransformation),
-  toArbitrary: () => fc => fc.json()
-}), defectTransformation))]);
-/**
- * Schema for defects that also includes stack traces in the encoded form.
+ * - A non-`Error` object such as `{ message: "boom" }` encodes as an
+ *   error-shaped JSON object and decodes back as an `Error`.
+ * - JSON serialization normalizes unsupported values. For example,
+ *   `undefined` array elements encode as `null`, unsupported object properties
+ *   are omitted, and circular references are dropped.
+ * - Values that cannot be represented as JSON fall back to Effect's formatted
+ *   string representation.
  *
- * @category Defect
+ * @see {@link Error} for a schema that only accepts JavaScript `Error` values.
+ * @category constructors
  * @since 4.0.0
  */
-export const DefectWithStack = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded.pipe(/*#__PURE__*/decodeTo(ErrorWithStack, /*#__PURE__*/SchemaTransformation.errorFromErrorJsonEncoded({
-  includeStack: true
-}))), /*#__PURE__*/Any.pipe(/*#__PURE__*/decodeTo(/*#__PURE__*/Unknown.annotate({
-  toCodecJson: () => link()(Any, defectTransformation),
-  toArbitrary: () => fc => fc.json()
-}), defectTransformation))]);
+export function Defect(options) {
+  const key = getErrorOptionsKey(options);
+  const cached = defectSchemaCache[key];
+  if (cached !== undefined) {
+    return cached;
+  }
+  const schema = Json.pipe(decodeTo(Unknown, SchemaTransformation.defectFromJson(getErrorOptions(key))));
+  defectSchemaCache[key] = schema;
+  return schema;
+}
 /**
  * Creates a schema for `Exit` values using schemas for the success value, typed
  * failure, and unexpected defect channels.
@@ -8197,6 +8262,12 @@ export function Tree(node) {
  * @since 4.0.0
  */
 export const Json = /*#__PURE__*/make(SchemaAST.Json);
+const JsonError = /*#__PURE__*/Struct({
+  message: String,
+  name: /*#__PURE__*/optionalKey(String),
+  stack: /*#__PURE__*/optionalKey(String),
+  cause: /*#__PURE__*/optionalKey(Json)
+});
 /**
  * Schema that accepts any mutable JSON-compatible value. See {@link Json} for
  * the immutable variant.