@jkhong/devutils

@jkhong/devutils

Provides syntactic sugar and shortcuts to bullet-proof your TypeScript/JavaScript code.

Contents

• Install
• DevUtils — isSet · isNotSet · isAllSet · isOneNotSet · isEmpty · getFieldValue · getChildFieldValue · makeSingleton · debounce · getError
• StringUtils — isBlank · capitalize · uncapitalize · replaceTrailing · replaceLeading
• ArrayUtils — isEmpty · getField
• DateUtils — addDays · addMinutes · addSeconds
• FunctionUtils — isAsync
• InMemory — TTL-based in-memory cache
• TestUtils — async test helpers

---

Install

npm install @jkhong/devutils

---

DevUtils

isSet(value)

Returns true if the value is not null, not undefined, and not the string 'undefined'.

import { DevUtils } from '@jkhong/devutils';

DevUtils.isSet(null);        // false
DevUtils.isSet(undefined);   // false
DevUtils.isSet('undefined'); // false
DevUtils.isSet(0);           // true
DevUtils.isSet('');          // true
DevUtils.isSet(false);       // true

isNotSet(value)

Inverse of isSet.

isAllSet(memberNames, data) / isOneNotSet(memberNames, data)

Check if all (or at least one) named fields of an object are set.

DevUtils.isAllSet(['id', 'name'], { id: 1, name: 'foo' }); // true
DevUtils.isOneNotSet(['id', 'name'], { id: 1 });            // true

isEmpty(value)

Returns true for null, undefined, empty/blank strings, empty arrays, and empty objects.

DevUtils.isEmpty(null);      // true
DevUtils.isEmpty('   ');     // true
DevUtils.isEmpty([]);        // true
DevUtils.isEmpty({});        // true
DevUtils.isEmpty([1]);       // false
DevUtils.isEmpty({ a: 1 }); // false

getFieldValue(struct, fieldname, default)

Returns the field value if set, otherwise the default.

DevUtils.getFieldValue({ age: 30 }, 'age', 0);  // 30
DevUtils.getFieldValue({}, 'age', 0);            // 0
DevUtils.getFieldValue(null, 'age', 0);          // 0

getChildFieldValue(struct, fieldnames, default)

Traverses nested objects safely, returning the default if any level is missing.

const obj = { a: { b: { c: 'deep' } } };
DevUtils.getChildFieldValue(obj, ['a', 'b', 'c'], 'default'); // 'deep'
DevUtils.getChildFieldValue(obj, ['a', 'x', 'c'], 'default'); // 'default'

makeSingleton(asyncFactory)

Wraps an async factory so it is called only once. Subsequent calls return the cached instance.

const getDb = DevUtils.makeSingleton(() => connectToDatabase());
await getDb(); // connects
await getDb(); // returns cached connection

debounce(fn, waitMs)

Returns a debounced version of fn that fires only after waitMs ms of inactivity.

const save = DevUtils.debounce(() => api.save(), 300);
save(); save(); save(); // only the last call fires after 300ms

getError(e)

Normalizes any thrown value to an Error instance. Useful in catch (e: unknown) blocks.

try { ... } catch (e: unknown) {
   const err = DevUtils.getError(e); // always an Error
}

---

StringUtils

import { StringUtils } from '@jkhong/devutils';

Method	Description
isBlank(str)	true if string is null, undefined, or contains only whitespace
capitalize(word)	Uppercases the first character
uncapitalize(word)	Lowercases the first character
replaceTrailing(value, char, replacement)	Replaces trailing occurrences of char
replaceLeading(value, char, replacement)	Replaces leading occurrences of char

StringUtils.capitalize('hello');                   // 'Hello'
StringUtils.uncapitalize('World');                 // 'world'
StringUtils.replaceTrailing('foo///', '/', '');    // 'foo'
StringUtils.replaceLeading('///foo', '/', '');     // 'foo'

---

ArrayUtils

import { ArrayUtils } from '@jkhong/devutils';

Method	Description
isEmpty(array)	true if array is null, undefined, or has no elements
getField(array, index, fieldname, default)	Safely reads a field from an element at a given index

ArrayUtils.isEmpty([]);                              // true
ArrayUtils.getField([{ id: 1 }], 0, 'id', null);   // 1
ArrayUtils.getField([], 0, 'id', null);             // null

---

DateUtils

import { DateUtils } from '@jkhong/devutils';

Method	Description
addDays(date, n)	Returns a new Date with n days added
addMinutes(date, n)	Returns a new Date with n minutes added
addSeconds(date, n)	Returns a new Date with n seconds added

Accepts negative values to subtract. The original date is never mutated.

DateUtils.addDays(new Date(), 7);     // one week from now
DateUtils.addSeconds(new Date(), -30); // 30 seconds ago

---

FunctionUtils

import { FunctionUtils } from '@jkhong/devutils';

Method	Description
isAsync(fn)	true if the function is async

FunctionUtils.isAsync(async () => {}); // true
FunctionUtils.isAsync(() => {});       // false

---

InMemory (cache)

A TTL-based in-memory cache with per-entry TTL support and automatic background cleanup.

import { InMemory } from '@jkhong/devutils';

Constructor options

Option	Default	Description
ttlInSec	3600 (1h)	Default TTL for entries
autoTtlCleanIntervalInSec	3600 (1h)	How often expired entries are swept
autoWipeAllIntervalInSec	disabled	How often the entire cache is cleared (opt-in)

Methods

add({ id, d, ttlInSec? })

Adds or overwrites an entry. ttlInSec overrides the global default for this entry.

const cache = new InMemory<User>({ ttlInSec: 300 });
await cache.add({ id: 'u1', d: user });
await cache.add({ id: 'u2', d: user, ttlInSec: 60 }); // custom TTL

fetch(id)

Returns the cached value or undefined if missing or expired.

const user = await cache.fetch('u1'); // User | undefined

fetchMultiple(ids)

Splits a list of ids into cached hits and ids that still need to be fetched from the source.

const { cachedData, idsToRequest } = await cache.fetchMultiple(['u1', 'u2', 'u3']);
// cachedData    → [{ id: 'u1', data: User }, ...]
// idsToRequest  → ['u3']

const fresh = await api.getUsers(idsToRequest);

remove(id)

Removes a single entry immediately.

await cache.remove('u1');

forceTtlClean()

Triggers an immediate sweep to remove all expired entries.

forceWipeAll()

Clears all entries regardless of TTL.

destroy()

Stops background intervals and clears the cache. Call this when the cache instance is no longer needed to prevent timer leaks.

await cache.destroy();

---

TestUtils

Helpers for structuring async tests with setup / run / assert phases.

import { TestUtils } from '@jkhong/devutils';

testExpectedSuccess({ setPreconditions, run, checkPostconditions })

For testing a happy path. Returns { success: true } or { success: false, error }.

const result = await TestUtils.testExpectedSuccess({
   setPreconditions: async () => buildInput(),
   run: async (input) => myService.process(input),
   checkPostconditions: async (output) => {
      expect(output.status).toBe('ok');
   },
});
expect(result.success).toBe(true);

testExpectedError({ setPreconditions, run, checkError, checkPostconditions })

For testing flows that return an error value (no exception thrown).

testExpectedException({ setPreconditions, run, checkError, checkPostconditions })

For testing flows that are expected to throw.