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.

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

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");
}

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);

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);

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();
}

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.";
}

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.";
}

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

Param Type Default Description
folder Folder the folder to which to copy this entry
options *
[options.overwrite] boolean false if true, allows overwriting existing entries

Example

await someFile.copyTo(someFolder);

Example

await someFile.copyTo(someFolder, {overwrite: true});

Example

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

Param Type Default Description
folder Folder the folder to which to move this entry
options *
[options.overwrite] boolean false If true allows the move to overwrite existing files
[options.newName] string If specified, the entry is renamed to this name

Example

await someFile.moveTo(someFolder);

Example

await someFile.moveTo(someFolder, {overwrite: true});

Example

await someFolder.moveTo(anotherFolder, {overwrite: true});

Example

await someFile.moveTo(someFolder, {newName: 'masterpiece.txt'})

Example

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();

entry.getMetadata() ⇒ Promise.<EntryMetadata>

Returns this entry's metadata.

Kind: instance method of Entry Since: XD 13 Example

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

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

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

file.read(options) ⇒ Promise.<(string or 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 or ArrayBuffer)> - the contents of the file Since: XD 13

Param Type Default Description
options Object
[options.format] Symbol formats.utf8 Optional. Format to read: one of storage.formats.utf8 or storage.formats.binary.

Example

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.");

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

Param Type Default Description
data string or ArrayBuffer Data to write to the file
options Object
[options.format] Symbol formats.utf8 Optional. Format to write: storage.formats.utf8 or storage.formats.binary.

Example

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

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> or 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> or 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

Param Type Default Description
options Object
[options.types] Array.<string> ['*'] Optional. Allowed file extensions, with no "." prefix; use storage.fileTypes.all to allow any file to be picked
[options.allowMultiple] boolean false Optional. 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

const file = await fs.getFileForOpening();
if (!file) {
    // file picker dialog was canceled
    return;
}
const text = await file.read();

Example

const files = await fs.getFileForOpening({allowMultiple: true, types: fileTypes.images});
if (files.length === 0) {
    // no files selected
}

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

Param Type Description
suggestedName string Required. The file extension should match one of the options specified in the types option.
options Object
[options.types] Array.<string> Required. Allowed file extensions, with no "." prefix.

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");

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();

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();

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

Param Type
entry Entry

fileSystemProvider.getNativePath(entry) ⇒ string

Returns the platform native file system path of given entry.

Kind: instance method of FileSystemProvider

Param Type
entry Entry

createSessionToken(entry)

Returns a token suitable for use with certain host-specific APIs. This token is valid only for the current plugin session. As such, it is of no use if you serialize the token to persistent storage, as the token will be invalid in the future.

Returns: string - the session token for the given entry

Param Type
entry Entry

Example 

const fs = require('uxp').storage.localFileSystem;
let entry = await fs.getFileForOpening();
let token = fs.createSessionToken(entry);

getEntryForSessionToken(token)

Returns the file system Entry that corresponds to the session token obtained from createSessionToken. If an entry cannot be found that matches the token, then a Reference Error: token is not defined error is thrown.

Returns: Entry - the corresponding entry for the session token

Param Type
token string

createPersistentToken(entry)

Returns a token suitable for use with host-specific APIs (such as Xd), or for storing a persistent reference to an entry (useful if you want to only ask for permission to access a file or folder once). A persistent token is not guaranteed to last forever – certain scenarios can cause the token to longer work (including moving files, changing permissions, or OS-specific limitations). If a persistent token cannot be reused, you'll get an error at the time of use.

Returns: string - the persistent token for the given entry

Param Type
entry Entry

Example 

const fs = require('uxp').storage.localFileSystem;
let entry = await fs.getFileForOpening();
let token = fs.createPersistentToken(entry);
localStorage.setItem("persistent-file", token);

getEntryForPersistentToken(token)

Returns the file system Entry that corresponds to the persistent token obtained from createPersistentToken. If an entry cannot be found that matches the token, then a Reference Error: token is not defined error is thrown.

Retrieving an entry for a persistent token does not guarantee that the entry is valid for use. You'll need to properly handle the case where the entry no longer exists on the disk, or the permissions have changed by catching the appropriate errors. If that occurs, the suggested practice is to prompt the user for the entry again and store the new token.

Returns: Entry - the corresponding entry for the persistent token

Param Type
token string

Example 

const fs = require('uxp').storage.localFileSystem;
let entry, contents, tries = 3, success = false;
while (tries > 0) {
    try {
        entry = await fs.getEntryForPersistentToken(localStorage.getItem("persistent-file"));
        contents = await entry.read();
        tries = 0;
        success = true;
    } catch (err) {
        entry = await fs.getFileForOpening();
        localStorage.setItem("persistent-token", await fs.createPersistentToken(entry));
        tries--;
    }
}
if (!success) {
    // fail gracefully somehow
}

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.

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

const entries = await aFolder.getEntries();
const 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.

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

Param Type Default Description
name string the name of the file to create.
options Object
[options.overwrite] boolean false If 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

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).

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

Param Type Description
name string the name of the folder to create.

Example

const myCollectionsFolder = await aFolder.createFolder("collections");

folder.getEntry(filePath) ⇒ Promise.<(File or 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 or Folder)> - the fetched entry. Since: XD 13

Param Type Description
filePath string Name, with optional relative path prefix, of an existing entry within this folder

Example

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

Param Type Default Description
entry Entry entry to rename (File or Folder). Must exist.
newName string the new name to assign
options any
[options.overwrite] boolean false if true, renaming can overwrite an existing entry

Example

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

results matching ""

    No results matching ""