Emit deprecation warnings for legacy JS API

lib/src/deprecations.ts

@@ -2,7 +2,7 @@
 // MIT-style license that can be found in the LICENSE file or at
 // https://opensource.org/licenses/MIT.
 
-import {DeprecationOrId} from './vendor/sass';
+import {Deprecation, DeprecationOrId} from './vendor/sass';
 import {Version} from './version';
 
 export {deprecations} from './vendor/deprecations';
@@ -15,12 +15,83 @@ export {Deprecation, DeprecationOrId, DeprecationStatus} from './vendor/sass';
 export function getDeprecationIds(
   arr: (DeprecationOrId | Version)[]
 ): string[] {
-  return arr.flatMap(item => {
+  return arr.map(item => {
     if (item instanceof Version) {
-      return arr.map(item => item.toString());
+      return item.toString();
     } else if (typeof item === 'string') {
       return item;
     }
     return item.id;
   });
 }
+
+/**
+ * Shorthand for the subset of options related to deprecations.
+ */
+export type DeprecationOptions = {
+  fatalDeprecations?: (DeprecationOrId | Version)[];
+  futureDeprecations?: DeprecationOrId[];
+  silenceDeprecations?: DeprecationOrId[];
+};
+
+/**
+ * Handles a host-side deprecation warning, either emitting a warning, throwing
+ * and error, or doing nothing depending on the deprecation options used.
+ */
+export function warnForHostSideDeprecation(
+  message: string,
+  deprecation: Deprecation,
+  options?: DeprecationOptions
+): void {
+  if (
+    deprecation.status === 'future' &&
+    !getDeprecationIds(options?.futureDeprecations ?? []).includes(
+      deprecation.id
+    )
+  ) {
+    return;
+  }
+  const fullMessage = `Deprecation [${deprecation.id}]: ${message}`;
+  if (isFatal(deprecation, options)) {
+    throw Error(fullMessage);
+  }
+  if (
+    !getDeprecationIds(options?.silenceDeprecations ?? []).includes(
+      deprecation.id
+    )
+  ) {
+    console.warn(fullMessage);
+  }
+}
+
+/**
+ * Checks whether the given deprecation is included in the given list of
+ * fatal deprecations.
+ */
+function isFatal(
+  deprecation: Deprecation,
+  options?: DeprecationOptions
+): boolean {
+  const versionNumber =
+    deprecation.deprecatedIn === null
+      ? null
+      : deprecation.deprecatedIn.major * 1000000 +
+        deprecation.deprecatedIn.minor * 1000 +
+        deprecation.deprecatedIn.patch;
+  for (const fatal of options?.fatalDeprecations ?? []) {
+    if (fatal instanceof Version) {
+      if (versionNumber === null) continue;
+      if (
+        versionNumber <=
+        fatal.major * 1000000 + fatal.minor * 1000 + fatal.patch
+      ) {
+        return true;
+      }
+    } else if (typeof fatal === 'string') {
+      if (fatal === deprecation.id) return true;
+    } else {
+      if (fatal.id === deprecation.id) return true;
+    }
+  }
+  return false;
+}

lib/src/legacy/index.ts

@@ -14,6 +14,7 @@ import {
   compileString,
   compileStringAsync,
 } from '../compile';
+import {deprecations, warnForHostSideDeprecation} from '../deprecations';
 import {
   SyncBoolean,
   fileUrlToPathCrossPlatform,
@@ -50,6 +51,11 @@ export function render(
     options = adjustOptions(options);
 
     const start = Date.now();
+    warnForHostSideDeprecation(
+      'The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0.',
+      deprecations['legacy-js-api'],
+      options
+    );
     const compileSass = isStringOptions(options)
       ? compileStringAsync(options.data, convertStringOptions(options, false))
       : compileAsync(options.file, convertOptions(options, false));
@@ -68,6 +74,11 @@ export function renderSync(options: LegacyOptions<'sync'>): LegacyResult {
   const start = Date.now();
   try {
     options = adjustOptions(options);
+    warnForHostSideDeprecation(
+      'The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0.',
+      deprecations['legacy-js-api'],
+      options
+    );
     const result = isStringOptions(options)
       ? compileString(options.data, convertStringOptions(options, true))
       : compile(options.file, convertOptions(options, true));

lib/src/value/color.ts

@@ -3,6 +3,7 @@
 // https://opensource.org/licenses/MIT.
 
 import {Value} from './index';
+import {deprecations, warnForHostSideDeprecation} from '../deprecations';
 import {valueError} from '../utils';
 import {
   fuzzyAssertInRange,
@@ -304,11 +305,11 @@ function checkChangeDeprecations(
 
 /** Warn users about legacy color channel getters. */
 function emitColor4ApiGetterDeprecation(name: string): void {
-  console.warn(
-    'Deprecation [color-4-api]: ' +
-      `\`${name}\` is deprecated, use \`channel\` instead.` +
+  warnForHostSideDeprecation(
+    `\`${name}\` is deprecated, use \`channel\` instead.` +
       '\n' +
-      'More info: https://sass-lang.com/d/color-4-api'
+      'More info: https://sass-lang.com/d/color-4-api',
+    deprecations['color-4-api']
   );
 }
 
@@ -317,32 +318,32 @@ function emitColor4ApiGetterDeprecation(name: string): void {
  * explicitly setting `space`.
  */
 function emitColor4ApiChangeSpaceDeprecation(): void {
-  console.warn(
-    'Deprecation [color-4-api]: ' +
-      "Changing a channel not in this color's space without explicitly " +
+  warnForHostSideDeprecation(
+    "Changing a channel not in this color's space without explicitly " +
       'specifying the `space` option is deprecated.' +
       '\n' +
-      'More info: https://sass-lang.com/d/color-4-api'
+      'More info: https://sass-lang.com/d/color-4-api',
+    deprecations['color-4-api']
   );
 }
 
 /** Warn users about `null` channel values without setting `space`. */
 function emitColor4ApiChangeNullDeprecation(channel: string): void {
-  console.warn(
-    'Deprecation [color-4-api]: ' +
-      `Passing \`${channel}: null\` without setting \`space\` is deprecated.` +
+  warnForHostSideDeprecation(
+    `Passing \`${channel}: null\` without setting \`space\` is deprecated.` +
       '\n' +
-      'More info: https://sass-lang.com/d/color-4-api'
+      'More info: https://sass-lang.com/d/color-4-api',
+    deprecations['color-4-api']
   );
 }
 
 /** Warn users about null-alpha deprecation. */
 function emitNullAlphaDeprecation(): void {
-  console.warn(
-    'Deprecation [null-alpha]: ' +
-      'Passing `alpha: null` without setting `space` is deprecated.' +
+  warnForHostSideDeprecation(
+    'Passing `alpha: null` without setting `space` is deprecated.' +
       '\n' +
-      'More info: https://sass-lang.com/d/null-alpha'
+      'More info: https://sass-lang.com/d/null-alpha',
+    deprecations['null-alpha']
   );
 }