README.md

aurelia-orm

Working with endpoints and client-side entities is unavoidable when doing API driven development. You end up writing a small wrapper for your XHRs / websocket events and putting your request methods in one place. Another option is just using Breeze, which is large, complex and not meant for most applications. Even though your endpoints are important, you still end up neglecting them.

Enter aurelia-orm. This module provides you with some useful and cool features, such as:

• Entity definitions
• Repositories
• Associations
• Validation
• Type casting
• Self-populating select element
• And more

This makes it easier to focus on your application and organize your code.

This library is an unofficial plugin for the Aurelia platform. This library plays nice with the Sails.js framework.

Important note

We've simplified installation and usage! This plugin should now be installed using jspm i aurelia-orm or (for webpack) npm i aurelia-orm --save. Make sure you update all references to spoonx/aurelia-orm and spoonx/aurelia-api and remove the spoonx/ prefix (don't forget your config.js, package.json, imports and bundles).

Documentation

You can find usage examples and the documentation at aurelia-orm-doc.

The changelog provides you with information about important changes.

Uses

• aurelia-api
• aurelia-validation@^0.12.3

Used by

• aurelia-datatable.

Installation

Aurelia-orm needs an installation of aurelia-api and aurelia-validation@^0.12.3.

Aurelia-Cli

Start by following the instructions for the dependencies of orm, aurelia-api and aurelia-view-manager. When done, resume with the other steps.

Run npm i aurelia-orm --save from your project root.

It also has submodules and makes use of get-prop. So, add following to the build.bundles.dependencies section of aurelia-project/aurelia.json.

"dependencies": [
  // ...
  "get-prop",
  {
    "name": "aurelia-orm",
    "path": "../node_modules/aurelia-orm/dist/amd",
    "main": "aurelia-orm",
    "resources": [
      "component/view/bootstrap/association-select.html",
      "component/view/bootstrap/paged.html"
    ]
  },
  {
    "name": "aurelia-validation",
    "path": "../node_modules/aurelia-validation/dist/amd",
    "main": "index"
  },
  // ...
],

Jspm

Run jspm i aurelia-orm npm:get-prop

And add following to the bundles.dist.aurelia.includes section of build/bundles.js:

  "get-prop",
  "aurelia-orm",
  "[aurelia-orm/**/*.js]",
  "aurelia-orm/**/*.html!text",

If the installation results in having forks, try resolving them by running:

jspm inspect --forks
jspm resolve --only registry:package-name@version

Webpack

Run npm i aurelia-orm --save from your project root.

Add aurelia-orm in the coreBundles.aurelia section of your webpack.config.js.

Typescript

Npm-based installations pick up the typings automatically. For Jspm-based installations, run typings i github:spoonx/aurelia-orm or add "aurelia-orm": "github:spoonx/aurelia-orm", to your typings.json and run typings i.

Example

Here's a snippet to give you an idea of what this module does.

entity/user.js

import {Entity, validatedResource} from 'aurelia-orm';
import {ValidationRules} from 'aurelia-validation';

@validatedResource('user')
export class UserEntity extends Entity {
  email    = null;
  password = null;

  constructor() {
    super();

    ValidationRules
      .ensure('email').required().email()
      .ensure('password').required().minLength(8).maxLength(20)
      .on(this);  
  }
}

page/some-view-model.js

import {EntityManager} from 'aurelia-orm';
import {inject} from 'aurelia-framework';

@inject(EntityManager)
export class Create {

  requestInFlight = false;

  constructor (entityManager) {
    this.entity = entityManager.getEntity('user');
  }

  create () {
    this.requestInFlight = true;

    this.entity.validate()
      .then(validateResults => {
        if (!validateResults[0].valid) {
          throw validateResults[0];
        }

        return this.entity.save();
      }).then(result => {
        this.requestInFlight = false;

        console.log('User created successfully');
      })
      .catch(error => {
        this.requestInFlight = false;
        // notify of the error?
      });
  }
}

Gotchas

When using this module, please keep in mind the following gotchas.

Bundling

When bundling your aurelia app, the bundler renames your modules (to save space). This is fine, but aurelia-orm allows you to add decorators without values, and uses the module name to set the value. For instance, @resource() would use the module's name to set the resource.

So keep in mind: When using aurelia-orm in a bundled application, you must specify a value for your decorators. For instance, @decorator('category').

Known hacks

• The association-select always parses the placeholderText as html (t="[html]${placeholderText}") due a aurelia-i18n binding issue.