snap-fileio / core

Express router factory for the Snap! File I/O extension. This package provides path-validated file operations over HTTP, designed to be mounted by a host application such as snap-db:

• Plain-text file operations (read, write, append, delete, mkdir, list, exists)
• Structured data support (CSV via PapaParse, JSON with pretty-printing)
• Path validation preventing absolute paths, traversal attacks, and escapes from the configured workspace directory
• Runtime-reconfigurable basePath for workspace switching

The implemented API contract is documented at https://gitlab.com/snap-fileio/api-contract

Usage

const express = require('express');
const { createFileIORouter } = require('@snap-fileio/core');

const app = express();
app.use(express.json());

app.use('/api/v1/fileio', createFileIORouter({
  basePath: '/home/student/Snap-Projects'
}));

app.listen(3000);

The options object is read at request time (not captured in closure), so the caller can mutate options.basePath at runtime — this is how the "Choose Workspace Folder" menu item works in snap-db.

Endpoints

| Method | Route | Description | |---|---|---| | GET | /read | Read file as string | | GET | /readlines | Read file as array of lines | | GET | /list | List directory entries | | GET | /exists | Check if path exists | | GET | /read-csv | Parse CSV (auto-detect or explicit delimiter, dynamic typing) | | GET | /read-json | Parse JSON file | | POST | /write | Create or overwrite a file | | POST | /append | Append to a file | | POST | /mkdir | Create a directory (recursive) | | POST | /write-csv | Write CSV with configurable delimiter | | POST | /write-json | Write JSON with 2-space indentation | | DELETE | /delete | Delete a file |

Testing

Tests use Jest and supertest against a temporary directory — no external services required:

npm test

License

The Snap! File I/O core package is free software. You may redistribute and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.