Lamination

Despite my lack of awareness of us having one, the laminating machine quickly became invaluable to a better final result as well as an easier experience with the Cricut. After some experimentation, we discovered the best process to be:

• Use the 0.3 mm lamination pouches for perfect card-feel (the 0.5 mm ones were too thick for the Cricut to handle swiftly); this precludes the use of a backing card, and makes the final sleeved result near perfect.
• Laminating before cutting is a must due to how the pouches work; it does makes the cutting itself slightly slower (requiring a custom profile; I ended up with max pressure and 4x passes but you can experiment with your own machine), but removing the cards from the Cricut sticker mat is infinitely easier and does not cause irreversible bends on the cards.
• If there are slight bends or creases on the corners due to cricut and lamination interplay, a quick second pass through the laminator (past cut, no pouch) can easily smooth anything visible.

Card Press

Added a few features to smooth the experience, including cut lines in case you are not using the Cricut and want to use a guillotine or similar tool.

Everything as usual is available at card-press and open-sourced on GitHub.

Foil Paper

By far the most exciting development was the discovery of foil (holographic) paper. It is a cardstock with a metallic finish. We print foil cards on top, and the shine exudes through the ink (there are also adhesive / vinyl versions for multi-layering, but I didn't go that far). You can find it on the required US Letter size and good thickness on Staples or equivalent.

The only problem is that our fancy printer (which accepts the HP Click software) cannot handle it - the ink just does not adhere, regardless of the profile. Our normal printer actually works perfectly, but it has a terrible issue. While still from HP, it is an older model that does not support HP Click. Using the normal print dialogs on our company macOS computers was a complete pain.

After a lot of investigation, I concluded that the AirPrint driver simply does not respect the options on the printer dialog. I tried multiple software's print dialog and the macOS native one, but it always adds an annoying margin making the cards every-so-slightly too small. In the end I realized that I need to link the printer from scratch using a different driver (HP's own), but then, it wouldn't respect some settings such as the selected tray and print quality. I had to resort changing those settings' defaults on the printer itself. And it would still not respect tray selection, so I had to make sure it first failed to print on Tray 1 (that wouldn't take the foil) and then switch the failed job on the printer UI to Tray 2. I had no idea the state of printer drivers in 2026 could be so abysmal, and definitely have some interest in taking a deeper look at the software to see if there is any way to improve this experience (but that is far from the scope of this post). I haven't tried bringing in my Linux machine to the Office to see if it would fare any better (would be incredibly ironic if so), so I can't comment on that.

All that aside, once the cards were printed on the correct size and quality on the foil paper, they look absolutely stunning. I think they could look even better through a layered foiling approach, but that is beyond what I am willing to do for my Dimensional Rift playtesting prototypes.

Conclusion

Overall, I found it much more enjoyable to pop the laminated cards right out of the Cricut mat, and much nicer to sleeve them by themselves, ready to playtest with no backing cards. The foils look amazing for the fanciest cards, and I still hold that card-press is the best tool for small-batch card printing, regardless of the cutting method.

I have updated the original Print and Play with Cricut tutorial to include the new lamination and foil processes, so check it out if you want to try any of these improvements!

If you know more about printer drivers and AirPrint on macOS, please let know, I am interested in understanding if I am doing something terribly wrong or if this is the state of affairs with these.

For more historical context and details about the card-press tool, see The Card Press Saga. The tutorial was updated on 2026-04-04 to include lamination and foil processes - see more details on Card Pipeline Improvements.

This is a step-by-step tutorial on how to use a printer (that can handle cardstock or photographic paper) paired with a Cricut (we have the Cricut Maker 4 but should be adaptable to other models) to automatically print then cut MTG-sized cards.

Preparation

The Cricut Design Space software is utterly unusable for large quantities of cards, as it requires manually uploading and dragging images one-by-one in the most painful way imaginable. So instead, I made card-press, a fully client-side webapp for generating card PDFs with (I hope) a very easy-to-use (and to automate) interface. It is open-source so feel free to submit any changes or enhancements.

Essentially, we are going to be tricking the Cricut by loading an "empty" template as the cut PDF with just black rectangles, and printing the PDF "on the side" (using card-press) and then selecting the option "I already printed" on the Cricut.

So you will need to:

• [one time] Make sure you have the Cricut Design Space and the printer software (in our case, HP Click) installed and configured.
• [one time] Load my custom template into the Cricut Design Studio software; it matches exactly with the PDF you will generate on card-press. You can also download it here if you don't want to use their "cloud", but manually importing is non-trivial (exercise to the reader).
• Load your images onto card-press and generate a PDF using the pre-defined Letter / Cricut - MTG 2x3 template (default). There are many input methods ("import", file picker, drag and drop, copy and paste). If you want card backs, enable that option and generate an additional PDF for the backs.

Materials

There are 3 factors to consider when selecting your paper:

• Size: unfortunately it must be Letter as that is what the Cricut understands.
• Finish: we have satin, glossy and double-glossy (for card backs) finishes; there is also matte. This is entirely up to you. Printing on photo/glossy paper takes slightly longer and requires a drying step, but I think it is worth it.
• Thickness: While the 300 gsm cardstock would have a superior card-feel, I found it to sometimes cause jams (in our printer at least). So I've started to use the 260 gsm instead. You can always add real cards as backings inside the sleeves for enhanced flickability.

Having made your choice, load a sufficient amount of sheets (according to your PDF) into the printer.

You can also use holographic / iridescent cardstock to make foil cards! The process is exactly the same, you just print on top of the foil paper (not the adhesive / vinyl ones), but make sure your printer is configured to accept it.

Execution

1. Kick off the print job for the entire PDF. Make sure to configure the printer for the type of paper you chose (notably, the type of finish - lest a very inky mess ensues). If you are manually attending and have free cycles in between other steps, you can cancel the in-print drying, very carefully dry the sheets to the side, and let the following pages get a head-start. Surprisingly, when using glossy photo paper, it is the printing that is the bottleneck rather than the cutting.

2. [optional] If you are doing card backs, wait for all pages to finish, recollect them, flip them, and print the backs.

3. [optional] If you are doing lamination, you can laminate the sheets once they are dry. Make sure to use the 0.3 mm pouches for both ideal card feel and best Cricut smoothness. Laminating before cutting makes removing the cards from the Cricut mat later a breeze, and precludes the need of using backing cards on the sleeves later! It is also a pretty quick addition to the pipeline when compared to the timing of other steps.

4. Load the first printed (and dried) page of the PDF into the Cricut mat (I use the Blue / Light Grip but depending on wear and tear it might be slightly too strong or too weak). Try to align it to the top left to the best of your abilities, as the Cricut will not haphazardly scan the entire mat for the cut marks.

   

5. Start to "Make It" (the template) on the Cricut Design Space (you do not need to load any images or change anything). Click "Continue" and then "I've Already Printed". I use the "Heavy Cardstock" material setting, which I have favourited (if you are laminating, you will need a custom profile - I use max pressure and 4x passes). Load the mat and start; let the machine do the work while you focus on what really matters (overseeing it with an air of superiority).

   

6. Unload and peel the cards (depending on the adhesive strength, you might need to be very gentle not to bend them, unless they are laminated).

   

7. [optional] If called by the design of your cards, you can use the Kadomaru Pro to round the corners (its smallest setting is the closest I found to the standard MTG border-radius).

And rinse and repeat! The Cricut software will require just one more click to re-do the same cut for the next page. You can very effectively alternate between collecting pages from the printer before they fall, attaching the next dry sheet onto the mat, and coding your next million-dollar project on the side.

As usual, you can install the drop-in-css package from NPM or import it directly from:

<link rel="stylesheet" href="https://luan.xyz/projects/drop-in/drop-in.css" />

Find the latest version on GitHub. Simply "drop it in" and it just works!

New Features

You've seen these features already on this website; but now they are an official part of drop-in.

• Better style for <h2> elements (seen above)
• New .muted class for subtle text (any element)
• New style for <footer> elements (seen below)
• New style for <blockquote> elements (seen above)

If you want to follow this and future posts through your preferred reader, you can now subscribe to my RSS or Atom feeds.

I spent some time digging into how to easily setup an RSS feed for these articles using my new astro setup; that led me into a few rabbit holes, such as learning the differences between RSS vs Atom, setting up FreshRSS on my own TrueNAS (and hopefully starting a more curated reading diet), and a few others.

But the biggest one was figuring out how to process a version of the actual content of the article suitable for the RSS feed. While not obligatory, it seems that the common consensus is that RSS feeds should include the article content. The problem is the content are markdown, potentially MDX files that are yet to be processed by Astro. The "official" RSS plugin also does not seem to support Atom out-of-the-box (and I wanted to offer both).

But nothing that some research and understanding could not fix; after studying this snippet and reading this enlightening article by George Song, I managed to combine them into my own, hopefully simpler solution.

The key takeaways I combined from both sources were:

• using the experimental_AstroContainer API to render content "in memory" - this will work with markdown and MDX without need special handling;
• using the feed package to generate both RSS and Atom feeds with a unified API.

There is still some one-off boilerplate, but hopefully it gets simpler as astro evolves its Container API. Let me know if you think it would be substantial enough to extract into a generic package, or if there are better solutions I failed to find.

Amongst the many things I wanted to change or do differently, using hexagonal maps for encounters always stood out to me as a superior alternative for the more tactical and nuanced combat I sought (they are the bestagons, after all).

However, after initial in-person sessions, I soon realized there would be some challenges when transitioning to the virtual realm. Firstly I started to look for satisfying hex-grid-aligned encounter-level map assets; but (due to not finding any and also to changing my mind about their relevance) eventually I opted for using bare grids with minimalist abstractions, akin to the ones I'd been jotting over my dry-erase hexagonal mat. The challenge then shifted: I realized the drawing tools on Foundry VTT (the virtual environment I use - and highly recommend) were not very well suited for swiftly improvising the kinds of annotations I was intending to plot over the grid.

To make the tactical situation of the battle clearer to digest for the players and myself, it would be ideal if my quick drawings would just "snap" to the hexagonal lattice. A wall instead of a straight line would just hug the edges of the hexes; a bush or tree would just be a stamp over one hex; and so on. On our minds, it is trivial to derive (and "colour") the nuanced scene from the simplified geometry, but not the other way around when one is calculating one's next move.

And not founding any comprehensive hexagon-drawing toolkit, I decided to make a quick module for it. It has tools for drafting lines, shapes, and stamps, all aligned to the lattice of your current map. If doing these kinds of sketches over hexagonal grids sounds like something that would fit your games, take a look at hexagons on GitHub and Foundry VTT. Contributions are very welcome!

If you just want to give it a try, jump straight into card-press.
The source code is available on GitHub.
For a step-by-step tutorial on how to execute the print-then-cut pipeline with the Cricut and card-press, check out Print & Play with Cricut.

The Story

Recently I've been studying the new Cricut Maker 4 that we got for the office. After a thorough intro by our resident expert, I started to wonder how well it would fare as a pipeline for the printing of prototype cards. It is an idea I've had for a while (some sort of automated cutting machine), but never really pursued it.

Previously, as I was experimenting with my (still work-in-progress) games, Dimensional Rift and Flaky Flasks, I'd either:

• print the cards at the office, and cut them myself, through an ever growing assortment of manual cutting implements - which was an excruciating amount of work and resulted in terrible quality due to my thorough lack of artistic ability; or
• paid some pretty penny for the corner print shop - to mixed results in terms of final quality.

As I plan to iterate on those and other game development projects, and since also have other pursuits that require mass printing-then-cutting (trying out new cards and decks from established games, or new games that are online-only, print-and-play, or otherwise niche and hard to find), I decided to give the Cricut idea a go. And, to my surprise, it did not take that much finagling to get it working!

The Paper

I have now trialled reams and reams of papers; I found that 300 gms (that's g/m² - they measure by area density instead of thickness, I can only imagine due to it being a more stable measurement over environmental conditions) is about the thickest our printer can handle; it is not as thick as a real TCG card, but close enough specially if you are sleeving. A well known trick is to add a real card behind the prototype in the sleeve, which also gives you the card back (for transparent sleeves). I usually use non-transparent sleeves and found that a single-sleeved 300 gms proxy has a good give for playing, even without the backing of a real card.

The finish on the paper was also up for debate; I found some people prefer the "glossy", while others were fascinated by the "satin". At first I had some trouble with the glossy print shedding ink (and staining everything), but that was due to my own idiocy on misconfiguring the printer. After enough experimentation, the double-glossy paper (when doing card backs) or the single satin (for no backs) emerged as winners.

The final variable was the paper size (i.e. dimensions). While I could easily squeeze a 3x3 MTG-sized grid on both A4 or Letter (and our printer can actually do even bigger paper sizes through a roll), the Cricut not only will exclusively cut a Letter-sized sheet (much to the dismay of any sane person), but the required template has expansive margins and cut marks, precluding any hope of fitting more than a 3x2 grid (which even then barely fits). There is some wasted paper - but the benefits of automatic cutting are beyond worth it.

With all that in mind, my current best pick for paper ended up being the Koala 300 gms double-glossy.

The Workflow

Even after creating and saving a "template" through very manual construction, the Cricut Design Space software (whether for the cut-and-print or anything else really) absolutely sucks for repeated workflows. You have to manually drag in the images (through a convoluted unskippable upload flow) on a new "project" each time; re-align, re-flatten and re-group; all by hand. I started to memorize coordinates so I could more easily input them. That is not a good sign. There seems to be no templating functionality whatsoever, no way to issue commands, nor to automate anything. Using it would be a nightmare for anything larger than a single page (of, remember, 6 measly cards).

So, I made my own software. Turns out the two parts of the process (printing and cutting) can be fully decoupled. My tool will generate the PDF for printing (using the Cricut or any other template as a base, with cut marks and all); and, then, to actually cut, you can just load up the empty Cricut project (without the card images or any modifications required). The cutting part does not care whether there are images or not - we trick the machine into thinking it is just cutting 6 black rectangles. In reality the images are there, because we printed an altogether different PDF (from my tool), that just so happens to perfectly align with the Cricut project.

The Software

card-press is a fully client-side webapp for generating print-then-cut PDFs for playing cards for TCGs, board games, or any other projects. Why yet another card template generator? I had a few design goals in mind; in order:

• support custom PDFs as templates (for the Cricut print-and-cut workflow);
• webapp (easily accessible) but fully client-side (fully offline, no uploading of any kind);
• ease of use; minimal but pleasing UI; zero fuss.

Even not considering the Cricut requirement, I couldn't find anything that satisfied my other goals. It is definitely still a work in progress, but ready to start battle testing. I've added additional features such as:

• very configurable and customizable;
• multiple sessions and templates, all saved locally;
• (mass) card upload via file picker, drag-and-drop, or pasting from clipboard;
• import cards from established TCGs (and my own);
• generating an additional "backs" pdf for printing on the other side of the sheet.

One important caveat to note: since all data including templates and card images is stored locally (on your local storage and indexed db), it will inevitably become slow if you load up a large swath of very high-res images. Though you are hopefully not going to be printing multiple hundreds of cards six a time (there ought to be better solutions at that point), if you notice any resource hogging (disk or otherwise), your storage can easily be managed through the Config tab.

I hope card-press helps anyone interested in card crafting!

The Final Touch

The final touch was the Kadomaru Pro corner cutter, whose ease of use is only surpassed by how satisfying its actuation is. It was the smallest corner radius I could find for the price, but still a bit bigger than a standard MTG rounding. I haven't explored making a rounded-corner template on the Cricut, but I suspect that would work very well, and also be fully compatible with card-press (should anyone wish to explore it).

This was a fitting end as the whole process could have been described as me trying to "cutting corners" on my previously excruciatingly manual process (though in this case the end result is so much better - I am relieved no none shall endure my cutting accuracy ever again). I am now excited to get back to work on my card games, knowing how painless, good, and cheap my prototypes will be. Who says you can't pick all three?

• I wanted it to be zero-CSS, just HTML and what your browser gives you
• I also despise light-mode

While I could expect all users to use some extension to change the CSS of all websites to dark mode (which would definitely work pretty perfectly on a non-CSS website), I kind of wanted to enshrine dark mode as a first-class experience. But I also just didn't want to write complex, arbitrary, ad-hoc CSS.

I've used simple css on a few projects before ([1],[2]), but I wanted something that was equally or even simpler, that I also could "drop in" to any semantic HTML with very basic assumptions, but also that looked the way I wanted it to look, inspired by my very bespoke design inclinations. So I extracted drop-in from another project and decided to have it on the back as my "default" stylesheet for web projects, including this one.

Now, for the purists, I kept an option to quickly nuke all the CSS back to smithereens - so you can still enjoy the "og" experience of a pure HTML website. I think at the end of the day this is a good compromise. It is still comfortably below the 512 KB mark (even after adding the Writer custom font by @tonsky).

This article was originally posted by me on Faire's Tech Blog.

At Faire, we have a very robust Kotlin backend service infrastructure that we’ve carefully honed over the years, powered by a collection of established libraries and frameworks used by the broader open-source community, all coupled with some special Faire glue to make it all work. And as many within the JVM world, for ease of database access without writing and mapping SQL queries to models by hand, we use Apache Hibernate. The Hibernate ORM is probably the most famous (infamous?) ORM framework of all time, and it has set the standard—and many of the pain points—for ORMs in general for several decades (yep, I know—feeling old yet?). It’s a polarizing topic. The discourse is often that people hate it but still use it, which leads me to compare it with that old democracy adage: it’s the worst way to do things, except for all of those other ways that have been tried from time to time.

It’s undeniable how easy Hibernate can make setting up basic database access, especially for smaller CRUD applications, by directly mapping tables to your POJOs, requiring very little boilerplate and glue. But it can lead to many issues that lead a lot of people to choose alternatives. But we’re not here today to talk about those, or discuss how to do ORMs or DB access in general (I leave that for the philosophers in the comments). Instead, I wanted to share a small way in which we made our usage of Hibernate, specifically the legacy Criteria API that we still use, a little bit better at Faire—taming one of its pain points with a creative solution. Hint: it will involve type-safety and KSP ;)

The Criteria API

The Criteria API is a legacy way of building queries. There are newer alternatives on newer Hibernate versions, including some that aim to fix this exact pain point we’re going to talk about. But if you’re in a large codebase that has evolved and adapted around the Criteria API, you might find newer alternatives can actually be more verbose, or require a bigger paradigm shift or migration that your team might not be ready or willing to accept. In which case, you will probably be familiar with your code for building queries currently looking something like:

criteria.add(Restrictions.eq("column", value))

If that looks anything familiar—this article is for you. Now, at Faire, we already had, for quite a while, a wrapper over this to make it nicer to use with Kotlin:

session.query<Book>
  .addEq("name", "Lord of the Rings")
  .list() // returns a List<Book>

That is a very thin wrapper we’ve been using and maintaining internally for years. However, it always bothered us that while we get back a fully typed List<Book>, consistent with the full-type-safety we know and expect in Kotlin, the actual arguments to the query were, let’s say, not ideal.

The column names are just String, and, even worse, the values are Any (that is from our Kotlin wrapper; the underlying Java API is just Object of course). If you make an incorrect assumption about your table, the best case-scenario is only catching that later on with unit tests (and that is the best scenario). After seeing again and again bugs and developer productivity hits, we had a dream of making this better.

But, as you can imagine, it was never a priority on top of other much-needed infrastructure improvements we’re always doing. Well, that all changed during one of our glorious Hack Weeks (an internal annual hackathon where everyone at Faire can participate and form teams to work on whatever projects their heart desires). And you can bet just what our heart desired.

So, during that pivotal Hack Week, we built a functional prototype of what would eventually replace our wrapper; a brand-new Hibernate Criteria API wrapper, with basically the same syntax we already knew and loved, minimally amended to provide one key benefit: full type-safety.

And over the course of the following 2 years (!!), we, slowly, whenever we had some spare time, migrated 61% of all queries across the entire codebase to the new infrastructure. As of now, we’re happy to say more than 11 of our production services are fully migrated. Given that, alongside the fact that all new queries are type-safe, we were able to reduce the number of magic-string induced incidents (and associated developer frustration only caught during tests) to zero.

As we rolled out this migration, we had to add support for different types of queries, refining the code-generation to power it, fixing bugs, listening to internal feedback, and thus homing in on what we now call, and are happy to introduce: Project Yawn.

Introducing: Project Yawn

This is what a Yawn query looks like:

session.query(BookTable) { books ->
 addEq(books.name, "Lord of the Rings")
}

That’s right! You get an object representing your Hibernate entity (BookTable), with all its fields. That means you get auto-complete, intellisense, and compile-time checks. But that’s not all—Yawn also knows the types of your columns, so it makes sure that the name column on the books table expects a String, and nothing else.

“But that is not going to cut it”, you might say, “I need complex queries!” Yawn has you covered—basically any query that can be written with Hibernate’s Criteria API can be written with Yawn, including complex and nested joins, projections, etc.

For example, here are the e-mails of all authors in the database whose favourite book is their own writing:

val emails = session.project(PersonTable) { people ->
  val favouriteBooks = join(people.favouriteBook)
  val favouriteBooksAuthors = join(favouriteBooks.author)
  addIn(people.name, authors)
  addEq(people.name, favouriteBooksAuthors.name)

  project(people.email)
}.list()

And we support much more: projection to data classes, sub-queries (detached and correlated), join references, and much more.

And that was all thanks to…

The magic of KSP

In order to power the creation of the meta-model representations of our tables based on our Hibernate entities, we use the power of Kotlin Symbol Processing, the official meta-programming framework in Kotlin. That means we hook up compilations steps to the compiler itself—no external tools, no scripts. It is pure Kotlin code that is automatically run when you add the Yawn dependency, and integrates well with IntelliJ or your preferred editor (references and go to definition all work out-of-the-box).

We have generators that scan through any entities Foo annotated with @YawnEntity on our Gradle module and generate a FooTable definition to be used for queries, maintaining the same visibility modifiers as the original class. It has references to columns and relationships, allowing for type-safe joins, and works with all Hibernate use-cases we had so far in our vast codebase (the hardest technical challenges were settling the exact shape and design of our APIs to support these edge cases such as embedded entities, composite keys, references with different foreign keys, etc).

After a period of tweaking the interfaces to be more ergonomic, fighting with the underlying Hibernate implementations, and wrangling some complex generics, the generators are now just plain Kotlin code, so they’re easily amendable by the entire team if there’s any feature missing.

We’ve tinkered with and refined it as we added to more usages and more complex use cases. But we wanted more—we wanted to share what we did with the community, in case other projects using Hibernate could benefit (and contribute!) to Yawn. So… we did.

OSS

We are thrilled to announce that we are officially fully open-sourcing Project Yawn under the MIT license! We believe in the power and community of open source, and while we use many tools and libraries, we want to contribute back with something we could share from our work.

You can check out the repository at github.com/faire/yawn for instructions on how to get started. We also welcome contributions and constructive feedback, and would love if you could give us a star!

And that’s not all—this is just one of a few pieces we’re happy to announce as part of a broader company-wide commitment to open-source and the developer community. We’ve started to build a dedicated public-facing OSS page at faire.tech/open-source where we aim to collect and catalogue projects we have (or have yet to) publish, as well as other contributions we’ve made over the years to existing and established libraries and tools we use every day.

If you’re interested in our other projects, I’d recommend checking out our faire-detekt-rules, a curated and opinionated collection of custom Detekt rules and configs that we use on our Kotlin modules. You can opt in many of the rules that help us catch bugs early on, standardize best practices, and just keep our code looking pristine.

If you’re looking to write more complex queries that Hibernate and Yawn can’t support, we highly recommend sqldelight (which, fun fact, also uses KSP under the hood), in which case you might want to check out the CRDB connector we open-sourced a while ago.

This is just the beginning of how we think Faire can contribute to the broader OSS community—stay tuned for new additions very soon as we work to extract other pieces of our codebase and infrastructure.

Many thanks to everyone at Faire and elsewhere that has helped us along the way, including, but not limited to, Adriel Martinez, Emily O’Leary, Jean Yang, Kevin Brightwell, Luan Nico, Micah Beech, Oren Kislev, Quinn Budan, Stas Novosad, and Zhiping Cai.

var result = longOperation(args);

Makes it very clear that the method will hold execution until it's done, so it can return the result string. While that's good and all, in a more event based language like JS, that has a single thread, it can be dangerous to go around performing a long chain of operations in a single event dispatch. Therefore, it's very common to see a method like this:

longOperation(args, function (result) {
  display(result);
});

This new version of longOperation, now written in JS, takes the same args as before but also takes a function (making usage of JS incredible powerful functional programming paradigm), that is callback. A callback is not but a function that is going to be "called back" when the first function ends. The existence of such callback, instead of a return statement, should make it clear the first function is asynchronous, i.e., it returns immediately, and just gives the result later on. This is a simple distinction that must be made; for instance, take the following two snippets:

// test A
longOperation(args, function (result) {
  console.log(result);
});
console.log("after");

// test B
var result = longOperation(args);
console.log(result);
console.log("after");

Note that test B will always give the described result, i.e., it will first print the result and then 'after'. However, one must note that the first (test A) example will always first print 'after' and then prints the result. This is a simple yet fundamental shift of perspective that would shape the JS development significantly throughout its history. Yet when we try to accomplish something just a little bit more complex, we run into some annoyances. Let's take a look at the following, more in depth example:

longOperation1(args, function (result1) {
  longOperation2(result1, function (result2) {
    display(result2);
    triggerScreenChange(function () {
      warnUser(function (response) {
        sendServerFeedback(response);
      });
    });
  });
});

As you can see, the code quickly gets a mess as the lines get further and further to the right. This phenomenon shared by every imperative C-like language is labelled callback hell, or more appropriately, Pyramid of Doom (referencing the triangular shape formed by each line start).

How can we make it prettier and easier to understand? Well, let's begin with a simple premise (no pun intended): instead of receiving a callback, the function will return an object that will work as a configurer, that will allow you to setup the callback later on. The API will look like something like this:

var configurer = longOperation(args);
configurer.setupCallback(function (response) {
  display(response);
});

Well, that seems pretty similar. Firstly, let's study how one would be able to go around doing that. Let's assume we have a synchronous opSync; we could then create the function op:

var op = function (args) {
  var callback = null;
  var configurer = {
    then: function (aCallback) {
      callback = aCallback;
    },
  };

  setTimeout(function () {
    var result = opSync(arg);
    callback(result);
  }, 0);

  return configurer;
};

This is a very naïve approach, of course, as it doesn't account for the possibility of the callback not being set upon resolution, for example. But it clearly shows how easy it is to turn a sync operation into a configurer. Now let's see how we would use the API:

op1(args).then(function (result1) {
  op2(result1).then(function (result2) {
    op3(result2).then(function (result3) {
      op4(result3).then(function (result4) {
        sendServerFeedback(result4);
      });
    });
  });
});

Well... I guess nothing changed, right? Well, that's because we failed to see the greatest advantage of this schema. Our then function was void, but we can make it return another configurer, to attach callbacks after it has ended. Now you can see where this is going... Basically this is making a Builder for the PoD! The structure would look like this:

op1(args).then(op2).then(op3).then(op4).then(sendServerFeedback);

That's right, we can do all that with a single like, as long as our functions are configurer compatible. Now that we understood the concept, let's call our configurer by their actual name: promises. So someone could build this incredible library, that's similar to what we already did, but actually returns subsequent promises and also checks for errors and more? Well, of course they did that. Actually, plenty of people did.

One example is q, a very simple JS lib that does that; its syntax would look something like this:

Q.fcall(promisedStep1)
  .then(promisedStep2)
  .then(promisedStep3)
  .then(promisedStep4)
  .then(function (value4) {
    // Do something with value4
  })
  .catch(function (error) {
    // Handle any error from all above steps
  })
  .done();

Taken directly from their docs. Pretty neat, hu?

So for some time people were very happy using several of q-like libs, but some libs started depending on these promise libs, and things started to get messy again, as one would need to write a converter to convert between different terminologies. Eventually a bunch of people got together and made A+, a spec for all promise libs to follow.

After that, this standard got accepted as native in JS, and ECMA 6 finally added the Promise object. It is A+ compatible, native, and made obsolete all promises lib. Now everyone could use that and live happily ever after - more details on the story in this article. It also added very interesting methods, like Promise.all(), which are of crucial importance for larger apps to remain concise and pretty.

After that, there was more development, and now we have a Stage 3 proposal for the next release to add the await/async keywords to the language and change promises once again.

That's it!