Skip to Content
DocumentationPackages@glotblocks/glost-plugins

glost-plugins

Core extension system for GLOST document processing.

Installation

pnpm add @glotblocks/glost-plugins

Overview

@glotblocks/glost-plugins provides the core extension infrastructure:

  • Extension processing functions
  • Extension registry for managing extensions
  • Built-in extensions for common transformations
  • Type definitions for creating custom extensions

Individual data-enrichment extensions (frequency, difficulty, POS, etc.) are in separate packages.

Processing with Extensions

import { processGLOST, type GLOSTExtension } from '@glotblocks/glost-plugins'; // Define a custom extension 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

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

Extension Registry

Global Registry

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

Using Registered Extensions

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

Built-in Extensions

CulturalNotesExtension

Formats cultural notes for display.

import { CulturalNotesExtension, createCulturalNotesExtension } from '@glotblocks/glost-plugins'; // Use default const result = processGLOST(document, [CulturalNotesExtension]); // Or create with options const customExtension = createCulturalNotesExtension({ // options });

Expects: extras.metadata.culturalNotes on words Adds: Formatted cultural notes display data

GenderTransformerExtension

Transforms text with gender variants.

import { createGenderTransformerExtension } from '@glotblocks/glost-plugins'; const transformer = createGenderTransformerExtension({ targetGender: 'female', // 'male' | 'female' displayFormat: 'replace' // 'replace' | 'show-both' | 'inline-toggle' });

Input format: "{masculine|feminine}" in text Output: Based on targetGender and displayFormat

NegationTransformerExtension

Marks clauses containing negation.

import { NegationTransformerExtension } from '@glotblocks/glost-plugins';

Dependencies: Clause analysis (must run first) Adds: Negation metadata to clauses

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 });

ClauseAnalysisExtension

Analyzes clause structure in sentences.

import { createClauseAnalysisExtension } from '@glotblocks/glost-plugins'; const analyzer = createClauseAnalysisExtension({ // 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-genderGrammatical genderpnpm add @glotblocks/glost-gender
@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 [diffGen, diffEnh] = createDifficultyExtension({ targetLanguage: 'th', provider: myDifficultyProvider }); const result = await processGLOSTWithExtensionsAsync(document, [ freqGen, freqEnh, diffGen, diffEnh ]);

Extension Interface

interface GLOSTExtension { id: string; name: string; description?: string; // Tree transformation (runs once) transform?: (tree: GLOSTRoot) => GLOSTRoot | Promise<GLOSTRoot>; // Node visitors (runs for each matching node) 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>; phrase?: (node: GLOSTPhrase) => GLOSTPhrase | void | Promise<GLOSTPhrase | void>; }; // Extension dependencies (IDs of extensions that must run first) dependencies?: string[]; // Extension options options?: Record<string, unknown>; }

Creating Custom Extensions

Visitor Pattern

import type { GLOSTExtension } from '@glotblocks/glost-plugins'; const MyVisitorExtension: GLOSTExtension = { id: 'my-visitor', name: 'My Visitor Extension', visit: { word: (node) => { // Return modified node or void return { ...node, extras: { ...node.extras, processed: true } }; }, sentence: (node) => { // Process sentences } } };

Transform Pattern

const MyTransformExtension: GLOSTExtension = { id: 'my-transform', name: 'My Transform Extension', transform: (tree) => { // Return completely new tree structure return modifyTree(tree); } };

Async Pattern

const MyAsyncExtension: GLOSTExtension = { id: 'my-async', name: 'My Async Extension', visit: { word: async (node) => { const data = await fetchExternalData(node); return { ...node, extras: { ...node.extras, externalData: data } }; } } };

With Dependencies

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

Exports

Types

export type { GLOSTExtension, ExtensionContext, ExtensionResult, ProcessorOptions, } from '@glotblocks/glost-plugins';

Processor Functions

export { processGLOSTWithExtensions, processGLOSTWithExtensionsAsync, processGLOSTWithExtensionIds, processGLOST, processGLOSTWithMeta, } from '@glotblocks/glost-plugins';

Registry

export { extensionRegistry, registerExtension, registerExtensions, getExtension, getAllExtensions, } from '@glotblocks/glost-plugins';

Utilities

export { deepMerge, findConflicts, type DeepMergeOptions } from '@glotblocks/glost-plugins';

Errors

export { ExtensionDependencyError, ExtensionConflictError, MissingNodeTypeError, } from '@glotblocks/glost-plugins';
Last updated on