extract-params

Extract Params

Installation

npm install extract-params --save

Then, in your app:

var extractParams = require('extract-params').extractParams;
// or
var extractParamsInFirstMatch = require('extract-params').extractParamsInFirstMatch;

API

• extractParams(str, pattern, transform)
• extractParamsInFirstMatch(str, patterns)

extractParams(str, pattern, transform)

Tests whether str matches the given parameterized pattern, and returns a key-value object of parameters and their values in case of a successful match.

An optional transform function can be passed to manipulate the extracted params. If transform returns null, the match fails. transform can be used, for example, to lowercase the values in params, or to validate them (return null if validation fails).

pattern parameters must be in the following format: :camelCase

Match must occur from the first character of str in order to be considered successful (see examples below).

If match is not successful, extractParams returns null.

Example 1

var params = extractParams(
  '/users/123/friends/456/photo',
  '/users/:userId/friends/:friendId/photo'
);

/* 
  Returns:
    {
      userId: '123',
      friendId: '456'
    }
*/

Example 2

var params = extractParams(
  '/home/users/123/friends/456/photo',
  '/users/:userId/friends/:friendId/photo'
);

/* 
  Returns:
    null
      
  because `str` matches `pattern`,
  but not from the first character of `str`.
*/

Example 3

var params = extractParams(
  '/users/1234/friends/456/photo',
  '/users/:userId/friends/:friendId/photo',
  function(params) {
    var userId = parseInt(params.userId, 10);
    
    return userId >= 1 && userId <= 999 ? params : null;
  }
);

/* 
  Returns:
    null
    
  because userId > 999
*/

extractParamsInFirstMatch(str, patterns)

Tests whether str matches one of the parameterized patterns. Every pattern can have an optional transform function. If none of the patterns match, extractParamsInFirstMatch returns null. Otherwise, it returns the matching pattern index and its parameters.

Example 1

var params = extractParamsInFirstMatch(
  '/users/123',
  [
    { pattern: '/users/:userId/friends/:friendId/photo' },
    { pattern: '/users/:userId/friends/:friendId' },
    { pattern: '/users/:userId/friends' },
    { pattern: '/users/:userId' },
    { pattern: '/users' }
  ]
);

/* 
  Returns:
    {
      patternIndex: 3,
      params: {
        userId: '123'
      }
    }
*/

Example 2

var params = extractParamsInFirstMatch(
  '/users/123/subscriptions',
  [
    { pattern: '/users/:userId/friends/:friendId/photo' },
    { pattern: '/users/:userId/friends/:friendId' },
    { pattern: '/users/:userId/friends' },
    { pattern: '/users/:userId' },
    { pattern: '/users' }
  ]
);

/* 
  Returns:
    null
    
  because none of the patterns match.
*/

Example 3

function userIdValidator(params) {
  if (!('userId' in params)) {
    return params;
  }

  // Without this check, '/users/1234/friends/567' would match '/users/:userId'
  // with { userId: '1234/friends/567' }
  if (!(/^\d+$/.test(params.userId))) {
    return null;
  }

  var userId = parseInt(params.userId, 10);

  return userId >= 1 && userId <= 999 ? params : null;
}
var params = extractParamsInFirstMatch(
  '/users/1234/friends/567',
  [
    { pattern: '/users/:userId/friends/:friendId/photo', transform: userIdValidator },
    { pattern: '/users/:userId/friends/:friendId', transform: userIdValidator },
    { pattern: '/users/:userId/friends', transform: userIdValidator },
    { pattern: '/users/:userId', transform: userIdValidator },
    { pattern: '/users' }
  ]
);

/* 
  Returns:
    null
    
  because userId > 999
*/

Running Tests

npm test

License

MIT