fileSystem: Class that works with browser or desktop file system (#3740)

nkomonen-amazon · web-flow · commit 6fcb85aa31b3 · 2023-08-21T19:07:13.000-04:00
- This uses the vscode.workspace.fs implementation

Signed-off-by: Nikolas Komonen &lt;nkomonen@amazon.com&gt;
diff --git a/src/srcShared/README.md b/src/srcShared/README.md
@@ -0,0 +1,4 @@
+# srcShared
+
+This folder must only contain code which can be used in the browser OR desktop.
+This is why we call it "shared".
diff --git a/src/srcShared/fs.ts b/src/srcShared/fs.ts
@@ -0,0 +1,134 @@
+/*!
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import * as vscode from 'vscode'
+
+const fs = vscode.workspace.fs
+type Uri = vscode.Uri
+
+/**
+ * @warning Do not import this class specifically, instead import the instance {@link fsCommon}.
+ *
+ * This class contains file system methods that are "common", meaning
+ * it can be used in the browser or desktop.
+ *
+ * Technical Details:
+ * TODO: Verify the point below once I get this hooked up to the browser code.
+ * - vscode.workspace.fs dynamically resolves the correct file system provider
+ *   to use. This means that in the browser it will attempt to use the File System
+ *   Access API.
+ *
+ *
+ * MODIFYING THIS CLASS:
+ * - All methods must work for both browser and desktop
+ * - Do not use 'fs' or 'fs-extra' since they are not browser compatible.
+ *   If they have functionality that cannot be achieved with a
+ *   browser+desktop implementation, then create it in the module {@link TODO}
+ */
+export class FileSystemCommon {
+    private constructor() {}
+    static #instance: FileSystemCommon
+    static get instance(): FileSystemCommon {
+        return (this.#instance ??= new FileSystemCommon())
+    }
+
+    async mkdir(path: Uri | string): Promise<void> {
+        path = FileSystemCommon.getUri(path)
+        return fs.createDirectory(path)
+    }
+
+    async readFile(path: Uri | string): Promise<Uint8Array> {
+        path = FileSystemCommon.getUri(path)
+        return fs.readFile(path)
+    }
+
+    async readFileAsString(path: Uri | string): Promise<string> {
+        path = FileSystemCommon.getUri(path)
+        return FileSystemCommon.arrayToString(await this.readFile(path))
+    }
+
+    async appendFile(path: Uri | string, content: Uint8Array | string): Promise<void> {
+        path = FileSystemCommon.getUri(path)
+
+        const currentContent: Uint8Array = (await this.fileExists(path)) ? await this.readFile(path) : new Uint8Array(0)
+        const currentLength = currentContent.length
+
+        const newContent = FileSystemCommon.asArray(content)
+        const newLength = newContent.length
+
+        const finalContent = new Uint8Array(currentLength + newLength)
+        finalContent.set(currentContent)
+        finalContent.set(newContent, currentLength)
+
+        return this.writeFile(path, finalContent)
+    }
+
+    async fileExists(path: Uri | string): Promise<boolean> {
+        path = FileSystemCommon.getUri(path)
+        const stat = await this.stat(path)
+        return stat === undefined ? false : stat.type === vscode.FileType.File
+    }
+
+    async writeFile(path: Uri | string, data: string | Uint8Array): Promise<void> {
+        path = FileSystemCommon.getUri(path)
+        return fs.writeFile(path, FileSystemCommon.asArray(data))
+    }
+
+    /**
+     * The stat of the file, undefined if the file does not exist, otherwise an error is thrown.
+     */
+    async stat(uri: vscode.Uri | string): Promise<vscode.FileStat | undefined> {
+        const path = FileSystemCommon.getUri(uri)
+        try {
+            return await fs.stat(path)
+        } catch (err) {
+            if (err instanceof vscode.FileSystemError && err.code === 'FileNotFound') {
+                return undefined
+            }
+            throw err
+        }
+    }
+
+    async delete(uri: vscode.Uri | string): Promise<void> {
+        const path = FileSystemCommon.getUri(uri)
+        return fs.delete(path, { recursive: true })
+    }
+
+    async readdir(uri: vscode.Uri | string): Promise<[string, vscode.FileType][]> {
+        const path = FileSystemCommon.getUri(uri)
+        return await fs.readDirectory(path)
+    }
+
+    // -------- private methods --------
+    static readonly #decoder = new TextDecoder()
+    static readonly #encoder = new TextEncoder()
+
+    private static arrayToString(array: Uint8Array) {
+        return FileSystemCommon.#decoder.decode(array)
+    }
+
+    private static stringToArray(string: string): Uint8Array {
+        return FileSystemCommon.#encoder.encode(string)
+    }
+
+    private static asArray(array: Uint8Array | string): Uint8Array {
+        if (typeof array === 'string') {
+            return FileSystemCommon.stringToArray(array)
+        }
+        return array
+    }
+
+    /**
+     * Retrieve the Uri of the file.
+     *
+     * @param path The file path for which to retrieve metadata.
+     * @return The Uri about the file.
+     */
+    private static getUri(path: string | vscode.Uri): vscode.Uri {
+        if (path instanceof vscode.Uri) {
+            return path
+        }
+        return vscode.Uri.file(path)
+    }
+}
diff --git a/src/test/srcShared/fs.test.ts b/src/test/srcShared/fs.test.ts
@@ -0,0 +1,227 @@
+/*!
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as assert from 'assert'
+import * as vscode from 'vscode'
+import * as path from 'path'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { FakeExtensionContext } from '../fakeExtensionContext'
+import { FileSystemCommon } from '../../srcShared/fs'
+import * as os from 'os'
+import { isMinimumVersion } from '../../shared/vscode/env'
+
+function isWin() {
+    return os.platform() === 'win32'
+}
+
+describe('FileSystem', function () {
+    let fakeContext: vscode.ExtensionContext
+    let fsCommon: FileSystemCommon
+
+    before(async function () {
+        fakeContext = await FakeExtensionContext.create()
+        fsCommon = FileSystemCommon.instance
+    })
+
+    beforeEach(async function () {
+        await makeTestRoot()
+    })
+
+    afterEach(async function () {
+        await deleteTestRoot()
+    })
+
+    describe('readFileAsString()', function () {
+        it('reads a file', async function () {
+            const path = await makeFile('test.txt', 'hello world')
+            const pathAsUri = vscode.Uri.file(path)
+
+            assert.strictEqual(await fsCommon.readFileAsString(path), 'hello world')
+            assert.strictEqual(await fsCommon.readFileAsString(pathAsUri), 'hello world')
+        })
+
+        it('throws when no permissions', async function () {
+            if (isWin()) {
+                console.log('Skipping since windows does not support mode permissions')
+                return this.skip()
+            }
+
+            const fileName = 'test.txt'
+            const path = await makeFile(fileName, 'hello world', { mode: 0o000 })
+
+            await assert.rejects(fsCommon.readFileAsString(path), err => {
+                assert(err instanceof vscode.FileSystemError)
+                assert.strictEqual(err.code, 'NoPermissions')
+                assert(err.message.includes(fileName))
+                return true
+            })
+        })
+    })
+
+    describe('writeFile()', function () {
+        it('writes a file', async function () {
+            const filePath = createTestPath('myFileName')
+            await fsCommon.writeFile(filePath, 'MyContent')
+            assert.strictEqual(readFileSync(filePath, 'utf-8'), 'MyContent')
+        })
+
+        it('writes a file with encoded text', async function () {
+            const filePath = createTestPath('myFileName')
+            const text = 'hello'
+            const content = new TextEncoder().encode(text)
+
+            await fsCommon.writeFile(filePath, content)
+
+            assert.strictEqual(readFileSync(filePath, 'utf-8'), text)
+        })
+
+        it('throws when existing file + no permission', async function () {
+            if (isWin()) {
+                console.log('Skipping since windows does not support mode permissions')
+                return this.skip()
+            }
+            if (isMinimumVersion()) {
+                console.log('Skipping since min version has different error message')
+                return this.skip()
+            }
+
+            const fileName = 'test.txt'
+            const filePath = await makeFile(fileName, 'hello world', { mode: 0o000 })
+
+            await assert.rejects(fsCommon.writeFile(filePath, 'MyContent'), err => {
+                assert(err instanceof vscode.FileSystemError)
+                assert.strictEqual(err.name, 'EntryWriteLocked (FileSystemError) (FileSystemError)')
+                assert(err.message.includes(fileName))
+                return true
+            })
+        })
+    })
+
+    describe('appendFile()', function () {
+        it('appends to a file', async function () {
+            const filePath = await makeFile('test.txt', 'LINE-1-TEXT')
+            await fsCommon.appendFile(filePath, '\nLINE-2-TEXT')
+            assert.strictEqual(readFileSync(filePath, 'utf-8'), 'LINE-1-TEXT\nLINE-2-TEXT')
+        })
+
+        it('creates new file if it does not exist', async function () {
+            const filePath = createTestPath('thisDoesNotExist.txt')
+            await fsCommon.appendFile(filePath, 'i am nikolas')
+            assert.strictEqual(readFileSync(filePath, 'utf-8'), 'i am nikolas')
+        })
+    })
+
+    describe('fileExists()', function () {
+        it('returns true for an existing file', async function () {
+            const filePath = await makeFile('test.txt')
+            const existantFile = await fsCommon.fileExists(filePath)
+            assert.strictEqual(existantFile, true)
+        })
+
+        it('returns false for a non-existant file', async function () {
+            const nonExistantFile = await fsCommon.fileExists(createTestPath('thisDoesNotExist.txt'))
+            assert.strictEqual(nonExistantFile, false)
+        })
+    })
+
+    describe('mkdir()', function () {
+        const paths = ['a', 'a/b', 'a/b/c', 'a/b/c/d/']
+
+        paths.forEach(async function (p) {
+            it(`creates path: '${p}'`, async function () {
+                const dirPath = createTestPath(p)
+                await fsCommon.mkdir(dirPath)
+                assert.ok(existsSync(dirPath))
+            })
+        })
+    })
+
+    describe('readdir()', function () {
+        it('lists files in a directory', async function () {
+            makeFile('a.txt')
+            makeFile('b.txt')
+            makeFile('c.txt')
+            mkdirSync(createTestPath('dirA'))
+            mkdirSync(createTestPath('dirB'))
+            mkdirSync(createTestPath('dirC'))
+
+            const files = await fsCommon.readdir(testRootPath())
+            assert.deepStrictEqual(
+                sorted(files),
+                sorted([
+                    ['a.txt', vscode.FileType.File],
+                    ['b.txt', vscode.FileType.File],
+                    ['c.txt', vscode.FileType.File],
+                    ['dirA', vscode.FileType.Directory],
+                    ['dirB', vscode.FileType.Directory],
+                    ['dirC', vscode.FileType.Directory],
+                ])
+            )
+        })
+
+        it('empty list if no files in directory', async function () {
+            const files = await fsCommon.readdir(testRootPath())
+            assert.deepStrictEqual(files, [])
+        })
+
+        function sorted(i: [string, vscode.FileType][]) {
+            return i.sort((a, b) => a[0].localeCompare(b[0]))
+        }
+    })
+
+    describe('delete()', function () {
+        it('deletes a file', async function () {
+            const filePath = await makeFile('test.txt', 'hello world')
+            await fsCommon.delete(filePath)
+            assert.ok(!existsSync(filePath))
+        })
+
+        it('deletes a directory', async function () {
+            const dirPath = createTestPath('dirToDelete')
+            mkdirSync(dirPath)
+
+            await fsCommon.delete(dirPath)
+
+            assert.ok(!existsSync(dirPath))
+        })
+    })
+
+    describe('stat()', function () {
+        it('gets stat of a file', async function () {
+            const filePath = await makeFile('test.txt', 'hello world')
+            const stat = await fsCommon.stat(filePath)
+            assert.ok(stat)
+            assert.strictEqual(stat.type, vscode.FileType.File)
+        })
+
+        it('return undefined if no file exists', async function () {
+            const filePath = createTestPath('thisDoesNotExist.txt')
+            const stat = await fsCommon.stat(filePath)
+            assert.strictEqual(stat, undefined)
+        })
+    })
+
+    async function makeFile(relativePath: string, content?: string, options?: { mode?: number }): Promise<string> {
+        const filePath = path.join(testRootPath(), relativePath)
+        writeFileSync(filePath, content ?? '', { mode: options?.mode })
+        return filePath
+    }
+
+    function createTestPath(relativePath: string): string {
+        return path.join(testRootPath(), relativePath)
+    }
+
+    function testRootPath() {
+        return path.join(fakeContext.globalStorageUri.fsPath, 'testDir')
+    }
+
+    async function makeTestRoot() {
+        return mkdirSync(testRootPath())
+    }
+
+    async function deleteTestRoot() {
+        return rmSync(testRootPath(), { recursive: true })
+    }
+})
