Implemented alternative open mode in files (#3119)

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

cli/js/files.ts

@@ -20,22 +20,69 @@ import {
 /** Open a file and return an instance of the `File` object
  *  synchronously.
  *
- *       const file = Deno.openSync("/foo/bar.txt");
+ *       const file = Deno.openSync("/foo/bar.txt", { read: true, write: true });
  */
-export function openSync(filename: string, mode: OpenMode = "r"): File {
-  const rid = sendSyncJson(dispatch.OP_OPEN, { filename, mode });
+export function openSync(filename: string, capability?: OpenOptions): File;
+/** Open a file and return an instance of the `File` object
+ *  synchronously.
+ *
+ *       const file = Deno.openSync("/foo/bar.txt", "r");
+ */
+export function openSync(filename: string, mode?: OpenMode): File;
+
+export function openSync(
+  filename: string,
+  modeOrOptions: OpenOptions | OpenMode = "r"
+): File {
+  let mode = null;
+  let options = null;
+
+  if (typeof modeOrOptions === "string") {
+    mode = modeOrOptions;
+  } else {
+    checkOpenOptions(modeOrOptions);
+    options = modeOrOptions;
+  }
+
+  const rid = sendSyncJson(dispatch.OP_OPEN, { filename, options, mode });
   return new File(rid);
 }
 
 /** Open a file and return an instance of the `File` object.
  *
- *       const file = await Deno.open("/foo/bar.txt");
+ *     const file = await Deno.open("/foo/bar.txt", { read: true, write: true });
  */
 export async function open(
   filename: string,
-  mode: OpenMode = "r"
+  options?: OpenOptions
+): Promise<File>;
+
+/** Open a file and return an instance of the `File` object.
+ *
+ *     const file = await Deno.open("/foo/bar.txt, "w+");
+ */
+export async function open(filename: string, mode?: OpenMode): Promise<File>;
+
+/**@internal*/
+export async function open(
+  filename: string,
+  modeOrOptions: OpenOptions | OpenMode = "r"
 ): Promise<File> {
-  const rid = await sendAsyncJson(dispatch.OP_OPEN, { filename, mode });
+  let mode = null;
+  let options = null;
+
+  if (typeof modeOrOptions === "string") {
+    mode = modeOrOptions;
+  } else {
+    checkOpenOptions(modeOrOptions);
+    options = modeOrOptions;
+  }
+
+  const rid = await sendAsyncJson(dispatch.OP_OPEN, {
+    filename,
+    options,
+    mode
+  });
   return new File(rid);
 }
 
@@ -216,6 +263,36 @@ export const stdout = new File(1);
 /** An instance of `File` for stderr. */
 export const stderr = new File(2);
 
+export interface OpenOptions {
+  /** Sets the option for read access. This option, when true, will indicate that the file should be read-able if opened. */
+  read?: boolean;
+  /** Sets the option for write access.
+   * This option, when true, will indicate that the file should be write-able if opened.
+   * If the file already exists, any write calls on it will overwrite its contents, without truncating it.
+   */
+  write?: boolean;
+  /** Sets the option for creating a new file.
+   * This option indicates whether a new file will be created if the file does not yet already exist.
+   * In order for the file to be created, write or append access must be used.
+   */
+  create?: boolean;
+  /** Sets the option for truncating a previous file.
+   * If a file is successfully opened with this option set it will truncate the file to 0 length if it already exists.
+   * The file must be opened with write access for truncate to work.
+   */
+  truncate?: boolean;
+  /**Sets the option for the append mode.
+   * This option, when true, means that writes will append to a file instead of overwriting previous contents.
+   * Note that setting { write: true, append: true } has the same effect as setting only { append: true }.
+   */
+  append?: boolean;
+  /** Sets the option to always create a new file.
+   * This option indicates whether a new file will be created. No file is allowed to exist at the target location, also no (dangling) symlink.
+   * If { createNew: true } is set, create and truncate are ignored.
+   */
+  createNew?: boolean;
+}
+
 export type OpenMode =
   /** Read-only. Default. Starts at beginning of file. */
   | "r"
@@ -241,3 +318,26 @@ export type OpenMode =
   | "x"
   /** Read-write. Behaves like `x` and allows to read from file. */
   | "x+";
+
+/** Check if OpenOptions is set to valid combination of options.
+ *  @returns Tuple representing if openMode is valid and error message if it's not
+ *  @internal
+ */
+function checkOpenOptions(options: OpenOptions): void {
+  if (Object.values(options).filter(val => val === true).length === 0) {
+    throw new Error("OpenOptions requires at least one option to be true");
+  }
+
+  if (options.truncate && !options.write) {
+    throw new Error("'truncate' option requires 'write' option");
+  }
+
+  const createOrCreateNewWithoutWriteOrAppend =
+    (options.create || options.createNew) && !(options.write || options.append);
+
+  if (createOrCreateNewWithoutWriteOrAppend) {
+    throw new Error(
+      "'create' or 'createNew' options require 'write' or 'append' option"
+    );
+  }
+}