Ramda’s R.unless() answers a guarded-transform question: should this value pass through or take the fallback transformer? You pass a predicate and a function. You get back one function. Call that leftover with a value. Native JavaScript might write pred(x) ? x : whenFalseFn(x). unless names that guard once, curries it, and only runs the transformer on a miss. Drop the leftover into R.map and R.pipe.
The official sample is the whole idea. Increment only when the value is not nil. null stays null. Need a transform only when the test passes? That is R.when. Need both branches to always transform? That is R.ifElse. Need more than two branches? That is R.cond. Previous Logic helper is R.propSatisfies. Next is R.until for iterative loops until a predicate is satisfied.
Syntax
Call R.unless. Start with this line.
Ramda
R.unless(pred, whenFalseFn, x)
Call
What it does
R.unless(pred, whenFalseFn, x)
Primary signature.
R.unless(...)
Call the logic helper.
Prefer import { unless } from "ramda" when you want a named import.
Library declarations
Ramda
R.unless(pred, whenFalseFn, x)
Parameters
Parameter
Description
pred
Required. Function. A predicate. Called with the same arguments you later pass to the leftover. Truthy result returns x unchanged.
whenFalseFn
Required. Function. Runs only when the predicate is falsy. Accepts Ramda's placeholder R.__.
x
Required. Any. The value to test. On a pass you get this value back. On a miss you get the transformer result.
Return Value
Return Value
Description
a | b
Either the original x on a pass, or whatever whenFalseFn returns on a miss.
Ramda Examples
📚 Getting Started
The official Ramda safe-increment sample, then the same idea compared with when, ifElse, and cond.
Example 1 — Official Safe Increment
Increment only when the value is not nil. null passes through unchanged.
when would transform 50 only if it were 0 — 50 is not 0, so 50 passes through. unless transforms the miss: 50 is not 0, so R.inc runs. R.cond is the same fork as a list of pairs.
📈 Practical Patterns
Pass keeps the original, fail runs the transformer, then map rows and pipe vs ternary.
Example 3 — Predicate Pass Keeps Original / Fail Runs Fn
When the predicate passes, x is returned unchanged. When it fails, whenFalseFn runs.
R.pipe(safeInc) is the point-first style. The manual ternary does the same nil guard inline. unless names the pattern once so the pipe stays readable.
Compatibility
Browser Support
R.unless() is ordinary JavaScript once Ramda is loaded. Logos use the shared browser-image-sprite.png sprite from this project.
✓ Ramda 0.18.0+ · Any JS runtime
Ramda.js R.unless()
Load Ramda 0.18.0 or later via CDN or npm, then call R.unless with a predicate and transformer. No extra browser API is required.
100%With Ramda 0.18.0+
Google ChromeAll versions · Desktop & Mobile
Full support
Mozilla FirefoxAll versions · Desktop & Mobile
Full support
Apple SafariAll versions · macOS & iOS
Full support
Microsoft EdgeAll versions · Chromium & Legacy
Full support
Internet ExplorerIE 6+ · Legacy environments
Full support
OperaAll modern versions
Full support
R.unless()Universal
Bottom line: Safe in any project that includes Ramda 0.18.0 or later. Use a CDN build such as ramda.min.js in the browser or install ramda from npm for Node. These labs use [email protected].
Frequently Asked Questions
R.unless(pred, whenFalseFn, x) takes a predicate and a transformer. If pred(x) is truthy, x is returned unchanged. If pred(x) is falsy, whenFalseFn(x) runs. Added in v0.18.0. Type: (a → Boolean) → (a → b) → a → a | b. Arity 3, curried.
safeInc = R.unless(R.isNil, R.inc). safeInc(null) is null. safeInc(1) is 2. Nil values pass through. Non-nil values get incremented.
unless transforms only on a miss and keeps the original on a pass. when transforms only on a pass. ifElse always runs one of two transformers. cond is a list of [predicate, transformer] pairs for many branches.
No. On a pass you get the original x back. On a miss you get whatever whenFalseFn returns: a number, object, string, or anything else.
Yes. when transforms on a pass and otherwise returns x. unless transforms on a miss and otherwise returns x. Same predicate, opposite side of the fork.
No. R.unless is a stable Ramda logic helper from v0.18.0. It is not deprecated, experimental, or non-standard.