DEV Community: Paceaux

SelectorHound: The tool for Sniffing out CSS Selectors

Paceaux — Thu, 29 Feb 2024 18:31:48 +0000

A few years back I ran into a difficult situation on a project: I needed to find out where a particular CSS selector was used.

I had a static version of the site, and so I did what any fool might do and I tried searching for it in my IDE. I had two problems though:

Writing a RegEx to essentially parse HTML is substantially more ~~difficult~~ dangerous than you might expect.
The actual live version of the site was managed by a CMS (content management system), and it would be much more difficult to know where that selector might end up

So after almost a day of failing to produce a good-enough RegEx, I got an idea: What if I just scanned the live site for that selector?

In about the same amount of hours it took for me to write a RegEx that didn’t always work, I was able to produce a node.js-based script that could scan a live site for the selector.

So with that, I got the bright idea to make it a proper NPM package that could run on the command line. And now I should introduce you.

Introducing SelectorHound

SelectorHound is on NPM and it’s already at 2.2!

It’s a Command Line Interface (CLI) that offers a pretty robust set of options:

Give it a single selector or a CSS file
Give it a URL to a sitemap or tell it to crawl your site
Ask for a lot of details about HTML elements that match the selector, or a screenshot
Tell it to treat pages like they’re a SPA (Single Page Application) or like static HTML

What it's good for

Do you have CSS on your site that you’d like to delete, but you’re uncertain if it’s used anywhere?
Are you looking for instances where one element may be next to another?
Would you like to know if your stylesheet has rulesets that could be deleted?
Has malware infected your CMS and started adding weird links, but you don't know what pages?
Do you have calls to action that might be missing data attributes?

All of these are real world use-cases that I’ve used SelectorHound for.

Try it out

First, Install it

npm install -g selector-hound

For, for more speed (requires installing bun first):

bun install -g selector-hound

Then Run it

SelectorHound -u https://blog.frankmtaylor.com/sitemap.xml -s "h1"

Then Look at what you got

First it'll tell you what it's doing as it gets started

Whether it's crawling or using your sitemap, it will export the URLs to a JSON file.

This means you can customize the pages it scans.

And it’ll rely on that JSON file for every scan unless you pass -X to force it to generate a new sitemap file.

BTW it's way easier to represent fetching with emoji than "I read these URLs from a file on your computer"

Then it’ll tell you when it’s finished and give you a nice summary of what it found.

You can modify the output file name with the -o flag. Your chosen name will be prepended to pages.json.

Don't forget to check the log

The log file will look a lot like what you see in the CLI. One big difference though is that any errors that occur will show up here. It'll also tell you in the log if a page didn't have any matches.

And then check out the results

The results will be in a JSON format.

The -e flag can give you details about the elements in case you want to know exactly where on the page your selector is found.

The output can be pretty robust because it’ll give you results for every page that it found. I am working on a reporting feature that can summarize the results if you don’t want to wade through what could be thousands of lines of JSON.

Is it Performant?

It’s faster than writing a RegEx to scan your codebase, that’s for sure.

I’ve done a some testing and found that, if you were looking for a single HTML element, it might take on average .52s per page. If you install with Bun, you will get maybe a .1s gain.

We use it a lot at work and I can tell you that one site which has about 5600 pages, SelectorHound takes about 3 hours to find one very complex CSS selector. If you do the math that's 31 pages a minute or ... .52 seconds a page.

Whether you think that's fast or slow is going to be relative to how much energy you're willing to spend blindly clicking through a site trying to find those 12 buttons missing data attributes.

Activating Puppeteer to either take screenshots or just expect it to be a SPA will slow things down significantly, so use that with caution. I mentioned that you can take screen shots with -c, right?

Did I also mention you can use -f to pass in a whole CSS file? Because you can. And if you do, expect that to take a little longer, too.

Where can you see the code?

You can view the package on NPM and you can look at the code on Github

Feature requests and pull requests welcome.

Using :not()? Try NOT to...

Paceaux — Wed, 24 Jun 2020 02:38:12 +0000

CSS is full of little gotchas and head scratchers. It’s also got a land mine or two that’s all too easy to step on. One of those landmines is the :not() pseudo-class.

As useful as it may seem, I’d like to encourage you to not use it, unless you really, really mean to because of the side-effects it brings.

What does `:not()` do?

:not() is a pseudo-class. Like all pseudo-classes, it targets a state. The most common pseudo-classes we see in our stylesheets are :hover and :focus, but we do have other fun friends like :checked, :target, and everyone’s loneliest, :only-child.

In the case of :not(), the state that is being target is, well… a negative. It targets a state of not being something.

The goal of :not() is to exclude certain elements from a particular ruleset.

`:not()` tells the browser “is not this”

CSS selectors are parsed right-to-left— but when a pseudo class is “chained” to something, the best way to read it is by saying, “that is also”.

So we read the below selector as “every element with the class name article, that is also not an element with the class name article--news“

.article:not(.article--news) {
  color: blue;
}

:not() also raises specificity unexpectedly

Pseudo-classes have the specificity of a class. Usually.

How a typical pseudo-class behaves

Styling a plain element (also known as a type selector) gets us a specificity of 0,0,1:

a {
  color: #6ea5dc;
}

Then we style the :hover pseudo-class of this link element, getting the specificity 0,1,1:

a:hover {
 color: #6ea5c1;
}

And if we wanted something special for targeting two states of this element, we’d get a specificity of 0,2,1:

a:hover:visited {
  color: #7fb6d2;
}

How `:not()` behaves may surprise you

Let’s suppose you wanted to target links that are not in a state of being visited. You might write this:

a:not(:visited) {
  color: #6ea5c1;
}

The specificity on this selector is 0,1,1.

Well that’s just like it was with a:hover. What’s the big deal?

:not() didn’t raise the specificity. :visited did.

It’s the argument within `:not()` that raises specificity

Let’s suppose you’ve got a special style for your calls-to-action. Maybe they’re autogenerated and you feel the need to make a single, one-off case of making it different. It might be tempting to write this:

 a:not(#call-to-action--3428){
  color: #333;
}

First, let’s read that out-loud (go ahead, I won’t judge you):

Every a element that is also not an element with the id call-to-action--3428

Every element. Got it?

Would you believe that the specificity of this style, on every a element is now 1,0,1 ?

:not() passes the specificity of the thing you’re excluding onto the thing your targeting.

I’ll say that one more time for emotional effect:

:not() passes the specificity of the element you’re excluding to the element you’re targeting.

Ugh.

Can’t we just set a best-practice; “don’t make the argument for `:not()` higher than the target?”

So we’re saying a:not(.nav__link) is off the table because this will target every link on the page and give it a specificity of 0,1,1; that’s an “unexpected” specificity.

What if the excluded specificity matches the targeted?

Isn’t this safe with a specificity of 0,2,0?

.nav__link:not(:last-child) {
  color: #444;
}

Let’s read this together:

Every element with the class name nav__link that also is not the :last-child

Every. Element.

Except one—and every element except that one got the specificity of 0,2,0.

You know how quickly this becomes a problem? Try the first time you add a hover state:

/*If this doesn't come later in the cascade, it's pointless*/
.nav__link:hover { 
  color: #555;
}

Ok, so can the excluded specificity be less than the target’s specificity?

ul .nav__link:not(:last-child) will get you a specificity of 0,2,1 on every .nav__link, except one. You probably didn’t mean to do that.

.nav__link:not(button)? Specificity of 0,1,1 on every nav__link. You probably didn't mean to do that, either.

The thing is, it doesn’t matter what the argument is that you send into :not(). Unless it’s *, it’s going to raise the specificity on the targeted item.

That’s right. This is the only thing that you can safely write:

.nav__link:not(*) { /* Pull Request denied*/
  color: transparent; /* double-denied */
}

Should you use `:not()` to set “default styles”?

I’ve seen this pattern a few times in my life. Folks write out a “default style” using :not():

.nav__item:not(:last-child) { /* 0,2,0*/
  border-bottom: 1px solid #333;
}

But the cost here is that theming is now more difficult. What should be a natural increase in specificity isn’t. The below styles only work if they come later in my stylesheet.

.nav--darkMode .nav__item { /* 0,2,0 */
  border-bottom: 1px solid #fff; 
}

So more than likely, I end up arbitrarily raising specificity (otherwise known as specificity bloat):

.nav--darkMode .nav__item.nav__item { /* 0,3,0 ...who hurt you?*/
  border-bottom: 1px solid #fff; 
}

But, if I opt for a less terse selector that has clearer intent:

.nav__item { /* 0,1,0 */
  border-bottom: 1px solid #333;
}

.nav__item:last-child { /* 0,2,0 */
  border-bottom: none;
}

We discover that theming can come without introducing dependencies on code organization:

.nav--darkmode .nav__item { /* 0,2,0 */
  border-bottom: 1px solid #fff;
} /* Pull Request Approved. Let's get beer. */

So when is `:not()` safe?

Rarely

This is really an article about selector intent. Most of the time we write code thinking about what we intend to style. Not what we don’t intend to style.

:not() is safest when you’ve reached an edge case. An edge-case is a point in your code where the scope is very small and you have a clear understanding that it won’t be expanded further.

A perfect example is picking up where we left off with a themed navigation item. In our last example, we got ourselves in a hole: we would have to remove border on the last-child again:

.nav--darkmode .nav__item:last-child { /* 0,3,0 */
  border-bottom: none:
}

That isn’t what we want. We don’t want to write code that makes us write more code.

Now, suddenly, :not() seems very useful:

.nav--darkmode .nav__item:not(:last-child) {
  border-bottom: 1px solid #fff;
}

We still raised the specificity (0, 3, 0) on our .nav__item. But we did it on an edge-case at the benefit of not having to rewrite a pre-existing style. We wrote our selector with a clear intent of, “I don’t want to overwrite :last-child except when I’m dealing with a .nav__item that’s within a .nav--darkmode container.”

Avoid `:not()`, but don’t ignore it

Avoid it for excluding type selectors (elements)
Avoid it for setting default styles
Never pass in an element with a higher specificity than your target
Prefer it in narrow scopes to address edge-cases
Prefer it when it saves you from duplicating code at a higher specificity

What’s the highest z-index on a page (and other CSS property problems)

Paceaux — Fri, 24 Jan 2020 20:14:46 +0000

Ever been the new person on an old project where you were trying to not make things substantially worse? Maybe you need to position an element, but you don’t know what z-index value is safe to use. You don’t want to layer something to z-index: 9999 if z-index: 10 will suffice… but how do you find out what the highest z-index is?

Or, for that matter, how do you find everything that’s using opacity?

Sure, you’ve got a modern browser with great debugging tools. But they don’t make it easy for you to search by CSS properties. So I wrote a JavaScript function that can do that.

Remember the CSSOM?

I’ve written about the CSSOM in the past (CSS Object Model) and I’ll say again that it’s an under-appreciated and under-utilized feature of the web browser environment.

If you need to do something so peculiar as searching for selectors by CSS properties, this is the thing the CSSOM is good for.

It starts with the `stylesheets`

Let’s start by creating a new function that’ll take two arguments; queryPropName and queryPropValue. We’ll access some styleSheets and loop through them since they’re enumerable, but not an array.

function queryCSSByProperty(queryPropName, queryPropValue) {
  const styleSheets= document.styleSheets; 
  const properties = new Map(); 

  Object.values(styleSheets).forEach(styleSheet => {

  });
}

Next, try to loop through the rules

We’ll need to wrap the interior of our loop in a try-catch because the browser may throw some restrictions at us trying to access some of the cssRules. Then we’ll loop through the rules of that styleSheet

Object.values(styleSheets).forEach(styleSheet => {
      try {
        const rules = styleSheet.cssRules; 

        Object.values(rules).forEach(rule => {
        });
      } catch (err) {
        console.log(err);
}

Then, look for a style on the rule

Now that we’re inside of a rule inside of a stylesheet, we’re where we need to be. So now what we want to do is see if the CSS property we want is there.

First, let’s pull out some things that will be useful, like style, which will be an object that contains every possible CSS property. Let’s also grab some selectorText, which is strictly the CSS selector part of this ruleset (e.g. .someSelector > h1 > .foo )

Once we get that out, let’s be safe and check to be sure style is truthy. Not every cssRule will have a style property.

 Object.values(rules).forEach(rule => {
          const {style, selectorText} = rule;

          if (style) {

          }
});

And if there’s a style, check if it’s the one you want

This is where some logic could probably be cleaned up.

First, let’s use the CSSOM, rather than hasOwnProperty or for–in to find out if there’s a value for our property. getPropertyValue turns out to be the perfect way to get the value off of a specific CSS property in our style.

Next, because we want an option to see search by value of a property, we have hasPropValMatch to tell us exactly that. And for right now, rather than ===, let’s use indexOf because there’s always the chance that there’s an !important floating here. It’d be better to search within the string rather than assume it’s a pure equality. We’ll probably need more robust matching in the future.

Finally, we check if our queryPropValue is there (because, after all, maybe you’re just interested in z-index, not z-index: 10 ). If it is, let’s set a value to our map.

We’ll make the key of our item the CSS selector, which is the selectorText. Then we’ll make the value a mashup of the property name and the property value. It won’t be a duplicate of what’s written in the actual stylesheet — just what’s important for search purposes.

if (style) {
        const propertyValue = style.getPropertyValue(queryPropName);
        const hasPropValMatch = queryPropValue && propertyValue.indexOf(queryPropValue) !== -1;

        if (queryPropValue && hasPropValMatch) {
          properties.set(selectorText, `${queryPropName}:${propertyValue}`);
        }

        if (!queryPropValue && propertyValue) properties.set(selectorText, `${queryPropName}:${propertyValue}`);
}

Finally, stitch it all together

Once we’ve done all this, let’s make sure that we return those properties we’re setting values in:

function queryCSSByProperty(queryPropName, queryPropValue) {
  const styleSheets= document.styleSheets; 
  const properties = new Map();

  if (!queryPropName) return properties;

  Object.values(styleSheets).forEach(styleSheet => {

    try {
      const rules = styleSheet.cssRules;

        Object.values(rules).forEach(rule => {
          const {style, selectorText} = rule;

          if (style) {
            const propertyValue = style.getPropertyValue(queryPropName);
            const hasPropValMatch = queryPropValue && propertyValue.indexOf(queryPropValue) !== -1;

            if (queryPropValue && hasPropValMatch) {
              properties.set(selectorText, `${queryPropName}:${propertyValue}`);
            }
            if (!queryPropValue && propertyValue) properties.set(selectorText, `${queryPropName}:${propertyValue}`);
          }
      });
      } catch (err) {
        console.log(err);
      }
    });
    return properties;
}

Final Result?

You should be able to run queryCSSByProperty('z-index') on this page and discover that there's over 60 CSS rulesets using z-index. Quite nicely though for dev.to, they're managing most of them with CSS custom properties.

A function like this will help you not be that person who’s picking random numbers out of a hat. In fact, a function like this might be a useful way to make sure your element is always lastzIndex + 1.

Of course, this could have other uses, too, beyond z-index. But you get the idea.

BTW, the final version of this is a gist, if that’s what you’re looking for.

The Symbology of JavaScript Symbols

Paceaux — Mon, 30 Dec 2019 19:52:03 +0000

There have been two things that have appeared in newer versions of JavaScript that I haven't understood: Symbols and Iterators.

When it comes to code I have to learn by doing, no amount of reading Mozilla Developer Network was going to help me understand Symbols.

So I finally decided to stop reading articles, crack open a JavaScript console, snap in to a Slim Jim, and figure out what Symbols are all about.

And now that I think I understand some basics, I want to share them with you.

JavaScript Symbols are a new primitive

If you read the entry on the Mozilla Developer Network it'll tell you right there at the beginning:

Symbol is a primitive data type

That's a big deal. The Symbol is right up there with String, Boolean, Number, undefined, and nobody's favorite, null.

Primitives are a bit like the protons and electrons; you mix and match them to make atoms (objects). Put enough of them together and you can make a ~~dying~~ Death Star (it's called NPM).

So the fact that I've been ignoring Symbol is bad; I've been ignoring a fundamental piece of how we build in the JavaScript universe.

Symbols are unequivocally unique

This is something that's easy to read on (digital) paper, but maybe hard to accept in practice: When you create a Symbol it is unique. Forever and for-always.

let ianMalcom = Symbol('Ian Malcom');
let ianMalcomClone = Symbol('Ian Malcom');

const ianMalcomWasWrong = (ianMalcom == ianMalcomClone); // false
const michaelCrichtonWasWrong = (ianMalcom === ianMalcomClone); // false

Not only is every symbol ever created unique, you can't even compare two symbols with the same "value".

Symbols don't coerce

Remember everyone's favorite gag, that old 1 + '1' == '11'? Or [1] + 1 == 11? I know you remember the one about the boolean throwing the baseball at the window: true * ([1] + [1]) == 11

Those are all fun type coercion games that we hope never come up in job interviews.

Well guess what?

Symbol don't play like that.

const zildjian = Symbol('1');
zildjian + 1; // TypeError: can't convert symbol to number
zildjian + '1'; // TypeError: can't convert symbol to string
!!zildjian; // true. Huh.

So Symbols don't give into our concatenation shenanigans.

So what are Symbols actually good for?

What good is an absolutely unique primitive that doesn't give into JavaScript's Weird Coercion Tricks®?

Symbols are Secret(ish)

Let's suppose some sort of library that we're bringing into our codebase. We're making some dinosaurs, but maybe we don't have that bit about getting dinos to reproduce.

The old school way might be something like this:

import dinosaurs from 'dinosaurs';

const tRex = Object.assign(
  {
    reproduce() {
     return null;
    }
  },
  dinosaurs);

This seems fine, except ... it's easy to create a scenario where everyone dies:

// Step 1. Let's create a bigger t-rex
const megaTRex = Object.assign({}, tRex);

// Step 2. t-rexes get lonely because they have no one to hug
megaTRex.reproduce = function () {
  return this;
};

// Step 3. You know what no one asked for? Velociraptor + t-rex
const velociTrex = Object.assign(velociraptor, megaTrex);


// Step 4. Hey, turns out we've got this .reproduce function, WCGW?
velociTrex.reproduce(); // returns zero rescues from Chris Pratt

Sometimes, when we add a feature on to an object, we want it just for that object. We don't want others to see what we've been doing and to use it themselves.

Symbol is a secret password

What if we created our own private way to help that megaTRex reproduce? One that no one else could know about?

Let's go back to our megaTRex and try again. But this time, we'll use a Symbol as the key for our object (this is called a symbol-keyed property):


const megaReproducer= Symbol('reproduce');

const megaTRex= Object.assign({}, tRex);

megaTRex[megaReproducer] = function () { 
  return this;
}

Guess what? You're not going to find that on the object! If you trying to find this megaReproducer with for-in, you're not going to find it.

In the Firefox console, you'll see something like this if you inspect the object:

You can see that it's there, but you're not going to find it in any of your typical approaches you might think of for finding properties on an object or its prototype.

None of these will reveal a property-keyed Symbol:

for (property in megaTRex) {
 console.log(megaTrex[property])
}

Object.keys(megaTRex).forEach(property => console.log(propertyName));

for (let [propertyName, value] of Object.entries(megaTRex)) {
  console.log(propertyName, value);
}

You'll have to use Object.getOwnPropertySymbols if you want to find the symbols living on an object. So it's not like Symbol-keyed property is invisible; it's just chilling on an island you weren't thinking of looking on.

But, looking is one thing. How do you access it?

It takes a symbol to know a symbol

You might be able to inspect an object and see that a symbol is a key on it. But you don't have any way to access it — unless you have the symbol you used to create it.

What this means is that we get a good fair amount of privacy and protection for our objects. The Symbol is a way to extend an object, maybe even an object you don't really "own" -- and do it in a safe way where you don't open up risks of abuse elsewhere in your runtime.

The only way this megaTRex is going to make a baby T-rex is if you have that exact Symbol:

const newMegaTRex = megaTrex[megaReproducer]()

This is especially practical in cases where we are importing from a library and exporting code to be used elsewhere:

import {tRex} from 'dinosaurs.js';
const keyToReproduction = Symbol('frogs');

tRex[keyToReproduction] = function () {

    return this;

}

export const megaTRex = tRex[keyToReproduction]();

We've safely extended our library and exported a product after that extension — without exporting the ability to access that function.

Symbols don't collide

Going back to the fact that a Symbol is absolutely unique. This turns out to be handy for another reason: it prevents accidental overwrites.

Let's step away from uncited Michael Crichton fan-fiction for a minute and talk through a slightly more practical example: extending the console.

Let's suppose we're dealing with a particularly fickle library, and we need to do a lot of logging.

Maybe we want to have a nice formatted console.log, because we're developers and of course we'd want this.

let pretty= Symbol('logPretty');

console.log[pretty] = function (message, styles= 'font-size: 1.5em; color: #bad') {
  console.log(`%c ${message}`, styles);
}

Cool. Because we've used a Symbol for extending the console, we're safe from any browser ever adding console.log.pretty in the near or distant future.

This is a great way to extend globals in the browser!

As long as we've got access to that pretty variable, we can write console.log[pretty]('Hey there') and see all the delightful console messages we want.

Just, uh, remember that you need that exact symbol. Which means...

Avoid Collisions with `const`

You may have noticed that I used let in my example above.
This is bad. Don't do that.

// uh oh. I reassigned my variable
pretty = Symbol('newPretty');
console.log[pretty] = function (message, styles = 'font-size: 3em; color: red') {
  console.log(`%c ${message}`, styles)
}

Now I have no easy way to get back my old "pretty" symbol.

I should've used const so my variable couldn't be reassigned. That was dumb.

Retrieving lost Symbols

How can I ever outshine other developers on my team without this precious symbol? Will I ever be able to get my long lost symbol back, so that I can make my logs pretty again?

Of course. I need to use getOwnPropertySymbols and quit being melodramatic:

const [oldPretty, newPretty] = Object.getOwnPropertySymbols(console.log);

Which reminds me...

Describe your Symbols

Wen you create a Symbol, it doesn't need a 'descriptor'. You can make plain ol' ordinary undescriptive Symbols:

const prettyBad = Symbol();

Much like cloning dinosaurs, this is probably a bad idea.

If you're using Symbol-keyed properties, and you need to use getOwnPropertySymbols, that descriptor is going to be the key to figuring out which is the prettiest log of them all:

I should add, by the way, that while you could use the same descriptor for every symbol-keyed property, that doesn't mean you should:

Symbols don't `stringify()`

JSON.stringify ignores Symbols completely.

import { dna } from 'dinosaurs';

const reproduction = Symbol('frogs');
const howToCloneDinosaurs = {
  richDudes: 1,
  newman: 0,
  cynicalMathematicians: 1,
  paleontologists: 2,
  island: 'isla nublar',
  lawyers: Infinity
};

howToCloneDinosaurs[reproduction] = dna;

I think this is a Good Thing™.

It prevents cloning

The most common way to deep-clone objects in JavaScript is with JSON.parse(JSON.stringify()).

A Symbol-keyed property is a simple and terse way to put a property on an object that you don't want to be cloned.

Of course, you can also use the always-clunky, super verbose, always-have-to-look-it-up Object.defineProperty() to make a property unJSON.stringifiable:

Object.defineProperty(howToCloneDinosaurs,'reproduction', {
 value: dna,
 enumerable: false
});

Object.defineProperty might make sense when we need to define a lot of things about a property. But if we want an easy way to make sure the property and its value aren't cloned, Symbol seems the way to go.

There's some built-in Symbols

Turns out, there's a slew of "built-in" symbols that exist. I won't list them all here, but there's a few that catch my eye as particularly interesting:

Symbol.iterator
Symbol.asyncIterator
Symbol.split
Symbol.toStringTag

The reason these are of interest to me (and should be of interest to you) is because these are "Symbol Keys" that allow us to define our own behaviors on objects. These behaviors didn't used to be available to us, but now they are!

Create a String that iterates by word

for of is kinda awesome, but it only works on things that are iterable (more on what that means in another post.

Let's use Symbol.iterator and make a string iterable:

function WordString(text) {
    const string = new String(text); // make explicit object
    const words = string.split(' '); // split by spaces
    let wordIndex = 0;

    string[Symbol.iterator] = function* stringIterator() {
      while (wordIndex < words.length) {
       yield words[wordIndex++]
        .replace(new RegExp('[!.?]', 'g'),''); // remove any punctuation
      }
    }

    return string;
}

Ignore the * and the yield for right now. Those are things for iterators. Just dial in on the fact that we used a global Symbol key (Symbol.iterator) and we used it to make something that wasn't iterable ... iterable.

Look at what we can do with this fancy WordString now:

Create an Honest Array

If you read my previous post on arrays you might recall that there's an implicit and explicit undefined. Maybe you're disappointed that arrays are liars sometimes.

Let's use Symbol.species to tell us that this is still an array. And then we'll throw a generator function on that array and define what for of will actually return:


class TruthyArray extends Array {
    constructor(value) {
        super(...value);  
        this.value = [...value];
    }
    get [Symbol.species]() {
      return Array;
    }
    *[Symbol.iterator]() {
      let itemIndex = -1;
          while (itemIndex < this.value.length ) {
              if (this.value[++itemIndex]) {
                  yield this.value[itemIndex];
              }
          }
      }
  }

Again, ignore the * and the yield. That's for another time.

The greater point is that Symbol has some built-in "keys" that we can add to an object to extend functionality.

The Recap

Dev.to says this is a 9-minute read. That's like 2 cigarette breaks or one visit to the bathroom after a tryst with a holiday cheese plate.

I don't want to keep you much longer or someone will be looking for you... and, "I was reading an article about Frank's Jurassic Park-inspired JavaScript Symbol fan fiction," is not how you want to explain yourself. You're a professional.

Symbol is a primitive. It's worth knowing because it's in the guts of how everything works in JS now.
Symbols are unique and it's best not to think about how they're unique. But they are.
Symbols don't coerce into other things. They laugh in the face of your + jokes.
You can and probably should be making property-keyed symbols.
Symbol-keyed properties guarantee you'll never have collision; that makes it the perfect way to extend browser built-ins or libraries.
Symbol-keyed properties are hidden-ish. JSON.stringify ignores them, for-in, Object.keys ignores them, too. You have to know you're looking for a property-keyed Symbol.
You need your Symbol to access a symbol-keyed property, so use const for defining it, or otherwise make sure you throw descriptors on that sucker lest it become lost forever and foralways.
It's not just about Symbol. The Symbol is how we access utilities previously unavailable to us on objects.

Shoutouts

Thanks to Isabela Moreira and Alex Klock for providing technical review of this.

Kyle Simpson proved I STILL don't know JavaScript (arrays)

Paceaux — Fri, 06 Dec 2019 17:26:49 +0000

If you've never read Kyle Simpson's fantastic series, You Don't know JS, I'd first encourage to stop reading this, go read that , and then come back. It might take about six weeks, but that's fine. I'll wait.

...
...
...

I see you came back. Great. Feel like you know JavaScript now? You sure? Go back and read it again. I'll wait. This post isn't going anywhere.

...
...
...

Feel like you really know JS now? Fantastic. Let's talk about that simplest of data structures, the array, and what I didn't know after reading that book series four times.

JavaScript, I thought I knew you...

First I want to point you to this twitter thread where, in the third tweet in the series, Kyle makes this statement:

just for clarity sake, this is what I find surprising...

Now, I looked at that image and thought, "this makes sense. But... why does it make sense?"

The more I tried to think about why it made sense, the more I realized I didn't know JavaScript.

First, a primer on making arrays

There's a few different ways to make arrays in JavaScript. They amount to, "you can instantiate them with data, or without data".

Instantiating with data

Sometimes we need to write an array with data already in it. It's not uncommon to do this when you don't expect that list to really change after you declare it. So there's two ways we instantiate that array:

Using the `Array` constructor

const mistakes = new Array('my liberal arts degree', 'eating 15 slim jims')`

This is considered weird and generally a bad practice in JavaScript. I'll explain why in a bit.

Using the Array Literal

const moreMistakes = [tequila', 'Michael Bay\'s TMNT movie'];

This is the more common approach that I hope most of us are using at home.

Instantiating without data

In cases where we're moving data from one data structure to another we often declare an empty array and then modify it.

An extremely common pattern is declaring the empty array and then pushing to it:

const moreFutureMistakes = [];

moreFutureMistakes.push('TMNT sequels')

But if you want to be that person, of course you can use the array constructor:

const moreUnusualMistakes = new Array();

moreUnusualMistakes.push('what you\'re going to see next');

Weird ways to instantiate arrays

I don't think I've ever really seen these in the wild, but they've always been there in the back of my mind. Kind of like the Hawaii 5-0 theme song. It's not really doing anything in my brain other than sitting there. Making sure I don't forget it.

One of the only things I remember from my C++ class was that arrays had to have sizes. And I didn't know why. I still don't know why. (answer:somethingSomething[memory])

So three weird ways of instantiating arrays involve setting the size of it up front:

const superSizeMe = [];
superSizeMe.length = 3; // SURPRISE! Length is a setter

const preSized = new Array(3); // "This won't confuse anyone," said no one ever.

const commaSized= [,,,]; 

const isWeirdButTrue= (superSizeMe.length === preSized.length === commaSized.length);

If you were wondering why it's considered bad practice to use the Array constructor, now you know. It's because if you give it exactly one argument, and that argument is an Integer, it will create an array of that size. So the array constructor could get unexpected results when dealing with numbers.

And it's not like any of the other approaches are remotely close to best-practice, either. They're all the strange practices of someone who's maybe a little too curious for their own good or perhaps wondering if the trickster-god Loki is in fact alive and designing programming languages.

Weird Instantiations and Weird ways to set data result in weird results totally expected behavior.

Now we're caught up and back to Kyle's tweet about how weird this is:

[,,,3,4,,5].forEach(x=>console.log(x));
// 3
// 4
// 5

Ok, let's agree that comma-instantiated arrays is weird.
Ok. It logged... 3,4,5

This is fine. Everything's fine. those other slots must be undefined or unavailable.

for (let x of [,,,3,4,,5]) { console.log(x); }
// undefined 
// undefined
// undefined
// 3
// 4
// undefined
// 5

Hold up....

What's in those "weirdly instantiated arrays" ?

Let's take a step back and look at these pre-sized arrays:

const myRegrets = new Array(3);
const moreRegrets = [,,,];
const noRegerts = [];

noRegerts.length = 3;

If you're using Firefox, crack open the console, run this, and take a look at those arrays.

You might see something like:

Array(3) [undefined, undefined, undefined]

But is that array really filled with three `undefined`?

No. Not it is not. That's what Kyle Simpson is aptly pointing out. If you loop through these "pre-sized" arrays, and try to log the value, you will not get a log:

const myRegrets = new Array(3);
myRegrets.forEach((regret, regretIndex) => {
  console.log(regret, regretIndex);
});


for (regretName in myRegrets) {
 console.log(regretName, myRegrets[regretName]);
}

So, the first big takeaway here is that a pre-sized array, or an array created with comma/slots, doesn't have a value in those slots.

myRegrets is not an array with 3 undefined. It's an array with three slots of nothing.

To further prove this point, add an actual undefined to the third slot:

const myRegrets = new Array(3);
myRegrets[1] = undefined; 
myRegrets.forEach((regret, regretIndex) => {
  console.log(regret, regretIndex);
});


for (regretName in myRegrets) {
 console.log(regretName, myRegrets[regretName]);
}

You got a log, didn't you? Just one, right?

Double-you Tee Eff

There's an implicit and explicit `undefined` in Arrays

This is what I think Kyle is talking about here.

When we do these weird Array tricks where we pre-size it, or we comma-slot it (e.g. [,,undefined]), JavaScript isn't actually putting values in those slots. Instead, it's saying the slots exist ... kinda.

If something exists, but has no value, we have a name for that:

undefined

const myRegrets = [,,undefined];
const youWillRegretThis;

myRegrets[0] === youWillRegretThis; // true, so very true

But I call this "implicit undefined" because this doesn't get logged in any looping that we do. Not forEach, neither for - in, nor map and its buddies will log a slot that has no value; i.e. implicitly undefined;

You could also call this "undeclared" if you don't like "implicitly undefined".

Explicit `undefined` must take up memory

When you loop over an array with an explicit undefined , it must be taking up actual memory. And that's why it gets logged:

const myRegrets = [,,undefined];

myRegrets.forEach((regret, regretIndex) => {
  console.log(regret, regretIndex);
});
// will log 3

for (regretName in myRegrets) {
 console.log(regretName, myRegrets[regretName]);
}

// will log 3

So just remember this, kids. There's an implicit undefined and an explicit undefined when it comes to arrays.

This probably won't be a thing you trip on any time soon unless you merge arrays.

Or use for of...

Wait. for of?

yes.

(Double-you tee ay eff)

`for - of` is the only looping mechanism that doesn't care about implicit or explicit undefined.

Again, think of "implicit undefined" as meaning, "undeclared":


const myRegrets = [,,undefined];


let regretCounter = 0;

for (regret of myRegrets) {
 console.log(regret, regretCounter++)
}
// undefined 0
// undefined 1
// undefined 2

Why did it log all three?

I don't know for certain, but I have a theory that a much smarter person than I needs to investigate.

The for of pattern implements an iteration protocol

My theory here is that the iteration protocol on arrays behaves something like what's shown from the examples page:

function makeIterator(array) {
    var nextIndex = 0;

    return {
       next: function() {
           return nextIndex < array.length ?
               {value: array[nextIndex++], done: false} :
               {done: true};
       }
    };
}

if for - of implements something like this under the hood, this will iterate by index, not property (and arrays are really just objects with properties that are numbers. kinda).

So, back to what we call a thing that exists but has no value. You know the one. Our old friend. The one we never invite to parties but he shows up anyway? Remember him?

undefined

I'm really starting to not like that guy. He weirds me out.

TL;DR

The .length property of an array isn't the same as saying, "these many slots have value"
Arrays can have "implicit undefined", and "explicit undefined", depending on whether the space really has a value and "implicit undefined" is more like, "undeclared"
If you don't create arrays in weird ways, or do weird things with arrays, you'll likely never encounter this
If you are that trickster god Loki, or a fan, and choose to create arrays in weird ways, or manipulate them weirdly, you may need to use for of to get the most consistent result while looping.

JavaScript makes a lot of sense early in the morning. Not late at night.

[Edit: Some additions]

A few comments on this post made me do some research and testing that some may find useful. This was already a long read, so unless you're camped out in a bathroom stall on account of a late-night binge on cheese, or you're otherwise really interested in talking about specifications, you can skip this stuff.

Are there array properties that are simply being set as not enumerable?

I don't think so.

I skimmed through some ECMA specs to see if this behavior is defined anywhere.

The specs say that array elements without assignment expressions are not defined

Section 12.2.5 says

Whenever a comma in the element list is not preceded by an AssignmentExpression (i.e., a comma at the beginning or after another comma), the missing array element contributes to the length of the Array and increases the index of subsequent elements. Elided array elements are not defined.

So if you have [,,'foo'], those array elements after the comma that don't have some sort of expression are "elided".

Also worth noting is that the specs say that ['foo',] does not contribute to the length of the array.

Also also worth noting is that I haven't yet found if pushing values to a random index above the length counts as elision. e.g.:

const gapped = [];
gapped[2] = "please mind the gap";

The specs don't seem to state that array elements are created but not enumerable

Step 8 of section 22.1.1.3 describes how an array is created:

Repeat, while k < numberOfArgs
a. Let Pk be ! ToString(k)
b. Let itemK be items[k]
c. Let defineStatus be CreateDataProperty(array, Pk, itemK)
d. Assert: defineStatus is true
e. Increase k by 1

Pk is the key (which is an index) and itemK is the value.

If the JavaScript engine is following this algorithm, an item, regardless of its value, gets passed into the CreateDataProperty function/method/whatever.

The question is, "does the first slot in [,,'foo'] constitute being an item? 12.2.5 says no. (I think)

But is there a chance `CreateDataProperty` is creating a property making it non-enumerable?

If you read in section 7.3.4, it doesn't give any logic or condition where the enumerable property in the descriptor . Steps 3 and 4 set the property to be enumerable:

Let newDesc be the PropertyDescriptor { [[Value]]: V, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]:true }.

Return ? O.[DefineOwnProperty]

I haven't read through all the specification has to say about arrays. But this seems further suggest that these "empty slots" are really empty.

What about the `in` operator. Will it find these empty slots?

No it will not!

const slotted = [,,'one'];
let i = 0;

while (i < slotted.length) {
 if (i++ in slotted) {
  console.log(`${i - 1} is in the array`);
 }
}

This will log exactly once, displaying 2 is in the array in your console.

If you have an explicit undefined, howeverconst explicit = [undefined, undefined, 'one'] , it will log three times.

STL;SDR (Still too long, still didn't read)

First, let me caveat everything by telling you I'm way more qualified to talk to you about French Existentialism than JavaScript. The likelihood that all this is wrong is pretty high.

Based on my understanding of the specifications, "implicit undefined" is a somewhat valid-ish way to describe a "slot" in an array that has no value.

Except, of course, there's not really even a slot. There's not even the idea of a slot. A slot does not exist without a value. (#Existentialism)

As Kyle Simpson points out there is a difference between undefined and undeclared but JavaScript doesn't always give you messaging that makes it clear which is which.

This "implicit undefined" is more of an existential problem where we only have so many ways to describe Being and Nothingness.

const existentialCrisis= [,undefined,'Waiting for Godot']`;
console.log(typeof existentialCrisis[1]); // undefined
console.log(typeof existentialCrisis[0]); // undefined