Edit in GitHubLog an issue

storage#

Category: uxp, io, file

storage.Entry#

An Entry is the base class for File and Folder. You'll never instantiate an Entry directly, but it provides the common fields and methods that both File and Folder share.

Info

Important:

  • An Entry object may exist even if the corresponding file/folder on disk does not currently exist.
  • It's possible for multiple Entry objects to represent the same item on disk, for example if the item was picked via multiple separate file picker invocations.

Kind: static class of storage Since: XD 13

entry.name : string#

The name of this entry. Read-only.

Kind: instance property of Entry Read only: true Since: XD 13 Example

Copied to your clipboard
console.log(anEntry.name);

entry.provider : FileSystemProvider#

The associated provider that services this entry. Read-only.

Kind: instance property of Entry Read only: true Since: XD 13 Example

Copied to your clipboard
1if (entryOne.provider !== entryTwo.provider) {
2 throw new Error("Providers are not the same");
3}

entry.url : URL#

The url of this entry. You can use this url as the src attribute of an <img> tag in the UI. Read-only.

Kind: instance property of Entry Read only: true Since: XD 13 Example

Copied to your clipboard
console.log(anEntry.url);

entry.nativePath : string#

The platform native file-system path of this entry. Read-only

Kind: instance property of Entry Read only: true Since: XD 13 Example

Copied to your clipboard
console.log(anEntry.nativePath);

entry.isEntry : boolean#

Indicates that this instance is an Entry. Useful for type-checking.

Kind: instance property of Entry Example

Copied to your clipboard
1if (something.isEntry) {
2 return something.getMetadata();
3}

entry.isFile : boolean#

Indicates that this instance is not a File. Useful for type- checking.

Kind: instance property of Entry Read only: true Example

Copied to your clipboard
1if (!anEntry.isFile) {
2 return "This entry is not a file.";
3}

entry.isFolder : boolean#

Indicates that this instance is not a folder. Useful for type- checking.

Kind: instance property of Entry Read only: true Example

Copied to your clipboard
1if (!anEntry.isFolder) {
2 return "This entry is not a folder.";
3}

entry.toString() ⇒ string#

Returns the details of the given entry like name, type and native path in a readable string format.

Kind: instance method of Entry Since: XD 13

entry.copyTo(folder, options) ⇒ Promise#

Copies this entry to the specified folder.

The Entry object passed to this function will continue to reference the original item - it is not updated to reference the copy.

Kind: instance method of Entry Throws:

  • EntryExists if the attempt would overwrite an entry and overwrite is false
  • PermissionDenied if the underlying file system rejects the attempt
  • OutOfSpace if the file system is out of storage space

Since: XD 13

ParamTypeDefaultDescription
folderFolderthe folder to which to copy this entry
options\*
[options.overwrite]booleanfalseif true, allows overwriting existing entries

Example

Copied to your clipboard
await someFile.copyTo(someFolder);

Example

Copied to your clipboard
await someFile.copyTo(someFolder, {overwrite: true});

Example

Copied to your clipboard
await someFolder.copyTo(anotherFolder, {overwrite: true});

entry.moveTo(folder, options) ⇒ Promise#

Moves this entry to the target folder, optionally specifying a new name.

The Entry object passed to this function is automatically updated to reference the new location, however any other Entry objects referencing the original item will not be updated, and will thus no longer point to an item that exists on disk.

Kind: instance method of Entry Since: XD 13

ParamTypeDefaultDescription
folderFolderthe folder to which to move this entry
options\*
[options.overwrite]booleanfalseIf true allows the move to overwrite existing files
[options.newName]stringIf specified, the entry is renamed to this name

Example

Copied to your clipboard
await someFile.moveTo(someFolder);

Example

Copied to your clipboard
await someFile.moveTo(someFolder, {overwrite: true});

Example

Copied to your clipboard
await someFolder.moveTo(anotherFolder, {overwrite: true});

Example

Copied to your clipboard
await someFile.moveTo(someFolder, {newName: 'masterpiece.txt'})

Example

Copied to your clipboard
await someFile.moveTo(someFolder, {newName: 'novel.txt', {overwrite: true})

entry.delete() ⇒ Promise#

Removes this entry from the file system. If the entry is a folder, you must remove the files inside before removing the folder.

Kind: instance method of Entry Since: XD 13 Example

Copied to your clipboard
await aFile.delete();

entry.getMetadata() ⇒ Promise.<EntryMetadata>#

Returns this entry's metadata.

Kind: instance method of Entry Since: XD 13 Example

Copied to your clipboard
const metadata = await aFile.getMetadata();

storage.EntryMetadata#

Metadata for an entry. It includes useful information such as:

  • size of the file (if a file)
  • date created
  • date modified
  • name

You'll never instantiate an EntryMetadata directly; instead use getMetadata to get metadata for a specific File or Folder entry.

Kind: static class of storage

entryMetadata.name : string#

The name of the entry.

Kind: instance property of EntryMetadata

entryMetadata.size : number#

The size of the entry, if a file. Zero if a folder.

Kind: instance property of EntryMetadata

entryMetadata.dateCreated : Date#

The date this entry was created.

Kind: instance property of EntryMetadata

entryMetadata.dateModified : Date#

The date this entry was modified.

Kind: instance property of EntryMetadata

entryMetadata.isFile : boolean#

Indicates if the entry is a file

Kind: instance property of EntryMetadata

entryMetadata.isFolder : boolean#

Indicates if the entry is a folder

Kind: instance property of EntryMetadata

storage.File#

Represents a file on a file system. Provides methods for reading from and writing to the file. You'll never instantiate a File directly; instead you'll get access via a FileSystemProvider. method such as getFileForOpening().

Kind: static class of storage Since: XD 13

Info

Important:

  • A File object may exist even if the corresponding file on disk does not currently exist.

  • It's possible for multiple File objects to represent the same file on disk, for example if the file was picked via multiple separate file picker invocations.

file.mode : Symbol#

Indicates whether this File object supports read-only or read-write access. See readOnly and readWrite.

Kind: instance property of File Since: XD 13 Example

Copied to your clipboard
1if (aFile.mode === modes.readOnly) {
2 throw new Error("Can't write to a file opened as read-only.");
3}

file.read(options) ⇒ Promise.<(string\|ArrayBuffer)>#

Reads data from the file and returns it. The file format can be specified with the format option. If a format is not supplied, the file is assumed to be a text file using UTF8 encoding.

Kind: instance method of File Returns: Promise.<(string\|ArrayBuffer)> - the contents of the file Since: XD 13

ParamTypeDefaultDescription
optionsObject
[options.format]Symbolformats.utf8Optional. Format to read: one of storage.formats.utf8 or storage.formats.binary.

Example

Copied to your clipboard
const text = await myNovel.read(); // 'text' is a string

Example

Copied to your clipboard
1const data = await myNovel.read({format: formats.binary}); // 'data' is an ArrayBuffer
2console.log("File is " + data.byteLength + " bytes long.");

file.write(data, options)#

Writes data to a file, appending if desired. The format of the file is controlled via the format option, and defaults to UTF8.

Kind: instance method of File Throws:

  • FileIsReadOnly if writing to a read-only file
  • OutOfSpace If writing to the file causes the file system to exceed the available space (or quota)

Since: XD 13

ParamTypeDefaultDescription
datastring | ArrayBufferData to write to the file
optionsObject
[options.format]Symbolformats.utf8Optional. Format to write: storage.formats.utf8 or storage.formats.binary.

Example

Copied to your clipboard
await myNovel.write("It was a dark and stormy night.\n");

Example

Copied to your clipboard
1const data = new Uint8Array([0xFF, 0xA1]);
2await aDataFile.write(data, {format: formats.binary}); // writes a 2-byte file

storage.FileSystemProvider#

Provides access to files and folders on a file system. You don't instantiate this directly; instead you'll use an instance that has already been created for you.

Kind: static class of storage Since: XD 13

fileSystemProvider.getFileForOpening(options) ⇒ Promise.<File> | Promise.<Array.<File>>#

Gets a file (or files) suitable for reading by displaying an "Open" file picker dialog to the user. File entries returned by this API are read-only - use getFileForSaving to get a File entry you can write to.

The user can select multiple files only if the allowMultiple option is true.

Kind: instance method of FileSystemProvider Returns: Promise.<?File> | Promise.<!Array.<File>> - ?File if allowMultiple is false (null if picker canceled); or !Array<File> if allowMultiple is true (length 0 if picker canceled) Since: XD 13

ParamTypeDefaultDescription
optionsObject
[options.types]Array.<string>[&#x27;*&#x27;]Optional. Allowed file extensions, with no "." prefix; use storage.fileTypes.all to allow any file to be picked
[options.allowMultiple]booleanfalseOptional. If true, multiple files can be selected and this API returns Array<File>.

If false, only one file can be selected and this API returns a File directly.

Example

Copied to your clipboard
1const file = await fs.getFileForOpening();
2if (!file) {
3 // file picker dialog was canceled
4 return;
5}
6const text = await file.read();

Example

Copied to your clipboard
1const files = await fs.getFileForOpening({allowMultiple: true, types: fileTypes.images});
2if (files.length === 0) {
3 // no files selected
4}

fileSystemProvider.getFileForSaving(suggestedName, options) ⇒ Promise.<?File>#

Gets a file reference suitable for read-write by displaying a "Save" file picker dialog to the user.

If the act of writing to the file would overwrite it, the file picker will prompt the user to confirm before returning a result to you.

Kind: instance method of FileSystemProvider Returns: Promise.<?File> - returns the selected file, or null if canceled Since: XD 13

ParamTypeDescription
suggestedNamestringRequired. The file extension should match one of the options specified in the types option.
optionsObject
[options.types]Array.<string>Required. Allowed file extensions, with no "." prefix.

Example

Copied to your clipboard
1const file = await fs.getFileForSaving("output.txt", { types: [ "txt" ]});
2if (!file) {
3 // file picker was cancelled
4 return;
5}
6await file.write("It was a dark and stormy night");

fileSystemProvider.getFolder() ⇒ Promise.<?Folder>#

Gets a folder from the file system via a folder picker dialog. The files and folders within can be accessed via getEntries. Any files within are read-write.

If the user cancels the picker, null is returned instead.

Kind: instance method of FileSystemProvider Returns: Promise.<?Folder> - the selected folder or null if picker is canceled. Since: XD 13 Example

Copied to your clipboard
1const folder = await fs.getFolder();
2const myNovel = (await fs.getEntries()).find(entry => entry.name.includes('novel'));
3const text = await myNovel.read();

fileSystemProvider.getTemporaryFolder() ⇒ Promise.<Folder>#

Returns a temporary folder. The contents of the folder may be lost when the host application is closed.

Kind: instance method of FileSystemProvider Since: XD 13 Example

Copied to your clipboard
const temp = await fs.getTemporaryFolder();

fileSystemProvider.getDataFolder() ⇒ Promise.<Folder>#

Returns a folder that can be used for storing plugin-specific data without needing user interaction though a file picker. Its contents remain persistent when the host application is updated and when your plugin is updated.

Kind: instance method of FileSystemProvider Since: XD 13

fileSystemProvider.getPluginFolder() ⇒ Promise.<Folder>#

Returns an plugin's folder – this folder and everything within it are read only. This contains all the Plugin related packaged assets.

Kind: instance method of FileSystemProvider Since: XD 13

fileSystemProvider.getFsUrl(entry) ⇒ URL#

Returns the fs url of given entry.

Kind: instance method of FileSystemProvider

ParamType
entryEntry

fileSystemProvider.getNativePath(entry) ⇒ string#

Returns the platform native file system path of given entry.

Kind: instance method of FileSystemProvider

ParamType
entryEntry

storage.Folder ⇐ Entry#

Represents a folder on a file system. You'll never instantiate this directly, but will get it by calling getTemporaryFolder, getFolder, or via getEntries.

Info

Important:

  • A Folder object may exist even if the corresponding folder on disk does not currently exist.
  • It's possible for multiple Folder objects to represent the same folder on disk, for example if the folder was picked via multiple separate folder picker invocations.

Kind: static class of storage Extends: Entry Since: XD 13

folder.getEntries() ⇒ Promise.<Array.<Entry>>#

Returns an array of entries contained within this folder.

Kind: instance method of Folder Returns: Promise.<Array.<Entry>> - The entries within the folder. Since: XD 13 Example

Copied to your clipboard
1const entries = await aFolder.getEntries();
2const allFiles = entries.filter(entry => entry.isFile);

folder.createFile(name, options) ⇒ Promise.<File>#

Creates a File object within this folder, which need not correspond to a file that exists on disk yet.

Info

Important:

  • If the file already exists on disk (and overwrite is true), creates a File object but does not modify the existing file on disk in any way.
  • If the file does not exist yet, creates a File object but does not create the file on disk yet. You can then use write to create the file and give it content.

Kind: instance method of Folder Returns: Promise.<File> - the created file entry Since: XD 13

ParamTypeDefaultDescription
namestringthe name of the file to create.
optionsObject
[options.overwrite]booleanfalseIf false, the call will fail if the file already exists. If true, the call will succeed regardless of whether the file currently exists on disk.

Example

Copied to your clipboard
const myNovelTxtFile = await aFolder.createFile("mynovel.txt");

folder.createFolder(name) ⇒ Folder#

Creates a Folder object within this folder and creates the folder on disk. Unlike createFile(), this call does modify the disk, and it cannot be used if the folder already exists (use getEntry in that case).

Info

Important:

  • If the folder already exists on disk, fails with an error.
  • If the folder does not exist yet, immediately creates it on disk and then returns a Folder object for it.

Kind: instance method of Folder Returns: Folder - the created folder entry object Since: XD 13

ParamTypeDescription
namestringthe name of the folder to create.

Example

Copied to your clipboard
const myCollectionsFolder = await aFolder.createFolder("collections");

folder.getEntry(filePath) ⇒ Promise.<(File\|Folder)>#

Returns a File or Folder entry for an item that already exists on disk within this folder or its hierarchy of subfolders. Fails if no entry with the given name/path currently exists on disk.

Kind: instance method of Folder Returns: Promise.<(File\|Folder)> - the fetched entry. Since: XD 13

ParamTypeDescription
filePathstringName, with optional relative path prefix, of an existing entry within this folder

Example

Copied to your clipboard
const myNovel = await aFolder.getEntry("mynovel.txt");

folder.renameEntry(entry, newName, options) ⇒ Promise#

Renames an item on disk to a new name within the same folder. The Entry object passed to this function is automatically updated to reference the new name, however any other Entry objects referencing the original item will not be updated, and will thus no longer point to an item that exists on disk.

Kind: instance method of Folder Since: XD 13

ParamTypeDefaultDescription
entryEntryentry to rename (File or Folder). Must exist.
newNamestringthe new name to assign
optionsany
[options.overwrite]booleanfalseif true, renaming can overwrite an existing entry

Example

Copied to your clipboard
await myNovels.rename(myNovel, "myFantasticNovel.txt");

storage.localFileSystem : LocalFileSystemProvider#

Kind: static property of storage

storage.errors : Errors#

Kind: static property of storage

errors.AbstractMethodInvocationError ⇐ Error#

Attempted to invoke an abstract method.

Kind: static class of errors Extends: Error

errors.ProviderMismatchError ⇐ Error#

Attempted to execute a command that required the providers of all entries to match.

Kind: static class of errors Extends: Error

errors.EntryIsNotAnEntryError ⇐ Error#

The object passed as an entry is not actually an Entry.

Kind: static class of errors Extends: Error

errors.EntryIsNotAFolderError ⇐ Error#

The entry is not a folder, but was expected to be a folder.

Kind: static class of errors Extends: Error

errors.EntryIsNotAFileError ⇐ Error#

The entry is not a file, but was expected to be.

Kind: static class of errors Extends: Error

errors.NotAFileSystemError ⇐ Error#

The instance was expected to be a file system, but wasn't.

Kind: static class of errors Extends: Error

errors.OutOfSpaceError ⇐ Error#

The file system is out of space (or quota has been exceeded)

Kind: static class of errors Extends: Error

errors.PermissionDeniedError ⇐ Error#

The file system revoked permission to complete the requested action.

Kind: static class of errors Extends: Error

errors.EntryExistsError ⇐ Error#

An attempt was made to overwrite an entry without indicating that it was safe to do so via overwrite: true.

Kind: static class of errors Extends: Error

errors.FileIsReadOnlyError ⇐ Error#

An attempt was made to write to a file that was opened as read-only.

Kind: static class of errors Extends: Error

errors.DomainNotSupportedError ⇐ Error#

Domain is not supported by the current FileSystemProvider instance.

Kind: static class of errors Extends: Error

errors.InvalidFileNameError ⇐ Error#

The file name contains invalid characters

Kind: static class of errors Extends: Error

storage.fileTypes#

This namespace describes the various file type extensions that can used be used in some FS file open methods.

Kind: static constant of storage

fileTypes.text#

Text file extensions

Kind: static property of fileTypes

fileTypes.images#

Image file extensions

Kind: static property of fileTypes

fileTypes.all#

All file types

Kind: static property of fileTypes

storage.formats#

This namespace describes the file content formats supported in FS methods like read and write.

Kind: static constant of storage

formats.utf8 : Symbol#

UTF8 File encoding

Kind: static property of formats

formats.binary : Symbol#

Binary file encoding

Kind: static property of formats

storage.modes#

This namespace describes the access modes that can be supported by a given File entry.

Kind: static constant of storage

modes.readOnly : Symbol#

The file is read-only; attempts to write will fail.

Kind: static property of modes

modes.readWrite : Symbol#

The file is read-write.

Kind: static property of modes

storage.types#

This namespace describes the type of the entry. Whether file or folder etc.

Kind: static constant of storage

types.file : Symbol#

A file; used when creating an entity

Kind: static property of types

types.folder : Symbol#

A folder; used when creating an entity

Kind: static property of types

Was this helpful?
Copyright © 2021 Adobe. All rights reserved.