The infix “smart” pipe operator |> proposed here would provide a backwards- and forwards-compatible style of chaining nested expressions into a readable, left-to-right manner.

Using a zero-cost abstraction, nested data transformations become untangled into short steps.

Nested, deeply composed expressions occur often in real-world JavaScript. They occur whenever any single value must be processed by a series of data transformations, whether they be operations, functions, or constructors. Unfortunately, these deeply nested expressions often result in messy spaghetti code, due to their mixing of prefix, infix, and postfix expressions together. Writing such code requires many nested levels of indentation and parentheses. Reading such code requires checking both the left and right of each subexpression to understand its data flow.

promise
|> await #
|> # || throw new TypeError(
  `Invalid value from ${promise}`)
|> doubleSay(#, ', ')
|> capitalize
|> # + '!'
|> new User.Message(#)
|> await stream.write(#)
|> console.log;

With smart pipelines, code becomes terser and, literally, more straightforward. Prefix, infix, and postfix expressions would be less tangled together in threads of spaghetti. Instead, data values would be piped from left to right through a single linear thread of postfix expressions, with a single level of indentation and four fewer pairs of parentheses – essentially forming a reverse Polish notation.

The resulting code’s terseness and linearity may be both easier for the JavaScript developer to read and to edit. This uniform postfix notation preserves locality between related code; the reader may follow the flow of data more easily through this single linear thread of postfix operations. And the developer may more easily add or remove operations at the beginning, end, or middle of the thread, without changing the indentation of unrelated lines.

console.log(
  await stream.write(
    new User.Message(
      capitalize(
        doubledSay(
          await promise
            || throw new TypeError(
              `Invalid value from ${promise}`)
        ), ', '
      ) + '!'
    )
  )
);

Compared with the pipeline version, this non-pipeline version requires additional indentation and grouping on each step. This requires four more levels of indentation and four more pairs of parentheses.

In addition, much related code is here separated by unrelated code. Rather than a uniform postfix chain, operations appear either before the previous step’s expression (await stream.write(…),new User.Message(…), capitalize(…), doubledSay(…), await …) but also after (… || throw new TypeError(), … + '!'). An additional argument to function calls (such as , in doubledSay(…, ', ')) is also separated from its function calls, forming another easy-to-miss “postfix” argument.

Each step of a pipeline creates its own lexical scope, within which the # token (the topic reference) is immutably to the result of the previous step (the topic). In this way, it acts as a placeholder for each step’s input.

input // step 0
|> # + 1 // step 1
|> f(x, #, y) // step 2
|> await g(#, z) // step 3
|> console.log(`${#}!`); // step 4

The use of # as the topic reference is not set in stone. @, ?, %, or many other symbols could also be used. Bikeshedding discussions over what characters to use for the topic token have been occurring on GitHub at tc39/proposal-pipeline-operator issue #91.

input |> (# = 50);
// 🚫 Reference Error:
// Cannot assign to topic reference.

The topic binding is immutable, established only once per pipeline step. It is an error to attempt to assign a value to it using =, whether inside or outside a pipeline step.

This chained pipeline:

input
|> # - 3
|> -#
|> # * 2
|> Math.max(#, 0)
|> console.log;

…is equivalent to the tangled nested expression:

console.log(
  Math.max(
    -(input - 3) * 2,
    0
  )
);

The syntax is statically term rewritable into already valid code in this way, with theoretically zero runtime cost.

Similar use cases appear numerous times in real-world JavaScript code, whenever any input is transformed by expressions of any type: function calls, property calls, method calls, object constructions, arithmetic operations, logical operations, bitwise operations, typeof, instanceof, await, yield and yield *, and throw expressions.

function doubleSay (str, separator) {
  return `${str}${separator}${string}`;
}

function capitalize (str) {
  return str[0].toUpperCase()
    + str.substring(1);
}

promise
|> await #
|> # || throw new TypeError()
|> doubleSay(#, ', ')
|> capitalize
|> # + '!'
|> new User.Message(#)
|> await stream.write(#)
|> console.log;

This pipeline is also relatively linear, with only one level of indentation, and with each transformation step on its own line.

… |> capitalize uses a special shortcut called the bare style, explained further below. It is a bare unary function call that is, in this case, equivalent to … |> capitalize(#).

function doubleSay (str, separator) {
  return `${str}${separator}${str}`;
}

function capitalize (str) {
  return str[0].toUpperCase()
    + str.substring(1);
}

console.log(
  await stream.write(
    new User.Message(
      capitalize(
        doubledSay(
          await promise
            || throw new TypeError(
              `Invalid value from ${promise}`)
        ), ', '
      ) + '!'
    )
  )
);

This deeply nested expression has four levels of indentation instead of two. Reading its data flow requires checking both the beginning of each expression (new User.Message, capitalizedString, doubledSay, await promise and end of each expression (|| throw new TypeError(), , ', ', + '!')).

x = … |> f(#, #);

x = … |> [#, # * 2, # * 3];

The topic reference may be used multiple times in a pipeline step. Each use refers to the same value (wherever the topic reference is not overridden by another, inner pipeline’s topic scope). Because it is bound to the result of the topic, the topic is still only ever evaluated once.

{
  const $ = …;
  x = f($, $);
}

{
  const $ = …;
  x = [$, $ * 2, $ * 3];
}

This is equivalent to assigning the topic value to a unique variable, then using that variable multiple times in an expression.

promise
|> await #
|> # || throw new TypeError()
|> `${#}, ${#}`
|> #[0].toUpperCase() + #.substring(1)
|> # + '!'
|> new User.Message(#)
|> stream.write
|> console.log;

When tiny functions are only used once, and when their bodies would be obvious and self-documenting in meaning, then they might be ritual boilerplate that a developer may prefer to inline: trading off self-documentation for localization of code.

{
  const promiseValue = await promise
    || throw new TypeError();
  const doubledValue =
    `${promiseValue}, ${promiseValue}`;
  const capitalizedValue
    = doubledValue[0].toUpperCase()
      + doubledValue.substring(1);
  const exclaimedValue
    = capitalizedValue + '!';
  const userMessage =
    new User.Message(exclaimedValue);
  const writeValue =
    stream.write(userMessage);
  console.log(writeValue);
}

Using a sequence of variables instead has both advantages and disadvantages. The variable names may be self-documenting. But they also are verbose. They visually distract from the crucial data transformations (overemphasizing the expressions’ nouns over their verbs), and it is easy to typo their names.

promise
|> await #
|> # || throw new TypeError()
|> normalize
|> `${#}, ${#}`
|> #[0].toUpperCase() + #.substring(1)
|> # + '!'
|> new User.Message(#)
|> await stream.write(#)
|> console.log;

With a pipeline, there are no unnecessary variable identifiers. Inserting a new step in between two steps (or deleting a step) only touches one new line. Here, a call of a function normalize was inserted between the second and third steps.

{
  const promiseValue = await promise
    || throw new TypeError();
  const normalizedValue = normalize();
  const doubledValue =
    `${normalizedValue}, ${normalizedValue}`;
  const capitalizedValue =
    doubledValue[0].toUpperCase()
      + doubledValue.substring(1);
  const exclaimedValue =
    capitalizedValue + '!';
  const userMessage =
    new User.Message(exclaimedValue);
  const writeValue =
    stream.write(userMessage);
  console.log(writeValue);
}

This code underwent a similar insertion of normalize. With a series of variables, inserting a new step in between two other steps (or deleting a step) requires editing the variable names in the following step.

input |> f |> [0, 1, 2, ...#] |> g;

A pipeline step may contain array literals.

A topic-style pipeline step may also contain object literals. However, pipeline steps that are entirely object literals must be parenthesized. It is similar to how arrow functions distinguish between object literals and blocks.

input |> f |> ({ x: #, y: # }) |> g;

This is for forward compatibility with Additional Feature BP, which introduces block pipeline steps. (It is expected that block pipelines would eventually be much more common than pipelines with object literals.) This restriction could be dropped, although that would make Additional Feature BP impossible forever.

input |> f |> { x: #, y: # } |> g;
// 🚫 Syntax Error:
// Unexpected token `{`.
// Cannot parse base expression.

f = input
|> f
|> (x => # + x);

A topic-style pipeline step may contain an inner arrow function. Both versions of this example result in an arrow function in a closure on the previous pipeline’s result input |> f.

{
  const $ = f(input);
  x => $ + x;
}

The arrow function lexically closes over the topic value, takes one parameter, and returns the sum of the topic value and the parameter.

input
|> f
|> settimeout(() => # * 5)
|> processIntervalID;

This ability to create arrow functions, which do not lexically shadow the topic, can be useful for using callbacks in a pipeline.

{
  const $ = f(input);
  const intervalID = settimeout(() => $ * 5);
  processIntervalID(intervalID);
}

The topic value of the second pipeline step (here represented by a normal variable $) is still lexically accessible within its body, an arrow function, in both examples.

input
|> f
|> (() => # * 5)
|> settimeout
|> processIntervalID;

The arrow function can also be created on a separate pipeline step.

{
  const $ = f(input);
  const callback = () => $ * 5;
  const intervalID = settimeout(callback);
  processIntervalID(intervalID);
}

The result here is the same.

input
|> f
|> () => # * 5
|> settimeout
|> processIntervalID;
// 🚫 Syntax Error:
// Unexpected token `=>`.
// Cannot parse base expression.

Note, however, that arrow functions have looser precedence than the pipe operator. This means that if a pipeline creates an arrow function alone in one of its steps, then the arrow-function expression must be parenthesized. (The same applies to assignment and yield operators, which are also looser than the pipe operator.) The example above is being parsed as if it were:

(input |> f |> ()) =>
  (# * 5 |> settimeout |> processIntervalID);
// 🚫 Syntax Error:
// Unexpected token `=>`.
// Cannot parse base expression.

The arrow function must be parenthesized, as with any other looser-precedence expression:

input
|> (f, g)
|> (() => # * 5)
|> settimeout
|> processIntervalID;

There is a shortcut for the very common case of unary function calls on variables or variables’ methods. In these cases, the topic reference can be left out. (This is the bare style of the pipe operator.)

promise
|> await #
|> # || throw new TypeError()
|> doubleSay(#, ', ')
|> capitalize
|> # + '!'
|> new User.Message(#)
|> await stream.write(#)
|> console.log;

In this example, it is not necessary to include the parenthesized argument (#) for capitalize and console.log. They were tacitly implied, forming tacit unary function calls. In other words, the example above is equivalent to the version in the next row.

promise
|> await #
|> # || throw new TypeError(
    `Invalid value from ${#}`)
|> doubleSay(#, ', ')
|> capitalize(#)
|> # + '!'
|> new User.Message(#)
|> await stream.write(#)
|> console.log(#);

This version is equivalent to the version above, except that the |> capitalize(#) and |> console.log(#) pipeline steps explicitly include optional topic references #, making the expressions slightly wordier than necessary. (Any pipeline step that isn’t in bare style is said to be in topic style, because it uses the topic reference somewhere in its expression.)

Being able to automatically detect this “bare style” is the smart part of the “smart pipe operator”. The styles of functional programming, dataflow programming, and tacit programming may particularly benefit from bare pipelines and their terse function application.

const object = input
|> f
|> # + 2
|> # * 3
|> -#
|> g(#, x)
|> o.unaryMethod
|> await asyncFunction(#)
|> await o.asyncMethod(#)
|> new Constructor(#);

This pipeline is a very linear expression, with only one level of indentation, and with each transformation step on its own line.

As with the previous examples, the … |> f is a bare unary function call, equivalent to … |> f(#). The topic reference # is unnecessary; it is invisibly, tacitly implied. The same goes for o.unaryMethod, which is a unary function call on o.unaryMethod.

This is the smart part of the smart pipe operator, which can distinguish between two syntax styles (bare style vs. topic style) by using a simple rule: bare style uses only identifiers and dots – and never parentheses, brackets, braces, or other operators. And topic style always contains at least one topic reference. For more information, see the reference below about the smart step syntax.

const object =
  new Constructor(
    await o.asyncMethod(
      await asyncFunction(
        o.unaryMethod(
          g(
            -(f(input) + 2)
              * 3,
            x
          )
        )
      )
    )
  );

In contrast to the version with pipes, this code without pipes is deeply nested, not linear.

The expression has two levels of indentation instead of one. Reading its data flow requires checking both the beginning and end of each expression, and each step expression gradually increases in size.

Inserting or removing any step of the data flow also requires changes to the indentation of any previous steps’ lines.

input |> x + 50 |> f |> g(x, 2);
// 🚫 Syntax Error:
// Topic-style pipeline step
// `|> x + 50`
// binds topic but contains
// no topic reference.
// 🚫 Syntax Error:
// Topic-style pipeline step
// `|> g(x, 2)`
// binds topic but contains
// no topic reference.

In order to fulfill the goal of “don’t shoot me in the foot”, when a pipeline step is in topic style but it contains no topic reference, that is currently an early error. Such a degenerate pipeline step has a very good chance of actually being an accidental bug. (The bare-style pipeline step |> f is not an error. The bare style is not supposed to contain any topic references #.)

For instance, this code may be clear enough:

input |> object.method;

It is a valid bare-style pipeline. Bare style is designed to be strictly simple: it must either be a simple reference or it is not in bare style.

It means:

object.method(input);

But this code would be less clear. That is why it is an early Syntax Error:

input |> object.method();
// 🚫 Syntax Error:
// Topic-style pipeline step
// `|> object.method()`
// binds topic but contains
// no topic reference.

It is an invalid topic-style pipeline. It is in topic style because it is not a simple reference; it has parentheses. And it is invalid because it is in topic style yet it does not have a topic reference.

Had that code not been an error, it could reasonably mean either of these lines:

object.method(input);
object.method()(input);

Instead, the developer must clarify what they mean, using a topic reference, into either of these two valid topic-style pipelines:

input |> object.method(#);
input |> object.method()(#);

The reading developer benefits from explicitness and clarity, without sacrificing the benefits of untangled flow that pipelines bring.

Adding other arguments:

input |> object.method(x, y);
// 🚫 Syntax Error:
// Topic-style pipeline step
// `|> object.method(x, y)`
// binds topic but contains
// no topic reference.

…would make this problem of semantic ambiguity worse. But the reader is protected from this ambiguity by the same early error.

That code could have any of these reasonable interpretations:

object.method(input, x, y);
object.method(x, y, input);
object.method(x, y)(input);

Both inserting the input as the first argument and inserting it as the last argument are reasonable interpretations, as evidenced by how other programming languages’ pipe operators variously do either. Or it could be a factory method that creates a function that is in turn to be called with a unary input argument.

The writer must clarify which of these reasonable interpretations is correct:

input |> object.method(#, x, y);
input |> object.method(x, y, #);
input |> object.method(x, y)(#);

And this example’s ambiguity would be even worse:

input |> await object.method(x, y);
// 🚫 Syntax Error:
// Topic-style pipeline step
// `|> await object.method(x, y)`
// binds topic but contains
// no topic reference.

…were it not an invalid topic-style pipeline.

It could reasonably mean any of these lines:

await object.method(input, x, y);
await object.method(x, y, input);
await object.method(x, y)(input);
(await object.method(x, y))(input);

So the developer must clarify their intent using one of these lines:

input |> await object.method(#, x, y);
input |> await object.method(x, y, #);
input |> await object.method(x, y)(#);
input |> (await object.method(x, y))(#);

Both the head and the steps of a pipeline may contain nested inner pipelines.

x = input
|> f(x =>
  # + x |> g |> # * 2)
|> #.toString();

However, just as with any other syntax, nested pipelines can quickly become complicated if not used judiciously; they are discouraged otherwise.

A nested pipeline works consistently. It merely shadows the outer context’s topic with the topic within its own steps’ inner contexts.

{
  const $ = input;
  x = f(x =>
    g($ + x) * 2
  ).toString();
}

Currently, four kinds of statements cannot use an outside context’s topic in their expressions. These are:

• function definitions (including those for async functions, generators, and async generators; but not arrow functions, as explained above),
• class definitions,
• for and while statements,
• catch clauses (but see Additional Feature TS), and
• with statements.

x = input |> function () { return #; };
// 🚫 Syntax Error:
// Lexical context `function () { return #; }`
// contains a topic reference
// but has no topic binding.
// 🚫 Syntax Error:
// Pipeline step `|> function () { … }`
// binds topic but contains
// no topic reference.

This behavior is in order to fulfill the goals of simple scoping and of “don’t shoot me in the foot”: it prevents the origin of any topic from being difficult to find. It also fulfills the goal of forward compatibility with future additional features.

However, this behavior is subject to change, depending on feedback after the proposal is implemented in the Babel plugin.

x = input
|> await f(#, 5)
|> () => {
  if (#)
    return # + 30;
  else
    return #;
}
|> g;

Any other nested blocks may contain topic references from outer lexical environments. These include arrow functions, if statements, try statements and their finally clauses (though not their catch clauses), switch statements, and bare block statements.

A function definition that is a pipeline step may contain topic references in its default parameters’ expressions, because their scoping is similar to that of the outside context’s: similar enough such that also allowing topic references in them would fulfill the goal of simple scoping. However, as stated above, the function body itself still may not contain topic references.

value
|> processing
|> function (x = #) { return x; }

The same applies to the parenthesized antecedents of for and while loops.

input
|> process
|> (x, y) => {
  for (const element of #)
    …
}

input
|> process
|> (x, y) => {
  let element;
  while (element = getNextFrom(#))
    …
}