feat(db): add Recording schema versioning and V6→V7 migration #1050
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
This adds the migration infrastructure needed to support the transcribedText → transcript rename from PR #1042. Without this, existing user data would break on upgrade. The Recording type now includes a version field (version: 7), and a migration pipeline validates and upgrades V6 records (with transcribedText) to V7 (with transcript). The Dexie migration (v0.7) handles IndexedDB upgrades, while desktop markdown storage simply constructs recordings with the current version on read.
braden-w
changed the base branch from
main
to
refactor/transcribedText-to-transcript
Contributor
🚀 Preview Deployment Ready!Whispering Preview: https://whispering-pr-1050.epicenter.workers.dev Worker Name: This preview will be automatically updated with new commits to this PR. Built with commit 63fc8f8 |
… validator Renamed RecordingMigrator to Recording and inlined the migration logic in the pipe callback to match the established pattern in transformations.ts. The pipe now explicitly returns RecordingV7 rather than the Recording alias. Removed the validateAndMigrateRecording wrapper as it's no longer needed.
Changed RecordingV7 type to use typeof infer pattern, matching how TransformationStepV2 is defined in transformations.ts. The "Two different types with this name exist" errors are pre-existing (56 errors) and affect all arktype types in this codebase, not specific to Recording.
…or for parsing Updates the V7 migration in web.ts to use Dexie's .modify() method instead of clear/bulkAdd, which is safer for in-place record updates and avoids potential data loss if the migration fails partway through. For file-system.ts, replaces the separate RecordingFrontMatter validator with the Recording validator itself, allowing desktop files to benefit from the same automatic V6→V7 migration as web storage. The parseMarkdownToRecording function now combines frontmatter and body, then validates through Recording which handles schema versioning automatically. Also adds clarifying comments distinguishing Dexie schema versions (0.1-0.7) from Recording schema versions (V6-V7) to prevent future confusion.
Updates V4 migration (adding createdAt/updatedAt) to use Dexie's .modify() for simpler in-place field additions. V5 migration (blob→ArrayBuffer) remains using clear/bulkAdd since the async blob conversion is more complex and the existing pattern is battle-tested. Added comment explaining this decision. V7 migration already uses .modify() from the previous commit.
… validator Desktop files are treated as V6 schema. The Recording validator handles defaulting version to 6 and migrating to V7 automatically. No need to manually set version or check frontmatter fields.
braden-w
force-pushed
the
feat/recording-migration-v7
branch
from
280f66d to
e0418f0
Compare
Changes parseMarkdownToRecording to return a wellcrafted Result type instead of a union type. The error variant includes the validation summary for better error reporting.
Adds detailed documentation explaining that the Recording validator accepts V6 or V7 input and always outputs the latest schema (V7). Includes usage example in the JSDoc.
Each RecordingsDbSchema type is now a complete, self-contained definition showing exactly what the data looked like at that Dexie version. No longer derived from current types, so changes to Recording won't affect historical schema definitions. This makes the migration history clear and prevents type drift.
Exports RecordingV6 and RecordingV7 types, then uses them to derive RecordingsDbSchemaV5 and RecordingsDbSchemaV6. This keeps the current schemas in sync with the validators while V4 and earlier remain as frozen snapshots.
V0.5 migration now sets version: 6 explicitly, and V0.7 migration uses hardcoded 7 instead of CURRENT_RECORDING_VERSION. This ensures migration code is self-documenting and doesn't depend on external constants that could change.
…ines - New article: freezing-schema-types-for-migrations.md explains why historical schema types should be explicit snapshots, not derived from current types - Updated documentation.md with refined technical article guidelines: section titles should contain the insight, openings can be personal if they get to the point quickly, banner comments help scanability
Removed the separate migrateStepV1ToV2 function and inlined the migration directly in the .pipe() callback. This follows the pattern of keeping simple transformations close to where they're used. Updated the migrate-on-read article to reflect this simpler approach.
- Make TransformationStepV1 and TransformationStepV2 internal (not exported) - Derive TransformationStep type from Transformation['steps'][number] - Change web.ts to use TransformationV2['steps'] instead of TransformationStepV2[] - Simplify migration pipe by checking V2 first for proper type narrowing - Remove TransformationBase intermediate type (inline fields into V1/V2) - Convert TransformationV1 from type alias to arktype validator
Updated both migration articles to use Recording as the primary example instead of TransformationStep since it's simpler. Added cross-references between the articles and removed the Composing Validators section.
braden-w
merged commit 67617e4
into
refactor/transcribedText-to-transcript
2 of 8 checks passed
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 PR adds the migration infrastructure needed to support the
transcribedText→transcriptrename from #1042. Without this migration, existing user data would break when users upgrade to a version with the renamed field.The Recording type now includes a
versionfield (currently7), and a migration pipeline validates and upgrades V6 records (withtranscribedText) to V7 (withtranscript). For IndexedDB (web), a Dexie migration (v0.7) handles the upgrade. For desktop, markdown files don't store version numbers; they're constructed with the current version on read since the field name in the body doesn't change.Depends on: #1042
Note: Pre-existing type errors in settings page bindings and test-persist-toast page are unrelated to these changes.