IntersectMBO / IntersectMBO/evolution-sdk

docs: TSchema guide is missing Union, TaggedStruct, Literal, Tuple, Boolean, and Struct options

Ouverte
#153 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
documentation enhancement
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

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.