feat: add t.External() helper for external TypeBox schema compatibility

[raunak-rpm]

Summary

This adds a new t.External() helper method that allows schemas from external TypeBox packages (like drizzle-typebox) to be used with Elysia's type system.

Problem

TypeBox uses a unique symbol for its Kind property. When schemas are created by different packages (like drizzle-typebox), TypeScript may see them as having different symbol identities, causing errors like:

Property '[Kind]' is missing in type 'TObject<...>' but required in type 'TSchema'

This is a fundamental TypeScript limitation with unique symbols across module boundaries, affecting users of:

• drizzle-typebox
• @sinclair/typebox (when imported separately)
• Any external package that generates TypeBox schemas

Solution

The t.External() helper wraps external TypeBox schemas with a type assertion that:

• Preserves full static type inference
• Makes schemas compatible with Elysia's TypeBox instance
• Has zero runtime overhead (identity function with type cast)

Usage

import { createSelectSchema } from 'drizzle-typebox'
import { t, Elysia } from 'elysia'

const UserSchema = createSelectSchema(usersTable)

const app = new Elysia()
  .get('/users', () => users, {
    response: t.Array(t.External(UserSchema))
  })

Changes

• Added t.External() method in src/type-system/index.ts
• Added comprehensive test suite in test/type-system/external.test.ts

Testing

• All 1454 tests pass
• 7 new tests for t.External() functionality

Fixes #1688
Related: #690, #1320, #1318

Summary by CodeRabbit

• New Features
  • Added External method to wrap and integrate external TypeBox schemas across different TypeBox instances. This enhancement enables seamless compatibility when using third-party or externally-defined schemas, while preserving static type inference and ensuring proper runtime validation throughout your application's routes and response definitions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a new External method to the Elysia type system that wraps external TypeBox schemas for cross-instance compatibility, enabling integration with libraries like drizzle-typebox. Implementation includes method definition and comprehensive test coverage validating schema wrapping, type preservation, and runtime validation behavior.

Changes

Cohort / File(s)	Summary
Type system implementation src/type-system/index.ts	Introduces External method to ElysiaType class that wraps external TypeBox schemas. Preserves static type information while enabling compatibility across different TypeBox instances. Exposes method on public t wrapper.
Test suite test/type-system/external.test.ts	Comprehensive test coverage for t.External() functionality, validating schema wrapping, type inference preservation, usage within t.Array, route response schemas, response payload validation, nested object handling, and TypeBox Kind symbol compatibility.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A wrapper most clever, so dapper and bright,
External schemas now work just right!
TypeBox from anywhere, near or afar,
Drizzle compatibility—we're raising the bar! ⭐

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding t.External() helper for TypeBox schema compatibility, which is the primary focus of the changeset.
Linked Issues check	✅ Passed	The PR fully addresses issue #1688 by implementing t.External() to solve the TypeBox Kind symbol compatibility problem with external packages like drizzle-typebox.
Out of Scope Changes check	✅ Passed	All changes are in-scope: the new External method in src/type-system/index.ts and comprehensive test coverage in test/type-system/external.test.ts directly address the linked objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/elysiajs/elysia@1689

commit: 179d7f1