dale-chall-formula - npm Package Compare versions

Comparing version 2.0.0 to 2.0.1

index.d.ts

 /**
- * @typedef {Object.<string, number>} DaleChallFormulaCounts
- * @property {number} sentence
- * @property {number} word
- * @property {number} difficultWord
- */
-/**
- * Given the number of words (`word`), the number of sentences (`sentence`), and the number of unique unfamiliar words in a document (`difficultWord`), returns the score associated with the document.
+ * Given the number of words (`word`), the number of sentences (`sentence`),
+ * and the number of unique unfamiliar words in a document (`difficultWord`),
+ * returns the score associated with the document.
  *
- * @param {DaleChallFormulaCounts} counts
- * @returns {number}
+ * @param {Counts} counts
+ *   Counts from input document.
+ * @return {number}
+ *   Score representing ease of reading.
+ *
+ *   Pass it to `daleChallGradeLevel` to get grade levels.
  */
-export function daleChallFormula(counts: DaleChallFormulaCounts): number
+export function daleChallFormula(counts: Counts): number
 /**
- * Mapping between a dale-chall score and a U.S. grade level.
+ * Turn a dale–chall score into U.S. grade levels.
  *
  * @param {number} score
+ *   Score representing ease of reading.
  * @returns {[number, number]}
+ *   Grade levels.
+ *
+ *   |        Score | Corresponding grade level               | Return value     |
+ *   | -----------: | --------------------------------------- | ---------------- |
+ *   |  Less than 5 | Grade 4 and lower                       | `[0, 4]`         |
+ *   |  Less than 6 | Grades 5 and 6                          | `[5, 6]`         |
+ *   |  Less than 7 | Grades 7 and 8                          | `[7, 8]`         |
+ *   |  Less than 8 | Grades 9 and 10                         | `[9, 10]`        |
+ *   |  Less than 9 | Grades 11 and 12                        | `[11, 12]`       |
+ *   | Less than 10 | Grades 13 and 15 (College)              | `[13, 15]`       |
+ *   |       Higher | Grades 16 and higher (College Graduate) | `[16, Infinity]` |
  */
 export function daleChallGradeLevel(score: number): [number, number]
-export type DaleChallFormulaCounts = {
-  [x: string]: number
+/**
+ * Counts from input document.
+ */
+export type Counts = {
+  /**
+   *   Number of sentences.
+   */
+  sentence: number
+  /**
+   *   Number of words.
+   */
+  word: number
+  /**
+   * Number of difficult words.
+   */
+  difficultWord?: number | undefined
 }
+/**
+ * Deprecated: please use the `Counts` type instead.
+ */
+export type DaleChallFormulaCounts = Counts

index.js

@@ -1,9 +0,26 @@
-var difficultWordWeight = 0.1579
-var wordWeight = 0.0496
-var difficultWordThreshold = 0.05
-var percentage = 100
-var adjustment = 3.6365
+/**
+ * @typedef Counts
+ *   Counts from input document.
+ * @property {number} sentence
+ *   Number of sentences.
+ * @property {number} word
+ *   Number of words.
+ * @property {number} [difficultWord=0]
+ *   Number of difficult words.
+ */
 
+/**
+ * @typedef {Counts} DaleChallFormulaCounts
+ *   Deprecated: please use the `Counts` type instead.
+ */
+
+const difficultWordWeight = 0.1579
+const wordWeight = 0.0496
+const difficultWordThreshold = 0.05
+const percentage = 100
+const adjustment = 3.6365
+
 // Grade map associated with the scores.
-var gradeMap = {
+/** @type {Record<string, [number, number]>} */
+const gradeMap = {
   4: [0, 4],
@@ -20,20 +37,14 @@ 5: [5, 6],
 /**
- * @typedef {Object.<string, number>} DaleChallFormulaCounts
- * @property {number} sentence
- * @property {number} word
- * @property {number} difficultWord
- */
-
-/**
- * Given the number of words (`word`), the number of sentences (`sentence`), and the number of unique unfamiliar words in a document (`difficultWord`), returns the score associated with the document.
+ * Given the number of words (`word`), the number of sentences (`sentence`),
+ * and the number of unique unfamiliar words in a document (`difficultWord`),
+ * returns the score associated with the document.
  *
- * @param {DaleChallFormulaCounts} counts
- * @returns {number}
+ * @param {Counts} counts
+ *   Counts from input document.
+ * @return {number}
+ *   Score representing ease of reading.
+ *
+ *   Pass it to `daleChallGradeLevel` to get grade levels.
  */
 export function daleChallFormula(counts) {
-  /** @type {number} */
-  var percentageOfDifficultWords
-  /** @type {number} */
-  var score
-
   if (!counts || !counts.sentence || !counts.word) {
@@ -43,5 +54,4 @@ return Number.NaN
 
-  percentageOfDifficultWords = (counts.difficultWord || 0) / counts.word
-
-  score =
+  const percentageOfDifficultWords = (counts.difficultWord || 0) / counts.word
+  let score =
     difficultWordWeight * percentageOfDifficultWords * percentage +
@@ -58,9 +68,21 @@ (wordWeight * counts.word) / counts.sentence
 /**
- * Mapping between a dale-chall score and a U.S. grade level.
+ * Turn a dale–chall score into U.S. grade levels.
  *
  * @param {number} score
+ *   Score representing ease of reading.
  * @returns {[number, number]}
+ *   Grade levels.
+ *
+ *   |        Score | Corresponding grade level               | Return value     |
+ *   | -----------: | --------------------------------------- | ---------------- |
+ *   |  Less than 5 | Grade 4 and lower                       | `[0, 4]`         |
+ *   |  Less than 6 | Grades 5 and 6                          | `[5, 6]`         |
+ *   |  Less than 7 | Grades 7 and 8                          | `[7, 8]`         |
+ *   |  Less than 8 | Grades 9 and 10                         | `[9, 10]`        |
+ *   |  Less than 9 | Grades 11 and 12                        | `[11, 12]`       |
+ *   | Less than 10 | Grades 13 and 15 (College)              | `[13, 15]`       |
+ *   |       Higher | Grades 16 and higher (College Graduate) | `[16, Infinity]` |
  */
 export function daleChallGradeLevel(score) {
-  var floored = Math.floor(score)
+  let floored = Math.floor(score)
 
@@ -73,5 +95,4 @@ if (floored < 5) {
 
-  // eslint-ignore-next-line capitalized-comments
-  // type-coverage:ignore-next-line
+  // @ts-expect-error: fine.
   return gradeMap[floored].concat()
 }

package.json

 {
   "name": "dale-chall-formula",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Formula to detect the grade level of text according to the (revised) Dale-Chall Readability Formula (1995)",
@@ -31,19 +31,17 @@ "license": "MIT",
   "devDependencies": {
-    "@types/tape": "^4.0.0",
+    "@types/node": "^18.0.0",
     "c8": "^7.0.0",
     "prettier": "^2.0.0",
-    "remark-cli": "^9.0.0",
-    "remark-preset-wooorm": "^8.0.0",
-    "rimraf": "^3.0.0",
-    "tape": "^5.0.0",
+    "remark-cli": "^11.0.0",
+    "remark-preset-wooorm": "^9.0.0",
     "type-coverage": "^2.0.0",
     "typescript": "^4.0.0",
-    "xo": "^0.38.0"
+    "xo": "^0.52.0"
   },
   "scripts": {
     "prepack": "npm run build && npm run format",
-    "build": "rimraf \"*.d.ts\" && tsc && type-coverage",
+    "build": "tsc --build --clean && tsc --build && type-coverage",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
-    "test-api": "node test.js",
-    "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
+    "test-api": "node --conditions development test.js",
+    "test-coverage": "c8 --check-coverage --100 --reporter lcov npm run test-api",
     "test": "npm run build && npm run format && npm run test-coverage"
@@ -60,7 +58,3 @@ },
   "xo": {
-    "prettier": true,
-    "rules": {
-      "no-var": "off",
-      "prefer-arrow-callback": "off"
-    }
+    "prettier": true
   },
@@ -67,0 +61,0 @@ "remarkConfig": {

readme.md

@@ -11,11 +11,35 @@ # dale-chall-formula
 
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When should I use this?](#when-should-i-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`daleChallFormula(counts)`](#dalechallformulacounts)
+    *   [`daleChallGradeLevel(score)`](#dalechallgradelevelscore)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [Security](#security)
+*   [License](#license)
+
+## What is this?
+
+This package exposes an algorithm to detect ease of reading of English texts.
+
+## When should I use this?
+
+You’re probably dealing with natural language, and know you need this, if
+you’re here!
+
 See [`dale-chall`][list] for a list of words which count as “familiar”.
+All other words are considered “difficult” for this algorithm.
 
 ## Install
 
-This package is ESM only: Node 12+ is needed to use it and it must be `import`ed
-instead of `require`d.
+This package is [ESM only][esm].
+In Node.js (version 14.14+, 16.0+), install with [npm][]:
 
-[npm][]:
-
 ```sh
@@ -25,2 +49,16 @@ npm install dale-chall-formula
 
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {daleChallFormula, daleChallGradeLevel} from 'https://esm.sh/dale-chall-formula@2'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {daleChallFormula, daleChallGradeLevel} from 'https://esm.sh/dale-chall-formula@2?bundle'
+</script>
+```
+
 ## Use
@@ -33,7 +71,3 @@
 
-daleChallFormula({word: 30, sentence: 2}) // => 0.744
-
-daleChallFormula() // => NaN
-
-daleChallGradeLevel(daleChallFormula(30, 2, 6)) // => [9, 10]
+daleChallGradeLevel(daleChallFormula({word: 30, sentence: 2, difficultWord: 6})) // => [9, 10]
 ```
@@ -43,4 +77,3 @@
 
-This package exports the following identifiers: `daleChallFormula`,
-`daleChallGradeLevel`.
+This package exports the identifiers `daleChallFormula`, `daleChallGradeLevel`.
 There is no default export.
@@ -54,7 +87,37 @@
 
+##### `counts`
+
+Counts from input document.
+
+###### `counts.sentence`
+
+Number of sentences (`number`, required).
+
+###### `counts.word`
+
+Number of words (`number`, required).
+
+###### `counts.difficultWord`
+
+Number of unique unfamiliar words (`number`, default: `0`).
+
+##### Returns
+
+Score representing ease of reading (`number`).
+
+Pass it to `daleChallGradeLevel` to get grade levels.
+
 ### `daleChallGradeLevel(score)`
 
-Given a score, returns the corresponding grade ranges
+Turn a dale–chall score into U.S. grade levels.
 
-|        Score | Corresponding Grade Level               | Return value     |
+###### `score`
+
+Score representing ease of reading.
+
+###### Returns
+
+Grade levels (`[number, number]`).
+
+|        Score | Corresponding grade level               | Return value     |
 | -----------: | --------------------------------------- | ---------------- |
@@ -69,19 +132,39 @@ |  Less than 5 | Grade 4 and lower                       | `[0, 4]`         |
 
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type `Counts`.
+
+## Compatibility
+
+This package is at least compatible with all maintained versions of Node.js.
+As of now, that is Node.js 14.14+ and 16.0+.
+It also works in Deno and modern browsers.
+
 ## Related
 
 *   [`automated-readability`](https://github.com/words/automated-readability)
-    — Uses character count instead of error-prone syllable parser
+    — uses character count instead of error-prone syllable parser
 *   [`coleman-liau`](https://github.com/words/coleman-liau)
-    — Uses letter count instead of an error-prone syllable parser
+    — uses letter count instead of an error-prone syllable parser
 *   [`flesch`](https://github.com/words/flesch)
-    — Uses syllable count
+    — uses syllable count
 *   [`flesch-kincaid`](https://github.com/words/flesch-kincaid)
-    — Like `flesch-formula`, returns U.S. grade levels
+    — like `flesch-formula`, returns U.S. grade levels
 *   [`gunning-fog`](https://github.com/words/gunning-fog)
-    — Uses syllable count, needs POS-tagging and NER
+    — uses syllable count, needs POS-tagging and NER
 *   [`smog-formula`](https://github.com/words/smog-formula)
-    — Like `gunning-fog-index`, without needing advanced NLP
+    — like `gunning-fog-index`, without needing advanced NLP
 *   [`spache-formula`](https://github.com/words/spache-formula)
-    — Uses a dictionary, suited for lower reading levels
+    — uses a dictionary, suited for lower reading levels
 
+## Contribute
+
+Yes please!
+See [How to Contribute to Open Source][contribute].
+
+## Security
+
+This package is safe.
+
 ## License
@@ -111,2 +194,10 @@
 
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[esmsh]: https://esm.sh
+
+[typescript]: https://www.typescriptlang.org
+
+[contribute]: https://opensource.guide/how-to-contribute/
+
 [license]: license
@@ -113,0 +204,0 @@

No alert changes

Improved metrics

Total package byte prevSize

13247

increased by43.06%

Dev dependency count

8

decreased by-20%

Lines of code

137

increased by61.18%

Number of lines in readme file

203

increased by81.25%

No dependency changes