@quanticdigit/web-model 1.0.1 → 1.0.2

package/README.md

@@ -1,64 +1,78 @@
-# WebModel
+# @quanticdigit/web-model
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.2.0.
+Typed model reconstruction from JSON: `BaseModel` and the expose decorators for dates and nested
+models.
 
-## Code scaffolding
+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.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+## Install
 
 ```bash
-ng generate component component-name
+npm install @quanticdigit/web-model class-transformer reflect-metadata
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+`class-transformer` and `reflect-metadata` are peer dependencies.
 
-```bash
-ng generate --help
-```
-
-## Building
+## Import reflect-metadata once
 
-To build the library, run:
+The decorators read type metadata. Without this import they silently find nothing:
 
-```bash
-ng build web-model
+```ts
+// main.ts, before anything else
+import 'reflect-metadata';
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
-
-### Publishing the Library
-
-Once the project is built, you can publish your library by following these steps:
+## Writing a model
 
-1. Navigate to the `dist` directory:
+```ts
+import { Exclude } from 'class-transformer';
+import { BaseModel, ExposeDateOnly, ExposeDateTimeOffset, ExposeModel } from '@quanticdigit/web-model';
 
-   ```bash
-   cd dist/web-model
-   ```
+@Exclude()
+export class Observation extends BaseModel {
+  @ExposeDateOnly() declare takenOn: Date;
+  @ExposeDateTimeOffset() declare createdAt: Date;
+  @ExposeModel(() => Species) declare species: Species;
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+  public override init(): void {
+    this.takenOn = new Date();
+    this.createdAt = new Date();
+    this.species = new Species();
+  }
+}
+```
 
-## Running unit tests
+Then a plain object from the wire becomes a typed instance, and back:
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+```ts
+const model = new Observation({ takenOn: '2026-08-29', species: { code: 'ABI' } });
 
-```bash
-ng test
+model.takenOn;            // a Date
+model.species;            // a Species instance, not a plain object
+model.toPlainObject();    // { takenOn: '2026-08-29', species: { code: 'ABI' } }
 ```
 
-## Running end-to-end tests
+## The decorators
 
-For end-to-end (e2e) testing, run:
+| 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 |
 
-```bash
-ng e2e
-```
+Round trips are stable across time zones: a date-only value read east of Greenwich is written back as
+the same day.
+
+## The family
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+`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.
 
-## Additional Resources
+## License
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+Commercial. See `LICENSE.txt` in the package.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@quanticdigit/web-model",
-  "version": "1.0.1",
-  "description": "Ricostruzione dei modelli tipizzati dal JSON: BaseModel e i decoratori di esposizione.",
+  "version": "1.0.2",
+  "description": "Typed model reconstruction from JSON: BaseModel and the expose decorators for dates and nested models.",
   "author": "Quantic Digit S.R.L.",
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://www.quanticdigit.it/",