From b9f5ef7a268bdfd6f857bcf0562efe8664243405 Mon Sep 17 00:00:00 2001 From: Braden Wong <13159333+braden-w@users.noreply.github.com> Date: Fri, 5 Dec 2025 16:56:20 -0800 Subject: [PATCH 1/3] docs(migrate): highlight Elysia string status name advantage Adds tip boxes to all migration guides highlighting that Elysia supports both numeric and string status names, unlike Express/Fastify/Hono which only accept numeric codes. This is a genuine DX advantage worth showcasing to users migrating from other frameworks. --- docs/migrate/from-express.md | 12 ++++++++++++ docs/migrate/from-fastify.md | 12 ++++++++++++ docs/migrate/from-hono.md | 12 ++++++++++++ docs/migrate/from-trpc.md | 12 ++++++++++++ 4 files changed, 48 insertions(+) diff --git a/docs/migrate/from-express.md b/docs/migrate/from-express.md index 471d56db..f7d3cc7d 100644 --- a/docs/migrate/from-express.md +++ b/docs/migrate/from-express.md @@ -521,6 +521,18 @@ const app = new Elysia() While Express has a `next` function to call the next middleware, Elysia does not has one. +::: tip +Unlike Express which only accepts numeric status codes, Elysia also supports descriptive string names: + +```ts +// Both are equivalent in Elysia +return status(401) +return status("Unauthorized") +``` + +String status names provide TypeScript autocompletion for all valid HTTP statuses, making your code more readable and less error-prone. +::: + ## Sounds type safety Elysia is designed to be sounds type safety. diff --git a/docs/migrate/from-fastify.md b/docs/migrate/from-fastify.md index eebc0c28..4d0198fd 100644 --- a/docs/migrate/from-fastify.md +++ b/docs/migrate/from-fastify.md @@ -549,6 +549,18 @@ const app = new Elysia() +::: tip +Unlike Fastify which only accepts numeric status codes, Elysia also supports descriptive string names: + +```ts +// Both are equivalent in Elysia +return status(401) +return status("Unauthorized") +``` + +String status names provide TypeScript autocompletion for all valid HTTP statuses, making your code more readable and less error-prone. +::: + ## Sounds type safety Elysia is designed to be sounds type safety. diff --git a/docs/migrate/from-hono.md b/docs/migrate/from-hono.md index 60b21e2c..a79ec127 100644 --- a/docs/migrate/from-hono.md +++ b/docs/migrate/from-hono.md @@ -531,6 +531,18 @@ const app = new Elysia() While Hono has a `next` function to call the next middleware, Elysia does not has one. +::: tip +Unlike Hono which only accepts numeric status codes, Elysia also supports descriptive string names: + +```ts +// Both are equivalent in Elysia +return status(401) +return status("Unauthorized") +``` + +String status names provide TypeScript autocompletion for all valid HTTP statuses, making your code more readable and less error-prone. +::: + ## Sounds type safety Elysia is designed to be sounds type safety. diff --git a/docs/migrate/from-trpc.md b/docs/migrate/from-trpc.md index 26896eba..6c386ed5 100644 --- a/docs/migrate/from-trpc.md +++ b/docs/migrate/from-trpc.md @@ -517,6 +517,18 @@ const app = new Elysia() While tRPC has a `next` function to call the next middleware in the queue, Elysia use specific event interceptor for each point in the request pipeline. +::: tip +Like tRPC's string error codes (e.g., `"UNAUTHORIZED"`), Elysia supports both numeric and string status names: + +```ts +// Both are equivalent in Elysia +return status(401) +return status("Unauthorized") +``` + +This gives you the readability of tRPC's string codes while staying compliant with HTTP standards. String status names also provide TypeScript autocompletion for all valid HTTP statuses. +::: + ## Sounds type safety Elysia is designed to be sounds type safety. From 84d221f2c4e581d0e70ebb55303c9991c5c5eb0f Mon Sep 17 00:00:00 2001 From: Braden Wong Date: Fri, 5 Dec 2025 17:36:55 -0800 Subject: [PATCH 2/3] style: use single quotes for status strings --- docs/migrate/from-express.md | 2 +- docs/migrate/from-fastify.md | 2 +- docs/migrate/from-hono.md | 2 +- docs/migrate/from-trpc.md | 2 +- docs/specs/20251205T000000-quote-style-fix.md | 43 ++++++ ...251205T000001-pr-consolidation-analysis.md | 137 ++++++++++++++++++ 6 files changed, 184 insertions(+), 4 deletions(-) create mode 100644 docs/specs/20251205T000000-quote-style-fix.md create mode 100644 docs/specs/20251205T000001-pr-consolidation-analysis.md diff --git a/docs/migrate/from-express.md b/docs/migrate/from-express.md index f7d3cc7d..8707bf8e 100644 --- a/docs/migrate/from-express.md +++ b/docs/migrate/from-express.md @@ -527,7 +527,7 @@ Unlike Express which only accepts numeric status codes, Elysia also supports des ```ts // Both are equivalent in Elysia return status(401) -return status("Unauthorized") +return status('Unauthorized') ``` String status names provide TypeScript autocompletion for all valid HTTP statuses, making your code more readable and less error-prone. diff --git a/docs/migrate/from-fastify.md b/docs/migrate/from-fastify.md index 4d0198fd..901c7505 100644 --- a/docs/migrate/from-fastify.md +++ b/docs/migrate/from-fastify.md @@ -555,7 +555,7 @@ Unlike Fastify which only accepts numeric status codes, Elysia also supports des ```ts // Both are equivalent in Elysia return status(401) -return status("Unauthorized") +return status('Unauthorized') ``` String status names provide TypeScript autocompletion for all valid HTTP statuses, making your code more readable and less error-prone. diff --git a/docs/migrate/from-hono.md b/docs/migrate/from-hono.md index a79ec127..3c3ca602 100644 --- a/docs/migrate/from-hono.md +++ b/docs/migrate/from-hono.md @@ -537,7 +537,7 @@ Unlike Hono which only accepts numeric status codes, Elysia also supports descri ```ts // Both are equivalent in Elysia return status(401) -return status("Unauthorized") +return status('Unauthorized') ``` String status names provide TypeScript autocompletion for all valid HTTP statuses, making your code more readable and less error-prone. diff --git a/docs/migrate/from-trpc.md b/docs/migrate/from-trpc.md index 6c386ed5..f4d63476 100644 --- a/docs/migrate/from-trpc.md +++ b/docs/migrate/from-trpc.md @@ -523,7 +523,7 @@ Like tRPC's string error codes (e.g., `"UNAUTHORIZED"`), Elysia supports both nu ```ts // Both are equivalent in Elysia return status(401) -return status("Unauthorized") +return status('Unauthorized') ``` This gives you the readability of tRPC's string codes while staying compliant with HTTP standards. String status names also provide TypeScript autocompletion for all valid HTTP statuses. diff --git a/docs/specs/20251205T000000-quote-style-fix.md b/docs/specs/20251205T000000-quote-style-fix.md new file mode 100644 index 00000000..cadd1938 --- /dev/null +++ b/docs/specs/20251205T000000-quote-style-fix.md @@ -0,0 +1,43 @@ +# Quote Style Fix for String Status Names + +## Issue +PRs #739-#745 introduced string status name examples using double quotes: +```ts +return status("Unauthorized") +``` + +However, the Elysia documentation consistently uses single quotes (680 occurrences of `from 'elysia'` vs 1 occurrence of double quotes). + +The examples should use single quotes to match the codebase style: +```ts +return status('Unauthorized') +``` + +## Files to Update + +### PR #745 - Migration Guides +- `docs/migrate/from-express.md` - line 530 +- `docs/migrate/from-fastify.md` - line 558 +- `docs/migrate/from-hono.md` - line 540 +- `docs/migrate/from-trpc.md` - line 526 + +### PR #739 - Lifecycle Tutorial +- `docs/tutorial/getting-started/life-cycle/index.md` - check for any double-quoted status strings + +### PRs #740-#744 +Check each file touched by these PRs for double-quoted status strings and convert to single quotes. + +## Search Pattern +```bash +grep -rn 'status("' docs/ +``` + +## Fix Pattern +Replace `status("...)` with `status('...')` in all code examples. + +## Verification +After fixing, run: +```bash +grep -rn 'status("' docs/ +# Should return no results (or only results in prose/explanatory text, not code blocks) +``` diff --git a/docs/specs/20251205T000001-pr-consolidation-analysis.md b/docs/specs/20251205T000001-pr-consolidation-analysis.md new file mode 100644 index 00000000..61da265e --- /dev/null +++ b/docs/specs/20251205T000001-pr-consolidation-analysis.md @@ -0,0 +1,137 @@ +# PR Consolidation Analysis + +## Current PRs + +| PR | Title | Files | Category | +|----|-------|-------|----------| +| #737 | fix: correct quote typos in status examples | status-and-headers, error-handling (tutorial) | Bug fix | +| #738 | docs(tutorial): clarify status accepts both number and string names | status-and-headers, error-handling (tutorial) | Educational | +| #739 | docs(tutorial): show string status names in lifecycle examples | life-cycle (tutorial) | Educational | +| #740 | docs: show string status names in lifecycle and error handling | life-cycle.md, error-handling.md (essential/patterns) | Educational | +| #741 | docs: show string status names in key-concept examples | key-concept.md | Educational | +| #742 | docs: use string status names in examples | validation, macro (tutorial) | Conversion | +| #743 | docs: use descriptive string status names for auth errors | guard, encapsulation, plugin, best-practice | Conversion | +| #744 | docs: use string status names consistently across remaining files | index.md, better-auth, extends-context, eden | Conversion | +| #745 | docs(migrate): highlight Elysia string status name advantage | from-express, from-fastify, from-hono, from-trpc | Migration tip | + +## Analysis Questions + +For each PR pair, determine: +1. Do they serve different purposes that justify separate PRs? +2. Would combining them make review harder or easier? +3. Are there any truly redundant changes? + +## Potential Consolidation Groups + +### Group A: Tutorial files (PRs #737, #738, #739, #742) +- #737 + #738: Already stacked, touch same files +- #739: Different file (life-cycle tutorial) +- #742: Different files (validation, macro tutorials) + +**Question**: Should all tutorial-related changes be one PR? + +### Group B: Essential/Pattern docs (PRs #740, #741) +- #740: life-cycle.md, error-handling.md +- #741: key-concept.md + +**Question**: Should core documentation changes be combined? + +### Group C: Auth-focused conversions (#743) +- Standalone theme: auth errors (401, 403) +- 5 files, clear scope + +**Question**: Is this distinct enough to stay separate? + +### Group D: Remaining files (#744) +- Catch-all for remaining conversions +- Mixed files (homepage, integrations, patterns, eden) + +**Question**: Is this too scattered? + +### Group E: Migration guides (#745) +- Clear distinct purpose +- All migration guide files + +**Question**: Should stay separate (different audience) + +--- + +## Subagent Prompt + +To analyze whether these PRs should be consolidated, run this prompt with multiple subagents: + +``` +For each of the following PR groupings, analyze whether they should remain separate or be merged: + +**Subagent 1 - Tutorial PRs Analysis** +Analyze PRs #737, #738, #739, #742 which all touch tutorial files: +- #737: typo fixes in status-and-headers, error-handling tutorials +- #738: adds explanation about string status names to same files +- #739: adds string status name comments to life-cycle tutorial +- #742: converts numeric to string status names in validation, macro tutorials + +Questions: +1. Would a maintainer prefer reviewing these as 4 separate PRs or 1-2 combined PRs? +2. Are any changes redundant or overlapping? +3. What's the clearest way to organize these for review? + +**Subagent 2 - Core Docs Analysis** +Analyze PRs #740, #741 which touch essential documentation: +- #740: adds string status name comments to essential/life-cycle.md, patterns/error-handling.md +- #741: adds string status name comments to key-concept.md + +Questions: +1. These are both "add educational comments" - should they be one PR? +2. Is key-concept.md special enough (MUST READ badge) to warrant its own PR? + +**Subagent 3 - Conversion PRs Analysis** +Analyze PRs #743, #744 which convert numeric codes to string names: +- #743: converts 401/403 to "Unauthorized"/"Forbidden" in auth-related files (guard, encapsulation, plugin, best-practice) +- #744: converts remaining files (homepage, better-auth, extends-context, eden) + +Questions: +1. Should all "conversion" changes be one PR? +2. Is the auth-focused theme of #743 worth preserving as separate? +3. Is #744 too scattered (5 unrelated files)? + +**Subagent 4 - Migration Guide Analysis** +Analyze PR #745 which adds tip boxes to migration guides: +- Adds tip highlighting Elysia's string status name advantage +- 4 files: from-express, from-fastify, from-hono, from-trpc + +Questions: +1. Should this stay separate? (Different audience: framework migrants) +2. Is this genuinely useful or just noise in migration docs? +``` + +## Recommendation Framework + +After running the analysis, consolidate based on these principles: + +1. **Maintainer cognitive load**: Fewer PRs = less context switching, but each PR should have a clear theme +2. **Review difficulty**: Smaller diffs are easier to review, but related changes should be together +3. **Revert granularity**: If something needs reverting, can it be done cleanly? +4. **Merge conflict risk**: Independent PRs can merge in any order + +## My Initial Assessment + +| Current | Recommendation | Rationale | +|---------|----------------|-----------| +| #737 + #738 | Keep stacked | Already dependent, same files | +| #739 | Could merge with #740 | Both add educational comments to lifecycle docs | +| #740 + #741 | Could merge | Both add "// or status(...)" comments to core docs | +| #742 | Keep separate | Tutorial conversions, clear scope | +| #743 | Keep separate | Auth-focused theme is coherent | +| #744 | Keep separate | Catch-all is necessary | +| #745 | Keep separate | Distinct audience (migrants) | + +**Potential consolidation**: Merge #739 + #740 + #741 into one "educational comments" PR. + +This would reduce 9 PRs to 7 PRs: +1. #737 - typo fixes +2. #738 - tutorial explanation (stacked on #737) +3. NEW - educational comments (lifecycle tutorial + essential docs + key-concept) +4. #742 - tutorial conversions +5. #743 - auth conversions +6. #744 - remaining conversions +7. #745 - migration guide tips From 21c33055f7647c95d3ff2c22eb0092b61983da8c Mon Sep 17 00:00:00 2001 From: Braden Wong Date: Fri, 5 Dec 2025 17:40:22 -0800 Subject: [PATCH 3/3] chore: remove specs folder from PR --- docs/specs/20251205T000000-quote-style-fix.md | 43 ------ ...251205T000001-pr-consolidation-analysis.md | 137 ------------------ 2 files changed, 180 deletions(-) delete mode 100644 docs/specs/20251205T000000-quote-style-fix.md delete mode 100644 docs/specs/20251205T000001-pr-consolidation-analysis.md diff --git a/docs/specs/20251205T000000-quote-style-fix.md b/docs/specs/20251205T000000-quote-style-fix.md deleted file mode 100644 index cadd1938..00000000 --- a/docs/specs/20251205T000000-quote-style-fix.md +++ /dev/null @@ -1,43 +0,0 @@ -# Quote Style Fix for String Status Names - -## Issue -PRs #739-#745 introduced string status name examples using double quotes: -```ts -return status("Unauthorized") -``` - -However, the Elysia documentation consistently uses single quotes (680 occurrences of `from 'elysia'` vs 1 occurrence of double quotes). - -The examples should use single quotes to match the codebase style: -```ts -return status('Unauthorized') -``` - -## Files to Update - -### PR #745 - Migration Guides -- `docs/migrate/from-express.md` - line 530 -- `docs/migrate/from-fastify.md` - line 558 -- `docs/migrate/from-hono.md` - line 540 -- `docs/migrate/from-trpc.md` - line 526 - -### PR #739 - Lifecycle Tutorial -- `docs/tutorial/getting-started/life-cycle/index.md` - check for any double-quoted status strings - -### PRs #740-#744 -Check each file touched by these PRs for double-quoted status strings and convert to single quotes. - -## Search Pattern -```bash -grep -rn 'status("' docs/ -``` - -## Fix Pattern -Replace `status("...)` with `status('...')` in all code examples. - -## Verification -After fixing, run: -```bash -grep -rn 'status("' docs/ -# Should return no results (or only results in prose/explanatory text, not code blocks) -``` diff --git a/docs/specs/20251205T000001-pr-consolidation-analysis.md b/docs/specs/20251205T000001-pr-consolidation-analysis.md deleted file mode 100644 index 61da265e..00000000 --- a/docs/specs/20251205T000001-pr-consolidation-analysis.md +++ /dev/null @@ -1,137 +0,0 @@ -# PR Consolidation Analysis - -## Current PRs - -| PR | Title | Files | Category | -|----|-------|-------|----------| -| #737 | fix: correct quote typos in status examples | status-and-headers, error-handling (tutorial) | Bug fix | -| #738 | docs(tutorial): clarify status accepts both number and string names | status-and-headers, error-handling (tutorial) | Educational | -| #739 | docs(tutorial): show string status names in lifecycle examples | life-cycle (tutorial) | Educational | -| #740 | docs: show string status names in lifecycle and error handling | life-cycle.md, error-handling.md (essential/patterns) | Educational | -| #741 | docs: show string status names in key-concept examples | key-concept.md | Educational | -| #742 | docs: use string status names in examples | validation, macro (tutorial) | Conversion | -| #743 | docs: use descriptive string status names for auth errors | guard, encapsulation, plugin, best-practice | Conversion | -| #744 | docs: use string status names consistently across remaining files | index.md, better-auth, extends-context, eden | Conversion | -| #745 | docs(migrate): highlight Elysia string status name advantage | from-express, from-fastify, from-hono, from-trpc | Migration tip | - -## Analysis Questions - -For each PR pair, determine: -1. Do they serve different purposes that justify separate PRs? -2. Would combining them make review harder or easier? -3. Are there any truly redundant changes? - -## Potential Consolidation Groups - -### Group A: Tutorial files (PRs #737, #738, #739, #742) -- #737 + #738: Already stacked, touch same files -- #739: Different file (life-cycle tutorial) -- #742: Different files (validation, macro tutorials) - -**Question**: Should all tutorial-related changes be one PR? - -### Group B: Essential/Pattern docs (PRs #740, #741) -- #740: life-cycle.md, error-handling.md -- #741: key-concept.md - -**Question**: Should core documentation changes be combined? - -### Group C: Auth-focused conversions (#743) -- Standalone theme: auth errors (401, 403) -- 5 files, clear scope - -**Question**: Is this distinct enough to stay separate? - -### Group D: Remaining files (#744) -- Catch-all for remaining conversions -- Mixed files (homepage, integrations, patterns, eden) - -**Question**: Is this too scattered? - -### Group E: Migration guides (#745) -- Clear distinct purpose -- All migration guide files - -**Question**: Should stay separate (different audience) - ---- - -## Subagent Prompt - -To analyze whether these PRs should be consolidated, run this prompt with multiple subagents: - -``` -For each of the following PR groupings, analyze whether they should remain separate or be merged: - -**Subagent 1 - Tutorial PRs Analysis** -Analyze PRs #737, #738, #739, #742 which all touch tutorial files: -- #737: typo fixes in status-and-headers, error-handling tutorials -- #738: adds explanation about string status names to same files -- #739: adds string status name comments to life-cycle tutorial -- #742: converts numeric to string status names in validation, macro tutorials - -Questions: -1. Would a maintainer prefer reviewing these as 4 separate PRs or 1-2 combined PRs? -2. Are any changes redundant or overlapping? -3. What's the clearest way to organize these for review? - -**Subagent 2 - Core Docs Analysis** -Analyze PRs #740, #741 which touch essential documentation: -- #740: adds string status name comments to essential/life-cycle.md, patterns/error-handling.md -- #741: adds string status name comments to key-concept.md - -Questions: -1. These are both "add educational comments" - should they be one PR? -2. Is key-concept.md special enough (MUST READ badge) to warrant its own PR? - -**Subagent 3 - Conversion PRs Analysis** -Analyze PRs #743, #744 which convert numeric codes to string names: -- #743: converts 401/403 to "Unauthorized"/"Forbidden" in auth-related files (guard, encapsulation, plugin, best-practice) -- #744: converts remaining files (homepage, better-auth, extends-context, eden) - -Questions: -1. Should all "conversion" changes be one PR? -2. Is the auth-focused theme of #743 worth preserving as separate? -3. Is #744 too scattered (5 unrelated files)? - -**Subagent 4 - Migration Guide Analysis** -Analyze PR #745 which adds tip boxes to migration guides: -- Adds tip highlighting Elysia's string status name advantage -- 4 files: from-express, from-fastify, from-hono, from-trpc - -Questions: -1. Should this stay separate? (Different audience: framework migrants) -2. Is this genuinely useful or just noise in migration docs? -``` - -## Recommendation Framework - -After running the analysis, consolidate based on these principles: - -1. **Maintainer cognitive load**: Fewer PRs = less context switching, but each PR should have a clear theme -2. **Review difficulty**: Smaller diffs are easier to review, but related changes should be together -3. **Revert granularity**: If something needs reverting, can it be done cleanly? -4. **Merge conflict risk**: Independent PRs can merge in any order - -## My Initial Assessment - -| Current | Recommendation | Rationale | -|---------|----------------|-----------| -| #737 + #738 | Keep stacked | Already dependent, same files | -| #739 | Could merge with #740 | Both add educational comments to lifecycle docs | -| #740 + #741 | Could merge | Both add "// or status(...)" comments to core docs | -| #742 | Keep separate | Tutorial conversions, clear scope | -| #743 | Keep separate | Auth-focused theme is coherent | -| #744 | Keep separate | Catch-all is necessary | -| #745 | Keep separate | Distinct audience (migrants) | - -**Potential consolidation**: Merge #739 + #740 + #741 into one "educational comments" PR. - -This would reduce 9 PRs to 7 PRs: -1. #737 - typo fixes -2. #738 - tutorial explanation (stacked on #737) -3. NEW - educational comments (lifecycle tutorial + essential docs + key-concept) -4. #742 - tutorial conversions -5. #743 - auth conversions -6. #744 - remaining conversions -7. #745 - migration guide tips