@hyperfrontend/project-scope/core/encoding

encoding

File encoding detection and conversion utilities for safely handling text files with mixed BOM markers and binary content.

Detects UTF-8, UTF-16 LE/BE byte-order marks, identifies binary signatures (PNG, ZIP, PDF, etc.) for isTextFile checks, and converts buffers to UTF-8 strings with optional BOM stripping or addition.

API Reference

ƒ Functions

§function

addBom(content: string): string

Add UTF-8 BOM to string if not present.

Parameters

Name	Type	Description
§content	`string`	String to add BOM to

Returns

string

String with BOM

Example

Adding UTF-8 BOM to content

const content = 'Hello World'
const withBom = addBom(content)
// => '\ufeffHello World'

§function

bufferToString(content: Buffer, encoding?: BufferEncoding): string

Convert buffer to string with encoding detection.

Parameters

Name	Type	Description
§content	`Buffer`	Buffer to convert
§encoding?	`BufferEncoding`	Optional encoding override (auto-detected if not provided)

Returns

string

Converted string

Example

Converting file buffer to string with auto-detection

const fileBuffer = readFileSync('./config.json')
const content = bufferToString(fileBuffer)
// => '{"key": "value"}'

§function

detectEncoding(buffer: Buffer): BufferEncoding

Detect file encoding from BOM or content analysis.

Parameters

Name	Type	Description
§buffer	`Buffer`	Buffer to analyze

Returns

BufferEncoding

Detected encoding, defaults to 'utf-8'

Example

Detecting encoding from buffer

const buffer = readFileSync('./data.txt')
const encoding = detectEncoding(buffer)
const content = buffer.toString(encoding)

§function

detectEncodingInfo(buffer: Buffer): EncodingInfo

Detect if content is likely text or binary with encoding information.

Parameters

Name	Type	Description
§buffer	`Buffer`	Buffer to analyze

Returns

EncodingInfo

Encoding information

Example

Detecting encoding and BOM info

const buffer = readFileSync('./document.txt')
const info = detectEncodingInfo(buffer)
if (info.type === 'text') {
  console.log(`Encoding: ${info.encoding}, BOM: ${info.hasBom}`)
}

§function

hasBom(buffer: Buffer): boolean

Check if buffer starts with a BOM.

Parameters

Name	Type	Description
§buffer	`Buffer`	Buffer to check

Returns

boolean

True if buffer has a BOM

Example

Checking if buffer has BOM

const buffer = readFileSync('./file.txt')
if (hasBom(buffer)) {
  // Strip BOM before processing
}

§function

isTextFile(buffer: Buffer): boolean

Check if buffer represents text content.

Parameters

Name	Type	Description
§buffer	`Buffer`	Buffer to check

Returns

boolean

True if the buffer appears to be text

Example

Checking if content is text

const buffer = readFileSync('./unknown-file')
if (isTextFile(buffer)) {
  const content = buffer.toString('utf-8')
}

§function

stripBom(content: string): string

Strip BOM from start of string if present.

Parameters

Name	Type	Description
§content	`string`	String that may have BOM

Returns

string

String without BOM

Example

Stripping BOM from a string

const withBom = '\ufeffHello World'
const clean = stripBom(withBom)
// => 'Hello World'

§function

toUtf8(content: string | Buffer<ArrayBufferLike>, sourceEncoding: BufferEncoding): string

Convert content to UTF-8 string.

Parameters

Name	Type	Description
§content	`string \| Buffer<ArrayBufferLike>`	Buffer or string content
§sourceEncoding	`BufferEncoding`	Source encoding (auto-detected if not provided) (default: `'utf-8'`)

Returns

string

UTF-8 string

Example

Converting a buffer to UTF-8 string

const buffer = Buffer.from('Hello', 'utf-8')
const text = toUtf8(buffer)
// => 'Hello'

◆ Types

§type

EncodingInfo

Encoding detection result.

type EncodingInfo = { encoding: BufferEncoding; hasBom: boolean; type: "text" } | { format: string; type: "binary" }

● Variables

§type

BINARY_SIGNATURES

Common binary file signatures.

§type

UTF16_BE_BOM_BYTES

UTF-16 BE BOM bytes

§type

UTF16_LE_BOM_BYTES

UTF-16 LE BOM bytes

§type

UTF8_BOM

UTF-8 BOM string

§type

UTF8_BOM_BYTES

UTF-8 BOM bytes