docs: TSchema guide is missing Union, TaggedStruct, Literal, Tuple, Boolean, and Struct options
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 新手友好度
- 52/100
- Issue 类型
- 文档
- 描述清晰度
- 描述清楚
- 活跃度
- 停滞
- 技术栈
- typescript
调研方向
从 docs/content/docs/encoding/tschema.mdx 及其中现有的 TSchema 示例开始，然后将每个缺失的构造和选项映射到一个子章节。添加可编译的 twoslash 示例，解释 Union、Variant 和 TaggedStruct 之间的 CBOR 差异，最后给出所要求的页面结构和最佳实践指导。
由索引模型根据 Issue 内容生成。
描述
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
- 主要语言
- TypeScript
- 星标
- 22
- 派生
- 31
- 平均合并
- 2 天 19 小时
- 30 天内合并 PR
- 32
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
IntersectMBO/evolution-sdk 的其他 Issue
-
难度 2/5 1-3 小时 新手友好度 88/100
IntersectMBO/evolution-sdk#579 ·
维护者通常 1 天内回复
-
bug
难度 2/5 1-3 小时 新手友好度 84/100
IntersectMBO/evolution-sdk#559 ·
维护者通常 1 天内回复
-
enhancement
难度 2/5 1-3 小时 新手友好度 72/100
IntersectMBO/evolution-sdk#557 ·
维护者通常 1 天内回复
-
dependencies good first issue
难度 1/5 1 小时以内 新手友好度 93/100
IntersectMBO/evolution-sdk#541 ·
维护者通常 1 天内回复
-
bug external-review
难度 2/5 1-3 小时 新手友好度 86/100
IntersectMBO/evolution-sdk#530 ·
维护者通常 1 天内回复
查看 IntersectMBO/evolution-sdk 的全部 Issue
相似的 Issue
-
area:docs bug triage:confirmed
难度 2/5 1-3 小时 新手友好度 74/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 65/100
anomalyco/models.dev#8862 · 1 条评论 ·
维护者通常 1 天内回复
-
fix(data-lake): wizard source step still previews the local slug, not the server-disambiguated one未关闭data-lake
难度 2/5 1-3 小时 新手友好度 82/100
维护者通常 1 天内回复
-
ready-for-triage
难度 1/5 1 小时以内 新手友好度 88/100
konflux-ci/konflux-ui#1596 · 1 条评论 ·
维护者通常 1 天内回复
-
enhancement good first issue priority: low size: XS
难度 2/5 1-3 小时 新手友好度 82/100
维护者通常 1 天内回复