ng-smart-id

Motivation

This library was created for making it easier to take advantage of smart ids when using PouchDB/CouchDB as a database.

In PouchDB/CouchDB it is best practice to use meaningful ids. Meaningful ids allow querying data in a more efficient way without the need of constructing views, that can be slow to build up and to dinamically refresh.

The id schema used in this module is based on the recommendations from CouchDB Best Practices.

Usage

The smartId service provides two functions

parse

smartId.parse('author:asimov:series:foundation:bookNr:1')

will return

{ author: 'asimov', series: 'foundation', bookNr: '1' }

Note that all fields will be returned as Strings.

An optional pattern can be provided for validation purposes (see patterns). If the id is missing any of the non optional fields specified in the pattern, an exception is thrown.

smartId.parse('author:asimov:series:foundation:bookNr:1', 'author:series:bookNr:?publicationYear')

will return

{ author: 'asimov', series: 'foundation', bookNr: '1' }

while

smartId.parse('author:asimov:series:foundation:bookNr:1', 'author:series:bookNr:publicationYear')

will throw an exception

idify

smartId.idify({ author: 'asimov', series: 'foundation', bookNr: 1 }, 'author:series:bookNr')

will return author:asimov:series:foundation:bookNr:1

Fields containing undefined, null or '' will be ignored. Example:

smartId.idify({ author: 'asimov', series: 'foundation', bookNr: undefined }, 'author:series:?bookNr')

will return author:asimov:series:foundation

Config

It is possible to configure the separator for id fields, if no separator is provided : is used by default.

To configure it add a value to your Angular module:

angular.module('myMod', [])
  .value('ngSmartIdSeparator', '-')

You can also provide a set of patterns to be reused through the application:

angular.module('myMod', [])
  .value('ngSmartIdPatterns', {
    'bookSeries': 'author:series:bookNr',
    'singleBook': 'author:book'
  })

Pass a preconfigured pattern id as an argument to parse or idify:

smartId.parse('author:asimov:series:foundation:bookNr:1', 'bookSeries')

Patterns

Patterns allow optional fields, to specify an optional field add ? before the field name:

smartId.parse('author:asimov:series:foundation:bookNr:1:rating:awesome', 'author:series:bookNr:?rating')

will return

{ author: 'asimov', series: 'foundation', bookNr: '1', rating: 'awesome' }

while

smartId.parse('author:asimov:series:foundation:bookNr:1', 'author:series:bookNr:?rating')

will still return

{ author: 'asimov', series: 'foundation', bookNr: '1' }

Installation

Install with bower:

bower install --save fielded/ng-smart-id

or npm:

npm install --save fielded/ng-smart-id

Then simply add ngSmartId as a dependency somewhere in your project that makes sense and you're good to go.

Contributing

Installation

# Clone the GitHub repository
git clone [email protected]:fielded/ng-smart-id.git
# Change into project folder
cd ng-smart-id
# Install the dev dependencies
npm install

Test Suite

The test suite is configured to run with PhantomJS and is powered by:

• Karma
• Jasmine

Running Tests

npm test

Release Process

To make a release, you need to run npm run build, commit the dist folder and tag the commit with an appropiate version according to the SemVer spec.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.