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.
npm install @nexusapp/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.
Install with npm:
``shell`
npm install extract-files
See the extractFiles documentation to get started.
- Node.js ^10.17.0 || ^12.0.0 || >= 13.7.0
- Browsers
- React Native
- class ReactNativeFile
- function extractFiles
- function isExtractableFile
- type ExtractableFile
- type ExtractableFileMatcher
- type ExtractFilesResult
- type ObjectPath
- type ReactNativeFileSubstitute
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
_Ways to import._
> `js`
> import { ReactNativeFile } from 'extract-files';
>
>
> js`
> import ReactNativeFile from 'extract-files/public/ReactNativeFile.js';
>
_Ways to require._
> `js`
> const { ReactNativeFile } = require('extract-files');
>
>
> js`
> const ReactNativeFile = require('extract-files/public/ReactNativeFile');
>
_An extractable file in React Native._
> `js`
> import { ReactNativeFile } from 'extract-files';
>
> const file = new ReactNativeFile({
> uri: uriFromCameraRoll,
> name: 'a.jpg',
> type: 'image/jpeg',
> });
>
---
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. |isExtractableFile
| | ExtractableFileMatcher? = isExtractableFile | The function used to identify extractable files. |parentAddFile
| | Map? | Parent's addFile function. |
Returns: ExtractFilesResult — Result.
#### Examples
_Ways to import._
> `js`
> import { extractFiles } from 'extract-files';
>
>
> js`
> import extractFiles from 'extract-files/public/extractFiles.js';
>
_Ways to require._
> `js`
> const { extractFiles } = require('extract-files');
>
>
> js`
> const extractFiles = require('extract-files/public/extractFiles');
>
_Extract files from an object._
> For the following:
>
> `js`
> 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');
>
>
> remains the same.clone
>
> is:`
>
> json`
> {
> "a": "0",
> "b": ["0", "1"]
> }
>
>
> is a Map instance containing:file1
>
> | Key | Value |
> | :------ | :---------------------------------- |
> | | ['0', ['prefix.a', 'prefix.b.0']] |file2
> | | ['1', ['prefix.b.1']] |
---
Checks if a value is an extractable file.
Type: ExtractableFileMatcher
| Parameter | Type | Description |
| :-------- | :--- | :-------------- |
| value | \* | Value to check. |
Returns: boolean — Is the value an extractable file.
#### Examples
_Ways to import._
> `js`
> import { isExtractableFile } from 'extract-files';
>
>
> js`
> import isExtractableFile from 'extract-files/public/isExtractableFile.js';
>
_Ways to require._
> `js`
> const { isExtractableFile } = require('extract-files');
>
>
> js`
> const isExtractableFile = require('extract-files/public/isExtractableFile');
>
---
An extractable file.
Type: File | Blob | ReactNativeFile
---
A function that checks if a value is an extractable file.
Type: Function
| Parameter | Type | Description |
| :-------- | :--- | :-------------- |
| value | \* | Value to check. |
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._
> `js`
> import { isExtractableFile } from 'extract-files';
>
> const isExtractableFileEnhanced = (value) =>
> isExtractableFile(value) ||
> (typeof CustomFile !== 'undefined' && value instanceof CustomFile);
>
---
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. |
---
String notation for the path to a node in an object tree.
Type: string
#### See
#### Examples
_Object path is property a, array index 0, object property b._
> a.0.b
---
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._
> `js``
> const fileSubstitute = {
> uri: uriFromCameraRoll,
> name: 'a.jpg',
> type: 'image/jpeg',
> };
>