Add boolean expressions to the Sass parser

Author: Goodwine

pkg/sass-parser/CHANGELOG.md

@@ -1,6 +1,7 @@
 ## 0.2.5
 
 * Add support for parsing the `@supports` rule.
+* Add `BooleanExpression` and `NumberExpression`.
 
 ## 0.2.4
 

pkg/sass-parser/README.md

@@ -257,3 +257,13 @@ There are a few cases where an operation that's valid in PostCSS won't work with
 
 * Trying to add child nodes to a Sass statement that doesn't support children
   like `@use` or `@error` is not supported.
+
+## Contributing
+
+Before sending out a pull request, please run the following commands from the
+`sass-parser` directory:
+
+* `npm run check` - Runs `eslint`, and then tries to compile the package with
+  `tsc`.
+
+* `npm run test` - Runs all tests in the package.

pkg/sass-parser/lib/index.ts

@@ -27,6 +27,11 @@ export {
   StringExpressionProps,
   StringExpressionRaws,
 } from './src/expression/string';
+export {
+  BooleanExpression,
+  BooleanExpressionProps,
+  BooleanExpressionRaws,
+} from './src/expression/boolean';
 export {
   Interpolation,
   InterpolationProps,

pkg/sass-parser/lib/src/expression/__snapshots__/boolean.test.ts.snap

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`a boolean expression toJSON 1`] = `
+{
+  "inputs": [
+    {
+      "css": "@#{true}",
+      "hasBOM": false,
+      "id": "<input css _____>",
+    },
+  ],
+  "raws": {},
+  "sassType": "boolean",
+  "source": <1:4-1:8 in 0>,
+  "value": true,
+}
+`;

pkg/sass-parser/lib/src/expression/boolean.test.ts

@@ -0,0 +1,137 @@
+// Copyright 2024 Google Inc. Use of this source code is governed by an
+// MIT-style license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import {BooleanExpression} from '../..';
+import * as utils from '../../../test/utils';
+
+describe('a boolean expression', () => {
+  let node: BooleanExpression;
+
+  describe('true', () => {
+    function describeNode(
+      description: string,
+      create: () => BooleanExpression
+    ): void {
+      describe(description, () => {
+        beforeEach(() => void (node = create()));
+
+        it('has sassType boolean', () => expect(node.sassType).toBe('boolean'));
+
+        it('is true', () => expect(node.value).toBe(true));
+      });
+    }
+
+    describeNode('parsed', () => utils.parseExpression('true'));
+
+    describeNode(
+      'constructed manually',
+      () =>
+        new BooleanExpression({
+          value: true,
+        })
+    );
+
+    describeNode('constructed from ExpressionProps', () =>
+      utils.fromExpressionProps({
+        value: true,
+      })
+    );
+  });
+
+  describe('false', () => {
+    function describeNode(
+      description: string,
+      create: () => BooleanExpression
+    ): void {
+      describe(description, () => {
+        beforeEach(() => void (node = create()));
+
+        it('has sassType boolean', () => expect(node.sassType).toBe('boolean'));
+
+        it('is false', () => expect(node.value).toBe(false));
+      });
+    }
+
+    describeNode('parsed', () => utils.parseExpression('false'));
+
+    describeNode(
+      'constructed manually',
+      () =>
+        new BooleanExpression({
+          value: false,
+        })
+    );
+
+    describeNode('constructed from ExpressionProps', () =>
+      utils.fromExpressionProps({
+        value: false,
+      })
+    );
+  });
+
+  describe('assigned new', () => {
+    beforeEach(() => void (node = utils.parseExpression('true')));
+
+    it('value', () => {
+      node.value = false;
+      expect(node.value).toBe(false);
+    });
+  });
+
+  describe('stringifies', () => {
+    it('true', () => {
+      expect(utils.parseExpression('true').toString()).toBe('true');
+    });
+
+    it('false', () => {
+      expect(utils.parseExpression('false').toString()).toBe('false');
+    });
+  });
+
+  describe('clone', () => {
+    let original: BooleanExpression;
+
+    beforeEach(() => {
+      original = utils.parseExpression('true');
+    });
+
+    describe('with no overrides', () => {
+      let clone: BooleanExpression;
+
+      beforeEach(() => void (clone = original.clone()));
+
+      describe('has the same properties:', () => {
+        it('value', () => expect(clone.value).toBe(true));
+
+        it('raws', () => expect(clone.raws).toEqual({}));
+
+        it('source', () => expect(clone.source).toBe(original.source));
+      });
+
+      describe('creates a new', () => {
+        it('self', () => expect(clone).not.toBe(original));
+      });
+    });
+
+    describe('overrides', () => {
+      describe('value', () => {
+        it('defined', () =>
+          expect(original.clone({value: false}).value).toBe(false));
+
+        it('undefined', () =>
+          expect(original.clone({value: undefined}).value).toBe(true));
+      });
+
+      describe('raws', () => {
+        it('defined', () =>
+          expect(original.clone({raws: {}}).raws).toEqual({}));
+
+        it('undefined', () =>
+          expect(original.clone({raws: undefined}).raws).toEqual({}));
+      });
+    });
+  });
+
+  it('toJSON', () => expect(utils.parseExpression('true')).toMatchSnapshot());
+});

pkg/sass-parser/lib/src/expression/boolean.ts

@@ -0,0 +1,82 @@
+// Copyright 2024 Google Inc. Use of this source code is governed by an
+// MIT-style license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import * as postcss from 'postcss';
+
+import {LazySource} from '../lazy-source';
+import type * as sassInternal from '../sass-internal';
+import * as utils from '../utils';
+import {Expression} from '.';
+
+/**
+ * The initializer properties for {@link BooleanExpression}.
+ *
+ * @category Expression
+ */
+export interface BooleanExpressionProps {
+  value: boolean;
+  raws?: BooleanExpressionRaws;
+}
+
+/**
+ * Raws indicating how to precisely serialize a {@link BooleanExpression}.
+ *
+ * @category Expression
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface -- No raws for a boolean expression yet.
+export interface BooleanExpressionRaws {}
+
+/**
+ * An expression representing a boolean literal in Sass.
+ *
+ * @category Expression
+ */
+export class BooleanExpression extends Expression {
+  readonly sassType = 'boolean' as const;
+  declare raws: BooleanExpressionRaws;
+
+  /** The boolean value of this expression. */
+  get value(): boolean {
+    return this._value;
+  }
+  set value(value: boolean) {
+    // TODO - postcss/postcss#1957: Mark this as dirty
+    this._value = value;
+  }
+  private _value!: boolean;
+
+  constructor(defaults: BooleanExpressionProps);
+  /** @hidden */
+  constructor(_: undefined, inner: sassInternal.BooleanExpression);
+  constructor(defaults?: object, inner?: sassInternal.BooleanExpression) {
+    super(defaults);
+    if (inner) {
+      this.source = new LazySource(inner);
+      this.value = inner.value;
+    } else {
+      this.value ??= false;
+    }
+  }
+
+  clone(overrides?: Partial<BooleanExpressionProps>): this {
+    return utils.cloneNode(this, overrides, ['raws', 'value']);
+  }
+
+  toJSON(): object;
+  /** @hidden */
+  toJSON(_: string, inputs: Map<postcss.Input, number>): object;
+  toJSON(_?: string, inputs?: Map<postcss.Input, number>): object {
+    return utils.toJSON(this, ['value'], inputs);
+  }
+
+  /** @hidden */
+  toString(): string {
+    return this.value ? 'true' : 'false';
+  }
+
+  /** @hidden */
+  get nonStatementChildren(): ReadonlyArray<Expression> {
+    return [];
+  }
+}

pkg/sass-parser/lib/src/expression/convert.ts

@@ -7,12 +7,14 @@ import * as sassInternal from '../sass-internal';
 import {BinaryOperationExpression} from './binary-operation';
 import {StringExpression} from './string';
 import {Expression} from '.';
+import {BooleanExpression} from './boolean';
 
 /** The visitor to use to convert internal Sass nodes to JS. */
 const visitor = sassInternal.createExpressionVisitor<Expression>({
   visitBinaryOperationExpression: inner =>
     new BinaryOperationExpression(undefined, inner),
   visitStringExpression: inner => new StringExpression(undefined, inner),
+  visitBooleanExpression: inner => new BooleanExpression(undefined, inner),
 });
 
 /** Converts an internal expression AST node into an external one. */

pkg/sass-parser/lib/src/expression/from-props.ts

@@ -5,10 +5,12 @@
 import {BinaryOperationExpression} from './binary-operation';
 import {Expression, ExpressionProps} from '.';
 import {StringExpression} from './string';
+import {BooleanExpression} from './boolean';
 
 /** Constructs an expression from {@link ExpressionProps}. */
 export function fromProps(props: ExpressionProps): Expression {
   if ('text' in props) return new StringExpression(props);
   if ('left' in props) return new BinaryOperationExpression(props);
+  if ('value' in props) return new BooleanExpression(props);
   throw new Error(`Unknown node type: ${props}`);
 }

pkg/sass-parser/lib/src/expression/index.ts

@@ -7,21 +7,25 @@ import type {
   BinaryOperationExpression,
   BinaryOperationExpressionProps,
 } from './binary-operation';
+import {BooleanExpressionProps} from './boolean';
 import type {StringExpression, StringExpressionProps} from './string';
 
 /**
  * The union type of all Sass expressions.
  *
  * @category Expression
  */
-export type AnyExpression = BinaryOperationExpression | StringExpression;
+export type AnyExpression =
+  | BinaryOperationExpression
+  | StringExpression
+  | BooleanExpressionProps;
 
 /**
  * Sass expression types.
  *
  * @category Expression
  */
-export type ExpressionType = 'binary-operation' | 'string';
+export type ExpressionType = 'binary-operation' | 'string' | 'boolean';
 
 /**
  * The union type of all properties that can be used to construct Sass
@@ -31,7 +35,8 @@ export type ExpressionType = 'binary-operation' | 'string';
  */
 export type ExpressionProps =
   | BinaryOperationExpressionProps
-  | StringExpressionProps;
+  | StringExpressionProps
+  | BooleanExpressionProps;
 
 /**
  * The superclass of Sass expression nodes.

pkg/sass-parser/lib/src/sass-internal.ts

@@ -191,6 +191,10 @@ declare namespace SassInternal {
     readonly text: Interpolation;
     readonly hasQuotes: boolean;
   }
+
+  class BooleanExpression extends Expression {
+    readonly value: boolean;
+  }
 }
 
 const sassInternal = (
@@ -218,6 +222,7 @@ export type Interpolation = SassInternal.Interpolation;
 export type Expression = SassInternal.Expression;
 export type BinaryOperationExpression = SassInternal.BinaryOperationExpression;
 export type StringExpression = SassInternal.StringExpression;
+export type BooleanExpression = SassInternal.BooleanExpression;
 
 export interface StatementVisitorObject<T> {
   visitAtRootRule(node: AtRootRule): T;
@@ -237,6 +242,7 @@ export interface StatementVisitorObject<T> {
 export interface ExpressionVisitorObject<T> {
   visitBinaryOperationExpression(node: BinaryOperationExpression): T;
   visitStringExpression(node: StringExpression): T;
+  visitBooleanExpression(node: BooleanExpression): T;
 }
 
 export const parse = sassInternal.parse;