feat: `FsFile.sync()` and `FsFile.syncSync()` (#22017)

This change:
1. Implements `Deno.FsFile.sync()` and `Deno.FsFile.syncSync()`.
2. Deprecates `Deno.fsync()` and `Deno.fsyncSync()` for removal in Deno
v2, in favour of the above corresponding methods.

Related #21995

---------

Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>

1 files changed, 42 insertions, 0 deletions

diff --git a/cli/tsc/dts/lib.deno.ns.d.ts b/cli/tsc/dts/lib.deno.ns.d.ts
index e32b90b41..2b82fa152 100644
--- a/cli/tsc/dts/lib.deno.ns.d.ts
+++ b/cli/tsc/dts/lib.deno.ns.d.ts
@@ -2168,6 +2168,9 @@ declare namespace Deno {
    * console.log(await Deno.readTextFile("my_file.txt")); // H
    * ```
    *
+   * @deprecated Use `file.sync()` instead. {@linkcode Deno.fsync} will be
+   * removed in v2.0.0.
+   *
    * @category I/O
    */
   export function fsync(rid: number): Promise<void>;
@@ -2187,6 +2190,9 @@ declare namespace Deno {
    * console.log(Deno.readTextFileSync("my_file.txt")); // H
    * ```
    *
+   * @deprecated Use `file.syncSync()` instead. {@linkcode Deno.fsyncSync} will
+   * be removed in v2.0.0.
+   *
    * @category I/O
    */
   export function fsyncSync(rid: number): void;
@@ -2531,6 +2537,42 @@ declare namespace Deno {
      */
     statSync(): FileInfo;
     /**
+     * Flushes any pending data and metadata operations of the given file
+     * stream to disk.
+     *
+     * ```ts
+     * const file = await Deno.open(
+     *   "my_file.txt",
+     *   { read: true, write: true, create: true },
+     * );
+     * await file.write(new TextEncoder().encode("Hello World"));
+     * await file.truncate(1);
+     * await file.sync();
+     * console.log(await Deno.readTextFile("my_file.txt")); // H
+     * ```
+     *
+     * @category I/O
+     */
+    sync(): Promise<void>;
+    /**
+     * Synchronously flushes any pending data and metadata operations of the given
+     * file stream to disk.
+     *
+     * ```ts
+     * const file = Deno.openSync(
+     *   "my_file.txt",
+     *   { read: true, write: true, create: true },
+     * );
+     * file.writeSync(new TextEncoder().encode("Hello World"));
+     * file.truncateSync(1);
+     * file.syncSync();
+     * console.log(Deno.readTextFileSync("my_file.txt")); // H
+     * ```
+     *
+     * @category I/O
+     */
+    syncSync(): void;
+    /**
      * Flushes any pending data operations of the given file stream to disk.
      *  ```ts
      * using file = await Deno.open(