Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions BENCHMARKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -400,6 +400,7 @@ infrastructure failures.
| `pnpm benchmark:nested-fallbacks` | Deeply nested `var()` fallbacks (depths 16–512) | Regression-gating for recursion and opaque call handling |
| `pnpm benchmark:corpus` | Real-world expressions harvested from GitHub vs. `@csstools/css-calc` | Comparative reporting (not a gate) and practical equivalence |
| `pnpm benchmark:serialization` | Wide sums, products, and nested calls across serializers | In-process local profiling for serializer changes |
| `pnpm benchmark:token-ranges` | One long token list reduced as many small `[start, end)` ranges | In-process profiling of per-range block matching |
| `pnpm test:benchmark` | Unit tests for statistics, bootstrap, and schema validation | Verifying benchmark harness logic |
| `pnpm test:benchmark:simulation` | Monte Carlo calibration across adversarial noise scenarios | Verifying bootstrap empirical coverage |
| `node scripts/benchmark/benchmark-plugin.js` | PostCSS processing of generated stylesheets (no package script) | In-process local profiling of the adapter |
Expand Down
24 changes: 23 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,33 @@ All notable changes to this project will be documented in this file. See [commit

## Unreleased

### Features

- add `postcss-calc/reduce-tokens`, which reduces a `@csstools/css-tokenizer`
token list and returns token replacements. It never reads token source
offsets, so it works on lists edited after tokenization. `postcss-calc/reduce`
shares its implementation; its output is unchanged except as noted under
Bug fixes.

### Bug fixes

- A reduced value that would merge with a neighbouring token is now kept apart
by a space. For example, `foo(calc(1px + 1px)b)` becomes `foo(2px b)` instead
of `foo(2pxb)`, which reads as a different unit.
of `foo(2pxb)`, which reads as a different unit. This now also applies after
a `+`: `a+calc(25% + 25%)` with `unwrapSingleValue` becomes `a+ 50%` instead
of `a+50%`, which reads as a signed number.
- A bare `clamp()`, `min()`, `max()`, `round()` or other math function that
cannot be folded is no longer wrapped in `calc()`. For example,
`clamp(1rem, 2.5vw, 2rem)` stays as written instead of becoming
`calc(clamp(1rem, 2.5vw, 2rem))`.
- `unwrapSingleValue` no longer removes `calc()` from opaque values.
`calc(var(--a))`, `calc(env(x))` and `calc(attr(x px))` keep their `calc()`,
as the option only applies to fully resolved finite scalars.
- Division by zero is no longer distributed over a sum with mixed units.
`calc((2em - 2px) / 0)` becomes `calc(infinity * (2em - 2px))` instead of a
sum that is always `NaN`.
- A literal `-0` divisor keeps its sign: `calc(1 / -0)` now gives
`calc(-infinity)` instead of `calc(infinity)`.
- `reduceCalc` and the plugin no longer report the nesting-limit error for a
value nested more than 1024 levels deep that has no supported math function
outside `url()`, a string or a comment, such as `url(calc(1+2))((((…`. The
Expand Down
54 changes: 54 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,60 @@ const result = reduceCalc('calc(100% + var(--gap))', {
Unlike the PostCSS plugin, the standalone reducer does not show warnings
by default; provide `onParseError` and/or `onWarn` if you want diagnostics.

### Reduce a token list (experimental)

> **Experimental:** this API may change in a minor release.

`postcss-calc/reduce-tokens` reduces a list of `@csstools/css-tokenizer`
tokens directly, without converting to a string. It returns ordered,
non-overlapping `{ start, end, tokens }` replacements for
`tokens.slice(start, end)` and does not modify the list. Apply them from last
to first:

```js
import { tokenize } from '@csstools/css-tokenizer';
import reduceTokens from 'postcss-calc/reduce-tokens';

const tokens = tokenize({ css: 'calc(1px + 2px) 3px' });
for (const { start, end, tokens: next } of reduceTokens(tokens).toReversed()) {
tokens.splice(start, end - start, ...next);
}
// tokens now spell 'calc(3px) 3px'
```

`reduceTokens(tokens, options, start, end)` takes the same options as
`reduceCalc`, plus an optional index range to reduce. Things to know:

- **Edited lists are fine.** Source offsets (`token[2]`, `token[3]`) are
ignored, but the type, raw text, and parsed value (`token[4]`) must agree:
if you change a token's text, replace it with a token `tokenize` produced
from the new text.
- **Replacement offsets are local.** Replacement tokens are tokenized from the
replacement text alone, so their offsets count from 0 within that text, not
from their place in your list.
- **Replacements may add whitespace.** When a replacement would fuse with the
token before or after it, it starts or ends with a whitespace token. For
example, with `unwrapSingleValue: true`, `calc(1px)a` becomes `1px a`
rather than the single token `1pxa`. The tokens checked are the ones
next to the replacement in `tokens`, even outside `start`/`end`, so splice
the replacements into the same list you passed.
- **EOF tokens are ignored.** They never appear in a replacement and are
skipped when finding the token next to one.
- **Diagnostics** passed to `onParseError` and `onWarn` use text built from
the current tokens.

To skip tokenizing values that cannot contain a math function, check them
first with `hasPotentialMathFunction(value)`. It may return `true` for a value
with nothing to reduce, but never `false` for one that has something.

```js
import { hasPotentialMathFunction } from 'postcss-calc/reduce-tokens';

if (hasPotentialMathFunction(value)) {
// tokenize and call reduceTokens
}
```

### Standalone reducer options

#### `unwrapSingleValue` (default: `false`)
Expand Down
5 changes: 5 additions & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,10 @@
"./reduce": {
"types": "./types/reduce.d.ts",
"default": "./src/reduce.js"
},
"./reduce-tokens": {
"types": "./types/reduce-tokens.d.ts",
"default": "./src/reduce-tokens.js"
}
},
"files": [
Expand All @@ -37,6 +41,7 @@
"benchmark:nested-fallbacks": "node scripts/benchmark/benchmark-parser.js nested-fallbacks",
"benchmark:corpus": "node scripts/benchmark/benchmark-corpus.js",
"benchmark:serialization": "node scripts/benchmark/benchmark-serialization.js",
"benchmark:token-ranges": "node scripts/benchmark/benchmark-token-ranges.js",
"test:benchmark": "node --test 'test/unit/benchmark-*.test.js' test/unit/compare-parser-benchmarks.test.js test/unit/corpus-benchmark.test.js",
"test:benchmark:simulation": "node test/benchmark/statistical-simulation.js",
"benchmark:reanalyze": "node scripts/benchmark/compare-parser-benchmarks.js",
Expand Down
53 changes: 53 additions & 0 deletions scripts/benchmark/benchmark-token-ranges.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
// Token-range benchmark. One long token list is reduced as many small
// `[start, end)` ranges, the way an editor reduces each declaration in place.
// Each call pays for its own block matching, so the cost should grow with
// the range, not with the length of the whole list. In-process and single
// run: a profiling hint, not a gate (see BENCHMARKS.md).
import { tokenize } from '@csstools/css-tokenizer';
import { createReducer } from '../../src/reduce-tokens.js';

const SIZES = [2_000, 4_000, 8_000, 16_000];
const RANGE_TEXT = 'calc(1px + 2px)';
// The tokenizer appends an EOF token, which is not part of any range.
const RANGE_TOKENS = tokenize({ css: RANGE_TEXT }).length - 1;
const REPEATS = 3;

const reduce = createReducer();
const target = { warn() {} };

/** @param {number} count @return {import('@csstools/css-tokenizer').CSSToken[]} */
function listOf(count) {
return tokenize({ css: RANGE_TEXT.repeat(count) });
}

/**
* Reduce each range in turn and return the best of a few runs, in ms.
*
* @param {import('@csstools/css-tokenizer').CSSToken[]} tokens
* @param {number} count
* @return {number}
*/
function timeRanges(tokens, count) {
let best = Infinity;
for (let repeat = 0; repeat < REPEATS; repeat++) {
const start = performance.now();
for (let range = 0; range < count; range++) {
const from = range * RANGE_TOKENS;
reduce(tokens, target, from, from + RANGE_TOKENS);
}
best = Math.min(best, performance.now() - start);
}
return best;
}

console.log('ranges list-tokens ms (best of ' + REPEATS + ') ms per range');
for (const count of SIZES) {
const tokens = listOf(count);
const ms = timeRanges(tokens, count);
console.log(
String(count).padStart(6),
String(tokens.length).padStart(11),
ms.toFixed(2).padStart(18),
(ms / count).toFixed(5).padStart(14)
);
}
Loading
Loading