[lexical] Chore: Change $getTextNodeOffset invariant to warn in prod (error in __DEV__) (#7397)

packages/lexical-devtools/tsconfig.json

@@ -161,6 +161,7 @@
       "@lexical/yjs": ["../lexical-yjs/src/index.ts"],
       "shared/canUseDOM": ["../shared/src/canUseDOM.ts"],
       "shared/caretFromPoint": ["../shared/src/caretFromPoint.ts"],
+      "shared/devInvariant": ["../shared/src/devInvariant.ts"],
       "shared/environment": ["../shared/src/environment.ts"],
       "shared/formatDevErrorMessage": [
         "../shared/src/formatDevErrorMessage.ts"
@@ -168,6 +169,9 @@
       "shared/formatProdErrorMessage": [
         "../shared/src/formatProdErrorMessage.ts"
       ],
+      "shared/formatProdWarningMessage": [
+        "../shared/src/formatProdWarningMessage.ts"
+      ],
       "shared/invariant": ["../shared/src/invariant.ts"],
       "shared/normalizeClassNames": ["../shared/src/normalizeClassNames.ts"],
       "shared/react-test-utils": ["../shared/src/react-test-utils.ts"],

packages/lexical/src/caret/LexicalCaret.ts

@@ -7,6 +7,7 @@
  */
 import type {LexicalNode, NodeKey} from '../LexicalNode';
 
+import devInvariant from 'shared/devInvariant';
 import invariant from 'shared/invariant';
 
 import {$getRoot, $isRootOrShadowRoot} from '../LexicalUtils';
@@ -890,7 +891,7 @@ export function $getTextPointCaret(
 
 /**
  * Get a normalized offset into a TextNode given a numeric offset or a
- * direction for which end of the string to use. Throws if the offset
+ * direction for which end of the string to use. Throws in dev if the offset
  * is not in the bounds of the text content size.
  *
  * @param origin a TextNode
@@ -902,14 +903,19 @@ export function $getTextNodeOffset(
   offset: number | CaretDirection,
 ): number {
   const size = origin.getTextContentSize();
-  const numericOffset =
+  let numericOffset =
     offset === 'next' ? size : offset === 'previous' ? 0 : offset;
-  invariant(
+  if (numericOffset < 0 || numericOffset > size) {
-    numericOffset >= 0 && numericOffset <= size,
+    devInvariant(
-    '$getTextNodeOffset: invalid offset %s for size %s',
+      false,
+      '$getTextNodeOffset: invalid offset %s for size %s at key %s',
       String(offset),
       String(size),
+      origin.getKey(),
     );
+    // Clamp invalid offsets in prod
+    numericOffset = numericOffset < 0 ? 0 : size;
+  }
   return numericOffset;
 }
 

packages/shared/src/__mocks__/devInvariant.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+export default function devInvariant(
+  cond?: boolean,
+  message?: string,
+  ...args: string[]
+): void {
+  if (cond) {
+    return;
+  }
+
+  throw new Error(
+    args.reduce((msg, arg) => msg.replace('%s', String(arg)), message || ''),
+  );
+}

packages/shared/src/devInvariant.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**
+ * If `!cond` throw in `__DEV__` like an invariant and warn in prod
+ */
+export default function devInvariant(
+  cond?: boolean,
+  message?: string,
+  ...args: string[]
+): void {
+  if (cond) {
+    return;
+  }
+
+  throw new Error(
+    'Internal Lexical error: devInvariant() is meant to be replaced at compile ' +
+      'time. There is no runtime version. Error: ' +
+      message,
+  );
+}

packages/shared/src/formatProdWarningMessage.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+export default function prodWarningMessage(
+  code: string,
+  ...args: string[]
+): void {
+  const url = new URL('https://lexical.dev/docs/error');
+  const params = new URLSearchParams();
+  params.append('code', code);
+  for (const arg of args) {
+    params.append('v', arg);
+  }
+  url.search = params.toString();
+
+  console.warn(
+    `Minified Lexical warning #${code}; visit ${url.toString()} for the full message or use the non-minified dev environment for full errors and additional helpful warnings.`,
+  );
+}

scripts/error-codes/__tests__/unit/transform-error-messages.test.js

@@ -53,10 +53,10 @@ function fmt(strings: TemplateStringsArray, ...keys: unknown[]) {
     .replace(/.use strict.;\n/g, '')
     .replace(/var _[^;]+;\n/g, '')
     .replace(/function _interopRequireDefault\([^)]*\) {[^;]+?;[\s\n]*}\n/g, '')
-    .replace(/_format(Dev|Prod)ErrorMessage\d+/g, 'format$1ErrorMessage')
+    .replace(/_format(Dev|Prod)(Error|Warning)Message\d+/g, 'format$1$2Message')
     .replace(
-      /\(0,\s*format(Dev|Prod)ErrorMessage\.default\)/g,
+      /\(0,\s*format(Dev|Prod)(Error|Warning)Message\.default\)/g,
-      'format$1ErrorMessage',
+      'format$1$2Message',
     )
     .trim();
   return prettier.format(before, {
@@ -98,6 +98,7 @@ async function expectTransform(opts) {
 }
 
 describe('transform-error-messages', () => {
+  describe('invariant', () => {
     describe('{extractCodes: true, noMinify: false}', () => {
       const opts = {extractCodes: true, noMinify: false};
       it('inserts known and extracts unknown message codes', async () => {
@@ -172,4 +173,81 @@ describe('transform-error-messages', () => {
         });
       });
     });
+  });
+  describe('devInvariant', () => {
+    describe('{extractCodes: true, noMinify: false}', () => {
+      const opts = {extractCodes: true, noMinify: false};
+      it('inserts known and extracts unknown message codes', async () => {
+        await expectTransform({
+          codeBefore: `
+        devInvariant(condition, ${JSON.stringify(NEW_MSG)});
+        devInvariant(condition, ${JSON.stringify(KNOWN_MSG)}, adj, noun);
+        `,
+          codeExpect: `
+        if (!condition) {
+          formatProdWarningMessage(1);
+        }
+        if (!condition) {
+          formatProdWarningMessage(0, adj, noun);
+        }`,
+          messageMapBefore: KNOWN_MSG_MAP,
+          messageMapExpect: NEW_MSG_MAP,
+          opts,
+        });
+      });
+    });
+    describe('{extractCodes: true, noMinify: true}', () => {
+      const opts = {extractCodes: true, noMinify: true};
+      it('inserts known and extracts unknown message codes', async () => {
+        await expectTransform({
+          codeBefore: `
+        devInvariant(condition, ${JSON.stringify(NEW_MSG)});
+        devInvariant(condition, ${JSON.stringify(KNOWN_MSG)}, adj, noun);
+        `,
+          codeExpect: `
+        if (!condition) {
+          formatDevErrorMessage(\`A new invariant\`);
+        }
+        if (!condition) {
+          formatDevErrorMessage(\`A \${adj} message that contains \${noun}\`);
+        }`,
+          messageMapBefore: KNOWN_MSG_MAP,
+          messageMapExpect: NEW_MSG_MAP,
+          opts,
+        });
+      });
+    });
+    describe('{extractCodes: false, noMinify: false}', () => {
+      const opts = {extractCodes: false, noMinify: false};
+      it('inserts known message', async () => {
+        await expectTransform({
+          codeBefore: `devInvariant(condition, ${JSON.stringify(
+            KNOWN_MSG,
+          )}, adj, noun)`,
+          codeExpect: `
+          if (!condition) {
+            formatProdWarningMessage(0, adj, noun);
+          }
+        `,
+          messageMapBefore: KNOWN_MSG_MAP,
+          messageMapExpect: KNOWN_MSG_MAP,
+          opts,
+        });
+      });
+      it('inserts warning comment for unknown messages', async () => {
+        await expectTransform({
+          codeBefore: `devInvariant(condition, ${JSON.stringify(NEW_MSG)})`,
+          codeExpect: `
+          /*FIXME (minify-errors-in-prod): Unminified error message in production build!*/
+          if (!condition) {
+            formatDevErrorMessage(\`A new invariant\`);
+          }
+       `,
+          messageMapBefore: KNOWN_MSG_MAP,
+          messageMapExpect: KNOWN_MSG_MAP,
+          opts,
+        });
+      });
+    });
+  });
 });

scripts/error-codes/transform-error-messages.js

@@ -50,6 +50,19 @@ function getErrorMap(filepath) {
  * @property {boolean} noMinify
  */
 
+const invariantExpressions = [
+  {
+    dev: 'formatDevErrorMessage',
+    name: 'invariant',
+    prod: 'formatProdErrorMessage',
+  },
+  {
+    dev: 'formatDevErrorMessage',
+    name: 'devInvariant',
+    prod: 'formatProdWarningMessage',
+  },
+];
+
 /**
  * @param {import('@babel/core')} babel
  * @param {Partial<TransformErrorMessagesOptions>} opts
@@ -66,7 +79,8 @@ module.exports = function (babel, opts) {
         const node = path.node;
         const {extractCodes, noMinify} =
           /** @type Partial<TransformErrorMessagesOptions> */ (file.opts);
-        if (path.get('callee').isIdentifier({name: 'invariant'})) {
+        for (const {name, dev, prod} of invariantExpressions) {
+          if (path.get('callee').isIdentifier({name})) {
             // Turns this code:
             //
             // invariant(condition, 'A %s message that contains %s', adj, noun);
@@ -89,7 +103,9 @@ module.exports = function (babel, opts) {
             const errorMsgExpressions = Array.from(node.arguments.slice(2));
             const errorMsgQuasis = errorMsgLiteral
               .split('%s')
-            .map((raw) => t.templateElement({cooked: String.raw({raw}), raw}));
+              .map((raw) =>
+                t.templateElement({cooked: String.raw({raw}), raw}),
+              );
 
             // Outputs:
             //   `A ${adj} message that contains ${noun}`;
@@ -101,8 +117,7 @@ module.exports = function (babel, opts) {
             const parentStatementPath = path.parentPath;
             if (parentStatementPath.type !== 'ExpressionStatement') {
               throw path.buildCodeFrameError(
-              'invariant() cannot be called from expression context. Move ' +
+                `${name}() cannot be called from expression context. Move the call to its own statement.`,
-                'the call to its own statement.',
               );
             }
 
@@ -123,16 +138,13 @@ module.exports = function (babel, opts) {
               //     formatDevErrorMessage(`A ${adj} message that contains ${noun}`);
               //   }
               const formatDevErrorMessageIdentifier =
-              helperModuleImports.addDefault(
+                helperModuleImports.addDefault(path, `shared/${dev}`, {
-                path,
+                  nameHint: dev,
-                'shared/formatDevErrorMessage',
+                });
-                {
+              callExpression = t.callExpression(
-                  nameHint: 'formatDevErrorMessage',
+                formatDevErrorMessageIdentifier,
-                },
+                [devMessage],
               );
-            callExpression = t.callExpression(formatDevErrorMessageIdentifier, [
-              devMessage,
-            ]);
             } else {
               // Error minification enabled for this build.
               //
@@ -143,13 +155,9 @@ module.exports = function (babel, opts) {
 
               // Import ReactErrorProd
               const formatProdErrorMessageIdentifier =
-              helperModuleImports.addDefault(
+                helperModuleImports.addDefault(path, `shared/${prod}`, {
-                path,
+                  nameHint: prod,
-                'shared/formatProdErrorMessage',
+                });
-                {
-                  nameHint: 'formatProdErrorMessage',
-                },
-              );
 
               // Outputs:
               //   formatProdErrorMessage(ERR_CODE, adj, noun);
@@ -181,6 +189,8 @@ module.exports = function (babel, opts) {
                 'FIXME (minify-errors-in-prod): Unminified error message in production build!',
               );
             }
+            return;
+          }
         }
       },
     },

tsconfig.build.json

@@ -162,6 +162,7 @@
       "@lexical/yjs": ["./packages/lexical-yjs/src/index.ts"],
       "shared/canUseDOM": ["./packages/shared/src/canUseDOM.ts"],
       "shared/caretFromPoint": ["./packages/shared/src/caretFromPoint.ts"],
+      "shared/devInvariant": ["./packages/shared/src/devInvariant.ts"],
       "shared/environment": ["./packages/shared/src/environment.ts"],
       "shared/formatDevErrorMessage": [
         "./packages/shared/src/formatDevErrorMessage.ts"
@@ -169,6 +170,9 @@
       "shared/formatProdErrorMessage": [
         "./packages/shared/src/formatProdErrorMessage.ts"
       ],
+      "shared/formatProdWarningMessage": [
+        "./packages/shared/src/formatProdWarningMessage.ts"
+      ],
       "shared/invariant": ["./packages/shared/src/invariant.ts"],
       "shared/normalizeClassNames": [
         "./packages/shared/src/normalizeClassNames.ts"

tsconfig.json

@@ -170,6 +170,7 @@
       "@lexical/yjs": ["./packages/lexical-yjs/src/index.ts"],
       "shared/canUseDOM": ["./packages/shared/src/canUseDOM.ts"],
       "shared/caretFromPoint": ["./packages/shared/src/caretFromPoint.ts"],
+      "shared/devInvariant": ["./packages/shared/src/devInvariant.ts"],
       "shared/environment": ["./packages/shared/src/environment.ts"],
       "shared/formatDevErrorMessage": [
         "./packages/shared/src/formatDevErrorMessage.ts"
@@ -177,6 +178,9 @@
       "shared/formatProdErrorMessage": [
         "./packages/shared/src/formatProdErrorMessage.ts"
       ],
+      "shared/formatProdWarningMessage": [
+        "./packages/shared/src/formatProdWarningMessage.ts"
+      ],
       "shared/invariant": ["./packages/shared/src/invariant.ts"],
       "shared/normalizeClassNames": [
         "./packages/shared/src/normalizeClassNames.ts"