Skima NPM | npm.io

Skima

ES6 Module for use with AngularJS. Adds helpers for creating schemas, models and basic validation.

Getting Started

You will first need to make sure you have jspm installed. You can do so with the following command.

$ npm install jspm -g

Once you have jspm installed you are now ready to initialize your application for use with jspm. Run the following to initialize jspm.

$ jspm init

For help with settings and configuring jspm please visit the jspm website

Now that you have initialized your application for jspm you are now ready to install Skima

$ jspm install github:origin1tech/skima

This will install the module in your jspm_packages folder. You'll notice an entry in your package.json file as well as your config.js file. You may have named the config.js file differently. Many choose to save it as jspm.config.js.

Jspm does a great job of mapping to your modules making it far easier to import into your project. It is good to note that if you're not able to import a module you just installed, check your config.js file. The property key for the module in the object will be the name you'll want to import.

Using Skima

Now for the fun stuff. The best thing to do is to define your schemas in separate files and then import them into your application early on in the import chain. Schemas are nothing more than structured objects. They are very easy to define. Consider the following workflow:

    // filename: schemas.js

    // import validation helpers.
    import vals from './validators';
    
    // create our schema using required,
    // various data types and min.
    var userSchema = {
        name: { type: String, required: true },
        email: { type: String },
        age: { type: Number, min: 16 },
        dob: { type: Date }
    };
    
    // in the below example we provide a
    // custom validator that validates 
    // the message property.
    var todoSchema = {
        title: { type: String, required: true, 'default': 'My Todo' },
        message: { type: String, validate: vals.todoMessage },
        user: { type: String } // we'll store the user id here.
    }

    // we'll now export our schemas.
    export default {
        userSchema: userSchema,
        todoSchema: todoSchema
    }

Now that we have some schemas created we need to now define them as part of the $skima module. You'll likely want to do this in the "run" block of your primary module. We'll import the above schemas then pass them to the $skima.define method which will wire up the api to the Model.

    // filename: app.js
    
    // import our primary dependencies.
    import angular from 'angular';
    import uiRouter from 'angular-ui-router';
    import skima from 'origin1tech/skima';

    // import our schemas we created.
    import schemas from './schemas';

    // create an app module inject dependency.    
    var app = angular.module('app', ['ui.router', 'skima']);

    // configure the $skimaProvider
    app.config(function ($skimaProvider) {
        $skimaProvider.set({
            capitalize: true    // turns user into User for Model name.
            prefix: '_',        // prefixes Model names user becomes _User.
            globalization: true // adds Model name to window as global.

            // see source (index.js) for additional options.
        });
    });
    app.config.$inject = ['$skimaProvider']

    // build up our skima repository/models
    app.run(function($skima) {

        // most times your Schema options will be
        // the same for all models define the options
        // passing them in as the second param.
        // see "schema.js" for additional options.
        var opts = {
            force: false, // setting to false allows non 
                          // defined properties.
            // NOTE: you can also define
            // lifecycle functions directly in schema.
            beforeCreate: function (value, next) {
                // lifecycle methods contain model context
                // for example if the schema has a property
                // named "firstName" you could access it
                // from this.
                this.fullName = `${this.firstName} ${this.lastName}`;
            }
        };

        // actions are the methods you will call 
        // when working with your defined Models.
        // by default the following methods are
        // automatically generated:
        // find, findOne, create, update, destroy & save.
        // supplying actions options allows you to override
        // the defaults or define new actions. see "index.js"
        // for detailed comments. The short version is you
        // define the method, routeParams and if a "post" method
        // you must also define whether it should be a 
        // create, update or destroy by decorating "isCreate"
        // for example.
        var actions = {
            // the method below if the model name is "user"
            // would be called as User.custom(params, data);
            custom: { method: 'POST', routerParams: [':key'], isUpdate: true }  
        }
        
        angular.forEach(schemas, function (v,k) {
            // create the schema.
            let schema = new Schema(v, opts);
            // define the skima with the repository.
            $skima.define(k, schema, actions);
        });

        // That's it you can now access your models
        // effortlessly through out your app.
        // ex: Model.find({/* filter params */})
        //          .then(function(res) {
        //              // the response is a Model instance.
        //              var fullName = Model.fullName;
        //          })

       
    });
    app.run.$inject = ['$skima'];

    export default app;

Injecting Skima

Although you can access you Model instances globally from the $window object this may feel dirty. If that's the case simply inject $skima as a dependency into your controller or factory and you'll have access to the entire repository.

    
    // filename: controller.js
    
    import app from './app';

    app.controller('MyCtrl', ['$skima', function ($skima) {
        
        // access User Model.
        var User = $skima.models.User;

        // at this point you have access to 
        // non instance methods such as 
        // find, findOne, create, update & destroy.
        
        User.find({id: 'some_id'}).then(function(res) {
            // this will be a new instance of Model
            var user = res;     
        })

        // create a new Model.
        var user = new Model({
            // model properties here.    
        });
        
        // now that the model is an 
        // instance you can directly
        // save and destroy without
        // providing any params or 
        // model data.
        
        user.save();

    }]);