@vikhola/content-parser

About

Provides a simple infrastructure vikhola framework module for parsing request content.

Installation

$ npm i @vikhola/content-parser

Usage

Package could be required as ES6 module

import { ContentType } from '@vikhola/content-parser'

Or as commonJS module.

const { ContentType } = require('@vikhola/content-parser');

ContentParser

To start using parser enough to initialize it and subscribe to the desirable scope of the vikhola framework. By default, parser already have several strategies and can parse requests with application/json and text/plain content types.

const server = new Server();
const parser = new ContentParser();

parser.parse(server);

server.post('/', (ctx) => {
	// some logic	
});

Parser will parse the request body by the strategy whose key exactly or as closely as possible matches the request Content-Type header by its type and every parameter.

parser.parse(server);

// POST / HTTP 1.1
// Content-Type: 'application/json; foo=bar; bar=foo'
server.post('/', (ctx) => {
	// some logic	
});

For the requests with Content-Type header other than application/json and text/plain the parser supports custom keys and strategies where the first ones is the Content-Type header or corresponding to it RegExp.

parser.set(key, strategy)

The parser.set() method binds the strategy for the passed key.

const strategy = new ContentParserStrategy();

parser.set('application/xml', strategy);

As mention before the strategy key could be Content-Type header or corresponding to it RegExp.

const strategy = new ContentParserStrategy();

parser.set(/^application\/xml/, strategy);

If the strategy key type of RegExp, parser will try to match it only if there is no strategies with a string key matching the request Content-Type header.

const strategyOne = { parse(request, source) { return 'bar' } };
const strategyTwo = { parse(request, source) { return 'foo' } };

parser.set(/^application\/xml/, strategyOne);
parser.set('application/xml; foo=bar; bar=baz', strategyTwo);

// POST / HTTP 1.1
// Content-Type: 'application/xml; foo=bar; bar=foo'
server.post('/', (ctx) => {
	// print: bar
	console.log(ctx.request.body);
});

Another strategy key is *. Strategy with this key will be executed if the request has a Content-Type that does not match any other strategy key.

const strategy = { parse(request, source) { return 'bar' } };

parser.set('*', strategy);

// POST / HTTP 1.1
// Content-Type: 'application/xml; foo=bar; bar=foo'
server.post('/', (ctx) => {
	// print: bar
	console.log(ctx.request.body);
});

There is no restriction to type of strategy, it could be any object that has parse() method.

const parser = new ContentParser();
const strategy = {
	parse(request, source) {
		// process data
	}
};

parser.set('application/xml', strategy);

parser.has(key)

The parser.has() method checks whether any strategy is associated with the passed key.

const strategy = new ContentParserStrategy();

// print: false
console.log(parser.has('application/xml'));

parser.set('application/xml', strategy);

// print: true
console.log(parser.has('application/xml'));

The method will compare the keys also by their payload, and if it is the same, true will be returned.

const strategy = new ContentParserStrategy();

parser.set('application/xml; foo=bar; bar=foo', strategy);

// print: true
console.log(parser.has('application/xml; bar=foo; foo=bar'));

parser.get(key)

The parser.get() method returns the strategy associated with the passed key.

const strategy = new ContentParserStrategy();

parser.set('application/xml', strategy);

// print: true
console.log(parser.get('application/xml') === strategy);

The method will compare the keys also by their payload, and if it is the same, strategy will be returned.

const strategy = new ContentParserStrategy();

parser.set('application/xml; foo=bar; bar=foo', strategy);

// print: true
console.log(parser.get('application/xml; bar=foo; foo=bar') === strategy);

parser.delete(key)

The parser.delete() method remove key and bound to it strategy from the parser.

const strategy = new ContentParserStrategy();

parser.set('application/xml', strategy);

parser.delete('application/xml');

// print: false
console.log(parser.has('application/xml'));

parser.parse(event)

The parser.parse() method subscribes with the provided parameters to the target kernel.parse event, during which parses its body using a strategy whose key matches exactly or as closely as possible the Content-Type of the request.

const strategy = { parse(request, source) { return 'bar' } };

parser.set('application/xml', strategy);

// POST / HTTP 1.1
// Content-Type: 'application/xml'
server.post('/', (ctx) => {
	// print: bar
	console.log(ctx.request.body);
});

parser.clear()

The parser.clear() method removes all key-value pairs from the parser.

const strategy = new ContentParserStrategy();

parser.set('application/xml', strategy);

parser.clear();

// print: false
console.log(parser.has('application/xml'));

ContentParserStrategy

Except parser, module also exports a default strategy and its more specialized versions as JSONContentParserStrategy and TextContentParserStrategy which helps parse the provided request body and return a promise with its contents. The strategy accepts an optional limit and type parameters.

const strategy = new BaseContentParserStrategy({ limit: '10mb', type: 'string' });

The limit parameter specifies the maximum content size that will cause an error if exceeded. The limit can be represented as a number of bytes or a string with a number and its units.

const strategy = new BaseContentParserStrategy({ limit: '1mb' });

The type parameter specifies the type of data returned by the parse() method. It could be buffer or string. By default its equal to buffer.

const strategy = new BaseContentParserStrategy({ type: 'string' });

strategy.parse(request, source)

The strategy.parse() method parses the provided source and return promise with its content.

strategy.parse(request, source);

For example, this method can be extended and the returned string or buffer processed by a more specific parser.

strategy.parse(request, source) {
	return super.parse(request, source).then(content => parseXML(content));
}

License

MIT