tsed-models

# Ts.ED Models, Validation and Serialization One class describes the JSON Schema, the validation rules, the mapping and the OpenAPI model. The schema is the source of truth: what is not described does not exist. Package map (never import from `@tsed/common`): | Concern | Package | | --------------------------------------------------------------------------------------------------- | ------------------------ | | Schema decorators, `s`, `getJsonSchema` | `@tsed/schema` | | `serialize`, `deserialize`, `OnSerialize`, `OnDeserialize`, `BeforeDeserialize`, `AfterDeserialize` | `@tsed/json-mapper` | | `Formats`, `Keyword`, `AjvService` | `@tsed/ajv` (plus `ajv`) | | `ValidationPipe`, `ValidationError` | `@tsed/platform-params` | ## 1. Describe the model ```typescript import {CollectionOf, Default, Email, Enum, Groups, MinLength, Nullable, Property, Required} from "@tsed/schema"; import {Role} from "./Role.js"; export class User { @Groups("!creation") id: string; @Required() @MinLength(3) name: string; @Required() @Email() email: string; @Enum("admin", "member") @Default("member") kind: string = "member"; @Nullable(String) bio: string | null; @CollectionOf(Role) roles: Role[]; @Property() createdAt: Date; } ``` 1. Use classes. Interfaces and type aliases carry no runtime metadata. 2. Put at least one schema decorator on every property; `@Property()` is the minimum. Undecorated properties are dropped from the schema, from deserialized inputs and from serialized outputs. 3. Declare the item type of every `Array`, `Map` and `Set` with `@CollectionOf(Item)` (aliases `@ArrayOf`, `@MapOf`). Use `@RecordOf` for records. 4. Presence and nullability are separate: `@Required()` / `@Optional()` versus `@Nullable(Type)`. `@Required()` treats `undefined`, `null` and `""` as missing; whitelist a value with `@Allow("")` or `@Allow(null)`. 5. Constraints: `@MinLength`/`@MaxLength`, `@Minimum`/`@Maximum` (aliases `@Min`/`@Max`), `@Pattern`, `@Format("date")`, `@Email`, `@Uri`, `@Url`, `@DateTime`, `@Enum`, `@Const`, `@Integer`, `@MinItems`/`@MaxItems`/`@UniqueItems`. 6. Rename on the wire with `@Name("first_name")`. Mark direction with `@ReadOnly()` / `@WriteOnly()`. Document with `@Description`, `@Example`, `@Title`. 7. Allow unknown keys per model with `@AdditionalProperties(true)` (or a schema). Do not enable `jsonMapper.additionalProperties` globally to work around a missing decorator. 8. Polymorphism: `@OneOf(A, B)` / `@AnyOf` / `@AllOf`. Add `@DiscriminatorKey()` on the base property and `@DiscriminatorValue("a")` on each subclass so `deserialize` instantiates the right class. 9. Generics: `@Generics("T")` on the class, `@CollectionOf("T")` or `@Property("T")` on the member, then bind at the endpoint with `@(Returns(200, Pagination).Of(Product))`. 10. Do not use `@Ignore()` in new code (deprecated); use `@Groups`. ## 2. Vary the model with groups 1. `@Groups("creation")` exposes a property only for that group; `@Groups("!creation")` hides it for that group; patterns such as `group.*` match several. 2. Select groups on input with `@BodyParams() @Groups("creation") user: User` and on output with `@(Returns(200, User).Groups("read"))`. 3. `@BodyParams() @Partial() payload: User` makes all properties optional for PATCH. 4. Set `jsonMapper.strictGroups: true` in new applications. Without it, an endpoint that declares no group exposes every grouped property, and the generated documentation does not match the runtime. ## 3. Enable validation ```typescript import "@tsed/ajv"; import {Configuration} from "@tsed/di"; @Configuration({ ajv: {returnsCoercedValues: true}, jsonMapper: {strictGroups: true} }) export class Server {} ``` 1. Install `ajv` and `@tsed/ajv`, and import `@tsed/ajv` in the server. Without a registered validator the built-in `ValidationPipe` only checks required parameters; every other constraint is silently skipped. 2. The `ajv` configuration key takes AJV constructor options directly, plus `errorFormatter` and `returnsCoercedValues`. 3. Failures throw `AjvValidationError` (a `BadRequest`, name `AJV_VALIDATION_ERROR`, with `errors[]`), returned as 400. Payload shape and customization: tsed-exceptions. 4. Custom messages: `.Error("...")` on a constraint decorator, or `@ErrorMsg`, `@TypeError`, `@DefaultMsg`. 5. Custom format: `@Formats("slug", {type: "string"})` on a class implementing `FormatsMethods<string>` (`validate(value): boolean`); apply with `@Format("slug")`. 6. Custom keyword: `@Keyword({keyword: "range", type: "number", schemaType: "array"})` on a class implementing `KeywordMethods` (`compile` or `validate`); apply with `@CustomKey("range", [1, 10])`. 7. Import format and keyword classes from the server entry point, otherwise they are never registered. 8. Replace the validator only as a last resort: extend `ValidationPipe` and decorate with `@OverrideProvider(ValidationPipe)` from `@tsed/di`, throwing `ValidationError`. OpenAPI and mapping keep using the JSON Schema. ## 4. Map outside of controllers ```typescript import {deserialize, serialize} from "@tsed/json-mapper"; import {s} from "@tsed/schema"; import {User} from "./models/User.js"; const user = deserialize<User>(input, {type: User, groups: ["creation"]}); const users = deserialize<User[]>(list, {type: User, collectionType: Array}); const json = serialize(user, {type: User, groups: ["read"]}); const schema = s.compile(User, {groups: ["creation"]}); // getJsonSchema() is the deprecated alias ``` 1. Controllers call these automatically for `@BodyParams`, `@QueryParams`, `@PathParams` and for returned values. Call them yourself for queues, sockets, caches and tests. 2. `deserialize` does not validate. Validate first with `AjvService.validate(value, {type: User})`. 3. Transform one property with `@OnSerialize((value) => ...)` / `@OnDeserialize((value) => ...)`; hook the whole class with `@BeforeDeserialize` / `@AfterDeserialize`. All four come from `@tsed/json-mapper`. 4. The constructor does not receive the payload unless `jsonMapper.disableUnsecureConstructor` is `false`. Do not rely on `Object.assign(this, data)` constructors. ## 5. Use the functional builder when a class is not wanted ```typescript import {s} from "@tsed/schema"; export const ProductSchema = s.object({ title: s.string().required().minLength(3), price: s.number().minimum(0), tags: s.array(s.string()) }); export type Product = s.infer<typeof ProductSchema>; ``` `s` is the only builder export to use (`s.string`, `s.number`, `s.integer`, `s.boolean`, `s.date`, `s.datetime`, `s.email`, `s.enums`, `s.array`, `s.map`, `s.set`, `s.record`, `s.oneOf`, `s.anyOf`, `s.allOf`). `s.from(Model)` returns a local copy to compose; `s.get(Model)` returns the shared class schema, so changes to it are global; `s.generic(Pagination).of(Product)` binds generics. ## Pitfalls - Field missing from the response or `undefined` in the handler: no decorator on the property. - Array items arrive as plain objects: `@CollectionOf` is missing, or the parameter decorator did not receive the item class (see tsed-controllers). - Nothing is validated: `@tsed/ajv` is not imported, or the parameter is typed with an interface or `any`. - `null` rejected or coerced: add `@Nullable(Type)`; it is mandatory when `ajv.returnsCoercedValues` is enabled. - Password leaks in a response: groups are declared but the endpoint sets none and `strictGroups` is off. - `@DiscriminatorKey()` property typed with the enum: keep it `string`; values come from `@DiscriminatorValue`. - `OnSerialize` imported from `@tsed/schema` (as some doc pages show) does not compile; import it from `@tsed/json-mapper`. ## Checklist - Classes only; every property decorated; every collection has `@CollectionOf`. - `@tsed/ajv` imported in the server; `jsonMapper.strictGroups` decided explicitly. - Groups set on both the input parameter and `@Returns` where the shape differs. - Custom formats and keywords imported at startup. - Schema checked with `s.compile(Model)` in a unit test (see tsed-testing). - No `@tsed/common` import; relative imports end with `.js`. Depth: https://tsed.dev/docs/model.md, https://tsed.dev/docs/validation.md, https://tsed.dev/docs/json-mapper.md. OpenAPI output: tsed-openapi.