refactor: migrate from 'flat' to 'flatInUnion' option

Author: solidsnakedev

packages/evolution/docs/modules/core/CBOR.ts.md

@@ -11,6 +11,7 @@ parent: Modules
 <h2 class="text-delta">Table of contents</h2>
 
 - [constants](#constants)
+  - [AIKEN_DEFAULT_OPTIONS](#aiken_default_options)
   - [CANONICAL_OPTIONS](#canonical_options)
   - [CBOR_ADDITIONAL_INFO](#cbor_additional_info)
   - [CBOR_MAJOR_TYPE](#cbor_major_type)
@@ -64,6 +65,25 @@ parent: Modules
 
 # constants
 
+## AIKEN_DEFAULT_OPTIONS
+
+Aiken-compatible CBOR encoding options
+
+Matches the encoding used by Aiken's cbor.serialise():
+
+- Indefinite-length arrays (9f...ff)
+- Maps encoded as arrays of pairs (not CBOR maps)
+- Strings as bytearrays (major type 2, not 3)
+- Constructor tags: 121-127 for indices 0-6, then 1280+ for 7+
+
+**Signature**
+
+```ts
+export declare const AIKEN_DEFAULT_OPTIONS: CodecOptions
+```
+
+Added in v2.0.0
+
 ## CANONICAL_OPTIONS
 
 Canonical CBOR encoding options (RFC 8949 Section 4.2.1)
@@ -239,6 +259,7 @@ export type CodecOptions =
   | {
       readonly mode: "canonical"
       readonly mapsAsObjects?: boolean
+      readonly encodeMapAsPairs?: boolean
     }
   | {
       readonly mode: "custom"
@@ -248,6 +269,7 @@ export type CodecOptions =
       readonly sortMapKeys: boolean
       readonly useMinimalEncoding: boolean
       readonly mapsAsObjects?: boolean
+      readonly encodeMapAsPairs?: boolean
     }
 ```
 

packages/evolution/docs/modules/core/Data.ts.md

@@ -20,8 +20,6 @@ parent: Modules
   - [int](#int)
   - [list](#list)
   - [map](#map)
-- [either](#either)
-  - [Either (namespace)](#either-namespace)
 - [equality](#equality)
   - [equals](#equals)
   - [hash](#hash)
@@ -71,6 +69,7 @@ parent: Modules
 - [utils](#utils)
   - [ByteArray (type alias)](#bytearray-type-alias)
   - [CDDLSchema](#cddlschema)
+  - [DataSchema (interface)](#dataschema-interface)
   - [Int (type alias)](#int-type-alias)
 
 ---
@@ -88,12 +87,12 @@ export declare const withSchema: <A, I extends Data>(
   schema: Schema.Schema<A, I>,
   options?: CBOR.CodecOptions
 ) => {
-  toData: (input: A) => I
-  fromData: (input: I) => A
-  toCBORHex: (input: A, options?: CBOR.CodecOptions) => string
-  toCBORBytes: (input: A, options?: CBOR.CodecOptions) => Uint8Array
-  fromCBORHex: (hex: string, options?: CBOR.CodecOptions) => A
-  fromCBORBytes: (bytes: Uint8Array, options?: CBOR.CodecOptions) => A
+  toData: (a: A, overrideOptions?: ParseOptions) => I
+  fromData: (i: I, overrideOptions?: ParseOptions) => A
+  toCBORHex: (a: A, overrideOptions?: ParseOptions) => string
+  toCBORBytes: (a: A, overrideOptions?: ParseOptions) => any
+  fromCBORHex: (i: string, overrideOptions?: ParseOptions) => A
+  fromCBORBytes: (i: any, overrideOptions?: ParseOptions) => A
 }
 ```
 
@@ -175,14 +174,6 @@ export declare const map: (entries: Array<[key: Data, value: Data]>) => Map
 
 Added in v2.0.0
 
-# either
-
-## Either (namespace)
-
-Either-based variants for functions that can fail.
-
-Added in v2.0.0
-
 # equality
 
 ## equals
@@ -525,7 +516,7 @@ Combined schema for PlutusData type with proper recursion
 **Signature**
 
 ```ts
-export declare const DataSchema: Schema.Schema<Data, DataEncoded, never>
+export declare const DataSchema: DataSchema
 ```
 
 Added in v2.0.0
@@ -735,7 +726,7 @@ Encode PlutusData to CBOR bytes
 **Signature**
 
 ```ts
-export declare const toCBORBytes: (input: Data, options?: CBOR.CodecOptions) => Uint8Array
+export declare const toCBORBytes: (data: Data, options?: CBOR.CodecOptions) => any
 ```
 
 Added in v2.0.0
@@ -747,7 +738,7 @@ Encode PlutusData to CBOR hex string
 **Signature**
 
 ```ts
-export declare const toCBORHex: (input: Data, options?: CBOR.CodecOptions) => string
+export declare const toCBORHex: (data: Data, options?: CBOR.CodecOptions) => string
 ```
 
 Added in v2.0.0
@@ -808,6 +799,14 @@ export type ByteArray = typeof ByteArray.Type
 export declare const CDDLSchema: Schema.Schema<CBOR.CBOR, CBOR.CBOR, never>
 ```
 
+## DataSchema (interface)
+
+**Signature**
+
+```ts
+export interface DataSchema extends Schema.SchemaClass<Data, DataEncoded> {}
+```
+
 ## Int (type alias)
 
 **Signature**

packages/evolution/docs/modules/core/TSchema.ts.md

@@ -12,6 +12,9 @@ parent: Modules
 
 - [combinators](#combinators)
   - [equivalence](#equivalence)
+- [constructors](#constructors)
+  - [TaggedStruct](#taggedstruct)
+  - [Variant](#variant)
 - [schemas](#schemas)
   - [ByteArray](#bytearray)
   - [Integer](#integer)
@@ -62,6 +65,48 @@ export declare const equivalence: <A, I, R>(schema: Schema.Schema<A, I, R>) => E
 
 Added in v2.0.0
 
+# constructors
+
+## TaggedStruct
+
+Creates a tagged struct - a shortcut for creating a Struct with a Literal tag field.
+
+This is a convenience helper that makes it easy to create structs with discriminator fields,
+commonly used in discriminated unions.
+
+**Signature**
+
+```ts
+export declare const TaggedStruct: <
+  TagValue extends string,
+  Fields extends Schema.Struct.Fields,
+  TagField extends string = "_tag"
+>(
+  tagValue: TagValue,
+  fields: Fields,
+  options?: StructOptions & { tagField?: TagField }
+) => Struct<{ [K in TagField]: OneLiteral<TagValue> } & Fields>
+```
+
+Added in v2.0.0
+
+## Variant
+
+Creates a variant (tagged union) schema for Aiken-style enum types.
+
+This is a convenience helper that creates properly discriminated TypeScript types
+while maintaining single-level CBOR encoding compatible with Aiken.
+
+**Signature**
+
+```ts
+export declare const Variant: <Variants extends Record<string, Schema.Struct.Fields>>(
+  variants: Variants
+) => Schema.Schema<VariantType<Variants>, Data.Data, never>
+```
+
+Added in v2.0.0
+
 # schemas
 
 ## ByteArray
@@ -289,7 +334,31 @@ export interface StructOptions {
    *
    * Default: true when index is specified, false otherwise
    */
-  flat?: boolean
+  flatInUnion?: boolean
+  /**
+   * When used as a field in a parent Struct, controls whether this Struct's fields
+   * should be spread (merged) into the parent's field array.
+   * - true: Inner Struct fields are merged directly into parent
+   * - false: Inner Struct is kept as a nested Constr
+   *
+   * Default: false
+   *
+   * Note: This only applies when the Struct is a field value, not when used in Union.
+   */
+  flatFields?: boolean
+  /**
+   * Name of a field to treat as a discriminant tag (e.g., "_tag", "type").
+   *
+   * Auto-detection: Fields named "_tag", "type", "kind", or "variant" containing
+   * Literal values are automatically stripped from CBOR encoding and injected during decoding.
+   *
+   * This option allows you to:
+   * - Explicitly specify a custom tag field name
+   * - Disable auto-detection with `tagField: false`
+   *
+   * Default: auto-detect from KNOWN_TAG_FIELDS
+   */
+  tagField?: string | false
 }
 ```
 
@@ -362,7 +431,7 @@ Added in v2.0.0
 export interface Union<Members extends ReadonlyArray<Schema.Schema.Any>>
   extends Schema.transformOrFail<
     Schema.SchemaClass<Data.Constr, Data.Constr, never>,
-    Schema.SchemaClass<Schema.Schema.Type<[...Members][number]>, Schema.Schema.Type<[...Members][number]>, never>,
+    Schema.SchemaClass<Schema.Schema.Type<Members[number]>, Schema.Schema.Type<Members[number]>, never>,
     never
   > {}
 ```