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?

[MKRhere]

Since Node vendors undici, it should be a matter of exposing https://github.com/nodejs/node/blob/3d49437262e4365dd25ce6009b41c205f930bcd5/deps/undici/src/lib/fetch/file.js

Am I missing something?

[MKRhere]

From a naive glance, it looks like adding File to this list should suffice:

node/lib/internal/process/pre_execution.js

Lines 235 to 240 in 3d49437

	ObjectDefineProperties(globalThis, {
	FormData: lazyInterface('FormData'),
	Headers: lazyInterface('Headers'),
	Request: lazyInterface('Request'),
	Response: lazyInterface('Response'),
	});

[jimmywarting]

The weird thing is that they have 2 kinds of File classes. One that extends native Blob and another File like class that can not be structuredClonable or sent via post message to other workers or with object urls.
The file like class can accept other 3rh party blobs that can be backed up by custom filesystem

[KhafraDev]

The spec-compliant File could be exposed after nodejs/undici#1687, I don't think there's anything holding it back anymore?

[isker]

Sorry to ping on this old issue, but is there a reason this wasn't added to the global object in #45139 like Blob and many other web APIs? I can open a new issue for that if it's appropriate.

CC @KhafraDev.

[KhafraDev]

#47153

[jasnell]

@isker ... To answer the specific question: we generally don't add experimental new apis to the global scope until they graduate from experimental.

[isker]

#47153

Thanks!

@isker ... To answer the specific question: we generally don't add experimental new apis to the global scope until they graduate from experimental.

Well, scroll down this and observe all the experimental fetch APIs on global 😬.

[jasnell]

Yes, I know it hasn't been applied consistently. That's the intent but doesn't always happen. Either way, #47153 should get this one there.

[jasnell]

I'd also just stress the new part of that. The experimental APIs that are global currently were not global when they were first introduced.

[jimmywarting]

• There is just but a tiny thing i discovered about disc based blob not being transferable across workers a few days ago.

• And then i think there is the kuku problem about the meta key/value type all being casted to all lowercase ( Implementations allow all values in type getter w3c/FileAPI#43 )
  It currently doesn't use "parse a MIME type", but it should.

but i don't think this 2 should be such a huge blocker. for adding it to the global scope

[KhafraDev]

Neither of those are issues with File, but with Blob. And that's if you consider 2 an issue when it matches other implementations and the spec isn't clear.

Undici's File class does strictly follow the spec, which seemingly doesn't cause issues, but I don't think so either approach is wrong.