v3.0.10 contains breaking changes from v3.0.9

The version v3.0.10 added a string & {} to types that didn’t supported string making it a breaking change from v3.0.9:

import type { Property } from 'csstype';

// Fails in 3.0.9 but works in 3.0.10
const fontWeight: Property.FontWeight = 'anything'; // ok 'anything' is a string & {}
console.log(fontWeight)

This difference makes TS fail when NPM resolves to different (but semver compatible) versions of csstype:

import styled from 'styled-components'; // npm resolves to 3.0.9
import otherLibProps from 'other'; // npm resolves to 3.0.10

const Component = styled.div`
   /* fails string & {} is not assignable to fontWeight in 3.0.9 */
   ${otherLibProps}
`

While the previous situation is a red flag about NPM hoisting issues, it’s a possible situation that I’ve seen in repos with dependencies that internally use older csstype versions (like material-ui v4).

Possible solutions:

• The addition of string & {} to fontWeight was an error, because it makes the type more permissive and not assignable to type declarations of previous versions. Removing string & {} in that case should be harmless as it doesn’t affect the TS LSP auto-complete. This will not fix #125 in 3.x.
• Keep the string & {} but mark the version as v4.0.0: it will not solve the TS compilation issues, but at least the incompatibility is explicit and libraries using ^3. in the semver range will not catch the issue by surprise. This fixes #125 but in a 4.x version.

[dfernandez79]

@villasv I agree with you about SemVer. The definition of “breaking change” is vague, and the use of typings wasn’t even a use case of Node dependency handling.

However, type widening may break a previous contract:

type OldFontWeight = 'bold';
type NewFontweight = 'bold' | (string & {})

const oldWeight: OldFontWeight = 'bold'
const weight:NewFontweight = oldWeight; // ok

function doSomething(w:OldFontWeight) {}

/*
Argument of type 'NewFontweight' is not assignable to parameter of type '"bold"'
*/
doSomething(weight);

This scenario may happen if:

• You mix a library using 3.0.9 with another using 3.0.10 (the dependencies are pinned or not hoisted for other reasons).
• or you have a function that doesn’t use csstype but is compatible for a specific sub-set of values. (this scenario doesn’t involve dependency handling).

To me is about expectations: when you upgrade to a patch version, a CI compilation failure is unexpected.

My situation was exactly like that: I maintain a design system that uses csstype. I did an upgrade from 3.0.9 to 3.0.10. Patch upgrade. Everything is good. All tests passing.

Suddenly, I received notifications from other teams using the library: the CI compile step failed. The reason: their project use styled-components and consume values from the design system. A tagged literal is a function call:

import styled from 'styled-components';
import {style} from 'the-design-system';

// Type error: the styled-components tag literal function uses 3.0.9 (narrow type)
// style uses 3.0.10 (wide type)
const Comp = styled.div`
  ${style}
`

And unless you declare csstype as a peer-dependency, there is no guarantee that the package manager will not duplicate versions.

In a situation like this, v4 in the version number is a good indicator of what to expect. As a project maintainer, I know it’s hard to identify breaking changes. I wonder if we can reify the notion of “breaking change” with unit tests.

[lecstor]

@dfernandez79 thank you! I was getting close to figuring out what was going on but not sure I would have got there if I didn’t find this issue report.

finally resolved after a long day of head-scratching with resolutions for yarn 3 added to main package.lock.

  "resolutions": {
    "csstype@^3.0.2": "3.0.9"
  }

I was just trying to move a bunch of [mui@4] React components from an old working repo to a new monorepo. Even copying all deps and versions from the old repo didn’t avoid this issue of course and it was very unclear as to where the problem lay so I spent a lot of time looking at all the wrong things.