Improve schema documentation #741
Merged
+1,326
−5
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…c team This document clarifies the TInput/TOutput architecture and explains how PowerSync can support arbitrary type transformations (like Date objects) by handling serialization in their integration layer rather than constraining TOutput to match SQLite types. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
This proposal addresses the lack of documentation around TInput/TOutput schema types and transformations. It includes: - Complete content outline for new schemas.md guide - Data flow diagrams and examples - Guidance for both app developers and integration authors - Common patterns for Date handling, defaults, and type conversions - Updates to existing docs (overview, mutations, collection-options-creator) The proposal directly addresses confusion like what the PowerSync team experienced regarding how to handle type transformations and serialization in integrations. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
After investigating all existing docs (overview, mutations, error-handling, live-queries, collection-options-creator) and examples, created a refined plan that addresses: KEY FINDING: Two distinct type conversion mechanisms 1. Integration-level parsing (storage format ↔ in-memory format) 2. Schema validation/transformation (TInput → TOutput for mutations) The plan includes: - Analysis of what's currently documented (and gaps) - Comprehensive schemas.md guide structure (11 sections) - Specific updates to 5 existing docs with exact content - Separate guidance for app developers vs integration authors - Clear distinction between integration parsing and schema validation - Complete working examples and best practices - Implementation order and success criteria This directly addresses the PowerSync confusion about TInput/TOutput and provides clear guidance for both audiences. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
New guide (docs/guides/schemas.md) covering: - Introduction with validation-first example - Core concepts: TInput vs TOutput with data flow diagram - Validation patterns (types, strings, numbers, enums, arrays, custom) - Transformation patterns (Date conversion, JSON, computed fields) - Default values (literals, functions, complex) - Handling updates with union types pattern - Error handling with SchemaValidationError - Best practices (with performance callout) - Two complete working examples (Todo app, E-commerce) - Brief integration authors section linking to collection-options-creator - Related topics links This addresses the documentation gap identified in the PowerSync question about TInput/TOutput and provides clear guidance for both app developers and integration authors on schema validation and type transformations. ~850 lines, 12 sections, 30+ code examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Address review feedback to make the guide more focused and practical: - Add clarification that schemas only validate client changes, not server data - Remove "Handling Sync Validation Errors" section - Fix QueryFn example to show manual parsing is required for API responses - Rename "Handling Updates" to "Handling Timestamps" with better focus on common patterns - Remove "Safe Parsing (Zod)" section - Remove "When to Use Schemas" from Best Practices - Remove "Schema Organization" from Best Practices - Replace lengthy "For Integration Authors" section with brief link to collection-options-creator.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
- Explicitly mention schemas catch invalid data from optimistic mutations - Show reusing schema with .parse() in queryFn to transform API responses - Remove The Data Flow diagram section (had errors and wasn't useful) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
Updates across documentation to explain schemas and type transformations: **overview.md:** - Expand collection schemas section with comprehensive example - Add list of what schemas do (validation, transformations, defaults, type safety) - Link to new schemas guide **mutations.md:** - Add "Schema Validation in Mutation Handlers" section - Explain that handlers receive TOutput (transformed data) - Show serialization pattern for backends **error-handling.md:** - Add "When schema validation occurs" section - Clarify schemas only validate client mutations, not sync data - Link to schemas guide **collection-options-creator.md:** - Add "Schemas and Type Transformations" section - Explain three approaches: parse/serialize helpers, user handles, automatic serialization - Show examples from TrailBase and Query Collection - Document design principles for integration authors 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
|
More templates
@tanstack/angular-db
@tanstack/db
@tanstack/db-ivm
@tanstack/electric-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit: |
|
Size Change: 0 B Total Size: 79.1 kB ℹ️ View Unchanged
|
|
Size Change: 0 B Total Size: 3.34 kB ℹ️ View Unchanged
|
samwillis
approved these changes
Nov 5, 2025
Comment on lines
+101
to
+107
| ### What are TInput and TOutput? | ||
|
|
||
| When you define a schema with transformations, it has two types: | ||
|
|
||
| - **TInput**: The type users provide when calling `insert()` or `update()` | ||
| - **TOutput**: The type stored in the collection and returned from queries | ||
|
|
There was a problem hiding this comment.
I think it's worth documenting that it's best practice (or even essential) to make TInput and superset of TOutput. This is particularly important due to the draft on update() calls, the draft is typed as TInput but will contain the data from that will be in from the output of the schemas.
We made this tradeoff in the design to keep things simple and understandable, at the expense of having to document it.
We looked at trying to make the draft TOutput | TInput but that has to be computed recursively though the structures - its not just a simple union of the types, but a union of each prop recursively. Documenting that one is a superset of the other seemed better.
There was a problem hiding this comment.
Good call — added.
Addresses PR review feedback from samwillis about the critical design principle that TInput must be a superset of TOutput when using transformations. Key improvements: - Add prominent "Critical Design Principle" section explaining why TInput must accept all TOutput values - Clarify that union types are REQUIRED (not optional) for transformations - Add clear ❌/✅ examples showing what breaks and why - Explain the draft parameter typing issue in collection.update() - Strengthen language in Best Practices from "should" to "must" This makes it clear that when schemas transform type A to type B, you must use z.union([A, B]) to ensure updates work correctly. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
KyleAMathews
deleted the
claude/tanstack-db-schema-integration-011CUQSQwu63eHsgKcN5Y7wf
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This was quite thin before.