Skip to main content
zerotal

Documentation

Documentation / zerotal / storage / StorageManager

Class: StorageManager

Defined in: packages/core/src/storage/StorageManager.ts:7

Constructors

Constructor

new StorageManager(config): StorageManager

Defined in: packages/core/src/storage/StorageManager.ts:13

Parameters

config

StorageConfigShape

Returns

StorageManager

Methods

disk()

disk(name?): StorageDriver

Defined in: packages/core/src/storage/StorageManager.ts:25

Get the driver for the named disk (or the default disk if omitted).

Parameters

name?

string

Returns

StorageDriver

Example

Storage.disk('local').put('avatars/alice.jpg', buffer);
Storage.disk('s3').get('reports/2025.pdf');
Storage.disk().exists('tmp/cache.json');

fake()

fake(name?): FakeDisk

Defined in: packages/core/src/storage/StorageManager.ts:66

Swap a disk for an in-memory FakeDisk and return it, so a test can exercise uploads without writing to the filesystem or reaching S3.

The fake stays installed until restoreFakes — call that in an afterEach, or a later test expecting real storage will silently write into memory and find its files gone.

Parameters

name?

string

Disk to replace; defaults to the configured default disk.

Returns

FakeDisk

Example

const disk = Storage.fake('s3');
await report.export();
disk.assertExists('reports/2025.pdf');

restoreFakes()

restoreFakes(): void

Defined in: packages/core/src/storage/StorageManager.ts:77

Restore every disk swapped by fake. Call in afterEach.

Returns

void

publicUrl()

publicUrl(path, options?): Promise<string>

Defined in: packages/core/src/storage/StorageManager.ts:115

A URL a browser can actually fetch — the one thing a template wants.

The disk's own config decides which kind, so the caller does not have to know whether the file is public:

  • Served, unsigned → a permanent URL under the disk's mount.
  • Served with signed → a time-limited signed URL.
  • Not served → DiskNotServedError, rather than a plausible string that 404s.

That last case is the point. url() on an unserved disk returns a path nothing answers, and a relative one at that — which resolves against whatever page embedded it and produces a broken image somewhere confusing. A URL you cannot fetch is not a URL, so asking for one is an error.

Parameters

path

string

Path on the disk.

options?
disk?

string

Disk name; defaults to the configured default disk.

expiresIn?

number

Seconds a signed link stays valid. Defaults to the disk's serve.expiresIn, then 900.

Returns

Promise<string>

Throws

DiskNotConfiguredError when the disk does not exist.

Throws

DiskNotServedError when the disk has no public URL.

Example

// Public disk → /storage/avatars/alice.jpg
await Storage.publicUrl("avatars/alice.jpg", { disk: "public" });

// Signed disk → /invoices/q1.pdf?expires=…&signature=…
await Storage.publicUrl("q1.pdf", { disk: "invoices" });

isServed()

isServed(disk?): boolean

Defined in: packages/core/src/storage/StorageManager.ts:137

Whether disk has a public URL at all — a served disk, or one pointed at a CDN. Use it to branch a template without catching an error.

Parameters

disk?

string

Returns

boolean

verifyTemporaryUrl()

verifyTemporaryUrl(path, expiresAt, signature): boolean

Defined in: packages/core/src/storage/StorageManager.ts:158

Verify a signature produced by a local disk's temporaryUrl(). Returns false when the link has expired or the signature does not match (constant-time). Wire this into the route that serves protected files:

Parameters

path

string

expiresAt

number

signature

string

Returns

boolean

Example

Router.get('/files/:path*', ({ params, query, response }) => {
  const path = params.path;
  if (!Storage.verifyTemporaryUrl(path, Number(query('expires')), query('signature') ?? '')) {
    return response.status(403).send('Invalid or expired link');
  }
  return response.stream(await Storage.disk().getBuffer(path));
});

S3 presigned URLs are verified by S3 itself and never pass through here.

verifyTemporaryUrlFor()

verifyTemporaryUrlFor(path, url): boolean

Defined in: packages/core/src/storage/StorageManager.ts:166

Convenience over verifyTemporaryUrl that reads ?expires=&signature= from a full request URL and checks them against path.

Parameters

path

string

url

string | URL

Returns

boolean