@urbane/aorm v1.0.1
aORM 
by David Urbane
aORM (agnostic Object-relational Mapping) inspired by the Mongoose workflow. I wanted an easy to use ORM that was compatible with DynamoDB with support for permissions and other advanced features.
- Comaptible with nearly any database or REST API.
- Out of the box support for filters and complex permissions on read and write actions.
- Easy schema creation with sub-document support.
- First class support for ES6+ classes.
Contents
Getting Started
Installation
Installation is easiet using npm, although there are other methods such as manually downloading.
DynamoDB
npm i --save @urbane/aorm-dynamodbBase Package (Custom Adapter)
npm i --save @urbane/aormDid you know?
NPM is pretty cool package manager, one of the best on the market, but you should check out Yarn as well. Yarn is doing some cool things with caching and parallel installs. It proxies the NPM registry, so you will still get all your packages without any trouble.
yarn add @urbane/aormUsage
import Model from '@urbane/aorm-dynamodb'
class MyModel extends Model {
static table = 'myTableName';
static schema = {
name: String,
//default and type can be arrays or objects
someField: {
_type: [{value:'some value',test: {_type:Boolean, default:true}}],
default: [{value:'one'}],
//Permissions are strings that are RegEx matched. '{name}' references
//modelInstance.name. This allows for dynamic permissions.
permission: 'my:{name}:field'
},
created: {_type: Date, default: Date.now}
}
someMethodOfMine(name){
this.name = name
}
}
...
let model = new MyModel({name:'My Name'})
//just set the attribute you want to modify
model.name = 'New Name'
//This will apply an object and run through permissions.
model.applyUpdate({name:'A name', someField:[]}, ['no:permission:here'])
//name doesn't have permissions on the field, so it will permit the update
model.name === 'A name'
//someField has a permission on it, so it will not update since 'no:permission:here'
// does not satisfy 'my:New Name:field', but 'my:*', 'my:*:field', '*:*:field', 'my:New Name:*' would
model.someField[0].value === 'one'
model.toJSON() == {name: 'A name', someField: [{value:'one'}], created: '2017-05-04T19:07:31.413Z'}
//filter out fields and/or add permissions
model.toJSON(['created'],['no:permission:here']) == {name:'A name'}
model.save().then(model=>...)
MyModel.get({name:'A name'}).then(resultOrNull=>...)Custom Adapter
Just implement the required methods to create a new adapter.
import Model from '@urbane/aorm'
Model.adapter = {
/**
*
* @param {string} table - Name of the table
* @param {number|string|{}} key - Key to get
* @return {Promise.<{}>}
*/
get(table, key){
return new Promise(...)
},
/**
*
* @param {string} table - Name of the table
* @param {number|string|{}|null} key - Key to update, optional if using condition
* @param {{}} data - The data to update.
* @param {{}} [condition] - The condition for the update to occur.
* @return {Promise.<{}>}
*/
update(table, key, data, condition){
return new Promise(...)
},
/**
*
* @param {string} table - Name of the table
* @param {{}} data - The data to update.
* @param {{}} [condition] - The condition for the insert to occur.
* @return {Promise.<{}>}
*/
insert(table, data, condition){
return new Promise(...)
},
/**
*
* @param {string} table - Name of the table
* @param {number|string|{}|null} key - Key to delete, optional if using condition
* @param {{}} [condition] - The condition for the delete to occur.
* @return {Promise.<boolean>}
*/
delete(table, key, condition){
return new Promise(...)
},
/**
*
* @param {string} table - Name of the table
* @param {{}} filter
* @param {number} [limit]
* @param {number} [offset]
* @return {Promise.<[{}]>}
*/
query(table, filter, limit, offset){
return new Promise(...)
},
/**
*
* @param {string} table - Name of the table
* @param {{}} filter
* @param {Function} walkFunction
* @return {Promise.<[{}]>}
*/
map(table, filter, walkFunction){
return new Promise(...)
}
}License
Apache 2.0 (view) - TL; DR: Use and modify as you want, however you are required to distribute notices of changes and there are patent restrictions. It is not "copyleft" like GPL, so you may feel safe using in proprietary applications. Note some @urbane projects are released under GPL, so double check before using libraries in your proprietary software. As long as those projects don't rely on other's GPL code, you may contact me if you need a different license.
Contributions
Feel free to create issues or pull requests. 1. Hit the Fork button on https://github.com/urbane/aorm (you'll need to sign in to GitHub). Note that this adds a copy of this repo to your account, which will be public. 2. Clone the repository from YOUR fork in your terminal/command line (you'll need Git installed, instructions here).
git clone https://github.com/YOUR_USERNAME/aorm- Install Dependices (you'll need Node.js installed, download here).
cd aorm && npm install- Add UPSTREAM to your repo, this will allow you to pull in the latest changes from the main repo.
git remote add upstream https://github.com/urbane/aorm.git
git fetch upstream
git checkout master- Make changes to make this project AWESOME!
- Update to make sure you are working with the latest version. This will update your repository to the latest in the main repo without overwriting your edits.
git merge upstream/master- Test your changes, make sure that all tests pass. If tests don't pass, you're changes won't be accepted into the next version. If you added a feature, you should also add a test. Unit testing is very important when multiple parties are working on the code, so other people don't break your code accidentally and vice-versa. This allows people to add features without having to understand all the code in the project.
npm test- Prepare for commit. Run the lint script to "lint" (check & clean code style) to make sure your awesome code is using the same standards as the project and doesn't contain obvious errors like undefined variables.
npm run lint- Commit to your fork.
git add .
git commit -m 'WHAT DID YOU CHANGE, THIS IS YOUR COMMIT MESSAGE'
git push origin master- Go to https://github.com/YOUR_USERNAME/aorm and click "Pull Request" and follow the directions on screen. You will need to make a comment on why your code should be added to the main project.
- Your pull request will be reviewed by a core contributer of the project. You may be asked to make changes to your code, so just repeat steps 4-8 as your commit will automatically update the pull request (PR). Afterwards your PR will be either accepted or rejected.
Other Projects by David Urbane (@urbane)
Unlike many other projects, I strive for continued maintainance of all packages with fixing bugs and updating dependencies. Projects are tested against latest dependecies and updated as needed, although all projects are AS IS and subject to the included license. If you want enchanced support or to license code differently, contact me at david@davidurbane.com or learn more at davidurbane.com.
- serverless-http-helper - Wrapper for providing Express.js style HTTP handlers for Lambda/Serverless architecture with minimal size and middleware support.
- config-manager - Handles the reading and writing of various config file types, such as YAML, JSON, INI, etc. with a unified API.
Twitter: @DavidUrbane
Facebook: David.Urbane
GitHub: @urbane
Website: davidurbane.com
So what's with @urbane in front of the packages?
Because I'm so vain (just ask Carly) and so I can brand in order to promote a certain level of quality and consistency across projects. I contribute to many other projects, I just want to make sure the ones I own are held to the highest standard. This also alleviates any issues with conflicting projects. If you want to adopt this project and pull it into the broader community, contact me and we maybe able to work it out and save it from possible deprecation.
:us: Coded proudly near beautiful Salt Lake City, Utah in the USA, however contributions are welcome from anywhere in the universe (except Pluto).