🚀📦 hbh-proxies

hbh-proxies is a lightweight, proxy-based utility toolkit for JavaScript and Node.js that enables fluent, chainable APIs for:

• ✨ Dynamic CSS generation (CSS-in-JS)
• 🔗 Proxy-driven function pipelines
• 🧩 Declarative, readable code without builders or config objects

This package heavily leverages JavaScript Proxy objects to create expressive, extensible APIs with minimal boilerplate.

---

⚡🚀 Installation

          
            1npm install hbh-proxies
          
        

---

📦📂 Package Exports

          
            1import { Builder, CSS } from "hbh-proxies";
          
        

📤 Export Map

---

🧠⚙️ ProxyBuilder (Generic Pipeline Builder)

The ProxyBuilder allows you to create chainable function pipelines dynamically.

---

✨📌 Basic Usage

          
            1import { Builder } from "hbh-proxies";3const api = new Builder()4  .use("upper", s => s.toUpperCase())5  .use("exclaim", s => s + "!")6  .use("repeat", (s, n) => s.repeat(n));8api.upper.exclaim.repeat("hello", 2);9// → "HELLO!HELLO!"
          
        

---

🔗🧩 How It Works

Each chained property corresponds to a function stored in an internal map. When the proxy is invoked, each function runs in order.

          
            1api.upper.exclaim("test")2// upper → exclaim → result
          
        

---

🧩🛠 Supported Invocation Styles

▶️ Normal Call

          
            1api.upper("hello")
          
        

🏷 Tagged Template

          
            1api.upper`hello world`
          
        

🧪 Explicit Execution

          
            1api.upper.exclaim.done("hello")2api.upper.exclaim.run("hello")3api.upper.exclaim.pipe("hello")
          
        

---

⏱⚡ Async Pipelines

If your functions return promises:

          
            1api.use("delay", async s => {2  await new Promise(r => setTimeout(r, 100));3  return s + " done";4});6await api.delay.asyncDone("task");
          
        

---

🔍📜 Introspection

          
            1api.upper.exclaim.steps2// → ["upper", "exclaim"]
          
        

---

⚠️🚫 Error Handling

Accessing an undefined method throws:

          
            1api.unknown("test");2// Error: Method "unknown" not found.
          
        

---

🎨🖌 CSSProxyBuilder (CSS-in-JS)

CSS.Builder provides a declarative, chainable API for building CSS with:

• 🧱 Nested selectors
• 📱 Media queries
• 🎞 Keyframes
• 🧬 Vendor prefixing
• 🧹 Optional minification

---

✨🎯 Basic Example

          
            1import { CSS } from "hbh-proxies";3const css = new CSS.Builder()4  .button({5    padding: "10px",6    background: "blue",7    color: "white"8  })9  .button.hover({10    background: "darkblue"11  })12  .all;14console.log(css);
          
        

🖨 Output

          
            1button { padding: 10px; background: blue; color: white; }2button:hover { background: darkblue; }
          
        

---

🔗📐 Selector Chaining

Pseudo-selectors (:hover, :active, etc.) automatically attach without spaces.

---

🎯🧩 Applying Styles

You apply styles by calling the proxy:

          
            1.div({2  margin: "0",3  padding: "0"4})
          
        

---

📱🌐 Media Queries

Media queries are declared using keys starting with @media.

          
            1.container({2  width: "100%",3  "@media (max-width: 600px)": {4    width: "90%"5  }6})
          
        

🖨 Output

          
            1container { width: 100%; }2@media (max-width: 600px) {3  container { width: 90%; }4}
          
        

---

🎞✨ Keyframes

          
            1const css = new CSS.Builder()2  .keyframes("fadeIn", {3    from: { opacity: 0 },4    to: { opacity: 1 }5  })6  .box({7    animation: "fadeIn 1s ease-in"8  })9  .all;
          
        

🖨 Output

          
            1box { animation: fadeIn 1s ease-in; }3@keyframes fadeIn {4  from { opacity: 0; }5  to { opacity: 1; }6}
          
        

---

🧬🔧 Vendor Prefixing

Vendor prefixes are automatically applied to known properties:

          
            1.box({2  transform: "scale(1.2)"3})
          
        

🖨 Output

          
            1box {2  -webkit-transform: scale(1.2);3  -moz-transform: scale(1.2);4  -ms-transform: scale(1.2);5  -o-transform: scale(1.2);6  transform: scale(1.2);7}
          
        

📦 Prefix Data

          
            1CSS.Prefixers.Props     // Set of prefixed properties2CSS.Prefixers.Prefixes // ['-webkit-', '-moz-', '-ms-', '-o-']
          
        

---

🧹⚡ Minification

▶️ Enable Minification

          
            1const css = new CSS.Builder()2  .minify()3  .card({4    padding: "10px",5    border: "1px solid #000"6  })7  .all;
          
        

🖨 Output

          
            1card{padding:10px;border:1px solid #000}
          
        

---

🛠🧪 Standalone Minifier

          
            1import { CSS } from "hbh-proxies";3CSS.Minify(`4  /* comment */5  .box {6    padding: 10px;7    margin: 0;8  }9`);
          
        

---

📤📄 Retrieving CSS

---

📚 Proxies

The hbh-proxies package ships with utility libraries exposed via Proxies:

          
            1import { Proxies } from "hbh-proxies";2const { HBHChalk, HBHString, DataConverter } = Proxies;
          
        

---

1️⃣ DataConverter

Purpose: Convert between common data types (strings, numbers, arrays, booleans, JSON).

Key Methods:

Usage Example:

          
            1DataConverter.strToArray("hello");2// → ['h','e','l','l','o']4DataConverter.strToBool("Yes");5// → true7DataConverter.parseJSON('{"a":1}');8// → { a: 1 }
          
        

---

2️⃣ HBHChalk

Purpose: Terminal string styling (colors, backgrounds, styles, RGB/Hex).

Features:

Usage Example:

          
            1HBHChalk.red.bold("Error!");2HBHChalk.hex("#ff8800")("Warning");3HBHChalk.bgRgb(0,128,255)("Hello Background");4HBHChalk.strip("\x1b[31mRed\x1b[0m");5// → "Red"
          
        

---

3️⃣ HBHString

Purpose: Chainable string utilities for case conversion, trimming, formatting, encoding, and more.

Key Features:

Usage Example:

          
            1HBHString.toUpper("hello"); 2// → "HELLO"4HBHString.toCamelCase("hello world"); 5// → "helloWorld"7HBHString.removeVowels("beautiful"); 8// → "btfl"10HBHString.slugify("Héllö Wörld!"); 11// → "hello-world"13HBHString.shout("hey"); 14// → "HEY!!!"16HBHString.binary("AB"); 17// → "1000001 1000010"
          
        

---

These libraries are fully chainable thanks to ProxyBuilder. Each method can be called directly, or combined in a pipeline:

          
            1HBHString.toUpper.removeVowels("hello world");2// → "HLL WRLD"4DataConverter.strToArrayByComma.strToInt(["1","2","3"]);5// → [1, 2, 3]
          
        

---

🧠🧬 Internal Design Notes

• All builders are immutable
• Each chain returns a new proxy
• CSS blocks are accumulated safely
• No DOM or browser dependencies
• Works in Node.js and browsers

---

🧪🌍 Compatibility

• Node.js ≥ 14
• Modern browsers with Proxy support
• ESM only (type: module recommended)

---

📄🪪 License

ISC © HBH

---

✅📊 Summary