@smartsoft001/models

Describes an entity once with decorators, and exposes readers so generic code can validate it, render it and trim it down per operation.

Install

npm install @smartsoft001/models

The manifest declares both runtime companions, so installing this package brings them along. The decorators call Reflect.defineMetadata, which comes from reflect-metadata, and the field decorator calls ObjectService.createByType from @smartsoft001/utils whenever a field declares a classType.

What it is

The package is the description layer the rest of the framework reads. @Model marks a class as a framework model and @Field records, per property, what kind of value it holds and how each operation may touch it. None of that lands in the class body. Both decorators write into reflect-metadata, keyed by the SYMBOL_MODEL and SYMBOL_FIELD symbols, which keeps the entity a plain class that a domain layer can construct without pulling in a framework.

The reader functions are what make the metadata useful. getModelFieldKeys returns the decorated property names of a type in declaration order, and that order is what the generated form and the generated list columns follow. getModelFieldOptions and getModelFieldsWithOptions hand back the options recorded for one field or for all of them, which is how a component decides which editor to build. isModel reports whether a value belongs to a decorated class at all, which is how generic code tells a model apart from a plain object before it tries to read either of the other two.

Two functions go further than reading. getInvalidFields returns the required fields that are still empty for a given operation, and castModel deletes everything that must not take part in that operation. Together they are the validation and the payload trimming the CRUD service in @smartsoft001/crud-shell-app-services applies to every incoming record: it casts the data for the operation, then rejects the request with a DomainValidationError naming the required fields that are still empty. The decorators also change how an instance serialises: @Model installs a toJSON on the prototype, which matters because a field declared with a classType is stored behind an underscore-prefixed backing property, and toJSON puts it back under its real name.

Usage

An entity is an ordinary class with decorators on the properties that the framework should know about.

import { IEntity } from '@smartsoft001/domain-core';
import { Field, FieldType, Model } from '@smartsoft001/models';

@Model({ titleKey: 'email' })
export class User implements IEntity<string> {
  id!: string;

  @Field({ type: FieldType.email, required: true })
  email!: string;

  @Field({ type: FieldType.int })
  age?: number;
}

@Model({ titleKey: 'email' }) names the field that stands in for the record in titles and lists. On each property, type picks the editor and the validation, and required: true marks the field mandatory. @Field is never silent about the type: a decorator called without one falls back to FieldType.text, except on a property literally named password, which falls back to FieldType.password.

Validation and payload trimming read the same metadata, and both are sensitive to the per-mode blocks.

import {
  castModel,
  Field,
  FieldType,
  getInvalidFields,
  Model,
} from '@smartsoft001/models';

@Model({ titleKey: 'name' })
export class Product {
  id?: string;

  // `required` declared inside the `create` block applies to the create mode
  // only. A bare `create: true` would mark the field as editable on create but
  // would also reset the top level `required` flag back to "not required".
  @Field({ type: FieldType.text, create: { required: true } })
  name?: string;

  @Field({ type: FieldType.currency, create: true })
  price?: number;

  // No `create` block, so `castModel` removes it from a create payload.
  @Field({ type: FieldType.text })
  internalNote?: string;
}

/** Returns the keys of the fields required on create that are still empty. */
export function missingFields(product: Product): Array<string> {
  return getInvalidFields(product, 'create', []);
}

/**
 * Strips everything that must not reach the create endpoint.
 * `castModel` mutates the object in place, so the example copies it first. It
 * keeps `id` plus every field marked for the mode, and deletes the rest,
 * including properties that carry no `@Field` decorator at all.
 */
export function toCreatePayload(product: Product): Product {
  const payload = Object.assign(new Product(), product);

  castModel(payload, 'create', []);

  return payload;
}

The spec that runs this example proves four things. An empty name comes back from getInvalidFields(product, 'create', []) as the one missing field, and a filled product yields an empty array; empty here means null, undefined or the empty string, not a falsy number. toCreatePayload keeps id and the two fields that carry a create block, and drops internalNote, which has none. And because the example copies the product before casting, the original still holds its internal note afterwards: castModel mutates the object it is given rather than returning a new one.

The comment in the example is the trap worth repeating. A mode block replaces the top-level required flag instead of inheriting it, and a bare create: true is a block like any other. Writing @Field({ required: true, create: true }) therefore marks the field editable on create and not required on create. To keep it mandatory, the flag has to be inside the block, as create: { required: true }.

API

Decorators

Metadata readers

Types and tokens

The field types group by what they produce. Text and numbers: text, longText, strings, int, ints, float, currency. Dates: date, dateTime, dateWithEdit, dateRange. Choices and flags: enum, radio, check, flag, color. Contact and identity: email, password, phoneNumber, phoneNumberPl, nip, pesel, address. Files and media: file, pdf, image, logo, video, attachment. Structure: object, array.

Related packages

• @smartsoft001/utils supplies the object service the field decorator calls when a field declares a classType.
• @smartsoft001/domain-core defines IEntity, which the decorated entities implement, and re-exports ISpecification from here.
• @smartsoft001/crud-shell-angular reads the field metadata to build the list and item screens.
• @smartsoft001/crud-shell-app-services casts and validates every record with these functions before it reaches a repository.