ecli-parser

Node module to test, parse and normalize European Case Law Identifier 1.0 strings.

Description

Provides utility functions to test, normalize and parse strings formatted as European Case Law Identifier (ECLI) version 1.0 strings.

The create() function returns a function that can parse input strings in ECLI format. By default, the parse function operates in strict mode and requires strict adherence to the format proposed in the Annex of EU Council Conclusion 2011/C 127/01 of 29 April 2011. Optionally, the parse function can operate in lenient mode, with default values provided for the country, court and/or year fields. In lenient mode,input strings may omit any field except the id field, and their corresponding default values will be used instead.

If successful, the parse function returns a javascript object with the individual fields of the ECLI as properties: country, court, year and id. The year property is an integer, the others are uppercase string. The object also has a property called text, which contains the entire ECLI identifier as a string, normalized to uppercase. The object also has a property called version, which is always set to the string '1.0' (version 2.0 of the ECLI spec has not yet been adopted).

If an input string cannot be parsed as an ECLI identifier, the parse function returns null.

The test() and normalize() functions operate in strict mode only. The test function indicates whether an input string matches the ECLI spec. The normalize function does the same, but instead of returning a boolean returns the input string converted to uppercase (the preferred case according to the ECLI spec). If the input string is not well-formed, the normalize function returns null.

To test or normalize an input string in lenient mode, parse it instead and review the result.

Installation

To install, just npm install ecli-parser.

Usage

To test an input string, just require the test() function:

const test = require('ecli-parser').test;
if (test('ECLI:NL:HR:2017:AB1234')) {
  console.log('The input string is a well-formed ECLI 1.0 identifier.')
}

To normalize an input string, require the normalize() function:

const normalize = require('ecli-parser').normalize;
const ecli = normalize('ecli:nl:hr:2017:ab1234')
console.log( ecli ) // outputs 'ECLI:NL:HR:2017:AB1234'

To parse an input string, require the create() function. If called without an options argument, the create() function returns a parser that operates in strict mode:

const parse = require('ecli-parser').create();
const ecli = parse('ecli:nl:hr:2017:ab1234')
// The return value of parse() is the following object:
// {
//  country: 'NL',
//  court: 'HR',
//  year: 2017,
//  id: 'AB1234'
//  text: 'ECLI:NL:HR:2017:AB1234'
//  version: '1.0'
// }

To create a parser that operates lenient mode, you must pass in a options argument to the create() function, as described in the following section.

Options

Possible options in the argument to the create() function are:

• lenient (default: false): If true, the parser created will operate in lenient mode, meaning it will replace missing fields in an input string with their corresponding default values.
• country: The default value to use if the country field is missing in an input string to a lenient parser. A default value for the country field must be provided if one is provided for the court field, otherwise the create() function will throw a RangeError.
• court: The default value to use if the court field is missing in an input string to a lenient parser. If this option is set, the country option must also be set, otherwise the create() function will throw a RangeError.
• year (default: new Date().getFullYear()): The default value to use if the year field is missing in an input string to a lenient parser. If omitted, the parser will use the current year returned by javascript Date object. The value must a four digit number or numeric string, otherwise the create() function will throw a TypeError.

A lenient parser will accept input strings with fields missing and replace them their corresponding default values. Only the id field is required in the input string.

An input string to a lenient parser may optionally contain a leading colon (':').

Missing fields in input strings must be continguous, so no gaps allowed.

Some examples:

const ECLIPARSER = require('ecli-parser')

const opts = {
  lenient: true,
  country: 'NL',
  court: 'HR',
  year: 2017
}
const parse = ECLIPARSER.create(opts)

parse('ECLI:NL:HR:2017:148ABC') // well-formed, so succeeds in any event
parse('NL:HR:2017:148ABC') // succeeds as ECLI:NL:HR:2017:148ABC
parse('HR:2017:148ABC') // succeeds as same
parse(':HR:2017:148ABC') // succeeds as same, a leading colon is permitted
parse('HR:2017:') // fails, a trailing colon is not permitted and the id field is required
parse('2017:148ABC') // succeeds as same
parse('148ABC') // succeeds as same
parse('ECLI::HR::148ABC') // fails because the missing fields are not contiguous

Return value

If an input string is successfully parsed, the parser function returns an object with the following fields:

• country: The value of the country field as an uppercase string.
• court: The value of the court field as an uppercase string.
• year: The value of the year field as an integer.
• id: The value of the id field as an uppercase string.
• text: The entire ECLI identifier in uppercase.
• version: The fixed string '1.0'.

Running tests

The test/ directory contains a single test.js file with 38 mocha tests. The package.json file contains a test script command that runs mocha.