{"id":18735699,"url":"https://github.com/rdmurphy/journalize","last_synced_at":"2025-04-07T12:06:16.522Z","repository":{"id":7405166,"uuid":"56263366","full_name":"rdmurphy/journalize","owner":"rdmurphy","description":":newspaper: A collection of JavaScript functions useful for making prose reader friendly.","archived":false,"fork":false,"pushed_at":"2023-10-18T17:09:12.000Z","size":3067,"stargazers_count":112,"open_issues_count":13,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-15T00:17:21.319Z","etag":null,"topics":["ap-style","formatting","journalism","prose"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/journalize","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rdmurphy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-04-14T19:07:54.000Z","updated_at":"2024-06-18T15:37:23.752Z","dependencies_parsed_at":"2024-06-18T15:37:11.994Z","dependency_job_id":"41ede096-82e4-4d24-b79a-792a33b5b49e","html_url":"https://github.com/rdmurphy/journalize","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdmurphy%2Fjournalize","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdmurphy%2Fjournalize/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdmurphy%2Fjournalize/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rdmurphy%2Fjournalize/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rdmurphy","download_url":"https://codeload.github.com/rdmurphy/journalize/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648977,"owners_count":20972945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ap-style","formatting","journalism","prose"],"created_at":"2024-11-07T15:17:47.671Z","updated_at":"2025-04-07T12:06:16.501Z","avatar_url":"https://github.com/rdmurphy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# journalize\n\nA collection of functions useful for making prose reader friendly. Inspired by (and initially based on) Django's [`django.contrib.humanize`](https://docs.djangoproject.com/en/dev/ref/contrib/humanize/).\n\n[![build status](https://img.shields.io/github/actions/workflow/status/rdmurphy/journalize/nodejs.yml?branch=main\u0026style=flat-square)](https://github.com/rdmurphy/journalize/actions/workflows/nodejs.yml)\n[![Coveralls branch](https://img.shields.io/coveralls/rdmurphy/journalize/master.svg?style=flat-square)](https://coveralls.io/github/rdmurphy/journalize)\n[![npm version](https://img.shields.io/npm/v/journalize.svg?style=flat-square)](https://www.npmjs.com/package/journalize)\n[![npm](https://img.shields.io/npm/dm/journalize.svg?style=flat-square)](https://www.npmjs.com/package/journalize)\n\n- [Why did you create this?](#why-did-you-create-this)\n- [Installation](#installation)\n- [API Docs](#api-docs)\n- [What if I do want to use this in Nunjucks?](#what-if-i-do-want-to-use-this-in-nunjucks)\n- [License](#license)\n\n## Why did you create this?\n\nI'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](#what-if-i-do-want-to-use-this-in-nunjucks), but I think it could be just as useful as a generic library.\n\n## Installation\n\n```sh\nnpm install journalize\n\n# or\n\nyarn add journalize\n```\n\n`journalize` tries to support the many ways to load packages in the Node.js ecosystem.\n\nIf you use a module bundler like [Browserify](http://browserify.org) or [Webpack](http://webpack.github.io), a version of `journalize` is built to be compatible.\n\n```js\nconst journalize = require('journalize');\n\n// you can also reach in and grab specific functions\nconst intcomma = require('journalize').intcomma;\n// or\nconst { intcomma } = require('journalize');\n```\n\nIt also supports ES6 imports:\n\n```js\nimport { intcomma } from 'journalize';\n\n// or if you want the whole thing\nimport * as journalize from 'journalize';\n```\n\n## API Docs\n\n\u003c!-- Generated by documentation.js. Update this documentation by updating the source code. --\u003e\n\n#### Table of Contents\n\n- [apdate](#apdate)\n  - [Parameters](#parameters)\n  - [Examples](#examples)\n- [apdatetab](#apdatetab)\n  - [Parameters](#parameters-1)\n  - [Examples](#examples-1)\n- [apmonth](#apmonth)\n  - [Parameters](#parameters-2)\n  - [Examples](#examples-2)\n- [apmonthtab](#apmonthtab)\n  - [Parameters](#parameters-3)\n  - [Examples](#examples-3)\n- [apnumber](#apnumber)\n  - [Parameters](#parameters-4)\n  - [Examples](#examples-4)\n- [aptime](#aptime)\n  - [Parameters](#parameters-5)\n  - [Examples](#examples-5)\n- [capfirst](#capfirst)\n  - [Parameters](#parameters-6)\n  - [Examples](#examples-6)\n- [intcomma](#intcomma)\n  - [Parameters](#parameters-7)\n  - [Examples](#examples-7)\n- [intword](#intword)\n  - [Parameters](#parameters-8)\n  - [Examples](#examples-8)\n- [ordinal](#ordinal)\n  - [Parameters](#parameters-9)\n  - [Examples](#examples-9)\n- [ordinalsuffix](#ordinalsuffix)\n  - [Parameters](#parameters-10)\n  - [Examples](#examples-10)\n- [pluralize](#pluralize)\n  - [Parameters](#parameters-11)\n  - [Examples](#examples-11)\n- [widont](#widont)\n  - [Parameters](#parameters-12)\n  - [Examples](#examples-12)\n- [yesno](#yesno)\n  - [Parameters](#parameters-13)\n  - [Examples](#examples-13)\n\n### apdate\n\nReturns an AP-formatted date string that corresponds with the supplied\nDate. If an `input` is not passed, it will use the result of `new Date();`.\n\n#### Parameters\n\n- `date` **[Date](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date)?** JavaScript Date object, defaults to current date if\n  not passed (optional, default `new Date()`)\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\n// Remember that JavaScript zero-indexes months!\njournalize.apdate(new Date(2016, 10, 8));\n// returns 'Nov. 8, 2016'\n\n// Uses the current date if no parameter is passed\njournalize.apdate();\n// returns 'July 4, 2016' (pretend it is actually July 4, 2016)\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### apdatetab\n\nReturns a tabular AP-formatted date string that corresponds with the supplied\nDate. If an `input` is not passed, it will use the result of `new Date();`.\n\n#### Parameters\n\n- `date` **[Date](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date)?** JavaScript Date object, defaults to current date if\n  not passed (optional, default `new Date()`)\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\n// Remember that JavaScript zero-indexes months!\njournalize.apdate(new Date(2016, 10, 8));\n// returns 'Nov 8, 2016'\n\n// Uses the current date if no parameter is passed\njournalize.apdate();\n// returns 'Jul 4, 2016' (pretend it is actually July 4, 2016)\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### apmonth\n\nReturns an AP-formatted month string that corresponds with the supplied\nDate. If an `input` is not passed, it will use the result of `new Date();`.\n\n#### Parameters\n\n- `date` **[Date](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date)?** JavaScript Date object, defaults to current date if\n  not passed (optional, default `new Date()`)\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\n// Remember that JavaScript zero-indexes months!\njournalize.apmonth(new Date(2016, 10, 8));\n// returns 'Nov.'\n\n// Uses the current date if no parameter is passed\njournalize.apmonth();\n// returns 'July' (pretend it is actually July)\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### apmonthtab\n\nReturns a tabular AP-formatted month string that corresponds with the supplied\nDate. If an `input` is not passed, it will use the result of `new Date();`.\n\n#### Parameters\n\n- `date` **[Date](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date)?** JavaScript Date object, defaults to current date if\n  not passed (optional, default `new Date()`)\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\n// Remember that JavaScript zero-indexes months!\njournalize.apmonth(new Date(2016, 10, 8));\n// returns 'Nov'\n\n// Uses the current date if no parameter is passed\njournalize.apmonth();\n// returns 'Jul' (pretend it is actually July)\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### apnumber\n\nConverts an integer to string representation per AP style rules. If an\ninteger is not one that would be converted, it is returned in its original\nform.\n\nIf a non-integer is given, it will be returned in its original form as\nwell.\n\n#### Parameters\n\n- `val` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))**\u0026#x20;\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\njournalize.apnumber(8);\n// returns 'eight'\n\njournalize.apnumber(42);\n// returns 42\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### aptime\n\nReturns an AP-formatted time string that corresponds with the supplied\nDate. If an `input` is not passed, it will use the result of `new Date();`.\n\n#### Parameters\n\n- `date` **[Date](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date)?** JavaScript Date object, defaults to current date if\n  not passed (optional, default `new Date()`)\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\n// Bright and early\njournalize.aptime(new Date(2016, 10, 8, 6, 30));\n// returns '6:30 a.m.'\n\n// It can handle `p.m.` too\njournalize.aptime(new Date(2016, 10, 8, 16, 30));\n// returns '4:30 p.m.'\n\n// Uses the current time if no parameter is passed\njournalize.aptime();\n// returns '6:45 p.m.' (pretend it is actually 6:45 p.m. right now)\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### capfirst\n\nCapitalizes the first character of a value and returns it.\n\n#### Parameters\n\n- `val` **any**\u0026#x20;\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\njournalize.capfirst('hello world');\n// returns 'Hello world'\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### intcomma\n\nAlters a string or number to include commas. If `val` is undefined or null,\nan empty string is returned.\n\n#### Parameters\n\n- `val` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))**\u0026#x20;\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\njournalize.intcomma(10311);\n// returns '10,311'\n\njournalize.intcomma('1234567.1234567');\n// returns '1,234,567.1234567'\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### intword\n\nConverts a large integer into a string representation. Only makes sense for\nnumbers at least 1 million or more.\n\n#### Parameters\n\n- `val` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))**\u0026#x20;\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\njournalize.intword(1000000);\n// returns '1 million'\n\njournalize.intword(6500000000000);\n// returns '6.5 trillion'\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### ordinal\n\nConverts an integer into its ordinal form. If `spellOutOrdinals` is `true`,\n1 through 9 will be spelled out per AP style. Handles the special cases of\n11, 12 and 13, too. If a non-integer is submitted it will be returned in\nits original form.\n\n#### Parameters\n\n- `val` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))**\u0026#x20;\n- `spellOutOrdinals` **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** (optional, default `false`)\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\njournalize.ordinal(5);\n// returns '5th'\n\njournalize.ordinal(13);\n// returns '13th'\n\njournalize.ordinal(103);\n// returns '103rd'\n\njournalize.ordinal(7, true);\n// returns 'seventh'\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### ordinalsuffix\n\nDetermines the ordinal suffix for a given integer. Handles the special\ncases of 11, 12 and 13. If a non-integer is submitted an empty string will\nbe returned.\n\n#### Parameters\n\n- `val` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String))**\u0026#x20;\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\njournalize.ordinalsuffix(5);\n// returns 'th'\n\njournalize.ordinalsuffix(13);\n// returns 'th'\n\njournalize.ordinalsuffix(103);\n// returns 'rd'\n\njournalize.ordinalsuffix(7);\n// returns 'th'\n\njournalize.ordinalsuffix('foo');\n// returns ''\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### pluralize\n\nReturns a plural suffix if the value is not 1. By default, `pluralize`\nuses \"s\" as the suffix. If a `String` is provided, `pluralize` will attempt\nto convert it into a `Number`. If an `Array` is provided instead of a\nnumber, the length of the `Array` is used to determine the suffix. An\nalternative plural suffix can be provided as the second parameter, and if\nnecessary, an alternative singular suffix can be provided as the third.\n\n#### Parameters\n\n- `value` **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) | [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array))**\u0026#x20;\n- `pluralSuffix` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** (optional, default `'s'`)\n- `singularSuffix` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** (optional, default `''`)\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\n// typical usage\n'vote' + journalize.pluralize(0); // votes\n'vote' + journalize.pluralize(1); // vote\n'vote' + journalize.pluralize(2); // votes\n\n// the plural suffix may be changed\n'class' + journalize.pluralize(0, 'es'); // classes\n'class' + journalize.pluralize(1, 'es'); // class\n'class' + journalize.pluralize(2, 'es'); // classes\n\n// some words also need a custom singular suffix\n'cand' + journalize.pluralize(0, 'ies', 'y'); // candies\n'cand' + journalize.pluralize(1, 'ies', 'y'); // candy\n'cand' + journalize.pluralize(2, 'ies', 'y'); // candies\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### widont\n\nPrevents \"widows\" - a word by itself on a line - from appearing in strings\nby replacing the space between the last two words with a non-breaking space\ncharacter.\n\n#### Parameters\n\n- `val` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n- `replaceChar` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** The character to replace the space with (optional, default `'\\xA0'`)\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\njournalize.widont('this is a string');\n// returns 'this is a\u0026nbsp;string'\n\njournalize.widont('this is a string', 'HELLO');\n// returns 'this is aHELLOstring'\n```\n\nReturns **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**\u0026#x20;\n\n### yesno\n\nGiven a mapping of arguments for `true`, `false`, and (optionally)\n`null`/`undefined`, return a string according to the value. If `maybe` is not\nprovided, a `null` or `undefined` value will return the `no` argument.\n\n#### Parameters\n\n- `val` **([boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) | [Null](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/null) | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))**\u0026#x20;\n- `yes` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** (optional, default `'yes'`)\n- `no` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** (optional, default `'no'`)\n- `maybe` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** (optional, default `'maybe'`)\n\n#### Examples\n\n```javascript\nvar journalize = require('journalize');\n\njournalize.yesno(true);\n// returns 'yes'\njournalize.yesno(false);\n// returns 'no'\njournalize.yesno(null);\n// returns 'maybe'\n\njournalize.yesno(true, 'yay', 'nay', 'shruggie');\n// returns 'yay'\njournalize.yesno(false, 'yay', 'nay', 'shruggie');\n// returns 'nay'\njournalize.yesno(null, 'yay', 'nay', 'shruggie');\n// returns 'shruggie'\n```\n\nReturns **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) | [boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean) | [Null](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/null) | [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))**\u0026#x20;\n\n## What if I do want to use this in [Nunjucks](http://mozilla.github.io/nunjucks/)?\n\nGreat question! I cannot speak to whether this is the best way, but it's what\nI've done without issue since `journalize` was released.\n\nOnce you have your `nunjucks` environment, you can loop through the\nproperties of `journalize` and add each function as a filter.\n\n```js\nconst journalize = require('journalize');\nconst nunjucks = require('nunjucks');\n\nconst env = nunjucks.configure(/* */);\n\n/*\nSet up `journalize`.\n */\nfor (let key in journalize) {\n  let func = journalize[key];\n\n  if (typeof func === 'function') {\n    env.addFilter(key, func); // this would work with env.addGlobal, too\n  }\n}\n```\n\nNow every function of `journalize` is available in your templates!\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frdmurphy%2Fjournalize","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frdmurphy%2Fjournalize","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frdmurphy%2Fjournalize/lists"}