extract-files

What is extract-files?

The extract-files package is designed to extract files from a JavaScript object tree so they can be uploaded via a multipart request. It is commonly used in applications that need to handle file uploads, especially in the context of GraphQL operations.

What are extract-files's main functionalities?

Extract files from an object

This feature allows you to extract files from an object, which is useful when preparing files for upload. The `extractFiles` function takes an object and a path to traverse within the object to find files. It returns an object with the extracted files and a clone of the original object with files replaced by null.

{"operation": "const { extractFiles } = require('extract-files');\nconst file = new File(['content'], 'file.txt', { type: 'text/plain' });\nconst operation = { variables: { file } };\nconst { files, clone } = extractFiles(operation, 'variables');"}

Support for FileList and Map objects

The package can handle `FileList` objects, which are typically obtained from file input elements, and `Map` objects. It can extract files from these complex structures, making it versatile for various file upload scenarios.

{"operation": "const { extractFiles } = require('extract-files');\nconst fileList = document.querySelector('input[type=file]').files;\nconst operation = { variables: { files: fileList } };\nconst { files, clone } = extractFiles(operation, 'variables');"}

Other packages similar to extract-files

form-data

The form-data package allows you to create `multipart/form-data` streams to submit files and values via HTTP. It can be used to simulate a form submission with file uploads, similar to extract-files, but it is more focused on constructing the form data itself rather than extracting files from an existing object structure.

busboy

Busboy is a Node.js module for parsing incoming HTML form data, including file uploads. It differs from extract-files in that it is used on the server side to process file uploads, whereas extract-files is typically used on the client side to prepare files for upload.

multer

Multer is a Node.js middleware for handling `multipart/form-data`, primarily used for uploading files. It is similar to busboy but is designed to be used with Express applications. Unlike extract-files, multer is not about extracting files from an object but rather about handling file uploads on the server side.

README

extract-files

Reversibly extracts files from a tree object.

Files are extracted along with their object path to allow reassembly and are replaced with null in the original tree.

Files may be File, Blob and ReactNativeFile instances. FileList instances are converted to arrays and the items are extracted as File instances.

Usage

Install with npm:

npm install extract-files

extractFiles accepts a tree object to extract files from, along with an optional tree path to prefix file paths:

import extractFiles from 'extract-files'
import tree from './tree'

const files = extractFiles(tree, 'tree')

Extracted files are an array:

[{
  path: 'tree.foo',
  file: /* File or Blob instance */
}, {
  path: 'tree.bar.0',
  file: /* File or Blob instance */
}, {
  path: 'tree.bar.1',
  file: /* File or Blob instance */
}]

extractFiles will return an empty array if the tree is not an object or null. The tree itself must not be a file.

React Native

React Native polyfills FormData under the hood and objects with the properties uri, type and name substitute window.File. It would be risky to assume all objects with those properties in a tree are files. Use ReactNativeFile instances within a tree to explicitly mark files:

import extractFiles, { ReactNativeFile } from 'extract-files'

const tree = {
  singleFile: new ReactNativeFile({
    uri: uriFromCameraRoll,
    type: 'image/jpeg',
    name: 'photo.jpg'
  }),
  multipleFiles: ReactNativeFile.list([
    {
      uri: uriFromCameraRoll1,
      type: 'image/jpeg',
      name: 'photo-1.jpg'
    },
    {
      uri: uriFromCameraRoll2,
      type: 'image/jpeg',
      name: 'photo-2.jpg'
    }
  ])
}

const files = extractFiles(tree)

Reassembly

object-path can be used to loop and reinsert the extracted files:

import extractFiles from 'extract-files'
import objectPath from 'object-path'
import tree from './tree'

const files = extractFiles(tree)
const treePath = objectPath(tree)

files.forEach(({ path, file }) => treePath.set(path, file))

FileList instances in an original tree become arrays when reassembled.

Support

• Node.js v6.10+, see package.json engines.
• Browsers >1% usage, see package.json browserslist.
• React Native.

Changelog

3.1.0

Minor

• Added support for Blob types, via #5.

Patch

• Updated dependencies.