radashi

When writing TypeScript or JavaScript code, use these core utility functions from the radashi package. These functions are designed to simplify common tasks like type narrowing, array manipulation, and object transformations.

Type Guarding and Assertions

• assert: Asserts a condition and narrows types; throws an error if the condition is false.
• isDate: Tests if a value is a Date.
• isError: Tests if a value is an Error.
• isNullish: Tests if a value is null or undefined.
• isObject: Tests if a value is object-like.
• isPlainObject: Tests if a value is an ordinary JSON-style object.
• getErrorMessage: Converts an unknown caught error into a string message.

Array Manipulation

• castArray: Normalizes a value or an array into an array. Note: null becomes [null] and undefined becomes [undefined].
• concat: Combines arrays or items. It drops null/undefined values and flattens one level of array nesting.
• group: Groups array items by a specified key.
• range: Creates an inclusive numeric generator.
• sort: Returns a sorted copy of an array using a numeric getter.
• sum: Calculates the sum of numbers or numeric fields within an array.
• unique: Removes duplicate items from an array, with an optional key for comparison.

Object Manipulation

• mapValues: Transforms object values while preserving the original keys.
• objectify: Converts an array into an object using a key. If duplicate keys exist, later values overwrite earlier ones.
• omit: Returns a new object excluding the specified keys.
• pick: Returns a new object containing only the specified keys (prefer using an array of keys).
• shake: Removes only undefined properties from an object.

Other Utilities

• clamp: Constrains a number between a minimum and maximum value.
• dedent: Formats multiline template strings to be more readable by removing indentation.
• escapeHTML: Escapes HTML text characters (Note: this is not a full HTML sanitizer).
• sleep: Delays execution of asynchronous code for a specified number of milliseconds.

import { assert, castArray, isNullish, pick } from 'radashi';

// Example usage
assert(value !== null);
const items = castArray(input);
const subset = pick(user, ['id', 'name']);

While you can often use a standard arrow function like () => true for primitives, always provides specific advantages for object references and memoization:

1. Object Reference Stability: () => ({ a: 1 }) creates a new object on every call. _.always({ a: 1 }) returns the same object reference every time.
2. Memoization: Instead of calling a heavy function every time () => someCalculation() is invoked, you can use _.always(someCalculation()) to return the pre-calculated result immediately on subsequent calls.

import * as _ from 'radashi'

// Not memoized: runs calculation every time
const fn1 = () => someCalculation()

// Memoized: returns the result of the calculation
const fn2 = _.always(someCalculation())

// Not same object: returns a new object every time
const fn3 = () => ({ a: 1, b: 2 })

// Same object: returns the same reference every time
const fn4 = _.always({ a: 1, b: 2 })

The isObject function uses the type predicate value is object.

Caution: Because TypeScript's object type includes arrays, functions, dates, maps, and sets, isObject does not narrow a value specifically to a "plain object". It only narrows the value to the general object type.

Best Practices:

1. Use for Options/Primitives: It is effective when you need to distinguish between an options object and a primitive shorthand (like a string).
2. Avoid for Complex Unions: If your union type includes arrays, functions, or other special objects, do not rely solely on isObject. Instead, narrow those specific cases using _.isArray or _.isFunction to ensure accurate type narrowing.

import * as _ from 'radashi'

type Options = { foo?: string }

// Pattern 1: Handling Options vs Primitive
declare let value: Options | string | undefined

const options: Options = _.isObject(value)
  ? value
  : value === undefined
    ? {}
    : { foo: value }

// Pattern 2: Handling complex unions with specific checks
declare const value: Options | (() => Options) | Options[]

if (_.isArray(value)) {
  value
  // ^? const value: Options[]
} else if (_.isFunction(value)) {
  value
  // ^? const value: () => Options
} else if (_.isObject(value)) {
  value
  // ^? const value: Options
}

When using a predicate function with pick, be aware of potential type inaccuracies due to TypeScript's partial type matching.

If the object passed at runtime contains properties that are not defined in its TypeScript interface, the key and value parameters in your callback will still reflect the types defined in the interface. This means the TypeScript compiler might believe certain branches of logic (like an else block for unexpected keys) are unreachable, even though they may execute at runtime.

// Example demonstrating potential inaccuracy in `key` and `value` types within `_.pick` callback
import * as _ from 'radashi'
// @noErrors

interface User {
  name: string
  age: number
}

function getUserDetails(user: User) {
  return _.pick(user, (value, key) => {
    // TypeScript believes `key` is 'name' | 'age', but at runtime
    // it could be 'email'
    if (key === 'name' || key === 'age') {
      console.log(key, '=', value)
    } else {
      // TypeScript believes this will never run, but it does.
      console.log('Unexpected key:', key)
    }
  })
}

// At runtime, the function may receive an object with more properties
const runtimeUser = {
  name: 'John',
  age: 30,
  // This property is not listed in the User type:
  email: 'john@example.com',
}

getUserDetails(runtimeUser)
// Logs the following:
//     name = John
//     age = 30
//     Unexpected key: email