🥾 Chemin 
A type-safe pattern builder & route matching library written in TypeScript
Gist
import { Chemin } from 'chemin';
const chemin = Chemin.parse('/admin/post/:postId/delete?');
console.log(chemin.match('/no/valid'));
// => false
console.log(chemin.match('/admin/post/e5t89u'));
// => { rest: [], params: { postId: 'e5t89u', delete: false } }More advanced (and type-safe) patterns
Use the Chemin.create and CheminParam to build more complex type-safe paths !
import { Chemin, CheminParam as P } from 'chemin';
const chemin = Chemin.create('admin', 'post', P.number('postId'), P.optionalConst('delete'));
console.log(chemin.match('/no/valid'));
// => false
const match = chemin.match('/admin/post/45');
console.log(match);
// => { rest: [], params: { postId: 45, delete: false } }Composition
You can use a Chemin inside another to easily compose your routes !
import { Chemin, CheminParam as P } from 'chemin';
const postFragment = Chemin.create('post', P.number('postId'));
const postAdmin = Chemin.create('admin', P.string('userId'), postFragment, 'edit');
console.log(postAdmin.stringify()); // /admin/:userId/post/:postId(number)/editCustom CheminParam
You can create your own CheminParam to better fit your application while keeping full type-safety !
import { Chemin, CheminParam } from 'chemin';
// match only string of 4 char [a-z0-9]
function fourCharStringId<N extends string>(name: N): CheminParam<N, string> {
const reg = /^[a-z0-9]{4}$/;
return {
name,
match: (...all) => {
if (all[0].match(reg)) {
return { match: true, value: all[0], next: all.slice(1) };
}
return { match: false, next: all };
},
serialize: (value) => value,
stringify: () => `:${name}(id4)`,
};
}
const path = Chemin.create('item', fourCharStringId('itemId'));
console.log(path.match('/item/a4e3t')); // false (5 char)
console.log(path.match('/item/A4e3')); // false (Maj)
console.log(path.match('/item/a4e3')); // { rest: [], params: { itemId: 'a4e3' } }Take a look a the custom-advanced.ts example. and the build-in CheminParam.
API
Chemin.parse(pattern)
Parse a string into a
Cheminobject
Accepts a string (/admin/:user/edit?) and return a Chemin.
Supported patterns
admin: Create aCheminParam.constant('admin'):param: Create aCheminParam.string('param')maybe?: Create aCheminParam.optionalConst('maybe'):maybe?: Create aCheminParam.optionalString('maybe')
Chemin.parse('/admin/:userId/edit?');Chemin.create(...parts)
Create a
Chemin
Accepts any number or arguments of type string, CheminParam or Chemin.
Note: strings are converted to CheminParam.constant.
Chemin.create('admin', CheminParam.number('userId'), CheminParam.optionalConst('edit'));Chemin.isChemin(maybe)
Test wether an object is a
Cheminor not
Accepts one argument and return true if it's a Chemin, false otherwise.
Chemin.isChemin(Chemin.parse('/admin')); // truechemin.parts
An array of the parts (other
Chemins orCheminParams) that make the chemin.
Note: You probably don't need this.
Note 2: You should not mutate this array or any of it's elements !
chemin.serialize(params?, options?)
Serialize a chemin
Accepts some params (an object or null) and an optional option object.
The option object accepts two boolean properties:
leadingSlash(defaulttrue): Add a slash at the beginingtrailingSlash(default:false): Add a slash at the end
const chemin = Chemin.create(
'admin',
CheminParam.number('userId'),
CheminParam.optionalConst('edit')
);
chemin.serialize({ userId: 42, edit: true }); // /admin/42/editchemin.match(pathname)
Test a chemin against a pathanme
Accepts a pathname and return false or CheminMatchResult.
pathnamecan be either a string (/admin/user/5) or an array of strings (['admin', 'user', '5'])CheminMatchResultis an object with two propertiesrest: an array of string of the remaining parts of the pathname once the matching is doneparams: an object of params extracted from the matching
Note: If you want to pass an array to pathname make sure to use splitPathname.
chemin.matchExact(pathname)
Accepts the same arguments as chemin.match but return false if the path does not match or if rest is not empty, otherwise it returns the params object directly.
chemin.extract()
Return an array of all the Chemin it contains (as well as the Chemin itself).
import { Chemin } from 'chemin';
const admin = Chemin.create('admin');
const adminUser = Chemin.create(admin, 'user');
adminUser.extract(); // [adminUser, admin];chemin.stringify()
Return a string representation of the chemin.
import { Chemin, CheminParam as P } from 'chemin';
const postFragment = Chemin.create('post', P.number('postId'));
const postAdmin = Chemin.create('admin', P.string('userId'), postFragment, 'edit');
console.log(postAdmin.stringify()); // /admin/:userId/post/:postId(number)/editsplitPathname(pathname)
Split a pathname and prevent empty parts
Accepts a string and returns an array od strings.
splitPathname('/admin/user/5'); // ['admin', 'user', '5']CheminParam
The CheminParam object contains the build-in CheminParam.
CheminParam.number(name)
A number using
parseFloat(x)
const chemin = Chemin.create(CheminParam.number('myNum'));
Chemin.matchExact(chemin, '/3.1415'); // { myNum: 3.1415 }NOTE: Because it uses parseFloat this will also accept Infinity, 10e2...
CheminParam.integer(name, options?)
A integer using
parseInt(x, 10)
const chemin = Chemin.create(CheminParam.integer('myInt'));
Chemin.matchExact(chemin, '/42'); // { myInt: 42 }By default it will only match if the parsed number is the same as the raw value.
You can pass an option object with strict: false to allow any valid parseInt:
const chemin = Chemin.create(CheminParam.integer('myInt', { strict: false }));
Chemin.matchExact(chemin, '/42fooo'); // { myInt: 42 }CheminParam.string(name)
Any non-empty string
const chemin = Chemin.create(CheminParam.string('myStr'));
Chemin.matchExact(chemin, '/cat'); // { myStr: 'cat' }CheminParam.constant(name)
A constant string
const chemin = Chemin.create(CheminParam.constant('edit'));
Chemin.matchExact(chemin, '/edit'); // {}
Chemin.matchExact(chemin, '/'); // falseCheminParam.optional(cheminParam)
Make any
CheminParamoptional
const chemin = Chemin.create(CheminParam.optional(CheminParam.integer('myInt')));
Chemin.matchExact(chemin, '/42'); // { myInt: { present: true, value: 42 } }
Chemin.matchExact(chemin, '/'); // { myInt: { present: false } }CheminParam.optionalConst(name, path?)
An optional contant string
const chemin = Chemin.create(CheminParam.optionalConst('isEditing', 'edit'));
Chemin.matchExact(chemin, '/edit'); // { isEditing: true }
Chemin.matchExact(chemin, '/'); // { isEditing: false }If path is omitted then the name is used as the path.
const chemin = Chemin.create(CheminParam.optionalConst('edit'));
Chemin.matchExact(chemin, '/edit'); // { edit: true }
Chemin.matchExact(chemin, '/'); // { edit: false }CheminParam.optionalString(name)
An optional string parameter
const chemin = Chemin.create(CheminParam.optionalString('name'));
Chemin.matchExact(chemin, '/paul'); // { name: 'paul' }
Chemin.matchExact(chemin, '/'); // { name: false }CheminParam.multiple(cheminParam, atLeastOne?)
Allow a params to be repeated any number of time
const chemin = Chemin.create(CheminParam.multiple(CheminParam.string('categories')));
Chemin.matchExact(chemin, '/'); // { categories: [] }
Chemin.matchExact(chemin, '/foo/bar'); // { categories: ['foo', 'bar'] }const chemin = Chemin.create(CheminParam.multiple(CheminParam.string('categories'), true));
Chemin.matchExact(chemin, '/'); // false because atLeastOne is true
Chemin.matchExact(chemin, '/foo/bar'); // { categories: ['foo', 'bar'] }