@quanticdigit/web-model

Typed model reconstruction from JSON: BaseModel and the expose decorators for dates and nested models.

This package holds the machinery, not the models. Your own model hierarchy lives in your product, where your generator writes it from your DTOs — those are your entity conventions, and a shared package that contained them would force the second consumer to adopt the first one's.

Install

npm install @quanticdigit/web-model class-transformer reflect-metadata

class-transformer and reflect-metadata are peer dependencies.

Import reflect-metadata once

The decorators read type metadata. Without this import they silently find nothing:

// main.ts, before anything else
import 'reflect-metadata';

Writing a model

import { Exclude } from 'class-transformer';
import { BaseModel, ExposeDateOnly, ExposeDateTimeOffset, ExposeModel } from '@quanticdigit/web-model';

@Exclude()
export class Observation extends BaseModel {
  @ExposeDateOnly() declare takenOn: Date;
  @ExposeDateTimeOffset() declare createdAt: Date;
  @ExposeModel(() => Species) declare species: Species;

  public override init(): void {
    this.takenOn = new Date();
    this.createdAt = new Date();
    this.species = new Species();
  }
}

Then a plain object from the wire becomes a typed instance, and back:

const model = new Observation({ takenOn: '2026-08-29', species: { code: 'ABI' } });

model.takenOn;            // a Date
model.species;            // a Species instance, not a plain object
model.toPlainObject();    // { takenOn: '2026-08-29', species: { code: 'ABI' } }

The decorators

| Decorator | Wire format | |---|---| | ExposeDateOnly | 2026-08-29 | | ExposeTimeOnly | 09:30:15 or 09:30:15.250 | | ExposeDateTimeOnly | 2026-08-29T14:05:30.123, no zone | | ExposeDateTimeOffset | a full instant with zone | | ExposeTimeOffset | a time of day carrying a zone | | ExposeModel | a nested model, reconstructed as an instance |

Round trips are stable across time zones: a date-only value read east of Greenwich is written back as the same day.

The family

web-utils, web-model, web-services, web-component and web-errors are released together and always share the same version. Install them at the same version.

License

Commercial. See LICENSE.txt in the package.