synset

WordNet dictionary parser with Zod validation, query utilities, and CLI.

Usage

CLI

# Run without installing
bunx synset define dog

# List synonyms
bunx synset synonyms happy

# Show hypernyms (more general terms)
bunx synset hypernyms dog

# Show all relations
bunx synset related computer

# Pre-download WordNet data
bunx synset fetch

# Export to SQLite database
bunx synset export-sqlite dictionary.db

# Use local file instead of cache
bunx synset define dog --file ./path/to/english-wordnet-{YEAR}.xml

Or install globally:

bun install -g synset
synset define dog

Library

npm install synset
# or
bun add synset

import {
  fetchWordNet,
  loadWordNet,
  buildIndex,
  getDefinitions,
  getSynonyms,
  getHypernyms,
  findSynsets,
} from 'synset'

// Fetch WordNet data (auto-discovers latest version, downloads & caches ~100MB XML)
const { lexicon, version } = await fetchWordNet()
console.log(`Loaded WordNet ${version}`)

// Or load from local file
const lexicon = await loadWordNet('./path/to/english-wordnet-{YEAR}.xml')

// Build index for fast lookups
const index = buildIndex(lexicon)

// Query
getDefinitions(index, 'dog')
// [{ text: "a member of the genus Canis...", synset, partOfSpeech: "n" }, ...]

getSynonyms(index, 'happy')
// [{ word: "glad", entry, synset }, ...]

getHypernyms(index, 'dog')
// [Synset for "canine", Synset for "domestic animal", ...]

findSynsets(index, 'bank')
// [Synset for "financial institution", Synset for "river bank", ...]

SQLite Export

import { exportToSQLite } from 'synset'

// Export to SQLite
exportToSQLite(lexicon, 'dictionary.db', {
  onProgress: ({ phase, current, total }) => {
    // phases: words, synsets, word_synsets, synset_relations, sense_relations
    console.log(`${phase}: ${current}/${total}`)
  }
})

Schema is available as:

• import { SCHEMA } from 'synset' - SQL string constant
• synset/schema.sql - standalone file via package exports

Tables:

• words - unique words with display form
• synsets - definitions with part of speech
• word_synsets - word → synset mappings
• synset_relations - hypernym, hyponym, meronym, etc. links between synsets
• sense_relations - antonym, derivation, pertainym, etc. links between word senses

Example queries:

-- Hypernyms via synset relations (dog → canine, domestic animal)
SELECT w2.word_display, s2.definition
FROM words w
JOIN word_synsets ws ON w.id = ws.word_id
JOIN synset_relations sr ON ws.synset_id = sr.source_id
JOIN synsets s2 ON sr.target_id = s2.id
JOIN word_synsets ws2 ON s2.id = ws2.synset_id
JOIN words w2 ON ws2.word_id = w2.id
WHERE w.word = 'dog' AND sr.rel_type = 'hypernym';

-- Antonyms via sense relations (happy → unhappy)
SELECT w2.word_display, s2.definition
FROM words w
JOIN sense_relations sr ON w.id = sr.source_word_id
JOIN words w2 ON sr.target_word_id = w2.id
JOIN synsets s2 ON sr.target_synset_id = s2.id
WHERE w.word = 'happy' AND sr.rel_type = 'antonym';

Runtime

• Bun: Full support
• Node.js 18+: Full support

Development

bun install
bun test
bun run check  # typecheck
bun run build  # build dist/

Dictionary Module

• WordNet
  • Format:
    • https://globalwordnet.github.io/schemas/
      • XML file source:
        • https://github.com/globalwordnet/english-wordnet
          • Latest version auto-discovered and downloaded by tests
        • XML format: DTD
          • Manually copied over to
            • WN-LMF-1.3.dtd

WordNet XML Source Structure

(Originally created with xmlstarlet against the 2023 xml file).

$ xmlstarlet el data/english-wordnet-2023.xml | sort | uniq | sort (with unicode symbols added manually)

📂 LexicalResource               root node
   📂 Lexicon                    desc of the database: id prefix, language, version, ...
      📂 LexicalEntry            an id for grouping children that can be refed by a Synset.
         📄 Form
         📂 Lemma
            📄 Pronunciation
         📂 Sense
            📄 SenseRelation
      📂 Synset
         📄 Definition
         📄 Example
         📄 ILIDefinition
         📄 SynsetRelation
      📄 SyntacticBehaviour

Schema Verification

Stats accumulated with:

• $ xmlstarlet el data/english-wordnet-2023.xml | sort | uniq -c | sort -n
• $ grep -oE '<[A-Za-z]+' data/english-wordnet-2024.xml | sed 's/<//g' | sort | uniq -c | sort -n

Element counts comparison (schema unchanged between releases):

| Element | 2023 | 2024 | | ------------------ | -----: | -----: | | LexicalResource | 1 | 1 | | Lexicon | 1 | 1 | | SyntacticBehaviour | 39 | 39 | | ILIDefinition | 2700 | 3216 | | Form | 4474 | 4474 | | Pronunciation | 44671 | 44669 | | Example | 49638 | 49723 | | Synset | 120135 | 120630 | | Definition | 120141 | 120635 | | SenseRelation | 122041 | 122018 | | LexicalEntry | 161338 | 161705 | | Lemma | 161338 | 161705 | | Sense | 212071 | 212478 | | SynsetRelation | 293864 | 297150 |

Zod Test Coverage

📂 LexicalResource                  [-] (basic test for a parent)
   📂 Lexicon                       [-] (basic test for a parent)
      📂 LexicalEntry               [x]
         📄 Form                    [x]
         📂 Lemma                   [x]
            📄 Pronunciation        [x]
         📂 Sense                   [x]
            📄 SenseRelation        [x]
      📂 Synset                     [x]
         📄 Definition              [x]
         📄 Example                 [x]
         📄 ILIDefinition           [x]
         📄 SynsetRelation          [x]
      📄 SyntacticBehaviour         [x]

TODO

• [ ] Support Open English Namenet - proper nouns (people, places, etc.) were moved to a separate resource starting with 2025 release
• [ ] Option to fetch "2025+" edition which includes curated proper nouns from Namenet
• [ ] CLI --json flag for JSON output
• [ ] CLI colored output (disable with --no-color)