DEV Community: Derk-Jan Karrenbeld

Predicate (Programming logic)

Derk-Jan Karrenbeld — Wed, 03 Jun 2020 12:38:46 +0000

Originally published at derk-jan.com. I have recently taken up writing, again and am trying to commit to at least one helpful post each week for the next 49 weeks.

In university I had to study Prolog when using Goal, in order to create an agent (artificial intelligence) to play and win capture the flag in Unreal Tournament. This article is not about Prolog, or Goal, but it helps me to mentally model what predicates are.

Predicates in English

In English, a predicate is a verb phrase template that describes a property, or a relationship, represented by the variables in that template. For example, the phrases "Jessica is running", "The program is running" and "The machine that assembles the car parts is running" all come from the same template "x is running", where x is replaced by the appropriate noun or noun phrase. The phrase "is running" is a predicate, and it describe the property of 'being in a running state'.

This does not limit itself to properties, as "The function produces an error when it runs", "The operation produces a value when it compiles" and "The API produces a new model when it is deployed" are all created by substituting the a, b and c in the template "a produces b when c". The latter is a predicate and describes the relationship between two objects and a state. This could be represented as Produces(A, B, C) or even P(a, b, c).

Predicates in Programming

Now, in mathematical logic, predicates are usually Boolean-valued functions which isn't much more than a function that takes a set of inputs, and only outputs a boolean value.

For example:

number = 2

isEven(number)
// => true

The function isEven takes a set of inputs (all natural numbers) and returns true or false, based on the predicate. More concretely, it returns true if it satisfies the predicate, and false otherwise. The function isEven is therefore a predicate.

Apart from specifically creating functions that return true or false, predicates are used all over. For example, in many languages there is a filter() function on something that is enumerable, like a list-like data structure.

import java.util.Arrays;
import java.util.List;
import java.util.function.Predicate;

public class JavaExample {

    public static void main(String[] args) {
        List<Integer> numbers = Arrays.asList(1, 2, 3, 5, 8, 13, 21, 34);
        Predicate<Integer> isEven = n -> n % 2 == 0;

        numbers.stream()
               .filter(isEven)
               .forEach(System.out::println);
  }
}

// 2
// 8
// 34

In this Java example, the lambda (anonymous function, which we've named isEven) has the type Predicate<Integer>, which is a function that takes an Integer and returns true or false. The function is a predicate. The predicate is passed into the function .filter(), which will execute the predicate for each item in the list.

isEven(1)
// => false

isEven(2)
// => true

isEven(5)
// => false

isEven(8)
// => true

isEven(13)
// => false

isEven(21)
// => false

isEven(34)
// => false

The final "list" of items that makes it to the .forEach are those that evaluate to true, because that is what .filter() does: keep the items for which the predicate returns true.

A language doesn't need to be typed to support predicates. Here is the equivalent example in JavaScript:

const numbers = [
  1, 2, 3, 5, 8, 13, 21, 34
]

const isEven = (n) => n % 2 === 0

numbers
  .filter(isEven)
  .forEach((i) => console.log(i))

// 2
// 8
// 34

Again, each value in the numbers array is given to the isEven() predicate, and those that evaluate the predicate to true, will be kept (and are then logged in the .forEach). It doesn't really matter if you name the predicate, using an in-line, anonymous function doesn't change the fact that it's a predicate:

const numbers = [
  1, 2, 3, 5, 8, 13, 21, 34
]

numbers
  .filter((n) => n % 2 === 0)
  .forEach((i) => console.log(i))

// 2
// 8
// 34

Ruby has a language feature built-in to support predicates! Predicate methods in Ruby are those methods that end with a question mark ?; they return either true or false. The same example in Ruby looks a bit like this:

NUMBERS = [1, 2, 3, 5, 8, 13, 21, 34]

NUMBERS.select { |i| i.even? }
       .each { |i| p i }

# Or alternatively
NUMBERS.select(&:even?)
       .each { |i| p i }

# 2
# 8
# 34
# => [2, 8, 34]

Conclusion

Predicates are used all over, and now you can name them as such. Each time a function (e.g. .filter()) takes an argument - an argument that must be a function itself; a function which returns true or false based on some input (e.g isEven) - you know you're dealing with a predicate.

Oh, and in Prolog? In Prolog define an even predicate like this:

even(X) :- 0 is mod(X, 2).

? even(1)
false

? even(2)
true

And then filter a list based on even items:

/** Predicates */

even(X) :- 0 is mod(X, 2).
odd(X)  :- 1 is mod(X, 2).

/**
 * Filter the list on even elements only
 * 1. true when empty
 * 2. otherwise, there are two options
 *    - if Element (first item) is odd, the Next list does not get Element
 *    - if Element is even, the Next list gets Element
 */
filter([], []).
filter([Element|Tail],        Next) :-  odd(Element), filter(Tail, Next).
filter([Element|Tail], [Element|T]) :- even(Element), filter(Tail, T).

/**
 * Prints a list by iteration through each element
 * 1. true when empty
 * 2. separate Element (first item) and the Tail (...rest)
 *    - write the element + new line
 *    - continue printlist with the tail of the list
 */
printlist([]).
printlist([Element|Tail]) :-
    write(Element),nl,
    printlist(Tail).


?- filter([1, 2, 3, 5, 8, 13, 21, 34], NewList), printlist(NewList).

2
8
34

Want these short articles in your e-mail? 📧 Sign up for my newsletter.

Cross tab events

Derk-Jan Karrenbeld — Wed, 27 May 2020 14:18:00 +0000

Originally published at derk-jan.com. I have recently taken up writing, again and am trying to commit to at least one helpful post each week for the next 50 weeks.

Last week I had an instance where I needed to update all tabs of the same site when a user chose something from a dropdown. Think of the dropdown's current value being a global setting and changing it on one tab, feels like it should change it every where.

Use a `BroadcastChannel`

The recommended way is to use a BroadcastChannel, which takes a name upon construction, which is unique for all browsing contexts of the same origin. In other words, most of the time this equals all tabs and windows on the same site. One of the great things about BroadcastChannels is that there is no real indirection, and it is available in Web Workers.

function reload({ timeRange }) {
  // fictional function that reloads the current page contents
}

function handleSettingsBroadcast(event) {
  switch (event.data.type) {
    case 'time-range.changed': {
      reload({ timeRange: event.data.value })
    }
  }
}

const channel = new BroadcastChannel('settings')
channel.onmessage = handleSettingsBroadcast

// Callback when the drop down is changed
function onChangeTimeRange(nextValue) {
  channel.postMessage({ type: 'time-range.changed', value: nextValue })
}

In the example above, I've chosen to use a single channel settings, with structured data. You could, instead, make
a channel per "message-type", or even use a single channel com.yourdomain.app for everything.

React use case

If you're using something like flux, redux or another state manager, you can send "updated state" across tabs, but be weary: if you have side-effects on state changes, this will run those side-effects multiple times.

Additionally, you can use a hook to receive updates, for example:

function useBroadcastValue(channel, event, initial = undefined) {
  const [value, setValue] = useState(initial)

  useEffect(() => {
    // Create a new channel on this name. The channel will be able to receive
    // data as long as it's not closed.
    const broadcastChannel = new BroadcastChannel(channel)

    // Receives messages and forwards them to the setValue dispatch if they
    // match the type. This requires each event in this channel to have the
    // shape:
    //
    // {
    //   type: 'event-type',
    //   value: <some value>
    // }
    //
    broadcastChannel.onmessage = (ev) => {
      ev.data.type === event && setValue(ev.data.value)
    }

    // Close the channel -- we no longer want to receive messages
    return () => {
      broadcastChannel.close()
    }
  }, [channel, event])

  return value
}

// ...

function MyComponent() {
  const timeRange = useBroadcastValue('settings', 'time-range.updated')
  // ...
}

In the same fashion, a "send on change" broadcast can be achieved:

function useBroadcastState(channel, event, initial = undefined) {
  const [value, setValue] = useState(initial)
  const [broadcastChannel, setBroadcastChannel] = useState()

  // You can do all this without a use-effect, as it's not expensive code. You
  // could also do this in a single use-effect. However, I've often gotten
  // questions how you do something like this: have two variables and update
  // them independently, whilst maintaining integrity. This is how you could do
  // that.

  useEffect(() => {
    // Create a new channel on this name. The channel will be able to receive
    // and send data as long as it's not closed.
    const pipe = new BroadcastChannel(channel)

    // This allows the channel to be used outside this effect
    setBroadcastChannel(pipe)

    // Close the channel -- we no longer want to receive or send messages, as
    // the channel name has changed (or the hook is in a component that is being
    // unmounted).
    return () => {
      pipe.close()
    }
  }, [channel])

  useEffect(() => {
    broadcastChannel.onmessage = (ev) => {
      ev.data.type === event && setValue(ev.data.value)
    }

    // Each time the channel changes (different name, initial mount) or the
    // event we want to listen to changes, run this hook.
  }, [broadcastChannel, event])

  const setAndBroadcastValue = useCallback(
    (nextValue) => {
      // Broadcast the value
      broadcastChannel.postMessage({ type: event, value: nextValue })

      // ...but also update it locally
      setValue(nextValue)
    },
    [broadcastChannel, event]
  )

  return [value, setAndBroadcastValue]
}

// ...

function MySettingComponent() {
  const [timeRange, setTimeRange] = useBroadcastState(
    'settings',
    'time-range.updated'
  )
  // ...
}

Compatibility

Support is pretty good, but at moment of writing, no Safari. This probably makes this solution not-workable for many of you. Luckily, there is a, now almost "ancient" way to do this with even better support.

Use `localStorage`

LocalStorage has been around for longer and that shows when you look at the support. Not only is it supported on Safari, it also works on mobile browsers and even IE. Great.

How can we use localStorage to send data across tabs? As you can imagine, data from localStorage is available in all the tabs of the same origin (scheme, port, hostname), but that doesn't magically broadcast changes everywhere. It actually does!

function reload({ timeRange }) {
  // fictional function that reloads the current page contents
}

function handleSettingsBroadcast(event) {
  switch (event.key) {
    case 'settings.time-range.changed': {
      reload({ timeRange: event.newValue })
    }
  }
}

window.addEventListener('storage', handleSettingsBroadcast)

// Callback when the drop down is changed
function onChangeTimeRange(nextValue) {
  localStorage.setItem('settings.time-range.changed', nextValue)
}

React hook

The implementation for a react hook is less complex:

function useBroadcastState(event) {
  // Get the initial value from local storage. Remove the initializer if you
  // don't intend to store the value _anyway_. For our settings, it makes
  // perfect sense, as they're not sensitive.
  const [value, setValue] = useState(() =>
    JSON.parse(localStorage.getItem(event) || 'null')
  )

  useEffect(() => {
    const onStorage = (ev) => {
      if (ev.key !== event) {
        return
      }

      setValue(JSON.parse(ev.newValue))
    }

    // This will trigger on storage events. That usually means that it will
    // trigger in all browsing contexts that are currently blurred (so not the
    // current, active/focussed one). This doesn't hold for older browsers. IE10
    // for example will send the event to the calling tab as well. That's okay,
    // just expect a double render.
    window.addEventListener('storage', onStorage)

    return () => {
      window.removeEventListener('storage', onStorage)
    }
  }, [event])

  const setAndBroadcastValue = useCallback(
    (nextValue) => {
      // Broadcast the value
      localStorage.setItem(event, JSON.stringify(nextValue))

      // ...but also update it locally
      setValue(nextValue)
    },
    [event]
  )

  return [value, setAndBroadcastValue]
}

Onwards

There are various ways to send information across tabs. This can be really helpful if context is key. Users sometimes open sites in many tabs at the same time. Here are some examples:

In CMS or on edit pages, you can broadcast that editing is in progress in a different tab
In systems where you only want one socket connection open, you can broadcast that socket connections should close
In adminsitrative dashboards you might want to reload index/show pages when content is CRUDed, for that type

Want these short articles in your e-mail? 📧 Sign up for my newsletter.

FFMPEG examples

Derk-Jan Karrenbeld — Wed, 20 May 2020 11:51:41 +0000

Originally published at derk-jan.com. I have recently taken up writing, again and am trying to commit to at least one helpful post each week for the next 51 weeks.

For Sounders Music I had to write a few new file processors. In their eco-system, audio tracks are uploaded and transcoded to a format that is playable in their front-ends, such as their apps.

ffmpeg is a free and open-source library which, depending on how it's built, supports (almost) all industry standard encodings. On top of that: it works cross-platform! Their documentation is very extensive and, with a bit of patience and perseverance, you can probably make most of it work. This article holds some of the commands I regularly need when working with media files.

This is written for FFMPEG 4.2.2+. It will probably work with most versions in the 4.x.x range, but YMMV.

Transcoding a file

From WikiPedia:

“Transcoding is the direct digital-to-digital conversion of one encoding to another, [1] such as for movie data files, audio files (e.g., MP3, WAV), or character encoding (e.g., UTF-8, ISO/IEC 8859).”

The following command converts any media file to an .mp4 (with audio encoded using Advanced Audio Coding).

ffmpeg -y -i input_path -c:a aac -b:a 160k -vn -f mp4 -movflags +faststart output_path

-i: Takes the input at input_path;
-y: Writing at output_path, overwriting;
-c:a: Transcodes all audio streams using the Advanced Audio Coding (AAC) encoder (aac);
-b:a: Setting the bitrate of all audio streams to a CBR of 160k bits per second;
-vn: Blocking all video streams;
-f: Forcing the type of the file (instead of guessing it based on the file name);
-movflags +faststart: And ensuring that the output mp4 has its metadata moved to the start, so that it can start playing earlier

The Advanced Audio Coding works on all our target devices (such as modern browsers, Android and iOS devices) and the bitrate chosen is generally a good trade-off between size and quality.

I generally have to force the "input type" because the files come in without an extension. However, I do usually determine the type using a mime-type analyzer before calling this function (Ruby, JavaScript or TypeScript)

Blocking the video streams seems to save some processing time and, if not correctly configured, ensures that the output is really an audio file. It also allows to accept video ánd audio files.

Finally the movflags enhance the playback when streaming or preloading the file. Normally, a MOV/MP4 file has all the metadata about all packets stored in one location (written at the end of the file, it can be moved to the start for better playback.

Example call and output

ffmpeg -y -i ./"-3 Daniel Powter - Bad Day.mp3" -c:a aac -b:a 160k -vn -f mp4 -movflags +faststart ./"Daniel Powter.mp4"

ffmpeg version 4.2.2 Copyright (c) 2000-2019 the FFmpeg developers
  built with gcc 9.2.1 (GCC) 20200122
  configuration: --enable-gpl --enable-version3 --enable-sdl2
   --enable-fontconfig --enable-gnutls --enable-iconv --enable-libass
   --enable-libdav1d --enable-libbluray --enable-libfreetype --enable-libmp3lame
   --enable-libopencore-amrnb --enable-libopencore-amrwb --enable-libopenjpeg
   --enable-libopus --enable-libshine --enable-libsnappy --enable-libsoxr
   --enable-libtheora --enable-libtwolame --enable-libvpx --enable-libwavpack
   --enable-libwebp --enable-libx264 --enable-libx265 --enable-libxml2
   --enable-libzimg --enable-lzma --enable-zlib --enable-gmp --enable-libvidstab
   --enable-libvorbis --enable-libvo-amrwbenc --enable-libmysofa
   --enable-libspeex --enable-libxvid --enable-libaom --enable-libmfx
   --enable-amf --enable-ffnvcodec --enable-cuvid --enable-d3d11va
   --enable-nvenc --enable-nvdec --enable-dxva2 --enable-avisynth
   --enable-libopenmpt
  libavutil      56. 31.100 / 56. 31.100
  libavcodec     58. 54.100 / 58. 54.100
  libavformat    58. 29.100 / 58. 29.100
  libavdevice    58.  8.100 / 58.  8.100
  libavfilter     7. 57.100 /  7. 57.100
  libswscale      5.  5.100 /  5.  5.100
  libswresample   3.  5.100 /  3.  5.100
  libpostproc    55.  5.100 / 55.  5.100
Input #0, mp3, from './-3 Daniel Powter - Bad Day.mp3':
  Metadata:
    title           : Bad Day
    comment         : www.mediahuman.com
    Software        : Lavf58.20.100
    artist          : Daniel Powter
  Duration: 00:03:55.18, start: 0.025057, bitrate: 182 kb/s
    Stream #0:0: Audio: mp3, 44100 Hz, stereo, fltp, 182 kb/s
    Metadata:
      encoder         : LAME3.98r
Stream mapping:
  Stream #0:0 -> #0:0 (mp3 (mp3float) -> aac (native))
Press [q] to stop, [?] for help
Output #0, mp4, to './Daniel Powter.mp4':
  Metadata:
    title           : Bad Day
    comment         : www.mediahuman.com
    Software        : Lavf58.20.100
    artist          : Daniel Powter
    encoder         : Lavf58.29.100
    Stream #0:0: Audio: aac (LC) (mp4a / 0x6134706D), 44100 Hz, stereo, fltp, 160 kb/s
    Metadata:
      encoder         : Lavc58.54.100 aac
[mp4 @ 0000021d07bf3940] Starting second pass: moving the moov atom to the beginning of the file
size=    4636kB time=00:03:55.14 bitrate= 161.5kbits/s speed=78.9x
video:0kB audio:4596kB subtitle:0kB other streams:0kB global headers:0kB muxing overhead: 0.881678%
[aac @ 0000021d07c18a40] Qavg: 508.682

Probing the duration

In the example above, there is a Input section with Metadata and Duration. This information can be extracted using ffprobe.

ffprobe input

In particular, I am interested in the duration of the file.

ffprobe input -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1

-v: Sets the log level to error, set that only errors and the "formatted" output is shown;
-show_entries: When this is present, the output only contains the entries as set in this option. Its value (section:field) will result in an output [SECTION]field=value[/SECTION];
-of: Output format, also as -print_format, which is set to use the default formatted, but remove the wrapper ([SECTION]) and remove the field= key portion;

What remains as output is either an error message or the duration, in (partial) seconds.

Example call and output

ffprobe "Daniel Powter - Bad Day.mp4" -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1
235.152000

Want these short articles in your e-mail? 📧 Sign up for my newsletter.

Forward arguments in shell

Derk-Jan Karrenbeld — Wed, 13 May 2020 14:16:00 +0000

Originally published at derk-jan.com. I have recently taken up writing, again and am trying to commit to at least one helpful post each week for the next 52 weeks.

For one of my CLIs, I needed to remove the first argument from the argument list and forward the rest to a next process. In this example, my shell script is called cli_process and given arguments arg1, arg2 and arg3, I want to execute forward_process with arg2 and arg3.

#!/usr/bin/env bash

# Documentation on @
#   https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#index-_0040
# Documentation on shift [n]
#   https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#index-shift
# Why quoting the argument is "necessary":
#   https://stackoverflow.com/questions/4824590/propagate-all-arguments-in-a-bash-shell-script/4824637#4824637

# eats 1 argument
shift 1

# forwards the rest to "forward_process"
forward_process "$@"

Originally posted as a gist, by myself.

Windows

Windows .bat files support a similar token: %*, which is equivalent to $@.
However, the SHIFT command, unlike the bash equivalent shift, doesn't modify this special token. There are various solutions that will attempt to eat the first n parameters, but all of them have edge-cases in which they don't properly work. Should you need this in windows, I recommend you write out the arguments manually %2, %3 (and skip %1).

Here you can find some Windows solutions, but make sure you check the comments underneath each one:

Resources

Bash documentation for @
Bash documentation for shift
StackOverflow (4824590) on why you need the "quotes" around "@\$"

Want these short articles in your e-mail? 📧 Sign up for my newsletter.

Internship 2019: Reading list

Derk-Jan Karrenbeld — Wed, 09 Oct 2019 16:57:02 +0000

During the first half of 2019, XP Bytes had two interns on the
payroll. This time it were two students from Techniek College Rotterdam, both studying to become an "Applicatieontwikkelaar" (Software Developer). As a general rule at XP Bytes, before students may accept their position, they have to agree to a few things, among which:

Reading and summarising at least 4 articles as given by the program manager
Keep their programming fresh with exercises regarding their internship

If a student is unable or uncomfortable to read in English, which might not be their first language, or a language they're proficient at, we will attempt to provide alternatives in the form of recording or audible content.

Both students graduated with good grades, and it's now time to close the book on past year's projects, which also includes archiving and documenting all the content that came out of this internship. To that end, we will release a series of articles that may aid you during your road to become a developer or may be used as a potential reading list.

Before I list the articles, you should know one more thing. We don't expect the student to understand everything or even grasp all the details. Instead, it's to prepare them on writing technical or semi-technical articles for the weeks to come, as well as trying to get them interested in the various products and aspects of writing software. If you're reading some of these and feel as if you don't know enough, that's okay. I would suggest to read it anyway, and come back to it, once you know more.

The Law of Leaky Abstractions

11 November 2012, 11 min read

This article by Joel Spolsky might be "old", its contents are (still) relevant. The reason we put it on the reading list, is that we often see incorrect or inconvenient abstractions, regardless of the level of the developer. However, It's good to know that abstractions are exactly that: not the concrete reality, and that every abstraction leaks: they are imperfect. And that's okay. This article shows how some well known abstractions are imperfect.

Why You Need to Build an MVP App (and 5 tips on how to do it)

13 June 2017, 9 min read

Why You Need to Build an MVP App (and 5 tips on how to do it) | by Jessi Salonen | The Startup | Medium

Jessi Salonen ・ Jun 19, 2017 ・ 9 min read
Medium

Most of us no longer use the waterfall model as our development cycle; we often have way more ideas than time to implement those ideas; we don't know where to start when we're building an app. Building an MVP (minimal viable product) can be a great strategy when tackling issues and challenges surrounding these concepts.

What the heck is a callback

12 June 2017, 5 min read

JavaScript: What the heck is a Callback? | by Brandon Morelli | codeburst

Brandon Morelli ・ Jul 5, 2017 ・ 5 min read
codeburst.io

In JavaScript, functions can be passed around as values. Sometimes code doesn't execute in-line (synchronously), but rather concurrently (asynchronously). When an asynchronous task finishes, we often want to be notified and execute some code. This article talks about what callbacks are, what they look like, and how or when you could need and use them.

JavaScript Event Loop Explains

27 December 2017, 4 min read

JavaScript Event Loop Explained. “How is JavaScript asynchronous and… | by Anoop Raveendran | Frontend Weekly | Medium

Anoop Raveendran ・ Nov 9, 2018 ・ 4 min read
Medium

A lot of JavaScript is used in browsers, and browsers do more than just executing JavaScript. JavaScript has various tools to schedule work or to listen for events (such as mouse clicks) and execute work once these occur. How this ties into responsiveness (vs freezing), and when scheduled calls are executed, is explained using the JavaScript "Orchestrator": The Event Loop.

Web fonts: when you need them, when you don’t

13 August 2017, 17 min read

Web fonts: when you need them, when you don’t | by David Gilbertson | HackerNoon.com | Medium

David Gilbertson ・ May 22, 2019 ・ 17 min read
Medium

Our interns and juniors often know what fonts are and that you can use certain ones via CSS on web pages. Sometimes they also know about services such as Google's web fonts. It usually comes as a shocker when one of us tells them about all the issue, limitations and challenges that come with using web fonts. This article is a good summary of our decision tree for using or not using web fonts.

Building the Google Photos Web UI

10 July 2018, 27 min read

Building the Google Photos Web UI | by Antin Harasymiv | Google Design | Medium

Antin Harasymiv ・ Jul 10, 2018 ・ 27 min read
Medium

If you use Google Photos you might have noticed how well it scrolls, and how nicely it can zoom in and out. Sometimes our interns need to build an app that can display thousands of items of data. We don't expect them to be able to optimise that, but we do want to give them some sense in what went into it at the tech giant Google. Hopefully they (and you) find this as intruiging as we find it. It's not meant as a tutorial, but definitely should be a good and interesting read.

API Versioning Has No "Right Way"

26 September 2017, 8 min read

Naming things is hard, versioning is harder, or so I personally like to say. Especially for those interns and juniors that will work on or build an API, we like to give them this article first, before they dive into the way we have implemented API versioning in our system. Additionally, if it makes sense, we send them over to read this article about Stripe's API and their versioning.

Web Architecture 101

7 November 2017, 11 min read

Web Architecture 101. The basic architecture concepts I wish… | by Jonathan Fulton | Storyblocks Product & Engineering

Jonathan Fulton ・ Dec 12, 2018 ・ 11 min read
engineering.videoblocks.com

The subtitle is "The basic architecture concepts I wish I knew when I was getting started as a web developer" and I think that pretty much sums up why we recommend this article. It's mostly a nice glossary and explanation of certain concepts you'll need to think about when building on and for the web.

How to visually design state in JavaScript

20 July 2018, 15 min read

The reason this article is on the list is that we want our juniors to get a bit more comfortable with graph theory. Its core contents is actually not about JavaScript at all, but expresses pretty well how we like to design on paper whenever we have to deal with states and their transitions.

The ultimate guide to proper use of animation in UX

5 September 2018, 11 min read

The ultimate guide to proper use of animation in UX | by Taras Skytskyi | UX Collective

Taras Skytskyi ・ Mar 9, 2019 ・ 11 min read
uxdesign.cc

I personally don't agree that this is thé ultimate guide, but it certainly is comprehensive, and most of all crystal clear. The animations itself are executed perfectly, conveying exactly what they intend to convey. Animation is not necessarily hard, but it's easy to try to slap on animation. This guide gives great guidelines and rules when it comes to using animation to benefit UX instead of just using animation.

Everything you need to know about skeleton screens

19 October 2018, 14 min read

Everything you need to know about skeleton screens | by Bill Chung | UX Collective

Bill Chung ・ Jun 5, 2020 ・ 14 min read
uxdesign.cc

Skeleton screens are powerful and research shows that they can help reducing the perceived load time of any application (Web or not). This article is a good in-depth resource about that exact research, the different ways to accomplish adding a skeleton screen and what exactly should be on it / in it.

Animation principles for UX and UI designers

13 December 2018, 11 min read

Animation principles for UX and UI designers | by Vernon Joyce | UX Planet

Vernon Joyce ・ Jul 16, 2019 ・ 11 min read
uxplanet.org

Whereas the "ultimate guide" is an amazing "rules and guidelines" article, this particular entry of our recommended reading list talks about the properties of animation and concepts on a bit more abstract level. In other words, if you work with these concepts in mind, you hopefully don't need the guidelines at all.

The reading list is not the final list of resources our interns used this year
and we'll be releasing more resources as time passes, as part of a series.

Want to help people learn programming languages?

Derk-Jan Karrenbeld — Thu, 26 Sep 2019 02:19:15 +0000

Exercism is an online platform designed to help you improve your coding skills through practice and mentorship. It currently provides over 50 language tracks.

Exercism provides you with thousands of exercises spread across numerous language tracks. Once you start a language track you are presented with a core set of exercises to complete. Each one is a fun and interesting challenge designed to teach you a little more about the features of a language.

At the moment of writing, I'm a maintainer of the JavaScript and TypeScript track and a while back we've started working on automating a part of the experience.

Writing a code analyzer in TypeScript (from scratch)

Derk-Jan Karrenbeld for XP Bytes ・ Jun 10 '19

#typescript #showdev #opensource #tutorial

The post above talks extensively about how to write an analyzer and what went into this work.

As part of Hacktoberfest, I have updated the javascript-analyzer and javascript-track contributing guidelines. Other maintainers have done the same for their repositories.

What can you work on

Because there are so many projects running at Exercism, there is also a lot you can work on. Here is a short list of the things I find the most interesting.

I'm super biased, but with 160 repositories, and at least 90 active in the past month, there is plenty for anyone and everyone.

Help out your favourite language

Given that we have over 50 language tracks, your favourite language is possibly one of them. Many of them have open issues, and all of them allow for new exercises to be ported from other tracks.

Checklist: exercises that could be implemented #660

SleeplessByte posted on Apr 04, 2019

Hi there (new) contributors.

The way this works is you can follow the link below to the problem specifications. This is the canonical data we have for this exercise. If you want a grasp of how this exercise might look, have a look at other tracks, where this exercise is implemented. You'll probably want to start with similar languages such as typescript and coffeescript, and then perhaps other loosly-typed languages such as ruby or python.

Open a new issue, we'll label it with new exercise ✨
We'll assign the issue to you, so you get to work on this exercise
Create a new folder in /exercises
You'll need to sync this folder with the matching config files. You can use scripts/sync to do this: ASSIGNMENT=slug npx @babel/node scripts/sync.
Create a <slug>.js stub file.
Create a <slug>.spec.js test file. Here add the tests, per canonical data if possible.
Create a example.js file. Place a working implementation, assuming it's renamed to <slug>.js
Run the tests locally, using scripts/test: ASSIGNMENT=slug npx @babel/node scripts/test.
Open a PR.

NOTE: Use this link for a ⚡️ live list of unimplemented exercises.

View on GitHub

Write an analyzer, or help improving one

There are currently 17 (or more) analyzers! This means that there are many tracks without any analyzer infrastructure. If you know a language well, you can help out with that. However, I would love your help on the javascript-analyzer or typescript-analyzer.

Write a complete new analyzer for an existing exercise. We will provide 500 fixtures and what should be approved and what shouldn't. We'll help writing some initial messaging, you don't need to worry about that.
Help improving an existing analyzer. The coming week, more issues will be opened to indicate where improvement is required!

Improve resistor-color-duo: detect unary + #56

SleeplessByte posted on Sep 26, 2019

Describe the improvement:

When a solution has +expression instead of Number(expression), and it's otherwise optimal, we want to give a specific message. It should still approve, but add a message that Number(...) is preferred over unary +.

Which exercise

resistor-color-duo

View on GitHub

Improve resistor-color-duo: detect string concat #55

SleeplessByte posted on Sep 26, 2019

Describe the improvement:

When the following main method is provided, the analyzer bails early:

export const value = arr => {
  return +(COLORS.indexOf(arr[0]) + "" + COLORS.indexOf(arr[1]));
};

Instead, it should be caught by hasDigitsString, and produce the same comment.

Which exercise

resistor-color-duo

Additional context

The ResistorColorDuoSolution has a method that checks if an exercise has a constructed string. It currently only detects a string template literal that looks like ${a}${b}, but we want to also capture the following:

`${a}` + `${b}`
a + "" + b
a + '' + b
""  + a + b
''  + a + b
a.toString() + b
a.toString() + b.toString()
a.toString().concat(b)

View on GitHub

Add analyzer for rna-transcription #53

SleeplessByte posted on Sep 26, 2019

This issue is for discussion and assignment for the rna-transcription core exercise in the javascript track.

🔗 implementation | mentor-notes | problem-specification

This exercise focuses on

String iteration (String#replace, String#split)
Object/Map

Optimal solution

const TRANSCRIPTION = {
  C: 'G',
  G: 'C',
  A: 'U',
  T: 'A',
};

export function toRna(sequence) {
  return sequence
    .split('')
    .map(nucleotide => TRANSCRIPTION[nucleotide])
    .join('')
}

Variations include Set or Map with #get, which are valid!

Variations (approvable without comment)

String destructuring can also be used:

return [...sequence].map(/**/).join('')

String#replace can also be used:

return sequence.replace(/./g, (nucleotide) => /* */)

Variations include replacing only the "known" nucleotides:

sequence.replace(/[CGAT]g/, (nucleotide) => /* */)

Helper function variation

Instead of an anonymous function, a helper function may be used:

function transcribe(nucleotide) {
  return TRANSCRIPTION[nucleotide]
}

This also allows for a version without a mapping object:

function transcribe(nucleotide) {
  switch(nucleotide) {
    case 'C': { return 'G' }
    case 'G': { return 'C' }
    case 'A': { return 'U' }
    case 'T': { return 'A' }
  }
}

SHOULD comment and disapprove

Cases we SHOULD comment on with this analyzer:

Use an Object to keep track of the mapping instead of conditionals.
Use iteration via String#split or String#replace instead of using for/forEach with Array#push
Discourage Array#reduce for this particular solution, because it creates a lot of intermediary strings (more than the split approach), except if the rest of the solution is correct (then you can mention it but approve). Using reduce requires more interpretation by the reader to follow, change and maintain.
Discourage String#substring with foreach iteration, because character iteration via split('') is more idiomatic and maintainable than substring with 1. Using split('') requires less interpretation by the reader to follow, change and maintain.

Approach

The suggested approach is to:

detect which type of solution it is (switch, map, or for/forEach)
make sure the optimal solution is correctly handled. You can use the batch runner to generate output for all fixtures.
go from there by adding paths to disapprove.

View on GitHub

Join the mentors

Naturally, we are always looking for new mentors. You don't need to be an expert in your language, but we'd love it if you have extensive experience. You'll be coaching people on their journey to gain fluency. We also have a #mentor-the-mentor program, to help you get better at mentoring.

Join the students!

Know how to program in Java, but always wanted to learn Rust? Or maybe you finally make that step knowing TypeScript? Some tracks are currently oversubscribed, but in general we welcome anyone to become a student. Note: this is not a platform to teach you how to code. It's a platform to gain fluency in a new language.

Tetris: Choosing the tools and setting up the project

Derk-Jan Karrenbeld — Sun, 14 Jul 2019 11:45:50 +0000

🔙 This is the second instalment of a series on building a Tetris clone using React. If you've missed the first, find it here.

Today we'll take a step towards starting the project. I'll discuss various options and choices which you might encounter when you're bootstrapping your own projects. It's important to talk about these - especially since a lot of tutorials and guides completely skip over the why - and you'll notice that not everything is crystal clear of has a single way to move forward.

🎮 In this series I'll show you all the steps to build a Tetris clone, abiding by the Tetris Guideline, the current specification that The Tetris Company enforces for making all new (2001 and later) Tetris game products alike in form.

🛑 Tetris is licensed which means that if you intend to take this series of articles to build your own arcade puzzler, make sure to abide by the law, if you intend to commercially release it. Even if you provide a clone for free, you could still get a cease and desist. This reddit thread is pretty comprehensive how to go about this. Additionally, this Ars Technica article talks in-depth about how courts judge gaming clones using Tetris and the alleged clone Mino as an example.

📚 This series is purely meant as an educational, non-commercial resource. We'll only be using the fandom wiki as a resource and only use the name Tetris to indicate the type of game and not the actual company, game(s) or brand.

Table of Contents
The Game Engine
The Toolchain
- Package management
- Bundler
- Compiler
- Linting and Styleguides
- Testing libraries
- Base Library
- Bootstrap
Initialisation of the project
Setting up typescript correctly
Setting up babel correctly
Setting up eslint correctly
- Testing the eslint configuration
- Fine-tuning the rules
Setting up jest correctly
- Enabling jest-dom extensions
- Getting a coverage report
Setting up prettier correctly
- Automatically formatting
Conclusion

The Game Engine

Since this series has a game as its deliverable, it can be wise to pick a game engine. As taken from the WikiPedia article, a game engine is a software-development environment designed for people to build video games. There is an entire list of game engines, which isn't complete, and choosing which one to use for your game is such an endeavour that many have entire articles or video about it. In my opinion, if you're building a game, from scratch, and you have the time, potential and choice, you only need to ask yourself the following question:

Do I ever want to go multiplayer? Pick Unreal Engine.
Do I want to build a First-Person Shooter (single- or multiplayer)? Pick Unreal Engine.
Otherwise, pick Unity.

I'm basing this on the hours and hours of GDC talks, and job listings! There are many more interesting engines, but if you need something which other people will trust and be able to work with, quickly, you probably need to pick one of these two.

If you're a one-person shop, and building for the web, there is a collection of javascript game engines, including well-known options such as GameMaker Studio (2).

However, since this series is building a Tetris clone using react, that is exactly what I'll use. Ask yourself: is React the right tool for the job? Meh, probably not (because there are better tools. Just because you can make something work, doesn't mean it was the right choice). Does that matter? It depends on the people you work with and the willingness of working around abstractions and challenges.

The Toolchain

Since react is supposed to be used for this project, it is likely that this project will be built as a JavaScript application. JavaScript projects (and libraries) tend to have a (sub)set of tools, which I refer to as the "toolchain".

Package management

A package manager has its function it the name: it manages packages. JavaScript modules, as listed in your package manifest (the collection of packages that the project depends on, for example listing an URL or a name, and version or version-range) are dependencies for your project. The current popular ones include Yarn and NPM.

You might ask: "But don't I always need a package manager?" The answer to that is a short no. You can also opt to:

Including all your dependencies locally, for example by vendoring (the act of storing dependencies locally to the project) them. This means you always have a working copy, without the need for the interwebs.
Use a runtime that doesn't use packages in the traditional sense, such as deno, but also using unpkg, which makes your HTML file the dependency manifest and manager in one.
Use system packages such as .debian packages, and manage dependencies using a system tool such as make and a Makefile. This technically still uses a package manager, but not in the same way as the Yarn or npm options.

💎 I'm choosing Yarn with the package manifest inside package.json. I think there are many valid reasons to pick any of the options above. I've used most of them myself, including now defunct tools such as Bower. It often doesn't matter, and the decision should be made in line with company policies or project team alignment.

Bundler

A bundler in the JavaScript eco-system is not to be confused with the package manager bundler from the Ruby eco-system. In the JavaScript eco-system, it usually takes care of the following set of feature, or a sub-set thereof:

collecting all the assets in your project (JS, HTML, files, images, CSS)
stripping out unused assets (think tree-shaking, dead code/import elimination)
applying transformations (transpilation e.g. Babel, post processing e.g. PostCSS)
outputting code bundles (chunks, code splitting, cache-friendly output)
error logging (more friendly)
hot module replacement (automatically updating modules / assets during development)

Some of the tools I've used in the past and still use are Webpack, Parcel, Rollup, microbundle, Browserify and Brunch. The same can be achieved using a task runner such as Grunt or using Gulp, but in my experience, those tend to get out of hand fast.

The choice here, again, doesn't really matter. I think they all have their strengths and weaknesses, and you should pick whichever you feel comfortable with. If you foresee you'll need to customise a lot, some will be favourable over others. If your team knows one of them better than the others, that will probably be favourable. In general: a great bundler is replaceable.

💎 I'm not choosing anything yet! I'll let the rest of the toolchain dictate what bundler I want to go with. If done right, it won't be that costly to replace the bundler later. Perhaps I won't need any.

Compiler

Technically, babel is mostly a transpiler, as it compiles code to the same level of abstraction (think JavaScript ESNext to JavaScript ES3). A compiler generally compiles code to a lower level of abstraction (think Java to JVM / ByteCode, TypeScript to JavaScript). That said, Babel lists itself as a compiler, which it also is as it can remove TypeScript token from TypeScript code, yielding valid JavaScript

💎 Since I want some type-safety, and I'm better at using TypeScript (which does come with a compiler which also transpiles) than Flow (which is technically a static type checker and not a compiler or transpiler), I'm choosing TypeScript for compilation to type-check and then use babel to actually compile and then transpile the files to JavaScript.

Linting and Styleguides

According to WikiPedia, Lint, or a linter, is a tool that analyses source code to flag programming errors, bugs, stylistic errors, and suspicious constructs. Since I'll be using TypeScript, I'm at least looking for a code-linter.

💎 TSLint has been deprecated, as Microsoft has rolled out an amazing toolset which enables ESLint to support Typescript, called typescript-eslint.

I also think that it's good practise to pick a coding style guide (e.g. do you use semicolons or not) and apply that to the project. Towards this goal, I'll use prettier.

Testing libraries

Alright, this one is also not groundbreaking. Whilst there are a lot of options here, such as mocha, jasmine, tape, or one of my favourites AVA, I'll use jest. I personally think it has all the great features I love from AVA, but because Facebook uses it internally, there is quite a bit of React tooling that hooks perfectly into jest.

Base Library

There are currently multiple options when you want to develop in "react":

react: https://reactjs.org/
preact: https://preactjs.com/
react-native-web: https://github.com/necolas/react-native-web

💎 Without going to deep into detail, since this series is focused on writing a game using react, that's what I'll use; if there is a lot of ask by the end of the series, I'll write one about how to move from react to preact.

Bootstrap

If you've read the react docs, you might know that there are several "toolchains" out there. They are mostly wrappers providing a single Command-Line Interface (CLI) and come bundled with all the dependencies (tools), as listed above in the various categories. The React team primarily recommends a few solutions, and I tend to agree with them:

If you’re learning React or creating a new single-page app, use Create React App.
If you’re building a server-rendered website with Node.js, try Next.js.
If you’re building a static content-oriented website, try Gatsby.
If you’re building a component library or integrating with an existing codebase, try Neutrino, nwb, Parcel or Razzle.

I'd like to throw react-static in the mix as well as an alternative to next.js and gatsby, which allows you to build super fast static content sites, hydrated with a react-app, without the requirement of using GraphQL or a server.

This is a very important decision, because if you choose to use a bootstrapped project with one of the toolchains above, you'll be somewhat tied to their technologies, choice of configuration and general ideas. Most of the tools allow you to eject (to stop using the built-in defaults), but you'll still have to to a lot of work to move away.

💎 The project (Tetris clone) is probably completely feasible without a complete bootstrapped toolchain. That's why I've chosen not to use one of the bootstrapping toolchains. Often I run into meh behaviour when I need to add something that it currently doesn't support correctly out of the box, when I try to upgrade dependencies or anything similar. If I end up needing it, I can always add it later!

Initialisation of the project

# Create the directory for this new project
mkdir tetreact

# Move into that directory
cd tetreact

# Install dependencies
yarn add react react-dom

# Install development dependencies (explanation below)
yarn add typescript core-js@3 eslint eslint-config-prettier eslint-plugin-import -D
yarn add eslint-plugin-jsx-a11y eslint-plugin-react eslint-plugin-react-hooks -D
yarn add jest babel-jest prettier @babel/cli @babel/core @babel/preset-env -D
yarn add @babel/preset-react @babel/preset-typescript @typescript-eslint/eslint-plugin -D
yarn add @typescript-eslint/parser @testing-library/react @testing-library/jest-dom -D
yarn add @types/jest @types/react @types/react-dom -D

# Make this a git repository
git init

Here is why the following packages are being installed:

react and react-dom are runtime packages for react,
typescript: used to type-check the ts and tsx files,
core-js: a library that polyfills features. There is an older, version (@2) and a newer version (@3).
eslint: the core package for the linter,
eslint-config-prettier: turns off conflicting, stylistic rules that are handled by prettier,
eslint-plugin-import: adds rules and linting of import and export statements,
eslint-plugin-jsx-a11y: adds accessibility rules on JSX elements,
eslint-plugin-react: adds React specific linting rules,
eslint-plugin-react-hooks: adds React Hooks specific linting rules,
jest: the testing framework,
babel-jest: makes it possible to run the test code through babel,
@babel/cli: allows me to run babel as a standalone command from the command line,
@babel/core: the core package for Babel,
@babel/preset-env: preset to determine which transformations need to be applied on the code, based on a list of browsers,
@babel/preset-react: preset that allows transpilation of JSX and ensures React's functional component's property displayName is correctly set,
@babel/preset-typescript: allows stripping TypeScript type tokens from files, leaving behind valid JavaScript,
@typescript-eslint/eslint-plugin: adds a lot of rules for linting TypeScript,
@typescript-eslint/parser: allows eslint to use the TypeScript ESLint parser (which knows about type tokens),
@testing-library/react: adds officially recommended testing library, for react,
@testing-library/jest-dom: adds special matchers for jest and the DOM,
@types/*: type definitions

You might think: "jee, that's a lot of dependencies", and yep, it's quite a few. However, when using something like create-react-app, you are installing the same if not more dependencies, as these are dependencies of the react-scripts project you'll be depending on. I've spent quite some time on getting this list to where it is, but feel free to make your own changes and/or additions.

Normally I would add these dependencies as I go, but I already did all the steps listed below, so I collected all the dependencies and listed them in two single commands for you to copy and paste.

Setting up `typescript` correctly

The following is to setup typescript. The dependencies added for this are:

typescript: provides the tsc typescript compiler and allows you to have a project version, different from a version e.g. bundled with your IDE or text editor.

Run the tsc --init command in order to create the tsconfig.json with the default settings.

yarn tsc --init

Now I need to make a few changes, all of which are explained below:

-  // "incremental": true,
+  "incremental": true
-  // "target": "es5",
+  "target": "esnext",
-  // "jsx": "preserve",
+  "jsx": "preserve",
-  // "noEmit": true,
+  "noEmit": true,
-  // "isolatedModules": true,
+  "isolatedModules": true,
-  // "moduleResolution": "node",
+  "moduleResolution": "node",
-  // "allowSyntheticDefaultImports": true,
+  "allowSyntheticDefaultImports": true,

Remember, the goal is to have tsc type-check the codebase. That means there doesn't need to be an output, hence noEmit. Furthermore, it doesn't need to spend time transpiling to an older JavaScript, because babel will take care of that, which means it can have an esnext target. For the same reason, jsx is set to preserve and not react. Babel will take care of that. Then there are a few options that make interoptability with other packages easier. Finally, isolatedModules is required for the TypeScript over Babel functionality to work correctly.

Additionally, package.json needs to get the "scripts" key with a command that runs the type-checking.

+  "scripts": {
+    "lint:types": "yarn tsc"
+  }

Running yarn lint:types should yield the following error:

error TS18003: No inputs were found in config file 'path/to/tetreact/tsconfig.json'. Specified
'include' paths were '["**/*"]' and 'exclude' paths were '[]'.


Found 1 error.

This is the correct error. There is nothing to compile! Let's add that:

mkdir src
touch src/App.tsx

Running yarn lint:types should yield the following errors:

node_modules/@types/babel__template/index.d.ts:16:28 - error TS2583: Cannot find name 'Set'. Do
you need to change your target library? Try changing the `lib` compiler option to es2015 or later.

16     placeholderWhitelist?: Set<string>;
                              ~~~

node_modules/@types/react/index.d.ts:377:23 - error TS2583: Cannot find name 'Set'. Do you need
to change your target library? Try changing the `lib` compiler option to es2015 or later.

377         interactions: Set<SchedulerInteraction>,
                          ~~~

src/App.tsx:1:1 - error TS1208: All files must be modules when the '--isolatedModules' flag is
provided.

1

Let's start at the first two. These give an explicit option to fix the error.

-  // "lib": [],
+  "lib": ["dom", "es2015"],

This is very similar to setting the correct env in your .eslintrc configuration file: I need to tell TypeScript that I'm in a browser environment (dom) and that it should be able to access those constructs that have been introduced in es2015.

The final error is because of the --isolatedModules flag. When running the compiler with this flag/option, each file expects to be its own, free-standing module. A file is only a module if it imports or exports something. The reason for this flag isn't apparent: It's listed on the documentation of @babel/plugin-transform-typescript as one of the caveats of "compiling" TypeScript using Babel. I have advanced knowledge here, but it would become clear in the next step.

I update the src/App.tsx file:

import React from 'react'

export function App(): JSX.Element {
  return <div>Hello world</div>
}

Finally, tsc does not complain.

Setting up `babel` correctly

Next up is making sure that babel "compiles" the TypeScript code to JavaScript, applies transformations and hooks into the various plugins that I've installed.

core-js@3: a library that polyfills features. There is an older, version (@2) and a newer version (@3); it uses used by @babel/preset-env in conjunction with a browerlist configuration,
@babel/cli: allows me to run babel as a standalone command from the command line,
@babel/core: the core package for Babel,
@babel/preset-env: preset to determine which transformations need to be applied on the code, based on a list of browsers,
@babel/preset-react: preset that allows transpilation of JSX and ensures React's functional component's property displayName is correctly set,
@babel/preset-typescript: allows stripping TypeScript type tokens from files, leaving behind valid JavaScript.

Babel currently, at moment of writing, does not have an --init command, but setting it up is not very complicated, albeit it takes some effort to get all the presets and plugins correctly listed. Since this is a project, per the babel documentation, the best way for this project is to create a JSON configuration, called .babelrc.

touch .babelrc

The contents are as follows, which I collected by taking the documentation of the three @babel/preset-* plugins and applying them:

{
  "presets": [
    [
      "@babel/preset-env", {
        "targets": {
          "node": "current"
        },
        "useBuiltIns": "usage",
        "corejs": { "version": 3 }
      }
    ],
    "@babel/preset-typescript",
    "@babel/preset-react"
  ],
  "ignore": [
    "node_modules",
    "dist"
  ]
}

It's also a good idea to explicitly define the browserlists key/configuration, even though since I'm building a cross-env cross-browser game, the setting can stay on defaults. In order to do that, and in order to be abel to call babel using @babel/cli, in package.json, I added the following:

   {
     "scripts": {
+      "build": "yarn babel src --out-dir dist --extensions \".ts,.tsx\"",
+      "watch": "yarn build --watch",
       "lint:types": "yarn tsc"
     },
     "dependencies": {

  ...

       "typescript": "^3.5.3"
     },
+    "browserslist": [
+      "defaults"
+    ]
   }

If you want a different target, make sure to follow the Browserlist best practices. You can also use a configuration file; pick whichever you like.

Let's see if this works!

$ yarn build
yarn run v1.16.0
warning package.json: No license field
$ babel src --out-dir dist --extensions ".ts,.tsx"
Successfully compiled 1 file with Babel.
Done in 1.67s.

In dist I can now find App.js, which does not have any type information. It should look something like this:

"use strict";

Object.defineProperty(exports, "__esModule", {
  value: true
});
exports.App = App;

var _react = _interopRequireDefault(require("react"));

function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

function App() {
  return _react.default.createElement("div", null, "Hello World!");
}

A few things to notice:

It added "use strict";
It is using the interopRequireDefault to require react's default export
It transpiled JSX to use _react.default.createElement

These three things would only happen if Babel is configured correctly.

Setting up `eslint` correctly

Next step is making sure that the TypeScript code can be linted!

eslint: the core package for the linter,
eslint-config-prettier: turns off conflicting, stylistic rules that are handled by prettier,
eslint-plugin-import: adds rules and linting of import and export statements,
eslint-plugin-jsx-a11y: adds accessibility rules on JSX elements,
eslint-plugin-react: adds React specific linting rules,
eslint-plugin-react-hooks: adds React Hooks specific linting rules,
@typescript-eslint/eslint-plugin: adds a lot of rules for linting TypeScript,
@typescript-eslint/parser: allows eslint to use the TypeScript ESLint parser (which knows about type tokens).

The eslint core package comes with a CLI tool to initialise (and run) eslint:

$ yarn eslint --init

? How would you like to use ESLint? To check syntax and find problems
? What type of modules does your project use? JavaScript modules (import/export)
? Which framework does your project use? React
? Where does your code run? Browser
? What format do you want your config file to be in? JSON

Successfully created .eslintrc.json file in path/to/tetreact

Depending on your configuration, and depending if you call yarn eslint (execute eslint from the local node_modules) or plain eslint (which might call the "globally" installed eslint), the following message may appear:

The config that you've selected requires the following dependencies:

eslint-plugin-react@latest

? Would you like to install them now with npm? No

I choose "No" because on one hand, it's already installed under devDependencies and on the other hand, it will try to use npm to install it if I say "yes" (at moment of writing), which is something I don't want (as I am using yarn).

As for the options: I personally like the .json file, because it restricts me from solving something using JavaScript, which makes the barrier to do something "hackly" a bit higher. I basically guard myself from trying to do something that is not supported out of the box. Your mileage may vary, but I like to use my dependencies with standard configuration, because it makes it easier to search for solutions and ask for support!

🛑 If you run into an error that looks like this:
ESLint couldn't find the plugin "eslint-plugin-react". This can happen for a
couple different reasons:
...
Even though it is installed locally, remove eslint from the global packages:
yarn global remove eslint

If you're using an IDE with eslint integration set-up, chances are that both App.js (in the dist folder) ánd App.tsx (in the src folder) light up with errors. This is to be expected. It doesn't automagically configure .eslintrc.json with all the plugins from your devDependencies.

In order to get all the configurtion in, I edit the generated .eslintrc.json.

First, I mark the configuration as the root configuration. This prohibits any eslint configuration somewhere up the tree to apply rules to this project.
Next, I update the parserOptions and tell it to use the @typescript-eslint/parser parser. My article on writing a TypeScript code Analyzer goes into a bit more detail on what the different @typescript-eslint/* packages are and do.
Finally, there are all the extends. These take preset configurations that I want to apply to this configuration. The @typescript-eslint/* and prettier/* modules have documentation that explains in what order these should be placed.

   {
+    "root": true,
+    "parser": "@typescript-eslint/parser",
     "parserOptions": {
+      "project": "./tsconfig.json",
+      "ecmaFeatures": {
+        "jsx": true
+      },
       "ecmaVersion": 2018,
       "sourceType": "module"
     },
     "env": {
       "browser": true,
       "es6": true
     },
-    "extends": "eslint:recommended"
+    "extends": [
+      "eslint:recommended",
+      "plugin:@typescript-eslint/eslint-recommended",
+      "plugin:@typescript-eslint/recommended"
+      "plugin:react/recommended",
+      "prettier",
+      "prettier/@typescript-eslint",
+      "prettier/babel",
+      "prettier/react"
+    ],
     "globals": {
       "Atomics": "readonly",
       "SharedArrayBuffer": "readonly"
     },
     "plugins": [
-      "react",
+      "@typescript-eslint",
+      "react-hooks",
     ],
     "rules": {
     },
+    "settings": {
+      "react": {
+        "version": "detect"
+      }
+    }
   }

The rules are currently still empty, I'll get to that. First, let's test the configuration!

Testing the `eslint` configuration

I change src/App.tsx:

+  function Header() {
+    return <h1>Hello World!</h1>
+  }

   export function App(): JSX.Element {
-    return <div>Hello World!</div>
+    return <Header />
   }

And add a new scripts entry:

   "scripts" {
     "build": "yarn babel src --out-dir dist --extensions \".ts,.tsx\"",
      "watch": "yarn build --watch",
+     "lint": "yarn eslint src/**/*",
      "lint:types": "yarn tsc"
   },

Now I run it!

yarn lint

$ eslint src/**/*

path/to/tetreact/src/App.tsx
  3:1  warning  Missing return type on function  @typescript-eslint/explicit-function-return-type

✖ 1 problem (0 errors, 1 warning)

Done in 4.01s.

Woopdiedo. A warning from the @typescript-eslint plugin! This is exactly what I expect to see, so I can now move on fine-tuning the "rules".

Fine-tuning the rules

Normally I fine-tune the "rules" as I develop a library or a project, or I use a set of rules that is pre-determined by a project lead. In the exercism/javascript-analyzer respository, I've added a document about the rules and why I chose them to be like this. The results are as listed below, which include the two react-hooks rules at the bottom.

{
  "rules": {
    "@typescript-eslint/explicit-function-return-type": [
      "warn", {
        "allowExpressions": false,
        "allowTypedFunctionExpressions": true,
        "allowHigherOrderFunctions": true
      }
    ],
    "@typescript-eslint/explicit-member-accessibility": [
      "warn", {
        "accessibility": "no-public",
        "overrides": {
          "accessors": "explicit",
          "constructors": "no-public",
          "methods": "explicit",
          "properties": "explicit",
          "parameterProperties": "off"
        }
      }
    ],
    "@typescript-eslint/indent": ["error", 2],
    "@typescript-eslint/no-non-null-assertion": "off",
    "@typescript-eslint/no-parameter-properties": [
      "warn", {
        "allows": [
          "private", "protected", "public",
          "private readonly", "protected readonly", "public readonly"
        ]
      }
    ],
    "@typescript-eslint/no-unused-vars": "off",
    "@typescript-eslint/no-use-before-define": [
      "error", {
        "functions": false,
        "typedefs": false
      }
    ],
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn"
  }
}

As I write more code, this ruleset may change, but for now this should suffice.

Setting up `jest` correctly

Next up is making sure the code is testable.

I personally don't like to co-locate my test files next to my source files, but rather put all the tests in a separate directory. However this isn't better or preferred, just different. You can do whichever you like. If you co-locate the tests, make sure that your tests end with .test.ts or .test.tsx, and if you don't, the default folder is __tests__. You can change these in the, soon to be, generated jest.config.js.

The dependencies that matter are:

jest: the testing framework,
babel-jest: makes it possible to run the test code through babel,
@testing-library/react: adds officially recommended testing library, for react,
@testing-library/jest-dom: adds special matchers for jest and the DOM,

Just like some of the other tools, jest comes with a CLI and an option that allows you to generate the configuration file.

$ yarn jest --init

√ Would you like to use Jest when running "test" script in "package.json"? ... yes
√ Choose the test environment that will be used for testing » jsdom (browser-like)
√ Do you want Jest to add coverage reports? ... yes
√ Automatically clear mock calls and instances between every test? ... no

This adds the test script to "scripts" in package.json and adds a jest.config.js file with defaults to the root directory.
The contents of the configuration file are all set correctly (given the answers as listed above), with the important ones being (you can go in and confirm):

coverageDirectory should be set to "coverage", because I want coverage reports,
testEnvironment should not be set or set to "jest-environment-jsdom", because I don't want to have to run in a browser.

The babel-jest package is automagically supported, out-of-the-box, without needing to set-up anything else. Since Babel is already configured correctly to "compile" the source code, and the test code has the same properties, no steps need to be taken in order to make the tests be "compiled" as well.

Then I want to integrate with the @testing-library/react library, which provides a cleanup script that makes sure the React application state and environment is reset (cleaned-up) after each test. Instead of including this in every test, it can be setup via the jest.config.js file:

-  // setupFilesAfterEnv: []
+  setupFilesAfterEnv: [
+    '@testing-library/react/cleanup-after-each'
+  ],

I use the default folder name for my tests:

mkdir __tests__

And now I create a smoke test __tests__/App.tsx with the following:

import React from 'react'
import { render } from '@testing-library/react'
import { App } from '../src/App';

it('App renders heading', () => {
  const {queryByText} = render(
    <App />,
  );

  expect(queryByText(/Hi/)).toBeTruthy();
});

Finally I run the tests using the "scripts" command that was added by yarn jest --init:

yarn test

$ jest
 FAIL  __tests__/App.tsx
  × App renders heading (29ms)

  ● App renders heading

    expect(received).toBeTruthy()

    Received: null

      14 |   );
      15 |
    > 16 |   expect(queryByText(/Hi/)).toBeTruthy();
         |                             ^
      17 | });
      18 |

      at Object.toBeTruthy (__tests__/App.tsx:16:29)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        4.361s
Ran all test suites.

Ah. I'm rendering Hello World, and not Hi. So now I change the regular expression to test for Hello World instead, and run the tests again:

$ jest
 PASS  __tests__/App.tsx
  √ App renders heading (21ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        4.184s
Ran all test suites.
Done in 6.10s.

Enabling `jest-dom` extensions

You might have noticed that there is another @testing-library dependency. I want to use the '@testing-library/jest-dom/extend-expect' visibility check toBeVisible, instead of only testing if it exists via toBeTruthy. I order to integrate with that package, I make the following change to the jest.config.js:

   setupFilesAfterEnv: [
     '@testing-library/react/cleanup-after-each',
+    '@testing-library/jest-dom/extend-expect',
   ],

This change makes the extension (new matchers, including .toBeVisible) available to all the tests.

I update the test to use these:

   import React from 'react'
   import { render } from '@testing-library/react'
   import { App } from '../src/App'

   it('App renders heading', () => {
     const { container, queryByText } = render(
       <App />,
     );

-    expect(queryByText(/Hello World/)).toBeTruthy()
+    expect(queryByText(/Hello World/)).toBeVisible()
   }

Running the tests works, but my IDE gives an error on the toBeVisible matcher. This is because TypeScript doesn't quite know that the expect matchers have been extended. It's not good at inferring new types from dynamically executed code. Since there is no cross-file information between the jest configuration and this test, I can't expect that to be magically picked up. Fortunately, there are various ways to solve this, for example, but not limited to:

Add import '@testing-library/jest-dom/extend-expect' to each test file. This extends the expect() Matchers to include those provided by the library,
Make sure typescript knows this is always included (which is true, given the jest.config.js changes).

In order to get the "always included" experience, I add a new file declarations.d.ts and add a triple-slash directive. I generally stay clear of these directives, and even have an eslint rule to disallow them, but in my experience, tooling is best when you run into something like this issue and use them. This might not be true if you follow this post some time in the future. You can do whatever works, perhaps an import suffices:

touch __tests__/declarations.d.ts

/* eslint-disable @typescript-eslint/no-triple-slash-reference */
/// <reference types="@testing-library/jest-dom/extend-expect" />

What this does is tell TypeScript that for the current directory subtree (__tests__), it should always add the package' types as defined by the directive. I can now also see that the error in __tests__/App.tsx has been resolved and that it recognises .toBeVisible.

Getting a coverage report

There are no new dependencies required for a coverage report as jest comes bundled with built-in coverage.

In order to test if the coverage is working correctly, I first change the App.tsx src file to include a branch:

import React from 'react'

export interface AppProps {
  headingText?: string
}

export function App({ headingText }: AppProps): JSX.Element | null {
  if (headingText === undefined) {
    return null
  }

  return <h1>{headingText}</h1>
}

Now, the app renders null unless a headingText is given. I also have to change the test to pass in "Hello World" as the heading text, or the test will
fail:

-  <App />
+  <App headingText="Hello World" />,

I run the test suite with coverage enabled:

yarn test --coverage

This runs the tests and they are passing; it also outputs the following table summary:

----------|----------|----------|----------|----------|-------------------|
File      |  % Stmts | % Branch |  % Funcs |  % Lines | Uncovered Line #s |
----------|----------|----------|----------|----------|-------------------|
All files |    66.67 |       50 |      100 |    66.67 |                   |
 App.tsx  |    66.67 |       50 |      100 |    66.67 |                 9 |
----------|----------|----------|----------|----------|-------------------|

Line 9 is inside a conditional branch (for when headerText === undefined):

    return null

This can be tested by explicitly adding a test.

it('App renders nothing without headingText', () => {
  const { container } = render(
    <App />,
  )

  expect(container.firstChild).toBeNull()
})

I generally don't like to test that things are not there, because often you have to make a few assumptions that are fragile at best (and therefore break easily), but just to test if jest has been set-up correctly, this is fine, since I'll throw away these lines later:

$ jest --coverage
 PASS  __tests__/App.tsx
  √ App renders heading (46ms)
  √ App renders nothing without headingText (1ms)

----------|----------|----------|----------|----------|-------------------|
File      |  % Stmts | % Branch |  % Funcs |  % Lines | Uncovered Line #s |
----------|----------|----------|----------|----------|-------------------|
All files |      100 |      100 |      100 |      100 |                   |
 App.tsx  |      100 |      100 |      100 |      100 |                   |
----------|----------|----------|----------|----------|-------------------|
Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        4.911s
Ran all test suites.
Done in 6.78s.

Setting up `prettier` correctly

Finally, I can focus on setting up the (automatic) code formatter! I really like prettier for the simple reason that it removes the need of discussing a lot of style choices. I don't think it always or even often generates pretty code, but that's okay. As their library improves, so does the output, and it's trivial to re-format all the code once they do.

eslint-config-prettier: turns off style rules that are in conflict with prettier. You can see the various prettier/* lines in the eslint configuration above. This has already been set-up.
prettier: the core package, including the CLI tools to run prettier.

Prettier has already been added to the eslint configuration, so that part can be skipped.

The prettier CLI doesn't have an --init option at the moment of writing, so I create the configuration file manually:

touch .prettierrc.json

I've chosen to loosly follow the StandardJS style, but it really doesn't matter. Pick a style and stick with it.

{
  "trailingComma": "es5",
  "tabWidth": 2,
  "semi": false,
  "singleQuote": true,
  "jsxSingleQuote": false
}

I also want to be able to run these as a script, so I add the following three "scripts":

   "lint:types": "yarn tsc",
+  "lint:format": "yarn format --check",
+  "format": "yarn prettier \"{src,__{tests}__}/**/*.{ts,tsx}\"",
+  "format:fix": "yarn format --write",
   "test": "yarn jest"

Automatically formatting

Since prettier has been added as plugin to eslint, it is already correctly integrated with eslint. However, you might want code to be formatted on save. The prettier documentation lists a lot of IDEs and allow you to turn on formatting on save.

In general, I'm not a fan of running prettier on commit, because it slows down my commits, occasionally breaks things and I think it shouldn't be a concern of the commit to format the code. That said, I do think it's a good idea to add a check in the continuous integration (CI) to test the format of the project.

Conclusion

And that's it! The project is now in a pretty good state to start writing code. Yes, it took quite a bit to get here and a lot of the configuration setup above is exactly why tools such as create-react-app or even the parcel bundler exist. Note that I haven't actually dealt with some of the things that parcel and webpack deal with, such as importing images or other file types; I don't think I'll need it, and therefore I didn't add that.

A few things are left to do:

Set-up CI,
Add the "name" and "license"` fields,
Add the servability i.e. add the HTML file that we can see in a browser.

Next time I will actually write some game code, and perhaps the things just listed, but for now, this is all I give you.

Tetris: Building a game using JavaScript

Derk-Jan Karrenbeld — Fri, 05 Jul 2019 15:53:27 +0000

I've always been a fan of retro, arcade and retro arcade games, mostly because their limitations often resulted in very creative game mechanics that were easy to learn and difficult to master. Mark Brown from Game Maker's Toolkit has done an excellent video about "versatile verbs", in a number of excellent games, which I recommend you to watch. Older games were less versatile, but as they were written mostly for arcade machines, which usually had a very limited set of inputs, those games utilise the few buttons they had in various ways.

🎮 In this series I'll show you all the steps to build a Tetris clone, abiding by the Tetris Guideline, the current specification that The Tetris Company enforces for making all new (2001 and later) Tetris game products alike in form.

🛑 Tetris is licensed which means that if you intend to take this series of articles to build your own arcade puzzler, make sure to abide by the law, if you intend to commerically release it. Even if you provide a clone for free, you could still get a cease and desist. This reddit thread is pretty comprehensive how to go about this. Additionally, this Ars Technica article talks in-depth about how courts judge gaming clones using Tetris and the alleged clone Mino as an example.

📚 This series is purely meant as an educational, non-commercial resource. We'll only be using the fandom wiki as a resource and only use the name Tetris to indicate the type of game and not the actual company, game(s) or brand.

In this first article, we'll be looking at the domain of the game, meaning which nouns (object/subjects) and verbs (actions/functions) exist in the game.

Definitions and Concepts

First, let's look at al the game definitions and concepts, before writing any code. I generally do this step of domain modelling before I write any code, because it will probably help out making the right abstractions.

Movement and Buttons

In the classic Tetris, as released in 1984, the number of inputs was basically the same as the version developed for the iPod (Tetris 2006):

a button to move the falling Tetromino left
a button to move the falling Tetromino right
a button to drop-and-lock the falling Tetromino
a button to rotate the Tetromino.

The standard button mapping adds a few more:

a button to drop (but not lock) the falling Tetromino
a button to rotate the Tetromino in the other direction (so counter-clockwise vs clockwise)
a button to use hold

Whilst these actions seem pretty simple by themselves, together with the other game rules, they can act on a wide vocabulary.

Binding a specific verb to a button is what we call a mapping. The mapping has standards as defined by the Tetris Guideline.

Playfield

In the manual for Tetris for NES (1989) the playfield is defined as:

PLAYFIELD: This is where the action is.

It makes up the grid on which the Tetrominos fall and come to rest. In the majority of the games the width is 10 tiles, and the height ranges from 16 through 24 tiles. Aboe the grid, there are 20 rows "hidden", which is called the Vanish Zone.

Tetrominos

There are various Tetrominos: shapes that come dropping down from the top of the playfield. They are defined as follows:

Cyan: I
Yellow: O
Purple: T
Green: S
Red: Z
Blue: J
Orange L

They also have defined starting locations:

Middle: I and O
Left-Middle: everything else

They should all spawn horizontally, with J, L and T spawning the flat-side first, and spawn above the visible playfied (inside the Vanish Zone), but drop one space if there is nothing in its path (becoming visible).

Generator

There is a Random Generator to generate the pieces that will come down the playfield. The standard implementation is the so called 7-bag random generator, meaning that all seven one-sided tetriminos are drawn, randomly, from a bag, before generating another back.

There are different randomizers.

Holding zone / Hold piece

The player can press a button to send the falling tetrimino to the hold box, and any tetrimino that had been in the hold box moves to the top of the screen and begins falling.

Ghost piece

The ghost piece indicates where the Tetromino will land, if it were dropped, It greatly reduces the number of misdrops.

Rotation

Rotation of a Tetromino is actually not straight-forward. The system and specification that deals with this is called the Super Rotation System (SRS).

In general, when unobstructed, Tetrominos rotate as you would except: about a single point. Because this is purely a mathematical rotation without any translation, there are states in which the J, L, S, T and Z Tetrominos "float" above their bounding box.

However, when obstructed, the game will attempt to "kick" the Tetromino into an alternative position nearby. The rules for these are described in the section about Wall Kicks.

Levels

A player levels up by clearing lines (filling them completely), or performing "T-Spins". Higher levels usually have higher drop-speeds and higher score (-multipliers).

Scoring

The Guideline scoring system dictates that certain ways of clearing a line have different scores than other ways. We won't go into the different combos, b2b, spins and so forth right now, but this will come up as we're implementing the game.

Next steps

No code has be written yet. The next steps are figuring out:

Which models and concerns are there? This will be accomplished by mapping the various nouns from the definitions and concepts above to programming namespaces and function names.
What toolchain should we use? This will be determined by the needs. That means deciding on a library/framework (if any), and the style of the output.
What unique gameplay element(s) do we want to implement? The less Tetris-y the better! Gotta be unique.

🔜 The next instalment in this series sets up the entire toolchain! You can find it here.

JavaScript, Ruby and C are not call by reference

Derk-Jan Karrenbeld — Thu, 27 Jun 2019 15:14:25 +0000

🛑 This article is a response to various articles in the wild which state that JavaScript and Ruby are "Call/Pass by reference" for objects and "Call/Pass by value" for primitives.

Many of these articles provide a lot of valuable information and this article is not to unequivically say that those articles should not have been written or are useless. Instead, this article attempts to explore the semantic, yet pedantic, meanings and definitions of

call by reference

pass a reference

reference type

reference

First, I would like to make a few statements, after which Ill try to explore what these statements actually mean and why I've made them, contrary to various articles in the wild.

☕ When you see this emoji (☕), I try to give a non-code analogy to help you better understand what's going on. These abstractions are pretty leaky and might not hold up, but they're only meant in the context of the paragraphs that surround them. Take them with a grain of salt.

Statements

JavaScript is always call by value.
Ruby is always call by value.
C is always call by value.
The terminology is confusing and perhaps even flawed.
The terminology only applies to function (procedure) parameters.
Pointers are an implementation detail and their presence don't say anything about the evaluation of function parameters.

History and Definitions

I've tried to look up the origins of the terms as mentioned above, and there is quite a bit of literature out there from the earlier programming languages.

The Main Features of CPL (D. W. Barron et al., 1963):

Three modes of parameter call are possible; call by value (which is equivalent to the ALGOL call by value), call by substitution (equivalent to ALGOL call by name), and call by reference. In the latter case, the LH value of the actual parameter is handed over; this corresponds to the "call by simple name" suggested by Strachey and Wilkes (1961).

It is important to note that here the literature talks about mode of parameter call. It further distinguishes three modes: call by value, call by name and call by reference.

Further literature gives a good, yet technical, definition of these three and a fourth strategy (namely copy restore), as published in the Semantic Models of Parameter Passing (Richard E. Fairly, 1973). I've quoted 2 of the 4 definitions below, after which I'll break them down and explain what they mean in more visual terms.

Call by Value

[...] Call by Value parameter requires that the actual parameter be evaluated at the time of the procedure call. The memory register associated with the formal parameter is then initialised to this value, and references to the formal parameter in the procedure body are treated as references to the local memory register in which the initial value of the actual parameter was stored. Due to the fact that a copy of the value associated with the actual parameter is copied into the local memory register, transformations on the parameter value within the procedure body are isolated from the actual parameter value. Because of this isolation of values, Call by value can not be used to communicate calculated values back to the calling program.

Roughly, this means that a parameter is, before the function (procedure) is called, completely evaluated. The resulting value (from that evaluation), is then assigned to the identifier inside the function (formal parameter). In many programming languages this is done by copying the value to a second memory address, making the changes inside the function (procedure body) isolated to that function.

In other words: the original memory address' contents (the one used to store the evaluated expression before passing it into the function) can not be changed by code inside the function and changes inside the function to the value are not propagated to the caller.

☕ When you order a coffee and someone asks for your name, they might write it down incorrectly. This doesn't affect your actual name and the change is only propagated to the cup.

Call by Reference

[...] In Call by Reference, the address (name) of the actual parameter at the time of the procedure call is passed to the procedure as the value to be associated with the corresponding formal parameter. References to the formal parameter in the procedure body result in indirect addressing references through the formal parameter register to the memory register associated with the actual parameter in the calling procedure. Thus, transformations of formal parameter values are immediately transmitted to the calling procedure, because both the actual parameter and the formal parameter refer to the same register.

Roughly, this means that, just like before, the parameter is evaluated, but, unlike before, the memory address (address / name) is passed to the function (procedure). Changes made to the parameter inside the function (formal parameter) are actually made on the memory address and therefore propagate back to the caller.

☕ When you go to a support store for one of your hardware devices and ask for it to be fixed, they might give you a replacement device. This replacement device is still yours, you own it just like before, but it might not be the exact same one you gave to be fixed.

Reference (and value) types

This is not the complete picture. There is one vital part left that causes most of the confusion. Right now I'll explain what a reference type is, which has nothing to do with arguments/parameters or function calls.

Reference types and value types are usually explained in the context of how a programming language stores values inside the memory, which also explains why some languages choose to have both, but this entire concept is worthy of (a series of) articles on its own. The Wikipedia page is, in my opinion, not very informative, but it does refer to various language specs that do go into technical detail.

A data type is a value type if it holds a data value within its own memory space. It means variables of these data types directly contain their values.

Unlike value types, a reference type doesn't store its value directly. Instead, it stores the address where the value is being stored.

In short, a reference type is a type that points to a value somewhere in memory whereas a value type is a type that directly points to its value.

☕ When you make a payment online, and enter your bank account number details, for example your card number, the card itself can not be changed. However, the bank account's balance will be affected. You can see your card as a reference to your balance (and multiple cards can all reference the same balance).

☕ When you pay offline, that is with cash, the money leaves your wallet. Your wallet holds its own value, just like the cash inside your wallet. The value is directly where the wallet/cash is.

Show me the code proof

function reference_assignment(myRefMaybe) {
  myRefMaybe = { key: 42 }
}

var primitiveValue = 1
var someObject = { is: 'changed?' }

reference_assignment(primitiveValue)
primitiveValue
// => 1

reference_assignment(someObject)
// => { is: 'changed?' }

As shown above, someObject has not been changed, because it was not a reference to someObject. In terms of the definitions before: it was not the memory
address of someObject that was passed, but a copy.

A language that does support pass by reference is PHP, but it requires special syntax to change from the default of passing by value:

function change_reference_value(&$actually_a_reference)
{
    $actually_a_reference = $actually_a_reference + 1;
}

$value = 41;
change_reference_value($value);
// => $value equals 42

I tried to keep the same sort of semantic as the JS code.

As you can see, the PHP example actually changes the value the input argument refers to. This is because the memory address of $value can be accessed by the parameter $actually_a_reference.

What's wrong with the nomenclature?

Reference types and "boxed values" make this more confusing and also why I believe that the nomenclature is perhaps flawed.

The term call-by-value is problematic. In JavaScript and Ruby, the value that is passed is a reference. That means that, indeed, the reference to the boxed primitive is copied, and therefore changing a primitive inside a function doesn't affect the primitive on the outside. That also means that, indeed, the reference to a reference type, such as an Array or Object, is copied and passed as the value.

Because reference types refer to their value, copying a reference type makes the copy still refer to that value. This is also what you experience as shallow copy instead of deep copy/clone.

Whoah. Okay. Here is an example that explores both these concepts:

function appendOne(list) {
  list.push(1)
}

function replaceWithFive(list) {
  list = [5]
}

const first = []
const second = []

appendOne(first)
first
// => [1]

replaceWithFive(second)
second
// => []

In the first example it outputs [1], because the push method modifies the object on which it is called (the object is referenced from the name list). This propagates because the list argument still refers to the original object first (its reference was copied and passed as a value. list points to that copy, but points to the same data in memory, because Object is a reference type).

In the second example it outputs [] because the re-assignment doesn't propagate to the caller. In the end it is not re-assigning the original reference but only a copy.

Here is another way to write this down. 👉🏽 indicates a reference to a different location in memory.

first_array   = []
second_array  = []

first         = 👉🏽 first_array
list          = copy(first) = 👉🏽 first_array
list.push     = (👉🏽 first_array).push(...)

// => (👉🏽 first_array) was changed

second        = 👉🏽 second_array
list          = copy(second) = 👉🏽 second_array
replace_array = []
list          = 👉🏽 replace_array

// => (👉🏽 second_array) was not changed

What about pointers?

C is also always pass by value / call by value, but it allows you to pass a pointer which can simulate pass by reference. Pointers are implementation details, and for example used in C# to enable pass by reference.

In C, however, pointers are reference types! The syntax *pointer allows you to follow the pointer to its reference. In the comments in this code I tried to explain what is going on under the hood.

void modifyParameters(int value, int* pointerA, int* pointerB) {
    // passed by value: only the local parameter is modified
    value = 42;

     // passed by value or "reference", check call site to determine which
    *pointerA = 42;

    // passed by value or "reference", check call site to determine which
    *pointerB = 42;
}

int main() {
    int first = 1;
    int second = 2;
    int random = 100;
    int* third = &random;

    // "first" is passed by value, which is the default
    // "second" is passed by reference by creating a pointer,
    //         the pointer is passed by value, but it is followed when
    //         using *pointerA, and thus this is like passing a reference.
    // "third" is passed by value. However, it's a pointer and that pointer
    //         is followed when using *pointerB, and thus this is like
    //         passing a reference.
    modifyParameters(first, &second, third);

    // "first" is still 1
    // "second" is now 42
    // "random" is now 42
    // "third" is still a pointer to "random" (unchanged)
    return 0;
}

Call by sharing?

The lesser used and known term that was coined is Call by sharing which applies to Ruby, JavaScript, Python, Java and so forth. It implies that all values are object, all values are boxed, and they copy a reference when they pass it as value. Unfortunately, in literature, the usage of this concept is not consistent, which is also why it's probably less known or used.

For the purpose of this article, call-by-sharing is call by value, but the value is always a reference.

Conclusion

In short: It's always pass by value, but the value of the variable is a reference. All primitive-methods return a new value and thus one can not modify it, all objects and arrays can have methods that modified their value, and thus one can modify it.

You can not affect the memory address of the parameter directly in the languages that use call-by-value, but you may affect what the parameter refers to. That is, you may affect the memory the parameter points to.

The statement Primitive Data Types are passed By Value and Objects are passed By Reference. is incorrect.

TypeScript types you should know about

Derk-Jan Karrenbeld — Tue, 18 Jun 2019 09:36:57 +0000

In my daily work with TypeScript, there are a lot of utility types and standard
types I use across most if not all projects. This article contains the following subjects:

Types in type-fest
Other types (custom, built-in or utility-types)
Common patterns
- Overloaded type guards
- const arrays and union type
- Custom errors
- Setting this

`type-fest`

A collection of essential TypeScript types.

This npm package contains quite a few that are not (yet) built-in. I sometimes use this package (and import from there) and sometimes copy these to an ambient declarations file in my project.

`SafeOmit<T, K>` 🌐

Create a type from an object type without certain keys.

The use-case is a safe(r) version than the built-in Omit, which doesn't check
the keys K against T, but instead check them against any.

export type SafeOmit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>

type ExecutionOptions = {
  debug: boolean;
  dry?: boolean;
  tag: 'default' | 'name';
}

type ExecutionFlags = SafeOmit<ExecutionOptions, 'tag'>
// => {
//  debug: boolean;
//  dry?: boolean | undefined;
// }

`ReadonlyDeep<T>` 🌐

Convert objects, Maps, Sets, and Arrays and all of their properties/elements into immutable structures recursively.

My use-case is primarily when I'm imported JSON, or dealing with Abstract Syntax Trees. These need to be completely immutable (until they're cloned) and this enforces that. The built-in Readonly<T> only works shallowly.

import { ReadonlyDeep } from 'type-fest'
import dataJson = require('./data.json')

const data: ReadonlyDeep<typeof dataJson> = dataJson
data.property.value.push('bar')
//=> error TS2339: Property 'push' does not exist on type 'readonly string[]'

`RequireAtLeastOnce<T, K>` 🌐

Create a type that requires at least one of the given properties. The remaining
properties are kept as is.

My use-case is primarily when I have to make sure one of the known interface methods is present (usually api, service, transform/conversion style objects), but the rest of the type consists of properties and members that are always available.

import { RequireAtLeastOne } from 'type-fest'

type Responder = {
  text?: () => string;
  json?: () => string;
  secure?: boolean;
}

const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
  json: () => '{"message": "ok"}',
  secure: true
}

`Merge<A, B>` 🌐

Merge two types into a new type. Keys of the second type overrides keys of the
first type.

My use-case is primarily when I want to use Object.assign instead of using destructuring/spread to build my merged object. In the example below, you can see that the default for Object.assign produces an incorrect type.

type Stringy = {
  bar: string,
  foo: string
}

type NotStri = {
  foo: number
  other: boolean
}

const stringy: Stringy = { bar: 'bar', foo: 'foo' }
const notstri: NotStri = { foo: 42, other: true }

const result1 = Object.assign(stringy, notstri)
//       infers Object.assign<Stringy, NotStri>
result1.foo
// => string & number

export type Merge<T, V> = Omit<T, Extract<keyof T, keyof V>> & V;
const result2: Merge<Stringy, NotStri> = Object.assign(stringy, notstri)

result2.foo
// => number

const result3 = { ...stringy, ...notstri }
// => number

`Mutable<T>` 🌐

Convert an object with readonly properties into a mutable object. Inverse of
Readonly<T>.

I personally use this very sparingly as I tend to Object.freeze those variables that are "truly" Readonly. As Required<T> is the inverse of Partial<T>, Mutable<T> is the inverse of Readonly<T>.

import {Mutable} from 'type-fest';

type Foo = {
    readonly a: number;
    readonly b: string;
};

const mutableFoo: Mutable<Foo> = { a: 1, b: '2' };
mutableFoo.a = 3;

Other types

`WithFoo<T>`

Whenever I have some data T and modify it so that it has more data, I generally use a wrapping type, so that it's easy to compose the type as I go.

interface MyType {
  bar: 'string';
}

type WithFoo<T> = T & { foo: number }

const data: MyType[] = [{ bar: 'first' }, { bar: 'second' }]
const dataWithFoo: WithFoo<MyType>[] = data.map((item, index) => ({ ...item, foo: index }))

// The inverse uses SafeOmit
type WithoutFoo<T> = Omit<T, 'foo'>

AtLeastOne

Sometimes I want to ensure that an array has at least one item. There are type libraries that actually define a whole lot more than just this simple alias, but that's out of the scope for this article.

type AtLeastOne<T> = [T, ...T[]]

`PromiseType<T>` 🌐

One of the more interesting unwrappers. This gives the inner type T of a Promise<T> type. Usefull when something will unwrap the type, or you want to work outside of the context of promises or construct a new promise type (e.g. Promise<WithLabel<PromiseType<Original>>>).

import { PromiseType } from 'utility-types';

type Response = PromiseType<Promise<string>>;
// => string

`ReturnType<T>` (built-in)

Obtain the return type of a function type.

This is one of the more powerful inferred types I use all the type. Instead of
duplicating a type expectation over and over, if I know a function is guaranteed to call (or expected to call) a function foo, and I return the result, I give it the return type ReturnType<typeof foo>, which forwards the return type from the function declaration of foo to the current function.

type T10 = ReturnType<() => string>
// => string
type T11 = ReturnType<(s: string) => void>
// => void

function foo(): Promise<number> { return Promise.resolve(42) }
type FooResult = ReturnType<typeof foo>
// => Promise<number>

`InstanceType<T>` (built-in)

Obtain the instance type of a constructor function type.

I use this if I have a constructor type (a type that is constructible), but I need to work with the ReturnType<T> of said constructor. More or less the inverse of ConstructorType<T>.

class C {}

type T20 = InstanceType<typeof C>;
// => C

`ConstructorType<T>`

Matches a class constructor

I use this when I have a type (T) and I create a factory that generates these, or when I need the constructor type, given an instance type. More or less the inverse of InstanceType<T>.

export type ConstructorType<T> = new(...arguments_: any[]) => T

Common patterns

Overloaded type guards

I often have custom type guard in order to easily narrow a very broad type. The issue with a broad type is that you only have access to the intersection until you check for presence or narrow it.

Sometimes you want to check more than just a broad type, and don't want the typeguard to assign never if it doesn't match some narrowing predicate. See the example below.

import { AST_NODE_TYPES, TSESTree } from "@typescript-eslint/typescript-estree";

// Aliases for these types, so they are easy to access
type Node = TSESTree.Node
type BinaryExpression = TSESTree.BinaryExpression

// Store all the possible values for the operator property
type BinaryOperator = BinaryExpression['operator']

// Define a special type that narrows the operator
type BinaryExpressionWithOperator<T extends BinaryOperator> = BinaryExpression & { operator: T }


// Generic overload that doesn't test for operator
export function isBinaryExpression(node: Node): node is BinaryExpression
// Special overload that only matches if the opertor matches
export function isBinaryExpression<T extends BinaryOperator>(node: Node, operator: T): node is BinaryExpressionWithOperator<T>

// Implementation that allows both arguments
export function isBinaryExpression(node: Node, operator?: string): node is BinaryExpression {
  return node.type === AST_NODE_TYPES.BinaryExpression && (
    operator === undefined
    || node.operator === operator
  )
}

const generic: Node = {
  type: 'BinaryExpression',
  operator: '+',
  /*...*/
} as Node
// => TSESTree.ArrayExpression
//    | TSESTree.ArrayPattern
//    | TSESTree.ArrowFunctionExpression
//    | TSESTree.AssignmentExpression
//    | TSESTree.AssignmentPattern
//    | TSESTree.AwaitExpression
//    | ... 150 more ...
//    | TSESTree.YieldExpression

if (isBinaryExpression(generic)) {
  // typeof generic is now
  // => { type: 'BinaryExpression', operator: BinaryOperator, left: ..., }
} else {
  // typeof generic is now anything except for
  // ~> { type: 'BinaryExpression' }
}

if (isBinaryExpression(generic, '+')) {
  // typeof generic is now
  // => { type: 'BinaryExpression', operator: '+', left: ..., }
} else {
  // typeof generic is still Node
}

`const` arrays and `OneOf<const Array>`

Often you have a distinct set of values you want to allow. Since TypeScript 3.4
there is no need to do weird transformations using helper functions.

The example below has a set of options in A and defines the union type OneOfA which is one of the options of A.

export type OneOf<T extends ReadonlyArray<any>> = T[number]

const A = ['foo', 'bar', 'baz'] as const
type OneOfA = OneOf<typeof A>
// => 'foo' | 'bar' | 'baz'

function indexOf(key: OneOfA): number {
  return A.indexOf(key)
  // never returns -1
}

Custom errors

As per TypeScript 2.1, transpilation of built-ins is weird. If you don't need to support IE10 or lower, the following pattern works well:

class EarlyFinalization extends Error {
  constructor() {
    super('Early finalization')
    // Doesn't work on IE10-
    Object.setPrototypeOf(this, EarlyFinalization.prototype);

    // Adds proper stacktrace
    Error.captureStackTrace(this, this.constructor)
  }
}

Setting `this`

There are (at least) two ways to tell TypeScript what the current contextual this value of a function is. The first one is adding a parameter this to your function:

interface Traverser {
  break(): void
}

function walker(this: Traverser, root: Node) {
  this.break()
  // no error
}

This can be very helpful if you're declaring functions outside the scope of a class or similar, but you know what the this value will be bound to.

The second method actually allows you to define it outside of the function:

interface HelperContext {
  logError: (error: string) => void;
}

const helperFunctions: { [name: string]: (() => void) } & ThisType<HelperContext> = {
  hello: function() {
      this.logError("Error: Something went wrong!");
      // TypeScript successfully recognizes that "logError" is a part of "this".

      this.update();
      // TS2339: Property 'update' does not exist on HelperContext.
  }
}

This can be very helpful if you're binding a collection of functions.

Conclusion

TypeScript has a lot of gems 💎 and even moreso in userland. Make sure that you check the built-in types, type-fest and your own collection of snippets, before you resort to as unknown as X or : any. A lot of the times there really is a proper way to do thing.

Writing a code analyzer in TypeScript (from scratch)

Derk-Jan Karrenbeld — Mon, 10 Jun 2019 23:29:45 +0000

Exercism is an online platform designed to help you improve your coding skills through practice and mentorship.

At the moment of writing, I'm a maintainer of the JavaScript and TypeScript track and recently we've been working on automating a part of the experience.

This article will introduce you to AST parsing and walking using ESTree compatible tools. It specifically looks at certain token types, most commonly found in JavaScript and TypeScript code.

It teaches you how to explore these trees yourself and refers to code samples and actual production implementations.

When reading this article, think about your own JavaScript and TypeScript code. Once you understand how the browser (and tooling, like eslint) parses your code, you might better understand how the language is defined and constructed.

🚧 The links to GitHub are all master links, meaning the contents may change between writing this article and you clicking them. However, in order to make sure the code samples make sense, the analyzer repository links refer to a specific commit (9ff332b). This means that the code you see might not be the same as what is used today.

Table of Contents
📝 The exercise
- JavaScript implementation
- TypeScript implementation
💯 Optimal solutions
- JavaScript solution
- TypeScript solution
👩🏽‍💻 Analysing the code
- 💬 Abstract Syntax Trees
- 🏃🏽‍💨 Running the parser
- 🔎 Finding the main entrypoint
- 🔎 Finding the top-level constant
The algorithm
- Properties of objects
- "Executing" a property
- Matching the identifiers
✅ Automated Mentoring
- 📦 Testing exports
- Inline exports
- Specifier exports
- CommonJS exports
🔀 Testing varations
Walking TypeScript Trees
- 🔑 Visitor Keys
- 📖 Type annotations
- Class properties
- ↩ Return types
Conclusion
Reference
- Analyzer reference
- Exercism repositories
- Packages

📝 The exercise

For this article, I'm going to write the analyzer for the gigasecond exercise, for both the TypeScript ánd JavaScript track. The description is a mere two lines:

Given a moment, determine the moment that would be after a gigasecond has passed.

A gigasecond is 10^9 (1,000,000,000) seconds.

The canonical data hints at the code I need to write, but luckily the exercise is implemented in both the JavaScript and TypeScript tracks.

JavaScript implementation

The JavaScript implementation expects us to write a named export gigasecond which returns a Date that is a gigasecond past the input Date.

  // Test case from the JavaScript track
  test('tells a gigasecond anniversary since midnight', () => {
    const gs = gigasecond(new Date(Date.UTC(2015, 8, 14)));
    const expectedDate = new Date(Date.UTC(2047, 4, 23, 1, 46, 40));
    expect(gs).toEqual(expectedDate);
  });

TypeScript implementation

The TypeScript implementation expects us to write a default export Gigasecond which is a class that has a date() function which returns a Date that is a gigasecond past the constructor Date.

  // Test case from the TypeScript track
  it('tells a gigasecond anniversary since midnight', () => {
    const gs = new Gigasecond(new Date(Date.UTC(2015, 8, 14)))
    const expectedDate = new Date(Date.UTC(2047, 4, 23, 1, 46, 40))
    expect(gs.date()).toEqual(expectedDate)
  })

💯 Optimal solutions

Before tackling how to write an analyzer for these two implementations, I first have to establish what the optimal solutions are. If I know the intended code result, I can try to recognise that and work from there.

JavaScript solution

The implementation in JavaScript is straightforward. It uses the Date constructor together with Date#getTime and a constant to generate a the appropriate result.

const GIGASECOND_IN_MS = (10 ** 9) * 1000

export function gigasecond(date) {
  return new Date(date.getTime() + GIGASECOND_IN_MS)
}

It is vital to note the peculiarities here:

Optimal is extracting the GIGASECOND_IN_MS value as a top-level constant
The constant's value ((10 ** 9) * 1000) can optimally be written in many equally valid forms. Writing the number out, however, is deemed a smell. All the following SHOULD be recognised as optimal:
- 10 ** 12
- 1e9 * 1e3
- 1e12,
- Math.pow(10, 9) * 1000
- Math.pow(10, 12)
Date#valueOf is not optimal. It is marked as "This method is usually called internally by JavaScript and not explicitly in code.", even though it's functionally equivalent.
Finally, Date.parse(date) is not a good candidate as it's supposed to work with strings only. The reason it returns the same value as getTime when given a date, is because that date is coerced to a string and then parsed.

TypeScript solution

The TypeScript implementation expects a class as default export, and has a method date(). The algorithm is exactly the same as in the JavaScript solution, but it requires type annotations.

const GIGASECOND_IN_MS = (10 ** 9) * 1000

export default class Gigasecond {

  private readonly futureDate: Readonly<Date>

  constructor(date: Readonly<Date>) {
    this.futureDate = Object.freeze(new Date(date.getTime() + GIGASECOND_IN_MS))
  }

  date(): Readonly<Date> {
    return this.futureDate
  }
}

Apart from the variations and rules as described earlier for JavaScript, the calculation may be done either in the constructor (as shown above) or in the date function. In that last case, it will look as follows:

const GIGASECOND_IN_MS = (10 ** 9) * 1000

export default class Gigasecond {

  constructor(private readonly date: Date) { }

  date(): Date {
    return new Date(date.getTime() + GIGASECOND_IN_MS)
  }
}

👩🏽‍💻 Analysing the code

Now it's time to actually write the analyzer. We'll focus on the JavaScript implementation first. Because there are already JavaScript analyzers running in the wild and that work is open source, this example will use the utilities and base class from the javascript-analyzer repository.

💬 Abstract Syntax Trees

The JavaScript Analyzer will be working the Abstract Syntax Tree (AST) of the code solutions. There are other ways to write an analyzer, but for the sake of this article, AST parsing is the way to go.

yarn add @typescript-eslint/parser @typescript-eslint/typescript-estree

The TypeScript ESLint team has built a great parser that outputs an ESTree, a specced format of tokens and information about the input code. It can work with both JavaScript and TypeScript and is therefore great for our use case. I prefer working with this type of tree, because of the spec which allows for interoptability with other tools.

The parser deals with the eslint configuration and then invokes the typescript-estree package which compiles the code using TypeScript and transforms the result to match the ESTree. You can head on over to AST Explorer and try this out yourself by pasting the example code from above into the input field and selecting @typescript-eslint/parser. ⚠ Note: The version of the parser here is usually not up-to-date with the latest parser.

You might wonder: Why not use the TypeScript Compiler Api? It has AST parsing built-in the TypeScript language. It also exposes a lot of helper functions (like isIdentifer).

The reason is that the output is not in the ESTree spec format, which means that you won't be able to use other tools with it. In fact, the TypeScript-ESTree package, actually uses the compiler under the hood but then transforms it to the spec, which means no lock-in. You're not bound by changes in the compiler.

🏃🏽‍💨 Running the parser

Now that the packages are in place, let's parse the input code.

import { parse, TSESTreeOptions } from "@typescript-eslint/typescript-estree";

const options: TSESTreeOptions = {
  comment: false,
  jsx: false
}

const program = parse(source, options)
// => Program({ body: [...], sourceType: "module", tokens: [...] })

This gives us the same output as you see in AST Explorer, with at the root a Program and its body. We won't need the other fields, but tokens is interesting. It lists the parsed tokens from the source, as it was building the tree.

💎 You can find this in parsers/AstParser.ts

🔎 Finding the main entrypoint

We're looking for a function called gigasecond. We know the following things:

It must be exported
Its name must be gigasecond

The input code declares a function, like in the optimal solution above, so the tree holds a FunctionDeclaration with an Identifier:

export function gigasecond(date) {
  // ...
}

{
  type: "FunctionDeclaration",
  id: {
    type: "Identifier",
    name: "gigasecond"
  },
  generator: false,
  expression: false,
  async: false,
  params: [ ... ],
  // The body is a block { ... }
  body: {
    type: "BlockStatement",
    body: [ ... ]
  }
}

This is something it can search for. The most common way to search in an AST is by walking that tree. You start at some node (usually the root / program) and visit each item.

We know that our parsed EStree is compatible with eslint and that eslint, just like prettier can recognise (and transform) code.

# Not a dev dependency!
yarn add eslint

import { TSESTree } from "@typescript-eslint/typescript-estree"
import { traverse } from 'eslint/lib/util/traverser'

traverse(program, {
  enter(node: TSESTree.Node) {
    // ...
  }
})

When writing this code, TypeScript will complain that there are no types for this library, which is unfortunately still true at moment of writing. However, you can copy this declarations.d.ts I wrote in order to get type completion.

The enter method will be called for each node in the program. Inside the enter block, your in the "TraverserContext" which exposes two methods:

this.skip(): skips the node from further traversal, meaning it will not visit any other keys (and therefore children) of the current node;
this.break(): completely stop traversing.

Finding the entrypoint is now straightforward.

import { TSESTree, AST_NODE_TYPES } from "@typescript-eslint/typescript-estree"

let entry: TSESTree.FunctionDeclaration | undefined = undefined

traverse(program, {
  enter(node: TSESTree.Node) {
    switch (node.type) {

      // function name() {}
      case AST_NODE_TYPES.FunctionDeclaration:
        if (node.id && node.id.name === 'gigasecond') {
          entry = node
          this.break()
        }
        break;
    }
  }
})

entry
// => FunctionDeclaration({
//      id: { type: "Identifier", name: "gigasecond" }, ...
//    })

Unfortunately the walker above only finds FunctionDeclaration and fails on equivalent code usign an ArrowFunctionExpression or FunctionExpression. More on that later.

💎 You can find this in analyzers/utils/extract_main_method.ts

🔎 Finding the top-level constant

The code finds the first of the two components. Now it also needs to find the second. A top-level const, but the name is not known.

const GIGASECOND_IN_MS = (10 ** 9) * 1000

{
  type: "VariableDeclaration",
  declarations: [
    {
      type: "VariableDeclarator",
      id: {
        type: "Identifier",
        name: "GIGASECOND_IN_MS"
      },
      init: {
        type: "BinaryExpression",
        operator: "*",
        // Left is another BinaryExpression with **
        left: { ... },
        // Right is a Literal
        right: { ... }
      }
    }
  ],
  kind: "const"
}

Nothing here is particularly helpful. Given the variations of data it needs to accept, I can't rely on init being a certain type. The name is also not fixed as it's not exported and therefore not tested.

However, there are a few constraints that will help here:

It must be a top-level constant
It can not be named gigasecond
In an optimal solution, there is really only one top-level constant that is not the entry,

type FoundConst = { kind: TSESTree.VariableDeclaration['kind'] }
  & TSESTree.VariableDeclarator

let bigNumber: FoundConst | undefined = undefined

traverse(program, {
  enter(node: TSESTree.Node) {
    switch (node.type) {

      // const NAME = ...
      case AST_NODE_TYPES.VariableDeclaration:
        const declaration = node.declarations.find(
          (declaration) => declaration.id && declaration.id.name !== 'gigasecond')
        )

        if (declaration) {
          bigNumber = { kind: node.kind, ...declaration }
          this.break()
        }

        break;

      default:
        // This doesn't declare a variable, so skip the node
        this.skip()
    }
  }
})

Later, I can check bigNumber['kind'] and make sure it's const, or otherwise attach a message that const is preferred.

💎 You can find this in analyzers/utils/find_top_level_constants.ts

The algorithm

Now that I found the entry point, I can figure out what the name of the argument is (date). Because I also know the top-level constant, I know what the constant name is GIGASECOND_IN_MS.

new Date(...)

Nothing too fancy here. It's a new expression with an expression as the first argument.

{
  type: "NewExpression",
  callee: {
    type: "Identifier",
    name: "Date"
  },
  arguments: [ ... ]
}

let newDate: TSESTree.NewExpression | undefined = undefined

traverse(program, {
  enter(node: TSESTree.Node) {
    switch (node.type) {

      // new Date(...)
      case AST_NODE_TYPES.NewExpression:
        if (
          node.callee.type === AST_NODE_TYPES.Identifier
          && node.callee.name === 'Date'
        ) {
          newDate = node;
          this.break()
        }
        break;

      default:
        // This doesn't declare a variable, so skip the node
        this.skip()
    }
  }
})

💎 You can find this in analyzers/utils/find_new_expression.ts

The inner expression is of type BinaryExpression. In EStree compatible output, and operator with two components (such as +, -, *) is a binary expression, whereas those with one component (such as ~ and !) are unary expressions.

date.getTime() + GIGASECOND_IN_MS

{
  type: "BinaryExpression",
  operator: "+",
  left: {
    type: "CallExpression",
    callee: {
      type: "MemberExpression",
      object: {
        type: "Identifier",
        name: "date"
      },
      property: {
        type: "Identifier",
        name: "getTime"
      }
    },
    arguments: []
  },
  right: {
    type: "Identifier",
    name: "GIGASECOND_IN_MS"
  }
}

Quite a few things we've already seen and also a few new types. Let's look at those.

Properties of objects

When the parser encounters a object property accessor (object.property), it is parsed as a MemberExpression. Depending on the way of writing, the property is either an Identifier or a Literal.

date.getTime
// ^       ^
// object  property
// |       |
// |       identifier (name = getTime)
// identifier (name = date)

date['getTime']
// ^       ^
// object  property
// |       |
// |       literal (value = getTime)
// identifier (name = date)

"Executing" a property

If there are parentheses behind the MemberExpression, the entire expression is parsed as a child of a CallExpression. This is also the case for parentheses following an indentifier.

date.getTime ( )
// ---------| ^ |
// ^        | argument(s) of call expression
// member expression
//              |
// -------------|
// call expression

gigasecond(INPUT)
// ------|   ^   |
// ^     | argument of call expression
// identifier    |
//               |
// --------------|
// call expression

Matching the identifiers

There are two identifiers provided by the source code that I need to find and match against:

the gigasecond first argument (used in arg.getTime())
the top-level constant (used in time + CONSTANT)


const argumentName = entry.id.name
// => "gigasecond"
const constantName = bigNumber.id.name
// => "GIGASECOND_IN_MS"

let optimalExpression: boolean = false

// NOTE: passing in the newDate as root, so this is a subtree traversal!
traverse(newDate, {
  enter(node: TSESTree.Node) {
    switch (node.type) {

      // new Date(x.z() + y)
      case AST_NODE_TYPES.BinaryExpression:
        this.break()

        if (node.operator !== '+') {
          optimalExpression = false;
          return;
        }


        // This allows the order to be reversed
        const leftType = node.left.type
        const constSide = leftType === AST_NODE_TYPES.Identifier
          ? node.left
          : node.right
        const expressionSide = leftType === AST_NODE_TYPES.CallExpression
          ? node.left
          : node.right

        if (constSide === expressionSide) {
          // throw new Error("not optimal! this is not x.z() + y")
          optimalExpression = false
          return
        }

        if (constSide.id.name !== constantName) {
          optimalExpression = false
          return
        }

        const { object, property } = expressionSide.callee
        optimalExpression =
          object.type === AST_NODE_TYPES.Identifier
          && object.name === argumentName
          && ((
            property.type === AST_NODE_TYPES.Identifier
            && property.name === 'getTime'
          ) || (
            property.type === AST_NODE_TYPES.Literal
            && property.value === 'getTime'
          ))

      break;
    }
  }
})

💎 You can find this in:

analyzers/utils/find_member_call.ts,

analyzers/utils/is_binary_expression.ts,

analyzers/utils/is_identifier.ts, and

analyzers/utils/is_literal.ts.

✅ Automated Mentoring

When all these pieces are put together, it is the analyzer for gigasecond. There are a few more things to check:

Is the bigNumber.kind equal to "const"? If not, add a comment
Is the value of GIGASECOND_IN_MS using one of the comprehensions? If not, add a comment.
Is there only one argument to gigasecond? Make sure it's not a ...splat argument, and that it has no value = "default".
Is gigasecond actually exported? Is the export inline? if not, add a comment.

Since the first one was mentioned (kind equality check) and the second one is very similar to the inner expression of the new Date(...) call, I've left out how to implement these. You can check the gigasecond analyzer source code if you need some inspiration. The third one is testing the entry for parameters.

As for exports, these are handled by 💎 extract_export, but I'll show you the gist of it.

📦 Testing exports

Exports in JavaScript and TypeScript basically come in three types. Those using a core language feature (read: use a keyword) are the easiest:

export const inline = {}
export default class InlineClass {}
export default defaultSpecifier
export { specifier }
export { specifier as renamed }

The default export have their own token type ExportDefaultDeclaration.

{
  type: "ExportDefaultDeclaration",
  declaration: {
    // ...
  }
}

Those without a default modifier are of type ExportNamedDeclaration.

{
  type: "ExportNamedDeclaration",
  declaration: {
    // ...
  }
}

The declaration property is where it gets slightly tricky. The inline export statements, regardless if they're default or not, are followed by the same token types as if they did not have the export keyword similarly to how writing parentheses wraps an expression in a CallExpression.

Inline exports

This means that the first example is a VariableDeclaration with a single VariableDeclaractor: the id is an Identifier with name = "inline" and the init is an ObjectExpression. Similarly the second example is a ClassDeclaration with as id an Identifier with name = "InlineClass".

Specifier exports

The third has a declaration of type Identifier with name = "defaultSpecifier". This is similar to inline exports.

The fourth and fifth however, do not have a declaration property. Instead, they have a specifiers property with, in this case, one item:

{
  type: "ExportSpecifier",
  local: {
    type: "Identifier",
    name: "specifier"
  }
  exported: {
    type: "Identifier",
    name: "specifier" // or "renamed"
  }
}

Use the local property to determine what is exported (what the internal name is) and the exported property how it's imported (what the exported name is).

CommonJS exports

Finally there are those exports that don't use a keyword but instead use the (as far as I'm concerned) defunct module.exports.

module.exports = singleExport
module.exports = { specifier }
module.exports.default = defaultExport
module.exports.renamed = specifier

Since these don't use keywords, they're interpreted as ExpressionStatements, as they're AssignmentExpressions. Here is a quick overview table of the important properties and representations:

expression	type	prop	value
`module.exports.renamed = specifier`	`AssignmentExpression`
		`operator`	`"="`
	`Identifier`	`right`	`"specifier"`
	`MemberExpression`	`left`	`🔽 module.exports.renamed 🔽`
`module.exports.renamed`	`MemberExpression`
	`Identifier`	`property`	`"renamed"`
	`MemberExpression`	`object`	`🔽 module.exports 🔽`
`module.exports`	`MemberExpression`
	`Identifier`	`property`	`"exports"`
	`Identifier`	`object`	`"module"`

There is also the variant of using the object['accessor'], where accessor is not an Identifier but a Literal, but otherwise that is the same.

🔀 Testing varations

As mentioned before, there are many ways to write functions in JavaScript and TypeScript. In the source code for the analyzer there is a utility method 💎 extract_main_method. It can detect the following variations:

function name() {}
// FunctionDeclaration

const name = () => {}
// ArrowFunctionExpression

const name = function() {}
// FunctionExpression

export default {
  name: () => {}
}
// ExportDefaultDeclaration + ObjectExpression + (Arrow)FunctionExpression

And the TypeScript specific variants (but they work on both)

class Foo {
  name() {}
}
// MethodDefinition + FunctionExpression

class Foo {
  static name = () => {}
  static name = function name() {}
}
// ClassProperty + (Arrow)FunctionExpression

Walking TypeScript Trees

As you've noticed, all we did so far is checking the JavaScript code and shown how that is parsed and walked. In order to adapt the solution so that TypeScript code can be parsed with it, there is one thing to change in the walker and a few extra properties to test for.

🔑 Visitor Keys

When the traverser is walking the tree, it decides which nodes to "walk 🚶🏽‍" based on a set of keys called visitor keys. Since TypeScript is a superset of JavaScript it has the same keys and then some.

import { visitorKeys } from "@typescript-eslint/parser/dist/visitor-keys"

traverse(root, {
  enter(node: Node) {
    // ...
  },

  visitorKeys
})

If you look at the source of that file, you'll see that it actually imports the eslint visitor keys (in order to visit all the JavaScript keys) and adds the specific TypeScript keys.

📖 Type annotations

These are interesting.

class Gigasecond {
  constructor(private readonly date: Date) { }
}

{
  type: "ClassDeclaration",
  id: {
    type: "Identifier",
    name: "Gigasecond"
  },
  // everything inside the class { body }
  body: {
    type: "ClassBody",
    body: [
      {
        // a constructor is a regular method definition...
        type: "MethodDefinition",
        key: {
          type: "Identifier",
          name: "constructor"
        },
        value: {
          type: "FunctionExpression",
          params: [{ /*...*/ }],
          generator: false,
          expression: false,
          async: false,
          body: { /*...*/ }
        }
        computed: false,
        static: false,  // (typescript static keyword)
        // ... but with a special kind
        kind: 'constructor'
      }
    ]
  }
}

The above has no special properties over the JavaScript equivalent, but that's because there are no type annotations in the source except for in the params of the constructor:

{
  type: "Identifier",
  name: "date",
  // : ...
  typeAnnotation: {
    type: "TSTypeAnnotation",
    typeAnnotation: {
      // Readonly
      type: "TSTypeReference",
      typeName: {
        type: "Identifier"
        name: "Readonly"
      },
      // <...>
      typeParameters: {
        type: "TSTypeParameterInstantiation",
        // Each type between the < brackets >
        params: [
          {
            type: "TSTypeReference",
            typeName: {
              type: "Identifier",
              name: "Date"
            }
          }
        ]
      }
    }
  }
}

A few key observations:

The type annotation has its own visitor key typeAnnotation,
All the TypeScript nodes start with TS,
A generic type is just a TSTypeReference with both a typeName and one or multiple typeParameters.
Stripping types is almost as easy as removing the typeAnnotation keys, which is almost exactly what babel's preset-typescript does.

Class properties

In TypeScript you can annotate class properties with keywords such as private and readonly. Additionally, they can have a type (which is Date in this example).

class Gigasecond {
  private readonly futureDate: Date
}

{
  type: "ClassProperty",
  key: {
    type: "Identifier",
    name: "futureDate"
  },
  computed: false,
  static: false,            // static keyword
  readonly: true,           // readonly keyword
  accessibility: "private", // private, protected, public keywords
  typeAnnotation: {
    type: "TSTypeAnnotation",
    typeAnnotation: {
      type: "TSTypeReference",
      typeName: {
        type: "Identifier",
        name: "Date"
      }
    }
  }
}

The TypeScript keywords private and readonly modify the ClassProperty directly, but the type is again on typeAnnotation. If the type annotation is left out the source code (read: implicit any), the typeAnnotation key is not present on the AST.

↩ Return types

The final type we'll look at for now are function return types. Most other type annotations are just variations on this and the ones mentioned before.

class Gigasecond {
  date(): Date {
    // ...
  }
}

{
  type: "MethodDefinition",
  key: {
    type: "Identifier",
    name: "date"
  },
  value: {
    type: "FunctionExpression",
    generator: false,
    expression: false,
    async: false,
    body: { /*...*/ },
    params: [],
    returnType: {
      type: "TSTypeAnnotation",
      typeAnnotation: {
        type: "TSTypeReference",
        typeName: {
          type: "Identifier",
          name: "Date"
        }
      }
    }
  },
  computed: false,
  static: false, // static keyword
  kind: "method"
}

As you might have noticed, the typeAnnotation is not on the MethodDefinition. That is because a method definition on a class is actually binding a function expression (): Date { ... } to the identifier date.

On the FunctionExpression you can find the previously not encountered type annotation returnType. Its structure is the same as typeAnnotations for ClassProperty.

Conclusion

Interpreting code as an Abstract Syntax Tree and seeking out certain properties is a lot of tree walking; because there is a specification for the format of the output of certain AST Parsers, you can write tooling yourself.

The contents of this article, in a different format, is being used to automatically approve the gigasecond exercise, given that the student has provided an exact variation of the optimal solution. There is enough surface to hook into the findings of the analyzer to provide meaningfull commentary, should the student not have provided an optimal solution.

Reference

Analyzer reference

Exercism repositories

Packages

Control flow in reduce/inject (ruby)

Derk-Jan Karrenbeld — Mon, 03 Jun 2019 23:29:49 +0000

reduce (inject) is one of the most powerful
methods that exists on the Enumerable module, meaning that the
methods are available on any instances of any class that includes this module,
including Array, Hash, Set and
Range.

reduce can be used in a MapReduce process,
often is the base for comprehensions and is a great way to group values or
calculate a single value (reducing a set of values to a single value) given a
set of values.

This article quickly shows you how to skip values / conditionally return values
during a reduce iteration and how to break early / return a
different value and stop iteration.

Recap 💬

From the documentation, given an instance enum (an Enumerable) calling
enum.reduce:

# Combines all elements of <i>enum</i> by applying a binary
# operation, specified by a block or a symbol that names a
# method or operator.

An example of using reduce would be write a function that sums
all the elements in a collection:

##
# Sums each item in the enumerable (naive)
#
# @param [Enumerable] enum the enumeration of items to sum
# @return [Numeric] the sum
#
def summation(enum)
  sum = 0
  enum.each do |item|
    sum += item
  end
  sum
end

##
# Sums each item in the enumerable (reduce block)
#
# Each iteration the result of the block is the passed in previous_result.
#
# @param [Enumerable] enum the enumeration of items to sum
# @return [Numeric] the sum
#
def summation(enum)
  enum.reduce do |previous_result, item|
    previous_result + item
  end
end

##
# Sums each item in the enumerable (reduce method)
#
# Each iteration the :+ symbol is sent as a message to the current result with
# the next value as argument. The result is the new current result.
#
# @param [Enumerable] enum the enumeration of items to sum
# @return [Numeric] the sum
#
def summation(enum)
  enum.reduce(:+)
end

##
# Alias for enum.sum
#
def summation(enum)
  enum.sum
end

reduce takes an optional initial value, which is used instead of
the first item of the collection, when given.

How to control the flow?

When working with reduce you might find yourself in one of two
situations:

you want to conditionally return a different value for the iteration (which is used as base value for the next iteration)
you want to break out early (stop iteration altogether)

next ⏭

The next keyword allows you to return early from a yield block, which is the
case for any enumeration.

Let’s say you the sum of a set of numbers, but want half of any even
number, and double of any odd number:

def halfly_even_doubly_odd(enum)
  enum.reduce(0) do |result, i|
    result + i * (i.even? ? 0.5 : 2)
  end
end

Not too bad. But now another business requirement comes in to skip any number
under 5:

def halfly_even_doubly_odd(enum)
  enum.reduce(0) do |result, i|
    if i < 5
      result
    else
      result + i * (i.even? ? 0.5 : 2)
    end
  end
end

Ugh. That’s not very nice ruby code. Using next it could look like:

def halfly_even_doubly_odd(enum)
  enum.reduce(0) do |result, i|
    next result if i < 5
    next result + i * 0.5 if i.even?
    result + i * 2
  end
end

next works in any enumeration, so if you’re just processing items using
.each , you can use it too:

(1..10).each do |num|
  next if num.odd?
  puts num
end
# 2
# 4
# 6
# 8
# 10
# => 1..10

break 🛑

Instead of skipping to the next item, you can completely stop iteration of a an
enumerator using break.

If we have the same business requirements as before, but we have to return the
number 42 if the item is exactly 7, this is what it would look like:

def halfly_even_doubly_odd(enum)
  enum.reduce(0) do |result, i|
    break 42 if i == 7
    next result if i < 5
    next result + i * 0.5 if i.even?
    result + i * 2
  end
end

Again, this works in any loop. So if you’re using find to try to find
an item in your enumeration and want to change the return value of that
find, you can do so using break:

def find_my_red_item(enum)
  enum.find do |item|
    break item.name if item.color == 'red'
  end
end

find_my_red_item([
  { name: "umbrella", color: "black" },
  { name: "shoe", color: "red" },
  { name: "pen", color: "blue" }
])
# => 'shoe'

StopIteration

You might have heard about or seen raise StopIteration.
It is a special exception that you can use to stop iteration of an enumeration,
as it is caught be Kernel#loop, but its use-cases are limited as
you should not try to control flow using raise or fail. The
airbrake blog has a good article about this
use case.

When to use reduce

If you need a guideline when to use reduce, look no further. I
use the four rules to determine if I need to use reduce or
each_with_object or something else.

I use reduce when:

reducing a collection of values to a smaller result (e.g. 1 value)
grouping a collection of values (use group_by if possible)
changing immutable primitives / value objects (returning a new value)
you need a new value (e.g. new Array or Hash)

Alternatives 🔀

When the use case does not match the guidelines above, most of the time I
actually need each_with_object which has a similar
signature, but does not build a new value based on the return value of a block,
but instead iterates the collection with a predefined “object”, making it much
easier to use logic inside the block:

doubles = (1..10).each_with_object([]) do |num, result|
  result << num* 2
  # same as result.push(num * 2)
end
# => [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

doubles_over_ten = (1..10).each_with_object([]) do |num, result|
  result << num * 2 if num > 5
end
# => [12, 14, 16, 18, 20]

Use each_with_object when:

building a new container (e.g. Array or Hash). Note that you’re not really reducing the current collection to a smaller result, but instead conditionally or unconditionally map values.
you want logic in your block without repeating the result value (because you must provide a return value when using reduce)

My use case

The reason I looked into control flow using reduce is because I was iterating
through a list of value objects that represented a migration path. Without using
lazy, I wanted an elegant way of representing when these
migrations should run, so used semantic versioning. The migrations enumerable is
a sorted list of migrations with a semantic version attached.

migrations.reduce(input) do |migrated, (version, migration)|
  migrated = migration.call(migrated)
  next migrated unless current_version.in_range?(version)
  break migrated
end

The function in_range? determines if a migration is executed, based on the
current “input” version, and the semantic version of the migration. This will
execute migrations until the “current” version becomes in-range, at which point
it should execute the final migration and stop.

The alternatives were less favourable:

take_while, select and friends are able to filter the list, but it requires multiple iterations of the migrations collection (filter, then “execute”);
find would be a good candidate, but I needed to change the input so that would require me to have a bookkeeping variable keeping track of “migrated”. Bookkeeping variables are almost never necessary in Ruby.

DEV Community: Derk-Jan Karrenbeld

Predicate (Programming logic)

Predicates in English

Predicates in Programming

Conclusion

Cross tab events

Use a BroadcastChannel

React use case

Compatibility

Use localStorage

React hook

Onwards

FFMPEG examples

Transcoding a file

Example call and output

Probing the duration

Example call and output

Forward arguments in shell

Windows

Resources

Internship 2019: Reading list

Why You Need to Build an MVP App (and 5 tips on how to do it) | by Jessi Salonen | The Startup | Medium

Jessi Salonen ・ Jun 19, 2017 ・ 9 min read Medium

JavaScript: What the heck is a Callback? | by Brandon Morelli | codeburst

Brandon Morelli ・ Jul 5, 2017 ・ 5 min read codeburst.io

JavaScript Event Loop Explained. “How is JavaScript asynchronous and… | by Anoop Raveendran | Frontend Weekly | Medium

Anoop Raveendran ・ Nov 9, 2018 ・ 4 min read Medium

Web fonts: when you need them, when you don’t | by David Gilbertson | HackerNoon.com | Medium

David Gilbertson ・ May 22, 2019 ・ 17 min read Medium

Building the Google Photos Web UI | by Antin Harasymiv | Google Design | Medium

Antin Harasymiv ・ Jul 10, 2018 ・ 27 min read Medium

Web Architecture 101. The basic architecture concepts I wish… | by Jonathan Fulton | Storyblocks Product & Engineering

Jonathan Fulton ・ Dec 12, 2018 ・ 11 min read engineering.videoblocks.com

The ultimate guide to proper use of animation in UX | by Taras Skytskyi | UX Collective

Taras Skytskyi ・ Mar 9, 2019 ・ 11 min read uxdesign.cc

Everything you need to know about skeleton screens | by Bill Chung | UX Collective

Bill Chung ・ Jun 5, 2020 ・ 14 min read uxdesign.cc

Animation principles for UX and UI designers | by Vernon Joyce | UX Planet

Vernon Joyce ・ Jul 16, 2019 ・ 11 min read uxplanet.org

Want to help people learn programming languages?

Writing a code analyzer in TypeScript (from scratch)

Derk-Jan Karrenbeld for XP Bytes ・ Jun 10 '19

What can you work on

Help out your favourite language

Write an analyzer, or help improving one

Optimal solution

Variations (approvable without comment)

Helper function variation

SHOULD comment and disapprove

Approach

Join the mentors

Join the students!

Tetris: Choosing the tools and setting up the project

Table of Contents

The Game Engine

The Toolchain

Package management

Bundler

Compiler

Linting and Styleguides

Testing libraries

Base Library

Bootstrap

Initialisation of the project

Setting up typescript correctly

Setting up babel correctly

Setting up eslint correctly

Testing the eslint configuration

Fine-tuning the rules

Setting up jest correctly

Enabling jest-dom extensions

Getting a coverage report

Setting up prettier correctly

Automatically formatting

Conclusion

Tetris: Building a game using JavaScript

Definitions and Concepts

Movement and Buttons

Playfield

Tetrominos

Use a `BroadcastChannel`

Use `localStorage`

Jessi Salonen ・ Jun 19, 2017 ・ 9 min read
Medium

Brandon Morelli ・ Jul 5, 2017 ・ 5 min read
codeburst.io

Anoop Raveendran ・ Nov 9, 2018 ・ 4 min read
Medium

David Gilbertson ・ May 22, 2019 ・ 17 min read
Medium

Antin Harasymiv ・ Jul 10, 2018 ・ 27 min read
Medium

Jonathan Fulton ・ Dec 12, 2018 ・ 11 min read
engineering.videoblocks.com

Taras Skytskyi ・ Mar 9, 2019 ・ 11 min read
uxdesign.cc

Bill Chung ・ Jun 5, 2020 ・ 14 min read
uxdesign.cc

Vernon Joyce ・ Jul 16, 2019 ・ 11 min read
uxplanet.org

Setting up `typescript` correctly

Setting up `babel` correctly

Setting up `eslint` correctly

Testing the `eslint` configuration

Setting up `jest` correctly

Enabling `jest-dom` extensions

Setting up `prettier` correctly

`SafeOmit<T, K>` 🌐

`ReadonlyDeep<T>` 🌐

`RequireAtLeastOnce<T, K>` 🌐

`Merge<A, B>` 🌐

`Mutable<T>` 🌐

`WithFoo<T>`

`PromiseType<T>` 🌐

`ReturnType<T>` (built-in)

`InstanceType<T>` (built-in)

`ConstructorType<T>`

`const` arrays and `OneOf<const Array>`

Setting `this`