intor-translator 1.2.0 → 1.2.2

package/README.md

@@ -3,7 +3,7 @@
 <div align="center">
 
 A modern **i18n engine** powered by a customizable, type-safe translation pipeline.  
-Easy to adopt, modular at its core, and fully extensible.
+Easy to use, modular at its core, and fully extensible.
 
 </div>
 
@@ -12,8 +12,8 @@ Easy to adopt, modular at its core, and fully extensible.
 [![NPM version](https://img.shields.io/npm/v/intor-translator?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/intor-translator)
 [![Bundle size](https://img.shields.io/bundlephobia/minzip/intor-translator?style=flat&colorA=000000&colorB=000000)](https://bundlephobia.com/package/intor-translator)
 [![Coverage Status](https://img.shields.io/coveralls/github/yiming-liao/intor-translator.svg?branch=main&style=flat&colorA=000000&colorB=000000)](https://coveralls.io/github/yiming-liao/intor-translator?branch=main)
-[![License](https://img.shields.io/npm/l/intor-translator?style=flat&colorA=000000&colorB=000000)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-%E2%9C%94-blue?style=flat&colorA=000000&colorB=000000)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/npm/l/intor-translator?style=flat&colorA=000000&colorB=000000)](LICENSE)
 
 </div>
 
@@ -30,12 +30,20 @@ Easy to adopt, modular at its core, and fully extensible.
 ```bash
 # npm
 npm install intor-translator
+
 # yarn
 yarn add intor-translator
+
 # pnpm
 pnpm add intor-translator
 ```
 
+Or load it directly from a CDN:
+
+```js
+import { Translator } from "https://cdn.jsdelivr.net/npm/intor-translator/+esm";
+```
+
 ## Quick Start
 
 ```typescript

package/dist/index.cjs

@@ -1,5 +1,9 @@
 'use strict';
 
+var rura = require('rura');
+
+// src/translators/core-translator/core-translator.ts
+
 // src/translators/shared/utils/find-message-in-locales.ts
 var findMessageInLocales = ({
   messages,
@@ -23,18 +27,18 @@ var findMessageInLocales = ({
   }
 };
 
-// src/pipeline/hooks/find-message.hook.ts
-var findMessageHook = {
-  name: "findMessage",
-  order: 200,
-  run(ctx) {
+// src/pipeline/hooks/find-message.ts
+var findMessage = rura.rura.createHook(
+  "findMessage",
+  (ctx) => {
     ctx.rawMessage = findMessageInLocales({
       messages: ctx.messages,
       candidateLocales: ctx.candidateLocales,
       key: ctx.key
     });
-  }
-};
+  },
+  200
+);
 
 // src/pipeline/utils/make-handler-context.ts
 function makeHandlerContext(ctx) {
@@ -52,19 +56,19 @@ function makeHandlerContext(ctx) {
   });
 }
 
-// src/pipeline/hooks/format.hook.ts
-var formatHook = {
-  name: "format",
-  order: 500,
-  run(ctx) {
+// src/pipeline/hooks/format.ts
+var format = rura.rura.createHook(
+  "format",
+  (ctx) => {
     const { config, rawMessage } = ctx;
     const { formatHandler } = config.handlers || {};
     if (!formatHandler || rawMessage === void 0) return;
     ctx.formattedMessage = formatHandler(
       makeHandlerContext(ctx)
     );
-  }
-};
+  },
+  500
+);
 
 // src/translators/shared/utils/replace-values.ts
 var replaceValues = (message, params) => {
@@ -85,11 +89,10 @@ var replaceValues = (message, params) => {
   return replaced;
 };
 
-// src/pipeline/hooks/interpolate.hook.ts
-var interpolateHook = {
-  name: "interpolate",
-  order: 600,
-  run(ctx) {
+// src/pipeline/hooks/interpolate.ts
+var interpolate = rura.rura.createHook(
+  "interpolate",
+  (ctx) => {
     const { rawMessage, formattedMessage, replacements } = ctx;
     const message = formattedMessage ?? rawMessage;
     if (typeof message !== "string" || !replacements) {
@@ -97,51 +100,48 @@ var interpolateHook = {
       return;
     }
     ctx.finalMessage = replaceValues(message, replacements);
-  }
-};
-
-// src/pipeline/hooks/loading.hook.ts
-var loadingHook = {
-  name: "loading",
-  order: 300,
-  run(ctx) {
+  },
+  600
+);
+var loading = rura.rura.createHook(
+  "loading",
+  (ctx) => {
     const { config, isLoading } = ctx;
     if (!isLoading) return;
     const { loadingHandler } = config.handlers || {};
     if (loadingHandler) {
       return {
-        done: true,
-        value: loadingHandler(makeHandlerContext(ctx))
+        early: true,
+        output: loadingHandler(makeHandlerContext(ctx))
       };
     }
     const { loadingMessage } = config;
     if (loadingMessage) {
-      return { done: true, value: loadingMessage };
+      return { early: true, output: loadingMessage };
     }
-  }
-};
-
-// src/pipeline/hooks/missing.hook.ts
-var missingHook = {
-  name: "missing",
-  order: 400,
-  run(ctx) {
+  },
+  300
+);
+var missing = rura.rura.createHook(
+  "missing",
+  (ctx) => {
     const { config, key, rawMessage } = ctx;
     if (rawMessage !== void 0) return;
     const { missingHandler } = config.handlers || {};
     if (missingHandler) {
       return {
-        done: true,
-        value: missingHandler(makeHandlerContext(ctx))
+        early: true,
+        output: missingHandler(makeHandlerContext(ctx))
       };
     }
     const { placeholder } = config;
     if (placeholder) {
-      return { done: true, value: placeholder };
+      return { early: true, output: placeholder };
     }
-    return { done: true, value: key };
-  }
-};
+    return { early: true, output: key };
+  },
+  400
+);
 
 // src/translators/shared/utils/resolve-candidate-locales.ts
 var resolveCandidateLocales = (locale, fallbackLocalesMap) => {
@@ -150,26 +150,26 @@ var resolveCandidateLocales = (locale, fallbackLocalesMap) => {
   return [locale, ...filteredFallbacks];
 };
 
-// src/pipeline/hooks/resolve-locales.hook.ts
-var resolveLocalesHook = {
-  name: "resolveLocales",
-  order: 100,
-  run(ctx) {
+// src/pipeline/hooks/resolve-locales.ts
+var resolveLocales = rura.rura.createHook(
+  "resolveLocales",
+  (ctx) => {
     ctx.candidateLocales = resolveCandidateLocales(
       ctx.locale,
       ctx.config.fallbackLocales
     );
-  }
-};
+  },
+  100
+);
 
-// src/pipeline/hooks/index.ts
+// src/pipeline/index.ts
 var DEFAULT_HOOKS = [
-  resolveLocalesHook,
-  findMessageHook,
-  loadingHook,
-  missingHook,
-  formatHook,
-  interpolateHook
+  resolveLocales,
+  findMessage,
+  loading,
+  missing,
+  format,
+  interpolate
 ];
 
 // src/translators/base-translator/base-translator.ts
@@ -235,27 +235,16 @@ var hasKey = ({
   });
   return !!message;
 };
-
-// src/pipeline/run-pipeline.ts
-function runPipeline(ctx, hooks) {
-  for (const hook of hooks) {
-    const result = hook.run(ctx);
-    if (result?.done) {
-      return result.value;
-    }
-  }
-  return ctx.finalMessage ?? ctx.rawMessage;
-}
-
-// src/translators/shared/translate.ts
 function translate(options) {
-  const ctx = {
+  const context = {
     ...options,
     config: options.translateConfig,
     candidateLocales: [],
     meta: {}
   };
-  return runPipeline(ctx, options.hooks);
+  const { early, ctx, output } = rura.rura.run(context, options.hooks);
+  if (early === true) return output;
+  return ctx.finalMessage;
 }
 
 // src/translators/core-translator/core-translator.ts
@@ -286,6 +275,12 @@ var CoreTranslator = class extends BaseTranslator {
     }
     this.sortHooks();
   }
+  /** Outputs a debug overview of the active pipeline. */
+  debugHooks() {
+    return rura.rura.createPipeline(this.hooks).debugHooks(
+      (hooks) => `\u{1F916} Intor Translator pipeline (${hooks.length} hooks)`
+    );
+  }
   /** Check if a key exists in the specified locale or current locale. */
   hasKey = (key, targetLocale) => {
     return hasKey({

package/dist/index.d.cts

@@ -1,3 +1,5 @@
+import { RuraHook } from 'rura';
+
 /**
  * A nested message structure or a simple string message.
  *
@@ -319,28 +321,8 @@ interface TranslateContext<Result = unknown> {
 }
 /**
  * A single step in the translate pipeline.
- *
- * @template Result - Final translated value type.
  */
-interface TranslateHook<Result = unknown> {
-    /** Unique name for this hook, used for debugging and introspection. */
-    name: string;
-    /**
-     * Optional execution order.
-     * - Lower values run earlier; hooks without order run last-in registration order.
-     */
-    order?: number;
-    /**
-     * Run the hook with the current context.
-     * - Return `{ done: true, value }` to short-circuit the pipeline.
-     */
-    run(ctx: TranslateContext<Result>): void | {
-        /** Indicates the pipeline should stop after this hook. */
-        done: true;
-        /** Final value to return from the translate call. */
-        value: Result;
-    };
-}
+type TranslateHook = RuraHook<TranslateContext>;
 
 /**
  * Options for initializing a translator
@@ -428,6 +410,8 @@ declare class CoreTranslator<M extends LocaleMessages, L extends keyof M | "unio
     private sortHooks;
     /** Register a plugin or a raw pipeline hook. */
     use(plugin: TranslatorPlugin | TranslateHook): void;
+    /** Outputs a debug overview of the active pipeline. */
+    debugHooks(): void;
     /** Check if a key exists in the specified locale or current locale. */
     hasKey: <K extends LocalizedLeafKeys<M, L>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { RuraHook } from 'rura';
+
 /**
  * A nested message structure or a simple string message.
  *
@@ -319,28 +321,8 @@ interface TranslateContext<Result = unknown> {
 }
 /**
  * A single step in the translate pipeline.
- *
- * @template Result - Final translated value type.
  */
-interface TranslateHook<Result = unknown> {
-    /** Unique name for this hook, used for debugging and introspection. */
-    name: string;
-    /**
-     * Optional execution order.
-     * - Lower values run earlier; hooks without order run last-in registration order.
-     */
-    order?: number;
-    /**
-     * Run the hook with the current context.
-     * - Return `{ done: true, value }` to short-circuit the pipeline.
-     */
-    run(ctx: TranslateContext<Result>): void | {
-        /** Indicates the pipeline should stop after this hook. */
-        done: true;
-        /** Final value to return from the translate call. */
-        value: Result;
-    };
-}
+type TranslateHook = RuraHook<TranslateContext>;
 
 /**
  * Options for initializing a translator
@@ -428,6 +410,8 @@ declare class CoreTranslator<M extends LocaleMessages, L extends keyof M | "unio
     private sortHooks;
     /** Register a plugin or a raw pipeline hook. */
     use(plugin: TranslatorPlugin | TranslateHook): void;
+    /** Outputs a debug overview of the active pipeline. */
+    debugHooks(): void;
     /** Check if a key exists in the specified locale or current locale. */
     hasKey: <K extends LocalizedLeafKeys<M, L>>(key: K, targetLocale?: Locale<M>) => boolean;
     /** Get the translated message for a key, with optional replacements. */

package/dist/index.js

@@ -1,3 +1,7 @@
+import { rura } from 'rura';
+
+// src/translators/core-translator/core-translator.ts
+
 // src/translators/shared/utils/find-message-in-locales.ts
 var findMessageInLocales = ({
   messages,
@@ -21,18 +25,18 @@ var findMessageInLocales = ({
   }
 };
 
-// src/pipeline/hooks/find-message.hook.ts
-var findMessageHook = {
-  name: "findMessage",
-  order: 200,
-  run(ctx) {
+// src/pipeline/hooks/find-message.ts
+var findMessage = rura.createHook(
+  "findMessage",
+  (ctx) => {
     ctx.rawMessage = findMessageInLocales({
       messages: ctx.messages,
       candidateLocales: ctx.candidateLocales,
       key: ctx.key
     });
-  }
-};
+  },
+  200
+);
 
 // src/pipeline/utils/make-handler-context.ts
 function makeHandlerContext(ctx) {
@@ -50,19 +54,19 @@ function makeHandlerContext(ctx) {
   });
 }
 
-// src/pipeline/hooks/format.hook.ts
-var formatHook = {
-  name: "format",
-  order: 500,
-  run(ctx) {
+// src/pipeline/hooks/format.ts
+var format = rura.createHook(
+  "format",
+  (ctx) => {
     const { config, rawMessage } = ctx;
     const { formatHandler } = config.handlers || {};
     if (!formatHandler || rawMessage === void 0) return;
     ctx.formattedMessage = formatHandler(
       makeHandlerContext(ctx)
     );
-  }
-};
+  },
+  500
+);
 
 // src/translators/shared/utils/replace-values.ts
 var replaceValues = (message, params) => {
@@ -83,11 +87,10 @@ var replaceValues = (message, params) => {
   return replaced;
 };
 
-// src/pipeline/hooks/interpolate.hook.ts
-var interpolateHook = {
-  name: "interpolate",
-  order: 600,
-  run(ctx) {
+// src/pipeline/hooks/interpolate.ts
+var interpolate = rura.createHook(
+  "interpolate",
+  (ctx) => {
     const { rawMessage, formattedMessage, replacements } = ctx;
     const message = formattedMessage ?? rawMessage;
     if (typeof message !== "string" || !replacements) {
@@ -95,51 +98,48 @@ var interpolateHook = {
       return;
     }
     ctx.finalMessage = replaceValues(message, replacements);
-  }
-};
-
-// src/pipeline/hooks/loading.hook.ts
-var loadingHook = {
-  name: "loading",
-  order: 300,
-  run(ctx) {
+  },
+  600
+);
+var loading = rura.createHook(
+  "loading",
+  (ctx) => {
     const { config, isLoading } = ctx;
     if (!isLoading) return;
     const { loadingHandler } = config.handlers || {};
     if (loadingHandler) {
       return {
-        done: true,
-        value: loadingHandler(makeHandlerContext(ctx))
+        early: true,
+        output: loadingHandler(makeHandlerContext(ctx))
       };
     }
     const { loadingMessage } = config;
     if (loadingMessage) {
-      return { done: true, value: loadingMessage };
+      return { early: true, output: loadingMessage };
     }
-  }
-};
-
-// src/pipeline/hooks/missing.hook.ts
-var missingHook = {
-  name: "missing",
-  order: 400,
-  run(ctx) {
+  },
+  300
+);
+var missing = rura.createHook(
+  "missing",
+  (ctx) => {
     const { config, key, rawMessage } = ctx;
     if (rawMessage !== void 0) return;
     const { missingHandler } = config.handlers || {};
     if (missingHandler) {
       return {
-        done: true,
-        value: missingHandler(makeHandlerContext(ctx))
+        early: true,
+        output: missingHandler(makeHandlerContext(ctx))
       };
     }
     const { placeholder } = config;
     if (placeholder) {
-      return { done: true, value: placeholder };
+      return { early: true, output: placeholder };
     }
-    return { done: true, value: key };
-  }
-};
+    return { early: true, output: key };
+  },
+  400
+);
 
 // src/translators/shared/utils/resolve-candidate-locales.ts
 var resolveCandidateLocales = (locale, fallbackLocalesMap) => {
@@ -148,26 +148,26 @@ var resolveCandidateLocales = (locale, fallbackLocalesMap) => {
   return [locale, ...filteredFallbacks];
 };
 
-// src/pipeline/hooks/resolve-locales.hook.ts
-var resolveLocalesHook = {
-  name: "resolveLocales",
-  order: 100,
-  run(ctx) {
+// src/pipeline/hooks/resolve-locales.ts
+var resolveLocales = rura.createHook(
+  "resolveLocales",
+  (ctx) => {
     ctx.candidateLocales = resolveCandidateLocales(
       ctx.locale,
       ctx.config.fallbackLocales
     );
-  }
-};
+  },
+  100
+);
 
-// src/pipeline/hooks/index.ts
+// src/pipeline/index.ts
 var DEFAULT_HOOKS = [
-  resolveLocalesHook,
-  findMessageHook,
-  loadingHook,
-  missingHook,
-  formatHook,
-  interpolateHook
+  resolveLocales,
+  findMessage,
+  loading,
+  missing,
+  format,
+  interpolate
 ];
 
 // src/translators/base-translator/base-translator.ts
@@ -233,27 +233,16 @@ var hasKey = ({
   });
   return !!message;
 };
-
-// src/pipeline/run-pipeline.ts
-function runPipeline(ctx, hooks) {
-  for (const hook of hooks) {
-    const result = hook.run(ctx);
-    if (result?.done) {
-      return result.value;
-    }
-  }
-  return ctx.finalMessage ?? ctx.rawMessage;
-}
-
-// src/translators/shared/translate.ts
 function translate(options) {
-  const ctx = {
+  const context = {
     ...options,
     config: options.translateConfig,
     candidateLocales: [],
     meta: {}
   };
-  return runPipeline(ctx, options.hooks);
+  const { early, ctx, output } = rura.run(context, options.hooks);
+  if (early === true) return output;
+  return ctx.finalMessage;
 }
 
 // src/translators/core-translator/core-translator.ts
@@ -284,6 +273,12 @@ var CoreTranslator = class extends BaseTranslator {
     }
     this.sortHooks();
   }
+  /** Outputs a debug overview of the active pipeline. */
+  debugHooks() {
+    return rura.createPipeline(this.hooks).debugHooks(
+      (hooks) => `\u{1F916} Intor Translator pipeline (${hooks.length} hooks)`
+    );
+  }
   /** Check if a key exists in the specified locale or current locale. */
   hasKey = (key, targetLocale) => {
     return hasKey({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intor-translator",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "🤖 A modern, type-safe i18n engine.",
   "author": "Yiming Liao",
   "license": "MIT",
@@ -51,26 +51,28 @@
   "engines": {
     "node": ">=16.0.0"
   },
-  "dependencies": {},
+  "dependencies": {
+    "rura": "1.0.7"
+  },
   "devDependencies": {
-    "@types/node": "^24.10.1",
-    "@vitest/coverage-v8": "4.0.9",
-    "eslint": "^9.39.1",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-import-resolver-typescript": "^4.4.4",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-prettier": "^5.5.4",
-    "eslint-plugin-unicorn": "^62.0.0",
-    "eslint-plugin-unused-imports": "^4.3.0",
-    "intl-messageformat": "^10.7.16",
-    "knip": "^5.69.1",
-    "prettier": "^3.6.2",
-    "ts-node": "^10.9.2",
-    "tsd": "^0.33.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.46.4",
-    "vite": "^7.2.6",
-    "vitest": "^4.0.9"
+    "@types/node": "24.10.1",
+    "@vitest/coverage-v8": "4.0.16",
+    "eslint": "9.39.1",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-import-resolver-typescript": "4.4.4",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-prettier": "5.5.4",
+    "eslint-plugin-unicorn": "62.0.0",
+    "eslint-plugin-unused-imports": "4.3.0",
+    "intl-messageformat": "10.7.16",
+    "knip": "5.69.1",
+    "prettier": "3.6.2",
+    "ts-node": "10.9.2",
+    "tsd": "0.33.0",
+    "tsup": "8.4.0",
+    "typescript": "5.8.3",
+    "typescript-eslint": "8.46.4",
+    "vite": "7.2.6",
+    "vitest": "4.0.16"
   }
 }