Migration Guide: v0.4 to v0.5
This guide helps you migrate from the current GLOST extension API to the new unified-style processor API.
Overview
GLOST v0.5 introduces a unified/remark-style processor API with:
- Fluent
.use()API for plugin composition - Enhanced plugin registry with discovery and validation
- Preset system for common configurations
- CLI tools for plugin management
- Middleware/hooks for observability
Quick Migration
Before (v0.4.x)
import { processGLOSTWithExtensions } from "@glotblocks/glost-plugins";
import { transcriptionExtension } from "@glotblocks/glost-transcription";
import { translationExtension } from "@glotblocks/glost-translation";
import { frequencyExtension } from "@glotblocks/glost-frequency";
const result = processGLOSTWithExtensions(document, [
transcriptionExtension,
translationExtension,
frequencyExtension,
]);
const processed = result.document;After (v0.5.0)
import { glost } from "@glotblocks/glost-processor";
import { transcription } from "@glotblocks/glost-transcription";
import { translation } from "@glotblocks/glost-translation";
import { frequency } from "@glotblocks/glost-frequency";
const result = await glost()
.use(transcription)
.use(translation)
.use(frequency)
.process(document);Key Changes
1. Processor API
Old: Array of Extensions
processGLOSTWithExtensions(doc, [ext1, ext2, ext3]);New: Fluent Chaining
glost()
.use(ext1)
.use(ext2)
.use(ext3)
.process(doc);2. Plugin Format
Plugins can now be:
- Plugin functions (recommended)
export function myPlugin(options?) {
return {
id: "my-plugin",
name: "My Plugin",
transform: (tree) => tree
};
}- Extension objects (backwards compatible)
export const myExtension: GLOSTExtension = {
id: "my-extension",
name: "My Extension",
transform: (tree) => tree
};- String IDs (from registry)
processor.use("my-plugin");3. Async Processing
Old: Two Functions
// Sync
processGLOSTWithExtensions(doc, extensions);
// Async
await processGLOSTWithExtensionsAsync(doc, extensions);New: One Function
// Always async
await processor.process(doc);4. Options
Old: Options in Third Parameter
processGLOSTWithExtensions(doc, extensions, {
lenient: true,
conflictStrategy: "warn"
});New: Options in Constructor
glost({ lenient: true, conflictStrategy: "warn" })
.use(ext1)
.use(ext2)
.process(doc);5. Metadata
Old: Always Returns Metadata
const result = processGLOSTWithExtensions(doc, extensions);
console.log(result.document);
console.log(result.metadata);New: Two Methods
// Just the document
const doc = await processor.process(document);
// With metadata
const result = await processor.processWithMeta(document);
console.log(result.document);
console.log(result.metadata);New Features
1. Presets
Group plugins into reusable configurations:
import { languageLearningPreset } from "@glotblocks/glost-presets";
const processor = glost()
.use(languageLearningPreset);Create custom presets:
const myPreset = {
id: "my-preset",
name: "My Preset",
plugins: [
["transcription", { scheme: "ipa" }],
"translation",
"frequency"
]
};
processor.use(myPreset);2. Hooks and Middleware
Add hooks to observe and modify processing:
processor
.use(transcription)
.use(translation)
.before("translation", (doc) => {
console.log("About to translate");
})
.after("translation", (doc) => {
console.log("Translation complete");
})
.onError((error, plugin) => {
console.error(`Plugin ${plugin} failed:`, error);
})
.onProgress((stats) => {
console.log(`Progress: ${stats.completed}/${stats.total}`);
});3. Data Storage
Share data between plugins:
processor
.data("config", { theme: "dark" })
.use(plugin1)
.use(plugin2);
// Access in plugins
const config = processor.data("config");4. Freezing
Freeze configuration for reuse:
const frozen = glost()
.use(transcription)
.use(translation)
.freeze();
// Reuse across documents
const result1 = await frozen.process(doc1);
const result2 = await frozen.process(doc2);5. Enhanced Registry
Register plugins with rich metadata:
import { pluginRegistry } from "@glotblocks/glost-registry";
pluginRegistry.register(myExtension, {
version: "1.0.0",
description: "My awesome plugin",
category: "enhancer",
tags: ["transcription", "thai"],
supports: {
languages: ["th"],
async: true
},
requires: {
plugins: ["frequency"],
glostVersion: ">=0.4.0"
}
});Search and validate:
// Search
const plugins = pluginRegistry.search({ language: "th" });
// Validate
const report = pluginRegistry.checkConflicts(["plugin1", "plugin2"]);
// Resolve dependencies
const ordered = pluginRegistry.resolveDependencies(["p1", "p2", "p3"]);6. CLI Tools
# List plugins
glost plugins list
# Search
glost plugins search transcription
# Show info
glost plugins info transcription
# Validate combinations
glost plugins validate transcription translation frequency
# Stats
glost plugins stats
# Create template
glost plugins create MyPluginBreaking Changes
1. Async Only
The new processor API is always async. No synchronous processing.
Migration: Add await to all process() calls.
2. Import Paths
Some import paths have changed:
Old
import { processGLOSTWithExtensions } from "@glotblocks/glost-plugins";New
import { glost } from "@glotblocks/glost-processor";3. Plugin Registration
Extensions are now automatically registered when used:
Old
import { registerExtension } from "@glotblocks/glost-plugins";
registerExtension(myExtension);New
// Automatic registration when used
processor.use(myExtension);
// Or explicit registration in enhanced registry
import { pluginRegistry } from "@glotblocks/glost-registry";
pluginRegistry.register(myExtension, metadata);Deprecation Timeline
v0.5 (Current)
- ✅ New processor API available
- ✅ Old API still works (deprecated)
- ⚠️ Deprecation warnings in console
v0.6 (Future)
- ⚠️ Louder deprecation warnings
- 📖 Migration guide prominent in docs
v1.0 (Future)
- ❌ Old API removed
- ✅ Only new processor API supported
Backwards Compatibility
The old API still works in v0.5:
// This still works!
import { processGLOSTWithExtensions } from "@glotblocks/glost-plugins";
const result = processGLOSTWithExtensions(doc, [ext1, ext2]);But you’ll see deprecation warnings:
DeprecationWarning: processGLOSTWithExtensions is deprecated.
Use glost().use(ext1).use(ext2).process(doc) instead.
See migration guide: https://glost.dev/migrationStep-by-Step Migration
Step 1: Install New Packages
pnpm add @glotblocks/glost-processor @glotblocks/glost-registry @glotblocks/glost-presetsStep 2: Update Imports
// Before
import { processGLOSTWithExtensions } from "@glotblocks/glost-plugins";
// After
import { glost } from "@glotblocks/glost-processor";Step 3: Convert to Fluent API
// Before
const result = processGLOSTWithExtensions(doc, [ext1, ext2, ext3]);
// After
const doc = await glost()
.use(ext1)
.use(ext2)
.use(ext3)
.process(document);Step 4: Handle Async
// Before
const result = processGLOSTWithExtensions(doc, extensions);
doSomething(result.document);
// After
const doc = await glost()
.use(ext1)
.use(ext2)
.process(document);
doSomething(doc);Step 5: Update Options
// Before
processGLOSTWithExtensions(doc, extensions, { lenient: true });
// After
glost({ lenient: true })
.use(ext1)
.use(ext2)
.process(doc);Step 6: Use Presets (Optional)
// Before
const result = processGLOSTWithExtensions(doc, [
transcriptionExt,
translationExt,
frequencyExt,
difficultyExt,
posExt
]);
// After - use preset
import { languageLearningPreset } from "@glotblocks/glost-presets";
const doc = await glost()
.use(languageLearningPreset)
.process(document);Common Patterns
Pattern 1: Reusable Processor
Old
function createProcessor(lang: string) {
return (doc: GLOSTRoot) => {
return processGLOSTWithExtensions(doc, [
transcriptionExt,
translationExt
]);
};
}New
function createProcessor(lang: string) {
return glost()
.use(transcription, { language: lang })
.use(translation, { target: "en" })
.freeze();
}
const processor = createProcessor("th");
const result = await processor.process(doc);Pattern 2: Conditional Plugins
Old
const extensions = [transcriptionExt];
if (needsTranslation) {
extensions.push(translationExt);
}
processGLOSTWithExtensions(doc, extensions);New
let processor = glost().use(transcription);
if (needsTranslation) {
processor = processor.use(translation);
}
await processor.process(doc);Pattern 3: Dynamic Plugin Loading
Old
const extensions = pluginIds.map(id => getExtension(id));
processGLOSTWithExtensions(doc, extensions);New
let processor = glost();
for (const id of pluginIds) {
processor = processor.use(id); // Looks up in registry
}
await processor.process(doc);Troubleshooting
Error: “Plugin not found in registry”
Solution: Register the plugin first:
import { pluginRegistry } from "@glotblocks/glost-registry";
pluginRegistry.register(myExtension, metadata);Or use the extension object directly:
processor.use(myExtension);Error: “Cannot modify frozen processor”
Solution: Don’t call .use() after .freeze():
// Wrong
const frozen = processor.freeze();
frozen.use(plugin); // Error!
// Right
processor.use(plugin).freeze();Warning: “Circular dependency detected”
Solution: Check plugin dependencies:
glost plugins validate plugin1 plugin2 plugin3Getting Help
Summary
The new processor API provides:
✅ More intuitive fluent interface
✅ Better TypeScript support
✅ Enhanced plugin discovery
✅ Middleware and hooks
✅ Preset system
✅ CLI tools
✅ Backwards compatible (v0.5)
Take your time migrating. The old API works until v1.0.