conceptadev / conceptadev/rockets

chore: evaluate upgrading @concepta/nestjs-* engine packages to alpha.9 (Zod-native DTOs)

Open
#102 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
1
Forks
2
Avg merge
2d 10h
Merged PRs (30d)
23

Description

## Summary

`@concepta/nestjs-*` alpha.9 replaces class-validator/class-transformer DTOs with Zod across the board. Verified against the actual published packages (not just the announcement) — the claim is real but only partially matches what it implies for us. Tracking issue for the upgrade decision + attempt.

## What was verified (not assumed)

Pulled and diffed the real `.d.ts` files for alpha.8 (currently pinned) vs alpha.9 for all 13 packages.

**Unaffected / purely additive:**
- `@concepta/nestjs-repository`: `RepositoryInterface` is byte-identical. Only addition: `BeforeDeleteMany`/`AfterDeleteMany` hooks.
- `@concepta/nestjs-crud`: the actual consumer-facing config surface (`CrudControllerOptionsInterface`, `ConfigurableCrudBuilder`, `CrudModuleForFeatureOptionsInterface`, `CrudModuleOptionsInterface`) is byte-identical. This is what `rockets-core`'s `defineResource`/zod layer plugs into — untouched.

**Real, confirmed breaking changes:**
- `@concepta/nestjs-crud`: `CrudResponsePaginatedDto` and `CrudCreateBatchDto` (extendable classes) are **removed**, replaced by `paginatedSchema()`/`createBatchSchema()` (zod schema factory functions — not class-extendable). We `extends CrudResponsePaginatedDto<...>` in:
- `packages/rockets-core/src/infrastructure/resource/paginated-dto.factory.ts`
- `packages/rockets-server-auth/src/domains/role/modules/rockets-auth-role-admin.module.ts`
- `packages/rockets-server-auth/src/domains/user/modules/rockets-auth-admin.module.ts`
- plus 3 e2e specs.
- `@concepta/nestjs-user`, `nestjs-role`, `nestjs-otp`, `nestjs-invitation`, `nestjs-federated`, `nestjs-authentication`: **every** PascalCase DTO **class** export (`UserDto`, `UserCreateDto`, `RoleDto`, `RoleCreateDto`, `InvitationDto`, `AuthenticationResponseDto`, `LocalLoginDto`, `RefreshDto`, etc.) is replaced by a lowerCamelCase zod schema **value** (`userSchema`, `userCreateSchema`, ...). Grepping this repo for the old class names hits **32 files** across `rockets-core`, `rockets-server-auth`, `rockets-server`, and e2e specs. `nestjs-password` and `nestjs-access-control` have no DTO exports and are unaffected.

**Compounding, non-optional dependency bump:**
- alpha.9 packages declare `@nestjs/common`/`@nestjs/core: 12.0.0-alpha.6` (we're pinned to `12.0.0-alpha.5`) and `@nestjs/config: 12.0.0-next.0` (we're pinned to the **stable `4.0.4`** — a major-line jump onto a `next` prerelease tag, not the same line at all). This is not a side effect we can skip: the upgrade is really two version bumps in sequence, and the `@nestjs/config` jump is the riskier of the two.

**`@concepta/nestjs-common` drops out of the dependency graph entirely at alpha.9** (transitively pulled in today at `8.0.0-alpha.6`). 5 files in `rockets-server-auth` import 4 symbols from it directly — traced each one, none is a real blocker (see the comment below for the full breakdown):
- `PasswordPlainInterface` — relocated to `@concepta/nestjs-password@8.0.0-alpha.9`, mechanical import-path fix.
- `EmailSendInterface` — **already unneeded**: a local equivalent already exists at `packages/rockets-server-auth/src/shared/email/email-send.interfaces.ts` (created for exactly this reason); 2 files just never switched to it.
- `LiteralObject` — is `Record`. One file, 3 occurrences, trivially inlined as `Record`.
- `ModelQueryException` — used only in a test fixture, never production code; the exceptions filter matches on `.context.originalError` shape, not `instanceof` this class, so a local equivalent works identically.

## Decision: deferred

Also checked whether alpha.9 would let `rockets-core`'s own zod bridge
(`compileDtoClass` et al., `packages/rockets-core/src/zod/**`) go away.
It would not: `CrudRequestConfig.body` (the field our bridge compiles a
zod schema down into) is still typed `Type` — a class, not a
schema/Standard-Schema value — and that file is part of the
byte-identical surface above. The DTO-class-to-schema-value swap only
happened in the identity packages' own pre-built resources, not in
`nestjs-crud`'s generic registration contract. So there is no
architectural upside for us here beyond the identity-package DTOs
themselves.

Given that — no functional gain for `rockets-core`'s own integration,
~32 touched consumer files, and a compounding Nest-core +
`@nestjs/config: 12.0.0-next.0` (prerelease tag) bump — **decided to
defer.** Revisit once the `@concepta/nestjs-*` alpha.9 line reaches a
stable (non-alpha, non-`next`-peer) release, and once the currently
open backlog PRs (#92-#100) have landed, so a dependency migration
doesn't collide with in-review work.

The `@concepta/nestjs-common` cleanup above (stop importing 4 symbols
we don't need) remains worth doing independently of this decision —
it is not blocked on the rest of this upgrade.

## References

- Verified 2026-08-25 against `@concepta/nestjs-*@8.0.0-alpha.9` on npm (all 13 packages inspected via `npm pack` + `.d.ts` diff against the currently installed `alpha.8`/`7.0.0-alpha.10`).

Contributor guide

Open the contributing guide

Research direction

Treat this as a deferred migration rather than an immediately actionable change. When revisiting, start with the listed paginated DTO factory, auth modules, the 32 old DTO references, and the packages/rockets-core/src/zod/** bridge; verify the alpha.9 package types and dependency requirements first. Done means the upgrade is compatible, the DTO consumers and e2e specs are migrated, and the independent nestjs-common imports are cleaned up without colliding with PRs #92-#100.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.