@devappd/nodejs-html5-file-api

0.11.0 • Public • Published

file-api

HTML5 FileAPI implemented in Node.js

The goal here is to be able to use this in connection with jsdom to create test utilities, possibly scraping utilities, ultimately an API-driven browser written in Node.

Usage

Install:

npm install file-api

Use:

var FileAPI = require('file-api')
  , File = FileAPI.File
  , FileList = FileAPI.FileList
  , FileReader = FileAPI.FileReader
  ;

API

Since HTML5 FileAPI has been described by the W3C (terse, technical) and Mozilla Developer Center (understandable, end-user-oriented) in detail, I'll just highlight the differences:

  • File is not (yet) a subclass of Blob
  • FileError and FileException are not yet implemented (they use Error instead)
  • blob: scheme and remote URI schemes are not yet implemented

FormData

FormData on MDN

Has the special method setNodeChunkedEncoding()

File

node-mime is used for extension-based automatic ContentType detection (uses name if available, or path if not)

File(StringUriPath)

var file = new File("./files/myfile.txt");

File({ buffer: Node.Buffer })

var file = new File({ 
  name: "abc-song.txt",   // required
  type: "text/plain",     // optional
  buffer: new Buffer("abcdefg,hijklmnop, qrs, tuv, double-u, x, y and z")
});

File({ stream: Node.ReadStream })

var file = new File({
  name: "abc-song.txt",       // required
  type: "text/plain",         // optional
  stream: new EventEmitter()  // a read stream (emits `error`, `data`, `end`)
});

process.nextTick(function () {
  file.stream.emit('data', "abcdefg,hijklmnop, qrs, tuv, double-u, x, y and z");
  file.stream.emit('end');
});

File(Object)

var file = new File({
  path: "./files/myfile.txt",   // path of file to read


  buffer: Node.Buffer,          // use this Buffer instead of reading file


  stream: Node.ReadStream,      // use this ReadStream instead of reading file


  name: "SomeAwesomeFile.txt",  // optional when using `path`
                                // must be supplied when using `Node.Buffer` or `Node.ReadStream`


  type: "text/plain",           // generated based on the extension of `name` or `path`


  jsdom: true,                  // be DoM-like and immediately get `size` and `lastModifiedDate`
                                // [default: false]


  async: true,                  // use `fs.stat` instead of `fs.statSync` for getting 
                                // the `jsdom` info
                                // [default: false]


  lastModifiedDate: fileStat.mtime.toISOString(),


  size: fileStat.size || Buffer.length
);

File(Array[ArrayBuffer], String, Object)

var file = new File(
  [ [ 0x0, 0x1, 0xFF, ... ] ],   // required, file bits

  "myfile.txt",                  // required, filename

  {
    type: "text/plain",          // optional, MIME type. Otherwise, generated based on filename
    lastModified: 1611162000     // optional, date modified. Defaults to Date.now()
  }
);

FileReader

FileReader.setNodeChunkedEncoding() is a non-standard method which hints that the FileReader should chunk if possible

I.E. The file will be sent with the header Transfer-Encoding: chunked

The default is false since many webservers do not correctly implement the standard correctly, and hence do not expect or accept Transfer-Encoding: chunked from clients.

FileReader.on is a non-standard alias of addEventListener

EventTarget.target.nodeBufferResult is a non-standard property which is a Node.Buffer instance of the data.

FileReader.on('data', fn) is a non-standard event which passes a Node.Buffer chunk each time the progress event is fired.

var fileReader = new FileReader();

fileReader.setNodeChunkedEncoding(true || false);
fileReader.readAsDataURL(new File('./files/my-file.txt'));

// non-standard alias of `addEventListener` listening to non-standard `data` event
fileReader.on('data', function (data) {
  console.log("chunkSize:", data.length);
});

// `onload` as listener
fileReader.addEventListener('load', function (ev) {
  console.log("dataUrlSize:", ev.target.result.length);
});

// `onloadend` as property
fileReader.onloadend', function () {
  console.log("Success");
});

FileList

The browser has no constructor for this. Node has two.

new FileList(f1, f2, ...)

var fileList = new FileList(file1, file2, file3);

new FileList([f1, f2])

var files = [
    new File('./files/blob.bin'),
    new File('./files/image.jpg'),
    new File('./files/readme.txt')
  ],
  fileList;

fileList = new FileList(files);

Formal Documentation

W3C

Mozilla Developer Center:

TODO

//
// TODO
//
// HTML5 File URI should be implemented
//   will need non-ahr 301-handling requester not prevent circular dep
//
// File should be a subclass of Blob
//
// jsdom EventTarget // http://aptana.com/reference/html/api/EventTarget.html
//    target.result
// 
// jsdom ProgressEvent // http://www.w3.org/TR/progress-events/
//    lengthComputable
//    loaded
//    total
//    initProgressEvent

Readme

Keywords

Package Sidebar

Install

npm i @devappd/nodejs-html5-file-api

Weekly Downloads

31

Version

0.11.0

License

Apache

Unpacked Size

19.5 kB

Total Files

4

Last publish

Collaborators

  • devappd