Essentials

Filesystem & storage

@stone-js/filesystem gives file access the same treatment as everything else: an abstraction you code against, not a platform's raw fs. You get a storage manager with named disks, typed uploaded files, and helpers that resolve project paths so nothing hard-codes a directory layout.

#Storage disks

A StorageManager exposes named disks; each disk (like LocalFileSystem) implements the same contract. Code against the disk, and swap the driver, local, cloud, in-memory, without touching call sites.

app/Reports.tsts

constructor ({ storage }) { this.disk = storage.disk('local') }

async save (name: string, contents: string) {
  await this.disk.put(`reports/${name}`, contents)
}

async load (name: string) {
  if (!(await this.disk.exists(`reports/${name}`))) return undefined
  return this.disk.get(`reports/${name}`)
}

#The disk contract

Method	Type	Description
get(path)	`(path) => contents`	Read a file.
put(path, contents)	`(path, data) => void`	Write a file.
exists(path)	`(path) => boolean`	Whether a file exists.
delete(path)	`(path) => void`	Remove a file.
copy / move(from, to)	`(from, to) => void`	Copy or move a file.
files(dir)	`(dir) => string[]`	List files in a directory.
url(path)	`(path) => string`	A URL for a stored file, where the driver supports it.

#Uploaded files

A multipart upload arrives as an UploadedFile, read off the event, which you can inspect and store through a disk. This is the file side of the incoming event.

app/Uploads.tsts

@Post('/import')
async import (event: IncomingHttpEvent) {
  const file = event.getFile('csv')            // an UploadedFile
  await this.storage.disk('local').put(`imports/${file.getClientOriginalName()}`, file.getContent())
  return { imported: true }
}

#Path helpers

Resolve project locations without assembling paths by hand. Each helper joins its arguments onto a well-known root, so code stays correct wherever the app is built or run.

Helper	Type	Description
basePath(...p)	`(...string) => string`	From the project root.
appPath(...p)	`(...string) => string`	From the app/ directory.
distPath(...p)	`(...string) => string`	From the build output.
buildPath(...p)	`(...string) => string`	From the build working directory.
tmpPath(...p)	`(...string) => string`	From a temp directory.
getFileHash(path)	`(path) => string`	A content hash for a file.
importModule(path)	`(path) => Promise<mod>`	Dynamically import a module by path.