Documentation / @zerotal/flow / index / TemporaryUploadedFile

Class: TemporaryUploadedFile

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:114

A Livewire-style temporary uploaded file — the server-side handle a component receives for a pending upload before it's promoted to permanent storage.

Remarks

Uploads bypass the WebSocket: the browser POSTs the bytes to /__flow/upload over HTTP, the endpoint stores them on a temp disk and returns a signed UploadRef, and the client $sets that ref onto a component property. The base Component verifies the signature and wraps it into a TemporaryUploadedFile (see resolveUploadValue). Component code then inspects it (isImage, extension, temporaryUrl) and calls store in an action to move it to permanent storage. The value round-trips through the HMAC-signed snapshot via its synth, so it survives across requests until stored.

Example

class Avatar extends ComponentWith(FileUploads) {
  @expose photo: TemporaryUploadedFile | null = null;
  @expose path = "";

  @expose async save() {
    if (this.photo?.isImage()) {
      this.path = await this.photo.store("avatars"); // -> "avatars/<uuid>.png"
      this.photo = null;
    }
  }
}

Constructors

Constructor

new TemporaryUploadedFile(d): TemporaryUploadedFile

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:141

Parameters

d

TufData

Returns

TemporaryUploadedFile

Metadata

tmpPath

readonly tmpPath: string

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:119

Path of the uploaded bytes on the temp disk.

originalName

readonly originalName: string

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:124

The client-supplied original filename.

mime

readonly mime: string

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:129

The upload's MIME type.

size

readonly size: number

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:134

Size of the upload in bytes.

tempDisk?

readonly optional tempDisk?: string

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:139

Name of the temp disk the bytes live on (default disk when undefined).

name

Get Signature

get name(): string

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:153

The original filename (alias of originalName).

Returns

string

isImage()

isImage(): boolean

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:160

Whether the upload's MIME type is an image (image/*).

Returns

boolean

extension()

extension(): string

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:170

The lowercased file extension derived from the original name, sanitized to [a-z0-9] only (so a crafted name can't smuggle path/control characters into the stored filename). Empty string when the name has no extension.

Returns

string

The sanitized extension without the leading dot.

Storage

toRef()

toRef(): TufData

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:185

Extract the plain TufData for serialization (used by the snapshot synth).

Returns

TufData

The upload's metadata without any signature.

fromSignedRef()

static fromSignedRef(ref): TemporaryUploadedFile | null

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:203

Verify a client-supplied signed ref and wrap it. Returns null when the signature is invalid (a forged or tampered ref), so callers discard it rather than trusting attacker-controlled paths.

Parameters

ref

UploadRef

The signed reference the client $set.

Returns

TemporaryUploadedFile | null

A verified file, or null if the signature check fails.

fromTrustedRef()

static fromTrustedRef(data): TemporaryUploadedFile

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:213

Rebuild from snapshot data that is already HMAC-trusted (the whole snapshot is signed), so no per-ref signature check is needed. Used by the snapshot synth.

Parameters

data

TufData

Trusted upload metadata from the snapshot.

Returns

TemporaryUploadedFile

bytes()

bytes(): Promise<Uint8Array<ArrayBufferLike>>

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:222

Read the temp file's raw bytes from its disk.

Returns

Promise<Uint8Array<ArrayBufferLike>>

The upload's contents.

store()

store(directory, diskName?, filename?): Promise<string>

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:236

Move the temp file to permanent storage and delete the temp copy.

Parameters

diskName?

string

Target storage disk; the default disk when omitted.

filename?

string

Explicit filename; when omitted, a random UUID plus the sanitized extension is used.

Returns

Promise<string>

The stored path (directory/filename).

temporaryUrl()

temporaryUrl(ttlSeconds?): Promise<string>

Defined in: flow/src/uploads/TemporaryUploadedFile.ts:255

A URL for previewing the still-temporary file — signed and expiring on disks that support it, falling back to a plain URL otherwise.

Parameters

ttlSeconds?

number = 300

Lifetime of the temporary URL in seconds (default 300).

Returns

Promise<string>

A URL to the temp file.