IntersectMBO / IntersectMBO/evolution-sdk
docs: TSchema guide is missing Union, TaggedStruct, Literal, Tuple, Boolean, and Struct options
- Lingua principale
- TypeScript
- Stelle
- 22
- Fork
- 30
- Merge medio
- 5h 29m
- PR unite (30g)
- 12
Descrizione
## Problem
The TSchema guide page at \`docs/content/docs/encoding/tschema.mdx\` covers basic schemas (ByteArray, Integer, Struct, Variant, Array, Map, UndefinedOr) and codec creation, but is missing documentation for several important constructs and usage areas.
### Missing Sections
**Union** — \`TSchema.Union()\` is the lower-level primitive that \`Variant\`, \`TaggedStruct\`, and other helpers are all built on. It is never documented on its own or explained in terms of when you'd reach for it directly over the helpers.
**TaggedStruct** — \`TSchema.TaggedStruct()\` creates discriminated unions with an explicit tag field (\`_tag\`, \`type\`, \`kind\`, \`variant\`). Auto-detection of tag fields inside \`Union\` members is a key feature that is not mentioned anywhere in the guide.
**Literal** — \`TSchema.Literal()\` for enum-style constructors with no fields. The \`LiteralOptions\` interface (\`index\`, \`flatInUnion\`) is not covered.
**Tuple** — \`TSchema.Tuple()\` for fixed-length positional data. No mention in the guide.
**Boolean** — \`TSchema.Boolean\` for Plutus-style booleans (Constr 0 = False, Constr 1 = True).
**NullOr vs UndefinedOr** — The guide only covers \`UndefinedOr\`. \`NullOr\` and the decision between them is absent.
**Struct options** — \`flatFields\`, \`flatInUnion\`, and \`index\` options on \`TSchema.Struct()\` are undocumented. These are critical for correctly matching Aiken on-chain encoding.
**Variant vs Union vs TaggedStruct** — No comparison section explaining when to use each and how they differ in CBOR encoding:
- **Variant**: wrapper-object shape (\`{ VerificationKey: { hash } }\`) — single-level CBOR
- **TaggedStruct**: discriminator-field shape (\`{ _tag: "Mint", amount }\`) — tag stripped in CBOR
- **Union**: raw position-based — constructor index determines variant
**Schema utilities** — \`compose\`, \`filter\`, \`equivalence\`, and \`is\` are exported but absent from the guide.
### Acceptance Criteria
- [ ] Each missing schema type has its own subsection with description and code example
- [ ] A comparison section for Union vs Variant vs TaggedStruct with CBOR encoding differences
- [ ] Struct options (\`flatFields\`, \`flatInUnion\`, \`index\`) documented with encoding examples
- [ ] All examples use \`twoslash\` code fences and compile
- [ ] Page structure: Overview → Quick Start → Core Concepts → Reference → Best Practices
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.