Stringiful
Warning - This is a Beta version
Stringiful
Stringify anything with powerful and configurable formatters.
·
Report a Bug or Request a Feature
·
Table of Contents
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.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature
) - Commit your Changes (
git commit -m 'Add some AmazingFeature'
) - Push to the Branch (
git push origin feature/AmazingFeature
) - Open a Pull Request
License
Distributed under the MIT License. See LICENSE
for more information.
Contact
Project Link: https://github.com/Samoray-l337/Stringiful