Typescript definitions

jsdoc.json

@@ -1,14 +1,22 @@
 {
   "tags": {
     "allowUnknownTags": true,
-    "dictionaries": ["jsdoc"]
+    "dictionaries": [
+      "jsdoc"
+    ]
   },
   "source": {
-    "include": ["src", "README.md"],
-    "includePattern": ".js$",
+    "include": [
+      "src",
+      "README.md"
+    ],
+    "includePattern": ".(js|ts)$",
     "excludePattern": "(node_modules|utils|__tests__)"
   },
-  "plugins": ["plugins/markdown"],
+  "plugins": [
+    "node_modules/better-docs/typescript",
+    "plugins/markdown"
+  ],
   "opts": {
     "template": "node_modules/jsdoc-template/",
     "encoding": "utf8",

package.json

@@ -25,12 +25,12 @@
     "url": "https://github.com/WaniKani/WanaKana/issues"
   },
   "devEngines": {
-    "node": ">=12"
+    "node": ">=16"
   },
   "scripts": {
     "prebuild": "rimraf ./dist",
     "build": "rollup -c",
-    "build:watch": "onchange './src/**/*.js' -- npm run build",
+    "build:watch": "onchange './src/**/*.(js|ts)' -- npm run build",
     "precommit": "lint-staged",
     "cz": "git-cz",
     "cypress:server": "static-server -p 9080 -i './cypress/fixtures/test-input.html'",
@@ -40,7 +40,7 @@
     "cypress:watch": "npm-run-all --parallel --race build:watch cypress:server cypress:open",
     "predocs": "rimraf ./gh-pages/docs",
     "docs": "node_modules/.bin/jsdoc -c jsdoc.json --verbose",
-    "docs:watch": "onchange './src/**/*.js' -- npm run docs",
+    "docs:watch": "onchange './src/**/*.(js|ts)' -- npm run docs",
     "docs:view": "open ./gh-pages/docs/index.html",
     "demo:view": "npm run build && static-server ./gh-pages",
     "pretest": "rimraf ./coverage",
@@ -56,18 +56,22 @@
     "lint:js": "npm run lint -- ./src/**/*.js"
   },
   "devDependencies": {
-    "@babel/core": "7.17.9",
-    "@babel/preset-env": "^7.16.11",
-    "@rollup/plugin-babel": "^5.3.1",
-    "@rollup/plugin-node-resolve": "13.2.0",
+    "@babel/core": "^7.23.2",
+    "@babel/plugin-transform-runtime": "^7.23.2",
+    "@babel/preset-env": "^7.23.2",
+    "@babel/preset-typescript": "^7.23.2",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
     "benchmark": "^2.1.4",
+    "better-docs": "^2.7.2",
     "commitizen": "^4.2.4",
     "core-js": "3",
     "coveralls": "^3.1.1",
     "cross-env": "^7.0.3",
     "cypress": "9.5.4",
     "cz-conventional-changelog": "^3.3.0",
-    "eslint": "^7.32.0",
+    "eslint": "^8.52.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-plugin-cypress": "^2.12.1",
     "eslint-plugin-import": "2.26.0",
@@ -81,14 +85,15 @@
     "npm-run-all": "^4.1.5",
     "onchange": "^7.1.0",
     "open-cli": "^7.0.1",
-    "prettier-eslint-cli": "^5.0.1",
+    "prettier-eslint-cli": "^8.0.1",
     "readline-sync": "^1.4.10",
     "replace-in-file": "^6.3.2",
     "rimraf": "^3.0.2",
-    "rollup": "2.70.1",
-    "rollup-plugin-terser": "^7.0.2",
+    "rollup": "^4.1.4",
+    "rollup-plugin-ts": "^3.4.5",
     "shelljs": "^0.8.5",
-    "static-server": "^3.0.0"
+    "static-server": "^3.0.0",
+    "typescript": "^5.2.2"
   },
   "dependencies": {
     "dequal": "^2.0.2",
@@ -131,4 +136,4 @@
       "path": "cz-conventional-changelog"
     }
   }
-}
+}

rollup.config.js → rollup.config.mjs

@@ -1,9 +1,10 @@
 import { nodeResolve } from '@rollup/plugin-node-resolve';
-import { terser } from 'rollup-plugin-terser';
+import terser from '@rollup/plugin-terser';
 import babel from '@rollup/plugin-babel';
-import pkg from './package.json';
+import pkg from './package.json' assert { type: "json" };
+import ts from "rollup-plugin-ts";
 
-const input = ['src/index.js'];
+const input = ['src/index.ts'];
 
 export default [
   // UMD
@@ -15,6 +16,9 @@ export default [
         babelHelpers: 'bundled',
       }),
       terser(),
+      ts({
+        transpiler: "babel"
+      }),
     ],
     output: {
       file: `dist/${pkg.name}.min.js`,
@@ -28,7 +32,9 @@ export default [
   // ESM and CJS
   {
     input,
-    plugins: [nodeResolve()],
+    plugins: [nodeResolve(), ts({
+      browserslist: false
+    })],
     output: [
       {
         dir: 'dist/esm',

scripts/release.js

@@ -35,6 +35,7 @@ const PACKAGE_JSON = {
   ],
   addFields: {
     'main': 'cjs/index.js',
+    'types': 'cjs/index.d.ts',
     'react-native': 'cjs/index.js',
     'module': 'esm/index.js',
     'unpkg': 'wanakana.min.js',
@@ -163,7 +164,7 @@ try {
     execFail(
       exec(
         `cd ${OUT_DIR} && npm publish${otp && ` --otp=${otp}`}${distTag
-          && ` --tag ${distTag}`}`
+        && ` --tag ${distTag}`}`
       )
     )
   ) {

src/bind.js

@@ -12,7 +12,7 @@ const newId = () => {
 /**
  * Binds eventListener for 'input' events to an input field to automagically replace values with kana
  * Can pass `{ IMEMode: 'toHiragana' || 'toKatakana' }` to enforce kana conversion type
- * @param  {HTMLElement} element textarea, input[type="text"] etc
+ * @param  {HTMLInputElement | HTMLTextAreaElement} element textarea, input[type="text"] etc
  * @param  {DefaultOptions} [options=defaultOptions] defaults to { IMEMode: true } using `toKana`
  * @example
  * bind(document.querySelector('#myInput'));

src/constants.js → src/constants.ts

@@ -1,18 +1,32 @@
 export const VERSION = '5.2.0';
 
-export const TO_KANA_METHODS = {
+export const TO_KANA_METHODS: {
+  HIRAGANA: 'toHiragana',
+  KATAKANA: 'toKatakana',
+} = {
   HIRAGANA: 'toHiragana',
   KATAKANA: 'toKatakana',
 };
 
-export const ROMANIZATIONS = {
+export const ROMANIZATIONS: { HEPBURN: 'hepburn' } = {
   HEPBURN: 'hepburn',
 };
 
+export type DefaultOptions = {
+  useObsoleteKana?: boolean,
+  passRomaji?: boolean,
+  convertLongVowelMark?: boolean,
+  upcaseKatakana?: boolean,
+  IMEMode?: boolean | 'toHiragana' | 'toKatakana',
+  romanization?: 'hepburn',
+  customKanaMapping?: { [index: string]: string }
+  customRomajiMapping?: { [index: string]: string }
+};
+
 /**
  * Default config for WanaKana, user passed options will be merged with these
  * @type {DefaultOptions}
- * @name defaultOptions
+ * @name DefaultOptions
  * @property {Boolean} [useObsoleteKana=false] - Set to true to use obsolete characters, such as ゐ and ゑ.
  * @example
  * toHiragana('we', { useObsoleteKana: true })
@@ -21,31 +35,31 @@ export const ROMANIZATIONS = {
  * @example
  * toHiragana('only convert the katakana: ヒラガナ', { passRomaji: true })
  * // => "only convert the katakana: ひらがな"
- * @property {Object} [convertLongVowelMark=true] - Set to false to prevent conversions of 'ー' to extended vowels with toHiragana()
+ * @property {Boolean} [convertLongVowelMark=true] - Set to false to prevent conversions of 'ー' to extended vowels with toHiragana()
  * @example
  * toHiragana('ラーメン', { convertLongVowelMark: false });
  * // => 'らーめん
  * @property {Boolean} [upcaseKatakana=false] - Set to true to convert katakana to uppercase using toRomaji()
  * @example
  * toRomaji('ひらがな カタカナ', { upcaseKatakana: true })
  * // => "hiragana KATAKANA"
- * @property {Boolean|String} [IMEMode=false] - Set to true, 'toHiragana', or 'toKatakana' to handle conversion while it is being typed.
- * @property {String} [romanization='hepburn'] - choose toRomaji() romanization map (currently only 'hepburn')
- * @property {Object} [customKanaMapping] - custom map will be merged with default conversion
+ * @property {Boolean | 'toHiragana' | 'toKatakana'} [IMEMode=false] - Set to true, 'toHiragana', or 'toKatakana' to handle conversion while it is being typed.
+ * @property {'hepburn'} [romanization='hepburn'] - choose toRomaji() romanization map (currently only 'hepburn')
+ * @property {Object.<String, String>} [customKanaMapping] - custom map will be merged with default conversion
  * @example
  * toKana('wanakana', { customKanaMapping: { na: 'に', ka: 'Bana' }) };
  * // => 'わにBanaに'
- * @property {Object} [customRomajiMapping] - custom map will be merged with default conversion
+ * @property {Object.<String, String>} [customRomajiMapping] - custom map will be merged with default conversion
  * @example
  * toRomaji('つじぎり', { customRomajiMapping: { じ: 'zi', つ: 'tu', り: 'li' }) };
  * // => 'tuzigili'
  */
-export const DEFAULT_OPTIONS = {
+export const DEFAULT_OPTIONS: DefaultOptions = {
   useObsoleteKana: false,
   passRomaji: false,
+  convertLongVowelMark: true,
   upcaseKatakana: false,
   IMEMode: false,
-  convertLongVowelMark: true,
   romanization: ROMANIZATIONS.HEPBURN,
 };
 

src/isJapanese.js

@@ -5,7 +5,7 @@ import isCharJapanese from './utils/isCharJapanese';
 /**
  * Test if `input` only includes [Kanji](https://en.wikipedia.org/wiki/Kanji), [Kana](https://en.wikipedia.org/wiki/Kana), zenkaku numbers, and JA punctuation/symbols.”
  * @param  {String} [input=''] text
- * @param  {Regexp} [allowed] additional test allowed to pass for each char
+ * @param  {RegExp} [allowed] additional test allowed to pass for each char
  * @return {Boolean} true if passes checks
  * @example
  * isJapanese('泣き虫')

src/isMixed.js

@@ -6,7 +6,7 @@ import isRomaji from './isRomaji';
 /**
  * Test if `input` contains a mix of [Romaji](https://en.wikipedia.org/wiki/Romaji) *and* [Kana](https://en.wikipedia.org/wiki/Kana), defaults to pass through [Kanji](https://en.wikipedia.org/wiki/Kanji)
  * @param  {String} input text
- * @param  {Object} [options={ passKanji: true }] optional config to pass through kanji
+ * @param  {{ passKanji: Boolean}} [options={ passKanji: true }] optional config to pass through kanji
  * @return {Boolean} true if mixed
  * @example
  * isMixed('Abあア'))

src/isRomaji.js

@@ -5,7 +5,7 @@ import isCharRomaji from './utils/isCharRomaji';
 /**
  * Test if `input` is [Romaji](https://en.wikipedia.org/wiki/Romaji) (allowing [Hepburn romanisation](https://en.wikipedia.org/wiki/Hepburn_romanization))
  * @param  {String} [input=''] text
- * @param  {Regexp} [allowed] additional test allowed to pass for each char
+ * @param  {RegExp} [allowed] additional test allowed to pass for each char
  * @return {Boolean} true if [Romaji](https://en.wikipedia.org/wiki/Romaji)
  * @example
  * isRomaji('Tōkyō and Ōsaka')

src/stripOkurigana.js

@@ -11,7 +11,7 @@ const isInvalidMatcher = (input, matchKanji) =>
 /**
  * Strips [Okurigana](https://en.wikipedia.org/wiki/Okurigana)
  * @param  {String} input text
- * @param  {Object} [options={ leading: false, matchKanji: '' }] optional config
+ * @param  {{ leading: Boolean | undefined, matchKanji: string | undefined }} [options={ leading: false, matchKanji: '' }] optional config
  * @return {String} text with okurigana removed
  * @example
  * stripOkurigana('踏み込む')

src/toKana.js

@@ -33,6 +33,7 @@ export const createRomajiToKanaMap = memoizeOne(
  * Convert [Romaji](https://en.wikipedia.org/wiki/Romaji) to [Kana](https://en.wikipedia.org/wiki/Kana), lowercase text will result in [Hiragana](https://en.wikipedia.org/wiki/Hiragana) and uppercase text will result in [Katakana](https://en.wikipedia.org/wiki/Katakana).
  * @param  {String} [input=''] text
  * @param  {DefaultOptions} [options=defaultOptions]
+ * @param  {Object.<string, string>} [map] custom mapping
  * @return {String} converted text
  * @example
  * toKana('onaji BUTTSUUJI')

src/toRomaji.js

@@ -25,7 +25,7 @@ export const createKanaToRomajiMap = memoizeOne(
  * Convert kana to romaji
  * @param  {String} kana text input
  * @param  {DefaultOptions} [options=defaultOptions]
- * @param  {Object} map custom mapping
+ * @param  {Object.<string, string>} [map] custom mapping
  * @return {String} converted text
  * @example
  * toRomaji('ひらがな　カタカナ')

src/tokenize.js

@@ -12,7 +12,7 @@ const isCharJaSpace = (x) => x === '　';
 const isCharJaNum = (x) => /[０-９]/.test(x);
 const isCharEnNum = (x) => /[0-9]/.test(x);
 
-export const TOKEN_TYPES = {
+const TOKEN_TYPES = {
   EN: 'en',
   JA: 'ja',
   EN_NUM: 'englishNumeral',
@@ -68,8 +68,8 @@ export function getType(input, compact = false) {
  * If `{ compact: true }` then many same-language tokens are combined (spaces + text, kanji + kana, numeral + punctuation).
  * If `{ detailed: true }` then return array will contain `{ type, value }` instead of `'value'`
  * @param  {String} input text
- * @param  {Object} [options={ compact: false, detailed: false}] options to modify output style
- * @return {String|Object[]} text split into tokens containing values, or detailed object
+ * @param  {{compact: Boolean | undefined, detailed: Boolean | undefined}} [options={ compact: false, detailed: false}] options to modify output style
+ * @return {(String[]|Array.<{type: String, value: String}>)} text split into tokens containing values, or detailed object
  * @example
  * tokenize('ふふフフ')
  * // ['ふふ', 'フフ']

src/unbind.js

@@ -3,7 +3,7 @@ import { removeDebugListeners } from './utils/logInputEvents';
 
 /**
  * Unbinds eventListener from input field
- * @param  {HTMLElement} element textarea, input
+ * @param  {HTMLInputElement | HTMLTextAreaElement} element textarea, input
  */
 export function unbind(element, debug = false) {
   const listeners = findListeners(element);

tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "include": [
+    "src/*"
+  ],
+  "compilerOptions": {
+    // Tells TypeScript to read JS files, as
+    // normally they are ignored as source files
+    "allowJs": true,
+    // Generate d.ts files
+    "declaration": true,
+    // This compiler run should
+    // only output d.ts files
+    "emitDeclarationOnly": true,
+    // go to js file when using IDE functions like
+    // "Go to Definition" in VSCode
+    "declarationMap": true,
+    "importHelpers": true,
+    "target": "es6"
+  }
+}