@ark7/model - v2.0.56
    Preparing search index...

    @ark7/model - v2.0.56

    @ark7/model

    In many projects, duplicating identical models can lead to numerous bugs. The @ark7/model library addresses this challenge by offering a unified model class layer that operates seamlessly across various environments, ensuring consistent business logic and reducing redundancy.

    API Documentation: https://ark7-technology.github.io/model/

    Supported Platforms:

    Install the package using npm:

    npm install @ark7/model

    Add transform plugin to tsconfig.json:

    // tsconfig.json

    {
      ...
      "plugins": [{
        "transform": "@ark7/model/transformer"
      }],
    }

    Models are defined by decorating the class with A7Model or using A7Model.provide(ModelClass).

    // models/users.ts

    import { A7Model } from '@ark7/model';

    @A7Model({})
    export class Name {

      readonly first: string;

      last: string;
    }

    export enum Gender {
      MALE = 'MALE',
      FEMALE = 'FEMALE',
    }

    @A7Model({})
    export class User {

      email: string;

      name?: Name;

      gender?: Gender;
    }

    // Another way to register User model:
    //
    // A7Model.provide(User)

    Once a model is defined, class metadata, field metadata, and model schema can be retrieved through A7Model.getMetadata(ModelClass). For example:

    @A7Model({})
    class Name {
      first: string;
      last: string;
    }

    A7Model.getMetadata(Name).should.be.deepEqual({
      modelClass: Name.prototype.constructor,
      superClass: null,
      configs: {
        schema: {
          name: 'Name',
          props: [
            {
              modifier: 'PUBLIC',
              name: 'first',
              optional: false,
              readonly: false,
              type: 'string',
            },
            {
              modifier: 'PUBLIC',
              name: 'last',
              optional: false,
              readonly: false,
              type: 'string',
            },
          ],
        },
      },
      fields: {},
      name: 'Name',
    });

    The @A7Model() decorator (and its alias @Config()) accepts a configuration object that controls model-level behavior. These options affect how the model is serialized, indexed, and integrated with adapters.

    Full API reference: StrictConfigOptions

    Options:

    Option Type Description
    schema runtime.Schema The runtime schema (auto-generated by the transformer).
    defaultLevel number Default data level for all fields in this model.
    discriminatorKey string The field used to distinguish subclass types in discrimination.
    toObject DocumentToObjectOptions Default options applied when calling .toObject().
    toJSON DocumentToObjectOptions Default options applied when calling .toJSON().
    indexes Array<{ fields, options? }> Compound indexes defined via @CompoundIndex().
    mixinClasses ModelClass[] Classes mixed into this model via @Mixin().
    protoNestedIn string The parent proto message name for Protocol Buffer nesting.
    protoMessageName string Override the Protocol Buffer message name.

    Default Data Level:

    Set a default level for all fields, so you don't need to decorate every field individually:

    @A7Model({ defaultLevel: DefaultDataLevel.SHORT })
    class UserProfile extends StrictModel {
      displayName: string;  // inherits SHORT level
      bio: string;          // inherits SHORT level

      @Confidential()
      ssn: string;          // overridden to CONFIDENTIAL
    }

    Default toObject / toJSON Options:

    Configure default serialization behavior at the model level:

    @A7Model({
      toObject: {
        virtuals: true,
        getters: true,
      },
      toJSON: {
        virtuals: true,
      },
    })
    class User extends Model {
      firstName: string;
      lastName: string;

      get fullName(): string {
        return `${this.firstName} ${this.lastName}`;
      }
    }

    Custom Configuration:

    The configuration object is extensible — you can pass custom key-value pairs and retrieve them via metadata:

    interface MyConfig {
      endpoint: string;
      cacheTTL: number;
    }

    @A7Model<MyConfig>({ endpoint: '/api/users', cacheTTL: 300 })
    class User extends Model {
      name: string;
    }

    const configs = A7Model.getMetadata(User).configs as MyConfig;
    configs.endpoint  // '/api/users'
    configs.cacheTTL  // 300

    Model-level configuration can be injected using either @A7Model() or @Config():

    @A7Model<ModelConfig>({ foo: 'bar' })
    class MCModel { }

    interface ModelConfig {
      foo: string;
    }

    (A7Model.getMetadata(MCModel).configs as ModelConfig).foo.should.be.equal(
      'bar'
    );

    @A7Model({
      discriminatorKey: 'kind',
    })
    class Event extends StrictModel {
      kind?: string;
    }

    @A7Model({})
    class MouseEvent extends Event {
      foo: string;
    }

    const ins = EventModel.modelize({
      kind: 'MouseEvent',
      foo: 'bar',
    } as any);

    ins.should.be.instanceof(MouseEvent);

    const ins2 = MouseEvent.modelize({
      foo: 'bar',
    });

    ins2.should.be.instanceof(MouseEvent);

    ins2.toObject().should.be.deepEqual({
      kind: 'MouseEvent',
      foo: 'bar',
    });

    A model can mix in other models.

    @A7Model({})
    class M1 {
      foo: string;
    }

    @A7Model({})
    class M2 {
      bar: string;
    }

    @A7Model({})
    @Mixin(M1)
    @Mixin(M2)
    class CombinedModel extends Model {}

    interface CombinedModel extends M1, M2 {}

    The required modifier can be declared at the field metadata or schema level:

    class Name {
      first: string;  // schema level required

      @Required()     // field metadata level required
      last: string;   // schema level required
    }

    Sometimes, the two levels may have conflicting opinions:

    class Name {
      first?: string;  // schema level optional

      @Required(false) // field metadata level: optional
      last: string;    // schema level: required
    }

    It depends on the adapter to resolve these conflicts.

    The readonly modifier can be declared at the field metadata or schema level:

    class Name {
      readonly first: string;  // schema level readonly

      @Readonly()     // field metadata level readonly
      last: string;   // schema level non-readonly
    }

    It depends on the adapter to resolve these conflicts.

    The @Autogen() decorator marks a field as both readonly and auto-generated. This is useful for fields that are automatically populated by the system (e.g., timestamps, computed values).

    @A7Model({})
    class Record extends Model {
      @Autogen()
      createdAt: Date;
    }

    The default value can be set at the field metadata level:

    class Name {
      @Default('foo')
      first: string;

      @Default(() => 'bar')
      last: string;
    }

    import { A7Model, StrictModel } from '@ark7/model';

    @A7Model({})
    class Name extends StrictModel {
      first: string;
      last: string;
    }

    @A7Model({})
    export class User extends StrictModel {
      email: string;
      name?: Name;
    }

    const user = User.modelize({
      email: 'test@google.com',
      name: {
        first: 'foo',
        last: 'bar',
      }
    });

    user.should.be.instanceof(User);
    user.name.should.be.instanceof(Name);

    import { A7Model, StrictModel } from '@ark7/model';

    @A7Model({})
    class Name extends StrictModel {
      first: string;
      last: string;
    }

    @A7Model({})
    export class User extends StrictModel {
      email: string;
      name?: Name;
    }

    const user = User.modelize({
      email: 'test@google.com',
      name: {
        first: 'foo',
        last: 'bar',
      }
    });

    user.toObject().should.be.deepEqual({
      email: 'test@google.com',
      name: {
        first: 'foo',
        last: 'bar',
      }
    });

    Each field is assigned a level number. The higher the level number, the more restricted or confidential the field is. We have predefined five data levels:

    1. BASIC (10) - The basic field that will be used in the most scenarios.
                Usually, presented when it's referenced by other model.

2. SHORT (20) - The fields that are useful for displaying as a list or
                table. Usually, presented in the find or search endpoints.

3. DETAIL (30) - The fields that contains detail information. Usually,
                 presented in the get endpoints.

4. CONFIDENTIAL (40) - The fields that contains sensitive information.
                       Usually, not returning to the client or only to
                       admins with special privileges.

5. NEVER (1000) - The fields that are never returns.

    Projection:

    We can do the projection by providing a filter level. Any fields with level numbers that are smaller or equal to the filter level will be projected. You can tune the filter level by specifying the passLevelMap in the option.

    @A7Model({})
    class Name extends StrictModel {
      @Basic() first: string;
      @Basic() last: string;
    }

    @A7Model({})
    export class User extends StrictModel {
      @Basic() email: string;
      @Short() name?: Name;
    }

    const user = User.modelize({
      email: 'test@google.com',
      name: {
        first: 'foo',
        last: 'bar',
      }
    });

    user.toObject({ level: DefaultDataLevel.BASIC }).should.be.deepEqual({
      email: 'test@google.com',
    });

    user.toObject({ level: DefaultDataLevel.SHORT }).should.be.deepEqual({
      email: 'test@google.com',
      name: {
        first: 'foo',
        last: 'bar',
      },
    });

    Population:

    For a reference field, when the filter level is greater than the populateLevel specified by the option, the field will be populated.

    @A7Model({})
    export class User extends Model {
      @Virtual({ ... })
      @Level({ populateLevel: DefaultDataLevel.DETAIL })
      posts: Post[];
    }

    @A7Model({})
    export class Post extends Model {
      author: Ref<User>;
    }

    The @Reference() decorator marks a field as a reference to another model. The Ref<T> type represents a field that can hold either an ID or a populated model instance.

    import { A7Model, Model, Ref, Reference, asModel, idOf, isSameModel } from '@ark7/model';

    @A7Model({})
    class Author extends Model {
      name: string;
    }

    @A7Model({})
    class Book extends Model {
      title: string;

      @Reference()
      author: Ref<Author>;
    }

    Utility functions for working with references:

    • asModel(ref) (alias $$) - Casts a Ref<T> to T.
    • idOf(ref) - Extracts the ID from a reference.
    • isModel(ref) - Checks if the reference is a populated model.
    • isSameModel(ref1, ref2) - Compares two references by their IDs.

    The @Virtual() decorator defines a virtual field that is populated from another model via a local/foreign field relationship, similar to Mongoose virtuals.

    @A7Model({})
    class Author extends Model {
      name: string;

      @Virtual({
        ref: 'Book',
        localField: '_id',
        foreignField: 'author',
      })
      books: Book[];
    }

    @A7Model({})
    class Book extends Model {
      title: string;

      @Reference()
      author: Ref<Author>;
    }

    Options:

    • ref - The referenced model name or class.
    • localField - The field on the current model to match against.
    • foreignField - The field on the referenced model to match.
    • justOne - If true, populates a single document instead of an array.
    • count - If true, returns only the count of matching documents.
    • match - Additional query conditions for filtering.

    The @Index(), @Unique(), and @CompoundIndex() decorators configure database indexes.

    @A7Model({})
    @CompoundIndex({ email: 1, name: 1 })
    class User extends Model {
      @Unique()
      email: string;

      @Index()
      name: string;

      @Index({ sparse: true })
      nickname?: string;
    }
    • @Index(options?) - Creates an index on the field. Options: unique, sparse, indexDisabled.
    • @Unique(options?) - Shorthand for a unique index. Options: sparse.
    • @CompoundIndex(fields, options?) - Class-level decorator for compound indexes.

    The @Encrypted() decorator marks a field for encryption at the database level.

    @A7Model({})
    class User extends Model {
      @Encrypted()
      ssn: string;

      @Encrypted({ algorithm: EncryptAlgorithm.AEAD_AES_256_CBC_HMAC_SHA_512_RANDOM })
      secretNotes: string;
    }

    Options:

    • algorithm - Encryption algorithm (default: AEAD_AES_256_CBC_HMAC_SHA_512_DETERMINISTIC).
    • keyAltName - The data key alias name (default: 'defaultDataKey').
    • autoDecrypt - Whether to auto-decrypt the field (default: false).

    The @Tag() decorator adds tags to a field for categorization or filtering.

    @A7Model({})
    class Settings extends Model {
      @Tag('ConfigField')
      theme: string;

      @Tag(['ConfigField', 'UserPref'])
      language: string;
    }

    The @NoPersist() decorator marks a field as in-memory only. The field will not be persisted to the database.

    @A7Model({})
    class Session extends Model {
      userId: string;

      @NoPersist()
      cachedProfile: object;
    }

    The @Present() decorator controls whether a field is present based on a static value or a condition evaluated against the model instance.

    @A7Model({})
    class Feature extends Model {
      @Present()
      enabledField: string;

      @Present(() => process.env.NODE_ENV === 'development')
      debugField: string;
    }

    The @Important() decorator prevents a field from being overridden by the natural field resolution order (Child Class > Mixin Class > Parent Class).

    @A7Model({})
    class Base extends Model {
      @Important()
      @Detail()
      role: string;
    }

    The @MMap() decorator and MMap<T> type provide Map support for model fields.

    import { A7Model, Model, MMap } from '@ark7/model';

    @A7Model({})
    class Config extends Model {
      @MMap(String)
      settings: MMap<string>;
    }

    The @IDType() decorator configures ID handling for nested fields.

    @A7Model({})
    class Record extends Model {
      @IDType({ forceIdToString: true })
      nested: SubRecord;
    }

    The @Editable() decorator attaches UI-oriented metadata to a field, useful for auto-generating forms and display components.

    @A7Model({})
    class User extends Model {
      @Editable({
        inputType: 'text',
        hint: 'Enter your full name',
      })
      name: string;

      @Editable({
        inputType: 'email',
        hideDisplay: true,
      })
      email: string;

      @Editable({
        type: 'select',
        options: [
          { label: 'Admin', value: 'admin' },
          { label: 'User', value: 'user' },
        ],
      })
      role: string;
    }

    Options include: type, inputType, options, hint, info, disabled, hideDisplay, hideEditing, hide, reference, displayWidth, editWidth, listItemRemovable, copyText, autoHide.

    The @Proto() decorator configures Protocol Buffer field options.

    @A7Model({})
    class Message extends Model {
      @Proto({ protoAssignedId: 1 })
      title: string;

      @Proto({ protoAssignedId: 2, protoFieldType: 'int32' })
      count: number;
    }

    Options:

    • protoAssignedId - The Protocol Buffer field number.
    • protoFieldType - Override the proto field type ('none', 'int32', 'int64', 'string', 'float', 'double').

    Sometimes, it's necessary to attach metadata to an instance.

    import { A7Model, StrictModel } from '@ark7/model';

    @A7Model({})
    class Name extends StrictModel {
      first: string;
      last: string;
    }

    const name = Name.modelize({ first: 'foo', last: 'bar'});

    name.$attach({ hello: 'world' });

    name.$attach().should.be.deepEqual({
      __$attach: true,
      hello: 'world',
    });

    // This won't affect toObject() or toJSON():
    name.toObject().should.be.deepEqual({
      first: 'foo',
      last: 'bar',
    });

    Email address type.

    UUID string type. Used for UUID fields that should be stored as strings.

    Social Security Number type.

    Phone number type.

    Date type with custom modelize handler that automatically converts values to Date instances via new Date(val).

    Base ID interface used for model identifiers (e.g., _id fields).

    Settings

    Member Visibility

    On This Page

    @ark7/model