@sounds.of.limbo/extensions v0.4.0

@sounds.of.limbo/extensions

Useful extensions for basic JS prototypes

Table of Contents

1. Installation
2. Basic usage
3. Available extensions
   1. Console
   2. Number
      1. padStart
      2. limit
      3. formatThousands
      4. pluralize
      5. as
4. Helpers
   1. interface SOLSizeNames
   2. class SOLTime
   3. class SOLSize

Installation

Simply install it using NPM:

npm install @sounds.of.limbo/extensions

Basic usage

To apply specific prototype extension, you have to import corresponding file at some point of you application:

// Assuming some React application
import React from "react"
import "@sounds.of.limbo/extensions/dist/Console"

export default class App extends React.Component {
    componentDidMount() {
        console.ok("Application *has been mounted*!")
    }

    render() {
        console.say("Application is being rendered")
        return <main>
            <h1>
                Hello, world!
            </h1>
        </main>
    }
}

Note that since corresponding file will be imported, extended prototype will be available GLOBALLY, including runtime (e.g. web browser's console). This is the basic side-effect of the prototype extension.

Available extensions

Console

Extended with five colorful log methods:

• say - cyan-colored , analogue of console.log
• nfo - blue-colored , analogue of console.info
• ok - lime-colored . Does not have analogues among basic console method. Typically being used for logging some success messages.
• hey - yellow-colored , analogue of console.warn
• no - red-colored , analogue of console.error

Despite some methods are marked as analogues, they are all still logging to the same level as console.log does. This is due to only console.log supports color customizations.

Each method takes infinite number of parameters. First parameter should be a string - this is the log message that will be colorfully customized. Other params will be logged as is.

You can make parts of the message to be written using bold font. To do this, just conclude desired part of message in asterisks (*) (see screenshots below).

Here is how custom logs look like in the browser console:

and here is an example from the terminal (Node.js):

Number

padStart

Analogue of String.prototype.padStart. Uses it under the hood.

padStart(maxLength: number, padWith?: string) => string

limit

Limit current number to min and max values.

limit(min: number, max: number) => number

Examples:

(-1).limit(0, 10) // => 0
(5).limit(0, 10) // => 5
(10).limit(0, 10) // => 10
(11).limit(0, 10) // => 10

formatThousands

Places spaces each 3 numbers

formatThousands() => string

Examples:

(1000).formatThousands() // => "1 000"
(12345.6789).formatThousands() // => "12 345.6789"

pluralize

Use value to create pluralized string

pluralize(singularForm: string, pluralForm: string, toFixed?: number) => string

Examples:

(2).pluralize("test", "tests") // => "2 tests"
(1 / 3 * 2).pluralize("pound", "pounds", 2) // "0.67 pounds"

as

Treat value as a time/size value in specified units and work with it in this context

as<T extends SOLTimeUnit | SOLSizeUnit>(unit: T) => T extends SOLTimeUnit ? SOLTime : SOLSize

Examples:

// Time units
(90).as("seconds").to("minutes") // => 1.5
(65.5).as("minutes").toTimeString() // => "1:05:30"

// Size units
(256).as("bytes").to("kilobytes") // => 0.25
(1536).as("kilobytes").toVerboseString() // => "1.5 MB"

Helpers

interface SOLSizeNames

Helper type that allows to specify custom singular and plural forms for specific size name.

interface SizeNames {
	/**
	 * default is **byte, bytes**
	 */
	bytes?: [string, string]
	/**
	 * default is **kB, kB**
	 */
	kilobytes?: [string, string]
	/**
	 * default is **MB, MB**
	 */
	megabytes?: [string, string]
	/**
	 * default is **GB, GB**
	 */
	gigabytes?: [string, string]
	/**
	 * default is **TB, TB**
	 */
	terabytes?: [string, string]
}

class SOLTime

Helper class, appears when you use Number.prototype.as() with TimeUnit as a parameter.

class SOLTime {
	constructor(
		value: number,
		unit: SOLTimeUnit,
	)

	/**
	 * Convert time value from current to target time unit
	 */
	to: (
		unit: SOLTimeUnit,
	) => number

	/**
	 * Make time string. For example:  
	 * **00:42**  
	 * **04:20**  
	 * **1:15:01**  
	 */
	toTimeString: (
		/**
		 * If there is more than 24 hours, whether there should be extra 'days' label at the start or not.  
		 * Default: `false`
		 */
		separateDays?: boolean
	) => string
}

class SOLSize

Helper class, appears when you use Number.prototype.as() with SizeUnit as a parameter.

class SOLSize {
	constructor(
		value: number,
		unit: SOLSizeUnit,
	)

	/**
	 * Convert size from current to target size unit
	 */
	to: (
		unit: SOLSizeUnit,
	) => number

	/**
	 * Make verbose size string up to terabytes (TB). For example:  
	 * **921 bytes**  
	 * **128 kB**  
	 * **1.2 MB**  
	 * **12.28 GB**  
	 * **1.2 TB**  
	 */
	toVerboseString: (
		customSizeNames?: SOLSizeNames
	) => string
}