Skip to content

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

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.

ParameterTypeDescription
fileNamestringFile name stored with the file and offered to the browser when downloading.
datastring | object | Array<any> | number | BufferContent of the file.
optionsCreateFileAccessTokenOptionsLifetime and access settings of the token.
format'utf8' | 'text_ascii'Optional. Encoding for string data. Defaults to 'utf8'.

CreateFileAccessTokenOptions fields

FieldTypeRequiredDescription
isPermanentbooleanYesIf false, the token is deleted shortly after the next server start.
userIdUserIdTypeNoIf set, only this End user can download the file.
expiresAtDateNoAfter this time the download is refused and the token is deleted by the hourly cleanup.
expiresOnDownloadbooleanNoIf true, the token expires 5 minutes after the first download.
deleteFileWhenExpiredbooleanNoIf 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(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.

ParameterTypeDescription
filePathstringAbsolute path of the file on the server, for example from Sys.Fs.getFilePath().
optionsFileAccessTokenOptional. Settings for the token.

Returns: Promise<FileAccessToken> · Availability: Server

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

ParameterTypeDescription
tokenFileAccessToken | stringThe token object or its token string.
formatReadFileFormatHow 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(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.

ParameterTypeDescription
findOptionsFindManyOptions<File>TypeORM find options. See the TypeORM find options documentation.

File fields

FieldTypeRequiredDescription
idnumberYesGenerated ID of the stored file.
fileNamestringYesFile name.
sizenumberNoSize in bytes.
mimeTypestringNoMIME type, if known.
dataBufferNoContent of the file.
accessTokensFileAccessToken[]NoFile 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(file: File): Promise<File>

Saves changes to a stored file, for example a new fileName or data.

ParameterTypeDescription
fileFileThe changed file, typically from findFiles().

Returns: Promise<File> · Availability: Server

deleteFile(file: File): Promise<File>

Deletes a stored file and all file access tokens for it.

ParameterTypeDescription
fileFileThe file to delete; only its id is used to find its tokens.

Returns: Promise<File>, the deleted file · Availability: Server

deleteFiles(where: FindOptionsWhere<File>): Promise<import("typeorm").DeleteResult>

Deletes all stored files that match the condition. The database also deletes their file access tokens.

ParameterTypeDescription
whereFindOptionsWhere<File>TypeORM condition, for example { fileName: 'orders.json' }.

Returns: Promise<DeleteResult>, TypeORM’s result with the number of deleted rows in affected · Availability: Server