@konfirm/patternize

Patternize Module

Register and match patterns. Use patterns as EventEmitter subjects.

Getting started

Installation

$ npm install --save @konfirm/patternize

Usage

Matching patterns

const { patternize } = require('@konfirm/patternize');

patternize.register('hello.{audience}');

const input = 'hello.world';
const match = patternize.match(input);

//  match is now a list of matched Patterns, which can be explored even further
console.log(match[0].getMatchedValues(input));  //  { audience: 'world' }

Pattern events

const { emitter } = require('@konfirm/patternize');

emitter.on('hello.{audience}', (subject) => {
	console.log(subject.input);   //  'hello.world'
	console.log(subject.values);  //  { audience: 'world' }
});

emiter.emit('hello.world');

Patterns

All pattern matching uses regular expressions under the hood, when specifying a pattern which contains variables, the exact expressions matching variables can be configured to your requirements. If not specific expression is provided for the variable pattern, it will use \w+, which means; one or more of: Letter (any case), number or underscore.

Examples

user.{id:[0-9]{3,12}}

Matches 'user.' followed by 3-12 number characters, e.g. 'user.123' and 'user.987262725682', but not 'user.jane' or 'user.john'

date/{year:20[0-2][0-9]}

Matches 'date/' followed by '20', followed by a number 0-2, followed by any number, e.g. 'date/2017' and 'date/2029', but not 'date/1999' or 'date/2030'

date/{year:20[0-2][0-9]}-{month:0[1-9]|11|12}-{day:0[1-9]|[1-2][0-9]|3[01]}

Like the example above, with the addition of a month 01-12 followed by a day 01-31. While it enforces sane month/date ranges, this will not enforce the date entered to be valid in itself Matches 'date/2017-02-31' (invalid as a date, valid as a pattern) and 'date/2005-06-07', but not 'date/1970-01-01' or 'date/2017-1-2'

Important

While the sort order of matches does take greedyness into account (non-variable portions), the variable portions in itself are not prioritized in any way but instead treated as equals. This means that the order of registration is important, for example:

const { patternize } = require('@konfirm/patternize');

patternize.register('user.{catchall:.+}');
patternize.register('user.{id:[0-9]{3,12}}');
patternize.register('user.{name:[a-zA-Z]+}');

Will always match the first (with catchall) before anything else, take this into consideration when registering patterns or adding on and once subscriptions to an Emitter.

API

The main package file is an export of several classes and ready to use instances. These can be easily accessed using destructuring assignment. For example;

//  All exported instances
const { patternize, emitter } = require('@konfirm/patternize');

//  All exported classes
const { Patternize, Pattern, PatternComponent, Emitter } = require('@konfirm/patternize');

Available exports

type	name	description
class	Patternize	The Patternize class
class	Pattern	The Pattern class
class	PatternComponent	The PatternComponent class
class	Emitter	The Emitter class
instance	patternize	Ready to use instance of Patternize
instance	emitter	Ready to use instance of Emitter, linked with the patternize instance

Documentation

• README
• Patternize
  • new Patternize()
  • register(pattern [, force=false])
  • match(input)
  • matchOne(input)
  • find(pattern)
• Pattern
  • fromString(input)
  • createComponents(input)
  • getComponentList(input)
  • new Pattern(components)
  • string
  • normalized
  • components
  • matches(input)
  • satisfies(input)
  • getMatchedValues(input)
  • render(input)
  • equals(compare)
  • same(compare)
• PatternComponent
  • new PatternComponent(input)
  • PROPERTY_PATTERN
  • string
  • key
  • pattern
  • regexp
• Emitter
  • new Emitter([patternize])
  • on(pattern, handle [,limit=Infinity])
  • once(pattern, handle)
  • emit(input, ...args)

Licence

MIT License

Copyright (c) 2017 Konfirm

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.