symbolfyi

Pure TypeScript symbol encoder -- 11 encoding formats for any Unicode character. Zero dependencies.

Part of the FYIPedia open-source ecosystem. TypeScript port of the Python symbolfyi package.

Table of Contents

• Features
• Installation
• Quick Start
• What You Can Do
  • Symbol Encoding
  • Unicode Properties
  • HTML Entity Lookup
• API Reference
• Encoding Formats
• Supplementary Plane Support
• Learn More About Symbols
• Also Available
• FYIPedia Developer Tools
• License

Features

• 11 encoding formats for any Unicode character (BMP + supplementary plane)
• 51 HTML entity mappings with bidirectional lookup
• Unicode category detection using ES2018 Unicode property escapes
• Zero dependencies -- pure TypeScript, works in Node.js and browsers
• Full surrogate pair support for emoji and supplementary plane characters

Installation

npm install symbolfyi

Quick Start

import { getEncodings, getInfo, lookupHtmlEntity } from "symbolfyi";

// Encode any character into 11 formats
const enc = getEncodings("→");
enc.unicode     // "U+2192"
enc.htmlDecimal // "→"
enc.htmlHex     // "→"
enc.htmlEntity  // "→"
enc.css         // "\\2192"
enc.javascript  // "\\u{2192}"
enc.python      // "\\u2192"
enc.java        // "\\u2192"
enc.utf8Bytes   // "e2 86 92"
enc.utf16Bytes  // "21 92"
enc.urlEncoded  // "%E2%86%92"

// Get character info with category detection
const info = getInfo("$");
info?.category      // "Sc"
info?.categoryName  // "Currency Symbol"
info?.codepoint     // 36

// Look up HTML entities
lookupHtmlEntity("♥")  // "♥"
lookupHtmlEntity("amp")       // "&"

What You Can Do

Symbol Encoding

Encode any Unicode character into 11 different representations for use in HTML, CSS, JavaScript, Python, Java, and more. The encoder handles both BMP characters (U+0000-U+FFFF) and supplementary plane characters (U+10000+, including emoji) with correct surrogate pair encoding where needed.

| # | Format | BMP Example (→) | Supplementary Example (U+1F600) | Use Case | |---|--------|-------------------|----------------------------------|----------| | 1 | Unicode | U+2192 | U+1F600 | Documentation, character charts | | 2 | HTML Decimal | → | 😀 | HTML content (numeric reference) | | 3 | HTML Hex | → | 😀 | HTML content (hex reference) | | 4 | HTML Entity | → | (none) | HTML shorthand (51 common entities) | | 5 | CSS | \2192 | \1F600 | CSS content property | | 6 | JavaScript | \u{2192} | \u{1F600} | ES6+ string literals | | 7 | Python | \u2192 | \U0001f600 | Python string escapes | | 8 | Java | \u2192 | \uD83D\uDE00 | Java (surrogate pairs for U+10000+) | | 9 | UTF-8 Bytes | e2 86 92 | f0 9f 98 80 | Network protocols, file I/O | | 10 | UTF-16 Bytes | 21 92 | d8 3d de 00 | Windows APIs, Java internals | | 11 | URL Encoded | %E2%86%92 | %F0%9F%98%80 | URLs, query strings |

import { getEncodings } from "symbolfyi";

// Encode the rightwards arrow into all 11 formats
const enc = getEncodings("\u2192");
console.log(enc.unicode);      // "U+2192"
console.log(enc.htmlEntity);   // "→"
console.log(enc.css);          // "\\2192"
console.log(enc.javascript);   // "\\u{2192}"
console.log(enc.utf8Bytes);    // "e2 86 92"
console.log(enc.urlEncoded);   // "%E2%86%92"

Learn more: Symbol Encoder · HTML Entity Collections · Unicode Blocks

Unicode Properties

Every Unicode character belongs to one of 30 general categories (e.g., "Math Symbol", "Currency Symbol", "Uppercase Letter"). The getInfo() function returns the character's codepoint, category, human-readable category name, and all 11 encodings.

| Category Code | Category Name | Example Characters | |--------------|---------------|-------------------| | Lu | Uppercase Letter | A, B, C, ..., Z | | Ll | Lowercase Letter | a, b, c, ..., z | | Nd | Decimal Number | 0, 1, 2, ..., 9 | | Sm | Math Symbol | +, =, <, >, ~ | | Sc | Currency Symbol | $, EUR, GBP, JPY | | So | Other Symbol | (C), (R), (TM), ... | | Ps | Open Punctuation | (, [, { | | Pe | Close Punctuation | ), ], } |

import { getInfo, getCategoryName } from "symbolfyi";

// Get full Unicode properties for any character
const info = getInfo("$");
console.log(info?.codepoint);      // 36
console.log(info?.category);       // "Sc"
console.log(info?.categoryName);   // "Currency Symbol"
console.log(info?.encodings.htmlHex);  // "$"

// Look up category names
console.log(getCategoryName("Sm"));  // "Math Symbol"
console.log(getCategoryName("Lu"));  // "Uppercase Letter"
console.log(getCategoryName("Nd"));  // "Decimal Number"

Learn more: Unicode Category Reference · Unicode Blocks · REST API Docs

HTML Entity Lookup

Resolve 51 common HTML named entities back to their characters. Accepts bare names (amp), &-prefixed (&amp), or full format (&).

import { lookupHtmlEntity, HTML_ENTITIES, HTML_ENTITY_TO_CHAR } from "symbolfyi";

// Reverse lookup: entity name to character
console.log(lookupHtmlEntity("♥"));  // "heart character"
console.log(lookupHtmlEntity("amp"));       // "&"
console.log(lookupHtmlEntity("→"));    // "rightwards arrow"
console.log(lookupHtmlEntity("unknown"));   // null

// Direct data access
console.log(HTML_ENTITIES[0x2192]);           // "rarr"
console.log(HTML_ENTITY_TO_CHAR["rarr"]);     // "rightwards arrow character"

Learn more: HTML Entity Reference · Math Symbols · Currency Symbols

API Reference

getEncodings(char: string): EncodingInfo

Compute all 11 encoding representations for a single Unicode character.

| Property | Example (→) | Description | |----------|---------------|-------------| | unicode | U+2192 | Unicode codepoint notation | | htmlDecimal | → | HTML decimal entity | | htmlHex | → | HTML hexadecimal entity | | htmlEntity | → | Named HTML entity (empty if none) | | css | \2192 | CSS escape sequence | | javascript | \u{2192} | JavaScript escape sequence | | python | \u2192 | Python escape (\U for supplementary) | | java | \u2192 | Java escape (surrogate pairs for supplementary) | | utf8Bytes | e2 86 92 | UTF-8 byte representation | | utf16Bytes | 21 92 | UTF-16 BE byte representation | | urlEncoded | %E2%86%92 | URL percent-encoded |

getInfo(char: string): SymbolInfo | null

Get Unicode character info including category and all encodings. Returns null for empty input.

interface SymbolInfo {
  codepoint: number;        // 8594
  character: string;        // "→"
  category: string;         // "Sm"
  categoryName: string;     // "Math Symbol"
  encodings: EncodingInfo;  // All 11 formats
}

getCategoryName(code: string): string

Get the full name for a Unicode general category code.

getCategoryName("Sm")  // "Math Symbol"
getCategoryName("Lu")  // "Uppercase Letter"
getCategoryName("Nd")  // "Decimal Number"

lookupHtmlEntity(entity: string): string | null

Look up the character for an HTML entity. Accepts bare names, &-prefixed, or full &...; format.

lookupHtmlEntity("amp")      // "&"
lookupHtmlEntity("&")    // "&"
lookupHtmlEntity("♥") // "♥"
lookupHtmlEntity("unknown")  // null

Data Exports

import { HTML_ENTITIES, HTML_ENTITY_TO_CHAR } from "symbolfyi";

// Codepoint → entity name
HTML_ENTITIES[0x2192]  // "rarr"

// Entity name → character
HTML_ENTITY_TO_CHAR["rarr"]  // "→"

Encoding Formats

| # | Format | BMP Example | Supplementary Example | |---|--------|-------------|----------------------| | 1 | Unicode | U+2192 | U+1F600 | | 2 | HTML Decimal | → | 😀 | | 3 | HTML Hex | → | 😀 | | 4 | HTML Entity | → | (none) | | 5 | CSS | \2192 | \1F600 | | 6 | JavaScript | \u{2192} | \u{1F600} | | 7 | Python | \u2192 | \U0001f600 | | 8 | Java | \u2192 | \uD83D\uDE00 | | 9 | UTF-8 | e2 86 92 | f0 9f 98 80 | | 10 | UTF-16 | 21 92 | d8 3d de 00 | | 11 | URL | %E2%86%92 | %F0%9F%98%80 |

Supplementary Plane Support

Characters above U+FFFF (emoji, musical symbols, etc.) are fully supported:

const enc = getEncodings("\u{1F600}");  // 😀
enc.unicode     // "U+1F600"
enc.javascript  // "\\u{1F600}"
enc.python      // "\\U0001f600"
enc.java        // "\\uD83D\\uDE00"  (surrogate pair)
enc.utf8Bytes   // "f0 9f 98 80"
enc.utf16Bytes  // "d8 3d de 00"

Learn More About Symbols

• Browse: Symbol Search · Unicode Blocks
• Collections: HTML Entities · Math Symbols
• API: REST API Docs · OpenAPI Spec
• Python: PyPI Package

Also Available

• Python: pip install symbolfyi -- the original package with unicodedata integration
• Web: symbolfyi.com -- look up any symbol's encodings online

FYIPedia Developer Tools

Part of the FYIPedia open-source developer tools ecosystem.

| Package | PyPI | npm | Description | |---------|------|-----|-------------| | colorfyi | PyPI | npm | Color conversion, WCAG contrast, harmonies -- colorfyi.com | | emojifyi | PyPI | npm | Emoji encoding & metadata for 3,953 emojis -- emojifyi.com | | symbolfyi | PyPI | npm | Symbol encoding in 11 formats -- symbolfyi.com | | unicodefyi | PyPI | npm | Unicode lookup with 17 encodings -- unicodefyi.com | | fontfyi | PyPI | npm | Google Fonts metadata & CSS -- fontfyi.com | | distancefyi | PyPI | npm | Haversine distance & travel times -- distancefyi.com | | timefyi | PyPI | npm | Timezone ops & business hours -- timefyi.com | | namefyi | PyPI | npm | Korean romanization & Five Elements -- namefyi.com | | unitfyi | PyPI | npm | Unit conversion, 220 units -- unitfyi.com | | holidayfyi | PyPI | npm | Holiday dates & Easter calculation -- holidayfyi.com | | cocktailfyi | PyPI | -- | Cocktail ABV, calories, flavor -- cocktailfyi.com | | fyipedia | PyPI | -- | Unified CLI: fyi color info FF6B35 -- fyipedia.com | | fyipedia-mcp | PyPI | -- | Unified MCP hub for AI assistants -- fyipedia.com |

License

MIT -- FYIPedia