Skip to Content
DocumentationGuidesUsing Plugins

Using Extensions

This guide covers processing GLOST documents with extensions.

Basic Usage

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

Async Processing

For extensions that fetch external data:

import { processGLOSTWithExtensionsAsync } from '@glotblocks/glost-plugins'; const result = await processGLOSTWithExtensionsAsync(document, [ asyncExtension1, asyncExtension2 ]);

Using Data-Enrichment Extensions

Data-enrichment extensions (frequency, difficulty, etc.) are in separate packages:

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

Extension Registry

Register Extensions

import { registerExtension, registerExtensions, getExtension, getAllExtensions } from '@glotblocks/glost-plugins'; // Register globally registerExtension(myExtension); registerExtensions([ext1, ext2]); // Retrieve const ext = getExtension('my-extension'); const all = getAllExtensions();

Process by ID

import { processGLOSTWithExtensionIds } from '@glotblocks/glost-plugins'; // Process using registered extension IDs const result = processGLOSTWithExtensionIds(document, [ 'cultural-notes', 'gender-transformer' ]);

Extension Dependencies

Extensions can declare dependencies that must run first:

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

Combining Extensions

All at Once

import { processGLOSTWithExtensionsAsync } from '@glotblocks/glost-plugins'; import { CulturalNotesExtension, createGenderTransformerExtension } from '@glotblocks/glost-plugins'; import { createTranscriptionGeneratorExtension } from '@glotblocks/glost-transcription'; import { createFrequencyExtension } from '@glotblocks/glost-frequency'; const genderTransformer = createGenderTransformerExtension({ targetGender: 'female', displayFormat: 'replace' }); const transcription = createTranscriptionGeneratorExtension({ targetLanguage: 'th', provider: myTranscriptionProvider }); const [freqGen, freqEnh] = createFrequencyExtension({ targetLanguage: 'th', provider: myFrequencyProvider }); const result = await processGLOSTWithExtensionsAsync(document, [ transcription, CulturalNotesExtension, genderTransformer, freqGen, freqEnh ]);

In Stages

import { processGLOSTWithExtensionsAsync } from '@glotblocks/glost-plugins'; // Stage 1: Fetch external data const withTranslations = await processGLOSTWithExtensionsAsync(document, [ translationExtension, transcriptionExtension ]); // Stage 2: Analyze structure const withStructure = await processGLOSTWithExtensionsAsync(withTranslations, [ clauseAnalysisExtension ]); // Stage 3: Enrich metadata const final = await processGLOSTWithExtensionsAsync(withStructure, [ freqGen, freqEnh, diffGen, diffEnh ]);

Accessing Enriched Data

import { getAllWords } from '@glotblocks/glost-core'; const words = getAllWords(result); words.forEach(word => { console.log('Text:', word.children[0].value); console.log('Frequency:', word.extras?.frequency); console.log('Difficulty:', word.extras?.difficulty); console.log('Translation:', word.extras?.translations?.en); });

Available Extension Packages

PackageDescription
@glotblocks/glost-pluginsCore extensions (cultural notes, gender transformer, etc.)
@glotblocks/glost-frequencyWord frequency data
@glotblocks/glost-difficultyDifficulty assessment
@glotblocks/glost-posPart-of-speech tagging
@glotblocks/glost-transcriptionTranscription/romanization
@glotblocks/glost-translationTranslation data
@glotblocks/glost-clause-segmenterClause segmentation

Performance Tips

  1. Batch related extensions - Run related extensions together
  2. Cache external data - In your provider functions
  3. Filter before processing - Don’t process unnecessary content
  4. Use async sparingly - Only when external data is needed
Last updated on