API reference

@thefinder/core

The server engine. It has no runtime dependencies and runs with the Web-standard Request → Response signature on Node.js (≥ 18.17), Bun, Deno and edge runtimes.

Entry points#

createTheFinder(options)#

import { createTheFinder } from "@thefinder/core";
import { localDriver } from "@thefinder/core/local";

const finder = createTheFinder({
  volumes: [{ id: "files", name: "Files", driver: localDriver({ root: "./uploads" }), url: "/uploads" }],
});

Same as new TheFinder(options). Throws an Error right away on a bad configuration (no volumes, the same volume id twice, chunkSize < 5 MiB while an S3 volume exists).

TheFinderOptions#

VolumeOptions#

The TheFinder instance#

// Example: removing versions older than 90 days in a cron job
await finder.execute("cleanup", { volume: "files", target: "versions", mode: "older", days: 90 });

Authorization#

type AuthorizeResult = boolean | void | { readOnly?: boolean };

interface CommandContext {
  cmd: string;                       // "ls", "upload"...
  request: Request;                  // the incoming request (cookies and headers can be read)
  params: Record<string, unknown>;   // merged query + body parameters
}

Keeping references in sync: onEntriesChanged#

Entry ids are made from the path (<volume>_<base64url(path)>), so a file gets a new id when it is renamed or moved. An application that refers to files by its own stable id (for example a CMS with a uuid → path table) can keep that table up to date with onEntriesChanged:

type EntryChange =
  | { type: "moved"; from: { volume: string; path: VolumePath }; to: { volume: string; path: VolumePath }; kind: EntryKind }
  | { type: "trashed"; volume: string; path: VolumePath; kind: EntryKind; trashId: string }
  | { type: "restored"; volume: string; trashId: string; path: VolumePath; kind: EntryKind }
  | { type: "deleted"; volume: string; path: VolumePath; kind: EntryKind } // removed for good, without the trash
  | { type: "purged"; volume: string; trashId: string } // removed from the trash for good
  | { type: "replaced"; volume: string; path: VolumePath }; // same file, same path, new content

const finder = createTheFinder({
  volumes: [/* ... */],
  async onEntriesChanged(changes, ctx) {
    for (const c of changes) {
      // A folder comes as one change: update its own path and every path below `from.path + "/"`.
      if (c.type === "moved") await db.files.movePath(c.from, c.to);
      if (c.type === "trashed") await db.files.markTrashed(c.volume, c.path, c.trashId);
      if (c.type === "restored") await db.files.restore(c.volume, c.trashId, c.path);
      if (c.type === "deleted") await db.files.removePath(c.volume, c.path);
      if (c.type === "purged") await db.files.removeTrashed(c.volume, c.trashId);
      if (c.type === "replaced") await db.files.touch(c.volume, c.path);
    }
  },
});

EntryChange and EntryKind ("file" | "dir") are exported from @thefinder/core.

When it is called

• Once per command, with every change of that command in one array, after the storage work is over and before onAfterCommand. It is awaited. Commands that change nothing existing do not call it.
• A folder is a single change for the folder's own path. What is inside it moved, went to the trash or was deleted with it and is not listed.
• The paths are the real outcome. A paste that had to rename because of a clash reports the new name ("/docs/a (2).txt"), and a restore that could not go back to the same name reports the path it went to.
• trashId is the id of the item inside the trash: Entry.trash.id in the trash listing, which is also the last segment of the trash entry's path (/.tf-trash/<trashId>). It is not the entry id. The same item has the same trashId in trashed, restored and purged.
• A command with several items that fails half way (a paste of five items whose third one fails) still reports what it did before the failure; the request then fails as usual.
• ctx is the command's context, the same object onBeforeCommand gets. Changes made outside a command come with ctx set to null. Today every change happens inside a command (the retention cleanup of the trash runs inside trash and purge), but handle null so a later version can report outside changes without breaking your code.
• execute() calls it like an HTTP request does. A read-only request cannot change anything, so it never calls it.
• Only changes made through theFinder are seen. Files changed directly on the disk or in the bucket are not reported.

Events

Errors. It behaves like onAfterCommand: when it throws, the request fails (500 INTERNAL unless it throws a TheFinderError) and onAfterCommand does not run. The storage change has already happened by then, so the client sees an error for something that was done. Catch inside the hook (and queue a retry, for example) when your table being out of date should not fail the user's request. When the command itself failed and the hook throws too, the command's error is returned and the hook's error is logged with console.error.

Drivers#

localDriver(options), @thefinder/core/local#

• Files are first written to a temporary file and then moved into place, so an interrupted write never corrupts the real file. On Windows it retries if the target file is open in another program.
• capacity() reports the disk size (for the storage dashboard).
• driver.root: the resolved absolute root path. driver.abs(path): converts a volume path to an OS path.

s3Driver(options), @thefinder/core/s3#

• Signing (SigV4) uses Web Crypto; no AWS SDK needed.
• Folders are modeled as prefixes; empty folders are kept with a folder/ marker object.
• Move and rename are copy + delete; for folders every object under the prefix is processed.
• Uploads are multipart and the server keeps no state.
• For the image editor to read images on S3, allow GET from your app's origin in the bucket's CORS settings.

The StorageDriver interface#

To add a new storage (FTP, Azure Blob, Google Drive…) all you need is to implement this interface. The engine always hands the driver normalized paths (/, /a/b.txt); the driver never sees ...

interface DriverStat { name: string; path: VolumePath; kind: "file" | "dir"; size: number; mtime: number /* ms */ }

interface UploadChunk {
  path: VolumePath;   // validated, conflict-free target on the first chunk
  session?: string;   // state returned by the previous chunk; undefined on the first chunk
  index: number; total: number;
  size: number;       // total size of the file
  offset: number;     // byte offset of the chunk
  data: Uint8Array;
}

Thumbnails#

import { sharpThumbnailer } from "@thefinder/core/sharp";

createTheFinder({ volumes, thumbnails: { generator: sharpThumbnailer(), sizes: [128, 256, 512] } });

ThumbnailOptions#

Thumbnails are kept in the volume's .tf-thumbs/ folder. They are regenerated when the source changes and cleaned up when the file is deleted, moved or renamed.

sharpThumbnailer(options?)#

Reads: jpg, jpeg, jfif, png, webp, gif, avif, tif, tiff, heic, heif. Applies EXIF orientation, keeps the aspect ratio, never upscales. If sharp can't be loaded the API keeps working, a warning is logged once and original images are sent.

The Thumbnailer interface#

interface Thumbnailer {
  extensions: string[];      // extensions it can read (lower case)
  extension?: string;        // extension of generated files, default "webp"
  generate(input: Uint8Array, size: number): Promise<Uint8Array>; // fit into a size×size box
}

Image processing#

import { sharpImages } from "@thefinder/core/sharp";

createTheFinder({ volumes, images: sharpImages() });

sharpImages(options?)#

Writes: jpeg (mozjpeg), png (palette when quality < 100), webp, avif, gif. Applies EXIF orientation, strips metadata, never upscales. Animation is kept when both the source and target formats support it. Throws INVALID_IMAGE on corrupt input and TOO_LARGE at the pixel limit. At most two images are processed at once; the rest wait in a queue.

The ImageProcessor interface#

interface ImageProcessor {
  extensions: string[];   // extensions it can read
  formats: ImageFormat[]; // formats it can write: "jpeg" | "png" | "webp" | "avif" | "gif"
  transform(input: Uint8Array, options: ImageTransformOptions): Promise<{ data: Uint8Array; width: number; height: number }>;
}

interface ImageTransformOptions { format: ImageFormat; width?: number; height?: number; quality?: number /* 1–100, default 80 */ }

Serving files#

createFileServer(options)#

A Web-standard handler that serves the files of a driver under a URL prefix.

Bun.serve({ routes: { "/uploads/*": createFileServer({ driver, prefix: "/uploads" }) } });

Range, ETag/304, HEAD, the right Content-Type and ?download are supported. Active content such as HTML and SVG is served with Content-Security-Policy: sandbox. Methods other than GET/HEAD return 405.

serveFile(options)#

A low-level helper for building a file response in your own route.

Other helpers: contentDisposition(type, filename) (RFC 6266/5987, UTF-8 names), parseRange(header, size) (ByteRange, "invalid" or null), etagOf(stat).

Node adapters#

@thefinder/core/node. If a parser such as express.json() or koa-bodyparser has already read the body, the adapter rebuilds it.

A file server can be mounted the same way: app.get("/uploads/*", toExpress(createFileServer({ driver, prefix: "/uploads" }))).

Errors#

import { TheFinderError, isTheFinderError } from "@thefinder/core";

throw new TheFinderError("UNAUTHORIZED");           // the message defaults to the code
throw new TheFinderError("FORBIDDEN", "This folder is off limits");

A TheFinderError thrown in a hook or a driver reaches the client with its own code and message. Any other error becomes INTERNAL and its details are written only to the server log.

Helpers#

interface ZipSource {
  name: string;          // path inside the archive; folders end with "/"
  mtime: number;
  size?: number;         // used to decide on zip64 for very large files
  open?: () => Promise<ReadableStream<Uint8Array>>;
}

Types#

Every type can be imported with import type { … } from "@thefinder/core". In browser code the same types are available from @thefinder/core/client.

Entry#

VolumeInfo#

{ id, name, kind, root: Entry, readOnly, maxUploadSize: number | null, allowExtensions: string[] | null, denyExtensions: string[], trash: { retentionDays, count } | null, versions: { maxPerFile, retentionDays } | null }

trash and versions are null when that feature is off.

InitResult#

{ volumes: VolumeInfo[], chunkSize, version, thumbnails: { sizes, extensions } | null, images: { extensions, formats } | null }

FileVersion#

{ id, size, createdAt, reason }. reason tells what replaced the version: edit, upload, replace, optimize, revert…

StorageStats#

VersionedFile: { id, path, name, exists, count, size, latest }. exists: false means the file was deleted or moved outside theFinder, so its versions are orphaned.

TransformResult#

This page is generated from docs/api/core.md.