Skip to Content

Extension System

GLOST’s extension system allows documents to be enriched with additional metadata and structural transformations.

Overview

Extensions can:

  1. Transform - Modify the document tree structure
  2. Visit - Process specific node types
  3. Enhance - Add metadata to nodes

Extension Interface

interface GLOSTExtension { id: string; // Unique identifier name: string; // Human-readable name description?: string; // Global tree transformation transform?: (tree: GLOSTRoot) => GLOSTRoot | Promise<GLOSTRoot>; // Node-specific visitors visit?: { word?: (node: GLOSTWord) => GLOSTWord | void | Promise<GLOSTWord | void>; sentence?: (node: GLOSTSentence) => GLOSTSentence | void | Promise<GLOSTSentence | void>; paragraph?: (node: GLOSTParagraph) => GLOSTParagraph | void | Promise<GLOSTParagraph | void>; clause?: (node: GLOSTClause) => GLOSTClause | void | Promise<GLOSTClause | void>; }; // Dependencies dependencies?: string[]; // Configuration options?: Record<string, unknown>; }

Processing Pipeline

  1. Registration - Extensions are registered in the registry
  2. Dependency Resolution - Topological sort determines order
  3. Transform Phase - Global tree transformations
  4. Visit Phase - Node-specific modifications
  5. Result - Returns processed document

Using Extensions

Basic Usage

import { processGLOST, type GLOSTExtension } from '@glotblocks/glost-plugins'; const myExtension: GLOSTExtension = { id: 'my-extension', name: 'My Extension', visit: { word: (node) => ({ ...node, extras: { ...node.extras, processed: true } }) } }; const result = processGLOST(document, [myExtension]);

Async Extensions

Extensions that fetch data work with the async processor:

import { processGLOSTWithExtensionsAsync } from '@glotblocks/glost-plugins'; const asyncExtension: GLOSTExtension = { id: 'async-extension', name: 'Async Extension', visit: { word: async (node) => { const data = await fetchExternalData(node); return { ...node, extras: { ...node.extras, data } }; } } }; const result = await processGLOSTWithExtensionsAsync(document, [asyncExtension]);

Extension Registry

import { registerExtension, getExtension, getAllExtensions, processGLOSTWithExtensionIds } from '@glotblocks/glost-plugins'; // Register an extension globally registerExtension(myExtension); // Get by ID const ext = getExtension('my-extension'); // Use registered extensions by ID const result = processGLOSTWithExtensionIds(document, [ 'cultural-notes', 'gender-transformer' ]);

Built-in Extensions

From glost-plugins

These extensions are included in @glotblocks/glost-plugins:

CulturalNotesExtension

Adds cultural context display data.

import { CulturalNotesExtension, createCulturalNotesExtension } from '@glotblocks/glost-plugins'; const result = processGLOST(document, [CulturalNotesExtension]); // Uses extras.metadata.culturalNotes // Adds formatted cultural notes for display

GenderTransformerExtension

Transforms text with gender variants.

import { createGenderTransformerExtension } from '@glotblocks/glost-plugins'; const transformer = createGenderTransformerExtension({ targetGender: 'female', displayFormat: 'replace' // or 'show-both', 'inline-toggle' }); // Input: "Hello {monsieur|madame}" // Output: "Hello madame" (with targetGender: 'female')

NegationTransformerExtension

Marks negated clauses.

import { NegationTransformerExtension } from '@glotblocks/glost-plugins'; // Depends on clause analysis // Adds negation metadata to clauses containing negative words

ReadingScoreExtension

Computes reading difficulty scores.

import { createReadingScoreExtension } from '@glotblocks/glost-plugins'; const scorer = createReadingScoreExtension({ /* options */ });

LearnerHintsExtension

Generates learner hints based on word metadata.

import { createLearnerHintsExtension } from '@glotblocks/glost-plugins'; const hints = createLearnerHintsExtension({ /* options */ });

Separate Extension Packages

Data-enrichment extensions are in separate packages:

PackageDescriptionInstall
@glotblocks/glost-frequencyWord frequency datapnpm add @glotblocks/glost-frequency
@glotblocks/glost-difficultyDifficulty assessmentpnpm add @glotblocks/glost-difficulty
@glotblocks/glost-posPart-of-speech taggingpnpm add @glotblocks/glost-pos
@glotblocks/glost-transcriptionTranscription/romanizationpnpm add @glotblocks/glost-transcription
@glotblocks/glost-translationTranslation datapnpm add @glotblocks/glost-translation
@glotblocks/glost-clause-segmenterClause segmentationpnpm add @glotblocks/glost-clause-segmenter

Example using separate packages:

import { processGLOSTWithExtensionsAsync } from '@glotblocks/glost-plugins'; import { createFrequencyExtension } from '@glotblocks/glost-frequency'; import { createDifficultyExtension } from '@glotblocks/glost-difficulty'; const [freqGen, freqEnh] = createFrequencyExtension({ targetLanguage: 'th', provider: myFrequencyProvider }); const result = await processGLOSTWithExtensionsAsync(document, [freqGen, freqEnh]);

Dependency Resolution

Extensions can declare dependencies:

const myExtension: GLOSTExtension = { id: 'my-extension', name: 'My Extension', dependencies: ['clause-analysis'], // Runs after clause-analysis visit: { clause: (node) => { // Process clauses created by clause-analysis } } };

The processor automatically:

  • Resolves dependencies using topological sort
  • Detects circular dependencies (throws error)
  • Ensures extensions run in correct order

Creating Custom Extensions

See the Creating Custom Extensions guide.

Quick Example

import type { GLOSTExtension } from '@glotblocks/glost-plugins'; const MyExtension: GLOSTExtension = { id: 'my-extension', name: 'My Custom Extension', visit: { word: (node) => { return { ...node, extras: { ...node.extras, myCustomField: computeValue(node) } }; } } }; // Use it import { processGLOST } from '@glotblocks/glost-plugins'; const result = processGLOST(document, [MyExtension]);

Best Practices

  1. Use unique IDs - Avoid conflicts with other extensions
  2. Declare dependencies - Let the system handle ordering
  3. Handle errors gracefully - Failed extensions shouldn’t crash processing
  4. Keep extensions focused - One extension, one responsibility
  5. Use async sparingly - Only when external data is needed
  6. Document your extensions - Describe what they add/transform
Last updated on