Create Platform Adapter

Create Ts.ED Platform Adapter

Build the adapter around Ts.ED's HTTP abstractions, not by copying an existing implementation wholesale. Preserve the target framework's lifecycle and native request/response model.

Read the adapter reference before designing or implementing. It summarizes the repository's Express, Koa, and Fastify patterns and the PlatformAdapter contract.

1. Establish feasibility and scope

1. Confirm the target runtime can support Ts.ED routing, async middleware, status/headers/cookies, streams or equivalent bodies, error propagation, and a testable HTTP entry point.
2. Identify whether it is Node IncomingMessage/ServerResponse compatible. For Fetch-native runtimes, explicitly design the bridge instead of pretending Node response mutation works.
3. Record framework-version support, required plugins, and unsupported Ts.ED features. Do not silently omit multipart uploads, static assets, or serverless callback support.
4. Do not start or apply an OpenSpec workflow from this skill. The workflow below is the source of truth for the adapter implementation.

2. Inspect local precedents

Read these sources before creating files:

• packages/platform/platform-http/src/common/services/PlatformAdapter.ts
• packages/platform/platform-express/src/components/PlatformExpress.ts
• packages/platform/platform-koa/src/components/PlatformKoa.ts
• packages/platform/platform-fastify/src/components/PlatformFastify.ts
• Each package's src/services/, src/utils/convertPath.ts, src/index.ts, package manifest, Vitest config, and focused specs.
• packages/platform/platform-express/test/platform-express.spec.ts, packages/platform/platform-koa/test/platform-koa.spec.ts, and packages/platform/platform-fastify/test/platform-fastify.spec.ts.
• docs/introduction/capabilities.md, docs/docs/configuration/{express,koa,fastify}.md, docs/docs/configuration/index.md, docs/index.md, and docs/.vitepress/config.mts.

Choose the closest precedent by execution model: Express for Connect-style middleware, Koa for composed async middleware, Fastify for plugin/route-registration APIs. Reuse intent and coverage, not framework-specific calls.

3. Create the package

Create packages/platform/platform-<framework>/ using a comparable package as a structural template. Adapt, do not blindly duplicate:

• package.json: ESM exports, build/test/barrel scripts, framework peer dependency, Ts.ED peer dependencies, and only runtime dependencies required by the adapter.
• tsconfig.esm.json, vitest.config.mts, .npmignore, and package readme.md.
• src/index.ts: export only the supported public adapter class, settings, decorators, and helpers.
• test/app/: a minimal server, framework-plugin setup, and shared integration fixtures compatible with PlatformTestSdk.
• test/platform-<framework>.spec.ts: the explicit @tsed/platform-test-sdk integration capability matrix. This file is mandatory for every new platform; a route-conversion or unit-only test suite is not a substitute.

Keep the framework itself a peer dependency; put it in devDependencies at a pinned test version. The workspace glob already discovers packages/platform/*; only update other package catalogues if a real registry, docs, or release surface needs the entry.

For vitest.config.mts, use the workspace preset import with this explicit type-resolution exception:

// @ts-ignore
import {presets} from "@tsed/vitest/presets";

Add the new public package alias to both tsconfig.node.json and tsconfig.spec.json. For Fetch-native platforms with native FormData parsing, prefer that API in the platform package and document Multer decorators and storage engines as unsupported; do not create a @tsed/platform-multer/<framework> alias unless the Multer middleware contract is proven compatible.

4. Implement the adaptations

Create Platform<Framework> extends PlatformAdapter<App> with:

1. NAME, static create() and bootstrap() through PlatformBuilder.
2. createApp() returning the framework app and a valid request callback. If the framework cannot yield a Node callback, implement and document the appropriate server/runtime boundary.
3. useContext() that creates a PlatformContext, awaits $ctx.start(), makes it available to mapped handlers, and reliably calls $ctx.finish() when the response completes.
4. mapLayers() translating PlatformLayer methods, paths, wildcard parameters, statics, and handler ordering to the framework router.
5. mapHandler() that runs in the Ts.ED DI context, captures async errors, and preserves error-middleware and response-function semantics.
6. bodyParser(), statics(), server/listening hooks, and framework-specific lifecycle hooks where the base contract requires them.
7. adapter() bindings for the framework-specific PlatformRequest, PlatformResponse, and PlatformHandler implementations.

Do not expose a framework's raw request/response directly to controllers without adapters. Map all semantics needed by PlatformRequest and PlatformResponse: URL and query, params, protocol and host, cookies/session, status, headers, redirect, body serialization, file/download, stream, and completion state.

5. Handle framework boundaries explicitly

• Convert Ts.ED route syntax with a framework-specific convertPath() and test named, optional, regexp, and wildcard paths.
• Preserve the framework's error path. Do not call a Connect next(error) from a Koa/Fastify/Fetch handler unless the target framework actually supports it.
• Route errors through PlatformExceptions.catch(error, $ctx) and route unknown paths through PlatformExceptions.resourceNotFound($ctx). Reuse the existing exception filters; do not handcraft framework-specific error or 404 response payloads.
• Register body parsing, multipart support, static serving, view rendering, and raw-body capture only when supported. Make plugin registration awaitable when required. Match PlatformBuilder's global rawBody policy: capture the raw buffer only when rawBody is configured or @RawBodyParams() is detected, while preserving the framework-parsed body. For Fetch-native runtimes, capture it before parsing with request.clone() only when request.body exists; do not globally disable parsing with a per-route parse: "none" strategy. Fall back to body when no raw capture is active.
• Make HTTP/HTTPS creation and listen() match the framework's ownership model. Confirm the callback works with serverless-http-style consumers if the adapter claims serverless support.
• Keep framework module augmentation and Ts.ED global declarations narrow and public.

6. Build and run the integration matrix

After the package and platform adaptations exist, add focused unit tests and create test/platform-<framework>.spec.ts with PlatformTestSdk.create({rootDir, adapter, server}). Build the spec from the Express, Koa, and Fastify precedents, then run it before documenting the platform as supported.

• Use Express and Koa as the implementation baseline.
• Use Fastify only to understand framework-specific integration differences; do not copy its skips as an escape hatch.
• Add the test/app/ fixtures needed by the SDK instead of omitting a scenario.

The following SDK groups are mandatory for every new platform. Keep them enabled, make them pass, and do not wrap them in describe.skip:

• handlers, childrenControllers, inheritanceController, response, stream, middlewares, scopeRequest, headers, acceptMime, headerParams, pathParams, queryParams, bodyParams, cookies, session, location, redirect, errors, responseFilter, routing, locals, auth, module, and cache.
• view, statics, deepQueryParams, and custom404.

For Fetch-native platforms, test multipart independently with native FormData and File body parameters. Do not add the SDK Multer suite when Multer's middleware contract is incompatible; document that Multer decorators and storage engines are unavailable.

Iterate on the adapter until the mandatory suite passes. Tackle isolated SDK gaps first (for example custom 404, deep query parsing, framework plugins, and test fixtures). Defer structural Fetch-native response work—stream bridging, response finalization, and Node callback emulation—until those simpler gaps are resolved. Then add coverage for adapter-specific behavior not supplied by the SDK, including bootstrap/create, native callback behavior, route conversion, error propagation, raw body, native multipart, and runtime/server lifecycle.

Update all public documentation in the same change:

1. Add the framework column and supported/unsupported states to both feature and plugin tables in docs/introduction/capabilities.md; explain limitations below the tables when a marker needs context.
2. Create docs/docs/configuration/<framework>.md, modeled on the closest adapter page. Cover installation, framework settings/plugins, static files, and use of a custom application instance.
3. Link the new page from docs/docs/configuration/index.md and add it to the Configuration sidebar in docs/.vitepress/config.mts.
4. Add the platform and configuration-page link to docs/index.md wherever the existing Express/Koa/Fastify list appears.

Follow this order: create the package; implement the platform adaptations; add the SDK matrix and its fixtures; execute the matrix; iterate on missing framework features until it passes; then run the package tests, yarn tsc -b from the repository root, affected lint checks, and the documentation build. Do not use a package-scoped tsc --build command.

Completion checklist

• Every mandatory PlatformTestSdk group is enabled and passing; none is skipped.
• The complete test/platform-<framework>.spec.ts matrix, checked against the Express, Koa, and Fastify precedents, exists and has been executed successfully.
• Framework capability gaps are documented in capabilities.md, the platform configuration page, navigation, and homepage.
• PlatformAdapter lifecycle, request/response/handler bindings, and route conversion are covered.
• Public package metadata, exports, peer dependencies, docs, and integration tests are complete.
• No Express/Koa/Fastify assumptions remain in the new adapter.