New filesystem API?

[beruic]

I have implemented the following to handle paths easier in our app.

I have focused on providing convenience and make the using code cleaner, without sacrificing performance by doing too many under-the-hood operations.

I do not claim that this is how it should be, but what do people think of the idea of making a class based API for doing file system operations?

import {
  Capacitor,
  CopyOptions,
  FileAppendOptions,
  FileAppendResult,
  FileDeleteOptions,
  FileDeleteResult,
  FileReadOptions,
  FileReadResult,
  FilesystemDirectory,
  FilesystemEncoding,
  FileWriteOptions,
  FileWriteResult,
  MkdirOptions,
  MkdirResult,
  Plugins,
  ReaddirOptions,
  RenameOptions,
  RmdirOptions,
  StatResult,
} from "@capacitor/core"

const { Filesystem } = Plugins

export enum InfoEntryType {
  Directory = "directory",
  File = "file",
}

export interface InfoResult {
  exists: boolean
  type?: InfoEntryType
  error?: Error
}

/**
 * Utility class for easy handling of paths.
 * Can be constructed with non-existing paths.
 */
export class PathHandle {
  readonly relativePath: string
  readonly directory: FilesystemDirectory

  /**
   * Constructor
   *
   * @param relativePath
   * @param directory
   */
  constructor(relativePath: string, directory: FilesystemDirectory) {
    // Clean excessive slashes in path
    let pathLength = relativePath.length
    let cleanedRelativePath = relativePath.replace("//", "/")
    while (pathLength > cleanedRelativePath.length) {
      pathLength = cleanedRelativePath.length
      cleanedRelativePath = cleanedRelativePath.replace("//", "/")
    }

    this.relativePath = cleanedRelativePath
    this.directory = directory
  }

  //# region Computed properties

  /**
   * Get path stats.
   */
  get stat(): Promise<StatResult> {
    return Filesystem.stat({
      directory: this.directory,
      path: this.relativePath,
    })
  }

  /**
   * Get the full `file://` uri of the file.
   */
  get uri(): Promise<string> {
    // Note: If this is slow, we can probably make it synchronous by caching the roots of the directories.
    return Filesystem.getUri({
      directory: this.directory,
      path: this.relativePath,
    }).then((value) => value.uri)
  }

  /**
   * Get the local `http://` url for use in the UI.
   */
  get url(): Promise<string> {
    return this.uri.then((uri) => Capacitor.convertFileSrc(uri))
  }

  /**
   * Whether the relative path for this handle is root at its respective {@link FilesystemDirectory}.
   */
  get isRelativeRoot(): boolean {
    return this.relativePath === "" || this.relativePath.replace("/", "") === ""
  }

  /**
   * Return a {@link PathHandle} to the directory containing this path.
   *
   * If already at the root of the current {@link FilesystemDirectory}, an error is thrown.
   */
  get parentDirectoryHandle(): PathHandle {
    if (this.isRelativeRoot) {
      throw Error("Already at relative root.")
    }

    const base = !this.relativePath.endsWith("/")
      ? this.relativePath
      : this.relativePath.slice(0, -1)

    const relativePath = base.slice(0, base.lastIndexOf("/"))

    return new PathHandle(relativePath, this.directory)
  }

  /**
   * Gets derived information for path in one go.
   *
   * The reason this functionality is done in one, is that they are cheap to do
   * together, and the common workflow is to check for existence and then type.
   * In that regard this method saves calls to {@link stat}
   */
  get info(): Promise<InfoResult> {
    return this.stat
      .then((statResult) => {
        const result: InfoResult = {
          exists: Object.entries(InfoEntryType).some((entry) => entry[1] === statResult.type),
        }
        if (result.exists) {
          result.type = statResult.type as InfoEntryType
        }
        return result
      })
      .catch((reason) => {
        // The reason this warning is here is to catch the actual error and see
        // if it is something that does not mean that the path is not there.
        console.warn("Non-existing file warning", reason)
        const result: InfoResult = {
          exists: false,
          error: reason,
        }
        return result
      })
  }

  //#endregion

  //#region Methods

  /**
   * Append another path to the current one (treating it as a directory), and return a {@link PathHandle} for it.
   *
   * For a checked version of this, see {@link checkedConcat}.
   *
   * @param pathAddition
   */
  concat(pathAddition: string): PathHandle {
    const currentPathCleaned = this.relativePath.endsWith("/")
      ? this.relativePath.slice(0, -1)
      : this.relativePath
    const pathAdditionCleaned = pathAddition.startsWith("/") ? pathAddition.slice(1) : pathAddition
    return new PathHandle(`${currentPathCleaned}/${pathAdditionCleaned}`, this.directory)
  }

  /**
   * Checked version of {@link concat} that verifies that the current path or nearest existing ancestor is not a file.
   *
   * @param pathAddition
   */
  async checkedConcat(pathAddition: string): Promise<PathHandle> {
    const info = await this.info

    if (info.exists && info.type === InfoEntryType.File) {
      throw new Error("Cannot concat path to file.")
    } else if (!info.exists) {
      // Look for an existing ancestor
      let ancestor = this.parentDirectoryHandle
      let ancestorInfo = await ancestor.info
      while (!ancestorInfo.exists) {
        ancestor = ancestor.parentDirectoryHandle
        ancestorInfo = await ancestor.info
      }
      // By here we have an ancestor that exists so we can check for compatibility
      if (ancestorInfo.type === InfoEntryType.File) {
        throw new Error("Cannot concat path to file.")
      }
    }

    return this.concat(pathAddition)
  }
  /**
   * Assumes that the path is a file and reads it.
   *
   * Returns data as a {@link string} according to the encoding (base64 if undefined)
   * like {@link Filesystem.readFile}.
   *
   * Alternatively the file can be fetched as a {@link Blob} by using the Fetch
   * API and the {@link url} of a path.
   *
   * @param encoding
   */
  async readFile(encoding: FilesystemEncoding | undefined = undefined): Promise<FileReadResult> {
    const options: FileReadOptions = {
      directory: this.directory,
      path: this.relativePath,
    }
    if (encoding !== undefined) {
      options.encoding = encoding
    }
    return Filesystem.readFile(options)
  }

  /**
   * Writes data to the path as a file.
   *
   * Will overwrite an existing file.
   *
   * @param data The data to write.
   * @param encoding The encoding to write the file in.
   * Works like the one of the same name in {@link FileWriteOptions}.
   */
  async writeFile(
    data: string,
    encoding: FilesystemEncoding | undefined = undefined
  ): Promise<FileWriteResult> {
    const options: FileWriteOptions = {
      path: this.relativePath,
      data: data,
      directory: this.directory,
      recursive: true,
    }
    if (encoding !== undefined) {
      options.encoding = encoding
    }
    return Filesystem.writeFile(options)
  }

  /**
   * Assumes the path is a file, and appends data to it.
   *
   * @param data The data to write.
   * @param encoding The encoding to write the file in.
   * Works like the one of the same name in {@link FileWriteOptions}.
   */
  async appendFile(
    data: string,
    encoding: FilesystemEncoding | undefined = undefined
  ): Promise<FileAppendResult> {
    const options: FileAppendOptions = {
      path: this.relativePath,
      data: data,
      directory: this.directory,
    }
    if (encoding !== undefined) {
      options.encoding = encoding
    }
    return Filesystem.writeFile(options)
  }

  /**
   * Assumes that the path is a directory and reads it.
   */
  async readDirectory(): Promise<string[]> {
    const options: ReaddirOptions = {
      directory: this.directory,
      path: this.relativePath,
    }
    return Filesystem.readdir(options).then((readdirResult) => readdirResult.files)
  }

  /**
   * Creates the paths as a directory.
   */
  async createDirectory(): Promise<MkdirResult> {
    const options: MkdirOptions = {
      directory: this.directory,
      path: this.relativePath,
      recursive: true,
    }
    return Filesystem.mkdir(options)
  }

  /**
   * Deletes whatever the path points at.
   *
   * If the path points to a directory it will be deleted recursively.
   * If the path points to nothing, then nothing will happen.
   *
   * @return
   */
  async delete(): Promise<FileDeleteResult> {
    const info = await this.info
    if (info.exists) {
      if (info.type === InfoEntryType.File) {
        const options: FileDeleteOptions = {
          directory: this.directory,
          path: this.relativePath,
        }
        return Filesystem.deleteFile(options)
      } else {
        const options: RmdirOptions = {
          directory: this.directory,
          path: this.relativePath,
          recursive: true,
        }
        return Filesystem.rmdir(options)
      }
    } else {
      return false
    }
  }

  /**
   * Helper to construct arguments for {@link rename} and {@link copy}.
   *
   * @param targetRelativePath
   * @param targetDirectory
   * @private
   */
  private renameOrCopyOptions(
    targetRelativePath: string,
    targetDirectory: FilesystemDirectory
  ): RenameOptions | CopyOptions {
    return {
      from: this.relativePath,
      to: targetRelativePath,
      directory: this.directory,
      toDirectory: targetDirectory,
    }
  }

  /**
   * Rename the path target.
   * @param targetRelativePath
   * @param targetDirectory
   * @return A {@link Promise} of a {@link PathHandle} for the target path.
   */
  async rename(
    targetRelativePath: string,
    targetDirectory: FilesystemDirectory
  ): Promise<PathHandle> {
    return Filesystem.rename(this.renameOrCopyOptions(targetRelativePath, targetDirectory)).then(
      () => new PathHandle(targetRelativePath, targetDirectory)
    )
  }

  /**
   * Copy the path target.
   * @param targetRelativePath
   * @param targetDirectory
   * @return A {@link Promise} of a {@link PathHandle} for the target path.
   */
  async copy(
    targetRelativePath: string,
    targetDirectory: FilesystemDirectory
  ): Promise<PathHandle> {
    return Filesystem.copy(this.renameOrCopyOptions(targetRelativePath, targetDirectory)).then(
      () => new PathHandle(targetRelativePath, targetDirectory)
    )
  }
}

export default {
  InfoEntryType,
  PathHandle,
}