IntersectMBO / IntersectMBO/evolution-sdk
docs: TSchema guide is missing Union, TaggedStruct, Literal, Tuple, Boolean, and Struct options
- Langage dominant
- TypeScript
- Étoiles
- 22
- Forks
- 30
- Merge moyen
- 5 h 29 min
- PR mergées (30 j)
- 12
Description
## 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
Guide de contribution
Ouvrir le guide de contribution
Piste de recherche
Commencez par docs/content/docs/encoding/tschema.mdx et ses exemples TSchema existants, puis associez chaque construction et option manquante à une sous-section. Ajoutez des exemples twoslash qui se compilent, expliquez les différences CBOR entre Union, Variant et TaggedStruct, et terminez par la structure de page demandée et les recommandations de bonnes pratiques.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- typescript
- Domaine
- documentation
- Type d'issue
- Documentation
- Difficulté
- 4/5
- Temps estimé
- 3-5 jours
- Activité
- À l'abandon
- Clarté
- Clairement spécifiée
- Accessibilité débutants
- 52/100