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
| Package | Description |
|---|---|
@glotblocks/glost-plugins | Core extensions (cultural notes, gender transformer, etc.) |
@glotblocks/glost-frequency | Word frequency data |
@glotblocks/glost-difficulty | Difficulty assessment |
@glotblocks/glost-pos | Part-of-speech tagging |
@glotblocks/glost-transcription | Transcription/romanization |
@glotblocks/glost-translation | Translation data |
@glotblocks/glost-clause-segmenter | Clause segmentation |
Performance Tips
- Batch related extensions - Run related extensions together
- Cache external data - In your provider functions
- Filter before processing - Don’t process unnecessary content
- Use async sparingly - Only when external data is needed
Last updated on