fn-ref v1.3.0

Utility Functions: ref and fnRef

This utility provides two powerful functions, ref and fnRef, designed for managing state and function references in JavaScript and TypeScript. They are especially useful in scenarios where dynamic updates to values or callbacks are needed while maintaining clean and efficient code.

Function: fnRef

Purpose

The fnRef function manages a reference to a function, allowing dynamic updates to the function logic while maintaining a consistent interface for callers. This is particularly useful for handling callbacks that need to be updated at runtime.

Syntax

function fnRef<T extends (...args: any[]) => any>(
  fn: T
): T & { set: (fn: T) => void };

Parameters

• fn (T): The initial function to store in the reference.

Returns

A function with:

• The same signature as the input function.
• An additional set method to update the stored function.

Use Cases

1. Dynamic Callbacks: Use fnRef to update callbacks without requiring the consuming code to rebind or reinitialize the callback.

2. Middleware-like Functionality: Dynamically inject or change behavior at runtime without altering the caller.

3. Decoupling Logic: Separate the function definition from its execution context, enabling modular and reusable designs.

Example

const logRef = fnRef((message: string) => {
  console.log(`Initial log: \${message}`);
});

// Call the function
logRef("Hello, world!"); // Output: Initial log: Hello, world!

// Update the function logic
logRef.set((message: string) => {
  console.log(`Updated log: \${message}`);
});

// Call the updated function
logRef("Hello again!"); // Output: Updated log: Hello again!

Function: ref

Purpose

The ref function acts as a simple reference holder for any value. It provides a getter and setter interface that allows for dynamically managing a value during runtime.

Syntax

function ref<T>(value: T | null | undefined): (newValue?: T | null) => T | void;

Parameters

• value (T | null | undefined): The initial value to store in the reference.

Returns

A function that:

• Returns the current value when called without arguments.
• Updates the stored value when called with a new value.

Use Cases

1. Dynamic State Management: Use ref to hold a value that needs to be dynamically updated or accessed during runtime.

2. Lightweight Alternative to React’s useRef: For non-reactive contexts, ref provides a similar utility without requiring React.

3. Encapsulation: Hide internal state management logic while exposing a clean API for getting or setting values.

Example

const valueRef = ref<number>(42);

// Get the current value
console.log(valueRef()); // Output: 42

// Set a new value
valueRef(100);

// Get the updated value
console.log(valueRef()); // Output: 100

Why Use These Utilities?

Benefits of ref:

• Simple, lightweight state holder.
• Decouples state management logic from its consumers.
• Works with any data type.

Benefits of fnRef:

• Allows dynamic updates to function logic while keeping a stable reference.
• Avoids boilerplate for reassigning functions.
• Ensures type safety with full TypeScript support.

Installation and Usage

Adding to Your Project

Since these are custom utilities, you can copy them directly into your project or include them as part of a shared utility library.

TypeScript Compatibility

Both functions are fully typed, ensuring type safety and autocompletion in TypeScript projects.

Feel free to explore these functions and incorporate them into your JavaScript or TypeScript projects for enhanced flexibility and cleaner code management!