🚀 Feats

A lightweight TypeScript library offering a collection of versatile helper functions and React hooks—perfect for both React and non-React projects.

✨ Features

• 🧱 Text Builder - Fluent string building with conditional logic
• 🛠️ Type-Safe Switcher - Powerful alternative to switch statements
• ⏱️ Duration Utilities - Immutable duration objects with conversions
• ⚛️ React Hooks - useTimeout and useInterval with manual control
• 🔧 Array & Object Utils - Extended prototypes with useful methods
• 📦 Zero Dependencies - Lightweight and tree-shakeable
• 🔒 TypeScript First - Full type safety and IntelliSense support

📦 Installation

1npm install feats
2# or
3yarn add feats
4# or
5pnpm add feats

🚀 Quick Start

1import { text, switcher, duration, useTimeout } from 'feats';
2
3// Text building
4const message = text()
5  .add("Hello")
6  .space()
7  .add("World!")
8  .if(user.isAdmin, (builder) => {
9    builder.newLine().add("You have admin access.");
10  })
11  .done();
12
13// Type-safe switching
14const status = switcher(user.role)
15  .case("admin", "full-access")
16  .case("user", "limited-access")
17  .default("read-only");
18
19// Duration utilities
20const timeout = duration(30, "seconds");
21const inMs = timeout.milliseconds; // 30000
22const inMinutes = timeout.as("minutes"); // 0.5

📚 Documentation

🧱 Text Builder

Build strings fluently with conditional logic and formatting:

1import { text } from 'feats';
2
3// Basic usage
4const greeting = text()
5  .add("Hello")
6  .space()
7  .add("World!")
8  .newLine()
9  .add("Welcome to our app!")
10  .done();
11
12// Conditional text
13const welcomeMessage = text()
14  .add(`Welcome, ${user.name}!`)
15  .if(user.isAdmin, (builder) => {
16    builder.newLine().add("You have admin privileges.");
17  })
18  .if(user.isNew, "This is your first visit!")
19  .done();
20
21// Multi-line formatting
22const formattedText = text()
23  .line("First line")
24  .line("Second line")
25  .trimLines() // Removes leading/trailing whitespace from each line
26  .done();

Available Methods:

• add(text) - Add text to the builder
• space() - Add a single space
• newLine(count?) - Add new lines (default: 1)
• line(text) - Add text followed by new line
• if(condition, then, else?) - Conditional text building
• trimLines() - Trim whitespace from each line
• done() / toString() - Get the final string

🛠️ Type-Safe Switcher

Replace switch statements with a fluent, type-safe API:

1import { switcher } from 'feats';
2
3// Basic usage
4const day = "Monday";
5const greeting = switcher(day)
6  .case("Monday", "Hello, Monday!")
7  .case("Tuesday", "Happy Tuesday!")
8  .case(["Saturday", "Sunday"], "Weekend vibes!")
9  .default("Have a great day!");
10
11// With custom equality check
12const user = { id: 1, name: "Alice" };
13const selectedUser = switcher(user, { 
14  equalityCheck: (v1, v2) => v1.id === v2.id 
15})
16  .case({ id: 1, name: "Alice" }, "It's Alice")
17  .case({ id: 2, name: "Bob" }, "It's Bob")
18  .done();
19
20// Type-safe with exhaustiveness checking
21const status = switcher(user.status)
22  .case("active", "User is active")
23  .case("inactive", "User is inactive")
24  .case("pending", "User is pending")
25  .done(); // TypeScript will warn if not all cases are handled

⏱️ Duration Utilities

Work with time durations in a type-safe, immutable way:

1import { duration, millis } from 'feats';
2
3// Create durations
4const timeout = duration(30, "seconds");
5const meeting = duration(1, "hour");
6const vacation = duration(2, "weeks");
7
8// Convert between units
9timeout.milliseconds; // 30000
10timeout.as("minutes"); // 0.5
11timeout.as("hours"); // 0.008333...
12
13// Arithmetic operations
14const totalTime = duration(1, "hour")
15  .add(30, "minutes")
16  .add(15, "seconds");
17
18const remaining = duration(2, "hours")
19  .subtract(45, "minutes");
20
21// Quick millisecond conversion
22const ms = millis(5, "minutes"); // 300000

Supported Units:

• ms, millisecond, milliseconds
• s, second, seconds
• m, minute, minutes
• h, hour, hours
• d, day, days

⚛️ React Hooks

useTimeout

Manage timeouts with manual control:

1import { useTimeout } from 'feats/react';
2
3function MyComponent() {
4  const timeout = useTimeout();
5
6  const handleClick = () => {
7    // Set a timeout
8    timeout.set(() => {
9      console.log('Timeout fired!');
10    }, 5000);
11
12    // Clear it if needed
13    // timeout.clear();
14
15    // Or dispatch it immediately
16    // timeout.dispatch();
17  };
18
19  return <button onClick={handleClick}>Start Timeout</button>;
20}

useInterval

Manage intervals with manual control:

1import { useInterval } from 'feats/react';
2
3function MyComponent() {
4  const interval = useInterval();
5
6  const startPolling = () => {
7    interval.set(() => {
8      fetchData();
9    }, 1000);
10  };
11
12  const stopPolling = () => {
13    interval.clear();
14  };
15
16  return (
17    <div>
18      <button onClick={startPolling}>Start Polling</button>
19      <button onClick={stopPolling}>Stop Polling</button>
20    </div>
21  );
22}

🔧 Array & Object Utilities

Extended prototypes for common array and object operations:

1// Array utilities (automatically available)
2const users = [
3  { id: 1, name: "Alice", role: "admin" },
4  { id: 2, name: "Bob", role: "user" },
5  { id: 3, name: "Charlie", role: "admin" }
6];
7
8// Filter and map in one operation
9const adminNames = users.filterAndMap(user => 
10  user.role === "admin" ? user.name : undefined
11); // ["Alice", "Charlie"]
12
13// Partition arrays
14const [admins, regularUsers] = users.partition(user => user.role === "admin");
15
16// Group by property
17const usersByRole = users.groupBy(user => user.role);
18// { admin: [...], user: [...] }
19
20// Remove duplicates
21const uniqueRoles = users.pluck("role").unique(); // ["admin", "user"]
22
23// Array operations
24const chunked = users.chunk(2); // [[user1, user2], [user3]]
25const intersection = users1.intersect(users2);
26const difference = users1.difference(users2);
27const union = users1.union(users2);
28
29// Object utilities
30const user = { id: 1, name: "Alice", email: "alice@example.com" };
31
32const picked = Object.pick(user, ["name", "email"]);
33const omitted = Object.omit(user, ["id"]);
34const keys = Object.typedKeys(user); // Type-safe keys

📦 Package Exports

1// Main exports
2import { text, switcher, duration } from 'feats';
3
4// React-specific exports
5import { useTimeout, useInterval } from 'feats/react';
6
7// Internal classes (advanced usage)
8import { TextBuilder, Switcher } from 'feats/internals';

🎯 Use Cases

• String Building: Generate dynamic messages, templates, or configuration files
• State Management: Replace complex switch statements with type-safe alternatives
• Time Handling: Work with durations in a consistent, immutable way
• React Development: Manage timeouts and intervals with better control
• Data Processing: Extended array and object utilities for common operations

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with TypeScript for type safety
• Zero dependencies for minimal bundle size
• Tree-shakeable for optimal performance