IntersectMBO / IntersectMBO/evolution-sdk
docs: TSchema guide is missing Union, TaggedStruct, Literal, Tuple, Boolean, and Struct options
- Lenguaje dominante
- TypeScript
- Estrellas
- 22
- Forks
- 30
- Merge medio
- 5 h 29 min
- PR fusionados (30 d)
- 12
Descripción
## 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
Guía de contribución
Línea de trabajo
Empieza con docs/content/docs/encoding/tschema.mdx y sus ejemplos existentes de TSchema; después, asigna cada construcción y opción que falte a una subsección. Añade ejemplos de twoslash que compilen, explica las diferencias de CBOR entre Union, Variant y TaggedStruct, y termina con la estructura de página solicitada y las indicaciones sobre buenas prácticas.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- typescript
- Área
- documentation
- Tipo de issue
- Documentación
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Estado de actividad
- Estancado
- Claridad
- Bien especificado
- Aptitud para principiantes
- 52/100