initial release

.gitea/workflows/publish.yaml

@@ -0,0 +1,19 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "*"
+  
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - run: npm ci
+      - run: npm version from-git --allow-same-version --no-git-tag-version
+      - run: npm config set registry https://gitea.sugoidogo.com/api/packages/sugoidogo/npm/
+      - run: npm config set -- '//gitea.sugoidogo.com/api/packages/sugoidogo/npm/:_authToken' "$PACKAGES_KEY"
+        env:
+          PACKAGES_KEY: ${{ secrets.PACKAGES_KEY }}
+      - run: npm publish

.npmrc

@@ -0,0 +1 @@
+@sugoidogo:registry=https://gitea.sugoidogo.com/api/packages/sugoidogo/npm/

LICENCE.md

@@ -0,0 +1,163 @@
+GNU Lesser General Public License
+=================================
+
+_Version 3, 29 June 2007_  
+_Copyright © 2007 Free Software Foundation, Inc. &lt;<http://fsf.org/>&gt;_
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+### 0. Additional Definitions
+
+As used herein, “this License” refers to version 3 of the GNU Lesser
+General Public License, and the “GNU GPL” refers to version 3 of the GNU
+General Public License.
+
+“The Library” refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An “Application” is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A “Combined Work” is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the “Linked
+Version”.
+
+The “Minimal Corresponding Source” for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The “Corresponding Application Code” for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+### 1. Exception to Section 3 of the GNU GPL
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+### 2. Conveying Modified Versions
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+* **a)** under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+* **b)** under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+### 3. Object Code Incorporating Material from Library Header Files
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+* **a)** Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+* **b)** Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+### 4. Combined Works
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+* **a)** Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+* **b)** Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+* **c)** For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+* **d)** Do one of the following:
+    - **0)** Convey the Minimal Corresponding Source under the terms of this
+License, and the Corresponding Application Code in a form
+suitable for, and under terms that permit, the user to
+recombine or relink the Application with a modified version of
+the Linked Version to produce a modified Combined Work, in the
+manner specified by section 6 of the GNU GPL for conveying
+Corresponding Source.
+    - **1)** Use a suitable shared library mechanism for linking with the
+Library.  A suitable mechanism is one that **(a)** uses at run time
+a copy of the Library already present on the user's computer
+system, and **(b)** will operate properly with a modified version
+of the Library that is interface-compatible with the Linked
+Version.
+
+* **e)** Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option **4d0**, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option **4d1**, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+### 5. Combined Libraries
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+* **a)** Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+* **b)** Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+### 6. Revised Versions of the GNU Lesser General Public License
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License “or any later version”
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

README.md

@@ -0,0 +1,13 @@
+# Node File System Adapter
+
+This is a small library that uses Node
+[Web Streams](https://nodejs.org/api/webstreams.html#nodejs-streams-interoperability) and
+[Blobs](https://nodejs.org/api/buffer.html#class-blob) to implement
+[FileSystemDirectoryHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemDirectoryHandle),
+allowing you to use or develop libraries compatible with both node and web with file system access.
+
+Note that this library cannot provide the same security as the browser implementation,
+since malicious code can detect and use the node filesystem API directly.
+`getDirectoryHandle` and `getFileHandle` will still reject paths with seperators,
+preventing normal code from accessing files above the directory handle,
+but the class constructors (which are not present in the web filesystem api) have no such limitations.

package-lock.json

@@ -4,10 +4,13 @@
   "requires": true,
   "packages": {
     "": {
+      "name": "node-file-system-adapter",
       "dependencies": {
+        "mime": "^4.1.0"
+      },
+      "devDependencies": {
         "@types/node": "^25.0.3",
         "@types/web": "^0.0.310",
-        "mime": "^4.1.0",
         "typescript": "^5.9.3"
       }
     },
@@ -15,6 +18,7 @@
       "version": "25.0.3",
       "resolved": "https://registry.npmjs.org/@types/node/-/node-25.0.3.tgz",
       "integrity": "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==",
+      "dev": true,
       "license": "MIT",
       "dependencies": {
         "undici-types": "~7.16.0"
@@ -24,6 +28,7 @@
       "version": "0.0.310",
       "resolved": "https://registry.npmjs.org/@types/web/-/web-0.0.310.tgz",
       "integrity": "sha512-XN++V7UZGEeRg8MXJBkzMqmcAWoCRN1UV/zpQxg9YnJQ9pIPSuzEG7oidC+nXi/J8pmfb3UgFv+TjEDzMiNnRg==",
+      "dev": true,
       "license": "Apache-2.0"
     },
     "node_modules/mime": {
@@ -45,6 +50,7 @@
       "version": "5.9.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
       "license": "Apache-2.0",
       "bin": {
         "tsc": "bin/tsc",
@@ -58,6 +64,7 @@
       "version": "7.16.0",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",
       "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==",
+      "dev": true,
       "license": "MIT"
     }
   }

package.json

@@ -1,8 +1,22 @@
 {
+  "name": "node-file-system-adapter",
+  "main": "dist/NodeFileSystemDirectoryHandle.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "scripts": {
+    "prepack": "tsc",
+    "pretest": "tsc",
+    "test": "node scripts/test.ts"
+  },
   "dependencies": {
+    "mime": "^4.1.0"
+  },
+  "devDependencies": {
     "@types/node": "^25.0.3",
     "@types/web": "^0.0.310",
-    "mime": "^4.1.0",
     "typescript": "^5.9.3"
   }
 }

scripts/test.ts

@@ -0,0 +1,16 @@
+import NodeFileSystemDirectoryHandle from '../dist/NodeFileSystemDirectoryHandle.js'
+
+const cwd_directory_handle = new NodeFileSystemDirectoryHandle('.')
+const test_directory_handle=await cwd_directory_handle.getDirectoryHandle('test',{'create':true})
+const file_handle = await test_directory_handle.getFileHandle('test.txt', { 'create': true })
+const writable = await file_handle.createWritable()
+writable.write('Hello World!')
+writable.close()
+const file = await file_handle.getFile()
+const file_text = await file.text()
+console.log(file_text)
+const result = await cwd_directory_handle.getFileHandle('test/test.txt').catch(error => 'blocked path traversal')
+if (typeof result === 'string') console.log(result)
+else console.error('path traversal not blocked')
+cwd_directory_handle.removeEntry('test',{recursive:true})
+console.log('test complete')

src/NodeFile.ts

@@ -1,35 +0,0 @@
-import * as fs from "node:fs";
-import * as fsp from "node:fs/promises";
-import * as path from "node:path";
-import mime from 'mime'
-
-export default class NodeFile implements File {
-    lastModified: number;
-    name: string;
-    webkitRelativePath: string;
-    size: number;
-    type: string;
-    constructor(name: string) {
-        this.name = path.normalize(name)
-        const stats = fs.lstatSync(name)
-        this.lastModified = stats.mtimeMs
-        this.size = stats.size
-        this.type = mime.getType(name.split('.').pop())
-    }
-    arrayBuffer(): Promise<ArrayBuffer> {
-        throw new Error("Method not implemented.");
-    }
-    bytes(): Promise<Uint8Array<ArrayBuffer>> {
-        return fsp.readFile(this.name)
-    }
-    slice(start?: number, end?: number, contentType?: string): Blob {
-        throw new Error("Method not implemented.");
-    }
-    stream(): ReadableStream<Uint8Array<ArrayBuffer>> {
-        throw new Error("Method not implemented.");
-    }
-    text(): Promise<string> {
-        return fsp.readFile(this.name,'utf8')
-    }
-    
-}

src/NodeFileSystemDirectoryHandle.ts

@@ -1,63 +1,67 @@
 import * as fs from 'node:fs';
-import * as fsp from 'node:fs/promises';
+import * as asyncfs from 'node:fs/promises';
 import * as path from 'node:path';
-import NodeFileSystemHandle from './NodeFileSystemHandle';
-import NodeFileSystemFileHandle from './NodeFileSystemFileHandle';
+import NodeFileSystemHandle from './NodeFileSystemHandle.js';
+import NodeFileSystemFileHandle from './NodeFileSystemFileHandle.js';
 
 export default class NodeFileSystemDirectoryHandle extends NodeFileSystemHandle implements FileSystemDirectoryHandle {
     declare kind: "directory";
-    declare name: string;
-    constructor(name: string, options?: FileSystemGetDirectoryOptions) {
+    constructor(fpath: string, options: FileSystemGetDirectoryOptions = {}) {
         super()
-        name=path.normalize(name)
-        if (!fs.existsSync(name) && options.create) fs.mkdirSync(name)
-        if (!fs.lstatSync(name).isDirectory()) throw new Error('not a directory')
-        this.name=name
+        fpath = path.normalize(fpath)
+        if (!fs.existsSync(fpath) && options.create) fs.mkdirSync(fpath)
+        if (!fs.lstatSync(fpath).isDirectory()) throw new Error('not a directory')
+        this.path = fpath
     }
-    entries(): FileSystemDirectoryHandleAsyncIterator<[string, FileSystemDirectoryHandle | FileSystemFileHandle]> {
-        const entries: Array<[string, FileSystemDirectoryHandle | FileSystemFileHandle]>=[]
-        fs.readdirSync(this.name).forEach(name => {
+    entries(): FileSystemDirectoryHandleAsyncIterator<[string, NodeFileSystemDirectoryHandle | NodeFileSystemFileHandle]> {
+        const entries: Array<[string, NodeFileSystemDirectoryHandle | NodeFileSystemFileHandle]> = []
+        fs.readdirSync(this.path).forEach(name => {
             if (fs.lstatSync(name).isDirectory()) {
-                entries.push([name,new NodeFileSystemDirectoryHandle(path.join(this.name, name))])
+                entries.push([name, new NodeFileSystemDirectoryHandle(path.join(this.path, name))])
             } else {
-                entries.push([name, new NodeFileSystemFileHandle(path.join(this.name, name))])
+                entries.push([name, new NodeFileSystemFileHandle(path.join(this.path, name))])
             }
         })
         return entries[Symbol.asyncIterator]
     }
     keys(): FileSystemDirectoryHandleAsyncIterator<string> {
-        return fs.readdirSync(this.name)[Symbol.asyncIterator]
+        return fs.readdirSync(this.path)[Symbol.asyncIterator]
     }
-    values(): FileSystemDirectoryHandleAsyncIterator<FileSystemDirectoryHandle | FileSystemFileHandle> {
-        const values: Array<FileSystemDirectoryHandle | FileSystemFileHandle> = [];
-        fs.readdirSync(this.name).forEach(name => {
+    values(): FileSystemDirectoryHandleAsyncIterator<NodeFileSystemDirectoryHandle | NodeFileSystemFileHandle> {
+        const values: Array<NodeFileSystemDirectoryHandle | NodeFileSystemFileHandle> = [];
+        fs.readdirSync(this.path).forEach(name => {
             if (fs.lstatSync(name).isDirectory()) {
-                values.push(new NodeFileSystemDirectoryHandle(path.join(this.name,name)))
+                values.push(new NodeFileSystemDirectoryHandle(path.join(this.path, name)))
             } else {
-                values.push(new NodeFileSystemFileHandle(path.join(this.name, name)))
+                values.push(new NodeFileSystemFileHandle(path.join(this.path, name)))
             }
         })
         return values[Symbol.asyncIterator]
     }
-    async getDirectoryHandle(name: string, options?: FileSystemGetDirectoryOptions): Promise<FileSystemDirectoryHandle> {
-        return new NodeFileSystemDirectoryHandle(path.join(this.name, name),options)
+    #getValidatedPath(name: string) {
+        name = path.normalize(name)
+        if (name.includes(path.sep)) throw new TypeError('Invalid Filename')
+        return path.join(this.path, name)
     }
-    async getFileHandle(name: string, options?: FileSystemGetFileOptions): Promise<FileSystemFileHandle> {
-        return new NodeFileSystemFileHandle(path.join(this.name,name),options)
+    async getDirectoryHandle(name: string, options: FileSystemGetDirectoryOptions = {}): Promise<NodeFileSystemDirectoryHandle> {
+        return new NodeFileSystemDirectoryHandle(this.#getValidatedPath(name), options)
     }
-    removeEntry(name: string, options?: FileSystemRemoveOptions): Promise<void> {
-        return fsp.rm(name,{'recursive':options.recursive,"force":options.recursive})
+    async getFileHandle(name: string, options: FileSystemGetFileOptions = {}): Promise<NodeFileSystemFileHandle> {
+        return new NodeFileSystemFileHandle(this.#getValidatedPath(name), options)
+    }
+    async removeEntry(name: string, options: FileSystemRemoveOptions = { recursive: false }): Promise<void> {
+        return asyncfs.rm(this.#getValidatedPath(name), { recursive: options.recursive, force: options.recursive })
     }
     async resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null> {
         if (typeof possibleDescendant !== typeof this) return null
-        let thisName = this.name
+        let thisName = this.path
         let possibleDescendantName = possibleDescendant.name
-        if (!path.isAbsolute(this.name)) thisName = path.join(process.cwd(), this.name)
+        if (!path.isAbsolute(this.path)) thisName = path.join(process.cwd(), this.path)
         if (!path.isAbsolute(possibleDescendant.name)) possibleDescendantName = path.join(process.cwd(), possibleDescendant.name)
         if (!possibleDescendantName.startsWith(thisName)) return null
         possibleDescendantName = possibleDescendantName.substring(thisName.length - 1)
         if (possibleDescendantName[0] == path.sep) possibleDescendantName = possibleDescendantName.substring(1)
         return possibleDescendantName.split(path.sep)
     }
-    [Symbol.asyncIterator]=this.entries
+    [Symbol.asyncIterator] = this.entries
 }

src/NodeFileSystemFileHandle.ts

@@ -1,25 +1,27 @@
 import * as fs from 'node:fs';
-import * as fsp from 'node:fs/promises';
+import * as asyncfs from 'node:fs/promises';
 import * as path from 'node:path';
-import NodeFileSystemHandle from './NodeFileSystemHandle';
-import NodeFileSystemWriteableFileStream from './NodeFileSystemWriteableFileStream';
-import NodeFile from './NodeFile';
+import NodeFileSystemHandle from './NodeFileSystemHandle.js';
+import NodeFileSystemWritableFileStream from './NodeFileSystemWriteableFileStream.js';
 
 export default class NodeFileSystemFileHandle extends NodeFileSystemHandle implements FileSystemFileHandle {
     declare kind: "file";
-    declare name: string;
-    constructor(name: string, options?: FileSystemGetFileOptions) {
+    constructor(fpath: string, options: FileSystemGetFileOptions={}) {
         super()
-        name=path.normalize(name)
-        if (!fs.existsSync(name) && options.create) fs.writeFileSync(name,'')
-        if (fs.lstatSync(name).isDirectory()) new Error('not a file')
-        this.name=name
+        fpath = path.normalize(fpath)
+        if (!fs.existsSync(fpath) && options.create) fs.writeFileSync(fpath, '')
+        if (fs.lstatSync(fpath).isDirectory()) new Error('not a file')
+        this.path = fpath
     }
-    async createWritable(options?: FileSystemCreateWritableOptions): Promise<FileSystemWritableFileStream> {
-        return new NodeFileSystemWriteableFileStream(this.name,options)
+    async createWritable(options: FileSystemCreateWritableOptions = {}): Promise<FileSystemWritableFileStream> {
+        return new NodeFileSystemWritableFileStream(this.path,options)
     }
     async getFile(): Promise<File> {
-        return new NodeFile(this.name)
+        const stats = await asyncfs.stat(this.path)
+        return asyncfs.readFile(this.path).then(buffer => Object.assign(new Blob([buffer]), {
+            lastModified: stats.mtimeMs,
+            name: this.path,
+            webkitRelativePath: this.path
+        }))
     }
-    
 }

src/NodeFileSystemHandle.ts

@@ -2,7 +2,8 @@ import * as path from 'node:path'
 
 export default class NodeFileSystemHandle implements FileSystemHandle {
     kind: FileSystemHandleKind;
-    name: string;
+    path: string;
+    get name() { return path.basename(this.path) }
     async isSameEntry(other: FileSystemHandle): Promise<boolean> {
         if (typeof other != typeof this) return false
         let thisName = this.name

src/NodeFileSystemWriteableFileStream.ts

@@ -1,31 +1,38 @@
 import * as fs from 'node:fs'
-import * as fsp from 'node:fs/promises'
+import * as asyncfs from 'node:fs/promises'
+import * as path from 'node:path'
+import { Writable } from 'node:stream'
 
-export default class NodeFileSystemWriteableFileStream implements FileSystemWritableFileStream {
-    #name:string
-    constructor(name: string, options?: FileSystemCreateWritableOptions) {
-        if (options.keepExistingData) {
-            
-        }
-        this.#name=name
+export default class NodeFileSystemWritableFileStream extends WritableStream implements FileSystemWritableFileStream {
+    #seek_position = 0
+    #name: string
+    constructor(name: string, options: FileSystemCreateWritableOptions={}) {
+        name = path.normalize(name)
+        super(Writable.toWeb(fs.createWriteStream(name)))
+        this.#name = name
+        if(!options.keepExistingData) this.truncate(0)
     }
-    seek(position: number): Promise<void> {
-        throw new Error("Method not implemented.");
+    async seek(position: number): Promise<void> {
+        this.#seek_position = position
     }
     truncate(size: number): Promise<void> {
-        return fsp.truncate(this.#name,size)
+        return asyncfs.truncate(this.#name, size)
     }
-    async write(data: FileSystemWriteChunkType): Promise<void> {
-        return fsp.writeFile(this.#name,(data as string))
-    }
-    locked: boolean;
-    abort(reason?: any): Promise<void> {
-        throw new Error("Method not implemented.");
-    }
-    close(): Promise<void> {
-        throw new Error("Method not implemented.");
-    }
-    getWriter(): WritableStreamDefaultWriter<any> {
-        throw new Error("Method not implemented")
+    async write(wdata: FileSystemWriteChunkType): Promise<void> {
+        if (wdata instanceof Blob) wdata = await wdata.bytes()
+        if (typeof wdata === 'string') wdata = new TextEncoder().encode(wdata)
+        let wsize: number = null
+        let pseek_position = this.#seek_position
+        if ((wdata as WriteParams).type) {
+            const { type, position, size, data } = (wdata as WriteParams)
+            if (type === 'truncate') return asyncfs.truncate(this.#name, size)
+            if (position) this.#seek_position = position
+            if (type === 'seek') return
+            if (size) wsize = size
+            wdata = data
+        }
+        const file = await asyncfs.open(this.#name,'r+')
+        await file.write((wdata as Uint8Array), null, wsize, this.#seek_position)
+        this.#seek_position = pseek_position
     }
 }