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. If match is successful, it returns a hash of parameters and their values.

Otherwise, extractParams returns null.

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).

The match is considered successful only if str matches the pattern at the start and at the end (see examples 2 and 3 below).

pattern parameters must have letters only.

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',
  '/users/:userId'
);

/* 
  Returns:
    null
      
  because `str` doesn't match the `pattern` at the start.
*/

Example 3

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

/* 
  Returns:
    null
      
  because `str` doesn't match the `pattern` at the end.
*/

Example 4

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