DEV Community: Pelle Wessman

TypeScript 5.0 for JavaScript devs

Pelle Wessman — Mon, 20 Mar 2023 15:57:12 +0000

The TypeScript 5.0 release brings a good amount of news for us who use it with JavaScript / JSDoc.

This time around we get two whole new keywords, @satisfies and @overload, and they are a big step towards feature parity with TypeScript itself.

On top of this we get some other goodies as well, which I'll go through in the end of this post.

`satisfies` – non-lossy type validation

When we have a piece of data that we want to ensure is of type Foo we do eg:

/** @type {Foo} */
const abc = data;

If Foo has a property .type that is 'car'|'bike', then we will not know which of the two abc will have, no matter if we know that data.type was bike.

We can now instead write:

/** @satisfies {Foo} */
const abc = data;

That will ensure that we simply ensure that abc satisfies the type of Foo, it will not make us lose any of the details of data.

For more info, check out the announcement post at the TypeScript blog.

`@overload` – enabling function overloading in JS

The announcement post at the TypeScript blog summarised this one well:

Each JSDoc comment with an @overload tag is treated as a distinct overload for the following function declaration.

In other words, we can now easily specify when eg. a second argument can or can not be specified to a function.

This is something that has been possible in TS for a long long time, now finally we can do it in JS as well. Great for those few times where it can make the code much more readable.

For more info, check out the announcement post at the TypeScript blog.

Other notable news

The new --allowImportingTsExtensions is great for when we need to specify a file extension when importing (I'm looking at you ESM) and you need to import a .d.ts file (a useful thing when it gets too verbose or hard to write your types in JSDoc). Only allowed when --noEmit or --emitDeclarationOnly is enabled, which is true for all JS projects.

Also: Support for multiple files in extends can be helpful, especially when sharing a common config with TS projects.

Conclusion

I'm in love with @satisfies and will use it plenty. I will probably also add --allowImportingTsExtensions to a future version of my shared @voxpelli/tsconfig configuration + may perhaps restructure it a bit eventually to enable use with multiple extends.

Head on over to voxpelli/types-in-js and read more about using types in JS and share your favorite additions lately 🙏

installed-check 5.0.0: Robustness galore

Pelle Wessman — Sun, 14 Nov 2021 18:56:43 +0000

A few seconds ago I shipped version 5.0.0 of installed-check CLI and its companion installed-check-core module, delivering a more robust, more well tested and all-round better tool.

So what does `installed-check` do?

It check's that your project's engine.node is equal to, or a subset of, of that of your dependencies.

What's new?

Replaced old @voxpelli/semver-set, a fork of another project, with a brand new rewritten from scratch 3.x version of it.

The new @voxpelli/semver-set is well tested and hardened – all to ensure better intersection calculations of semantic versioning ranges – essential for calculating engine.node compatibility. Eg. ^10.17.0 || >=12.0.0 and >=8.0.0 now properly calculates.

The new @voxpelli/semver-set also fixes an issue with the license of the former module. Since its a full rewrite I could pick a license myself, so it's now under MIT.

Other news for the installed-check modules includes a swap from the non-standard VError to my pony-cause pony-fill for the now standardised Error Causes

installed-check in general now also has much more tests and have fixes for issues those tests uncovered, making for a much more robust experience going forward.

How do I get started?

Add it to your project:

npm install -d installed-check@latest

Then add it (early) to the tests in your package.json:

"scripts": {
  "test": "installed-check"
}

A more full-featured example can be found in eg. my list-installed project.

Happy compatibility checking! 🥳

TypeScript 4.5 adds JSDoc template tag defaults

Pelle Wessman — Tue, 09 Nov 2021 17:50:32 +0000

TypeScript 4.5, which is currently a release candidate, includes an exciting new feature for us types in js JSDoc users:

Defaults for template tags, microsoft/TypeScript#45483: @template [T=string]

I found this through when looking for a way to void T defaulting to any when no value was given in this code:

/** @template [T=undefined] */
class ErrorWithCause extends Error {
  /**
   * @param {string} message
   * @param {{ cause?: T }} [options]
   */
  constructor (message, { cause } = {}) {
    if (cause) {
      /** @type {T} */
      this.cause = cause;
    }
    // ...
  }
}

Now it gets set to undefined when no value is provied and my type-coverage got closer to 100%.

And it properly compiles to:

export class ErrorWithCause<T = undefined> extends Error {
    constructor(message: string, { cause }?: {
        cause?: T;
    } | undefined);
    cause: T;
}

I will push this new code to my pony-cause module very soon, just wanted to write this up first 🥳

Originally posted as a discussion in the types-in-js community:

// Detect dark theme var iframe = document.getElementById('tweet-1458128109836935168-226'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1458128109836935168&theme=dark" }

Open source and taxes: A Swedish perspective

Pelle Wessman — Wed, 29 Sep 2021 17:27:58 +0000

Open source and taxes seems to be a weird beast in at least Sweden and perhaps elsewhere as well. Let's dig into how it seems to work.

The basics

If I receive a donation for an open source project of mine, then the Swedish tax authority says that I should tax that as income as there's a reasonable expectation of a service in return.

If I as a company decides to donate to an open source project, then that donation is not tax deductible as it is a voluntary donation and hence not required for my company to acquire its income.

The result: Both my company and the receiver has to pay taxes on the same money, making a taxes on taxes kind of situation – expensive.

Lets do the math: Best case scenario

If...

The giver is a limited company ("aktiebolag", the company itself pays taxes on its profits)
The receiver is not paying the Swedish high income tax
The receiver lives in the municipality with the lowest local taxes
The receiver declares the income as from a hobby ("hobbyinkomst")

...then, what is left of $100...

After the company has paid taxes: $100 * (100% - 20.6%) = $79.6
After the receiver has paid "egenavgifter": $79.6 * (100% - 29%) = $79.6 * 71% ≈ $56.52
After the receiver has paid income tax: $56.52 * (100% - 29.18%) = $56.52 * 70.82% ≈ $40.03

...is just around $40

40% of the money that the company giver originally used for the donation actually got received by the recipient.

Lets do the math: Worse case

If...

The giver is a personal company ("enskild firma", the owner pays taxes on its profits)
The owner of the giving company as well as the receiver, both earns enough money to pay high income taxes (an additional 20%)
Both lives in a municipality with average local taxes
The receiver still declares the income as from a hobby ("hobbyinkomst")

...then, what is left of $100...

After the company has paid "egenavgifter": $100 * (100% - 29%) = $71
After the company has paid taxes: $71 * (100% - 32.27% - 20%) = $71 * 47.73% ≈ $33.89
For the receiver, after paying "egenavgifter": $33.89 * (100% - 29%) = $33.89 * 71% ≈ $24.06
For the receiver, after paying tax: $24.06 * (100% - 32.27% - 20%) = $24.06 * 47.73% ≈ $11.48

...is just around $11.50

11.5% of the money that the company giver originally used for the donation actually got received by the recipient.

Lets do the math: The absolute worst case – circular/Reciprocal donations

Many of the donations in the open source space moves around within that space, being used to fund the receiver's donations to others. Many maintainers who receive also give donations, even reciprocally at times, and due to the above this can really cause issues with double taxation or more.

When money given can't be deducted from the ones received, then every step more and more money gets lost.

That's why companies can deduct their costs from their income, as the intention of the tax system is to only tax the profits a company make, not the full revenue they have.

If 60% gets lost per step, as in the best current scenario above, then out of $100 000 donated this much will be received after each step:

$40 000
$16 000
$6400
$2560
$1024

After five steps 99% of the money has evaporated away, making reciprocal donations or any kind of trickle-down effects on eg. sub-dependencies essentially impossible.

Only if donations given can be deducted from donations received can any kind of reciprocal donations or trickle-down effects be achieved.

Up until then, the only feasible strategy at all is to either be a receiver or to be a giver, never both. Though that doesn't rhyme with the open source spirit.

Lets do the math: How it should be, deductible donations

Then, what is left of $100...

For the company: Deductible, no taxes paid, all $100 is forwarded to the receiver
For the receiver, after paying "egenavgifter": $100 * (100% - 29%) = $71
Depending on whether high income tax is paid or not:
1. After only paying local municipal taxes: $71 * (100% - 32.27%) = $71 * 67.73% ≈ $48.09
2. After paying both local municipal taxes and state high income taxes: $71 * (100% - 32.27% - 20%) = $71 * 47.73% ≈ $33.89

...is roughly $48 rather than $40 and $34 rather than $11.50

In other words: A receiver paying high income taxes would get almost three times the money compared to the current worse scenario. A receiver who doesn't pay high income taxes would get at least 20% more than the current best case scenario.

But how to approach donations here and now?

Currently the better approach for the "giver company" is to buy something from the receiver which could be required for the "giver company" to acquire its income and therefore become a deductible expense.

Some examples of that are: Sign a support agreement, buy consulting hours, sign an SLA-style guarantee from something like Tidelift or perhaps ensure you get enough promotion back to essentially make it classify as an ad for you.

Tidelift is also a current fix for the challenge to the trickle-down effect, as they disperse money received to the entire dependency trees, not just to the topmost rockstar projects a project depends upon, but their dependencies and the dependencies of those and so on.

Though: I'm not a tax expert, so I can't give any here advice. These are purely some thoughts and ramblings of mine on a topic that I think many ignore, based on the response I got when I asked the Swedish tax authority a question on this.

I find it okay that received open source donations is classified and taxes as income, but then the reverse also have to be true – it then has to be a tax deductible expense for the giving company as well.

Currently it seems like the Swedish tax authority wants to both have the cake and eat it, taxing both, which isn't fair and isn't along the intent of the tax system.

I myself am available at Tidelift for companies who wants to support me and I'm available at GitHub Sponsors for people who want to sponsor me (as well as companies if it makes sense for them to give there, maybe it is tax deductible in some countries?).

How does it work in your countries? Any thoughts on my rumblings? Please leave a comment!

Originally published in an earlier version at LinkedIn.

Pony Cause 1.0: Error Causes

Pelle Wessman — Mon, 20 Sep 2021 15:35:53 +0000

Pony Cause is my new ponyfill and helpers for the new Error Cause tc39 proposal.

The ponyfill as well as the proposal aims to replace VError / NError with a standard mechanism for wrapping errors and improving error contexts.

How does it wrap errors?

The Error Cause proposals add a second argument to the Error constructor.

The new argument is a plain object with so far cause as its only defined key.

cause is intended to be the value of a caught error.

That way cause enables an Error of a higher level to reference one of a lower level error, adding context without sacrificing detail.

An example:

try {
  // ...
  throw new Error('ABC123 exception encountered in database "Foo"');
} catch (err) {
  throw new Error('Failed to save blog post', { cause: err })
}

The Failed to save blog post message provides a higher level context, it tells us what has happened, it tells us the impact.

The inner ABC123 exception encountered in database "Foo" message tells us why this happened, it tells us the cause.

So why wrap errors?

In classic JavaScript it has been an either or – either getting to know the impact or the cause, but never both Error:s (unless one has logged them separately or have used VError / NError).

The impact and cause provides the most value when paired with the other, and that's what Error Cause enables and what Pony Cause is is a ponyfill for and provides helpers for.

What does `pony-cause` add?

Pony Cause is consist of two parts:

A ponyfill in the shape of a ErrorWithCause class which mimics the new cause-supporting Error class.
A couple of VError-inspired helpers for working with error causes, ensuring that the added context becomes actually useful. These helpers also supports VError style causes on top of the new error causes, enabling a smooth transition from one to the other.

Which helpers does it add?

Anything else I should know?

Pony Cause is written in JS, typed with JSDoc, validated with TypeScript and have .d.ts / .d.ts.map generated by TypeScript. In other words: 100% typed in true Types in JS spirit.

It's a CommonJS module rather than ESM, to maximise compatibility here and now, as that's the point of a ponyfill.

It's licensed under the 0BSD license, a BSD/MIT-style license with the requirement for attribution removed.

Will there be native support?

Yes, it's recently been implemented in all three major browsers and V8 shipped native support a bit over a month ago with eg. Node.js v16.9.0 and Deno v1.13 both having already shipped with that version of V8.

Though you still need a ponyfill or polyfill if you want to support older browsers or older Node.js versions.

Pony Cause also provides helpers which are useful no matter if you're using it with old environments or not it is a module that your toolbox needs 😉

How to use TypeScript 3.7 to generate declarations from JSDoc

Pelle Wessman — Mon, 07 Oct 2019 15:42:27 +0000

Background

While TypeScript for long has supported validating the types in ones javascript files, even reading ones JSDoc-comments, it hasn’t really worked that well for those who in turn wanted to use ones code.

By default TypeScript doesn’t read the JSDoc of any dependencies. One have had to set maxNodeModuleJsDepth to a higher value, which hasn’t been without some issues.

Issues range from having the required depth change over time due to nested modules in node\_modules, making it hard to guarantee that types has been read, and picking up weird JSDoc comments from other packages – JSDoc comments that has never been tested for correctness.

So, what about TypeScript 3.7? It introduces a way to create a type definition file from your JSDoc definitions. I decided to try it out on a project.

How-to

This is how I added it to a project which publishes a single index.js file, bunyan-adaptor:

1. Create a new tsconfig file

Add a new tsconfig.json with the sole purpose of generating your declaration. This way you can avoid getting declarations generated for tests and such.

I added a declaration.tsconfig.json containing:

{
  "extends": "./tsconfig",
  "exclude": [
    "test/**/*.js"
  ],
  "compilerOptions": {
    "declaration": true,
    "noEmit": false,
    "emitDeclarationOnly": true
  }
}

2. Add a npm script for generating the declaration

"declaration:build": "rm -f index.d.ts && tsc -p declaration.tsconfig.json",

3. (optional) Add a npm script for ensuring your declaration has been committed

"declaration:check": "git diff --exit-code -- index.d.ts",

4. (optional) Add a prepublishOnly npm script

"prepublishOnly": "npm run --silent declaration:build && npm run --silent declaration:check",

Or simpler, with the use of npm-run-all:

"prepublishOnly": "run-s declaration:*",

5. Profit / Party / 🦄 / 🤳

However you want to celebrate: This is the moment.

Run npm run declaration:build, commit the resulting index.d.ts and publish your module!

Note: Visual Studio Code could/will complain about your generated type declaration unless you tell it to use TypeScript 3.7.

Tell it by running the TypeScript: Select TypeScript Version... command when in eg. the type declaration file.

3 tricks to better handle npm modules

Pelle Wessman — Tue, 05 Jul 2016 17:10:00 +0000

Developing with npm modules isn’t just installing modules and then updating them. In a team environment you might not even know when a new module should be installed or when its version requirement has changed. This can cause lots of weird unexpected behaviors when the installed modules doesn’t match the expectations of the app – and that annoys and is a waste of time.

Here I’ll give you three tricks to avoid that. Tricks which I’ve begun to use over the years and which we’re currently using at my latest project, the development of the new sites for Sydsvenskan and HD.

1. Verify installed versions against package.json

When rapidly developing a new site, establishing the basic features etc, new modules gets added quite a lot. Often after a rebase one realize that one is missing a module after ones nodemon process suddenly crash with some unexpected weird error.

I created installed-check to solve that. To have a script I could run to check if my installed modules still fulfilled the requirements set out by the package.json or whether it was time to install some more. All checked locally, without any slow network lookups or such.

If any module were missing or were outside the version requirements it would exit with an error.

I then hooked that script into my npm test script and into husky (at postapplypatch and postmerge) so that whenever I pulled down new code or ran my tests it verified that my installation was up to date.

With that in place everyone in the team could stop worry about whether they were missing a module locally and we could all stop wasting time debugging issues that were due to changes in the package.json requirements. Happy developers!

2. Verify that package.json is in sync with actual module usage

While tests may pass just fine locally, if one doesn’t commit all the dependency requirements then it’s hard for them to pass anywhere else.

Likewise refactored code may work just fine, but one may not have realized that a removed require() was the very last one for a given module.

Therefore I always run dependency-check (which I now co-maintain) in my npm test. To ensure that uncommitted dependencies are caught early and that no extra modules are kept around and weighing down the project after they are no longer in use.

I also make npm test run before code is pushed remotely by setting up a prepush git hook using husky. That way neither I or anyone else in the team can accidentally push code with any such mistakes. (I’ve found prepush to work better for this than precommit – more pragmatic, with happier developers as a result)

3. Verify engine requirements of installed modules

How do you express what versions of node.js your library supports? There’s the engines field in package.json for that:

"engines": {
  "node": ">=5.0.0"
}

Simple. You know what engine you support and you politely tell others so that they easily can find out as well.

But how do you detect when others update their requirements and how do you avoid that you get dependencies that have stricter engine requirements than you yourself have? Surely there must be able to verify that automatically?

Check out the just released 2.0.0 version of installed-check: It has a new optional flag, --engine-check, that makes it also check the engine requirements of all of the installed dependencies.

If the engine requirements of any installed dependencies doesn’t match yours, then an error will be returned along with a suggestion of a stricter engine requirement whenever possible.

By running that in your npm test you can easily early detect whenever an engine requirement change and either avoid the change altogether or move along with it and release a new major version yourself with the new stricter engine requirements. (Changed engine requirements are always to be considered a breaking change, which requires a new major version according to Semantic Versioning)

Only gotcha with this approach is that not all modules explicitly define their engine requirements in their package.json. By default installed-check ignores any such modules and doesn’t treat undefined engine requirements as an error. By setting either or both of the --verbose and --strict flags one can make it warn or throw errors whenever it encounters such a module though.

Example: Run all the tricks

Install the modules:

npm install --save-dev installed-check
npm install --save-dev dependency-check
npm install --save-dev husky

Set them up to run:

{
  "scripts": {
    "test": "installed-check -e && dependency-check . && dependency-check . --extra --no-dev",
    "prepush": "npm test",
    "postapplypatch": "installed-check -e",
    "postmerge": "installed-check -e"
  }
}

Then profit from a more solid dependency workflow and a more happy development team!