Validation system for MAGE topics and user command input types (TypeScript).
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Validation system for MAGE topics and user command input types (TypeScript).


npm install --save mage-validator class-validator class-transformer reflect-metadata

You need to install two peer dependencies alongside mage-validator:

  1. class-validator so that you may add validation decorators to your data class
  2. class-transformer to control how the received data will be deserialised
  3. relfect-metadata will be needed by the two modules above to extract type information

You will also need to make sure that the following configuration is set in your tsconfig.json:

  "experimentalDecorators": true,
  "emitDecoratorMetadata": true


mage-validator exports all functions exposed by class-validator and class-transformer for convenience. A few changes and additions have however been made for convenience.

@Type decorator

// Both are equivalent
@Type(() => Hello)

The @Type decorator has been customized to accept either a type or a function (instead of only a function).

@MapOf decorator

function validateFunc(key: string, value: Child) {
  throw new Error('never valid')

class Child { @IsPositive() public id: number }

class DynamicMap { [key: string]: Child }

class TestTopic extends ValidatedTopic {
  // [...]

  // Use a Map class
  @Type(DynamicMap) public map: DynamicMap

  // Use an anonymous object as a map
  @MapOf(Child) public anonymousMap: { [key: string]: Child }

  @MapOf(Child, validateFunc) public anotherMap: { [key: string]: Child }

mage-validator also provides an additional @MapOf decorator for dealing with key-value map objects; using this type will both ensure nested maps entries will be typed and that each entries will be validated (so @ValidateNested is not required).

(Optional) Project structure

In normal MAGE projects, you need to put all your topics configuration under ./lib/archivist/index.ts. However, this quickly becomes hard to manage as the number of topics grows.

Instead, we recommend using the following file structure:


In other words, we recommend to separate MAGE topics and attach them to their related modules under the topics folder; we also recommend to put other types (example: user command custom parameter type) under a types folder.

To make it easier for you to set this up, mage-validator comes with a method you can simply drop into ./lib/archivist/index.ts; it will scan each one of your modules and attempt to load all topics defined in them.


import { loadTopicsFromModules } from 'mage-validator'


User command parameters and return data validation

Validation works by encapsulating messages into types:


import { IsInt, Max } from 'mage-validator';

export default class {
    public count: gems = 1 // Default value

Which then can be used as user commands types:


import * as mage from 'mage'
import { Type, IsInt, Max, ValidateNested, Acl } from 'mage-validator'
import PlayerData from '../types/PlayerData'

export default class {
    public gemRegisterBonus: number

    @Type(() => PlayerData)
    public data: PlayerData

    public static async execute(state: mage.core.IState, data: PlayerData, gemRegisterBonus: number) {
        data.gems += gemRegisterBonus
        return data

In this case, both data and gemRegisterBonus will be validated prior to execution, and data will be validated once again once it is returned.


Topic definition

Topics work the same way as types, except that they contain the topic configuration as static parameters:


import { ValidatedTopic, ValidateNested, IsUUID, IsAlpha } from 'mage-validator';
import { Type } from 'class-transform';
import PlayerData from '../topics/PlayerData'

class Index {
  playerId: string

export default class {
    // Index configuration
    public static readonly index = ['playerId']
    public static readonly indexType = Index

    // Vaults configuration (optional)
    public static readonly vaults = {}
    // Attribute instances
    public name: string

    @Type(() => PlayerData)
    public data: PlayerData

If you wish to use tome instead, you can you can extend the ValidatedTomeTopic class instead. Unlike normal tomes, you will simply access and set object values directly (instead of using assign, set, valueOf and so on).

Loading topics


import * as mage from 'mage'
import { Acl } from 'mage-validator'
import Player from '../topics/Player'

export default class {
    public id: string

    public static async execute(state: mage.core.IState, id: string) {
        return await Player.get(state, { playerId: id })

Storing topics

Topic instances also work as state wrappers:


import * as mage from 'mage'
import { Acl } from 'mage-validator'
import PlayerData from '../types/PlayerData'
import Player from '../topics/Player'

export default class {
    public static async execute(state: mage.core.IState, name: string) {
        const player: Player = Player.create(state, { playerId: '123' }) = name = new PlayerData() = 5

        return player.add() // Same a state.archivist.add()

In this particular case, you could even simply put the player topic directly as you user command parameter; all you will then need to do is to set the index at some point before you attempt to record any operations:

Topics as user command parameters


import * as mage from 'mage'
import { ValidateNested, Type, Acl } from 'mage-validator'
import Player from '../topics/Player'

export default class {
    @Type(() => Player)
    public player: Player

    public static async execute(state: mage.core.IState, player: Player) {
        return player