Local Driver

Stores files on the local filesystem using Node.js streams.

import { FilewayClient } from "@fileway/core";
import { LocalDriver } from "@fileway/driver-local";

const client = new FilewayClient({
  driver: new LocalDriver({
    directory: "/var/data/uploads",
    baseUrl: "https://cdn.example.com/files",
  }),
});

const result = await client.upload(stream, {
  filename: "photo.jpg",
  path: "users/123/avatars",
});

// result.meta.localPath -> absolute path on disk

Download

Stream a stored file back from disk with get(path) — it returns a WHATWG ReadableStream<Uint8Array>:

const stream = await client.get("users/123/avatars/photo.jpg");
const bytes = new Uint8Array(await new Response(stream).arrayBuffer());

stream is a WHATWG ReadableStream<Uint8Array>, so you can also pipe it straight to its destination (stream.pipeTo(writable)) with no buffering. Use .arrayBuffer()/.blob() for binary files — .text() would decode binary data as UTF-8 and corrupt it.

Throws if the file does not exist or if path escapes the configured directory.

Cancellation

Pass an AbortSignal in UploadOptions to cancel an upload in flight:

const controller = new AbortController();

const upload = client.upload(stream, {
  filename: "large.bin",
  signal: controller.signal,
});

// later...
controller.abort();

On abort the driver destroys both the source and destination streams, deletes the partial file from disk, and rejects with a DOMException whose name is AbortError:

try {
  await upload;
} catch (err) {
  if (err instanceof DOMException && err.name === "AbortError") {
    // cancelled — no partial file was left behind
  }
}

Progress

Pass onProgress to receive { bytes, total?, progress? } as bytes are written to disk — with options.size set, progress reaches exactly 1 when the file is fully flushed:

const result = await client.upload(stream, {
  filename: "large.bin",
  size: totalBytes,
  onProgress: ({ bytes, progress }) => {
    console.log(`${Math.round((progress ?? 0) * 100)}%`);
  },
});

Config

Metadata

LocalDriver implements BaseDriver<{ localPath: string }>

Errors

All failures are StorageErrors from @fileway/core (see the error reference for the full contract — codes, statusCode, provider, cause, and isAbortError). For this driver: