Skip to content

Latest commit

 

History

History
142 lines (99 loc) · 4.52 KB

README.md

File metadata and controls

142 lines (99 loc) · 4.52 KB
Raw

Urly

Easily convert the format of your URLs.

var Urly = require('urly');
var urly = new Urly();

// Register a mapping
urly.register('/users.html?userId', '/users/:userId');
urly.register('/photos/:photoId', '/photos.html?photoId=:photoId');

// Map your urls!
urly.map('/users.html?userId=123');     // returns `/users/123`
urly.map('/users.html?userId=456');     // returns `/users/456`
urly.map('/users.html');                // returns `false`, missing `userId` query string parameter
urly.map('/photos/789');                // returns `/photos.html?photoId=789`
urly.map('/photos');                    // returns `false`, missing `photoId` param

Installation

$ npm install --save urly

Features

  • Can match URLs by pattern, e.g. /users/:userId.
  • Can require specific query string parameters to be considered a match, e.g. /foo?a&b&c.
  • Can accept a callback for complex URL transformations.

Advanced Usage

Callback Functions

You may provide a callback function to handle mapping the URL. When matched, the callback function will be invoked with a request object that contains params and query objects.

Whatever is returned by the callback function will be the mapped URL.

urly.register('/users/:userId/photos/:photoId?page&perPage', function(request) {
    var query = {
        user: request.params.userId,
        photo: request.params.photoId,
        page: request.query.page,
        perPage: request.query.perPage
    };
    return '/photo_gallery.html?' + querystring.stringify(query);
});

urly.map('/users/123/photos/456?page=3&perPage=10');
// returns `/photo_gallery.html?user=123&photo=456&page=3&perPage=10

Extra Params

In some cases you'll need to provide extra parameters to help create the target url. Simply pass in an object with the extra params to help map the URL:

// Pattern to pattern conversion
urly.register('/photos/:photoId', '/users/:userId/photos/:photoId');
urly.map('/photos/123', {
    userId: 456
}); // returns /users/456/photos/123

// Pattern to callback conversion
urly.register('/photos/:photoId', function(request) {
    request.params.userId; // 456
    return '/users/' + request.params.userId + '/photos/' + request.params.photoId;
});
urly.map('/photos/123', {
    userId: 456
}); // returns /users/456/photos/123

Files and Directory Structure

The following describes the various files in this repo and the directory structure.

Note: Files and directories prefixed by * are auto-generated and excluded from the repository via .gitignore.

.
├── Gruntfile.js            # grunt task configuration
├── README.md               # this file
├── *docs                   # autogenerated documentation
│   └── *index.html         # each JS file in `./lib` has a corresponding HTML file for documentation
├── lib                     # all code for this library will be placed here
│   └── index.js            # main entry point for your npm package
├── *node_modules           # all dependencies will be installed here by npm
├── package.json            # description of this package for npm, including dependency lists
└── test                    # unit test configuration, reports, and specs
    ├── *coverage.html      # code coverage report
    ├── lib                 # specs go here, preferably with a 1:1 mapping to code in `./lib`
    │   └── index_test.js   # example spec for `./lib/index.js`
    ├── mocha.opts          # runtime options for mocha
    └── test_runner.js      # configures mocha environment (e.g. chai, sinon, etc.)

What's Included?

Grunt

Grunt is a JavaScript task runner to automate common actions. The Tagged NPM Package Seed supports the following built-in grunt tasks:

test

Runs all unit tests through mocha.

$ grunt test

coverage

Runs all unit tests and generates a code coverage report in ./test/coverage.html

$ grunt coverage

watch

Automatically runs mocha tests each time a file changes in ./lib or ./test.

$ grunt watch

docs

Generates documentation for all JS files within ./lib using docco. Documentation is written to ./docs.

$ grunt docs

clean

Deletes all auto-generated files, including ./docs and ./test/coverage.html

Mocha, Sinon, Chai, Blanket

The ultimate TDD environment for node. Place your specs in ./test/lib, and run grunt test.

See ./test/lib/index_test.js for examples.