Sys.Files
Sys.Files manages files that Lowgile stores in its system database and the file access tokens through which End users download them. A file access token is a stored, random token that makes a file downloadable at /__api/file/token/<token>, optionally only by one End user and only until it expires. Files on the server’s file system are handled by Sys.Fs.
Availability: Server
Functions
Section titled “Functions”createFileAccessToken()
Section titled “createFileAccessToken()”createFileAccessToken(fileName: string, data: string, options: CreateFileAccessTokenOptions, format?: 'utf8' | 'text_ascii'): Promise<FileAccessToken>createFileAccessToken(fileName: string, data: object | Array<any> | number, options: CreateFileAccessTokenOptions): Promise<FileAccessToken>createFileAccessToken(fileName: string, data: Buffer, options: CreateFileAccessTokenOptions): Promise<FileAccessToken>createFileAccessToken(fileName: string, data: any, options: CreateFileAccessTokenOptions): Promise<FileAccessToken>Stores data as a new file in the database and returns a new file access token for it. Strings are encoded with format; objects, arrays and numbers are stored as JSON; a Buffer is stored as-is. Call getUrl() on the result to get the download URL.
| Parameter | Type | Description |
|---|---|---|
fileName | string | File name stored with the file and offered to the browser when downloading. |
data | string | object | Array<any> | number | Buffer | Content of the file. |
options | CreateFileAccessTokenOptions | Lifetime and access settings of the token. |
format | 'utf8' | 'text_ascii' | Optional. Encoding for string data. Defaults to 'utf8'. |
CreateFileAccessTokenOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
isPermanent | boolean | Yes | If false, the token is deleted shortly after the next server start. |
userId | UserIdType | No | If set, only this End user can download the file. |
expiresAt | Date | No | After this time the download is refused and the token is deleted by the hourly cleanup. |
expiresOnDownload | boolean | No | If true, the token expires 5 minutes after the first download. |
deleteFileWhenExpired | boolean | No | If true (the default), the stored file is deleted together with the token. |
const fat = await Sys.Files.createFileAccessToken('orders.json', orders, { isPermanent: false, expiresOnDownload: true,})const url = fat.getUrl(true) // "/__api/file/token/<token>?download=true"Returns: Promise<FileAccessToken> · Availability: Server
createFileAccessTokenForFilePath()
Section titled “createFileAccessTokenForFilePath()”createFileAccessTokenForFilePath(filePath: string, options?: Exclude<FileAccessToken, 'token' | 'filePath'>): Promise<FileAccessToken>Stores a new file access token for a file on the server’s file system. It does the same as Sys.Auth.createFileAccessToken(), where the FileAccessToken fields and the type-check caveat for options are described.
| Parameter | Type | Description |
|---|---|---|
filePath | string | Absolute path of the file on the server, for example from Sys.Fs.getFilePath(). |
options | FileAccessToken | Optional. Settings for the token. |
Returns: Promise<FileAccessToken> · Availability: Server
readFileFromToken()
Section titled “readFileFromToken()”readFileFromToken<T = any>(token: FileAccessToken | string, format: 'json'): Promise<FileAndContent<T>>readFileFromToken<T = Buffer>(token: FileAccessToken | string, format: 'binary'): Promise<FileAndContent<T>>readFileFromToken<T extends string = string>(token: FileAccessToken | string, format: TextFileFormat): Promise<FileAndContent<T>>readFileFromToken<T = any>(token: FileAccessToken | string, format: ReadFileFormat): Promise<FileAndContent<T>>Reads the file behind a file access token, whether it is stored in the database or on the file system. For a file in the database, filePath in the result is the stored file name. For an unknown token, the result is { filePath: '', content: null }.
| Parameter | Type | Description |
|---|---|---|
token | FileAccessToken | string | The token object or its token string. |
format | ReadFileFormat | How to return the content: 'json' parses it, 'binary' returns a Buffer, a text encoding ('utf8', 'ascii', 'latin1', …) returns a string. 'binaryStream' returns a ReadStream and works only for files on the file system. See Sys.Fs for all formats. |
Returns: Promise<FileAndContent<T>>, an object with filePath: string and content: T · Availability: Server
Note
readFileFromToken() does not check the token’s expiresAt or userId; only the download URL does.
findFiles()
Section titled “findFiles()”findFiles(findOptions: FindManyOptions<File>): Promise<File[]>Finds files stored in the database, using TypeORM find options (where, select, order, skip, take, …). Unless select excludes it, each file is loaded with its content in data.
| Parameter | Type | Description |
|---|---|---|
findOptions | FindManyOptions<File> | TypeORM find options. See the TypeORM find options documentation. |
File fields
| Field | Type | Required | Description |
|---|---|---|---|
id | number | Yes | Generated ID of the stored file. |
fileName | string | Yes | File name. |
size | number | No | Size in bytes. |
mimeType | string | No | MIME type, if known. |
data | Buffer | No | Content of the file. |
accessTokens | FileAccessToken[] | No | File access tokens for this file, if loaded as a relation. |
const files = await Sys.Files.findFiles({ where: { fileName: 'orders.json' }, select: { id: true, fileName: true, size: true },})Returns: Promise<File[]> · Availability: Server
updateFile()
Section titled “updateFile()”updateFile(file: File): Promise<File>Saves changes to a stored file, for example a new fileName or data.
| Parameter | Type | Description |
|---|---|---|
file | File | The changed file, typically from findFiles(). |
Returns: Promise<File> · Availability: Server
deleteFile()
Section titled “deleteFile()”deleteFile(file: File): Promise<File>Deletes a stored file and all file access tokens for it.
| Parameter | Type | Description |
|---|---|---|
file | File | The file to delete; only its id is used to find its tokens. |
Returns: Promise<File>, the deleted file · Availability: Server
deleteFiles()
Section titled “deleteFiles()”deleteFiles(where: FindOptionsWhere<File>): Promise<import("typeorm").DeleteResult>Deletes all stored files that match the condition. The database also deletes their file access tokens.
| Parameter | Type | Description |
|---|---|---|
where | FindOptionsWhere<File> | TypeORM condition, for example { fileName: 'orders.json' }. |
Returns: Promise<DeleteResult>, TypeORM’s result with the number of deleted rows in affected · Availability: Server