storage

Category: uxp, io, file

• storage
  • .Entry
    • .name : string
    • .provider : FileSystemProvider
    • .url : URL
    • .nativePath : string
    • .isEntry : boolean
    • .isFile : boolean
    • .isFolder : boolean
    • .toString() ⇒ string
    • .copyTo(folder, options) ⇒ Promise
    • .moveTo(folder, options) ⇒ Promise
    • .delete() ⇒ Promise
    • .getMetadata() ⇒ Promise.<EntryMetadata>
  • .EntryMetadata
    • .name : string
    • .size : number
    • .dateCreated : Date
    • .dateModified : Date
    • .isFile : boolean
    • .isFolder : boolean
  • .File
    • .mode : Symbol
    • .read(options) ⇒ Promise.<(string\|ArrayBuffer)>
    • .write(data, options)
  • .FileSystemProvider
    • .getFileForOpening(options) ⇒ Promise.<?File> | Promise.<!Array.<File>>
    • .getFileForSaving(suggestedName, options) ⇒ Promise.<?File>
    • .getFolder() ⇒ Promise.<?Folder>
    • .getTemporaryFolder() ⇒ Promise.<Folder>
    • .getDataFolder() ⇒ Promise.<Folder>
    • .getPluginFolder() ⇒ Promise.<Folder>
    • .getFsUrl(entry) ⇒ URL
    • .getNativePath(entry) ⇒ string
  • .Folder ⇐ Entry
    • .getEntries() ⇒ Promise.<Array.<Entry>>
    • .createFile(name, options) ⇒ Promise.<File>
    • .createFolder(name) ⇒ Folder
    • .getEntry(filePath) ⇒ Promise.<(File\|Folder)>
    • .renameEntry(entry, newName, options) ⇒ Promise
  • .localFileSystem : LocalFileSystemProvider
  • .errors : Errors
    • .AbstractMethodInvocationError ⇐ Error
    • .ProviderMismatchError ⇐ Error
    • .EntryIsNotAnEntryError ⇐ Error
    • .EntryIsNotAFolderError ⇐ Error
    • .EntryIsNotAFileError ⇐ Error
    • .NotAFileSystemError ⇐ Error
    • .OutOfSpaceError ⇐ Error
    • .PermissionDeniedError ⇐ Error
    • .EntryExistsError ⇐ Error
    • .FileIsReadOnlyError ⇐ Error
    • .DomainNotSupportedError ⇐ Error
    • .InvalidFileNameError ⇐ Error
  • .fileTypes
    • .text
    • .images
    • .all
  • .formats
    • .utf8 : Symbol
    • .binary : Symbol
  • .modes
    • .readOnly : Symbol
    • .readWrite : Symbol
  • .types
    • .file : Symbol
    • .folder : Symbol

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
  • .provider : FileSystemProvider
  • .url : URL
  • .nativePath : string
  • .isEntry : boolean
  • .isFile : boolean
  • .isFolder : boolean
  • .toString() ⇒ string
  • .copyTo(folder, options) ⇒ Promise
  • .moveTo(folder, options) ⇒ Promise
  • .delete() ⇒ Promise
  • .getMetadata() ⇒ Promise.<EntryMetadata>

entry.name : string

The name of this entry. Read-only.

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

console.log(anEntry.name);
CopyCopied 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

if (entryOne.provider !== entryTwo.provider) {
    throw new Error("Providers are not the same");
}
CopyCopied 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

console.log(anEntry.url);
CopyCopied 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

console.log(anEntry.nativePath);
CopyCopied 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

if (something.isEntry) {
    return something.getMetadata();
}
CopyCopied 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

if (!anEntry.isFile) {
    return "This entry is not a file.";
}
CopyCopied 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

if (!anEntry.isFolder) {
    return "This entry is not a folder.";
}
CopyCopied 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

Example

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

Example

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

Example

await someFolder.copyTo(anotherFolder, {overwrite: true});
CopyCopied 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

Example

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

Example

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

Example

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

Example

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

Example

await someFile.moveTo(someFolder, {newName: 'novel.txt', {overwrite: true})
CopyCopied 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

await aFile.delete();
CopyCopied to your clipboard
await aFile.delete();

entry.getMetadata() ⇒ Promise.<EntryMetadata>

Returns this entry's metadata.

Kind: instance method of Entry Since: XD 13 Example

const metadata = await aFile.getMetadata();
CopyCopied 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
  • .size : number
  • .dateCreated : Date
  • .dateModified : Date
  • .isFile : boolean
  • .isFolder : boolean

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
  • .read(options) ⇒ Promise.<(string\|ArrayBuffer)>
  • .write(data, options)

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

if (aFile.mode === modes.readOnly) {
    throw new Error("Can't write to a file opened as read-only.");
}
CopyCopied 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

Example

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

Example

const data = await myNovel.read({format: formats.binary}); // 'data' is an ArrayBuffer
console.log("File is " + data.byteLength + " bytes long.");
CopyCopied 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

Example

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

Example

const data = new Uint8Array([0xFF, 0xA1]);
await aDataFile.write(data, {format: formats.binary});  // writes a 2-byte file
CopyCopied 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>>
  • .getFileForSaving(suggestedName, options) ⇒ Promise.<?File>
  • .getFolder() ⇒ Promise.<?Folder>
  • .getTemporaryFolder() ⇒ Promise.<Folder>
  • .getDataFolder() ⇒ Promise.<Folder>
  • .getPluginFolder() ⇒ Promise.<Folder>
  • .getFsUrl(entry) ⇒ URL
  • .getNativePath(entry) ⇒ string

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

Example

const file = await fs.getFileForOpening();
if (!file) {
    // file picker dialog was canceled
    return;
}
const text = await file.read();
CopyCopied 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

const files = await fs.getFileForOpening({allowMultiple: true, types: fileTypes.images});
if (files.length === 0) {
    // no files selected
}
CopyCopied 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

Example

const file = await fs.getFileForSaving("output.txt", { types: [ "txt" ]});
if (!file) {
    // file picker was cancelled
    return;
}
await file.write("It was a dark and stormy night");
CopyCopied 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

const folder = await fs.getFolder();
const myNovel = (await fs.getEntries()).find(entry => entry.name.includes('novel'));
const text = await myNovel.read();
CopyCopied 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

const temp = await fs.getTemporaryFolder();
CopyCopied 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

fileSystemProvider.getNativePath(entry) ⇒ string

Returns the platform native file system path of given entry.

Kind: instance method of FileSystemProvider

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 ⇐ Entry
  • .getEntries() ⇒ Promise.<Array.<Entry>>
  • .createFile(name, options) ⇒ Promise.<File>
  • .createFolder(name) ⇒ Folder
  • .getEntry(filePath) ⇒ Promise.<(File\|Folder)>
  • .renameEntry(entry, newName, options) ⇒ Promise

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

const entries = await aFolder.getEntries();
const allFiles = entries.filter(entry => entry.isFile);
CopyCopied 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

Example

const myNovelTxtFile = await aFolder.createFile("mynovel.txt");
CopyCopied 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

Example

const myCollectionsFolder = await aFolder.createFolder("collections");
CopyCopied 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

Example

const myNovel = await aFolder.getEntry("mynovel.txt");
CopyCopied 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

Example

await myNovels.rename(myNovel, "myFantasticNovel.txt");
CopyCopied 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 : Errors
  • .AbstractMethodInvocationError ⇐ Error
  • .ProviderMismatchError ⇐ Error
  • .EntryIsNotAnEntryError ⇐ Error
  • .EntryIsNotAFolderError ⇐ Error
  • .EntryIsNotAFileError ⇐ Error
  • .NotAFileSystemError ⇐ Error
  • .OutOfSpaceError ⇐ Error
  • .PermissionDeniedError ⇐ Error
  • .EntryExistsError ⇐ Error
  • .FileIsReadOnlyError ⇐ Error
  • .DomainNotSupportedError ⇐ Error
  • .InvalidFileNameError ⇐ Error

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
  • .images
  • .all

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
  • .binary : Symbol

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
  • .readWrite : Symbol

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
  • .folder : Symbol

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

Last updated 8/10/2021

Was this helpful?

Yes

No