myna-dictionary

v1.0.8

Published

4 months ago

High-performance dictionary lookup library with compression

0High
0Medium
0Low

zenfast

myna dictionary lookup compression performance

Myna Dictionary

A high-performance dictionary lookup library with compression, designed for both Node.js and browser environments.

Features

On-demand loading: Dictionary shards loaded as needed (no 12MB upfront download)
Self-contained: All dictionary data included in npm package
No external files: No need to copy dictionary files to your project
Auto-initialization: Works out of the box with just lookup()
High performance: Fast lookups with intelligent caching
Compression: Built-in text compression for efficient storage
Cross-platform: Works in Node.js and browsers
Complete dictionary: 113,376 words ready to use

Installation

npm install myna-dictionary

Quick Start

Node.js

import { DictionaryLookup } from "myna-dictionary";

const dictionary = new DictionaryLookup();
const result = await dictionary.lookup("beauty");

console.log(result);
// {
//   word: 'beauty',
//   pos: 'noun',
//   definitions: ['An assemblage or graces or properties...'],
//   found: true
// }

Browser

<script type="module">
  import { DictionaryLookup } from "./node_modules/myna-dictionary/dist/index.js";

  const dictionary = new DictionaryLookup();
  const result = await dictionary.lookup("beauty");
  console.log(result);
</script>

API

DictionaryLookup

Constructor

const dictionary = new DictionaryLookup();

Methods

`lookup(word: string): Promise<LookupResult>`

Look up a word in the dictionary. Auto-initializes the dictionary on first call.

const result = await dictionary.lookup("programming");

Returns:

{
  word: string;        // Original word
  pos: string;         // Part of speech
  definitions: string[]; // Array of definitions
  found: boolean;      // Whether word was found
}

`getStats(): Promise<Stats>`

Get dictionary statistics.

const stats = await dictionary.getStats();
// {
//   totalWords: 113376,
//   totalShards: 358,
//   averageShardSize: 257,
//   compressionEnabled: { text_compression: true },
//   cachedShards: 0
// }

`clearCache(): void`

Clear the internal cache to free memory.

dictionary.clearCache();

`isInitialized(): boolean`

Check if the dictionary is initialized.

if (dictionary.isInitialized()) {
  // Dictionary is ready
}

Examples

Basic Usage

import { DictionaryLookup } from "myna-dictionary";

async function main() {
  const dict = new DictionaryLookup();

  // Look up words
  const words = ["beauty", "love", "happiness", "computer"];

  for (const word of words) {
    const result = await dict.lookup(word);

    if (result.found) {
      console.log(`${result.word} (${result.pos}): ${result.definitions[0]}`);
    } else {
      console.log(`${word}: Not found`);
    }
  }
}

main();

Performance Testing

import { DictionaryLookup } from "myna-dictionary";

async function performanceTest() {
  const dict = new DictionaryLookup();
  const words = ["beauty", "love", "happiness", "computer", "programming"];

  const startTime = Date.now();

  for (let i = 0; i < 1000; i++) {
    const word = words[i % words.length];
    await dict.lookup(word);
  }

  const endTime = Date.now();
  console.log(`1000 lookups took ${endTime - startTime}ms`);
}

performanceTest();

Browser Usage

Option 1: CDN (Automatic)

The library automatically uses jsDelivr CDN to load dictionary files. No setup required!

<!DOCTYPE html>
<html>
  <head>
    <title>Dictionary Lookup</title>
  </head>
  <body>
    <input type="text" id="wordInput" placeholder="Enter a word" />
    <button onclick="lookupWord()">Lookup</button>
    <div id="result"></div>

    <script type="module">
      import { DictionaryLookup } from "https://cdn.jsdelivr.net/npm/[email protected]/dist/index.js";

      const dictionary = new DictionaryLookup();

      window.lookupWord = async function () {
        const word = document.getElementById("wordInput").value;
        const result = await dictionary.lookup(word);

        document.getElementById("result").innerHTML = result.found
          ? `<strong>${result.word}</strong> (${result.pos}): ${result.definitions[0]}`
          : `Word "${word}" not found`;
      };
    </script>
  </body>
</html>

Option 2: Self-Hosted (No CDN)

For better performance or privacy, copy dictionary files to your public folder:

# Copy dictionary files to your web server's public folder
mkdir -p public/dictionary
cp node_modules/myna-dictionary/dist/dictionary/* public/dictionary/

Then use the library normally:

<script type="module">
  import { DictionaryLookup } from "./node_modules/myna-dictionary/dist/index.js";

  const dictionary = new DictionaryLookup(); // Automatically detects local files
  const result = await dictionary.lookup("hello");
</script>

Benefits of self-hosting:

✅ Faster loading (no external CDN)
✅ Works offline
✅ No external dependencies
✅ Better privacy

Technical Details

Dictionary Size: 113,376 words
Compression: Built-in text compression reduces storage by ~30%
On-demand Loading: Dictionary shards loaded as needed (not all at once)
Sharding: Dictionary is split into 358 shards for efficient loading
Caching: Intelligent caching system for fast repeated lookups
Browser Loading: Automatic detection of local files or CDN fallback
Package Size: 3.4MB (compressed), 9.5MB (unpacked)
Memory Usage: Only loaded shards consume memory (~40KB per shard)

License

MIT