Stringiful

About The Project

Stringiful gives an easy to use stringify function with built-in formatters and extendable configurations that will match every need.

Stringiful uses at its core NodeJS native module util.inspect, for colorful and amazing strings representations of any Object.

Stringiful supports also circular objects.

(note: colors are not supported on every shell, you should check if your terminal support ansi colors before using {colors: true} option)

Getting started

Prerequisites

This is a Node.js module available through the npm registry.

Before installing, download and install Node.js. Node.js 0.10 or higher is required.

Installation is done using the npm install command:

• npm

  npm install stringiful

Examples

simple use example

import { stringify } from 'stringiful';

const nestedObject = {
  a: { b: ['123', '456', new Date()], c: { d: '12323'}, e: 'testing'}
};

console.log(stringify(nestedObject));

colorful and compact output example

import { stringify, IStringifyOptions } from 'stringiful';

const nestedObject = {
  a: { b: ['123', '456', new Date()], c: { d: '12323'}, e: 'testing'}
};

const options: IStringifyOptions = { InspectOptions: { compact: true, colors: true }}

console.log(stringify(nestedObject, options));

change the default formatters parameters

import { stringify, IStringifyOptions } from 'stringiful';

const testObject = {
  a: { b: ['long string examples', 'as', new Date()], c: 'aa'}
};

const options: IStringifyOptions = {
    formatters: [
        { matches: 'string', params: { maxLength: 5 } }, // limit strings to length 5
        { matches: 'date', params: { timezone: 'Australia/Perth' } }, // change timezones of dates to Australia/Perth
    ],
    inspectOptions: {
        colors: true,
        depth: null
    },
};

console.log(stringify(testObject, options));

// outputs:
// { a: { b: [ 'long ...', 'as', 2021-04-16T16:50:37.000Z ], c: 'aa' } }

add new custom formatter

import { stringify, IStringifyOptions } from 'stringiful';

const testObject = {
  a: { b: ['long string examples', 'as', new Date()], c: { d: 'aa' }}
};

const options: IStringifyOptions = {
    formatters: [
        { matches: 'string', params: { maxLength: 5 } }, // limit strings to length 5
        {
            matches: (obj: any) => obj.d === 'aa',
            format: (obj: any) => {
                return { d: `---${obj.d}---` };
            },
        },
    ],
    inspectOptions: {
      colors: true,
      depth: null
    },
};

console.log(stringify(testObject, options));

// outputs:
//  a: {
//    b: [ 'long ...', 'as', 2021-04-16T11:56:57.000Z ],
//    c: { d: '---aa---' } // the formatted string is not limited to length 5 because of the custom formatter
//  }

for multiple time uses, create a stringify function with specefic options, which is also more efficient

import { createStringifyFunction, IStringifyOptions } from 'stringiful';

const testObject = {
  a: { b: ['long string examples', 'as', new Date()], c: { d: 'aa' }}
};

const testObject2 = {
  a: { d: 'aa', c: { d: 'aa' }}
};

const options: IStringifyOptions = {
    formatters: [
        { matches: 'string', params: { maxLength: 5 } }, // limit strings to length 5
        {
            matches: (obj: any) => obj.d === 'aa',
            format: (obj: any) => {
                return { d: `---${obj.d}---` };
            },
        },
    ],
    inspectOptions: {
      colors: true,
      depth: null
    },
};

const myAwesomeStringify = createStringifyFunction(options);
console.leg(myAwesomeStringify(testObject));
console.leg(myAwesomeStringify(testObject2));

// outputs:
//  a: {
//    b: [ 'long ...', 'as', 2021-04-16T11:56:57.000Z ],
//    c: { d: '---aa---' } // the formatted string is not limited to length 5 because of the custom formatter
//  }

//  a: { d: '---aa---', c: { d: '---aa---'} }

for more advanced exmaples visit src/exmaples/index.ts

Documentation

stringify

The main function of stringiful package, this is where all the magic happens.

the function will get any Object (with couple of options) and return the beautiful string representation of it.

It will also format the object as you wish using generic formatters configurations and couple of amazing default ones to.

look at the configuration here: Interfaces

Create Stringify Function

if your'e using stringify function couple of times using the same (or almost same) configuration, you are doing it wrong. you should use createStringifyFunction() that takes your configuration once and returns stringify function that you can use couple of times.

(note: you cant override the configuration after you created the function) (btw: this is much more efficient because the formatters are created only one time and the function will reuse them)

Formatters configuration

Stringiful supports couple of built-in formatters that you could configure as you wish

matches: 'string'

simple string formatter that will identify strings and limit their length

const params?: {
    maxLength?: number;
};

matches: 'axiosError'

simple axiosError formatter that will identify axios errors and filter their fields for simplified output. You can also configure the maximum response and request data length

const params?: {
    maxResponseDataLength?: number;
    maxRequestDataLength?: number;
};

matches: 'date'

simple date formatter that will identify dates and convert them to your prefered timezone and locale.

const params?: {
    timezone?: AllowedTimezone;
    locale?: string;
};

parse

WIP: doesn't implemanted yet

Interfaces

IStringifyOptions

interface IStringifyOptions {
    formatters?: IFormatterConfig[];
    inspectOptions?: InspectOptions;
}

IFormatterConfig

// this is the way of making your custom formatters for your specefic uses
interface IObjectFormatter {
    matches: (obj: any) => boolean; // this is the matches function that will help me find your specefic object and classify (look at the examples)
    format?: (obj: any) => any; // this is the format function, which will change your classified object as you wish
    fieldsWhitelist?: string[]; // you can also provide fieldsWhitelist and Blacklist which will filter fields from your classified object
    fieldsBlacklist?: string[];
}

// this is the way for you to reconfigure my default formatters
interface IDefaultFormatterConfig {
    matches: string; // the name of the type you want to override its config
    // for now its only 'string' | 'axiosError' | 'date',  but many more will be added soon;

    params?: {
        ... // every formatter got his own parameters that you can change (for an example, 'string' type got maxLength param)
    };
    format?: (obj: any) => any; // if you want to, you can override the format function of any formatter with your own formatter.
    // some formatters got also fieldsWhitelist and fieldsBlacklist also that you can change as you wish (as an example: 'axiosError')
    fieldsWhitelist?: string[]; 
    fieldsBlacklist?: string[]; 
}

export interface IFormatterConfig = IObjectFormatter | IDefaultFormatterConfig;

InspectOptions

This is the util.inspect original options, for more information util.inspect options

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Project Link: https://github.com/Samoray-l337/Stringiful