thomasbertet/extract-files

Reversibly extracts files from an object tree.

extract-files

Clones a value, recursively extracting File, Blob and ReactNativeFile instances with their object paths, replacing them with null. FileList instances are treated as File instance arrays.

Used by GraphQL multipart request spec client implementations such as graphql-react and apollo-upload-client.

Usage

Install with npm:

npm install extract-files

See the extractFiles documentation to get started.

Support

• Node.js v6+
• Browsers > 0.5%, not dead
• React Native

API

Table of contents

• class ReactNativeFile
  • Examples
• function extractFiles
  • Examples
• type ExtractableFile
• type ExtractFilesResult
• type ObjectPath
  • See
  • Examples
• type ReactNativeFileSubstitute
  • See
  • Examples

class ReactNativeFile

Used to mark a React Native File substitute in an object tree for extractFiles. It’s too risky to assume all objects with uri, type and name properties are files to extract.

Parameter	Type	Description
file	ReactNativeFileSubstitute	A React Native File substitute.

Examples

An extractable file in React Native.

import { ReactNativeFile } from 'extract-files'

const file = new ReactNativeFile({
  uri: uriFromCameraRoll,
  name: 'a.jpg',
  type: 'image/jpeg'
})

function extractFiles

Clones a value, recursively extracting File, Blob and ReactNativeFile instances with their object paths, replacing them with null. FileList instances are treated as File instance arrays.

Parameter	Type	Description
value	*	Value (typically an object tree) to extract files from.
path	ObjectPath? = ''	Prefix for object paths for extracted files.

Returns: ExtractFilesResult — Result.

Examples

Extract files from an object.

For the following:

import { extractFiles } from 'extract-files'

const file1 = new File(['1'], '1.txt', { type: 'text/plain' })
const file2 = new File(['2'], '2.txt', { type: 'text/plain' })
const value = {
  a: file1,
  b: [file1, file2]
}

const { clone, files } = extractFiles(value, 'prefix')

value remains the same.

clone is:

{
  a: null,
  b: [null, null]
}

files is a Map instance containing:

Key	Value
file1	['prefix.a', 'prefix.b.0']
file2	['prefix.b.1']

type ExtractableFile

An extractable file.

Type: File | Blob | ReactNativeFile

type ExtractFilesResult

What extractFiles returns.

Type: Object

Property	Type	Description
clone	*	Clone of the original input value with files recursively replaced with null.
files	Map<ExtractableFile, Array<ObjectPath>>	Extracted files and their locations within the original value.

type ObjectPath

String notation for the path to a node in an object tree.

Type: String

See

• object-path on npm.

Examples

Object path is property a, array index 0, object property b.

a.0.b

type ReactNativeFileSubstitute

A React Native File substitute for when using FormData.

Type: Object

Property	Type	Description
uri	String	Filesystem path.
name	String?	File name.
type	String?	File content type.

See

• React Native FormData polyfill source.

Examples

A camera roll file.

{
  uri: uriFromCameraRoll,
  name: 'a.jpg',
  type: 'image/jpeg'
}