josephuspaye / lookup

📖 Lookup definitions and synonyms of words using online sources

Lookup

📖 Lookup definitions and synonyms of words using online sources. Designed for use in Node.js (v10 and above).

This project is part of #CreateWeekly, my attempt to create something new publicly every week in 2020.

How it works

Lookup provides a common interface for looking up definitions and synonyms of words using various online sources. An adapter is used to implement this interface for each source. Currently, the available sources are:

• WordWeb Online

Installation

npm install @josephuspaye/lookup --save

Usage

Look up definitions

The following example looks up definitions of the word "map":

const lookup = require('@josephuspaye/lookup');

async function main() {
  try {
    const { attribution, meanings } = await lookup.definitions('map');
    console.log({ attribution, meanings });
  } catch (error) {
    console.log('unable to look up definitions', error);
  }
}

main();

And yields the following output when ran:

View output

{
  "attribution": "Definitions from WordWeb Online",
  "meanings": [
    {
      "word": "map",
      "partOfSpeech": "noun",
      "forms": [],
      "pronunciation": {
        "text": "map",
        "key": "/a/ fat"
      },
      "usage": [],
      "definitions": [
        {
          "definition": "A diagrammatic representation of the earth's surface (or part of it)",
          "examples": [],
          "synonyms": []
        },
        {
          "definition": "(mathematics) a mathematical relation such that each element of a given set (the domain of the function) is associated with an element of another set (the range of the function)",
          "examples": [],
          "synonyms": [
            "function",
            "mathematical function",
            "single-valued function",
            "mapping"
          ]
        }
      ]
    },
    {
      "word": "map",
      "partOfSpeech": "verb",
      "forms": [
        "mapped",
        "mapping"
      ],
      "pronunciation": {
        "text": "map",
        "key": "/a/ fat"
      },
      "usage": [],
      "definitions": [
        {
          "definition": "Make a map of; show or establish the features or details of",
          "examples": [
            "map the surface of Venus"
          ],
          "synonyms": []
        },
        {
          "definition": "Explore or survey for the purpose of making a map",
          "examples": [
            "We haven't even begun to map the many galaxies that we know exist"
          ],
          "synonyms": []
        },
        {
          "definition": "Locate within a specific region of a chromosome in relation to known DNA or gene sequences",
          "examples": [
            "map the genes"
          ],
          "synonyms": []
        },
        {
          "definition": "Plan, delineate, or arrange in detail",
          "examples": [
            "map one's future"
          ],
          "synonyms": [
            "map out"
          ]
        },
        {
          "definition": "Depict as if on a map",
          "examples": [
            "sorrow was mapped on the mother's face"
          ],
          "synonyms": []
        },
        {
          "definition": "To establish a mapping (of mathematical elements or sets)",
          "examples": [],
          "synonyms": [
            "represent"
          ]
        }
      ]
    }
  ]
}

Look up related words

When looking up definitions, you can choose to include related words in the following categories:

• soundsLike
• derivedForms
• seeAlso
• typeOf
• partOf
• antonyms
• nearest

The following example finds derivedForms, typeOf, and nearest relations for the word "fiction":

const lookup = require('@josephuspaye/lookup');

async function main() {
  try {
    const { derivedForms, typeOf, nearest } = await lookup.definitions(
      'fiction',
      {
        includeRelated: ['derivedForms', 'typeOf', 'nearest'],
      }
    );
    console.log({ derivedForms, typeOf, nearest });
  } catch (error) {
    console.log('unable to look up related words', error);
  }
}

main();

And yields the following output when ran:

View output

{
  "derivedForms": [
    "fictions"
  ],
  "typeOf": [
    "creative thinking",
    "creativeness",
    "creativity",
    "falsehood",
    "falsity",
    "literary composition",
    "literary work",
    "untruth"
  ],
  "nearest": {
    "before": [
      "fibular",
      "fibular vein",
      "FICA",
      "fice",
      "fiche",
      "fichu",
      "fickle",
      "fickleness",
      "fico",
      "fictile"
    ],
    "after": [
      "fictional",
      "fictional animal",
      "fictional character",
      "fictionalisation",
      "fictionalise",
      "fictionalization",
      "fictionalize",
      "fictitious",
      "fictitious character",
      "fictitious name"
    ]
  }
}

Look up synonyms

The following example looks up synonyms of the word "reticent":

const lookup = require('@josephuspaye/lookup');

async function main() {
  try {
    const { attribution, synonyms } = await lookup.synonyms('reticent');
    console.log({ attribution, synonyms });
  } catch (error) {
    console.log('unable to look up synonyms', error);
  }
}

main();

And yields the following output when ran:

View output

{
  attribution: 'Definitions from WordWeb Online',
  synonyms: [
    {
      definition: 'Temperamentally disinclined to talk',
      partOfSpeech: 'adjective',
      synonym: 'untalkative',
      word: 'reticent'
    },
    {
      definition: 'Cool and formal in manner',
      partOfSpeech: 'adjective',
      synonym: 'restrained',
      word: 'reticent'
    },
    {
      definition: 'Cool and formal in manner',
      partOfSpeech: 'adjective',
      synonym: 'unemotional',
      word: 'reticent'
    },
    {
      definition: 'Reluctant to draw attention to yourself',
      partOfSpeech: 'adjective',
      synonym: 'self-effacing',
      word: 'reticent'
    },
    {
      definition: 'Reluctant to draw attention to yourself',
      partOfSpeech: 'adjective',
      synonym: 'retiring',
      word: 'reticent'
    }
  ]
}

API

lookup.definitions()

Look up definitions and words related to the given word. Will throw on errors. See below for type definitions and errors.

async function definitions(
  word: string,
  options?: {
    language?: Lookup.Language;
    source?: Lookup.Source;
    includeRelated?: Lookup.Related[];
  }
): Promise<Lookup.DefinitionsResult>;

lookup.synonyms()

Look up synonyms of the given word. Will throw on errors. See below for type definitions and errors.

async function synonyms(
  word: string,
  options: {
    language?: Lookup.Language;
    source?: Lookup.Source;
  }
): Promise<Lookup.SynonymsResult>;

Types

The following types are used for parameters and return values.

namespace Lookup {
  /**
   * The sources available for looking up words.
   */
  type Source = 'wordWebOnline';

  /**
   * Types of related words
   */
  type Related =
    | 'soundsLike'
    | 'derivedForms'
    | 'seeAlso'
    | 'typeOf'
    | 'partOf'
    | 'antonyms'
    | 'nearest';

  /**
   * The available languages
   */
  type Language = 'en';

  /**
   * A definition
   */
  interface Definition {
    /**
     * The definition text
     */
    definition: string;

    /**
     * Zero or more examples of the definition
     */
    examples: string[];

    /**
     * Zero or more synonyms of the word matching the definition
     */
    synonyms: string[];
  }

  /**
   * A meaning (sense). One word can have multiple meanings,
   * and each meaning can have multiple definitions.
   */
  interface Meaning {
    /**
     * The word with this meaning
     */
    word: string;

    /**
     * The part of speech of the word with this meaning
     */
    partOfSpeech: string;

    /**
     * For verbs, the forms (e.g. present, past, present progressive, etc)
     */
    forms: string[];

    /**
     * The pronunciation for this meaning
     */
    pronunciation?: {
      /**
       * The pronunciation text
       */
      text: string;

      /**
       * The pronunciation key
       */
      key?: string;

      /**
       * URL to an audio file with the pronunciation
       */
      audioUrl?: string;
    };

    /**
     * The word's usage, e.g. ['vulgar'], ['archiac'], ['Brit', 'Cdn'], etc.
     * An empty array indicates the word has no special usage, or its usage is universal.
     */
    usage: string[];

    /**
     * Alternative usage of the word if any. E.g. for 'colour', alternative usage is:
     * `{ where: 'US', word: 'color' }`
     */
    usageAlternative?: {
      where: string;
      word: string;
    };

    /**
     * The definitions of the word with this meaning
     */
    definitions: Definition[];
  }

  /**
   * A definition result
   */
  interface DefinitionsResult {
    /**
     * Attribution for where the definitions are from
     */
    attribution: string;

    /**
     * The meanings found for the given word
     */
    meanings: Meaning[];

    /**
     * Zero or more words that sound like the given word
     */

    soundsLike: string[];

    /**
     * Derived forms of the given word (e.g. tenses)
     */
    derivedForms: string[];

    /**
     * Zero or more words that are similar to the given word
     */
    seeAlso: string[];

    /**
     * Zero or more words that the given words is a semantic type of
     */
    typeOf: string[];

    /**
     * Zero or more words that the given word is a semantic part of
     */
    partOf: string[];

    /**
     * Zero or more words that are antonyms of the given word
     */
    antonyms: string[];

    /**
     * Words nearest to the given word in the database
     */
    nearest: {
      /**
       * Zero or more words that appear immediately before the given word in the databse
       */
      before: string[];

      /**
       * Zero or more words that appear immediately after the given word in the databse
       */
      after: string[];
    };
  }

  /**
   * A synonym result
   */
  interface Synonym {
    /**
     * The synonym
     */
    synonym: string;

    /**
     * The word with this synonym
     */
    word: string;

    /**
     * The part of speech of the word with this synonym
     */
    partOfSpeech: string;

    /**
     * The definition of the word matching this synonym
     */
    definition: string;
  }

  interface SynonymsResult {
    /**
     * Attribution for where the definitions are from
     */
    attribution: string;

    /**
     * The synonyms found for the given word
     */
    synonyms: Synonym[];
  }
}

Errors

lookup.definitions() and lookup.synonyms() may throw errors matching the following interface:

/**
 * A look up error.
 */
interface Error {
  type: ErrorType;
  message: string;
  originalError?: any;
}

Where type is a member of the following enum:

/**
 * The errors that could occur when looking up words.
 */
enum ErrorType {
  /**
   * The given word is empty
   */
  'WORD_EMPTY',

  /**
   * Request to the source website failed
   */
  'SOURCE_REQUEST_FAILED',

  /**
   * The given source was not recognized
   */
  'UNKNOWN_SOURCE',

  /**
   * The given word was not found on the source page: perhaps the page format changed
   */
  'NOT_FOUND',

  /**
   * Unable to extract the definitions or synonyms from the source page
   */
  'EXTRACTION_FAILED',
}

Licence

MIT

lookup's Issues

Fix definitions for meanings without a pronounciation key

When a meaning has no pronunciation key, the list of definitions is the 2nd sibling away from the head, instead of the 4th.

For example, the compound word "rap music" has no pronounciation key:

Fix definitions for meanings marked "archaic"

When a meaning is marked "archiac", a new DOM node is added between the heading and the list of definitions, which throws off the parser.

For example, the word fable as a verb meaning which is marked as archaic: