Skip to main content

Quik Framework :: Entity

Handles generic entity definitions and metadata storage. The module loads defaults and exports decorators, base entity classes, and metadata utilities.

Installation​

npm install @quik/entity

Usage​

Define an entity with decorators:

import { Entity, Fields, QEntity } from '@quik/entity';

@Entity('User')
export class User extends QEntity {
  @Fields.String()
  name: string;

  @Fields.Email()
  email: string;
}

Query metadata from the store:

import { EntityStore } from '@quik/entity';

const definition = EntityStore.get('User');

API Highlights​

  • Entity, BaseEntity, PaginatedEntity decorators.
  • Fields decorators for common field types.
  • Validators and Sanitizers helpers.
  • EntityStore access to registered entity metadata.

Flags​

The Flags decorators annotate fields with special behavior. Selectable marks a field that can be used in select lists or lookups and is recorded in the field metadata under flags.

Instances expose a selectableFields getter which returns all fields decorated with this flag. The same list can be retrieved programmatically using getFlaggedField("selectable").

Common flags:

  • Required enforces non-null values at validation time.
  • Optional allows null/undefined values and skips validators when unset.
  • AllowEmpty permits empty strings, empty arrays, and zero values.
  • ReadOnly prevents assignment during fill().
  • Array and Set instruct the entity to treat the field as a collection.
  • Slug and Url validate string formats.
  • Virtual, Getter, and Setter control accessor behavior for computed fields.
  • Selectable marks fields for query selection helpers.

Lifecycle Hooks​

Entities can register lifecycle hooks using the Hooks decorators. These hooks run during fill() operations and are useful for defaulting or derived fields.

Available hooks:

  • Hooks.onBeforeFill runs before values are applied.
  • Hooks.onAfterFill runs after values are applied.

Example:

import { Entity, Fields, Hooks, QEntity } from '@quik/entity';

@Entity('Profile')
class Profile extends QEntity {
  @Fields.String()
  name!: string;

  @Fields.String()
  slug!: string;

  @Hooks.onAfterFill
  deriveSlug() {
    this.slug = this.name.toLowerCase().replace(/\\s+/g, '-');
  }
}

Testing & Coverage​

See the root instructions for details on running pnpm run test:coverage and accessing coverage artifacts.

API Reference​

Generated API documentation is available in the entity API section.