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

# Export only a subset of tables
bunx synset export-sqlite dictionary.db --tables=words,synsets

# 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, synset_examples, word_regions
    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
• synset_examples - example sentences for synsets
• word_regions - per-word region tags ('us' | 'gb' | 'au' | 'ca' | 'scotland'), derived from the WordNet "exemplifies" relation

The CLI accepts --tables=<csv> to export a subset (e.g. --tables=words,synsets). Each requested table's dependencies must also be listed: synsets requires words; word_synsets, sense_relations, and synset_examples require their parents; word_regions requires both words and sense_relations. The command exits with an error naming any missing dependency or unknown table; omit --tables for a full export.

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';

-- All British-English variants
SELECT w.word_display
FROM words w
JOIN word_regions wr ON w.id = wr.word_id
WHERE wr.region = 'gb'
ORDER BY w.word;

Runtime

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

Development

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

Releasing

Releases are manual. The repo encodes the version in commit subjects (e.g. v0.9.8; …) rather than relying on git tags, and publishes to npm from a local checkout.

1. Land the change on main and confirm the Bun workflow is green — it runs bun run verify (typecheck + Biome + tests) on every push.
2. Bump version in package.json (patch for additive/fix, minor for feature batches; the project is still 0.x).
3. Commit with a vX.Y.Z; <summary> subject, lowercase after the prefix:

   git commit -am "v0.9.9; add word_regions, --tables export flag"

4. (Optional) Tag the commit and push:

   git tag v0.9.9
   git push origin main --tags

5. Publish to npm. prepublishOnly runs npm run build (tsup) so the dist/ listed in package.json#files is fresh:

   npm publish

6. (Optional) Cut a GitHub release:

   gh release create v0.9.9 --generate-notes

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)