CacheStorage FS

CacheStorage FS, or CSFS, is a Filesystem-like storage library for frontend TypeScript (and JavaScript), built on Web Cache API.

Although the test coverage seems promising, it should be considered experimental and unstable: The APIs may change and test coverage does not mean everything.

It is a purely frontend TypeScript ES module with no server side code.

It should work in all global scopes as long as it provides CacheStorage and can load ES module. That is to say, window, WebWorker and also ServiceWorker but with async import().

There is a JavaScript version hosting on the project's gitlab/github page which can be imported with script[type=module]. However, it is highly recommended that you should clone and use the TypeScript version instead, for many reasons.

It also compiles to some other kinds of modules, although I see no reason for them.

Before everything:

• It currently supports only directories and files, which means, no links.
• It is not designed for concurrent use, and not willing to resolve conflicts and race conditions.
• The separator is hard coded (by Path) as '/'.
• All directory names should ends with the separator, and no file names should end with it. That is the way the library tell directories from files.
  • It allows to share names between directories and files, since it is never really sharing it.

APIs

• Path

  • Path is a ported version of nodejs's path, which is from deno's standard library, which is then from browserify.

• Storage

  • class Storage represents the filesystem and the root directory. It provides all functions a normal directory provides.
  • static async create(storage: CacheStorage, prefix?: string): Promise<Storage>:
    • It is the asynchronous constructor.
    • Parameters:
      • storage: a CacheStorage, usually globalThis.caches.
      • prefix: it is a chroot mechanism: it decides the prefix of all the cacheNames it uses. If no prefix provided, it defaults to 'CSFS/'
    • Returns:
      • an instance of Storage
    • Throws:
      • All throws should be considered a bug.

• CacheDirectory

  • class CacheDirectory represents a directory.

  • static async create(storage: CacheStorage, path: string): Promise<CacheDirectory>

    • The asynchronous constructor, but it is not recommended.
    • Consider open, openDirectory or openPath instead.
    • Unlike Storage, path is required, and its parent directory is required.

  • Direct access functions:

    • These function access the directory and its direct entries. They cannot work with path and cannot work recursively.
    • If the directory is already removed, all of these functions will throw 'Directory already removed'.
    • async list(): Promise<string[]>, alias ls
      • Get a list of all (direct) entries in the directory.
      • There is no ls -R.
    • async openDirectory(entry: string), async openFile(entry: string), async open(entry: string):
      • To open an entry.
      • Parameters:
        • entry: either a FileEntry or a DirectoryEntry.
          • FileEntry:
            Entries satisfying entry === Path.basename(entry), that is to say, not containing the separator.
          • DirectoryEntry:
            Entries satisfying entry === Path.join(Path.basename(entry), Path.sep), that is to say, not containing the separator in the middle, and ends with the separator.
      • Returns:
        • an instance of CacheFile if the entry is a FileEntry, or CacheDirectory otherwise.
      • Throws:
        • 'Illegal entry name': try opening a file with openDirectory or vise versa, or the entry is neither a FileEntry nor a DirectoryEntry
        • 'Not Exists': the entry does not exists.
        • Otherwise a bug.
    • async createFile(entry: string), alias mkdir, async createFile(entry: string), alias touch, async create(entry: string)
      • To create an entry.
      • touch can be used only for file, not directory. Behavior may change.
      • there is no mkdir -p.
      • Similar to open, but:
        • Not throwing Not Exists if it does not exists, throws Already Exists otherwise.
    • async removeFile(entry: string), async removeDirectory(entry: string), async removeSelf(), async remove(entry?: string), alias unlink:
      • To remove an entry, or to remove the directory.
      • If no entry passed to remove, it will call removeSelf, otherwise remove the given entry.
      • Returns:
        • A Promise<void>, resolving after all jobs done.
      • Throws:
        • 'Directory already removed', otherwise a bug
    • async openOrCreate(entry: string):
      • To try opening an entry, create if failed.
      • Throws: *'Illegal entry name', otherwise a bug.

  • Path-related functions:

    • These APIs work with path directly, instead of entry.
    • async createPath(path: string | string[]): Promise<CacheDirectory | CacheFile>:
      • open or create recursively the path, like mkdir -p, but work for files as well.
      • Parameters:
        • path as in string
          • The path
        • path as in string[]
          • The path, but split by the separator.
      • Returns:
        • CacheFile, if the path means a file.
        • CacheDirectory, if the path means a directory.
      • Throws:
        • Whatever openOrCreate may throw, that is to say, 'Illegal entry name' and 'Directory already removed'.
        • 'cannot create new directory': should not happen. If it happens, it might indicate that CacheStorage usage exceeds the limit, or it indicates a bug.
        • Otherwise a bug.
    • async openPath(path: string)
      • open the path
      • potentially unexpected behavior
        • The path is "jailed" inside the current path.
      • Throws:
        • 'Not Exists'
        • Otherwise a bug
    • async removePath(path: string)
      • open the given path, and then remove it. It also applies the "jailing" feature from openPath.

• CacheFile

  • Representing a file
  • async read(), alias cat
    • Returns:
      • A Response, containing what was written to it.
    • Throws:
      • 'File not exists'
  • async write(data: Body)
    • Parameters:
      • A Response, or whatever can be put into a response:
        • type Body = Response | BodyInit | null | undefined
    • Returns:
      • Promise<void>, resolving after all jobs done.
    • Throws:
      • 'File not exists'
  • async remove(), alias unlink
    • Returns:
      • Promise<void>, resolving after all jobs done.
    • Throws:
      • Should never throw.