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
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.