This is an argument for keyword arguments (often simulated in JavaScript by taking an object as a single argument, which would work great here: being both faster and frankly somewhat more logical as it is a single step rather than a chain of modifications), and I would argue doesn't really "challenge the status quo" other than to make the argument yet again that named arguments are pretty cool (even though I do tend to use [@"Get on the road" stringByReplacingOccurrencesOfString:@"road" withString:@"bus" as an example of how ludicrously verbose Objective-C can feel ;P).

Destructuring assignment could also helps readability, for example:

  function replace(text, {fromText = '', toText = '', caseInsensitive = false} = {}){
  	//
  	// ...
  	//
  }

  replace(
  	'Get on the Road',
  	{
  		fromText: 'road',
  		toText: 'bus',
  		caseInsensitive: true
  	}
  );

Question out of couriosity: Why whould you davor smt like that over a simple regexp replace? like

const target = 'Get on the Road' const result = target.replace(/road/i, 'bus')

Regex is harder to understand because one should be aware of the peculiarities of each language. Besides, it uses abbreviations such as "i", "u", "g" and the one reading it might need to look at the docs to know what that means.

str-replace uses regex internally but abstracts it in a fluent interface for legibility purposes at the cost of not optimizing prematurely. Regex is definitely the solution if one want to make more complex replaces or need to care about micro-optimizations like the use of regex without an additional function call (which imho in 90% of the cases is irrelevant).

Not a fan. Not to say this isn't perhaps more readable to a layperson than the regex equivalent. However, I dislike these sorts of "syntactic sugar" libraries as a rule due to the cognitive overhead they add to a project; every programmer working on this code now needs to know this API in addition to the regex equivalent, which, let's face it, they would've needed to know anyways.

Nonetheless, I commend you for putting a well documented/examples API out there. Cheers.

This is not syntactic sugar - it's just a regular API.

I think it would be useful if there was a very good reason to use it. Otherwise, learn regexing and it shouldn't be so bad.

It is just an experiment. If anyone finds it useful it will improved for AMD/Browser support, reducing bytes, adding more features on high demand (want to keep it simple but extensible), etc.