journalize

A collection of functions useful for making prose reader friendly. Inspired by (and initially based on) Django's django.contrib.humanize.

• Why did you create this?
• Installation
• API Docs
• What if I do want to use this in Nunjucks?
• License

Why did you create this?

I've always really appreciated the built-in functionality provided by Django's humanize, and I wanted to port it over to JavaScript/Node.js. Originally this was to be a collection of custom filters, but I think it could be just as useful as a generic library.

Installation

npm install journalize
# or
yarn add journalize

journalize tries to support the many ways to load packages in the Node.js ecosystem.

If you use a module bundler like Browserify or Webpack, a version of journalize is built to be compatible.

constjournalize=require('journalize');// you can also reach in and grab specific functionsconstintcomma=require('journalize').intcomma;// orconst{ intcomma }=require('journalize');

It also supports ES6 imports:

import{intcomma}from'journalize';// or if you want the whole thingimport*asjournalizefrom'journalize';

API Docs

Table of Contents

• apdate
  • Parameters
  • Examples
• apdatetab
  • Parameters
  • Examples
• apmonth
  • Parameters
  • Examples
• apmonthtab
  • Parameters
  • Examples
• apnumber
  • Parameters
  • Examples
• aptime
  • Parameters
  • Examples
• capfirst
  • Parameters
  • Examples
• intcomma
  • Parameters
  • Examples
• intword
  • Parameters
  • Examples
• ordinal
  • Parameters
  • Examples
• ordinalsuffix
  • Parameters
  • Examples
• pluralize
  • Parameters
  • Examples
• widont
  • Parameters
  • Examples
• yesno
  • Parameters
  • Examples

apdate

Returns an AP-formatted date string that corresponds with the supplied Date. If an input is not passed, it will use the result of new Date();.

Parameters

• dateDate? JavaScript Date object, defaults to current date if not passed (optional, default new Date())

Examples

varjournalize=require('journalize');// Remember that JavaScript zero-indexes months!journalize.apdate(newDate(2016,10,8));// returns 'Nov. 8, 2016'// Uses the current date if no parameter is passedjournalize.apdate();// returns 'July 4, 2016' (pretend it is actually July 4, 2016)

Returns string

apdatetab

Returns a tabular AP-formatted date string that corresponds with the supplied Date. If an input is not passed, it will use the result of new Date();.

Parameters

• dateDate? JavaScript Date object, defaults to current date if not passed (optional, default new Date())

Examples

varjournalize=require('journalize');// Remember that JavaScript zero-indexes months!journalize.apdate(newDate(2016,10,8));// returns 'Nov 8, 2016'// Uses the current date if no parameter is passedjournalize.apdate();// returns 'Jul 4, 2016' (pretend it is actually July 4, 2016)

Returns string

apmonth

Returns an AP-formatted month string that corresponds with the supplied Date. If an input is not passed, it will use the result of new Date();.

Parameters

• dateDate? JavaScript Date object, defaults to current date if not passed (optional, default new Date())

Examples

varjournalize=require('journalize');// Remember that JavaScript zero-indexes months!journalize.apmonth(newDate(2016,10,8));// returns 'Nov.'// Uses the current date if no parameter is passedjournalize.apmonth();// returns 'July' (pretend it is actually July)

Returns string

apmonthtab

Returns a tabular AP-formatted month string that corresponds with the supplied Date. If an input is not passed, it will use the result of new Date();.

Parameters

• dateDate? JavaScript Date object, defaults to current date if not passed (optional, default new Date())

Examples

varjournalize=require('journalize');// Remember that JavaScript zero-indexes months!journalize.apmonth(newDate(2016,10,8));// returns 'Nov'// Uses the current date if no parameter is passedjournalize.apmonth();// returns 'Jul' (pretend it is actually July)

Returns string

apnumber

Converts an integer to string representation per AP style rules. If an integer is not one that would be converted, it is returned in its original form.

If a non-integer is given, it will be returned in its original form as well.

Parameters

• val(number | string)

Examples

varjournalize=require('journalize');journalize.apnumber(8);// returns 'eight'journalize.apnumber(42);// returns 42

Returns string

aptime

Returns an AP-formatted time string that corresponds with the supplied Date. If an input is not passed, it will use the result of new Date();.

Parameters

• dateDate? JavaScript Date object, defaults to current date if not passed (optional, default new Date())

Examples

varjournalize=require('journalize');// Bright and earlyjournalize.aptime(newDate(2016,10,8,6,30));// returns '6:30 a.m.'// It can handle `p.m.` toojournalize.aptime(newDate(2016,10,8,16,30));// returns '4:30 p.m.'// Uses the current time if no parameter is passedjournalize.aptime();// returns '6:45 p.m.' (pretend it is actually 6:45 p.m. right now)

Returns string

capfirst

Capitalizes the first character of a value and returns it.

Parameters

• valany

Examples

varjournalize=require('journalize');journalize.capfirst('hello world');// returns 'Hello world'

Returns string

intcomma

Alters a string or number to include commas. If val is undefined or null, an empty string is returned.

Parameters

• val(number | string)

Examples

varjournalize=require('journalize');journalize.intcomma(10311);// returns '10,311'journalize.intcomma('1234567.1234567');// returns '1,234,567.1234567'

Returns string

intword

Converts a large integer into a string representation. Only makes sense for numbers at least 1 million or more.

Parameters

• val(number | string)

Examples

varjournalize=require('journalize');journalize.intword(1000000);// returns '1 million'journalize.intword(6500000000000);// returns '6.5 trillion'

Returns string

ordinal

Converts an integer into its ordinal form. If spellOutOrdinals is true, 1 through 9 will be spelled out per AP style. Handles the special cases of 11, 12 and 13, too. If a non-integer is submitted it will be returned in its original form.

Parameters

• val(number | string)
• spellOutOrdinalsboolean? (optional, default false)

Examples

varjournalize=require('journalize');journalize.ordinal(5);// returns '5th'journalize.ordinal(13);// returns '13th'journalize.ordinal(103);// returns '103rd'journalize.ordinal(7,true);// returns 'seventh'

Returns string

ordinalsuffix

Determines the ordinal suffix for a given integer. Handles the special cases of 11, 12 and 13. If a non-integer is submitted an empty string will be returned.

Parameters

• val(number | string)

Examples

varjournalize=require('journalize');journalize.ordinalsuffix(5);// returns 'th'journalize.ordinalsuffix(13);// returns 'th'journalize.ordinalsuffix(103);// returns 'rd'journalize.ordinalsuffix(7);// returns 'th'journalize.ordinalsuffix('foo');// returns ''

Returns string

pluralize

Returns a plural suffix if the value is not 1. By default, pluralize uses "s" as the suffix. If a String is provided, pluralize will attempt to convert it into a Number. If an Array is provided instead of a number, the length of the Array is used to determine the suffix. An alternative plural suffix can be provided as the second parameter, and if necessary, an alternative singular suffix can be provided as the third.

Parameters

• value(number | string | array)
• pluralSuffixstring (optional, default 's')
• singularSuffixstring (optional, default '')

Examples

varjournalize=require('journalize');// typical usage'vote'+journalize.pluralize(0);// votes'vote'+journalize.pluralize(1);// vote'vote'+journalize.pluralize(2);// votes// the plural suffix may be changed'class'+journalize.pluralize(0,'es');// classes'class'+journalize.pluralize(1,'es');// class'class'+journalize.pluralize(2,'es');// classes// some words also need a custom singular suffix'cand'+journalize.pluralize(0,'ies','y');// candies'cand'+journalize.pluralize(1,'ies','y');// candy'cand'+journalize.pluralize(2,'ies','y');// candies

Returns string

widont

Prevents "widows" - a word by itself on a line - from appearing in strings by replacing the space between the last two words with a non-breaking space character.

Parameters

• valstring
• replaceCharstring The character to replace the space with (optional, default '\xA0')

Examples

varjournalize=require('journalize');journalize.widont('this is a string');// returns 'this is a string'journalize.widont('this is a string','HELLO');// returns 'this is aHELLOstring'

Returns string

yesno

Given a mapping of arguments for true, false, and (optionally) null/undefined, return a string according to the value. If maybe is not provided, a null or undefined value will return the no argument.

Parameters

• val(boolean | Null | undefined)
• yesstring (optional, default 'yes')
• nostring (optional, default 'no')
• maybestring (optional, default 'maybe')

Examples

varjournalize=require('journalize');journalize.yesno(true);// returns 'yes'journalize.yesno(false);// returns 'no'journalize.yesno(null);// returns 'maybe'journalize.yesno(true,'yay','nay','shruggie');// returns 'yay'journalize.yesno(false,'yay','nay','shruggie');// returns 'nay'journalize.yesno(null,'yay','nay','shruggie');// returns 'shruggie'

Returns (string | boolean | Null | undefined)

What if I do want to use this in Nunjucks?

Great question! I cannot speak to whether this is the best way, but it's what I've done without issue since journalize was released.

Once you have your nunjucks environment, you can loop through the properties of journalize and add each function as a filter.

constjournalize=require('journalize');constnunjucks=require('nunjucks');constenv=nunjucks.configure(/* */);/*Set up `journalize`. */for(letkeyinjournalize){letfunc=journalize[key];if(typeoffunc==='function'){env.addFilter(key,func);// this would work with env.addGlobal, too}}

Now every function of journalize is available in your templates!

License

MIT