🏎️ feat: expose calculateForAST method

[bartveneman]

closes #17

• Exposes calculateSelectorNode next to the existing calculate function
• Adds static Specificity.calculateSelectorNode(selector: string) + tests
• Moved around some internals so calculateSelectorNode does not need to reference Specificity each time
• Agree on naming
• Check that /test/standalone is implemented correcty. I suspect the existing tests for calculate don't actually test it's implementation so I did mine a little different than the existing tests. Please double-check my work 😅. Also opened Question: are standalone tests correct? #24 for further discussion.

[bramus]

Apologies for the delay but only now I took a good look into this PR.

One thing I’m wondering is why calculateSelectorNode returns a plain object while calculate does return (an array) with Specificity objects. I would have assumed for both to return Specificity instances

[bartveneman]

~~The existing function already returned a single object, so I simply renamed it and exported it.

It does make sense to me however to keep this method as small as possible, because it's easy to integrate and mock for testing.~~

edit: interpreted your question incorrectly

For my use case I generate sometimes over 10,000 Specificity instances, each with a small enough footprint. Separating instantiating the Specificity object felt light the right thing to do, to keep more of the 'business logic' in the more customer-facing calculate method. On the other hand, I don't have very strong feelings about this, so happy to revert that part.

[bartveneman]

My css-analyzer package has benchmarks enabled in CI and running it with the changes from this MR makes the analyzer 25-50% faster! projectwallace/css-analyzer#423 (comment)

(I don't necessarily trust the benchmarks blindly and ~50% is probably waaaay too much, but I'm very confident that it's faster because it's making a lot fewer function calls and memory allocations)

[bramus]

I did some local performance testing:

• Specificity.calculate(string) which passes a string into Specificity.calculate()
• Specificity.calculate(ast) which passes a pre-parsed AST into Specificity.calculate()
• Specificity.calculateSpecificityOfSelectorObject(ast) which passes a pre-parsed AST into Specificity.calculateSpecificityOfSelectorObject()

(This uses an unmodified package, all invocations return one Specificity instance – possibly wrapped in an array)

These are the results:

Specificity.calculate(string) x 404,178 ops/sec ±1.19% (96 runs sampled)
Specificity.calculate(ast) x 7,517,796 ops/sec ±1.52% (96 runs sampled)
Specificity.calculateSpecificityOfSelectorObject(ast) x 48,482,376 ops/sec ±0.94% (96 runs sampled)

What is interesting is that the simple check if (ast.type === 'Selector') in Specificity.calculate() is enough to slow things down by 85% (!). So yeah, exposing calculateSpecificityOfSelectorObject would definitely allow speeding things up.

As for the name, what about calculateForAST or maybe calculateForSelectorAST? I believe having the name AST in there is pretty clear to indicate what it’s about.

As for changing the return format (see https://github.com/bramus/specificity/pull/23/files#diff-b4fecae0a093d01e2d48a4410d338901e0e6bf09a6ef3b2a91c4dcf34b2cd61dR184), I would not do that as the package is meant to return Specificity instances.

I see no significant impact when I re-run all benchmarks when the functions return a simple object instead of a Specificity instance:

Specificity.calculate(string) x 411,932 ops/sec ±0.67% (91 runs sampled)
Specificity.calculate(ast) x 7,899,297 ops/sec ±0.28% (98 runs sampled)
Specificity.calculateSpecificityOfSelectorObject(ast) x 49,126,613 ops/sec ±1.63% (95 runs sampled)

(Yes there is a difference, but I don’t see a huge impact)

[bartveneman]

Excellent, excellent research! Shall I update the PR with these proposed changes? It'll solve my use case so I'm in favour and I'm happy to spend some more time on this if you want. 🙌

[bramus]

Please do. Afterwards I can commit the benchmarks too and then prepare a new release :)

(And apologies for the delay, should have looked into this much much sooner)

[bartveneman]

• Updated method name and signature
• Added static calculateForAST() to .d.ts because I forgot about that in the first round

[bartveneman]

Thanks for getting this across the finish line!