rura 1.0.8 → 1.1.1

package/README.md

@@ -2,16 +2,13 @@
 
 <div align="center">
 
-A minimal **pipeline engine** for every modern workflow,  
-built for clarity and stability.
+The hook pipeline
 
 </div>
 
 <div align="center">
 
 [![NPM version](https://img.shields.io/npm/v/rura?style=flat&colorA=000000&colorB=000000)](https://www.npmjs.com/package/rura)
-[![Bundle size](https://img.shields.io/bundlephobia/minzip/rura?style=flat&colorA=000000&colorB=000000)](https://bundlephobia.com/package/rura)
-[![Coverage Status](https://img.shields.io/coveralls/github/yiming-liao/rura.svg?branch=main&style=flat&colorA=000000&colorB=000000)](https://coveralls.io/github/yiming-liao/rura?branch=main)
 [![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/rura?style=flat&colorA=000000&colorB=000000)](LICENSE)
 
@@ -19,158 +16,81 @@ built for clarity and stability.
 
 ## Features
 
-- **Deterministic** – Ordered hooks with effortless early exit.
-- **Typed** – Inferred context and output with zero boilerplate.
-- **Universal** – Tiny, framework-agnostic, and ready for any flow.
+- **Deterministic** — Strict hook ordering with early termination.
+- **Type-safe** — Fully inferred context and output.
+- **Composable** — Minimal and framework-agnostic.
 
 ## Installation
 
 ```bash
-# npm
 npm install rura
-# yarn
+# or
 yarn add rura
-# pnpm
+# or
 pnpm add rura
 ```
 
-## Quick Start
-
-#### 1. Define the initial context
+## Example
 
 ```ts
-const ctx = { count: 1 };
-type Ctx = typeof ctx;
-```
-
-#### 2. Create your hooks
-
-- Hooks can be created with `rura.createHook`, or defined manually using the `RuraHook` type.
-- Hooks may specify an `order`; omitted values default to `0`.
+import { rura } from "rura";
 
-```ts
-import { rura, type RuraHook } from "rura";
+// Shared pipeline context.
+type Ctx = { count: number };
 
-// With createHook (recommended for convenience)
+// Synchronous hook.
 const addOne = rura.createHook<Ctx>("add-one", (ctx) => {
   ctx.count += 1;
-}); // order: 0
+});
 
-// Manual hook definition (full control)
-const stopIfEven: RuraHook<Ctx, number> = {
-  name: "stop-if-even",
-  run: (ctx) => {
+// Synchronous hook (Early-terminating).
+const stopIfEven = rura.createHook<Ctx, number>(
+  "stop-if-even",
+  (ctx) => {
     if (ctx.count % 2 === 0) {
       return { early: true, output: ctx.count };
     }
   },
-  order: 2, // order: 2
-};
-```
-
-- Rura executes hooks in order and exits early when a hook returns `{ early: true, output }`.
+  2, // optional execution order
+);
 
-- When the pipeline does not exit early, `output` is omitted and `early` becomes `false`.
+// Deterministic execution.
+const result = rura.run({ count: 1 }, [addOne, stopIfEven, addOne]);
+```
 
-#### 3. Run the pipeline
+Asynchronous variant:
 
 ```ts
-const result = rura.run(ctx, [addOne, stopIfEven]);
-
-console.log(result);
-// -> {
-//      early: true,
-//      ctx: { count: 2 },
-//      output: 2
-//    }
+rura.createHookAsync(...)
+rura.runAsync(...)
 ```
 
-> Note: If your hooks are asynchronous,  
-> use `rura.createHookAsync()` and run them through `rura.runAsync()` accordingly.
-
 ---
 
 ## Pipeline Builder
 
-> If you prefer working with a reusable pipeline instance
-
-**rura.createPipeline()** - Creates a lightweight, composable pipeline instance  
-that can register hooks, merge with other pipelines, and be inspected.
+Reusable pipeline instance:
 
 ```ts
-import { rura } from "rura";
+const pipeline = rura.createPipeline<Ctx>();
 
-const pipeline = rura.createPipeline<Context, Output>();
+pipeline.use(hookA).use(hookB);
 
-// Add hooks
-pipeline
-  .use(hookA) // chainable
-  .use(hookB)
-  .use(hookC);
+const result = pipeline.run({ count: 1 });
 ```
 
-example:
+Asynchronous variant:
 
 ```ts
-type Ctx = { value: number };
-
-// Create a reusable pipeline instance
-const pipelineA = rura.createPipeline<Ctx>();
-
-// Register a hook using `use()`
-pipelineA.use({
-  name: "add-two",
-  run: (ctx) => {
-    ctx.value += 2;
-  },
-});
-
-// Create another pipeline (preloaded with hooks)
-const pipelineB = rura.createPipeline<Ctx>([
-  {
-    name: "multiply-three",
-    run: (ctx) => {
-      ctx.value *= 3;
-    },
-  },
-]);
-
-// Merge pipelines into a single combined pipeline
-const pipeline = pipelineA.merge(pipelineB);
-
-// Execute the pipeline
-const result = await pipeline.run({ value: 1 });
-
-console.log(result);
-// -> {
-//      early: false,
-//      ctx: { value: 9 }
-//    }
+const pipeline = rura.createPipelineAsync<Ctx>();
+await pipeline.run(ctx);
 ```
 
-> Note: If your pipeline includes async hooks,  
-> be sure to use `rura.createPipelineAsync()`, which awaits each hook in order.
-
-#### Pipeline Instance Methods
-
-`rura.createPipeline()` — Synchronous Pipeline
-
-| Method           | Description                                                       | Parameters | Returns            |
-| ---------------- | ----------------------------------------------------------------- | ---------- | ------------------ |
-| **use(hook)**    | Adds a hook, normalizes its order, and re-sorts hooks.            | `hook`     | `this` (chainable) |
-| **merge(other)** | Merges hooks from another pipeline and re-sorts them.             | `other`    | `this` (chainable) |
-| **getHooks()**   | Returns a sorted shallow copy of all registered hooks.            | –          | `RuraHook[]`       |
-| **debugHooks()** | Prints a formatted, human-readable hook list.                     | –          | `void`             |
-| **run(ctx)**     | Executes the pipeline synchronously. (delegates to `rura.run()`). | `ctx`      | `RuraResult`       |
-
-<br/>
-
-`rura.createPipelineAsync()` — Asynchronous Pipeline
+#### Pipeline Instance API
 
-| Method           | Description                                                             | Parameters | Returns               |
-| ---------------- | ----------------------------------------------------------------------- | ---------- | --------------------- |
-| **use(hook)**    | Adds a hook, normalizes its order, and re-sorts hooks.                  | `hook`     | `this` (chainable)    |
-| **merge(other)** | Merges hooks from another pipeline and re-sorts them.                   | `other`    | `this` (chainable)    |
-| **getHooks()**   | Returns a sorted shallow copy of all registered hooks.                  | –          | `RuraHook[]`          |
-| **debugHooks()** | Prints a formatted, human-readable hook list.                           | –          | `void`                |
-| **run(ctx)**     | Executes the pipeline asynchronously. (delegates to `rura.runAsync()`). | `ctx`      | `Promise<RuraResult>` |
+| Method       | Description                                 | Returns                  |
+| ------------ | ------------------------------------------- | ------------------------ |
+| **use**      | Registers a hook and re-sorts the pipeline. | `this` (chainable)       |
+| **getHooks** | Returns a shallow copy of sorted hooks.     | `Hook[]`                 |
+| **logHooks** | Logs hook order and execution type.         | `void`                   |
+| **run**      | Executes the pipeline.                      | `RuraResult` / `Promise` |

package/dist/index.cjs

@@ -1,87 +1,95 @@
 'use strict';
 
+// src/hooks/internal.ts
+var ASYNC_HOOK = /* @__PURE__ */ Symbol("rura.async");
+
 // src/hooks/create-hook.ts
 function createHook(name, run2, order) {
-  return { name, run: run2, order };
+  const hook = {
+    name,
+    run: run2,
+    ...order !== void 0 ? { order } : {}
+  };
+  return hook;
 }
 function createHookAsync(name, run2, order) {
-  return { name, run: run2, order };
+  const hook = {
+    name,
+    run: run2,
+    ...order !== void 0 ? { order } : {},
+    [ASYNC_HOOK]: true
+  };
+  return hook;
 }
 
 // src/hooks/utils/is-async-hook.ts
 function isAsyncHook(hook) {
-  return hook.run.constructor.name === "AsyncFunction";
+  return hook[ASYNC_HOOK] === true;
 }
 
-// src/pipeline/create/utils/format-debug-message.ts
-var formatDebugMessage = (hooks, name, title) => {
-  if (title) {
-    console.log(`
-${title(hooks)}`);
-  } else {
-    const label = name ? ` <${name}>` : "";
-    console.log(`
-\u{1F30A} Rura Pipeline${label} (${hooks.length} hooks)`);
+// src/pipeline/create/utils/assert-sync-hook.ts
+function assertSyncHook(hook) {
+  if (isAsyncHook(hook)) {
+    throw new Error(
+      `Async hook "${hook.name}" is not allowed in sync pipeline.`
+    );
   }
-  console.log(`\u2500\u2500\u2500`);
+}
+
+// src/pipeline/create/utils/log-pipeline-hooks.ts
+function logPipelineHooks(hooks, name = "Rura") {
+  const count = hooks.length;
+  const suffix = count === 1 ? "hook" : "hooks";
+  console.log(`${name} (${count} ${suffix})`);
+  console.log("\u2500\u2500\u2500");
   hooks.forEach((hook, i) => {
     const kind = isAsyncHook(hook) ? "async" : "sync";
+    const order = hook.order ?? "-";
     console.log(
-      `${i + 1}. order:${String(hook.order).padStart(4)} | ${hook.name} (${kind})`
+      `${i + 1}. order: ${String(order).padEnd(4)} | ${hook.name} (${kind})`
     );
   });
-  console.log(`\u2500\u2500\u2500
-`);
-};
+  console.log("\u2500\u2500\u2500");
+}
 
 // src/pipeline/create/create-pipeline-base.ts
 function createPipelineBase(initialHooks, runFn, options) {
+  const isSync = options.mode === "sync";
+  if (isSync) for (const hook of initialHooks) assertSyncHook(hook);
   const name = options.name;
-  const hooks = initialHooks.map((h) => applyDefaultOrder(h));
-  function applyDefaultOrder(h) {
-    return { ...h, order: h.order ?? 0 };
-  }
+  const hooks = [...initialHooks];
   function sortHooks() {
-    hooks.sort((a, b) => a.order - b.order);
+    hooks.sort((a, b) => {
+      const ao = a.order ?? Number.POSITIVE_INFINITY;
+      const bo = b.order ?? Number.POSITIVE_INFINITY;
+      return ao - bo;
+    });
   }
-  function use(h) {
-    if (options.mode === "sync" && isAsyncHook(h)) {
-      throw new Error(`Async hook "${h.name}" is not allowed in createRura().`);
-    }
-    hooks.push(applyDefaultOrder(h));
-    sortHooks();
-    return api;
-  }
-  function merge(other) {
-    other.getHooks().forEach((h) => hooks.push(applyDefaultOrder(h)));
+  function use(hook) {
+    if (isSync) assertSyncHook(hook);
+    hooks.push(hook);
     sortHooks();
-    return api;
+    return pipeline;
   }
   function getHooks() {
     return [...hooks];
   }
-  function debugHooks(title) {
-    formatDebugMessage(hooks, name, title);
+  function logHooks() {
+    logPipelineHooks(hooks, name);
   }
   function run2(ctx) {
-    return runFn(ctx, hooks);
+    return runFn(ctx, [...hooks]);
   }
-  const api = { use, merge, getHooks, debugHooks, run: run2 };
+  const pipeline = { use, getHooks, logHooks, run: run2 };
   sortHooks();
-  return api;
+  return pipeline;
 }
 
 // src/pipeline/run/run.ts
 function run(ctx, hooks) {
   for (const hook of hooks) {
-    if (isAsyncHook(hook)) {
-      throw new Error(
-        `Async hook "${hook.name}" detected in run(). Use runAsync() instead.`
-      );
-    }
     const result = hook.run(ctx);
-    const isEarlyReturn = result && result.early === true;
-    if (isEarlyReturn) {
+    if (result?.early === true) {
       return {
         early: true,
         ctx,
@@ -95,20 +103,11 @@ function run(ctx, hooks) {
   };
 }
 
-// src/pipeline/create/create-pipeline.ts
-function createPipeline(hooks = []) {
-  return createPipelineBase(
-    hooks,
-    run,
-    { mode: "sync" }
-  );
-}
-
 // src/pipeline/run/run-async.ts
 async function runAsync(ctx, hooks) {
   for (const hook of hooks) {
     const result = await hook.run(ctx);
-    if (result && result.early === true) {
+    if (result?.early === true) {
       return {
         early: true,
         ctx,
@@ -122,6 +121,15 @@ async function runAsync(ctx, hooks) {
   };
 }
 
+// src/pipeline/create/create-pipeline.ts
+function createPipeline(hooks = []) {
+  return createPipelineBase(
+    hooks,
+    run,
+    { mode: "sync" }
+  );
+}
+
 // src/pipeline/create/create-pipeline-async.ts
 function createPipelineAsync(hooks = []) {
   return createPipelineBase(
@@ -132,18 +140,22 @@ function createPipelineAsync(hooks = []) {
 }
 
 // src/rura.ts
-var rura = {
-  // hook factories
+var rura = Object.freeze({
+  // Hook creation
   createHook,
   createHookAsync,
-  // executors
+  // Direct execution
   run,
   runAsync,
-  // pipeline constructors
+  // Pipeline construction
   createPipeline,
-  createPipelineAsync,
-  // utils
-  isAsyncHook
-};
+  createPipelineAsync
+});
 
+exports.createHook = createHook;
+exports.createHookAsync = createHookAsync;
+exports.createPipeline = createPipeline;
+exports.createPipelineAsync = createPipelineAsync;
+exports.run = run;
+exports.runAsync = runAsync;
 exports.rura = rura;

package/dist/index.d.ts

@@ -1,159 +1,211 @@
-/**
- * Base shape for all Rura hooks.
- * - Every hook must have a unique `name`.
- * - `order` controls execution priority (lower runs earlier).
- */
-interface RuraHookBase {
-    /** Unique identifier for debugging and inspection. */
-    name: string;
-    /** Execution priority. Hooks with lower values run first. */
-    order?: number;
-}
-/**
- * Synchronous Rura hook.
- * - Runs without awaiting.
- * - May optionally signal early termination.
- */
-interface RuraHookSync<Ctx, Out> extends RuraHookBase {
-    /**
-     * Executes the hook.
-     * @returns Nothing, or an early-return signal with output.
-     */
-    run(ctx: Ctx): void | {
-        early: true;
-        output: Out;
-    };
-}
-/**
- * Asynchronous Rura hook.
- * - Executes via `await`.
- * - May optionally signal early termination.
- */
-interface RuraHookAsync<Ctx, Out> extends RuraHookBase {
-    /**
-     * Executes the hook asynchronously.
-     * @returns A promise resolving to nothing or an early-return signal.
-     */
-    run(ctx: Ctx): Promise<void | {
-        early: true;
-        output: Out;
-    }>;
-}
-/**
- * A union of all hook types accepted by the Rura pipeline.
- */
-type RuraHook<Ctx = unknown, Out = unknown> = RuraHookSync<Ctx, Out> | RuraHookAsync<Ctx, Out>;
-
-/**
- * Creates a synchronous Rura hook.
- * - The hook will be executed without `await`.
- * - Suitable for lightweight, purely synchronous operations.
- */
-declare function createHook<Ctx = unknown, Out = unknown>(name: string, run: RuraHookSync<Ctx, Out>["run"], order?: number): RuraHookSync<Ctx, Out>;
-/**
- * Creates an asynchronous Rura hook.
- * - The hook will be awaited during pipeline execution.
- * - Suitable for I/O, timers, or any async workflow.
- */
-declare function createHookAsync<Ctx = unknown, Out = unknown>(name: string, run: RuraHookAsync<Ctx, Out>["run"], order?: number): RuraHookAsync<Ctx, Out>;
-
-/**
- * Final result of a pipeline execution.
- *
- * - If `early` is true, the pipeline stopped before completing all hooks.
- * - The `ctx` field always contains the context after the last executed hook.
- * - The `output` field is present only when early termination occurs.
- */
-type RuraResult<Ctx, Out> = {
-    early: true;
-    ctx: Ctx;
-    output: Out;
-} | {
-    early: false;
-    ctx: Ctx;
-    output?: never;
-};
-
-/**
- * Executes a __synchronous__ Rura pipeline.
- *
- * - Hooks are executed in order.
- * - If any hook returns `{ early: true, output }`, the pipeline
- *   stops immediately and returns the early result.
- * - Async hooks are not allowed. Detecting one will throw an error.
- *
- * @param ctx - The initial pipeline context.
- * @param hooks - A list of hooks to execute sequentially.
- * @returns A promise resolving to a `RuraResult`.
- */
-declare function run<Ctx = unknown, Out = unknown>(ctx: Ctx, hooks: RuraHook<Ctx, Out>[]): RuraResult<Ctx, Out>;
-
-/**
- * Executes an __asynchronous__ Rura pipeline.
- *
- * - Hooks are awaited in order.
- * - If any hook returns `{ early: true, output }`, the pipeline
- *   stops immediately and returns the early result.
- * - Both sync and async hooks are allowed.
- *
- * @param ctx - The initial pipeline context.
- * @param hooks - A list of hooks to execute sequentially.
- * @returns A promise resolving to a `RuraResult`.
- */
-declare function runAsync<Ctx = unknown, Out = unknown>(ctx: Ctx, hooks: RuraHook<Ctx, Out>[]): Promise<RuraResult<Ctx, Out>>;
-
-/**
- * Creates a __synchronous__ Rura pipeline.
- *
- * - Only synchronous hooks are allowed.
- * - Hooks are executed in order using `run()`.
- * - Returns a chainable pipeline instance with `use`, `merge`, `getHooks`, and `run`.
- */
-declare function createPipeline<Ctx = unknown, Out = unknown>(hooks?: RuraHook<Ctx, Out>[]): {
-    use: (h: RuraHook<Ctx, Out>) => /*elided*/ any;
-    merge: (other: {
-        getHooks(): RuraHook<Ctx, Out>[];
-    }) => /*elided*/ any;
-    getHooks: () => RuraHook<Ctx, Out>[];
-    debugHooks: (title?: ((hooks: RuraHook<Ctx, Out>[]) => string) | undefined) => void;
-    run: (ctx: Ctx) => RuraResult<Ctx, Out>;
-};
-
-/**
- * Creates an __asynchronous__ Rura pipeline.
- *
- * - Accepts both synchronous and asynchronous hooks.
- * - Hooks are awaited in order using `runAsync()`.
- * - Returns a chainable pipeline instance with `use`, `merge`, `getHooks`, and `run`.
- */
-declare function createPipelineAsync<Ctx = unknown, Out = unknown>(hooks?: RuraHook<Ctx, Out>[]): {
-    use: (h: RuraHook<Ctx, Out>) => /*elided*/ any;
-    merge: (other: {
-        getHooks(): RuraHook<Ctx, Out>[];
-    }) => /*elided*/ any;
-    getHooks: () => RuraHook<Ctx, Out>[];
-    debugHooks: (title?: ((hooks: RuraHook<Ctx, Out>[]) => string) | undefined) => void;
-    run: (ctx: Ctx) => Promise<RuraResult<Ctx, Out>>;
-};
-
-/**
- * Determines whether a given hook is asynchronous.
- *
- * A hook is considered async if its `run` function
- * is an `AsyncFunction` (i.e. declared with `async`).
- *
- * @returns `true` if the hook executes asynchronously, otherwise `false`.
- */
-declare function isAsyncHook<Ctx, Out>(hook: RuraHook<Ctx, Out>): hook is RuraHookAsync<Ctx, Out>;
-
-declare const rura: {
-    readonly createHook: typeof createHook;
-    readonly createHookAsync: typeof createHookAsync;
-    readonly run: typeof run;
-    readonly runAsync: typeof runAsync;
-    readonly createPipeline: typeof createPipeline;
-    readonly createPipelineAsync: typeof createPipelineAsync;
-    readonly isAsyncHook: typeof isAsyncHook;
-};
-
-export { type RuraHook, type RuraHookAsync, type RuraHookSync, type RuraResult, rura };
+/**
+ * Rura — The hook pipeline
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Creates a synchronous hook.
+ *
+ * The hook executes without awaiting.
+ *
+ * @public
+ */
+export declare function createHook<Ctx = unknown, Out = unknown>(name: string, run: RuraHookSync<Ctx, Out>["run"], order?: number): RuraHookSync<Ctx, Out>;
+
+/**
+ * Creates an asynchronous hook.
+ *
+ * The hook executes via `await`.
+ *
+ * @public
+ */
+export declare function createHookAsync<Ctx = unknown, Out = unknown>(name: string, run: RuraHookAsync<Ctx, Out>["run"], order?: number): RuraHookAsync<Ctx, Out>;
+
+/**
+ * Creates a synchronous Rura pipeline.
+ *
+ * The returned pipeline:
+ * - Executes hooks sequentially using a synchronous strategy.
+ * - Rejects asynchronous hooks at registration time.
+ * - Preserves deterministic ordering based on `order`.
+ *
+ * This variant guarantees that `run()` returns immediately
+ * without producing a Promise.
+ *
+ * @public
+ */
+export declare function createPipeline<Ctx = unknown, Out = unknown>(hooks?: RuraHookSync<Ctx, Out>[]): {
+    use: (hook: RuraHookSync<Ctx, Out>) => /*elided*/ any;
+    getHooks: () => RuraHookSync<Ctx, Out>[];
+    logHooks: () => void;
+    run: (ctx: Ctx) => RuraResult<Ctx, Out>;
+};
+
+/**
+ * Creates an asynchronous Rura pipeline.
+ *
+ * The returned pipeline:
+ * - Executes hooks sequentially using an async strategy.
+ * - Accepts any RuraHook, including sync and async variants.
+ * - Preserves deterministic ordering based on `order`.
+ *
+ * This variant guarantees that `run()` returns a Promise.
+ *
+ * @public
+ */
+export declare function createPipelineAsync<Ctx = unknown, Out = unknown>(hooks?: RuraHook<Ctx, Out>[]): {
+    use: (hook: RuraHook<Ctx, Out>) => /*elided*/ any;
+    getHooks: () => RuraHook<Ctx, Out>[];
+    logHooks: () => void;
+    run: (ctx: Ctx) => Promise<RuraResult<Ctx, Out>>;
+};
+
+/**
+ * Executes a synchronous Rura pipeline.
+ *
+ * Hooks are executed sequentially in the given order.
+ *
+ * Execution contract:
+ * - Each hook receives the same `ctx` reference.
+ * - If a hook returns `{ early: true, output }`,
+ *   execution stops immediately and that result is returned.
+ * - If no hook triggers early termination, a normal result
+ *   `{ early: false, ctx }` is returned.
+ *
+ * This function is strictly synchronous:
+ * - It does not produce a Promise.
+ * - Only `RuraHookSync` hooks are allowed.
+ *
+ * @public
+ */
+export declare function run<Ctx = unknown, Out = unknown>(ctx: Ctx, hooks: RuraHookSync<Ctx, Out>[]): RuraResult<Ctx, Out>;
+
+/**
+ * Executes an asynchronous Rura pipeline.
+ *
+ * Hooks are awaited sequentially in the provided order.
+ *
+ * Execution contract:
+ * - Each hook receives the same `ctx` reference.
+ * - Hooks may be synchronous or asynchronous.
+ * - If a hook resolves to `{ early: true, output }`,
+ *   execution stops immediately and that result is returned.
+ * - If no hook triggers early termination, a normal result
+ *   `{ early: false, ctx }` is returned.
+ *
+ * This function always returns a Promise.
+ *
+ * @public
+ */
+export declare function runAsync<Ctx = unknown, Out = unknown>(ctx: Ctx, hooks: RuraHook<Ctx, Out>[]): Promise<RuraResult<Ctx, Out>>;
+
+/**
+ * Rura public API namespace.
+ *
+ * Provides a cohesive entry point for:
+ *
+ * - Hook factories (`createHook`, `createHookAsync`)
+ * - Direct executors (`run`, `runAsync`)
+ * - Pipeline constructors (`createPipeline`, `createPipelineAsync`)
+ *
+ * This object contains no additional logic —
+ * it simply exposes the stable, public surface of Rura.
+ *
+ * The namespace is frozen to prevent runtime mutation.
+ *
+ * @public
+ */
+export declare const rura: Readonly<{
+    createHook: typeof createHook;
+    createHookAsync: typeof createHookAsync;
+    run: typeof run;
+    runAsync: typeof runAsync;
+    createPipeline: typeof createPipeline;
+    createPipelineAsync: typeof createPipelineAsync;
+}>;
+
+/**
+ * Union of all hook variants supported by the Rura pipeline.
+ *
+ * @public
+ */
+export declare type RuraHook<Ctx = unknown, Out = unknown> = RuraHookSync<Ctx, Out> | RuraHookAsync<Ctx, Out>;
+
+/**
+ * Asynchronous hook.
+ *
+ * Executed via `await`.
+ * The provided `ctx` may be mutated.
+ * Resolving with an early signal terminates the pipeline.
+ *
+ * @public
+ */
+export declare interface RuraHookAsync<Ctx, Out> extends RuraHookBase {
+    run(ctx: Ctx): Promise<void | {
+        early: true;
+        output: Out;
+    }>;
+}
+
+/**
+ * Base contract for all Rura hooks.
+ *
+ * A hook is an ordered execution unit within a pipeline.
+ * The `name` uniquely identifies the hook.
+ * The optional `order` controls execution priority (lower values run first).
+ *
+ * @public
+ */
+export declare interface RuraHookBase {
+    /** Unique hook identifier. */
+    name: string;
+    /** Execution priority. Lower values run earlier. */
+    order?: number;
+}
+
+/**
+ * Synchronous hook.
+ *
+ * Executed without awaiting.
+ * The provided `ctx` may be mutated.
+ * Returning an early signal terminates the pipeline.
+ *
+ * @public
+ */
+export declare interface RuraHookSync<Ctx, Out> extends RuraHookBase {
+    run(ctx: Ctx): void | {
+        early: true;
+        output: Out;
+    };
+}
+
+/**
+ * Result of a Rura pipeline execution.
+ *
+ * This type represents the final outcome of running a pipeline,
+ * either through `run` or `runAsync`.
+ *
+ * Execution semantics:
+ * - `ctx` always refers to the same context object that was
+ *   passed into the pipeline. Hooks may mutate it in place.
+ * - When `early` is `true`, execution stopped before all hooks
+ *   completed, and `output` contains the early-return value.
+ * - When `early` is `false`, all hooks were executed and no
+ *   early termination occurred. In this case, `output` is not present.
+ *
+ * The `early` field acts as a discriminant for safe narrowing.
+ *
+ * @public
+ */
+export declare type RuraResult<Ctx, Out> = {
+    early: true;
+    ctx: Ctx;
+    output: Out;
+} | {
+    early: false;
+    ctx: Ctx;
+    output?: never;
+};
+
+export { }

package/dist/index.js

@@ -1,85 +1,93 @@
+// src/hooks/internal.ts
+var ASYNC_HOOK = /* @__PURE__ */ Symbol("rura.async");
+
 // src/hooks/create-hook.ts
 function createHook(name, run2, order) {
-  return { name, run: run2, order };
+  const hook = {
+    name,
+    run: run2,
+    ...order !== void 0 ? { order } : {}
+  };
+  return hook;
 }
 function createHookAsync(name, run2, order) {
-  return { name, run: run2, order };
+  const hook = {
+    name,
+    run: run2,
+    ...order !== void 0 ? { order } : {},
+    [ASYNC_HOOK]: true
+  };
+  return hook;
 }
 
 // src/hooks/utils/is-async-hook.ts
 function isAsyncHook(hook) {
-  return hook.run.constructor.name === "AsyncFunction";
+  return hook[ASYNC_HOOK] === true;
 }
 
-// src/pipeline/create/utils/format-debug-message.ts
-var formatDebugMessage = (hooks, name, title) => {
-  if (title) {
-    console.log(`
-${title(hooks)}`);
-  } else {
-    const label = name ? ` <${name}>` : "";
-    console.log(`
-\u{1F30A} Rura Pipeline${label} (${hooks.length} hooks)`);
+// src/pipeline/create/utils/assert-sync-hook.ts
+function assertSyncHook(hook) {
+  if (isAsyncHook(hook)) {
+    throw new Error(
+      `Async hook "${hook.name}" is not allowed in sync pipeline.`
+    );
   }
-  console.log(`\u2500\u2500\u2500`);
+}
+
+// src/pipeline/create/utils/log-pipeline-hooks.ts
+function logPipelineHooks(hooks, name = "Rura") {
+  const count = hooks.length;
+  const suffix = count === 1 ? "hook" : "hooks";
+  console.log(`${name} (${count} ${suffix})`);
+  console.log("\u2500\u2500\u2500");
   hooks.forEach((hook, i) => {
     const kind = isAsyncHook(hook) ? "async" : "sync";
+    const order = hook.order ?? "-";
     console.log(
-      `${i + 1}. order:${String(hook.order).padStart(4)} | ${hook.name} (${kind})`
+      `${i + 1}. order: ${String(order).padEnd(4)} | ${hook.name} (${kind})`
     );
   });
-  console.log(`\u2500\u2500\u2500
-`);
-};
+  console.log("\u2500\u2500\u2500");
+}
 
 // src/pipeline/create/create-pipeline-base.ts
 function createPipelineBase(initialHooks, runFn, options) {
+  const isSync = options.mode === "sync";
+  if (isSync) for (const hook of initialHooks) assertSyncHook(hook);
   const name = options.name;
-  const hooks = initialHooks.map((h) => applyDefaultOrder(h));
-  function applyDefaultOrder(h) {
-    return { ...h, order: h.order ?? 0 };
-  }
+  const hooks = [...initialHooks];
   function sortHooks() {
-    hooks.sort((a, b) => a.order - b.order);
+    hooks.sort((a, b) => {
+      const ao = a.order ?? Number.POSITIVE_INFINITY;
+      const bo = b.order ?? Number.POSITIVE_INFINITY;
+      return ao - bo;
+    });
   }
-  function use(h) {
-    if (options.mode === "sync" && isAsyncHook(h)) {
-      throw new Error(`Async hook "${h.name}" is not allowed in createRura().`);
-    }
-    hooks.push(applyDefaultOrder(h));
-    sortHooks();
-    return api;
-  }
-  function merge(other) {
-    other.getHooks().forEach((h) => hooks.push(applyDefaultOrder(h)));
+  function use(hook) {
+    if (isSync) assertSyncHook(hook);
+    hooks.push(hook);
     sortHooks();
-    return api;
+    return pipeline;
   }
   function getHooks() {
     return [...hooks];
   }
-  function debugHooks(title) {
-    formatDebugMessage(hooks, name, title);
+  function logHooks() {
+    logPipelineHooks(hooks, name);
   }
   function run2(ctx) {
-    return runFn(ctx, hooks);
+    return runFn(ctx, [...hooks]);
   }
-  const api = { use, merge, getHooks, debugHooks, run: run2 };
+  const pipeline = { use, getHooks, logHooks, run: run2 };
   sortHooks();
-  return api;
+  return pipeline;
 }
 
 // src/pipeline/run/run.ts
 function run(ctx, hooks) {
   for (const hook of hooks) {
-    if (isAsyncHook(hook)) {
-      throw new Error(
-        `Async hook "${hook.name}" detected in run(). Use runAsync() instead.`
-      );
-    }
     const result = hook.run(ctx);
-    const isEarlyReturn = result && result.early === true;
-    if (isEarlyReturn) {
+    if (result?.early === true) {
       return {
         early: true,
         ctx,
@@ -93,20 +101,11 @@ function run(ctx, hooks) {
   };
 }
 
-// src/pipeline/create/create-pipeline.ts
-function createPipeline(hooks = []) {
-  return createPipelineBase(
-    hooks,
-    run,
-    { mode: "sync" }
-  );
-}
-
 // src/pipeline/run/run-async.ts
 async function runAsync(ctx, hooks) {
   for (const hook of hooks) {
     const result = await hook.run(ctx);
-    if (result && result.early === true) {
+    if (result?.early === true) {
       return {
         early: true,
         ctx,
@@ -120,6 +119,15 @@ async function runAsync(ctx, hooks) {
   };
 }
 
+// src/pipeline/create/create-pipeline.ts
+function createPipeline(hooks = []) {
+  return createPipelineBase(
+    hooks,
+    run,
+    { mode: "sync" }
+  );
+}
+
 // src/pipeline/create/create-pipeline-async.ts
 function createPipelineAsync(hooks = []) {
   return createPipelineBase(
@@ -130,18 +138,16 @@ function createPipelineAsync(hooks = []) {
 }
 
 // src/rura.ts
-var rura = {
-  // hook factories
+var rura = Object.freeze({
+  // Hook creation
   createHook,
   createHookAsync,
-  // executors
+  // Direct execution
   run,
   runAsync,
-  // pipeline constructors
+  // Pipeline construction
   createPipeline,
-  createPipelineAsync,
-  // utils
-  isAsyncHook
-};
+  createPipelineAsync
+});
 
-export { rura };
+export { createHook, createHookAsync, createPipeline, createPipelineAsync, run, runAsync, rura };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rura",
-  "version": "1.0.8",
-  "description": "🌊 A pipeline engine that flows like water.",
+  "version": "1.1.1",
+  "description": "The hook pipeline",
   "author": "Yiming Liao",
   "homepage": "https://github.com/yiming-liao/rura#readme",
   "repository": {
@@ -17,51 +17,47 @@
   },
   "keywords": [
     "pipeline",
-    "hooks",
+    "hook",
     "hook-system",
-    "pipeline-engine",
-    "flow",
-    "workflow",
     "middleware",
-    "typescript",
-    "ts",
-    "utility",
-    "functional",
     "composition",
-    "composable"
+    "functional",
+    "typescript"
   ],
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./dist/types/export/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     }
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/types/export/index.d.ts",
   "files": [
-    "dist",
+    "dist/index.*",
     "README.md",
     "LICENSE"
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=20"
   },
   "scripts": {
-    "build": "tsup",
-    "prepublishOnly": "yarn build",
-    "test": "vitest",
-    "type": "tsc --noEmit",
+    "type": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint",
-    "lint:debug": "eslint --debug",
-    "knip": "knip --config .config/knip.config.ts"
+    "test": "vitest",
+    "knip": "knip --config .config/knip.config.ts",
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "prepublishOnly": "yarn build && yarn api:check",
+    "api:build": "api-extractor run -c api-extractor/index.json --local",
+    "api:check": "api-extractor run -c api-extractor/index.json"
   },
   "dependencies": {},
   "devDependencies": {
+    "@microsoft/api-extractor": "^7.57.6",
     "@types/node": "^24.10.1",
     "@vitest/coverage-v8": "4.0.15",
     "eslint": "^9.39.1",

package/dist/index.d.cts

@@ -1,159 +0,0 @@
-/**
- * Base shape for all Rura hooks.
- * - Every hook must have a unique `name`.
- * - `order` controls execution priority (lower runs earlier).
- */
-interface RuraHookBase {
-    /** Unique identifier for debugging and inspection. */
-    name: string;
-    /** Execution priority. Hooks with lower values run first. */
-    order?: number;
-}
-/**
- * Synchronous Rura hook.
- * - Runs without awaiting.
- * - May optionally signal early termination.
- */
-interface RuraHookSync<Ctx, Out> extends RuraHookBase {
-    /**
-     * Executes the hook.
-     * @returns Nothing, or an early-return signal with output.
-     */
-    run(ctx: Ctx): void | {
-        early: true;
-        output: Out;
-    };
-}
-/**
- * Asynchronous Rura hook.
- * - Executes via `await`.
- * - May optionally signal early termination.
- */
-interface RuraHookAsync<Ctx, Out> extends RuraHookBase {
-    /**
-     * Executes the hook asynchronously.
-     * @returns A promise resolving to nothing or an early-return signal.
-     */
-    run(ctx: Ctx): Promise<void | {
-        early: true;
-        output: Out;
-    }>;
-}
-/**
- * A union of all hook types accepted by the Rura pipeline.
- */
-type RuraHook<Ctx = unknown, Out = unknown> = RuraHookSync<Ctx, Out> | RuraHookAsync<Ctx, Out>;
-
-/**
- * Creates a synchronous Rura hook.
- * - The hook will be executed without `await`.
- * - Suitable for lightweight, purely synchronous operations.
- */
-declare function createHook<Ctx = unknown, Out = unknown>(name: string, run: RuraHookSync<Ctx, Out>["run"], order?: number): RuraHookSync<Ctx, Out>;
-/**
- * Creates an asynchronous Rura hook.
- * - The hook will be awaited during pipeline execution.
- * - Suitable for I/O, timers, or any async workflow.
- */
-declare function createHookAsync<Ctx = unknown, Out = unknown>(name: string, run: RuraHookAsync<Ctx, Out>["run"], order?: number): RuraHookAsync<Ctx, Out>;
-
-/**
- * Final result of a pipeline execution.
- *
- * - If `early` is true, the pipeline stopped before completing all hooks.
- * - The `ctx` field always contains the context after the last executed hook.
- * - The `output` field is present only when early termination occurs.
- */
-type RuraResult<Ctx, Out> = {
-    early: true;
-    ctx: Ctx;
-    output: Out;
-} | {
-    early: false;
-    ctx: Ctx;
-    output?: never;
-};
-
-/**
- * Executes a __synchronous__ Rura pipeline.
- *
- * - Hooks are executed in order.
- * - If any hook returns `{ early: true, output }`, the pipeline
- *   stops immediately and returns the early result.
- * - Async hooks are not allowed. Detecting one will throw an error.
- *
- * @param ctx - The initial pipeline context.
- * @param hooks - A list of hooks to execute sequentially.
- * @returns A promise resolving to a `RuraResult`.
- */
-declare function run<Ctx = unknown, Out = unknown>(ctx: Ctx, hooks: RuraHook<Ctx, Out>[]): RuraResult<Ctx, Out>;
-
-/**
- * Executes an __asynchronous__ Rura pipeline.
- *
- * - Hooks are awaited in order.
- * - If any hook returns `{ early: true, output }`, the pipeline
- *   stops immediately and returns the early result.
- * - Both sync and async hooks are allowed.
- *
- * @param ctx - The initial pipeline context.
- * @param hooks - A list of hooks to execute sequentially.
- * @returns A promise resolving to a `RuraResult`.
- */
-declare function runAsync<Ctx = unknown, Out = unknown>(ctx: Ctx, hooks: RuraHook<Ctx, Out>[]): Promise<RuraResult<Ctx, Out>>;
-
-/**
- * Creates a __synchronous__ Rura pipeline.
- *
- * - Only synchronous hooks are allowed.
- * - Hooks are executed in order using `run()`.
- * - Returns a chainable pipeline instance with `use`, `merge`, `getHooks`, and `run`.
- */
-declare function createPipeline<Ctx = unknown, Out = unknown>(hooks?: RuraHook<Ctx, Out>[]): {
-    use: (h: RuraHook<Ctx, Out>) => /*elided*/ any;
-    merge: (other: {
-        getHooks(): RuraHook<Ctx, Out>[];
-    }) => /*elided*/ any;
-    getHooks: () => RuraHook<Ctx, Out>[];
-    debugHooks: (title?: ((hooks: RuraHook<Ctx, Out>[]) => string) | undefined) => void;
-    run: (ctx: Ctx) => RuraResult<Ctx, Out>;
-};
-
-/**
- * Creates an __asynchronous__ Rura pipeline.
- *
- * - Accepts both synchronous and asynchronous hooks.
- * - Hooks are awaited in order using `runAsync()`.
- * - Returns a chainable pipeline instance with `use`, `merge`, `getHooks`, and `run`.
- */
-declare function createPipelineAsync<Ctx = unknown, Out = unknown>(hooks?: RuraHook<Ctx, Out>[]): {
-    use: (h: RuraHook<Ctx, Out>) => /*elided*/ any;
-    merge: (other: {
-        getHooks(): RuraHook<Ctx, Out>[];
-    }) => /*elided*/ any;
-    getHooks: () => RuraHook<Ctx, Out>[];
-    debugHooks: (title?: ((hooks: RuraHook<Ctx, Out>[]) => string) | undefined) => void;
-    run: (ctx: Ctx) => Promise<RuraResult<Ctx, Out>>;
-};
-
-/**
- * Determines whether a given hook is asynchronous.
- *
- * A hook is considered async if its `run` function
- * is an `AsyncFunction` (i.e. declared with `async`).
- *
- * @returns `true` if the hook executes asynchronously, otherwise `false`.
- */
-declare function isAsyncHook<Ctx, Out>(hook: RuraHook<Ctx, Out>): hook is RuraHookAsync<Ctx, Out>;
-
-declare const rura: {
-    readonly createHook: typeof createHook;
-    readonly createHookAsync: typeof createHookAsync;
-    readonly run: typeof run;
-    readonly runAsync: typeof runAsync;
-    readonly createPipeline: typeof createPipeline;
-    readonly createPipelineAsync: typeof createPipelineAsync;
-    readonly isAsyncHook: typeof isAsyncHook;
-};
-
-export { type RuraHook, type RuraHookAsync, type RuraHookSync, type RuraResult, rura };