Seque: What It Is & How It Works

Jonathan Skeate — Fri, 17 Jul 2015 00:00:00 GMT

What even is this?

Seque is a library of chainable control flow functions — in other words, it allows you to write code like this:

[1, 2, 3]
  .if(useEvens)
  .filter(x => x % 2 === 0)
  .else()
  .filter(x => x % 2 === 1)
  .endif()
  .forEach(doSomething)
  // ...

So far there are three control flow functions:

if() … [else() …] endif()
while() … endwhile() (continuously applies functions as long as the function returns true)
loop() … endloop() (applies functions times)

How does it work? First, a quick recap of what’s really going on in a chain:

See the Pen Basic Chain by Jonathan Skeate (@skeate) on CodePen.

Each step returns a value, which the next function in the chain is then invoked upon. Chained functions have no knowledge of each other.

Wrappers Galore

To get around this, Seque uses a wrap function. Essentially, it returns an object which will intercept any function you try to call on it. It stashes these away until some endpoint (e.g. endif()), and then executes a callback with the entire list of functions that had been "called", along with their arguments. The callback can then decide to apply them or not apply them as it sees fit.

Technically, it will only intercept any function if the platform has ES6 Proxy support. More on that in a bit.

All of Seque’s control flow methods use this wrap method, with differing callbacks. if 's callback, for example, splits the chain where the else call is (if it exists), and then applies the stack before or after the else based on the value it was passed.

An attempt at illustrating this point (press arrow buttons at the top to change slides):

See the Pen Seque chain by Jonathan Skeate (@skeate) on CodePen.

Caveat

Without ES6’s new Proxy feature, doing this in a completely seamless way is (as far as I can tell) impossible. Without it, the wrap function can only track those functions it has some way of knowing about. By default, it will track any functions available on the original object it was called upon — if an array, it’ll watch for calls to map or forEach, for example. But if some link in the chain returns a different type, then you could have problems if you try to call a function that didn’t exist (at least by name) on the original object.

For example, something like this will work:

['a', 'b', 'c', ...]
  .if(someCondition)
  .join('')
  .slice(1)
  .endif()

Because slice is available on both arrays and strings. However, this will fail:

['a', 'b', 'c', ...]
  .if(someCondition)
  .join('')
  .toUpperCase()
  .endif()

Because toUpperCase() does not exist on arrays. The Seque-wrapped version of the original array will not know that it should be looking for some function named toUpperCase, and thus when it encounters that in the chain, it will say undefined is not a function (or something along those lines).

There is a way around this issue: pass an array of the extra function names as a second argument to the control flow function. Thus, the above failing example would become

['a', 'b', 'c', ...]
  .if(someCondition, ['toUpperCase'])
  .join('')
  .toUpperCase()
  .endif()

Admittedly, this is a bit gross, but I can think of no other way around a lack of proper Proxy support, at least in the code itself. One possible way would be to make a Seque preprocessor, so the array of function names would be generated for you. Of course, if what you’re chaining always returns the same type (e.g. arrays or promises), then this is unnecessary. Speaking of promises…

Chaining Asynchrony with Promises

One thing you might have noticed is that these all resolve immediately. That can be useful with a chain of promises (e.g. if you want to do this one asynchronous step conditionally, but you know the condition ahead of time). But what if you want to branch or loop based on the resolved value of a promise? Seque includes some Async versions of its functions for this purpose.

$.get('/api/posts')
  .ifAsync(posts => posts.length === 1)
  .then(handleSinglePost)
  .else()
  .then(handlePostList)
  .endif()

It takes a function which will get passed the resolved value of the promise immediately preceding the ifAsync.

There is also a similar whileAsync, but its function will get the last resolved value in the enclosed chain on each iteration. For example, imagine you are dealing with some awful API that has a "nextPage" endpoint which returns page info (including a pageNumber property), and no way to get many pages at once. You want to load up and process 50 pages. You could do something like

$.get('/api/page')
  .whileAsync(page => {
    processPage(page);
    return page.pageNumber !== 50;
  })
  .then(() => $.get('/api/nextPage'))
  .endWhile();

Have ideas for other functions? Find bugs with the current ones? Please post an issue to Github, and I’ll see what I can do!

Wrapping Text to Fit Shaped Containers with CSS

Jonathan Skeate — Mon, 13 Jul 2015 00:00:00 GMT

With CSS, you can make all kinds of shapes, but if you try to put any text inside even a simple non-rectangular shape, you can run into problems. The text will not wrap to fit inside the container.

See the Pen raOVjY by Jonathan Skeate (@skeate) on CodePen.

However, recently I discovered the CSS property shape-outside. Browser support isn’t great (currently only Webkit-based browsers), but there is a polyfill. It allows you to wrap text around a floated element, as if it had a shape you specify. Perhaps the most common example is a circle:

See the Pen qEOdrM by Jonathan Skeate (@skeate) on CodePen.

Gorgeous. But how does this help with the original problem? This handles wrapping outside a shape. There’s no shape-inside (yet).

Until that arrives, we can still manage this. The trick lies in inverting the shape-outside. In other words, make the shape a polygon, with two points at (0,0) and (0, 100%), and the rest following the contour of the desired shape. It’s not perfect (for circles at least) but it’s good enough, since text would never be perfect anyway.

One caveat: this only works with floated elements. We can float the ::before pseudoelement just fine, but if we try to float the ::after, it doesn’t look right. See the example below — you can hover over the circle to color the pseudoelements, to make it more obvious what’s happening.

See the Pen gbarrN by Jonathan Skeate (@skeate) on CodePen.

Unfortunately the only way I’ve found around it so far is double-wrapping the circle element, so you can use both ::before elements. Forgiveable, I suppose, but I would like a single-element solution.

See the Pen YPyqWd by Jonathan Skeate (@skeate) on CodePen.

Here’s an SCSS mixin to handle it all:

@mixin circle($radius){
  width: $radius*2;
  height: $radius*2;
  border-radius: $radius;
  &::before{
    content: '';
    height: 100%;
    width: 50%;
    float: left;
    shape-outside: polygon(
      0 0, 100% 0, 60% 4%, 40% 10%, 20% 20%, 10% 28.2%, 5% 34.4%, 0 50%,
      5% 65.6%, 10% 71.8%, 20% 80%, 40% 90%, 60% 96%, 100% 100%, 0 100%
    );
  }
  > span::before{
    content: '';
    height: 100%;
    width: 50%;
    float: right;
    shape-outside: polygon(
      100% 0, 0 0, 40% 4%, 60% 10%, 80% 20%, 90% 28.2%, 95% 34.4%, 100% 50%,
      95% 65.6%, 90% 71.8%, 80% 80%, 60% 90%, 40% 96%, 0 100%, 100% 100%
    );
  }
}