@meanie/angular-store

An Angular service for managing model instances

Installation

You can install this package using yarn or npm:

#yarn
yarn add @meanie/angular-store

#npm
npm install @meanie/angular-store --save

Include the script node_modules/@meanie/angular-store/release/angular-store.js in your build process, or add it via a <script> tag to your index.html:

<script src="node_modules/@meanie/angular-store/release/angular-store.js"></script>

Add Store.Service as a dependency for your app.

Usage

Please note that this service is best used in conjunction with the Meanie Angular API service and models derived from $baseModel.

The store service comes with two predefined store classes that you can use, the $collectionStore and the $instanceStore. You can also extend these services and create your own store service for a specific model, or derive one from the $baseStore.

All store methods return promises so they are ideal for chaining and post handling of model instances, and can be used to resolve data in your routes.

Collection store

The collection store is used to manage a collection of models. It requires the following methods present on your model (each returning a promise):

• Model.query(filter).then(items => ...)
• Model.prototype.save(data).then(item => ...)
• Model.prototype.delete().then(item => ...)

Furthermore, it requires that each instance of your data has a unique id property by which the store will track your items.

angular.module('App.MyModule', [
  'Store.Service'
])

//Register a new store
.config(function($storeProvider) {
  $storeProvider.registerStore('users', {
    model: 'User',
    service: '$collectionStore' //default, can be omitted
  });
})

//Use in your app
.controller('MyController', function($store) {

  //Query users
  $store.users.query()
    .then(users => ...);

  //Find a specific user
  $store.users.findByid(1)
    .then(user => ...)

  //Save a user instance
  $store.users.save(user)
    .then(user => ...);

  //Delete a user instance
  $store.users.delete(user)
    .then(user => ...);

  //Create a new user model instance from plain object
  $store.users.save({name: 'Meanie'})
    .then(user => ...)

  //Clear the users from the store
  $store.users.clear();

  //Load a predefined set of users (or plain user data) to the store
  //Converts them to models if plain data objects given
  $store.users.load([{name: 'A'}, {name: 'B'}])
    .then(users => ...);

  //Add instance to the store manually (without saving on server)
  $store.users.add(new User({name: 'C'}))
    .then(user => ...);

  //Remove user instance from the store manually (without deleting from server)
  $store.users.remove(user)
    .then(user => ...);
});

Instance store

The instance store is used to manage a single model, for example the logged in user. It requires the following methods present on your model (each returning a promise):

• Model.get().then(item => ...)
• Model.prototype.save().then(item => ...)

angular.module('App.MyModule', [
  'Store.Service'
])

//Register a new store
.config(function($storeProvider) {
  $storeProvider.registerStore('user', {
    model: 'User',
    service: '$instanceStore'
  });
})

//Use in your app
.controller('MyController', function($store) {

  //Get the user instance
  $store.user.get()
    .then(user => ...);

  //Save the user instance
  $store.user.save(user);

  //Create a new user model instance from plain object
  $store.user.save({name: 'Meanie'})
    .then(user => ...);

  //Set a user instance manually
  $store.user.set(new User({name: 'Meanie'}))
    .then(user => ...);

  //Also works with plain data
  $store.user.set({name: 'Meanie'})
    .then(user => ...);

  //Clear the user
  $store.user.clear()
    .then(user => ...);
});

Custom store

angular.module('UserStore.Service', [
  'Store.Store.Service'
])

//Register a new store
.config(function($storeProvider) {
  $storeProvider.registerStore('users', {
    model: 'User',
    service: 'UserStore'
  });
})

//Factory for store
.factory('UserStore', function($collectionStore) {

  /**
   * Constructor
   */
  function UserStore(name, config) {
    $collectionStore.call(this, name, config);
  }

  /**
   * Extend prototype
   */
  angular.extend(UserStore.prototype, $collectionStore.prototype);

  /**
   * Extend with custom methods as needed
   */
  UserStore.prototype.findByName = function(name) {
    return this.query({
      name: name
    });
  };

  //Return
  return UserStore;
});

Issues & feature requests

Please report any bugs, issues, suggestions and feature requests in the @meanie/angular-store issue tracker.

Contributing

Pull requests are welcome! If you would like to contribute to Meanie, please check out the Meanie contributing guidelines.

Sponsor

This package has been kindly sponsored by Hello Club, an all in one club and membership management solution complete with booking system, automated membership renewals, online payments and integrated access and light control. Check us out if you happen to belong to any kind of club or if you know someone who helps run a club!

License

(MIT License)

Copyright 2016-2020, Adam Reis