igniculus

Igniculus

SQL Syntax Highlighter and Logger. Unadorned and customizable.

Install

$ npm install igniculus

Usage

const igniculus = require('igniculus')();

igniculus('SELECT [port] AS Printer, \'on fire\' AS Status ' +
          'FROM [Printers] P ' +
          'WHERE P."online" AND P."check"');

Logger

A reference to the log function is returned on initialization but can be accesed anywhere through .log

// config.js
const igniculus = require('igniculus');
const options = { ... };

igniculus(options);

// any.js
const igniculus = require('igniculus');

let query = 'SELECT ...';
igniculus.log(query);

Options

A default color scheme is provided. However, you can define the highlight style for each rule when instantiating:

const igniculus = require('igniculus');
/* White constants over red background using inverse mode.
 * Gray keywords.
 * Prefixed by white '(query)' message.
 */
const options = {
    constants:         { mode: 'inverse', fg: 'red', bg: 'white' },
    standardKeywords:  { mode: 'bold', fg: 'black' },
    lesserKeywords:    { mode: 'bold', fg: 'black' },
    prefix:            { mode: 'bold', fg: 'white', text: '(query) '}
};
const illumine = igniculus(options);

illumine('SELECT * FROM Student s ' +
         'WHERE s.programme = \'IT\' AND EXISTS (' +
             'SELECT * FROM Enrolled e ' +
             'JOIN Class c ON c.code = e.code ' +
             'JOIN Tutor t ON t.tid = c.tid ' +
             'WHERE e.sid = s.sid AND t.name LIKE \'%Hoffman\')');

The options argument is optional and each property should be one of the following.

Rules

• options.constants - Values surrounded by single quotes. E.g: 'static'
• options.numbers - Numeric values. E.g: 2.5
• options.operators - Arithmetic, Bitwise and Comparison operators. E.g: + or >=
• options.delimitedIdentifiers - Text between brackets or double quotes. E.g: [Employee] or "salary"
• options.dataTypes - One of the included data types. E.g: INTEGER or VARCHAR
  • dataTypes.types - Array of custom data types. Replaces the ones by default. E.g: ['SERIAL', 'TIMESTAMP']
• options.standardKeywords - One the included keywords. E.g: SELECT or CONSTRAINT
  • standardKeywords.keywords - Array of custom standard keywords. Replaces the ones by default. E.g: ['CLUSTER', 'NATURAL']
• options.lesserKeywords - One of the included lesser keywords. E.g: ANY, AVG or DESC
  • lesserKeywords.keywords - Array of custom lesser keywords. Replaces the ones by default. E.g: ['VOLATILE', 'ASYMMETRIC']
• options.prefix
  • prefix.text - A prefix can be appended to every log through this option. This prefix can be styled like any previous options.
  • prefix.replace - Also, a string or regular expression can be provided and it will replace (if a prefix.text was given) or remove a prefix that matches such parameter. E.g: Sequelize prefixes every SQL statement with Executing (default): This is removed by default by the option prefix: { replace: /.*?: / }
• options.postfix
  • postfix.text - A postfix can be appended to every log through this option. This postfix can be styled like any previous options.

If defined, the options argument takes precedence over default options. If a rule or it´s style is missing it won't be applied. This allows to "enable" or "disable" certain syntax highlighting as you see fit. (Examples below)

A word on types and keywords

Most often, highlighting every reserved keyword can make syntax difficult to read, defeating the purpose altogether. Therefore, three distinct rules are provided: dataTypes, standardKeywords and lesserKeywords. Each of these rules can be customized individually and come with a predefined list of most widely used T-SQL and SQL-92 keywords and data types. Furthermore each of this lists can be customized as described above.

Styles

All of the previous rule styles can be defined like this:

/* options = {"rule": style, ... } where
 * style = { mode: "modifier", fg: "color", bg: "color"}
 */
const options = {
    constants: {
        mode: 'inverse',
        fg: 'red',
        bg: 'white'
    },
    ...
};

Each style having an optional:

• style.mode - Modifier. E.g: 'bold'
• style.fg - Foreground text color. E.g: 'red'
• style.bg - Background color. E.g: 'black'

These can be one of the following.

Modifiers

• reset
• bold
• dim
• italic
• underline
• blink
• inverse
• hidden
• strikethrough

Colors (Foreground and Background)

• black
• red
• green
• yellow
• blue
• magenta
• cyan
• white

Examples

/* Predifined style */
const defaults = {
    constants:              { mode: 'dim', fg: 'red' },
    delimitedIdentifiers:   { mode: 'dim', fg: 'yellow' },
    dataTypes:              { mode: 'dim', fg: 'green' },
    standardKeywords:       { mode: 'dim', fg: 'cyan' },
    lesserKeywords:         { mode: 'bold', fg: 'black' },
    prefix:                 { replace: /.*?: / }
};

const igniculus = require('igniculus')(
    {
        constants:             { mode: 'bold', fg: 'yellow' },
        numbers:               { mode: 'bold', fg: 'magenta' },
        delimitedIdentifiers:  { mode: 'bold', fg: 'red' },
        standardKeywords:      { mode: 'bold', fg: 'blue' }
    }
);

igniculus("INSERT INTO [Printers] ([port], [name], [ready], [online], [check]) " +
          "VALUES ('lp0', 'Bob Marley', 0, 1, 1)");

const igniculus = require('igniculus');

const options = {
    delimitedIdentifiers: {
        fg: 'yellow'
    },
    dataTypes: {
        fg: 'magenta',
        types: ['VARBINARY']
    },
    standardKeywords: {
        fg: 'red',
        keywords: ['CREATE', 'PRIMARY', 'KEY']
    },
    lesserKeywords: {
        mode: 'bold',
        fg: 'black',
        keywords: ['TABLE', 'NOT', 'NULL']
    },
    prefix: {
        text: '\n'
    }
};
igniculus(options);

igniculus.log('CREATE TABLE User (' +
              '[username] VARCHAR(20) NOT NULL, ' +
              '[password] BINARY(64) NOT NULL, ' +
              '[avatar] VARBINARY(MAX), PRIMARY KEY ([username]))');

Integration

Igniculus' logger is a drop in replacement on any tool that passes the log function either a string or Object paramater. In the latest case the toString() method will be called to obtain a string primitive.

Sequelize

Using igniculus with sequelize is straightforward.

const Sequelize = require('sequelize');
const igniculus = require('igniculus')();

const sequelize = new Sequelize('database', 'username', 'password', {
    logging: igniculus
});

/* Or add some customizations */
const Sequelize = require('sequelize');
const igniculus = require('igniculus')(
    {
        constants:             { fg: 'red' },
        delimitedIdentifiers:  { fg: 'yellow' },
        dataTypes:             { fg: 'red' },
        standardKeywords:      { fg: 'magenta' },
        lesserKeywords:        { mode: 'bold', fg: 'black' },
        prefix:                {
                                   mode: 'bold',
                                   fg: 'white',
                                   replace: /.*?:/,
                                   text: '(Sequelize)'
                               },
        postfix:               { text:'\r\n' }
    }
);
const sequelize = new Sequelize('database', 'username', 'password', {
    logging: igniculus
});

...

sequelize.sync({ logging: igniculus});

Before

After

Future Upgrades

• Custom rules
• Selecting log stream E.g: process.stdout

Maintainers

• Lucas Astrada

License

MIT

Changelog

1.0.0 ~ 29 Dec 2017

• Promotion to stable release
• Fixed compound operators mismatch
• Fixed keywords and data types breaking format if inside delimited identifiers
• Custom pluggable output support