iconv-corefoundation

1.1.7 verified Sat Apr 25 auth: no javascript

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.

Common errors

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. ↓

cause Pre-compiled binary incompatible with current Node.js version (e.g., Node 12 vs Node 14).

fix

Rebuild native addon: npm rebuild iconv-corefoundation

error TypeError: Class constructor StringEncoding cannot be invoked without 'new' ↓

cause Attempted to call StringEncoding() as a function instead of using static methods.

fix

Use StringEncoding.byCFStringEncoding(...) or similar static method.

error Error: Dynamic loading not supported: this module works only on macOS ↓

cause Tried to use the package on non-macOS system.

fix

Do not import on non-macOS platforms. Use conditional require: if (process.platform === 'darwin') { ... }

error Error: Could not locate the bindings file. Tried: ... ↓

cause Native addon .node file missing or not installed properly.

fix

Reinstall package: npm install iconv-corefoundation

Warnings

gotcha This package only works on macOS. It will fail on Windows, Linux, or other platforms. ↓

fix Use a conditional import or alternative cross-platform library like iconv-lite.

deprecated Node.js versions 8 and 9 are unsupported outside of LTS. Pre-compiled binaries for old Node versions may be unavailable. ↓

fix Upgrade Node.js to 10.x or later.

gotcha StringEncoding cannot be constructed directly (new StringEncoding() fails). Use static methods like byCFStringEncoding, byIANACharSetName, etc. ↓

fix Call StringEncoding.by* methods to obtain an instance.

breaking N-API version 3 is required. Older Node.js versions (below 8.11.2) are not supported. ↓

fix Use Node.js 8.11.2 or later, or 10+.

gotcha No streaming API. CoreFoundation does not support incremental conversion. ↓

fix Load entire string/buffer into memory before conversion.

gotcha Performance may be slow for large strings due to multiple copies. ↓

fix Benchmark with your data; consider alternatives for performance-sensitive tasks.

gotcha Building from source requires Xcode command-line tools. GCC may not compile Core Foundation headers. ↓

fix Install Xcode CLI tools via xcode-select --install.

Install

npm install iconv-corefoundation

yarn add iconv-corefoundation

pnpm add iconv-corefoundation

Imports

StringEncoding

wrong

import StringEncoding from 'iconv-corefoundation'

correct

import { StringEncoding } from 'iconv-corefoundation'

Named export, not default. Must be imported using named import syntax.

transcode

wrong

const transcode = require('iconv-corefoundation').transcode

correct

import { transcode } from 'iconv-corefoundation'

ESM style works, but also available via CJS. TypeScript friendly with types.

encodeSmallest

wrong

const { encodeSmallest } = require('iconv-corefoundation')

correct

import { encodeSmallest } from 'iconv-corefoundation'

Both ESM and CJS imports work. The named export is correct.

Quickstart

Demonstrates encoding/decoding and transcoding with StringEncoding and transcode function.

import { StringEncoding, transcode } from 'iconv-corefoundation';

// Get Mac OS Roman encoding
const macRoman = StringEncoding.byIANACharSetName('macintosh');

// Encode a string
const buf = macRoman.encode('Hello, world!');
console.log(buf); // <Buffer ...>

// Decode back
const str = macRoman.decode(buf);
console.log(str); // 'Hello, world!'

// Transcode directly between buffers (no JS string)
const utf8Buf = Buffer.from('Hello, world!', 'utf8');
const latin1 = StringEncoding.byCFStringEncoding(0x0600); // kCFStringEncodingISOLatin1
const latin1Buf = transcode(utf8Buf, null, latin1); // null means UTF-8
console.log(latin1Buf);