{"id":10792,"library":"encoding-japanese","title":"Japanese Character Encoding Conversion","description":"encoding-japanese is a JavaScript library designed for detecting and converting various character encodings, with a strong focus on Japanese encodings like Shift_JIS, EUC-JP, and ISO-2022-JP, alongside common Unicode formats like UTF-8 and UTF-16. Unlike standard JavaScript string handling, which is internally UTF-16, this library processes encodings as arrays of character code values, allowing for conversions between diverse character sets. The current stable version is 2.2.0, with releases occurring infrequently, often driven by feature additions or maintenance updates. Its key differentiator is robust support for a wide range of Japanese encodings and its ability to handle character codes as arrays, making it suitable for binary data manipulation (e.g., with `Uint8Array` or Node.js `Buffer`).","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/polygonplanet/encoding.js","tags":["javascript","base64","charset","convert","detect","encoding","euc-jp","eucjp","iconv"],"install":[{"cmd":"npm install encoding-japanese","lang":"bash","label":"npm"},{"cmd":"yarn add encoding-japanese","lang":"bash","label":"yarn"},{"cmd":"pnpm add encoding-japanese","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library exports a namespace object, not a default export. Use `* as Encoding` for all methods.","wrong":"import Encoding from 'encoding-japanese';","symbol":"Encoding","correct":"import * as Encoding from 'encoding-japanese';"},{"note":"While `* as Encoding` is common, individual methods can be imported directly from their `lib` paths for tree-shaking benefits, though the `lib/encoding` path is less intuitive.","wrong":"import { detect } from 'encoding-japanese';","symbol":"Encoding.detect","correct":"import { detect } from 'encoding-japanese/lib/encoding';"},{"note":"For CommonJS, `require('encoding-japanese')` returns the full `Encoding` object. Destructuring individual methods directly from the top-level package is not directly supported without deeper path imports.","wrong":"const { convert } = require('encoding-japanese');","symbol":"Encoding.convert","correct":"const Encoding = require('encoding-japanese');\nconst convertedData = Encoding.convert(...);"}],"quickstart":{"code":"import * as Encoding from 'encoding-japanese';\n\n// Example: Convert a Shift_JIS string to UTF-8\nconst shiftJisBytes = new Uint8Array([\n  0x82, 0xA0, 0x82, 0xA2, 0x82, 0xA4, 0x82, 0xA6, 0x82, 0xA8 // 'あいうえお' in Shift_JIS\n]);\n\nconst utf8Bytes = Encoding.convert(shiftJisBytes, {\n  to: 'UTF8',\n  from: 'SJIS',\n  type: 'array'\n});\n\nconst utf8String = Encoding.codeToString(utf8Bytes);\nconsole.log('Original Shift_JIS (bytes):', shiftJisBytes);\nconsole.log('Converted UTF-8 (bytes):', utf8Bytes);\nconsole.log('Converted UTF-8 (string):', utf8String);\n\n// Example: Detect encoding\nconst detectedEncoding = Encoding.detect(shiftJisBytes);\nconsole.log('Detected encoding:', detectedEncoding);\n\n// Example: URL encoding\nconst urlEncoded = Encoding.urlEncode('テスト&123');\nconsole.log('URL Encoded:', urlEncoded);","lang":"typescript","description":"Demonstrates converting Shift_JIS byte array to UTF-8 string, detecting encoding, and URL encoding, highlighting core library functionalities."},"warnings":[{"fix":"Review calls to `Encoding.convert` and explicitly define a `fallback` option (e.g., `fallback: 'html-entity'`, `fallback: 'ignore'`, or `fallback: 'error'`) to match desired behavior for unrepresentable characters.","message":"Version 2.0.0 introduced breaking changes by adding a `fallback` option to `Encoding.convert`. Previously, unrepresentable characters might have been handled differently or implicitly, but now explicit handling through `fallback` options ('html-entity', 'ignore', 'error') is available. While adding functionality, existing code relying on previous implicit behavior for unrepresentable characters might need adjustment.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always convert JavaScript strings to character code arrays (e.g., `Encoding.stringToCode(myString)`) before passing them to `Encoding.convert` or `Encoding.detect` if you intend to specify a non-UTF-16 'from' encoding. Similarly, convert the resulting code arrays back to strings using `Encoding.codeToString`.","message":"JavaScript strings are internally UTF-16. `encoding-japanese` primarily works with arrays of character codes (e.g., `Uint8Array`). Direct string arguments to `convert` or `detect` are not the primary use case and might lead to unexpected results if not correctly converted to/from character code arrays first using `stringToCode` and `codeToString`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be explicit about the `type` option in `Encoding.convert` (e.g., `type: 'Uint8Array'`) if you expect a TypedArray. Ensure consistency in data types when chaining operations or explicitly convert between plain arrays and TypedArrays as needed.","message":"When using `Encoding.convert`, the `type` option determines the return format. Omitting it or using `type: 'array'` returns a plain number array, while `type: 'Uint8Array'` returns a TypedArray. Mixing these types in subsequent operations without explicit conversion can lead to errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure that if you need to serialize character code arrays, you convert them to a JSON-compatible format first, such as a regular array of numbers (`Array.from(uint8Array)`), or directly to a string via `Encoding.codeToString` before stringifying.","cause":"Attempting to `JSON.stringify` an array of character codes (especially Uint8Array) without proper serialization, or passing non-serializable objects to functions.","error":"TypeError: Converting circular structure to JSON"},{"fix":"Verify the package is installed (`npm install encoding-japanese`) and ensure your import statement is `import * as Encoding from 'encoding-japanese';` for ESM or `const Encoding = require('encoding-japanese');` for CommonJS. Check your bundler or TypeScript configuration if paths are being resolved incorrectly.","cause":"Incorrect import path or the package is not installed correctly, especially in environments with strict module resolution or when using specific build tools.","error":"Cannot find module 'encoding-japanese'"},{"fix":"Use the `fallback` option in `Encoding.convert` (e.g., `fallback: 'html-entity'`, `fallback: 'ignore'`, or `fallback: 'error'`) to explicitly define how unrepresentable characters should be handled. If 'error' is used, wrap the conversion in a `try...catch` block to gracefully handle the error.","cause":"Occurs when a character from the 'from' encoding cannot be represented in the 'to' encoding, and the `fallback` option is not handled or is set to 'error'.","error":"Unrepresentable character error or incorrect character output after conversion."}],"ecosystem":"npm"}