{"id":18443,"library":"iconv-corefoundation","title":"iconv-corefoundation","description":"Character set conversion library using macOS CoreFoundation API. Version 1.1.7. Pre-compiled native add-on using N-API 3. macOS-only (requires 10.10+). Supports all legacy Macintosh scripts including Mac OS Inuit and double-byte scripts. Not for general use; prefer iconv-lite for cross-platform needs. No streaming API. Built for Node.js 8.11.2+ and 10+. Ships TypeScript types. MIT license.","status":"active","version":"1.1.7","language":"javascript","source_language":"en","source_url":"https://github.com/argv-minus-one/iconv-corefoundation","tags":["javascript","corefoundation","iconv","convert","charset","mac","typescript"],"install":[{"cmd":"npm install iconv-corefoundation","lang":"bash","label":"npm"},{"cmd":"yarn add iconv-corefoundation","lang":"bash","label":"yarn"},{"cmd":"pnpm add iconv-corefoundation","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for building native addon (pre-compiled binaries provided for macOS, but fallback build may need node-gyp)","package":"node-gyp","optional":true}],"imports":[{"note":"Named export, not default. Must be imported using named import syntax.","wrong":"import StringEncoding from 'iconv-corefoundation'","symbol":"StringEncoding","correct":"import { StringEncoding } from 'iconv-corefoundation'"},{"note":"ESM style works, but also available via CJS. TypeScript friendly with types.","wrong":"const transcode = require('iconv-corefoundation').transcode","symbol":"transcode","correct":"import { transcode } from 'iconv-corefoundation'"},{"note":"Both ESM and CJS imports work. The named export is correct.","wrong":"const { encodeSmallest } = require('iconv-corefoundation')","symbol":"encodeSmallest","correct":"import { encodeSmallest } from 'iconv-corefoundation'"}],"quickstart":{"code":"import { StringEncoding, transcode } from 'iconv-corefoundation';\n\n// Get Mac OS Roman encoding\nconst macRoman = StringEncoding.byIANACharSetName('macintosh');\n\n// Encode a string\nconst buf = macRoman.encode('Hello, world!');\nconsole.log(buf); // <Buffer ...>\n\n// Decode back\nconst str = macRoman.decode(buf);\nconsole.log(str); // 'Hello, world!'\n\n// Transcode directly between buffers (no JS string)\nconst utf8Buf = Buffer.from('Hello, world!', 'utf8');\nconst latin1 = StringEncoding.byCFStringEncoding(0x0600); // kCFStringEncodingISOLatin1\nconst latin1Buf = transcode(utf8Buf, null, latin1); // null means UTF-8\nconsole.log(latin1Buf);\n","lang":"typescript","description":"Demonstrates encoding/decoding and transcoding with StringEncoding and transcode function."},"warnings":[{"fix":"Use a conditional import or alternative cross-platform library like iconv-lite.","message":"This package only works on macOS. It will fail on Windows, Linux, or other platforms.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Upgrade Node.js to 10.x or later.","message":"Node.js versions 8 and 9 are unsupported outside of LTS. Pre-compiled binaries for old Node versions may be unavailable.","severity":"deprecated","affected_versions":">=1.0.0 <1.2.0"},{"fix":"Call StringEncoding.by* methods to obtain an instance.","message":"StringEncoding cannot be constructed directly (new StringEncoding() fails). Use static methods like byCFStringEncoding, byIANACharSetName, etc.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use Node.js 8.11.2 or later, or 10+.","message":"N-API version 3 is required. Older Node.js versions (below 8.11.2) are not supported.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Load entire string/buffer into memory before conversion.","message":"No streaming API. CoreFoundation does not support incremental conversion.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Benchmark with your data; consider alternatives for performance-sensitive tasks.","message":"Performance may be slow for large strings due to multiple copies.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Install Xcode CLI tools via xcode-select --install.","message":"Building from source requires Xcode command-line tools. GCC may not compile Core Foundation headers.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Rebuild native addon: npm rebuild iconv-corefoundation","cause":"Pre-compiled binary incompatible with current Node.js version (e.g., Node 12 vs Node 14).","error":"Error: The module 'iconv-corefoundation' was compiled against a different Node.js version using NODE_MODULE_VERSION 64. This version of Node.js requires NODE_MODULE_VERSION 72."},{"fix":"Use StringEncoding.byCFStringEncoding(...) or similar static method.","cause":"Attempted to call StringEncoding() as a function instead of using static methods.","error":"TypeError: Class constructor StringEncoding cannot be invoked without 'new'"},{"fix":"Do not import on non-macOS platforms. Use conditional require: if (process.platform === 'darwin') { ... }","cause":"Tried to use the package on non-macOS system.","error":"Error: Dynamic loading not supported: this module works only on macOS"},{"fix":"Reinstall package: npm install iconv-corefoundation","cause":"Native addon .node file missing or not installed properly.","error":"Error: Could not locate the bindings file. Tried: ..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}