rura 1.0.2 → 1.0.4

package/README.md

@@ -49,38 +49,51 @@ type Ctx = typeof ctx;
 - Hooks may specify an `order`; omitted values default to `0`.
 
 ```ts
+import { createHook, type RuraHook } from "rura";
+
 // With createHook (recommended for convenience)
 const addOne = createHook<Ctx>("add-one", (ctx) => {
   ctx.count += 1;
 }); // order: 0
 
 // Manual hook definition (full control)
-const stopIfEven: Hook<Ctx, number> = {
+const stopIfEven: RuraHook<Ctx, number> = {
   name: "stop-if-even",
   run: (ctx) => {
     if (ctx.count % 2 === 0) {
-      return { done: true, output: ctx.count };
+      return { early: true, output: ctx.count };
     }
   },
   order: 2, // order: 2
 };
 ```
 
-> Rura executes hooks in order and exits early when a hook returns `{ done: true }`.
+- Rura executes hooks in order and exits early when a hook returns `{ early: true, output }`.
+
+- When the pipeline does not exit early, `output` is omitted and `early` becomes `false`.
 
 #### 3. Run the pipeline
 
 ```ts
 const result = await runRura(ctx, [addOne, stopIfEven]);
 
-console.log(result); // -> 2 (early exit triggered)
+console.log(result);
+// -> {
+//      early: true,
+//      ctx: { count: 2 },
+//      output: 2
+//    }
 ```
 
+_If you prefer working with a reusable pipeline instance,  
+you can use the **Pipeline Builder**, introduced below:_
+
 ---
 
 ## Pipeline Builder
 
-**createRura()** - Creates a lightweight, composable pipeline instance.
+**createRura()** - Creates a lightweight, composable pipeline instance  
+that can register hooks, merge with other pipelines, and be inspected.
 
 ```ts
 const rura = createRura<Context, Output>();
@@ -125,14 +138,19 @@ const pipeline = pipelineA.merge(pipelineB);
 // Run it
 const result = await pipeline.run({ value: 1 });
 
-console.log(result); // -> { value: 9 }
+console.log(result);
+// -> {
+//      early: false,
+//      ctx: { value: 9 }
+//    }
 ```
 
 #### Pipeline Instance Methods
 
-| Method           | Description                                          | Parameters | Returns                      |
-| ---------------- | ---------------------------------------------------- | ---------- | ---------------------------- |
-| **use(hook)**    | Adds a hook to the pipeline.                         | `hook`     | `this` (chainable)           |
-| **merge(other)** | Merges hooks from another pipeline instance.         | `other`    | `this` (chainable)           |
-| **getHooks()**   | Returns all registered hooks.                        | –          | `Hook[]`                     |
-| **run(ctx)**     | Executes the pipeline **_(equivalent to runRura)_**. | `ctx`      | `Promise<Output \| Context>` |
+| 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 (delegates to `runRura`).        | `ctx`      | `Promise<RuraResult>` |

package/dist/index.cjs

@@ -1,40 +1,61 @@
 'use strict';
 
-// src/is-done.ts
-function isDone(r) {
-  return typeof r === "object" && r !== null && "done" in r;
-}
-
 // src/run-rura.ts
 async function runRura(ctx, hooks) {
-  hooks.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
   for (const hook of hooks) {
     const result = await hook.run(ctx);
-    if (isDone(result)) {
-      return result.output;
+    const isEarlyReturn = result && result.early === true;
+    if (isEarlyReturn) {
+      return {
+        early: true,
+        ctx,
+        output: result.output
+      };
     }
   }
-  return ctx;
+  return {
+    early: false,
+    ctx
+  };
 }
 
 // src/create-rura.ts
 function createRura(initialHooks = []) {
-  const hooks = [...initialHooks];
+  const hooks = [...initialHooks].map((h) => applyDefaultOrder(h));
+  function applyDefaultOrder(h) {
+    return { ...h, order: h.order ?? 0 };
+  }
+  function sortHooks() {
+    hooks.sort((a, b) => a.order - b.order);
+  }
   function use(hook) {
-    hooks.push(hook);
+    hooks.push(applyDefaultOrder(hook));
+    sortHooks();
     return api;
   }
   function merge(other) {
-    other.getHooks().forEach((h) => hooks.push(h));
+    other.getHooks().forEach((h) => hooks.push(applyDefaultOrder(h)));
+    sortHooks();
     return api;
   }
   function getHooks() {
-    return hooks;
+    return [...hooks];
+  }
+  function debugHooks() {
+    console.log(`
+\u{1F4A7} Rura Pipeline (${hooks.length} hooks)`);
+    console.log("\u2500\u2500\u2500");
+    hooks.forEach(({ name, order }, i) => {
+      const paddedOrder = String(order).padStart(4, " ");
+      console.log(`${i + 1}. order: ${paddedOrder} | name: ${name}`);
+    });
+    console.log("\u2500\u2500\u2500\n");
   }
   async function run(ctx) {
     return runRura(ctx, hooks);
   }
-  const api = { use, merge, getHooks, run };
+  const api = { use, merge, getHooks, debugHooks, run };
+  sortHooks();
   return api;
 }
 

package/dist/index.d.cts

@@ -1,23 +1,83 @@
-type MaybePromise<T> = T | Promise<T>;
-interface Done<Output> {
-    done: true;
-    output: Output;
-}
-interface Hook<Context = unknown, Output = unknown> {
+/**
+ * The return type of a Rura hook.
+ *
+ * - Return `void` to continue the pipeline.
+ * - Return `{ early: true, output }` to stop the pipeline immediately.
+ *
+ * Supports both sync and async forms.
+ */
+type RuraHookResult<Out> = void | {
+    early: true;
+    output: Out;
+} | Promise<void | {
+    early: true;
+    output: Out;
+}>;
+/**
+ * A single pipeline hook.
+ *
+ * Hooks receive the current context and may:
+ * - mutate it and continue, or
+ * - return `{ early: true, output }` to exit the pipeline early.
+ */
+interface RuraHook<Ctx = unknown, Out = unknown> {
+    /** Unique name for debugging and inspection. */
     name: string;
+    /** Executes the hook. */
+    run(ctx: Ctx): RuraHookResult<Out>;
+    /** Optional execution order. Lower values run first. */
     order?: number;
-    run(ctx: Context): MaybePromise<void | Done<Output>>;
+}
+/**
+ * Final result of a pipeline execution.
+ *
+ * - If `early` is true, the pipeline stopped before completing all hooks.
+ * - The `ctx` field always contains the final context.
+ * - The `output` field appears only when early termination occurs.
+ */
+interface RuraResult<Ctx, Out> {
+    /** Indicates whether the pipeline exited early. */
+    early: boolean;
+    /** The final context after all executed hooks. */
+    ctx: Ctx;
+    /** The output value when the pipeline ends early. */
+    output?: Out;
 }
 
-declare function runRura<Context = unknown, Output = unknown>(ctx: Context, hooks: Hook<Context, Output>[]): Promise<Output | Context>;
+/**
+ * Executes a list of hooks in order.
+ * - Stops early when a hook returns `{ early: true, output }`.
+ *
+ * @returns A `RuraResult` describing whether the pipeline ended early
+ *          and the final context/output.
+ */
+declare function runRura<Ctx = unknown, Out = unknown>(ctx: Ctx, hooks: RuraHook<Ctx, Out>[]): Promise<RuraResult<Ctx, Out>>;
 
-declare function createRura<Context = unknown, Output = unknown>(initialHooks?: Hook<Context, Output>[]): {
-    use: (hook: Hook<Context, Output>) => /*elided*/ any;
-    merge: (other: ReturnType<typeof createRura<Context, Output>>) => /*elided*/ any;
-    getHooks: () => Hook<Context, Output>[];
-    run: (ctx: Context) => Promise<Context | Output>;
+/**
+ * Creates a reusable pipeline instance.
+ * Hooks can be registered, merged, inspected, and executed in order.
+ *
+ * @param initialHooks - Optional list of hooks to initialize the pipeline with.
+ *
+ * @returns An API for managing and running the pipeline.
+ */
+declare function createRura<Ctx = unknown, Out = unknown>(initialHooks?: RuraHook<Ctx, Out>[]): {
+    use: (hook: RuraHook<Ctx, Out>) => /*elided*/ any;
+    merge: (other: ReturnType<typeof createRura<Ctx, Out>>) => /*elided*/ any;
+    getHooks: () => RuraHook<Ctx, Out>[];
+    debugHooks: () => void;
+    run: (ctx: Ctx) => Promise<RuraResult<Ctx, Out>>;
 };
 
-declare function createHook<Context = unknown, Output = unknown>(name: string, run: Hook<Context, Output>["run"], order?: number): Hook<Context, Output>;
+/**
+ * Creates a pipeline hook.
+ *
+ * @param name  - Unique name for debugging and inspection.
+ * @param run   - Hook implementation.
+ * @param order - Optional execution order. Lower values run first.
+ *
+ * @returns A normalized `RuraHook` object.
+ */
+declare function createHook<Ctx = unknown, Out = unknown>(name: string, run: RuraHook<Ctx, Out>["run"], order?: number): RuraHook<Ctx, Out>;
 
-export { type Hook, createHook, createRura, runRura };
+export { type RuraHook, type RuraHookResult, type RuraResult, createHook, createRura, runRura };

package/dist/index.d.ts

@@ -1,23 +1,83 @@
-type MaybePromise<T> = T | Promise<T>;
-interface Done<Output> {
-    done: true;
-    output: Output;
-}
-interface Hook<Context = unknown, Output = unknown> {
+/**
+ * The return type of a Rura hook.
+ *
+ * - Return `void` to continue the pipeline.
+ * - Return `{ early: true, output }` to stop the pipeline immediately.
+ *
+ * Supports both sync and async forms.
+ */
+type RuraHookResult<Out> = void | {
+    early: true;
+    output: Out;
+} | Promise<void | {
+    early: true;
+    output: Out;
+}>;
+/**
+ * A single pipeline hook.
+ *
+ * Hooks receive the current context and may:
+ * - mutate it and continue, or
+ * - return `{ early: true, output }` to exit the pipeline early.
+ */
+interface RuraHook<Ctx = unknown, Out = unknown> {
+    /** Unique name for debugging and inspection. */
     name: string;
+    /** Executes the hook. */
+    run(ctx: Ctx): RuraHookResult<Out>;
+    /** Optional execution order. Lower values run first. */
     order?: number;
-    run(ctx: Context): MaybePromise<void | Done<Output>>;
+}
+/**
+ * Final result of a pipeline execution.
+ *
+ * - If `early` is true, the pipeline stopped before completing all hooks.
+ * - The `ctx` field always contains the final context.
+ * - The `output` field appears only when early termination occurs.
+ */
+interface RuraResult<Ctx, Out> {
+    /** Indicates whether the pipeline exited early. */
+    early: boolean;
+    /** The final context after all executed hooks. */
+    ctx: Ctx;
+    /** The output value when the pipeline ends early. */
+    output?: Out;
 }
 
-declare function runRura<Context = unknown, Output = unknown>(ctx: Context, hooks: Hook<Context, Output>[]): Promise<Output | Context>;
+/**
+ * Executes a list of hooks in order.
+ * - Stops early when a hook returns `{ early: true, output }`.
+ *
+ * @returns A `RuraResult` describing whether the pipeline ended early
+ *          and the final context/output.
+ */
+declare function runRura<Ctx = unknown, Out = unknown>(ctx: Ctx, hooks: RuraHook<Ctx, Out>[]): Promise<RuraResult<Ctx, Out>>;
 
-declare function createRura<Context = unknown, Output = unknown>(initialHooks?: Hook<Context, Output>[]): {
-    use: (hook: Hook<Context, Output>) => /*elided*/ any;
-    merge: (other: ReturnType<typeof createRura<Context, Output>>) => /*elided*/ any;
-    getHooks: () => Hook<Context, Output>[];
-    run: (ctx: Context) => Promise<Context | Output>;
+/**
+ * Creates a reusable pipeline instance.
+ * Hooks can be registered, merged, inspected, and executed in order.
+ *
+ * @param initialHooks - Optional list of hooks to initialize the pipeline with.
+ *
+ * @returns An API for managing and running the pipeline.
+ */
+declare function createRura<Ctx = unknown, Out = unknown>(initialHooks?: RuraHook<Ctx, Out>[]): {
+    use: (hook: RuraHook<Ctx, Out>) => /*elided*/ any;
+    merge: (other: ReturnType<typeof createRura<Ctx, Out>>) => /*elided*/ any;
+    getHooks: () => RuraHook<Ctx, Out>[];
+    debugHooks: () => void;
+    run: (ctx: Ctx) => Promise<RuraResult<Ctx, Out>>;
 };
 
-declare function createHook<Context = unknown, Output = unknown>(name: string, run: Hook<Context, Output>["run"], order?: number): Hook<Context, Output>;
+/**
+ * Creates a pipeline hook.
+ *
+ * @param name  - Unique name for debugging and inspection.
+ * @param run   - Hook implementation.
+ * @param order - Optional execution order. Lower values run first.
+ *
+ * @returns A normalized `RuraHook` object.
+ */
+declare function createHook<Ctx = unknown, Out = unknown>(name: string, run: RuraHook<Ctx, Out>["run"], order?: number): RuraHook<Ctx, Out>;
 
-export { type Hook, createHook, createRura, runRura };
+export { type RuraHook, type RuraHookResult, type RuraResult, createHook, createRura, runRura };

package/dist/index.js

@@ -1,38 +1,59 @@
-// src/is-done.ts
-function isDone(r) {
-  return typeof r === "object" && r !== null && "done" in r;
-}
-
 // src/run-rura.ts
 async function runRura(ctx, hooks) {
-  hooks.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
   for (const hook of hooks) {
     const result = await hook.run(ctx);
-    if (isDone(result)) {
-      return result.output;
+    const isEarlyReturn = result && result.early === true;
+    if (isEarlyReturn) {
+      return {
+        early: true,
+        ctx,
+        output: result.output
+      };
     }
   }
-  return ctx;
+  return {
+    early: false,
+    ctx
+  };
 }
 
 // src/create-rura.ts
 function createRura(initialHooks = []) {
-  const hooks = [...initialHooks];
+  const hooks = [...initialHooks].map((h) => applyDefaultOrder(h));
+  function applyDefaultOrder(h) {
+    return { ...h, order: h.order ?? 0 };
+  }
+  function sortHooks() {
+    hooks.sort((a, b) => a.order - b.order);
+  }
   function use(hook) {
-    hooks.push(hook);
+    hooks.push(applyDefaultOrder(hook));
+    sortHooks();
     return api;
   }
   function merge(other) {
-    other.getHooks().forEach((h) => hooks.push(h));
+    other.getHooks().forEach((h) => hooks.push(applyDefaultOrder(h)));
+    sortHooks();
     return api;
   }
   function getHooks() {
-    return hooks;
+    return [...hooks];
+  }
+  function debugHooks() {
+    console.log(`
+\u{1F4A7} Rura Pipeline (${hooks.length} hooks)`);
+    console.log("\u2500\u2500\u2500");
+    hooks.forEach(({ name, order }, i) => {
+      const paddedOrder = String(order).padStart(4, " ");
+      console.log(`${i + 1}. order: ${paddedOrder} | name: ${name}`);
+    });
+    console.log("\u2500\u2500\u2500\n");
   }
   async function run(ctx) {
     return runRura(ctx, hooks);
   }
-  const api = { use, merge, getHooks, run };
+  const api = { use, merge, getHooks, debugHooks, run };
+  sortHooks();
   return api;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rura",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "💧 A pipeline engine that flows like water.",
   "author": "Yiming Liao",
   "license": "MIT",