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

package/dist/Schema.d.ts

@@ -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}
@@ -4757,12 +4757,21 @@ export declare const isStringBigInt: (annotations?: Annotations.Filter) => Schem
  */
 export declare const isStringSymbol: (annotations?: Annotations.Filter) => SchemaAST.Filter<string>;
 /**
- * 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
@@ -4773,10 +4782,36 @@ export declare const isStringSymbol: (annotations?: Annotations.Filter) => Schem
  * 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
  */
 export declare function isUUID(version?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8, annotations?: Annotations.Filter): SchemaAST.Filter<string>;
+/**
+ * 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 declare function isGUID(annotations?: Annotations.Filter): SchemaAST.Filter<string>;
 /**
  * Validates that a string is a valid ULID (Universally Unique Lexicographically
  * Sortable Identifier).
@@ -6157,70 +6192,93 @@ export interface Error extends instanceOf<globalThis.Error> {
     readonly "Rebuild": Error;
 }
 /**
- * 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.
+ * Options for {@link Error} and {@link Defect}.
  *
- * @category schemas
+ * @category options
  * @since 4.0.0
  */
-export declare const Error: Error;
+export interface ErrorOptions {
+    /**
+     * Includes string stack traces in encoded `Error` values when set to `true`.
+     *
+     * @default false
+     */
+    readonly includeStack?: boolean | undefined;
+    /**
+     * Excludes `Error.cause` values from encoded `Error` values when set to
+     * `true`.
+     *
+     * @default false
+     */
+    readonly excludeCause?: boolean | undefined;
+}
 /**
- * Schema for JavaScript `Error` objects that preserves stack traces in the JSON
- * encoded form.
+ * Schema for JavaScript `Error` objects.
  *
  * **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`.
+ * `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 schemas
+ * @category constructors
  * @since 4.0.0
  */
-export declare const ErrorWithStack: Error;
+export declare function Error(options?: ErrorOptions): Error;
 /**
  * Type-level representation of {@link Defect}.
  *
  * @category Defect
  * @since 3.10.0
  */
-export interface Defect extends Union<readonly [
-    decodeTo<Error, Struct<{
-        readonly message: String;
-        readonly name: optionalKey<String>;
-        readonly stack: optionalKey<String>;
-    }>>,
-    decodeTo<Unknown, Any>
-]> {
+export interface Defect extends decodeTo<Unknown, typeof Json> {
     readonly "Rebuild": Defect;
 }
 /**
- * Schema for defect values, accepting either JavaScript `Error` values encoded
- * with `message` and optional `name`, or arbitrary unknown defect values.
+ * 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:
- * Unknown defects are serialized with `JSON.stringify` when possible and fall
- * back to Effect's formatted representation when JSON serialization fails.
+ * 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 constructors
- * @since 3.10.0
- */
-export declare const Defect: Defect;
-/**
- * Schema for defects that also includes stack traces in the encoded form.
+ * 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.
  *
- * @category Defect
+ * **Gotchas**
+ *
+ * This schema is for carrying defects across JSON boundaries, not for
+ * preserving every JavaScript value exactly. Some values cannot round-trip
+ * unchanged:
+ *
+ * - 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.
+ *
+ * @see {@link Error} for a schema that only accepts JavaScript `Error` values.
+ * @category constructors
  * @since 4.0.0
  */
-export declare const DefectWithStack: Defect;
+export declare function Defect(options?: ErrorOptions): Defect;
 /**
  * Type-level representation returned by {@link Exit}.
  *
@@ -9361,6 +9419,10 @@ export declare namespace Annotations {
             readonly regExp: globalThis.RegExp;
             readonly version: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | undefined;
         };
+        readonly isGUID: {
+            readonly _tag: "isGUID";
+            readonly regExp: globalThis.RegExp;
+        };
         readonly isULID: {
             readonly _tag: "isULID";
             readonly regExp: globalThis.RegExp;