normalizeThenable

Guarantees a thenable value or returns null.

This helper determines whether a value conforms to the Promise-like (thenable) contract by checking for a callable then property. It performs no wrapping, invocation, or coercion.

Use this helper when you need to safely detect async-capable values without triggering execution.

Signature

function normalizeThenable<T = unknown>(
  value: unknown
): PromiseLike<T> | null

Parameters

Name	Data type	Description
value	unknown	The value to normalize.

Returns

One of:

• The original value, typed as PromiseLike<T>
• null if the value is not thenable.

Behavior

• Accepts:
• Native Promise instances.
• Objects with a callable then property.
• Functions with a callable then property.
• Rejects:
• null and undefined.
• Primitives.
• Objects whose then property is not a function.
• Never throws and never mutates input.
• Never invokes then.

Examples

normalizeThenable(Promise.resolve(1))
// Promise

normalizeThenable({ then: () => {} })
// { then: [Function] }

normalizeThenable({ then: 123 })
// null

normalizeThenable(42)
// null

Notes

This helper does not:

• Await values.
• Wrap values in Promises.
• Create async side effects.
• Structural checks only.
• Suitable for async boundary detection.
• Mirrors the ECMAScript notion of "thenable" without execution.