Folders & prefix navigation

An object store (S3, and the local driver that mimics it) has no folders. There is only a flat map of keys to bytes — photos/2024/paris/eiffel.jpg is one opaque string, not a paris directory living inside a 2024 directory. The slashes are a convention, nothing more.

Yet every file browser — including this library's console — shows you folders you can open, create, and drag things between. That illusion is built entirely from prefix rollups: ask the driver to list a prefix and to stop at the next delimiter, and it hands back the distinct sub-prefixes it found. Those become your folders.

The delimiter rollup

Every StorageDriver whose capabilities.list is true implements:

list(prefix: string, options?: ListOptions): Promise<ListResult>;

interface ListOptions {
  /** Delimiter that rolls deeper keys up into folder prefixes. Default '/'. */
  delimiter?: string;
  /** Opaque pagination cursor from a previous ListResult. */
  cursor?: string;
  /** Max entries per page. */
  limit?: number;
  /** Override the driver's configured bucket/root (admin cross-bucket browse). */
  bucket?: string;
}

interface ListResult {
  /** Sub-folder prefixes (each ends in the delimiter), from CommonPrefixes. */
  folders: string[];
  /** File entries directly under the prefix. */
  files: ListEntry[];
  /** Present when the result is truncated; pass back as ListOptions.cursor. */
  cursor?: string;
}

interface ListEntry {
  key: string;                    // full key relative to the bucket/root
  name: string;                   // last path segment (no trailing slash)
  sizeBytes: number | null;
  lastModified: Date | null;
}

The delimiter defaults to /. With it, list behaves exactly like ls of a single directory: files directly under the prefix land in files, and everything deeper collapses into folders (S3 calls these CommonPrefixes). Nothing nested is enumerated — that's what makes a huge bucket cheap to browse one level at a time.

Given these keys on a disk:

photos/logo.png
photos/2023/summer/a.jpg
photos/2023/winter/b.jpg
photos/2024/paris/eiffel.jpg

listing the photos/ prefix rolls the two years up into folders and returns only the file that sits directly there:

const result = await storage.disk('s3').list('photos/');
// result.folders → ['photos/2023/', 'photos/2024/']   (each ends in the delimiter)
// result.files   → [{ key: 'photos/logo.png', name: 'logo.png', sizeBytes: 5123, … }]

Open a folder by feeding its prefix straight back in — the folders entries are already valid prefixes:

const inner = await storage.disk('s3').list('photos/2024/');
// inner.folders → ['photos/2024/paris/']
// inner.files   → []

That single call, repeated as the user clicks, is the whole navigation model.

Listing flat: delimiter: ''

Pass an empty delimiter and the rollup disappears — you get every key under the prefix, nested included, with folders empty. This is how you sweep a subtree, e.g. to size it or to delete it recursively:

// Every object under photos/2024/, however deep — no folders, all files.
let cursor: string | undefined;
const all: string[] = [];
do {
  const page = await storage.disk('s3').list('photos/2024/', { delimiter: '', cursor, limit: 1000 });
  all.push(...page.files.map((f) => f.key));
  cursor = page.cursor;
} while (cursor);

The dashboard's recursive folder delete and folder move/copy are exactly this loop — a flat sweep, then an operation per key. The default / delimiter would have hidden the nested keys inside folders, and the sweep would have missed them.

Pagination

list is paginated. When a result is truncated it carries a cursor; pass it back as ListOptions.cursor for the next page, and stop when it's absent:

let cursor: string | undefined;
do {
  const page = await storage.disk('s3').list('photos/', { cursor, limit: 100 });
  render(page.folders, page.files);
  cursor = page.cursor;
} while (cursor);

The cursor is opaque — don't parse it. It encodes the S3 continuation token (or the local driver's equivalent offset); treat it as a "give me more" token that only means anything to the driver that issued it.

Cross-bucket browse: bucket

ListOptions.bucket overrides the driver's configured bucket/root for one call — an admin escape hatch to browse a different bucket through the same credentials, without registering a second disk. Drivers without a bucket concept (e.g. the local driver) ignore it.

await storage.disk('s3').list('', { bucket: 'some-other-bucket' });

The dashboard folder feature

Because object stores have no folders, "create a folder" can't mean "make a directory" — there's nothing to make. The console fakes it with a zero-byte marker object whose key is the prefix itself, ending in a slash (invoices/2024/). S3-style listing then surfaces that prefix as a navigable, and now empty-but-real, folder. MediaConsoleService owns the four folder operations:

Marker objects are why the console filters listings the way it does: a folder marker's key ends in /, so after stripping the prefix its name is empty — the console drops those empty-named entries so the marker shows up as the folder, never as a phantom file inside it.

Same-disk moves and copies use the driver's native, server-side copy/move (no bytes through your pod). A cross-disk folder transfer has no driver primitive, so each object is streamed through the process (get → put, buffered) — bounded per object to protect the heap. A move into a destination inside its own source is rejected on the same disk (it would recurse forever).

Dashboard REST folder routes

The folder operations are reachable over the console's JSON API. All are on the actions controller (present only with actions: true) and return 204 No Content. The disk in the path is the source disk; the JSON body's optional toDisk names the destination for a cross-disk transfer (omit it to stay on the same disk).

# Create a folder
curl -X POST https://app.example.com/media/api/disks/s3/folder \
  -H 'Content-Type: application/json' \
  -d '{"prefix":"invoices/2024"}'

# Move a folder to another disk, keeping its subtree layout
curl -X POST https://app.example.com/media/api/disks/s3/move-folder \
  -H 'Content-Type: application/json' \
  -d '{"from":"invoices/2024","to":"archive/2024","toDisk":"cold"}'

# Recursively delete a folder and everything under it
curl -X DELETE 'https://app.example.com/media/api/disks/s3/folder?prefix=invoices/2024'

From the browser, the typed console client wraps every one of these:

import { mediaConsoleClient } from '@dudousxd/nestjs-media-dashboard/client';

await mediaConsoleClient.createFolder('s3', 'invoices/2024');
await mediaConsoleClient.moveFolder('s3', 'invoices/2024', 'cold', 'archive/2024');
await mediaConsoleClient.deleteFolder('s3', 'invoices/2024');

Building your own folder browser

You don't need the console — the SPI is enough to build navigation into your own admin. The pattern is always the same three steps:

const { folders, files, cursor } = await storage.disk('s3').list(prefix);

const next = await storage.disk('s3').list(clickedFolder /* already a prefix */);