A collection of functions useful for making prose reader friendly. Inspired by (and initially based on) Django's django.contrib.humanize
.
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.
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.
const journalize = require('journalize');
// you can also reach in and grab specific functions
const intcomma = require('journalize').intcomma;
// or
const { intcomma } = require('journalize');
It also supports ES6 imports:
import { intcomma } from 'journalize';
// or if you want the whole thing
import * as journalize from 'journalize';
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();
.
date
Date? JavaScript Date object, defaults to current date if not passed (optional, defaultnew Date()
)
var journalize = require('journalize');
// Remember that JavaScript zero-indexes months!
journalize.apdate(new Date(2016, 10, 8));
// returns 'Nov. 8, 2016'
// Uses the current date if no parameter is passed
journalize.apdate();
// returns 'July 4, 2016' (pretend it is actually July 4, 2016)
Returns string
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();
.
date
Date? JavaScript Date object, defaults to current date if not passed (optional, defaultnew Date()
)
var journalize = require('journalize');
// Remember that JavaScript zero-indexes months!
journalize.apmonth(new Date(2016, 10, 8));
// returns 'Nov.'
// Uses the current date if no parameter is passed
journalize.apmonth();
// returns 'July' (pretend it is actually July)
Returns string
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.
val
number
var journalize = require('journalize');
journalize.apnumber(8);
// returns 'eight'
journalize.apnumber(42);
// returns 42
Returns string
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();
.
date
Date? JavaScript Date object, defaults to current date if not passed (optional, defaultnew Date()
)
var journalize = require('journalize');
// Bright and early
journalize.aptime(new Date(2016, 10, 8, 6, 30));
// returns '6:30 a.m.'
// It can handle `p.m.` too
journalize.aptime(new Date(2016, 10, 8, 16, 30));
// returns '4:30 p.m.'
// Uses the current time if no parameter is passed
journalize.aptime();
// returns '6:45 p.m.' (pretend it is actually 6:45 p.m. right now)
Returns string
Capitalizes the first character of a value and returns it.
val
string
var journalize = require('journalize');
journalize.capfirst('hello world');
// returns 'Hello world'
Returns string
Alters a string or number to include commas. If val
is undefined or null,
an empty string is returned.
var journalize = require('journalize');
journalize.intcomma(10311);
// returns '10,311'
journalize.intcomma('1234567.1234567');
// returns '1,234,567.1234567'
Returns string
Converts a large integer into a string representation. Only makes sense for numbers at least 1 million or more.
val
number
var journalize = require('journalize');
journalize.intword(1000000);
// returns '1 million'
journalize.intword(6500000000000);
// returns '6.5 trillion'
Returns string
Converts an integer into its ordinal form. Handles the special cases of 11, 12 and 13, too. If a non-integer is submitted, it will be returned in its original form.
val
number
var journalize = require('journalize');
journalize.ordinal(5);
// returns '5th'
journalize.ordinal(13);
// returns '13th'
journalize.ordinal(103);
// returns '103rd'
Returns string
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.
value
(number | string | Array)pluralSuffix
string (optional, default's'
)singularSuffix
string (optional, default''
)
var journalize = 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
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.
val
(boolean | Null | undefined)yes
string (optional, default'yes'
)no
string (optional, default'no'
)maybe
string (optional, default'maybe'
)
var journalize = 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'
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.
const journalize = require('journalize');
const nunjucks = require('nunjucks');
const env = nunjucks.configure(/* */);
/*
Set up `journalize`.
*/
for (let key in journalize) {
let func = journalize[key];
if (typeof func === 'function') {
env.addFilter(key, func); // this would work with env.addGlobal, too
}
}
Now every function of journalize
is available in your templates!
MIT