Major API revision

[szwacz]

Hello all fs-jetpack users. This project is few years old now, and there are ideas in my head of things that I wish had been done differently from the beginning. I'm thinking about major revision of the API, that will be more logical and elegant.

This is very early idea and can be killed if there is enough push back, so your voice counts :)

One: The library right now has the concept of “directory object”, but is lacking “file object” and I’d love to be able to do sometimes things like:

const logFile = jetpack.file("logfile")
logFile.empty()
logFile.append(data1)
logFile.append(data2)
logFile.copy("some/path")

Two: I was aiming for very elegant API, that just reads well. So for example current way to make empty directory:

jetpack.dir(“foo”, { empty: true })

Can be described in more human readable form:

jetpack.dir(“foo”).empty()

Three: The API can actually be smaller and less clunky. For instance the concept of .cwd() actually is not necessary for API to work, and brings confusion with process.cwd().

So. Finally. The main idea is that there are two main methods:

.file()
.dir()

Those methods don’t do any disk I/O, they just create javascript object representing given path on disk. Next you interact with directory or file under given path by calling sync or async methods on corresponding object. Fully OOP :)

A lot of the methods would be the same on dir and file object, just file won’t take the path as a parameter. So those two lines would be equivalents:

myDir.remove("file.txt")
myDir.file("file.txt").remove()

What do you think?

Do you find some parts of the current API irritating?

[vladcosorg]

Actually that was my initial expectation after starting to use this amazing library. For example when creating a file (and not reading the documentation carefully), I was expecting to receive back a "handle" that would let apply further operations over that file. Totally supporting this change 👍

[eaton]

I just discovered the project (much to my delight) after bashing out a first pass at a similar utility for my own projects. It might be out of scope, but one significant enhancement would be support for additional “smart” read/write formats beyond json.

Json5, JSONLD, csv/tsv, and toml files are examples; perhaps a config object with file extensions mapped to callbacks, passed on when creating a fresh jetpack instace?

other than that, the changes you describe sound excellent.

[szwacz]

Thank you @eaton
This sounds reasonable, but would force everybody who uses the library to download extra libraries for different built in formats, even when they don't plan to use them. So the solution would need to be "extra formats are pluggable, but not built-in".

Regarding status of the project. Right now my biggest problem is that I've changed my career and stopped programming completely. Hopefully incoming winter will force me to contribute again to this project :)

[eaton]

Congratulations on escaping the world of software, hopefully you're busy raising goats while the rest of us growl about CJS/ESM problems. ;D

Regarding the "everyone would have to download extra libraries" problem, I definitely agree that hard-coding the long list of formats would be a problem. I was thinking something along the lines of "A way to add async callbacks to process specific file extensions during read and write operations" — something along the lines of:

const jetpack = require('fs-jetpack')
const JSON5 = require('json5')
const json5handler = {
  encode: (data, options) => JSON5.stringify(data, undefined, options),
  decode: (data, options) => JSON5.parse(data),
}
jetpack('json5', json5handler)

It would require the write and read functions to check for matching handlers based on the file extension they're given, but if that approach seems like it would fit with philosophy of the library, I'm happy to turn the work I'm doing into a patch.