Plugin Registry Guide
The GLOST plugin registry provides discovery, metadata management, validation, and conflict detection for plugins.
Table of Contents
- Quick Start
- Registering Plugins
- Discovering Plugins
- Validation
- Conflict Detection
- Dependency Resolution
- Statistics
- Best Practices
Quick Start
import { pluginRegistry } from "@glotblocks/glost-registry";
// Register a plugin
pluginRegistry.register(myExtension, {
version: "1.0.0",
description: "My awesome plugin",
category: "enhancer",
tags: ["transcription"],
supports: {
languages: ["th", "ja"],
async: true
}
});
// Search for plugins
const plugins = pluginRegistry.search({ language: "th" });
// Check for conflicts
const report = pluginRegistry.checkConflicts(["plugin1", "plugin2"]);Registering Plugins
Basic Registration
import { pluginRegistry } from "@glotblocks/glost-registry";
pluginRegistry.register(myExtension, {
version: "1.0.0",
description: "Adds transcription support",
category: "enhancer",
tags: ["transcription", "phonetics"],
supports: {
async: true
}
});Complete Metadata
pluginRegistry.register(myExtension, {
// Required
version: "1.0.0",
description: "Comprehensive transcription support",
category: "enhancer",
tags: ["transcription", "ipa", "phonetics"],
supports: {
async: true
},
// Optional
author: "Your Name",
repository: "https://github.com/yourusername/glost-transcription",
homepage: "https://transcription.glost.dev",
// Capabilities
supports: {
languages: ["th", "ja", "ko"],
nodeTypes: ["WordNode", "SentenceNode"],
async: true,
parallel: false,
custom: {
streaming: true,
offline: true
}
},
// Requirements
requires: {
plugins: ["frequency"],
glostVersion: ">=0.4.0",
nodeVersion: ">=18.0.0"
},
// Conflicts
conflicts: ["old-transcription-plugin"],
// Options schema
options: {
type: "object",
properties: {
scheme: {
type: "string",
description: "Transcription scheme to use",
enum: ["ipa", "rtgs", "paiboon"],
default: "ipa"
},
includeStress: {
type: "boolean",
description: "Include stress markers",
default: false
}
},
required: ["scheme"]
},
// Examples
examples: [
{
title: "Basic Usage",
description: "Transcribe with IPA",
code: `
import { glost } from "@glotblocks/glost-processor";
import { transcription } from "@glotblocks/glost-transcription";
const processor = glost()
.use(transcription, { scheme: "ipa" });
`.trim()
}
]
});Plugin Categories
transformer- Modifies document structureenhancer- Adds metadata to existing nodesgenerator- Generates new data/metadataanalyzer- Analyzes document without modificationutility- Utility functions
Discovering Plugins
List All Plugins
const plugins = pluginRegistry.list();
for (const plugin of plugins) {
console.log(plugin.name, plugin.version);
}Search by Keyword
const results = pluginRegistry.search({ keyword: "transcription" });Searches in:
- Plugin name
- Plugin description
- Plugin ID
- Tags
Filter by Category
const enhancers = pluginRegistry.search({ category: "enhancer" });
const transformers = pluginRegistry.search({ category: "transformer" });Filter by Language
const thaiPlugins = pluginRegistry.search({ language: "th" });
const japanesePlugins = pluginRegistry.search({ language: "ja" });Filter by Tags
const results = pluginRegistry.search({
tags: ["transcription", "ipa"]
});Combined Filters
const results = pluginRegistry.search({
keyword: "transcription",
category: "enhancer",
language: "th",
tags: ["ipa"]
});Get by Category
const enhancers = pluginRegistry.getByCategory("enhancer");Get Language Support
const thaiPlugins = pluginRegistry.getLanguageSupport("th");Check Language Support
if (pluginRegistry.isLanguageSupported("transcription", "th")) {
console.log("Transcription supports Thai");
}Validation
Validate Plugin Configuration
const result = pluginRegistry.validate("transcription", {
scheme: "ipa",
includeStress: true
});
if (!result.valid) {
for (const error of result.errors) {
console.error(error.message);
}
}
for (const warning of result.warnings) {
console.warn(warning.message);
}Validation Checks
The validator checks:
- Required options are provided
- Option types match schema
- Unknown options (if not allowed)
- Version requirements
- Dependency availability
Validation Result
interface ValidationResult {
valid: boolean;
errors: ValidationError[];
warnings: ValidationWarning[];
}
interface ValidationError {
plugin: string;
message: string;
code: string;
}Conflict Detection
Check for Conflicts
const report = pluginRegistry.checkConflicts([
"plugin1",
"plugin2",
"plugin3"
]);
if (report.hasConflicts) {
for (const conflict of report.conflicts) {
console.error(`Conflict: ${conflict.plugin1} <-> ${conflict.plugin2}`);
console.error(`Reason: ${conflict.reason}`);
console.error(`Severity: ${conflict.severity}`);
}
}Conflict Types
- Explicit Conflicts - Declared in
conflictsfield - Field Ownership Conflicts - Both plugins provide same fields
Conflict Severity
error- Cannot be used togetherwarning- Can be used but may cause issues
Example
const report = pluginRegistry.checkConflicts([
"new-transcription",
"old-transcription"
]);
// Output:
// {
// hasConflicts: true,
// conflicts: [{
// plugin1: "new-transcription",
// plugin2: "old-transcription",
// reason: "new-transcription declares conflict with old-transcription",
// severity: "error"
// }]
// }Dependency Resolution
Resolve Dependencies
const ordered = pluginRegistry.resolveDependencies([
"plugin-c", // depends on plugin-a
"plugin-a",
"plugin-b" // depends on plugin-a
]);
console.log(ordered);
// ["plugin-a", "plugin-c", "plugin-b"]Handles Circular Dependencies
try {
pluginRegistry.resolveDependencies(["plugin-a", "plugin-b"]);
} catch (error) {
console.error("Circular dependency detected:", error.message);
}Use with Processor
const pluginIds = ["plugin3", "plugin1", "plugin2"];
const ordered = pluginRegistry.resolveDependencies(pluginIds);
let processor = glost();
for (const id of ordered) {
processor = processor.use(id);
}Statistics
Get Statistics
const stats = pluginRegistry.getStatistics();
console.log(`Total plugins: ${stats.total}`);
console.log("By category:", stats.byCategory);
console.log("By language:", stats.byLanguage);
console.log("Top tags:", stats.topTags);Example Output
{
total: 12,
byCategory: {
transformer: 2,
enhancer: 5,
generator: 3,
analyzer: 2,
utility: 0
},
byLanguage: {
th: 8,
ja: 6,
ko: 4,
en: 12
},
topTags: [
{ tag: "transcription", count: 5 },
{ tag: "translation", count: 3 },
{ tag: "frequency", count: 2 }
]
}Advanced Usage
Custom Registry
Create an isolated registry:
import { PluginRegistry } from "@glotblocks/glost-registry";
const myRegistry = new PluginRegistry();
myRegistry.register(plugin1, metadata1);
myRegistry.register(plugin2, metadata2);
const plugins = myRegistry.search({ keyword: "test" });Plugin Discovery Utilities
import { PluginDiscovery } from "@glotblocks/glost-registry";
// Find related plugins
const related = PluginDiscovery.findRelated(
pluginRegistry.list(),
"transcription"
);
// Find plugins that depend on a plugin
const dependents = PluginDiscovery.findDependents(
pluginRegistry.list(),
extensionsMap,
"frequency"
);
// Find missing dependencies
const missing = PluginDiscovery.findMissingDependencies(
pluginRegistry.list(),
extensionsMap
);
// Suggest plugins based on current selection
const suggestions = PluginDiscovery.suggestPlugins(
currentPlugins,
pluginRegistry.list()
);Filtering and Sorting
import { PluginFilter, PluginSorter } from "@glotblocks/glost-registry";
let plugins = pluginRegistry.list();
// Filter
plugins = PluginFilter.byLanguage(plugins, "th");
plugins = PluginFilter.byCategory(plugins, "enhancer");
plugins = PluginFilter.asyncOnly(plugins);
// Sort
plugins = PluginSorter.byName(plugins);
plugins = PluginSorter.byDate(plugins, false); // newest first
plugins = PluginSorter.byCategory(plugins);Custom Validation
import { PluginValidator } from "@glotblocks/glost-registry";
const metadata = pluginRegistry.getMetadata("my-plugin");
// Validate metadata structure
const metaResult = PluginValidator.validateMetadata(metadata);
// Validate compatibility
const compResult = PluginValidator.validateCompatibility(
metadata,
"0.4.0", // GLOST version
"20.0.0" // Node.js version
);
// Validate dependencies
const depResult = PluginValidator.validateDependencies(
metadata,
new Set(["plugin-a", "plugin-b"])
);Best Practices
1. Register Plugins at Application Startup
// In your app initialization
import { pluginRegistry } from "@glotblocks/glost-registry";
import { allPlugins } from "./plugins";
for (const [extension, metadata] of allPlugins) {
pluginRegistry.register(extension, metadata);
}2. Validate Plugin Combinations
function createProcessor(pluginIds: string[]) {
// Validate before creating processor
const report = pluginRegistry.checkConflicts(pluginIds);
if (report.hasConflicts) {
throw new Error(`Plugin conflicts: ${JSON.stringify(report.conflicts)}`);
}
// Resolve dependencies
const ordered = pluginRegistry.resolveDependencies(pluginIds);
// Create processor
let processor = glost();
for (const id of ordered) {
processor = processor.use(id);
}
return processor.freeze();
}3. Use Rich Metadata
Provide complete metadata for better discovery:
pluginRegistry.register(myExtension, {
version: "1.0.0",
description: "Clear, concise description",
category: "enhancer",
tags: ["relevant", "searchable", "tags"],
author: "Your Name",
repository: "https://github.com/...",
homepage: "https://...",
supports: {
languages: ["th", "ja"],
async: true
},
examples: [
{
title: "Basic Usage",
code: "..."
}
]
});4. Check Compatibility
if (pluginRegistry.isCompatible("transcription", "1.0.0")) {
// Use the plugin
}5. Handle Missing Plugins Gracefully
const pluginIds = ["plugin1", "plugin2", "plugin3"];
const available = pluginIds.filter(id => pluginRegistry.has(id));
const missing = pluginIds.filter(id => !pluginRegistry.has(id));
if (missing.length > 0) {
console.warn(`Missing plugins: ${missing.join(", ")}`);
}
// Use only available plugins
let processor = glost();
for (const id of available) {
processor = processor.use(id);
}Integration with CLI
The registry powers the CLI tools:
# List plugins
glost plugins list
# Search
glost plugins search transcription
# Show info
glost plugins info transcription
# Validate
glost plugins validate transcription translation frequency
# Stats
glost plugins statsNext Steps
Last updated on