rura 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yiming Liao
+
+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,139 @@
+<h1 align="center">Rura</h1>
+
+<div align="center">
+
+A minimal **pipeline engine** for every modern workflow.
+
+</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)
+
+</div>
+
+> Clarity meets 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.
+
+## Installation
+
+```bash
+# npm
+npm install rura
+# yarn
+yarn add rura
+# pnpm
+pnpm add rura
+```
+
+## Quick Start
+
+#### 1. Define the initial context
+
+```ts
+const ctx = { count: 1 };
+type Ctx = typeof ctx;
+```
+
+#### 2. Create your hooks
+
+- Hooks can be defined with `createHook` or manually via the `Hook` type.
+- Hooks may specify an `order`; omitted values default to `0`.
+
+```ts
+// 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> = {
+  name: "stop-if-even",
+  run: (ctx) => {
+    if (ctx.count % 2 === 0) {
+      return { done: true, output: ctx.count };
+    }
+  },
+  order: 2, // order: 2
+};
+```
+
+> Rura executes hooks in order and exits early when a hook returns `{ done: true }`.
+
+#### 3. Run the pipeline
+
+```ts
+const result = await runRura(ctx, [addOne, stopIfEven]);
+
+console.log(result); // -> 2 (early exit triggered)
+```
+
+---
+
+## Pipeline Builder
+
+**createRura()** - Creates a lightweight, composable pipeline instance.
+
+```ts
+const rura = createRura<Context, Output>();
+
+// Add hooks
+rura
+  .use(hookA) // chainable
+  .use(hookB)
+  .use(hookC);
+```
+
+example:
+
+```ts
+import { createRura } from "rura";
+
+type Ctx = { value: number };
+
+// Create a pipeline
+const pipelineA = createRura<Ctx>();
+
+pipelineA.use({
+  name: "add-two",
+  run: (ctx) => {
+    ctx.value += 2;
+  },
+});
+
+// Create another pipeline
+const pipelineB = createRura<Ctx>();
+
+pipelineB.use({
+  name: "multiply-three",
+  run: (ctx) => {
+    ctx.value *= 3;
+  },
+});
+
+// Merge pipelines
+const pipeline = pipelineA.merge(pipelineB);
+
+// Run it
+const result = await pipeline.run({ value: 1 });
+
+console.log(result); // -> { 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>` |

package/dist/index.cjs

@@ -0,0 +1,48 @@
+'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;
+    }
+  }
+  return ctx;
+}
+
+// src/create-rura.ts
+function createRura() {
+  const hooks = [];
+  function use(hook) {
+    hooks.push(hook);
+    return api;
+  }
+  function merge(other) {
+    other.getHooks().forEach((h) => hooks.push(h));
+    return api;
+  }
+  function getHooks() {
+    return hooks;
+  }
+  async function run(ctx) {
+    return runRura(ctx, hooks);
+  }
+  const api = { use, merge, getHooks, run };
+  return api;
+}
+
+// src/create-hook.ts
+function createHook(name, run, order) {
+  return { name, run, order };
+}
+
+exports.createHook = createHook;
+exports.createRura = createRura;
+exports.runRura = runRura;

package/dist/index.d.cts

@@ -0,0 +1,23 @@
+type MaybePromise<T> = T | Promise<T>;
+interface Done<Output> {
+    done: true;
+    output: Output;
+}
+interface Hook<Context, Output> {
+    name: string;
+    order?: number;
+    run(ctx: Context): MaybePromise<void | Done<Output>>;
+}
+
+declare function runRura<Context = unknown, Output = unknown>(ctx: Context, hooks: Hook<Context, Output>[]): Promise<Output | Context>;
+
+declare function createRura<Context = unknown, Output = unknown>(): {
+    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>;
+};
+
+declare function createHook<Context = unknown, Output = unknown>(name: string, run: Hook<Context, Output>["run"], order?: number): Hook<Context, Output>;
+
+export { type Hook, createHook, createRura, runRura };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+type MaybePromise<T> = T | Promise<T>;
+interface Done<Output> {
+    done: true;
+    output: Output;
+}
+interface Hook<Context, Output> {
+    name: string;
+    order?: number;
+    run(ctx: Context): MaybePromise<void | Done<Output>>;
+}
+
+declare function runRura<Context = unknown, Output = unknown>(ctx: Context, hooks: Hook<Context, Output>[]): Promise<Output | Context>;
+
+declare function createRura<Context = unknown, Output = unknown>(): {
+    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>;
+};
+
+declare function createHook<Context = unknown, Output = unknown>(name: string, run: Hook<Context, Output>["run"], order?: number): Hook<Context, Output>;
+
+export { type Hook, createHook, createRura, runRura };

package/dist/index.js

@@ -0,0 +1,44 @@
+// 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;
+    }
+  }
+  return ctx;
+}
+
+// src/create-rura.ts
+function createRura() {
+  const hooks = [];
+  function use(hook) {
+    hooks.push(hook);
+    return api;
+  }
+  function merge(other) {
+    other.getHooks().forEach((h) => hooks.push(h));
+    return api;
+  }
+  function getHooks() {
+    return hooks;
+  }
+  async function run(ctx) {
+    return runRura(ctx, hooks);
+  }
+  const api = { use, merge, getHooks, run };
+  return api;
+}
+
+// src/create-hook.ts
+function createHook(name, run, order) {
+  return { name, run, order };
+}
+
+export { createHook, createRura, runRura };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "rura",
+  "version": "0.0.0",
+  "description": "A minimal pipeline engine for every modern workflow.",
+  "author": "Yiming Liao",
+  "license": "MIT",
+  "homepage": "https://github.com/yiming-liao/rura#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yiming-liao/rura.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yiming-liao/rura/issues"
+  },
+  "keywords": [],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "yarn build",
+    "test": "vitest",
+    "type": "tsc --noEmit",
+    "lint": "eslint",
+    "lint:debug": "eslint --debug",
+    "knip": "knip --config .config/knip.config.ts"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "4.0.15",
+    "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",
+    "knip": "^5.69.1",
+    "prettier": "^3.6.2",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.46.4",
+    "vitest": "^4.0.9"
+  }
+}