simple-mapper
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.0 • Public • Published

    npm version Build Status dependencies Status devDependencies Status codecov Greenkeeper badge

    SimpleMapper

    SimpleMapper provides simple, object-to-object mapping by convention. It was created to solve the problem of recursively mapping JSON to models, in order to gain the benefits of those models, particularly their methods and default values. However, it can be used to map from Javascript objects of any type, to objects of any type.

    Usage

    let myClassVm = mapper.map(MyClass, { /* JSON object */ }, true);
    let myClassVmArray = mapper.mapArray(MyClass, [{ /* JSON object array */ }], false);

    The optional third argument turns on (default) or off warnings about missing destination properties.

    Models

    Due to the way Typescript works (as of v2.2), you should define your models so they always have default values. Otherwise, their properties will not be visible to the mapper.

    Be sure the default values for iterables are empty iterables (both in the source and destination), otherwise the properties will be mapped like ordinary properties.

    export class MyWidget {
        Id: number; /* not visible to the mapper. */
        Name: string = null; /* visible due to null default. */
        get Display(): string { 
            return `${Name} (Id: ${Id})`;
        }
     
        @mappable("MyWidget")
        Wiggy: MyWidget = null;
     
        @mappable(MyWidget)
        WigArray: MyWidget[] = [];
    }

    If providing model names as strings instead of references, then you must provide a model collection during import (see Setup).

    If a source property exists while a destination does not, a warning will be issued by default. You can turn this off by providing a third parameter:

    let json = {
        Id: 314,
        Name: "Chris",
        ExtraProp: "Missing in the destination model, MyWidget."
    };
    mapper.map(MyWidget, json, false);

    Installation

    npm install --save-dev simple-mapper

    Setup

    // if you are using dependency injection, your setup might look like this:
     
    import { MapperService, IMapperService, IConfig } from 'simple-mapper';
    import * as models from './models/barrel/';
     
    export let MapperServiceToken = new Symbol("MapperService");
     
    diContainer.bind<IMapperService>(MapperServiceToken).to(MapperService);
     
    // or with configuration...
     
    let config = <IConfig> {
        models: models,
        unmappedWarnings: true,
        validateOnStartup: true
    };
    diContainer.bind<IMapperService>(MapperServiceToken).to(() => new MapperService(config, console));

    Options

    let config: IConfig = {
        /** The dictionary of models to use for recursive mapping. 
          * Not needed if using object references in @mappable() instead of names.
          * Default: empty. */
        models: {},
     
        /** Validate models provided on instantiation (makes sure mappable names exist in your models collection).
         * Default: false.
         */
        validateOnStartup: false,
     
        /** Turn off unmapped source property warnings globally. Can be overridden at the method level. */
        unmappedWarnings: false
    }

    Build

    Run npm run build to build the project. The build artifacts will be stored in the dist/ directory.

    Running unit tests

    Run npm test to execute the unit tests. Run npm run cover to run tests and generate a code coverage report. Code coverage will be available at ./coverage/index.html.

    Documentation

    The scaffolding exists, but no real documentation, for the moment. Run 'npm run compodoc' to generate documentation. Then run 'npm run compodoc-serve' to see auto-generated documentation and documentation coverage on port 8080.

    Further help

    Feel free to post issues.

    Keywords

    none

    Install

    npm i simple-mapper

    DownloadsWeekly Downloads

    3

    Version

    2.2.0

    License

    MIT

    Unpacked Size

    37.6 kB

    Total Files

    21

    Last publish

    Collaborators

    • cdibbs