drafael/coding-harness / skills/typescript-coder
typescript-coder
UnverifiedMandatory for every task in a TypeScript or mixed TypeScript codebase, including planning, implementation, debugging, refactoring, review, testing, dependency and build changes, CI, security analysis, and TypeScript-related documentation. Detect projects from tsconfig files, .ts/.tsx sources, TypeScript dependencies, or TypeScript framework configuration. Load before inspecting or changing such repositories. Covers Node.js, Bun, existing Deno projects, backend, frontend, CLI/TUI, Electron, Electrobun, Tauri, AWS CDK, and modern tooling.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 4.1 KB |
| SKILL.md | skill md | 11.8 KB |
| references/aws-cdk.md | markdown | 9.6 KB |
| references/backend.md | markdown | 6.2 KB |
| references/cli-and-tui.md | markdown | 7.6 KB |
| references/dependencies-linting-formatting.md | markdown | 5.7 KB |
| references/desktop.md | markdown | 9.1 KB |
| references/frontend.md | markdown | 6.7 KB |
| references/language-and-tsconfig.md | markdown | 8.9 KB |
| references/modules-packages-runtimes.md | markdown | 5.9 KB |
| references/project-detection.md | markdown | 5.2 KB |
| references/security.md | markdown | 8.1 KB |
| references/testing-and-builds.md | markdown | 5.6 KB |
references/backend.md
View on GitHub# Backend TypeScript
Apply these rules to HTTP services, workers, queues, scheduled jobs, WebSockets, and backend-for-frontend packages.
## Architecture
Use the smallest structure that keeps responsibilities clear:
```text
transport/framework → application use case → domain logic → infrastructure adapter
```
- Transport owns HTTP/RPC parsing, authentication context, status codes, and response serialization.
- Application code coordinates use cases and transactions.
- Domain code owns business invariants where the domain warrants a distinct layer.
- Infrastructure adapters own databases, queues, files, external APIs, and framework-specific details.
Do not create layers with no meaningful boundary. Conversely, do not put business rules directly into route handlers when they need reuse or focused tests.
## Input and Output Boundaries
- Treat body, query, path, headers, cookies, messages, database JSON, and upstream responses as untrusted runtime values.
- Validate and normalize once near the boundary. Infer types from schemas when the chosen library supports it, avoiding duplicate interfaces that can drift.
- Validate output where contract integrity or Fastify-style serialization schemas justify it.
- Authentication establishes identity; authorization decides whether that identity may perform the operation. Apply authorization in every access path.
- Bound body sizes, uploads, pagination, batch sizes, concurrency, retries, and timeouts according to exposure.
## Errors and Observability
- Map known domain/application errors to stable public responses in one boundary layer.
- Return generic 5xx details to clients while preserving safe structured diagnostics internally.
- Preserve causes and attach request/trace identifiers without logging secrets or entire untrusted payloads.
- Use structured logs with stable event names and fields. Avoid interpolated log strings that are difficult to query.
- Distinguish expected client failures from operational failures; do not page on routine validation errors.
## Lifecycle and I/O
- Load and validate configuration once at startup, then pass typed configuration inward. Avoid scattered environment reads.
- Fail startup on invalid required configuration rather than failing on the first request.
- Use connection pooling and close servers, workers, consumers, telemetry, and database clients during graceful shutdown.
- Propagate cancellation/time budgets where downstream APIs support them.
- Retry only transient failures, with bounded backoff/jitter and idempotency analysis.
- Avoid blocking synchronous work on request paths. Move CPU-heavy work to workers/processes when measurement justifies it.
## Framework Adaptation
### Express
- Build focused routers and middleware; keep handlers thin enough to expose application intent.
- Validate before application logic and centralize error translation in error middleware.
- Understand the installed Express generation's async error behavior; do not copy version-incompatible wrappers.
- Configure proxy trust, cookies, CORS, body limits, and security headers according to the real deployment topology.
### Fastify
- Prefer route JSON Schema for validation and serialization where the project uses Fastify's schema model.
- Keep TypeScript schema types and runtime schemas derived from one source or verified together.
- Use plugins and encapsulation for ownership, not a global decoration dumping ground.
- Treat schemas as application code. Fastify warns that validation/serialization uses dynamic code generation; do not compile user-provided schemas.
- Perform database-backed authorization in hooks/handlers after structural validation, not as an initial schema validator.
### NestJS
- Use constructor injection and cohesive modules/providers.
- Use `ValidationPipe` or the project's chosen schema pipe at transport boundaries; configure transformation/whitelisting deliberately rather than assuming defaults.
- Use guards for authorization, interceptors for cross-cutting request behavior, pipes for transformation/validation, and exception filters for boundary translation.
- Keep business logic out of controllers and avoid resolving providers through a service locator when normal injection works.
### Hono
- Account for the actual target runtime—Node, Bun, Deno, Cloudflare Workers, or another edge platform.
- Use Hono validation middleware or the established schema adapter and retrieve validated values through the framework's validated access path.
- Keep middleware environment bindings and context variables typed.
- Avoid Node-only APIs in portable/edge packages unless the deployment target supports them.
## Persistence and Transactions
- Parameterize queries; never build SQL from unchecked interpolation.
- Keep transaction boundaries around one application operation and avoid remote network calls inside long transactions when possible.
- Treat ORM types as persistence representations, not automatic public API schemas.
- Plan migrations for compatibility, rollback/recovery, and data volume. Do not run destructive schema changes implicitly at service startup in production.
- Make idempotency explicit for retried messages, webhooks, payments, and job processing.
## Testing
Prioritize:
- Pure business rules and validators.
- Route/transport integration with realistic framework injection/test helpers.
- Authorization denial paths and tenant/resource ownership.
- Persistence adapters against a representative database where query semantics matter.
- Timeout, retry, idempotency, shutdown, and duplicate-message behavior.
- Contract tests for external APIs or generated clients at the integration boundary.
## Sources
- [Fastify validation and serialization](https://fastify.io/docs/latest/Reference/Validation-and-Serialization/)
- [Fastify TypeScript](https://fastify.io/docs/latest/Reference/TypeScript/)
- [NestJS validation](https://docs.nestjs.com/techniques/validation)
- [NestJS exception filters](https://docs.nestjs.com/exception-filters)
- [NestJS testing](https://docs.nestjs.com/fundamentals/testing)
- [Hono validation](https://hono.dev/docs/guides/validation)
- [Hono testing](https://hono.dev/docs/guides/testing)
- [Express security best practices](https://expressjs.com/en/advanced/best-practice-security.html)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |