Implement File class

[jimmywarting]

I think a File class would be useful to implement also, it's a quite simple class that only extends Blob with two properties name and lastModified, it dose not have to do much else beside also being transferable.

File is a fundamental building block for aligning with more Web Platform APIs such as FormData, native File System Access and even node:fs itself... the simplast solution to save it being await fsPromises.writeFile(path, blob.stream()) as it supports async iterable streams

A step in appending a blob to FormData is to convert blobs to a File instance (to give it a name) and make it possible to serialize the FormData when you iterate over all entries. Or getting a entry with formData.get(field)
FormData is a desired tool for all those folks who wants to see support for window.fetch in core

fetch-blob just added a File class as well, we saw many ppl extending fetch-blob with a own File class and wanted to remove that burdan for everyone so everybody could use the same instances instead.

Therefore we also added a utility fn that could create a File from a path. fileFrom(path, [mimetype]) and fileFromSync(path, [mimetype]) which i hope to see being implemented into fs one day (#37340).

(in fetch-blob it first create a BlobDataItem (that is similar to what a Blob looks like but don't read anything into memory, it backed up by the filesystem instead) and then wrap it with a File class new File([BlobDataItem], name, { type }))

[jimmywarting]

I would like to help and make a PR that implements this, but I have never contributed or looked into the code before (write test & documentation, making transferable items and more) but what i could do is to contribute with a File class that i think could be helpful and help review anyone who make a PR

/*  ./node/lib/internal/blob.js */

const kName = Symbol('kName');
const kLastModified = Symbol('kLastModified');

class InternalFile extends JSTransferable {
  constructor(handle, length, name, lastModified, type = '') {
    super([], '');
    this[kHandle] = handle;
    this[kType] = type;
    this[kLength] = length;
    this[kName] = name;
    this[kLastModified] = lastModified;
  }
}

class File extends Blob {
  constructor(fileBits, fileName, options = {}) {
    emitExperimentalWarning('buffer.File');
    if (arguments.length < 2) {
      throw new TypeError(`Failed to construct 'File': 2 arguments required, but only ${arguments.length} present.`);
    }
    super(fileBits, options);

    const modified = Number(options.lastModified);
    this[kLastModified] = Number.isNaN(modified) ? Date.now() : modified;
    this[kName] = fileName;
  }

  get name() { return this[kName]; }

  get lastModified() { return this[kLastModified]; }

  [kClone]() {
    return {
      data: {
        handle: this[kHandle],
        type: this[kType],
        length: this[kLength],
        lastModified: this[kLastModified],
        name: this[kName]
      },
      deserializeInfo: 'internal/file:InternalFile'
    };
  }

  [kDeserialize](data) {
    this[kHandle] = data.handle;
    this[kType] = data.type;
    this[kLength] = data.length;
    this[kLastModified] = data.lastModified;
    this[kName] = data.name;
  }
}

ObjectDefineProperty(File.prototype, SymbolToStringTag, {
  configurable: true,
  value: 'File'
});

InternalFile.prototype.constructor = File;
ObjectSetPrototypeOf(InternalFile.prototype, File.prototype);

[targos]

@jasnell probably has some ideas on this topic.

[jasnell]

Yeah I've been planning on this implementing this for a while but need to get some other bits done first. The Blob impl, for instance, needs to be finished to allow for this

[jimmywarting]

undici have also implementing this file class into theirs fetch implementation.

So there is currently a round about way of getting a file class now i suppose?
requires --experimental-fetch + node v17.5

import { Blob } from 'node:buffer'

const { constructor: FormData } = await new Response(new URLSearchParams()).formData()
const fd = new FormData()
fd.set('x', new Blob())
const File = fd.get('x').constructor

new File([], '') instanceof Blob // ???

supposedly their formdata implementation also accepts 3th party blobs look a like items? so is File really a instances of Blob?