Stone.js - Filesystem

A robust, strongly typed ESM utility for safe, contextual file and path management in Stone.js applications.

Overview

The @stone-js/filesystem package is a pure ESM, strongly typed utility library that provides safe and contextual file management capabilities for Stone.js applications. It wraps native Node.js APIs with consistent, expressive, and domain-oriented abstractions to handle files, paths, temporary directories, and project-specific structure resolution.

This package is part of the Stone.js ecosystem, designed to support the Continuum Architecture by exposing a normalized, context-aware interface to filesystem operations across platforms and runtimes.

Key Features

• File inspection, creation, editing, and movement via the File and UploadedFile classes
• Utility functions to resolve:
  • basePath, appPath, distPath, tmpPath, etc.
• Helpers for hashing, MIME detection, and dynamic imports
• Consistent error handling with FilesystemError
• Immutable, encapsulated methods for safety and predictability
• Ideal for use in CLI tools, server runtimes, and adapter layers

Installation

npm install @stone-js/filesystem

[!IMPORTANT] This package is pure ESM. Ensure your package.json includes "type": "module" or configure your bundler appropriately.

Usage

import { File, basePath, getFileHash } from '@stone-js/filesystem'

const file = File.create(basePath('config', 'app.json'))

if (file.isReadable()) {
  console.log(file.getContent())
}

For more examples and a complete guide to path resolution, file mutation, and upload handling, visit the official documentation:

https://stonejs.dev/docs

Learn More

This package is part of the Stone.js ecosystem, a modern JavaScript framework built around the Continuum Architecture.

Explore the full documentation: https://stonejs.dev

API documentation

• API

Contributing

See Contributing Guide