✨ react-loop-z

LIVE EXAMPLE

---

react-loop-z is a lightweight, type-safe, declarative looping toolkit for React.

It helps you replace .map() chains and manual iteration logic with clean, expressive JSX blocks.

Write loops like logic. Render JSX like structure.

---

📖 Why react-loop-z?

• Declarative JSX loops
• Strict TypeScript support
• Zero dependencies
• Tree-shakable
• Infinite loop protection (safe guards)
• SSR & StrictMode safe
• Tiny bundle size

---

🧠 Mental Model

• Pure function components
• No internal state machines
• No proxies or runtime magic
• Strict generic typing
• Guard-based loop safety

Each loop is an independent, tree-shakable unit. Import only what you use.

---

📦 Installation

npm install react-loop-z

---

🚀 Usage

🔁 For (Array iteration)

import { For } from "react-loop-z";

<For
  of={["foo", "bar"]}
>
  {(item, index) => (
    <span key={index}>Hello, {item}</span>
  )}
</For>

Type-safe example:

type User = { id: number; name: string };

<For<User> of={users}>
  {(user) => <div key={user.id}>{user.name}</div>}
</For>

---

🔢 Range / Numeric Loop

import { RangeLoop } from "react-loop-z";

<RangeLoop from={0} to={5}>
  {(i) => <div key={i}>{i}</div>}
</RangeLoop>

---

🔂 While

import { While } from "react-loop-z";

let i = 0;

<While
  condition={() => i++ < 3}
>
  {(index) => <div key={index}>Count {index}</div>}
</While>

---

🔄 Do

import { Do } from "react-loop-z";

let i = 0;

<Do
  condition={() => i < 3}
>
  {(index) => {
    i++;
    return <div key={index}>Count {index}</div>;
  }}
</Do>

---

🗺️ MapLoop

import { MapLoop } from "react-loop-z";

<MapLoop of={new Map([["a", 1], ["b", 2]])}>
  {(value, key) => (
    <div key={key}>
      {key}: {value}
    </div>
  )}
</MapLoop>

---

🧩 SetLoop

import { SetLoop } from "react-loop-z";

<SetLoop of={new Set(["foo", "bar"])}>
  {(item) => <div key={item}>{item}</div>}
</SetLoop>

---

🗂️ ObjectLoop

import { ObjectLoop } from "react-loop-z";

<ObjectLoop of={{ a: 1, b: 2 }}>
  {(value, key) => (
    <div key={key}>
      {key}: {value}
    </div>
  )}
</ObjectLoop>

---

🛡 Infinite Loop Protection

While, Do, and numeric loops include safety guards to prevent runaway infinite loops in development.

Always ensure your condition eventually becomes false.

---

🔥 BreakableLoop

Declarative loop with early exit support (like break in JavaScript).

<BreakableLoop items={users}>
  {(user, { breakLoop }) => {
    if (!user.active) breakLoop()
    return <UserCard user={user} />
  }}
</BreakableLoop>

---

🔎 FilterLoop

Render conditionally without chaining .filter().map().

<FilterLoop items={products} when={(p) => p.inStock}>
  {(product) => <ProductItem product={product} />}
</FilterLoop>

---

🧱 ChunkLoop

Split an array into chunks (ideal for grid or row rendering).

<ChunkLoop items={posts} size={3}>
  {(chunk) => (
    <div className="row">
      {chunk.map(post => <PostCard key={post.id} {...post} />)}
    </div>
  )}
</ChunkLoop>

---

✂️ TakeLoop

Render only the first N elements (lightweight alternative to slice).

<TakeLoop items={messages} count={5}>
  {(msg) => <MessageItem message={msg} />}
</TakeLoop>

---

🧬 UniqueLoop

Remove duplicates by key selector before rendering.

<UniqueLoop items={users} by={(u) => u.email}>
  {(user) => <UserRow user={user} />}
</UniqueLoop>

---

📦 FlatLoop

Flatten nested arrays before rendering.

<FlatLoop items={nestedComments}>
  {(comment) => <CommentItem comment={comment} />}
</FlatLoop>

---

⏳ AsyncLoop

Supports async iterables, promises, or async generators with built-in async handling.

<AsyncLoop items={fetchUsers()}>
  {(user) => <UserCard user={user} />}
</AsyncLoop>

Or:

<AsyncLoop items={asyncGenerator()}>
  {(value) => <div>{value}</div>}
</AsyncLoop>

---

⚡ Core Numeric Loops

RangeLoop

Declarative numeric range loop.

<RangeLoop from={1} to={5}>
  {(i) => <div>{i}</div>}
</RangeLoop>

---

TimesLoop

Render N times (simple repeat utility).

<TimesLoop times={3}>
  {(index) => <Skeleton key={index} />}
</TimesLoop>

---

📊 Comparison

Feature	react-loop-z	react-loops	react-for	Native .map()
Declarative JSX Blocks	✅	✅	✅	❌
Strong TypeScript Inference	✅	⚠️ Partial	⚠️	⚠️ Manual
Array Loop	✅	✅	✅	✅
Numeric / Range Loop	✅	❌	⚠️	❌
While / Do Loop	✅	⚠️	⚠️	❌
Map / Set / Object Support	✅	✅ Iterable	⚠️	⚠️ Manual
Break Control	✅	❌	❌	❌
Async Loop	✅	❌	❌	❌
Infinite Loop Protection	✅	❌	❌	❌
Zero Runtime Dependencies	✅	❌	⚠️	✅
Tree-Shakable	✅	❌	❌	✅

A declarative loop control system for React — not just array mapping.

---

🎯 Philosophy

• Keep rendering pure
• Keep iteration declarative
• Keep bundle tiny
• Keep logic readable

Iteration belongs to structure, not utility chains.

---

🏁 Final Thought

react-loop-z is not trying to replace .map().

It provides:

• Structure-driven iteration
• Declarative control flow
• Composable loop primitives

Think of it as: Control flow components for React.

---

📄 License

MIT