glost-processor 0.7.0 → 1.0.2

package/src/processor.js

@@ -0,0 +1,482 @@
+/**
+ * GLOST Processor
+ *
+ * Unified-style processor for GLOST documents with fluent API.
+ * Similar to unified/remark processors.
+ *
+ * @packageDocumentation
+ */
+import { processGLOSTWithExtensionsAsync, extensionRegistry } from "glost-extensions";
+/**
+ * GLOST Processor
+ *
+ * Fluent API for processing GLOST documents through plugin pipelines.
+ *
+ * @example
+ * ```typescript
+ * import { GLOSTProcessor } from "glost-processor";
+ *
+ * const processor = new GLOSTProcessor()
+ *   .use(transcription, { scheme: "ipa" })
+ *   .use(translation, { target: "en" })
+ *   .use(frequency);
+ *
+ * const result = await processor.process(document);
+ * ```
+ */
+export class GLOSTProcessor {
+    plugins = [];
+    hooks = {
+        before: new Map(),
+        after: new Map(),
+        onError: [],
+        onSkip: [],
+        onProgress: [],
+    };
+    dataStore = new Map();
+    options = {};
+    frozen = false;
+    /**
+     * Create a new processor instance
+     *
+     * @param options - Initial processor options
+     */
+    constructor(options = {}) {
+        this.options = { ...options };
+        if (options.data) {
+            this.dataStore = new Map(options.data);
+        }
+    }
+    /**
+     * Use a plugin, preset, or extension
+     *
+     * @param spec - Plugin function, extension object, preset, or plugin ID
+     * @param options - Plugin options
+     * @returns This processor for chaining
+     *
+     * @example
+     * ```typescript
+     * processor
+     *   .use(transcription, { scheme: "ipa" })
+     *   .use(translation)
+     *   .use("frequency");
+     * ```
+     */
+    use(spec, options) {
+        this.assertNotFrozen();
+        // Handle presets
+        if (this.isPreset(spec)) {
+            return this.usePreset(spec);
+        }
+        // Add plugin to pipeline
+        this.plugins.push({ spec, options });
+        return this;
+    }
+    /**
+     * Apply a preset (collection of plugins)
+     *
+     * @param preset - Preset to apply
+     * @returns This processor for chaining
+     */
+    usePreset(preset) {
+        for (const pluginEntry of preset.plugins) {
+            if (Array.isArray(pluginEntry)) {
+                const [plugin, opts] = pluginEntry;
+                this.use(plugin, opts);
+            }
+            else {
+                this.use(pluginEntry);
+            }
+        }
+        return this;
+    }
+    /**
+     * Register a hook to run before a plugin
+     *
+     * @param pluginId - Plugin ID to hook into
+     * @param hook - Hook function to run
+     * @returns This processor for chaining
+     *
+     * @example
+     * ```typescript
+     * processor.before("translation", (doc) => {
+     *   console.log("About to translate");
+     * });
+     * ```
+     */
+    before(pluginId, hook) {
+        this.assertNotFrozen();
+        if (!this.hooks.before.has(pluginId)) {
+            this.hooks.before.set(pluginId, []);
+        }
+        this.hooks.before.get(pluginId).push(hook);
+        return this;
+    }
+    /**
+     * Register a hook to run after a plugin
+     *
+     * @param pluginId - Plugin ID to hook into
+     * @param hook - Hook function to run
+     * @returns This processor for chaining
+     *
+     * @example
+     * ```typescript
+     * processor.after("translation", (doc) => {
+     *   console.log("Translation complete");
+     * });
+     * ```
+     */
+    after(pluginId, hook) {
+        this.assertNotFrozen();
+        if (!this.hooks.after.has(pluginId)) {
+            this.hooks.after.set(pluginId, []);
+        }
+        this.hooks.after.get(pluginId).push(hook);
+        return this;
+    }
+    /**
+     * Register an error handler
+     *
+     * @param hook - Error handler function
+     * @returns This processor for chaining
+     *
+     * @example
+     * ```typescript
+     * processor.onError((error, plugin) => {
+     *   console.error(`Plugin ${plugin} failed:`, error);
+     * });
+     * ```
+     */
+    onError(hook) {
+        this.assertNotFrozen();
+        this.hooks.onError.push(hook);
+        return this;
+    }
+    /**
+     * Register a skip handler
+     *
+     * @param hook - Skip handler function
+     * @returns This processor for chaining
+     *
+     * @example
+     * ```typescript
+     * processor.onSkip((plugin, reason) => {
+     *   console.log(`Plugin ${plugin} skipped: ${reason}`);
+     * });
+     * ```
+     */
+    onSkip(hook) {
+        this.assertNotFrozen();
+        this.hooks.onSkip.push(hook);
+        return this;
+    }
+    /**
+     * Register a progress handler
+     *
+     * @param hook - Progress handler function
+     * @returns This processor for chaining
+     *
+     * @example
+     * ```typescript
+     * processor.onProgress((stats) => {
+     *   console.log(`Progress: ${stats.completed}/${stats.total}`);
+     * });
+     * ```
+     */
+    onProgress(hook) {
+        this.assertNotFrozen();
+        this.hooks.onProgress.push(hook);
+        return this;
+    }
+    data(key, value) {
+        if (arguments.length === 1) {
+            return this.dataStore.get(key);
+        }
+        this.assertNotFrozen();
+        this.dataStore.set(key, value);
+        return this;
+    }
+    /**
+     * Freeze the processor
+     *
+     * Returns a frozen processor that cannot be modified.
+     * Useful for reusing the same configuration across multiple documents.
+     *
+     * @returns A frozen copy of this processor
+     *
+     * @example
+     * ```typescript
+     * const frozen = processor
+     *   .use(transcription)
+     *   .use(translation)
+     *   .freeze();
+     *
+     * // Can process multiple documents with the same pipeline
+     * const result1 = await frozen.process(doc1);
+     * const result2 = await frozen.process(doc2);
+     * ```
+     */
+    freeze() {
+        const frozen = new GLOSTProcessor(this.options);
+        frozen.plugins = [...this.plugins];
+        frozen.hooks = {
+            before: new Map(this.hooks.before),
+            after: new Map(this.hooks.after),
+            onError: [...this.hooks.onError],
+            onSkip: [...this.hooks.onSkip],
+            onProgress: [...this.hooks.onProgress],
+        };
+        frozen.dataStore = new Map(this.dataStore);
+        frozen.frozen = true;
+        return frozen;
+    }
+    /**
+     * Process a document through the pipeline
+     *
+     * @param document - GLOST document to process
+     * @returns Promise resolving to the processed document
+     *
+     * @example
+     * ```typescript
+     * const result = await processor.process(document);
+     * console.log(result);
+     * ```
+     */
+    async process(document) {
+        const result = await this.processWithMeta(document);
+        return result.document;
+    }
+    /**
+     * Process a document and return detailed metadata
+     *
+     * @param document - GLOST document to process
+     * @returns Promise resolving to processing result with metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await processor.processWithMeta(document);
+     * console.log(result.metadata.appliedPlugins);
+     * console.log(result.metadata.stats.totalTime);
+     * ```
+     */
+    async processWithMeta(document) {
+        const startTime = Date.now();
+        const extensions = await this.resolveExtensions();
+        const timing = new Map();
+        const errors = [];
+        const warnings = [];
+        const appliedPlugins = [];
+        const skippedPlugins = [];
+        // Emit initial progress
+        this.emitProgress({
+            total: extensions.length,
+            completed: 0,
+            startTime,
+            elapsed: 0,
+        });
+        // Process extensions with hooks
+        let processedDoc = document;
+        for (let i = 0; i < extensions.length; i++) {
+            const extension = extensions[i];
+            const pluginStart = Date.now();
+            try {
+                // Run before hooks
+                await this.runBeforeHooks(processedDoc, extension.id);
+                // Process with this extension
+                const { data: _, ...extensionOptions } = this.options;
+                const result = await processGLOSTWithExtensionsAsync(processedDoc, [extension], extensionOptions);
+                processedDoc = result.document;
+                // Check for errors/skips
+                if (result.metadata.errors.length > 0) {
+                    for (const err of result.metadata.errors) {
+                        errors.push({
+                            plugin: extension.id,
+                            phase: "transform",
+                            message: err.error.message,
+                            stack: err.error.stack,
+                            recoverable: true,
+                            error: err.error,
+                        });
+                    }
+                }
+                if (result.metadata.skippedExtensions.includes(extension.id)) {
+                    skippedPlugins.push(extension.id);
+                    this.emitSkip(extension.id, "Skipped by processor");
+                }
+                else {
+                    appliedPlugins.push(extension.id);
+                }
+                // Run after hooks
+                await this.runAfterHooks(processedDoc, extension.id);
+                // Record timing
+                timing.set(extension.id, Date.now() - pluginStart);
+                // Emit progress
+                this.emitProgress({
+                    total: extensions.length,
+                    completed: i + 1,
+                    current: extension.id,
+                    startTime,
+                    elapsed: Date.now() - startTime,
+                });
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                errors.push({
+                    plugin: extension.id,
+                    phase: "transform",
+                    message: err.message,
+                    stack: err.stack,
+                    recoverable: false,
+                    error: err,
+                });
+                skippedPlugins.push(extension.id);
+                this.emitError(err, extension.id);
+                this.emitSkip(extension.id, err.message);
+                // Re-throw in strict mode
+                if (!this.options.lenient) {
+                    throw err;
+                }
+            }
+        }
+        const endTime = Date.now();
+        return {
+            document: processedDoc,
+            metadata: {
+                appliedPlugins,
+                skippedPlugins,
+                errors,
+                warnings,
+                stats: {
+                    totalTime: endTime - startTime,
+                    timing,
+                    nodesProcessed: 0, // Could be calculated by visiting the tree
+                    startTime,
+                    endTime,
+                },
+            },
+        };
+    }
+    /**
+     * Process a document synchronously (only if all plugins are sync)
+     *
+     * @param document - GLOST document to process
+     * @returns The processed document
+     * @throws {Error} If any plugin is async
+     *
+     * @example
+     * ```typescript
+     * const result = processor.processSync(document);
+     * ```
+     */
+    processSync(document) {
+        throw new Error("Synchronous processing not yet implemented. Use process() instead.");
+    }
+    /**
+     * Resolve all plugins to extensions
+     */
+    async resolveExtensions() {
+        const extensions = [];
+        for (const { spec, options } of this.plugins) {
+            const extension = await this.resolvePlugin(spec, options);
+            if (extension) {
+                extensions.push(extension);
+            }
+        }
+        return extensions;
+    }
+    /**
+     * Resolve a single plugin to an extension
+     */
+    async resolvePlugin(spec, options) {
+        // String ID - lookup in registry
+        if (typeof spec === "string") {
+            const ext = extensionRegistry.get(spec);
+            if (!ext) {
+                throw new Error(`Plugin "${spec}" not found in registry`);
+            }
+            return ext;
+        }
+        // Function - call to get extension
+        if (typeof spec === "function") {
+            const result = spec(options);
+            return result || null;
+        }
+        // Extension object - use directly
+        return spec;
+    }
+    /**
+     * Check if a spec is a preset
+     */
+    isPreset(spec) {
+        return (spec &&
+            typeof spec === "object" &&
+            "plugins" in spec &&
+            Array.isArray(spec.plugins));
+    }
+    /**
+     * Run before hooks for a plugin
+     */
+    async runBeforeHooks(document, pluginId) {
+        const hooks = this.hooks.before.get(pluginId) || [];
+        for (const hook of hooks) {
+            await hook(document, pluginId);
+        }
+    }
+    /**
+     * Run after hooks for a plugin
+     */
+    async runAfterHooks(document, pluginId) {
+        const hooks = this.hooks.after.get(pluginId) || [];
+        for (const hook of hooks) {
+            await hook(document, pluginId);
+        }
+    }
+    /**
+     * Emit error to error handlers
+     */
+    emitError(error, pluginId) {
+        for (const hook of this.hooks.onError) {
+            try {
+                hook(error, pluginId);
+            }
+            catch (err) {
+                console.error("Error in error hook:", err);
+            }
+        }
+    }
+    /**
+     * Emit skip to skip handlers
+     */
+    emitSkip(pluginId, reason) {
+        for (const hook of this.hooks.onSkip) {
+            try {
+                hook(pluginId, reason);
+            }
+            catch (err) {
+                console.error("Error in skip hook:", err);
+            }
+        }
+    }
+    /**
+     * Emit progress to progress handlers
+     */
+    emitProgress(stats) {
+        for (const hook of this.hooks.onProgress) {
+            try {
+                hook(stats);
+            }
+            catch (err) {
+                console.error("Error in progress hook:", err);
+            }
+        }
+    }
+    /**
+     * Assert that the processor is not frozen
+     */
+    assertNotFrozen() {
+        if (this.frozen) {
+            throw new Error("Cannot modify frozen processor");
+        }
+    }
+}
+//# sourceMappingURL=processor.js.map

package/src/processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.js","sourceRoot":"","sources":["processor.ts"],"names":[],"mappings":"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"}

package/src/stream-processor.d.ts

@@ -0,0 +1,145 @@
+/**
+ * GLOST Stream Processor
+ *
+ * Streaming variant of GLOSTProcessor that yields processed sentence
+ * batches progressively using AsyncGenerator. Keeps the full document
+ * out of memory between chunks.
+ *
+ * Document-level transforms (extensions with streamingSupport !== 'chunk')
+ * run once on the full document before streaming begins. Chunk-compatible
+ * extensions (streamingSupport === 'chunk') then run on each batch.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { GLOSTStreamProcessor } from "glost-processor";
+ *
+ * const processor = new GLOSTStreamProcessor()
+ *   .use(transcription)
+ *   .use(translation);
+ *
+ * for await (const chunk of processor.stream(document)) {
+ *   console.log(chunk.sentences, chunk.isLast);
+ * }
+ * ```
+ *
+ * @since 0.7.0
+ */
+import type { GLOSTRoot, GLOSTSentence } from "glost-core";
+import type { PluginSpec, Preset, ProcessorOptions } from "./types.js";
+/**
+ * Options for stream() method
+ *
+ * @since 0.7.0
+ */
+export interface StreamOptions {
+    /**
+     * Number of sentences per chunk.
+     *
+     * A smaller value reduces latency to first yielded chunk; a larger
+     * value amortises per-chunk overhead. Default: 50.
+     */
+    batchSize?: number;
+}
+/**
+ * A single yielded chunk from the stream
+ *
+ * @since 0.7.0
+ */
+export interface ProcessedChunk {
+    /** Processed sentences in this batch */
+    sentences: GLOSTSentence[];
+    /**
+     * Index of the source paragraph this chunk came from.
+     *
+     * When the document has multiple paragraphs each paragraph is
+     * chunked independently, so multiple consecutive chunks may share
+     * the same paragraphIndex.
+     */
+    paragraphIndex: number;
+    /**
+     * Index of this chunk within its paragraph (0-based).
+     */
+    chunkIndex: number;
+    /** True for the final chunk across the whole document */
+    isLast: boolean;
+}
+/**
+ * Streaming processor for GLOST documents
+ *
+ * Mirrors the `GLOSTProcessor` API (`.use()`, `.freeze()`) but adds a
+ * `.stream()` method that returns an `AsyncGenerator<ProcessedChunk>`.
+ *
+ * @since 0.7.0
+ */
+export declare class GLOSTStreamProcessor {
+    private plugins;
+    private options;
+    private frozen;
+    /**
+     * Create a new stream processor instance
+     *
+     * @param options - Initial processor options
+     */
+    constructor(options?: ProcessorOptions);
+    /**
+     * Add a plugin, preset, or extension to the pipeline
+     *
+     * @param spec - Plugin function, extension object, preset, or ID
+     * @param options - Plugin options
+     * @returns This processor for chaining
+     */
+    use(spec: PluginSpec | Preset, options?: unknown): this;
+    /**
+     * Freeze the processor
+     *
+     * Returns a frozen processor that cannot be modified. Useful for
+     * reusing the same pipeline configuration across multiple documents.
+     *
+     * @returns A frozen copy of this processor
+     */
+    freeze(): FrozenStreamProcessor;
+    /**
+     * Stream a document as progressive sentence batches
+     *
+     * Processing phases:
+     * 1. All extensions with `streamingSupport !== 'chunk'` (i.e. `'none'`
+     *    or `'full'`, or unset) run their `transform`, `visit`, and
+     *    `enhanceMetadata` hooks on the **full** document.
+     * 2. The resulting document is split into sentence batches.
+     * 3. For each batch, extensions with `streamingSupport === 'chunk'`
+     *    run their `visit` and `enhanceMetadata` hooks.
+     * 4. A `ProcessedChunk` is yielded.
+     *
+     * Cancellation: break out of the `for await` loop at any time. The
+     * generator will stop without processing remaining chunks.
+     *
+     * @param document - GLOST document to stream
+     * @param streamOptions - Streaming options (batchSize etc.)
+     * @yields `ProcessedChunk` objects in document order
+     *
+     * @example
+     * ```typescript
+     * for await (const chunk of processor.stream(doc, { batchSize: 20 })) {
+     *   console.log(`para ${chunk.paragraphIndex} chunk ${chunk.chunkIndex}`);
+     *   if (chunk.isLast) console.log("done");
+     * }
+     * ```
+     */
+    stream(document: GLOSTRoot, streamOptions?: StreamOptions): AsyncGenerator<ProcessedChunk>;
+    private usePreset;
+    private resolveExtensions;
+    private resolvePlugin;
+    private isPreset;
+    private assertNotFrozen;
+}
+/**
+ * A frozen `GLOSTStreamProcessor` that cannot be modified.
+ *
+ * @since 0.7.0
+ */
+export type FrozenStreamProcessor = Omit<GLOSTStreamProcessor, "use" | "freeze"> & {
+    readonly frozen: true;
+};
+//# sourceMappingURL=stream-processor.d.ts.map

package/src/stream-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-processor.d.ts","sourceRoot":"","sources":["stream-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAO3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMvE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,SAAS,EAAE,aAAa,EAAE,CAAC;IAE3B;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC;CACjB;AAMD;;;;;;;GAOG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAsD;IACrE,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,OAAO,GAAE,gBAAqB;IAI1C;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAWvD;;;;;;;OAOG;IACH,MAAM,IAAI,qBAAqB;IAO/B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,MAAM,CACX,QAAQ,EAAE,SAAS,EACnB,aAAa,CAAC,EAAE,aAAa,GAC5B,cAAc,CAAC,cAAc,CAAC;IAiGjC,OAAO,CAAC,SAAS;YAYH,iBAAiB;YAWjB,aAAa;IAsB3B,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,eAAe;CAKxB;AAMD;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,IAAI,CACtC,oBAAoB,EACpB,KAAK,GAAG,QAAQ,CACjB,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC"}