Module: resource/file#

Type Aliases#

GetFileOptions#

Ƭ GetFileOptions: Object

Options when fetching a file from a Pod.

Available options:

fetch: A custom fetch function with the same signature as fetch. This will be used to execute the actual requests. This option can be used to, for example, attach credentials to requests that need authentication.

Type declaration#

Name	Type
`fetch`	typeof `fetch`

Defined in#

src/resource/file.ts:49

WriteFileOptions#

Ƭ WriteFileOptions: GetFileOptions & { contentType: string }

Options available when writing a file.

Defined in#

src/resource/file.ts:255

Functions#

deleteFile#

▸ deleteFile(file, options?): Promise<void>

Deletes a file at a given URL.

For example:

await deleteFile( "https://pod.example.com/some/file", { fetch: fetch });

For additional examples, see Read/Write Files.

Parameters#

Name	Type	Description
`file`	`string` \| `Url` \| `WithResourceInfo`	The URL of the file to delete or the file itself (if it has ResourceInfo).
`options?`	`Partial`<`GetFileOptions`>	-

Returns#

Promise<void>

Defined in#

src/resource/file.ts:125

getFile#

▸ getFile(fileUrl, options?): Promise<File & WithServerResourceInfo>

Retrieves a file from a URL and returns the file as a blob.

For example:

const fileBlob = await getFile("https://pod.example.com/some/file", { fetch: fetch });

For additional examples, see Read/Write Files.

Parameters#

Name	Type	Description
`fileUrl`	`string` \| `Url`	The URL of the file to return
`options?`	`Partial`<`GetFileOptions`>	Fetching options: a custom fetcher and/or headers.

Returns#

Promise<File & WithServerResourceInfo>

The file as a blob.

Defined in#

src/resource/file.ts:80

overwriteFile#

▸ overwriteFile<FileExt>(fileUrl, file, options?): Promise<FileExt & WithResourceInfo>

Saves a file at a given URL. If a file already exists at the URL, the function overwrites the existing file.

For example:

const savedFile = await overwriteFile(
  "https://pod.example.com/some/container/myFile.txt",
  new File(["This is a plain piece of text"], "myFile", { type: "text/plain" }),
  { fetch: fetch }
);

For additional example, see Read/Write Files.

Recommended: In the options parameter, you can specify the media type of the file in the contentType. If unspecified, the function uses the default type of application/octet-stream, indicating a binary data file.

When saving a file with [[overwriteFile]], the Solid server creates any intermediary Containers as needed; i.e., the Containers do not need to be created in advance. For example, when saving a file to the target URL of https://example.pod/container/resource, if https://example.pod/container/ does not exist, the container is created as part of the save.

Type parameters#

Name	Type
`FileExt`	extends `Blob` \| `File` \| `File`

Parameters#

Name	Type	Description
`fileUrl`	`string` \| `Url`	The URL where the file is saved.
`file`	`FileExt`	The file to be written.
`options?`	`Partial`<`WriteFileOptions`>	Additional parameters for file creation (e.g., media type).

Returns#

Promise<FileExt & WithResourceInfo>

Defined in#

src/resource/file.ts:300

saveFileInContainer#

▸ saveFileInContainer<FileExt>(folderUrl, file, options?): Promise<FileExt & WithResourceInfo>

Saves a file in an existing folder/Container associated with the given URL.

For example:

const savedFile = await saveFileInContainer(
  "https://pod.example.com/some/existing/container/",
  new File(["This is a plain piece of text"], "suggestedFileName.txt", { type: "text/plain" }),
  { fetch: fetch }
);

For additional example, see Read/Write Files.

In the options parameter,

You can suggest a file name in the slug field. However, the Solid Server may or may not use the suggested slug as the file name.
Recommended: You can specify the media type of the file in the contentType. If unspecified, the function uses the default type of application/octet-stream, indicating a binary data file.

The function saves a file into an existing Container. If the Container does not exist, either:

Create the Container first using [[createContainerAt]], and then use the function, or
Use [[overwriteFile]] to save the file. [[overwriteFile]] creates the Containers in the saved file path as needed.

Users who only have Append but not Write access to a Container can use [[saveFileInContainer]] to save new files to the Container. That is, [[saveFileInContainer]] is useful in situations where users can add new files to a Container but not change existing files in the Container, such as users given access to send notifications to another’s Pod but not to view or delete existing notifications in that Pod.

Users with Write access to the given folder/Container may prefer to use [[overwriteFile]].

Type parameters#

Name	Type
`FileExt`	extends `Blob` \| `File` \| `File`

Parameters#

Name	Type	Description
`folderUrl`	`string` \| `Url`	The URL of an existing folder where the new file is saved.
`file`	`FileExt`	The file to be written.
`options?`	`Partial`<`SaveFileOptions`>	Additional parameters for file creation (e.g. a slug).

Returns#

Promise<FileExt & WithResourceInfo>

A Promise that resolves to the saved file, if available, or null if the current user does not have Read access to the newly-saved file. It rejects if saving fails.

Defined in#

src/resource/file.ts:209