effect 4.0.0-rc.118 → 4.0.1

package/dist/Schema.d.ts

@@ -50,7 +50,7 @@ import type * as SchemaRepresentation from "./SchemaRepresentation.ts";
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "./StandardSchema.ts";
 import type { Assign, Lambda, Mutable, Simplify } from "./Struct.ts";
 import * as Struct_ from "./Struct.ts";
-import type { RequiredKeys, UnionToIntersection } from "./Types.ts";
+import type { IsUnion, RequiredKeys } from "./Types.ts";
 import type { Unify } from "./Unify.ts";
 declare const TypeId = "~effect/Schema/Schema";
 /**
@@ -4154,27 +4154,28 @@ export interface refine<T extends S["Type"], S extends Constraint> extends Botto
  * @since 3.10.0
  */
 export declare function refine<S extends Constraint, T extends S["Type"]>(refinement: (value: S["Type"]) => value is T, annotations?: Annotations.Filter): (schema: S) => refine<T, S>;
-type DistributeBrands<B> = UnionToIntersection<B extends infer U extends string ? Brand.Brand<U> : never>;
+type EnsureSingleBrandKey<K extends PropertyKey> = IsUnion<K> extends false ? {} extends Record<K, unknown> ? never : unknown : never;
+type FromBrandKeys<A extends Brand.Brand<any>> = A extends unknown ? Brand.Brand.Keys<A> : never;
 /**
  * Type-level representation returned by {@link brand}.
  *
  * @category branding
  * @since 3.10.0
  */
-export interface brand<S extends Constraint, B> extends BottomLazy<S["ast"], brand<S, B>, S["~type.parameters"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
-    readonly "Type": S["Type"] & DistributeBrands<B>;
+export interface brand<S extends Constraint, B extends string> extends BottomLazy<S["ast"], brand<S, B>, S["~type.parameters"], S["~type.mutability"], S["~type.optionality"], S["~type.constructor.default"], S["~encoded.mutability"], S["~encoded.optionality"]> {
+    readonly "Type": S["Type"] & Brand.Brand<B>;
     readonly "Encoded": S["Encoded"];
     readonly "DecodingServices": S["DecodingServices"];
     readonly "EncodingServices": S["EncodingServices"];
     readonly "~type.make.in": S["~type.make.in"];
-    readonly "~type.make": S["Type"] & DistributeBrands<B>;
-    readonly "Iso": S["Type"] & DistributeBrands<B>;
+    readonly "~type.make": S["Type"] & Brand.Brand<B>;
+    readonly "Iso": S["Type"] & Brand.Brand<B>;
     readonly schema: S;
     readonly identifier: string;
 }
 /**
- * Adds a nominal brand to a schema, intersecting the output type with
- * `Brand.Brand<B>` to prevent accidental mixing of structurally identical types.
+ * Intersects a schema's output type with `Brand.Brand<B>` to prevent accidental
+ * mixing of structurally identical types.
  *
  * **When to use**
  *
@@ -4183,25 +4184,42 @@ export interface brand<S extends Constraint, B> extends BottomLazy<S["ast"], bra
  *
  * **Gotchas**
  *
- * `brand` adds brand metadata and narrows the TypeScript output type, but it
- * does not add runtime checks.
+ * - `identifier` must be a single concrete string literal. Widened strings,
+ *   unions, and open template literal types are rejected.
+ * - `brand` only narrows the TypeScript output type. It does not change the
+ *   schema's runtime AST or add runtime checks.
+ * - Schema representations and generated schema code omit the brand. Reapply
+ *   `brand` after rebuilding or generating a schema when the nominal type is
+ *   still required.
  *
- * @see {@link fromBrand} for applying a Brand constructor's checks along with the brand tag
+ * @see {@link fromBrand} for applying a Brand constructor's checks along with its branded type
  *
  * @category branding
  * @since 3.10.0
  */
-export declare function brand<B extends string>(identifier: B): <S extends ConstraintRebuildable>(schema: S) => brand<S["Rebuild"], B>;
+export declare function brand<B extends string>(identifier: B & EnsureSingleBrandKey<B>): <S extends ConstraintRebuildable>(schema: S) => brand<S["Rebuild"], B>;
 /**
  * Creates a branded schema from a {@link Brand.Constructor}, applying the
- * constructor's checks and brand tag to the underlying schema.
+ * constructor's checks and branded type to the underlying schema.
+ *
+ * **When to use**
+ *
+ * Use to reuse the checks from a constructor with one concrete brand key.
+ *
+ * **Gotchas**
+ *
+ * `identifier` must match the constructor's only brand key. Apply `fromBrand`
+ * repeatedly to compose distinct brands, and use {@link Union} to represent
+ * alternatives.
+ *
+ * @see {@link brand} for adding a brand without constructor checks
  *
  * @category branding
  * @since 3.10.0
  */
-export declare function fromBrand<A extends Brand.Brand<any>>(identifier: string, ctor: Brand.Constructor<A>): <S extends Top & {
+export declare function fromBrand<A extends Brand.Brand<any>>(identifier: Brand.Brand.Keys<A> & string, ctor: Brand.Constructor<A> & EnsureSingleBrandKey<FromBrandKeys<A>>): <S extends Top & {
     readonly "Type": Brand.Brand.Unbranded<A>;
-}>(self: S) => brand<S["Rebuild"], Brand.Brand.Keys<A>>;
+}>(self: S) => brand<S["Rebuild"], keyof A["~effect/Brand"] & string>;
 /**
  * Type-level representation returned by {@link middlewareDecoding}.
  *
@@ -10608,6 +10626,8 @@ export declare function toEquivalence<T>(schema: Schema<T>): Equivalence.Equival
  * Use {@link toType} before this function to represent the type side instead.
  * The optional reference policy controls which candidates are extracted into the document's reference table. By
  * default, only candidates with a resolved identifier become references; recursive candidates always require one.
+ * TypeScript-only distinctions such as those added by {@link brand} are not
+ * part of the schema AST and are therefore omitted.
  *
  * @see {@link SchemaRepresentation.toRepresentation} for converting a `SchemaAST.AST` directly
  *
@@ -11373,8 +11393,8 @@ export declare namespace Annotations {
     }
     /**
      * Base annotations shared by all composite schema nodes. Extends
-     * {@link Documentation} with error messages, branding, and arbitrary
-     * generation hooks. {@link Declaration} and other annotation
+     * {@link Documentation} with error messages and arbitrary generation hooks.
+     * {@link Declaration} and other annotation
      * interfaces build on top of this.
      *
      * @category models
@@ -11412,10 +11432,6 @@ export declare namespace Annotations {
          * filter/refinement instead.
          */
         readonly identifier?: string | undefined;
-        /**
-         * Accumulated brands when multiple brands are added with `Schema.brand`.
-         */
-        readonly brands?: ReadonlyArray<string> | undefined;
     }
     /**
      * Helpers for projecting declaration type-parameter schemas into decoded or