glost-processor 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GLOST Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,262 @@
+# glost-processor
+
+Unified-style processor API for GLOST documents with fluent plugin composition.
+
+## Overview
+
+`glost-processor` provides a fluent API for processing GLOST documents through plugin pipelines, similar to the [unified](https://unifiedjs.com/) ecosystem (remark, rehype, etc.).
+
+## Installation
+
+```bash
+npm install glost-processor
+# or
+pnpm add glost-processor
+```
+
+## Usage
+
+### Basic Processing
+
+```typescript
+import { glost } from "glost-processor";
+import { transcription } from "glost-transcription";
+import { translation } from "glost-translation";
+import { frequency } from "glost-frequency";
+
+const processor = glost()
+  .use(transcription, { scheme: "ipa" })
+  .use(translation, { target: "en" })
+  .use(frequency);
+
+const result = await processor.process(document);
+```
+
+### Freezing for Reuse
+
+```typescript
+const frozen = glost()
+  .use(transcription)
+  .use(translation)
+  .freeze();
+
+// Reuse across multiple documents
+const result1 = await frozen.process(doc1);
+const result2 = await frozen.process(doc2);
+```
+
+### Using Presets
+
+```typescript
+import { languageLearningPreset } from "glost-presets";
+
+const processor = glost()
+  .use(languageLearningPreset);
+
+const result = await processor.process(document);
+```
+
+### Hooks and Middleware
+
+```typescript
+const processor = glost()
+  .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}`);
+  });
+
+const result = await processor.process(document);
+```
+
+### Data Storage
+
+Share data between plugins:
+
+```typescript
+const processor = glost()
+  .data("config", { theme: "dark" })
+  .use(plugin1)
+  .use(plugin2);
+
+// Access in plugins
+const config = processor.data("config");
+```
+
+### Processing with Metadata
+
+Get detailed processing information:
+
+```typescript
+const result = await processor.processWithMeta(document);
+
+console.log(result.document);              // Processed document
+console.log(result.metadata.appliedPlugins);  // Which plugins ran
+console.log(result.metadata.stats.totalTime); // Total time
+console.log(result.metadata.errors);       // Any errors
+```
+
+## API
+
+### `glost(options?)`
+
+Create a new processor instance.
+
+**Options:**
+- `lenient?: boolean` - If true, continue processing on errors (default: false)
+- `conflictStrategy?: "error" | "warn" | "lastWins"` - How to handle metadata conflicts
+- `debug?: boolean` - Enable debug logging
+- `data?: Map<string, any>` - Initial data store
+
+### `processor.use(plugin, options?)`
+
+Add a plugin to the pipeline.
+
+**Parameters:**
+- `plugin` - Plugin function, extension object, preset, or plugin ID string
+- `options` - Plugin-specific options
+
+**Returns:** The processor for chaining
+
+### `processor.freeze()`
+
+Freeze the processor configuration for reuse.
+
+**Returns:** A frozen processor that can only process documents
+
+### `processor.process(document)`
+
+Process a document through the pipeline.
+
+**Parameters:**
+- `document` - GLOST document to process
+
+**Returns:** Promise resolving to the processed document
+
+### `processor.processWithMeta(document)`
+
+Process a document and get detailed metadata.
+
+**Parameters:**
+- `document` - GLOST document to process
+
+**Returns:** Promise resolving to processing result with metadata
+
+### `processor.before(pluginId, hook)`
+
+Register a hook to run before a plugin.
+
+**Parameters:**
+- `pluginId` - Plugin ID to hook into
+- `hook` - Function to run before the plugin
+
+**Returns:** The processor for chaining
+
+### `processor.after(pluginId, hook)`
+
+Register a hook to run after a plugin.
+
+**Parameters:**
+- `pluginId` - Plugin ID to hook into
+- `hook` - Function to run after the plugin
+
+**Returns:** The processor for chaining
+
+### `processor.onError(hook)`
+
+Register an error handler.
+
+**Parameters:**
+- `hook` - Function to handle errors
+
+**Returns:** The processor for chaining
+
+### `processor.onSkip(hook)`
+
+Register a skip handler.
+
+**Parameters:**
+- `hook` - Function to handle skipped plugins
+
+**Returns:** The processor for chaining
+
+### `processor.onProgress(hook)`
+
+Register a progress handler.
+
+**Parameters:**
+- `hook` - Function to handle progress updates
+
+**Returns:** The processor for chaining
+
+### `processor.data(key, value?)`
+
+Get or set data in the processor data store.
+
+**Parameters:**
+- `key` - Data key
+- `value` - Data value (omit to get)
+
+**Returns:** Value if getting, processor if setting
+
+## Plugin Format
+
+Plugins can be:
+
+1. **Plugin functions** (returns an extension)
+```typescript
+const myPlugin = (options) => {
+  return {
+    id: "my-plugin",
+    name: "My Plugin",
+    transform: (tree) => tree
+  };
+};
+```
+
+2. **Extension objects** (used directly)
+```typescript
+const myExtension = {
+  id: "my-extension",
+  name: "My Extension",
+  transform: (tree) => tree
+};
+```
+
+3. **Plugin ID strings** (looked up in registry)
+```typescript
+processor.use("transcription");
+```
+
+## Comparison with Old API
+
+**Old API:**
+```typescript
+import { processGLOSTWithExtensions } from "glost-extensions";
+
+const result = processGLOSTWithExtensions(doc, [ext1, ext2, ext3]);
+```
+
+**New API:**
+```typescript
+import { glost } from "glost-processor";
+
+const result = await glost()
+  .use(ext1)
+  .use(ext2)
+  .use(ext3)
+  .process(doc);
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * GLOST Processor
+ *
+ * Unified-style processor for GLOST documents.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { glost } from "glost-processor";
+ * import { transcription } from "glost-transcription";
+ * import { translation } from "glost-translation";
+ *
+ * const processor = glost()
+ *   .use(transcription, { scheme: "ipa" })
+ *   .use(translation, { target: "en" })
+ *   .freeze();
+ *
+ * const result = await processor.process(document);
+ * ```
+ */
+export { GLOSTProcessor } from "./processor.js";
+export type { FrozenProcessor } from "./processor.js";
+export type { Plugin, PluginSpec, Preset, ProcessorOptions, ProcessingResult, ProcessingError, ProcessingWarning, ProcessingStats, BeforeHook, AfterHook, ErrorHook, SkipHook, ProgressHook, ProgressStats, } from "./types.js";
+import { GLOSTProcessor } from "./processor.js";
+import type { ProcessorOptions } from "./types.js";
+/**
+ * Create a new GLOST processor
+ *
+ * Factory function for creating a new processor instance.
+ * Similar to `unified()` from the unified ecosystem.
+ *
+ * @param options - Initial processor options
+ * @returns A new processor instance
+ *
+ * @example
+ * ```typescript
+ * import { glost } from "glost-processor";
+ *
+ * const processor = glost()
+ *   .use(plugin1)
+ *   .use(plugin2)
+ *   .use(plugin3);
+ *
+ * const result = await processor.process(document);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With options
+ * const processor = glost({ lenient: true, debug: true })
+ *   .use(plugin1)
+ *   .use(plugin2);
+ * ```
+ */
+export declare function glost(options?: ProcessorOptions): GLOSTProcessor;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,YAAY,EACV,MAAM,EACN,UAAU,EACV,MAAM,EACN,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,SAAS,EACT,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,KAAK,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,CAEhE"}

package/dist/index.js

@@ -0,0 +1,56 @@
+/**
+ * GLOST Processor
+ *
+ * Unified-style processor for GLOST documents.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { glost } from "glost-processor";
+ * import { transcription } from "glost-transcription";
+ * import { translation } from "glost-translation";
+ *
+ * const processor = glost()
+ *   .use(transcription, { scheme: "ipa" })
+ *   .use(translation, { target: "en" })
+ *   .freeze();
+ *
+ * const result = await processor.process(document);
+ * ```
+ */
+export { GLOSTProcessor } from "./processor.js";
+import { GLOSTProcessor } from "./processor.js";
+/**
+ * Create a new GLOST processor
+ *
+ * Factory function for creating a new processor instance.
+ * Similar to `unified()` from the unified ecosystem.
+ *
+ * @param options - Initial processor options
+ * @returns A new processor instance
+ *
+ * @example
+ * ```typescript
+ * import { glost } from "glost-processor";
+ *
+ * const processor = glost()
+ *   .use(plugin1)
+ *   .use(plugin2)
+ *   .use(plugin3);
+ *
+ * const result = await processor.process(document);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With options
+ * const processor = glost({ lenient: true, debug: true })
+ *   .use(plugin1)
+ *   .use(plugin2);
+ * ```
+ */
+export function glost(options) {
+    return new GLOSTProcessor(options);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAmBhD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,KAAK,CAAC,OAA0B;IAC9C,OAAO,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC"}

package/dist/processor.d.ts

@@ -0,0 +1,256 @@
+/**
+ * GLOST Processor
+ *
+ * Unified-style processor for GLOST documents with fluent API.
+ * Similar to unified/remark processors.
+ *
+ * @packageDocumentation
+ */
+import type { GLOSTRoot } from "glost-core";
+import type { PluginSpec, Preset, ProcessorOptions, ProcessingResult, BeforeHook, AfterHook, ErrorHook, SkipHook, ProgressHook } from "./types.js";
+/**
+ * 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 declare class GLOSTProcessor {
+    private plugins;
+    private hooks;
+    private dataStore;
+    private options;
+    private frozen;
+    /**
+     * Create a new processor instance
+     *
+     * @param options - Initial processor options
+     */
+    constructor(options?: ProcessorOptions);
+    /**
+     * 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: PluginSpec | Preset, options?: any): this;
+    /**
+     * Apply a preset (collection of plugins)
+     *
+     * @param preset - Preset to apply
+     * @returns This processor for chaining
+     */
+    private usePreset;
+    /**
+     * 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: string, hook: BeforeHook): 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: string, hook: AfterHook): 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: ErrorHook): 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: SkipHook): 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: ProgressHook): this;
+    /**
+     * Set or get data in the processor data store
+     *
+     * @param key - Data key
+     * @param value - Data value (omit to get)
+     * @returns Value if getting, this processor if setting
+     *
+     * @example
+     * ```typescript
+     * processor.data("config", { theme: "dark" });
+     * const config = processor.data("config");
+     * ```
+     */
+    data(key: string): any;
+    data(key: string, value: any): 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(): FrozenProcessor;
+    /**
+     * 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);
+     * ```
+     */
+    process(document: GLOSTRoot): Promise<GLOSTRoot>;
+    /**
+     * 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);
+     * ```
+     */
+    processWithMeta(document: GLOSTRoot): Promise<ProcessingResult>;
+    /**
+     * 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: GLOSTRoot): GLOSTRoot;
+    /**
+     * Resolve all plugins to extensions
+     */
+    private resolveExtensions;
+    /**
+     * Resolve a single plugin to an extension
+     */
+    private resolvePlugin;
+    /**
+     * Check if a spec is a preset
+     */
+    private isPreset;
+    /**
+     * Run before hooks for a plugin
+     */
+    private runBeforeHooks;
+    /**
+     * Run after hooks for a plugin
+     */
+    private runAfterHooks;
+    /**
+     * Emit error to error handlers
+     */
+    private emitError;
+    /**
+     * Emit skip to skip handlers
+     */
+    private emitSkip;
+    /**
+     * Emit progress to progress handlers
+     */
+    private emitProgress;
+    /**
+     * Assert that the processor is not frozen
+     */
+    private assertNotFrozen;
+}
+/**
+ * Frozen processor type
+ *
+ * A frozen processor cannot be modified, only used for processing.
+ */
+export type FrozenProcessor = Omit<GLOSTProcessor, "use" | "before" | "after" | "onError" | "onSkip" | "onProgress" | "data" | "freeze"> & {
+    readonly frozen: true;
+};
+//# sourceMappingURL=processor.d.ts.map

package/dist/processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../src/processor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,KAAK,EACV,UAAU,EACV,MAAM,EACN,gBAAgB,EAChB,gBAAgB,EAEhB,UAAU,EACV,SAAS,EACT,SAAS,EACT,QAAQ,EACR,YAAY,EAIb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAkD;IACjE,OAAO,CAAC,KAAK,CAMX;IACF,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,OAAO,GAAE,gBAAqB;IAO1C;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI;IAanD;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAYjB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IAShD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAS9C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAM9B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAM5B;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAMpC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;IACtB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI;IAUnC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,IAAI,eAAe;IAezB;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IAKtD;;;;;;;;;;;;OAYG;IACG,eAAe,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAkHrE;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS;IAM3C;;OAEG;YACW,iBAAiB;IAa/B;;OAEG;YACW,aAAa;IAuB3B;;OAEG;IACH,OAAO,CAAC,QAAQ;IAShB;;OAEG;YACW,cAAc;IAO5B;;OAEG;YACW,aAAa;IAO3B;;OAEG;IACH,OAAO,CAAC,SAAS;IAUjB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAUhB;;OAEG;IACH,OAAO,CAAC,YAAY;IAUpB;;OAEG;IACH,OAAO,CAAC,eAAe;CAKxB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,cAAc,EACd,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,CACrF,GAAG;IACF,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;CACvB,CAAC"}