Remove claim, untrue since over 5 years ago, that cursorOffset is incompatible with rangeStart/rangeEnd (#15750)

ExplodingCabbage · web-flow · commit 1e30f66f3979 · 2023-12-08T16:35:02.000+02:00
diff --git a/changelog_unreleased/misc/15750.md b/changelog_unreleased/misc/15750.md
@@ -0,0 +1,3 @@
+#### Fix false claim in docs that cursorOffset is incompatible with rangeStart/rangeEnd (#15750 by @ExplodingCabbage)
+
+The cursorOffset option has in fact been compatible with rangeStart/rangeEnd for over 5 years, thanks to work by @ds300. However, Prettier's documentation (including the CLI `--help` text) continued to claim otherwise, falsely. The documentation is now fixed.
diff --git a/docs/api.md b/docs/api.md
@@ -26,7 +26,7 @@ await prettier.format("foo ( );", { semi: false, parser: "babel" });
 
 `formatWithCursor` both formats the code, and translates a cursor position from unformatted code to formatted code. This is useful for editor integrations, to prevent the cursor from moving when code is formatted.
 
-The `cursorOffset` option should be provided, to specify where the cursor is. This option cannot be used with `rangeStart` and `rangeEnd`.
+The `cursorOffset` option should be provided, to specify where the cursor is.
 
 ```js
 await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" });
diff --git a/docs/options.md b/docs/options.md
@@ -254,8 +254,6 @@ These two options can be used to format code starting and ending at a given char
 - Backwards to the start of the first line containing the selected statement.
 - Forwards to the end of the selected statement.
 
-These options cannot be used with `cursorOffset`.
-
 | Default    | CLI Override          | API Override        |
 | ---------- | --------------------- | ------------------- |
 | `0`        | `--range-start <int>` | `rangeStart: <int>` |
diff --git a/src/index.d.ts b/src/index.d.ts
@@ -548,8 +548,6 @@ export interface CursorOptions extends Options {
    * Specify where the cursor is.
    */
   cursorOffset: number;
-  rangeStart?: never;
-  rangeEnd?: never;
 }
 
 export interface CursorResult {
@@ -572,7 +570,7 @@ export function check(source: string, options?: Options): Promise<boolean>;
  * `formatWithCursor` both formats the code, and translates a cursor position from unformatted code to formatted code.
  * This is useful for editor integrations, to prevent the cursor from moving when code is formatted.
  *
- * The `cursorOffset` option should be provided, to specify where the cursor is. This option cannot be used with `rangeStart` and `rangeEnd`.
+ * The `cursorOffset` option should be provided, to specify where the cursor is.
  */
 export function formatWithCursor(
   source: string,
diff --git a/src/main/core-options.evaluate.js b/src/main/core-options.evaluate.js
@@ -49,10 +49,8 @@ const options = {
     type: "int",
     default: -1,
     range: { start: -1, end: Number.POSITIVE_INFINITY, step: 1 },
-    description: outdent`
-      Print (to stderr) where a cursor at the given position would move to after formatting.
-      This option cannot be used with --range-start and --range-end.
-    `,
+    description:
+      "Print (to stderr) where a cursor at the given position would move to after formatting.",
     cliCategory: CATEGORY_EDITOR,
   },
   endOfLine: {
@@ -160,7 +158,6 @@ const options = {
     description: outdent`
       Format code ending at a given character offset (exclusive).
       The range will extend forwards to the end of the selected statement.
-      This option cannot be used with --cursor-offset.
     `,
     cliCategory: CATEGORY_EDITOR,
   },
@@ -172,7 +169,6 @@ const options = {
     description: outdent`
       Format code starting at a given character offset.
       The range will extend backwards to the start of the first line containing the selected statement.
-      This option cannot be used with --cursor-offset.
     `,
     cliCategory: CATEGORY_EDITOR,
   },
diff --git a/src/standalone.d.ts b/src/standalone.d.ts
@@ -4,7 +4,7 @@ import { CursorOptions, CursorResult, Options, SupportInfo } from "./index.js";
  * formatWithCursor both formats the code, and translates a cursor position from unformatted code to formatted code.
  * This is useful for editor integrations, to prevent the cursor from moving when code is formatted
  *
- * The cursorOffset option should be provided, to specify where the cursor is. This option cannot be used with rangeStart and rangeEnd.
+ * The cursorOffset option should be provided, to specify where the cursor is.
  *
  * ```js
  * await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" });
diff --git a/tests/dts/unit/cases/standalone.ts b/tests/dts/unit/cases/standalone.ts
@@ -4,13 +4,11 @@ prettierStandalone.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" });
 prettierStandalone.formatWithCursor(" 1", {
   cursorOffset: 2,
   parser: "babel",
-  // @ts-expect-error
   rangeStart: 2,
 });
 prettierStandalone.formatWithCursor(" 1", {
   cursorOffset: 2,
   parser: "babel",
-  // @ts-expect-error
   rangeEnd: 2,
 });
 prettierStandalone.format(" 1", { parser: "babel" });
diff --git a/tests/format/markdown/markdown/__snapshots__/jsfmt.spec.js.snap b/tests/format/markdown/markdown/__snapshots__/jsfmt.spec.js.snap
@@ -465,7 +465,7 @@ This is similar to the \`--list-different\` parameter in the CLI and is useful f
 \`formatWithCursor\` both formats the code, and translates a cursor position from unformatted code to formatted code.
 This is useful for editor integrations, to prevent the cursor from moving when code is formatted.
 
-The \`cursorOffset\` option should be provided, to specify where the cursor is. This option cannot be used with \`rangeStart\` and \`rangeEnd\`.
+The \`cursorOffset\` option should be provided, to specify where the cursor is.
 
 \`\`\`js
 prettier.formatWithCursor(" 1", { cursorOffset: 2 });
@@ -646,8 +646,6 @@ These two options can be used to format code starting and ending at a given char
 * Backwards to the start of the first line containing the selected statement.
 * Forwards to the end of the selected statement.
 
-These options cannot be used with \`cursorOffset\`.
-
 Default | CLI Override | API Override
 --------|--------------|-------------
 \`0\`        | \`--range-start <int>\`| \`rangeStart: <int>\`
@@ -1454,7 +1452,6 @@ unformatted code to formatted code. This is useful for editor integrations, to
 prevent the cursor from moving when code is formatted.
 
 The \`cursorOffset\` option should be provided, to specify where the cursor is.
-This option cannot be used with \`rangeStart\` and \`rangeEnd\`.
 
 \`\`\`js
 prettier.formatWithCursor(' 1', { cursorOffset: 2 });
@@ -1670,8 +1667,6 @@ character offset (inclusive and exclusive, respectively). The range will extend:
 - Backwards to the start of the first line containing the selected statement.
 - Forwards to the end of the selected statement.
 
-These options cannot be used with \`cursorOffset\`.
-
 | Default    | CLI Override          | API Override        |
 | ---------- | --------------------- | ------------------- |
 | \`0\`        | \`--range-start <int>\` | \`rangeStart: <int>\` |
@@ -2442,7 +2437,7 @@ This is similar to the \`--list-different\` parameter in the CLI and is useful f
 \`formatWithCursor\` both formats the code, and translates a cursor position from unformatted code to formatted code.
 This is useful for editor integrations, to prevent the cursor from moving when code is formatted.
 
-The \`cursorOffset\` option should be provided, to specify where the cursor is. This option cannot be used with \`rangeStart\` and \`rangeEnd\`.
+The \`cursorOffset\` option should be provided, to specify where the cursor is.
 
 \`\`\`js
 prettier.formatWithCursor(" 1", { cursorOffset: 2 });
@@ -2623,8 +2618,6 @@ These two options can be used to format code starting and ending at a given char
 * Backwards to the start of the first line containing the selected statement.
 * Forwards to the end of the selected statement.
 
-These options cannot be used with \`cursorOffset\`.
-
 Default | CLI Override | API Override
 --------|--------------|-------------
 \`0\`        | \`--range-start <int>\`| \`rangeStart: <int>\`
@@ -3431,7 +3424,6 @@ unformatted code to formatted code. This is useful for editor integrations, to
 prevent the cursor from moving when code is formatted.
 
 The \`cursorOffset\` option should be provided, to specify where the cursor is.
-This option cannot be used with \`rangeStart\` and \`rangeEnd\`.
 
 \`\`\`js
 prettier.formatWithCursor(" 1", { cursorOffset: 2 });
@@ -3647,8 +3639,6 @@ character offset (inclusive and exclusive, respectively). The range will extend:
 - Backwards to the start of the first line containing the selected statement.
 - Forwards to the end of the selected statement.
 
-These options cannot be used with \`cursorOffset\`.
-
 | Default    | CLI Override          | API Override        |
 | ---------- | --------------------- | ------------------- |
 | \`0\`        | \`--range-start <int>\` | \`rangeStart: <int>\` |
diff --git a/tests/format/markdown/markdown/real-world-case.md b/tests/format/markdown/markdown/real-world-case.md
@@ -455,7 +455,7 @@ This is similar to the `--list-different` parameter in the CLI and is useful for
 `formatWithCursor` both formats the code, and translates a cursor position from unformatted code to formatted code.
 This is useful for editor integrations, to prevent the cursor from moving when code is formatted.
 
-The `cursorOffset` option should be provided, to specify where the cursor is. This option cannot be used with `rangeStart` and `rangeEnd`.
+The `cursorOffset` option should be provided, to specify where the cursor is.
 
 ```js
 prettier.formatWithCursor(" 1", { cursorOffset: 2 });
@@ -636,8 +636,6 @@ These two options can be used to format code starting and ending at a given char
 * Backwards to the start of the first line containing the selected statement.
 * Forwards to the end of the selected statement.
 
-These options cannot be used with `cursorOffset`.
-
 Default | CLI Override | API Override
 --------|--------------|-------------
 `0`        | `--range-start <int>`| `rangeStart: <int>`
diff --git a/tests/integration/__tests__/__snapshots__/early-exit.js.snap b/tests/integration/__tests__/__snapshots__/early-exit.js.snap
@@ -107,15 +107,12 @@ Config options:
 Editor options:
 
   --cursor-offset <int>    Print (to stderr) where a cursor at the given position would move to after formatting.
-                           This option cannot be used with --range-start and --range-end.
                            Defaults to -1.
   --range-end <int>        Format code ending at a given character offset (exclusive).
                            The range will extend forwards to the end of the selected statement.
-                           This option cannot be used with --cursor-offset.
                            Defaults to Infinity.
   --range-start <int>      Format code starting at a given character offset.
                            The range will extend backwards to the start of the first line containing the selected statement.
-                           This option cannot be used with --cursor-offset.
                            Defaults to 0.
 
 Other options:
@@ -274,15 +271,12 @@ Config options:
 Editor options:
 
   --cursor-offset <int>    Print (to stderr) where a cursor at the given position would move to after formatting.
-                           This option cannot be used with --range-start and --range-end.
                            Defaults to -1.
   --range-end <int>        Format code ending at a given character offset (exclusive).
                            The range will extend forwards to the end of the selected statement.
-                           This option cannot be used with --cursor-offset.
                            Defaults to Infinity.
   --range-start <int>      Format code starting at a given character offset.
                            The range will extend backwards to the start of the first line containing the selected statement.
-                           This option cannot be used with --cursor-offset.
                            Defaults to 0.
 
 Other options:
diff --git a/tests/integration/__tests__/__snapshots__/help-options.js.snap b/tests/integration/__tests__/__snapshots__/help-options.js.snap
@@ -136,7 +136,6 @@ exports[`show detailed usage with --help cursor-offset (stdout) 1`] = `
 "--cursor-offset <int>
 
   Print (to stderr) where a cursor at the given position would move to after formatting.
-  This option cannot be used with --range-start and --range-end.
 
 Default: -1"
 `;
@@ -505,7 +504,6 @@ exports[`show detailed usage with --help range-end (stdout) 1`] = `
 
   Format code ending at a given character offset (exclusive).
   The range will extend forwards to the end of the selected statement.
-  This option cannot be used with --cursor-offset.
 
 Default: Infinity"
 `;
@@ -519,7 +517,6 @@ exports[`show detailed usage with --help range-start (stdout) 1`] = `
 
   Format code starting at a given character offset.
   The range will extend backwards to the start of the first line containing the selected statement.
-  This option cannot be used with --cursor-offset.
 
 Default: 0"
 `;
diff --git a/tests/integration/__tests__/__snapshots__/schema.js.snap b/tests/integration/__tests__/__snapshots__/schema.js.snap
@@ -36,8 +36,7 @@ exports[`schema 1`] = `
         },
         "cursorOffset": {
           "default": -1,
-          "description": "Print (to stderr) where a cursor at the given position would move to after formatting.
-This option cannot be used with --range-start and --range-end.",
+          "description": "Print (to stderr) where a cursor at the given position would move to after formatting.",
           "type": "integer",
         },
         "embeddedLanguageFormatting": {
@@ -345,15 +344,13 @@ This option cannot be used with --range-start and --range-end.",
         "rangeEnd": {
           "default": Infinity,
           "description": "Format code ending at a given character offset (exclusive).
-The range will extend forwards to the end of the selected statement.
-This option cannot be used with --cursor-offset.",
+The range will extend forwards to the end of the selected statement.",
           "type": "integer",
         },
         "rangeStart": {
           "default": 0,
           "description": "Format code starting at a given character offset.
-The range will extend backwards to the start of the first line containing the selected statement.
-This option cannot be used with --cursor-offset.",
+The range will extend backwards to the start of the first line containing the selected statement.",
           "type": "integer",
         },
         "requirePragma": {
diff --git a/tests/integration/__tests__/__snapshots__/support-info.js.snap b/tests/integration/__tests__/__snapshots__/support-info.js.snap
@@ -806,7 +806,7 @@ exports[`CLI --support-info (stdout) 1`] = `
     {
       "category": "Special",
       "default": -1,
-      "description": "Print (to stderr) where a cursor at the given position would move to after formatting.\\nThis option cannot be used with --range-start and --range-end.",
+      "description": "Print (to stderr) where a cursor at the given position would move to after formatting.",
       "name": "cursorOffset",
       "pluginDefaults": {},
       "range": { "end": null, "start": -1, "step": 1 },
@@ -1001,7 +1001,7 @@ exports[`CLI --support-info (stdout) 1`] = `
     {
       "category": "Special",
       "default": null,
-      "description": "Format code ending at a given character offset (exclusive).\\nThe range will extend forwards to the end of the selected statement.\\nThis option cannot be used with --cursor-offset.",
+      "description": "Format code ending at a given character offset (exclusive).\\nThe range will extend forwards to the end of the selected statement.",
       "name": "rangeEnd",
       "pluginDefaults": {},
       "range": { "end": null, "start": 0, "step": 1 },
@@ -1010,7 +1010,7 @@ exports[`CLI --support-info (stdout) 1`] = `
     {
       "category": "Special",
       "default": 0,
-      "description": "Format code starting at a given character offset.\\nThe range will extend backwards to the start of the first line containing the selected statement.\\nThis option cannot be used with --cursor-offset.",
+      "description": "Format code starting at a given character offset.\\nThe range will extend backwards to the start of the first line containing the selected statement.",
       "name": "rangeStart",
       "pluginDefaults": {},
       "range": { "end": null, "start": 0, "step": 1 },
diff --git a/website/versioned_docs/version-stable/api.md b/website/versioned_docs/version-stable/api.md
@@ -27,7 +27,7 @@ await prettier.format("foo ( );", { semi: false, parser: "babel" });
 
 `formatWithCursor` both formats the code, and translates a cursor position from unformatted code to formatted code. This is useful for editor integrations, to prevent the cursor from moving when code is formatted.
 
-The `cursorOffset` option should be provided, to specify where the cursor is. This option cannot be used with `rangeStart` and `rangeEnd`.
+The `cursorOffset` option should be provided, to specify where the cursor is.
 
 ```js
 await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" });
diff --git a/website/versioned_docs/version-stable/options.md b/website/versioned_docs/version-stable/options.md
@@ -255,8 +255,6 @@ These two options can be used to format code starting and ending at a given char
 - Backwards to the start of the first line containing the selected statement.
 - Forwards to the end of the selected statement.
 
-These options cannot be used with `cursorOffset`.
-
 | Default    | CLI Override          | API Override        |
 | ---------- | --------------------- | ------------------- |
 | `0`        | `--range-start <int>` | `rangeStart: <int>` |

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+#### Fix false claim in docs that cursorOffset is incompatible with rangeStart/rangeEnd (#15750 by @ExplodingCabbage)`
	`2`	`+`
	`3`	+The cursorOffset option has in fact been compatible with rangeStart/rangeEnd for over 5 years, thanks to work by @ds300. However, Prettier's documentation (including the CLI `--help` text) continued to claim otherwise, falsely. The documentation is now fixed.
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@ import { CursorOptions, CursorResult, Options, SupportInfo } from "./index.js";`
`4`	`4`	`* formatWithCursor both formats the code, and translates a cursor position from unformatted code to formatted code.`
`5`	`5`	`* This is useful for editor integrations, to prevent the cursor from moving when code is formatted`
`6`	`6`	`*`
`7`		`- * The cursorOffset option should be provided, to specify where the cursor is. This option cannot be used with rangeStart and rangeEnd.`
	`7`	`+ * The cursorOffset option should be provided, to specify where the cursor is.`
`8`	`8`	`*`
`9`	`9`	* ```js
`10`	`10`	`* await prettier.formatWithCursor(" 1", { cursorOffset: 2, parser: "babel" });`