extract-files-robo v9.0.1

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.

Setup

Install with npm:

npm install extract-files

See the extractFiles documentation to get started.

Support

• Node.js ^10.17.0 || ^12.0.0 || >= 13.7.0
• Browsers > 0.5%, not OperaMini all, not dead
• React Native

API

Table of contents

• class ReactNativeFile
• function extractFiles
• function isExtractableFile
• type ExtractableFile
• type ExtractableFileMatcher
• type ExtractFilesResult
• type ObjectPath
• type ReactNativeFileSubstitute

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.

Examples

Ways to import.

import { ReactNativeFile } from 'extract-files';

import ReactNativeFile from 'extract-files/public/ReactNativeFile.js';

Ways to require.

const { ReactNativeFile } = require('extract-files');

const ReactNativeFile = require('extract-files/public/ReactNativeFile');

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.

Returns: ExtractFilesResult — Result.

Examples

Ways to import.

import { extractFiles } from 'extract-files';

import extractFiles from 'extract-files/public/extractFiles.js';

Ways to require.

const { extractFiles } = require('extract-files');

const extractFiles = require('extract-files/public/extractFiles');

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']

function isExtractableFile

Checks if a value is an extractable file.

Type: ExtractableFileMatcher

Returns: boolean — Is the value an extractable file.

Examples

Ways to import.

import { isExtractableFile } from 'extract-files';

import isExtractableFile from 'extract-files/public/isExtractableFile.js';

Ways to require.

const { isExtractableFile } = require('extract-files');

const isExtractableFile = require('extract-files/public/isExtractableFile');

type ExtractableFile

An extractable file.

Type: File | Blob | ReactNativeFile

type ExtractableFileMatcher

A function that checks if a value is an extractable file.

Type: Function

Returns: boolean — Is the value an extractable file.

See

• isExtractableFile is the default extractable file matcher.

Examples

How to check for the default exactable files, as well as a custom type of file.

import { isExtractableFile } from 'extract-files';

const isExtractableFileEnhanced = (value) =>
  isExtractableFile(value) ||
  (typeof CustomFile !== 'undefined' && value instanceof CustomFile);

type ExtractFilesResult

What extractFiles returns.

Type: object

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

See

• React Native FormData polyfill source.

Examples

A camera roll file.

const fileSubstitute = {
  uri: uriFromCameraRoll,
  name: 'a.jpg',
  type: 'image/jpeg',
};