FilewayClient
API reference for the FilewayClient engine and its configuration
Constructor
new FilewayClient<TConfig extends FilewayConfig>(config: TConfig)config
| Option | Type | Description |
|---|---|---|
driver | BaseDriver | The storage driver. See Drivers. |
middlewares | MiddlewareHook[] | Optional. Middleware run around uploads. See Middleware. |
logger | Logger | Optional. Structured logger; receives info per operation and error on failure. See Observability. |
onError | (error, context) => void | Promise<void> | Optional. Called (and awaited) before an error is re-thrown. Aborts are skipped. See Observability. |
retry | RetryConfig | Optional. Retries transient failures (network, provider-error, HTTP 429/5xx). See Observability. |
upload(stream, options)
Uploads a WHATWG ReadableStream<Uint8Array>.
| Param | Type | Description |
|---|---|---|
stream | ReadableStream<Uint8Array> | The file bytes. Never buffered whole by Local/S3. |
options | UploadOptions | See the options table below. |
Returns Promise<UploadResult<TMeta>> where TMeta is the driver's metadata type.
An upload retries on transient failures only when options.streamFactory is provided (see Retries). delete, get, getUrl, and getPresignedUrl retry automatically.
UploadOptions:
| Option | Type | Required | Description |
|---|---|---|---|
filename | string | ✅ | Original file name. |
path | string | Folder/path prefix for the stored object. | |
mimeType | string | Content type. | |
metadata | Record<string, string> | Provider user metadata (see Metadata). | |
size | number | Known byte length — unlocks zero-buffer streaming (see Uploads). | |
signal | AbortSignal | Cancels the upload in flight (see Uploads). | |
onProgress | (progress) => void | Progress callback (see Uploads). | |
streamFactory | () => ReadableStream<Uint8Array> | Re-produces the stream for retry attempts. Required to retry an upload (see Retries). Sync-only today; an async (Promise-returning) variant is planned — see Retrying uploads. |
get(path)
Streams a stored file back as ReadableStream<Uint8Array> (see Downloads).
| Param | Type | Description |
|---|---|---|
path | string | Path of the stored file. |
Throws StorageError("not-found") when the file does not exist.
delete(path)
Deletes a stored file.
| Param | Type | Description |
|---|---|---|
path | string | Path of the stored file. |
Returns Promise<boolean> — true when deleted, false when it was already gone.
getUrl(path)
Returns the public URL for a stored file (see Downloads).
| Param | Type | Description |
|---|---|---|
path | string | Path of the stored file. |
getPresignedUrl(path, options?)
Returns a time-limited, signed download URL. Only available on drivers that implement it (S3Driver, CloudinaryDriver); otherwise throws StorageError("config") (see Downloads).
| Param | Type | Description |
|---|---|---|
path | string | Path of the stored file. |
options.expiresIn | number | Lifetime in seconds (default 3600; bounds are driver-specific). |