Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#153 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
52/100
Tipo de issue
Documentación
Claridad
Bien especificado
Estado de actividad
Estancado
Stack tecnológico
typescript
Área
documentation

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.

Descripción

documentation enhancement

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
Lenguaje dominante
TypeScript
Estrellas
22
Forks
31
Merge medio
3 d 4 h
PR fusionados (30 d)
27

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de IntersectMBO/evolution-sdk

Todos los issues de IntersectMBO/evolution-sdk

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.