Extension System
GLOST’s extension system allows documents to be enriched with additional metadata and structural transformations.
Overview
Extensions can:
- Transform - Modify the document tree structure
- Visit - Process specific node types
- 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
- Registration - Extensions are registered in the registry
- Dependency Resolution - Topological sort determines order
- Transform Phase - Global tree transformations
- Visit Phase - Node-specific modifications
- 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 displayGenderTransformerExtension
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 wordsReadingScoreExtension
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:
| Package | Description | Install |
|---|---|---|
@glotblocks/glost-frequency | Word frequency data | pnpm add @glotblocks/glost-frequency |
@glotblocks/glost-difficulty | Difficulty assessment | pnpm add @glotblocks/glost-difficulty |
@glotblocks/glost-pos | Part-of-speech tagging | pnpm add @glotblocks/glost-pos |
@glotblocks/glost-transcription | Transcription/romanization | pnpm add @glotblocks/glost-transcription |
@glotblocks/glost-translation | Translation data | pnpm add @glotblocks/glost-translation |
@glotblocks/glost-clause-segmenter | Clause segmentation | pnpm 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
- Use unique IDs - Avoid conflicts with other extensions
- Declare dependencies - Let the system handle ordering
- Handle errors gracefully - Failed extensions shouldn’t crash processing
- Keep extensions focused - One extension, one responsibility
- Use async sparingly - Only when external data is needed
- Document your extensions - Describe what they add/transform
Last updated on