API referansı

@thefinder/core

Sunucu motoru. Çalışma zamanı bağımlılığı yoktur; Web standardı Request → Response imzasıyla Node.js (≥ 18.17), Bun, Deno ve edge ortamlarında çalışır.

Giriş noktaları#

createTheFinder(options)#

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

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

new TheFinder(options) ile aynıdır. Hatalı yapılandırmada (volume yok, aynı volume kimliği iki kez, S3 varken chunkSize < 5 MiB) hemen Error fırlatır.

TheFinderOptions#

VolumeOptions#

TheFinder örneği#

// Örnek: bir cron işinde 90 günden eski sürümleri temizlemek
await finder.execute("cleanup", { volume: "files", target: "versions", mode: "older", days: 90 });

Yetkilendirme#

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

interface CommandContext {
  cmd: string;                       // "ls", "upload"...
  request: Request;                  // gelen istek (çerez, başlık okunabilir)
  params: Record<string, unknown>;   // birleştirilmiş sorgu + gövde parametreleri
}

Referansları güncel tutmak: onEntriesChanged#

Öğe kimlikleri yoldan üretilir (<volume>_<base64url(path)>), bu yüzden bir dosyanın adı değişince ya da taşınınca kimliği de değişir. Dosyalara kendi sabit kimliğiyle başvuran bir uygulama (örneğin uuid → path tablosu tutan bir CMS) bu tabloyu onEntriesChanged ile güncel tutabilir:

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 } // çöpe uğramadan kalıcı silindi
  | { type: "purged"; volume: string; trashId: string } // çöpten kalıcı silindi
  | { type: "replaced"; volume: string; path: VolumePath }; // aynı dosya, aynı yol, yeni içerik

const finder = createTheFinder({
  volumes: [/* ... */],
  async onEntriesChanged(changes, ctx) {
    for (const c of changes) {
      // Klasör tek değişiklik olarak gelir: kendi yolunu ve `from.path + "/"` altındaki her yolu güncelleyin.
      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 ve EntryKind ("file" | "dir") @thefinder/core'dan dışa aktarılır.

Ne zaman çağrılır

• Komut başına bir kez, o komutun bütün değişiklikleri tek dizide; depolama işlemleri bittikten sonra ve onAfterCommand'dan önce. await edilir. Var olan hiçbir şeyi değiştirmeyen komutlar onu çağırmaz.
• Klasör, klasörün kendi yolu için tek değişikliktir. İçindekiler onunla birlikte taşınmış, çöpe gitmiş ya da silinmiştir ve tek tek listelenmez.
• Yollar gerçek sonuçtur. Çakışma yüzünden yeniden adlandıran bir yapıştırma yeni adı ("/docs/a (2).txt"), aynı ada dönemeyen bir geri yükleme de gittiği yolu bildirir.
• trashId, öğenin çöp kutusundaki kimliğidir: trash listesindeki Entry.trash.id, aynı zamanda çöp öğesinin yolunun son parçası (/.tf-trash/<trashId>). Öğenin id'si değildir. Aynı öğe trashed, restored ve purged'de aynı trashId ile gelir.
• Birden çok öğeli bir komut yarıda hata verirse (üçüncü öğesi hata veren beş öğelik bir yapıştırma) hatadan önce yaptıklarını yine bildirir; istek sonra her zamanki gibi hatayla döner.
• ctx komutun bağlamıdır, onBeforeCommand'ın aldığı nesnenin aynısı. Komut dışında yapılan değişikliklerde ctx null gelir. Bugün her değişiklik bir komut içinde olur (çöpün saklama süresi temizliği trash ve purge içinde çalışır), ama sonraki bir sürüm komut dışı değişiklikleri kodunuzu bozmadan bildirebilsin diye null'ı karşılayın.
• execute() da HTTP isteği gibi çağırır. Salt okunur bir istek hiçbir şeyi değiştiremediği için onu hiç çağırmaz.
• Yalnızca theFinder üzerinden yapılan değişiklikler görülür. Diskte ya da bucket'ta doğrudan değiştirilen dosyalar bildirilmez.

Olaylar

Hatalar. onAfterCommand gibi davranır: hata fırlatırsa istek hatayla döner (TheFinderError fırlatmadıkça 500 INTERNAL) ve onAfterCommand çalışmaz. Depolama işlemi o anda zaten yapılmıştır, yani istemci yapılmış bir iş için hata görür. Tablonuzun geride kalması kullanıcının isteğini düşürmemeliyse hatayı hook içinde yakalayın (ve örneğin yeniden denemeye kuyruklayın). Komutun kendisi hata verdiyse ve hook da fırlatırsa komutun hatası döner, hook'un hatası console.error ile yazılır.

Sürücüler#

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

• Dosyaları önce geçici bir dosyaya yazar, sonra yerine taşır. Böylece yarım kalan yazma asıl dosyayı bozmaz. Windows'ta hedef dosya başka bir programda açıksa yeniden dener.
• capacity() disk boyutunu bildirir (depolama paneli için).
• driver.root: çözülmüş mutlak kök yolu. driver.abs(path): volume yolunu işletim sistemi yoluna çevirir.

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

• İmzalama (SigV4) Web Crypto ile yapılır; AWS SDK gerekmez.
• Klasörler prefix olarak modellenir; boş klasörler klasör/ işaret nesnesiyle tutulur.
• Taşıma ve yeniden adlandırma kopyala + sil şeklindedir; klasörlerde prefix altındaki tüm nesneler işlenir.
• Yüklemeler multipart'tır ve sunucu durum tutmaz.
• Görsel editörünün S3'teki görselleri okuyabilmesi için bucket CORS ayarında uygulamanızın origin'ine GET izni verin.

StorageDriver arayüzü#

Yeni bir depolama (FTP, Azure Blob, Google Drive…) eklemek için bu arayüzü uygulamanız yeterlidir. Motor sürücüye her zaman normalize edilmiş yollar verir (/, /a/b.txt); sürücü .. görmez.

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

interface UploadChunk {
  path: VolumePath;   // ilk parçada doğrulanmış ve çakışmasız hedef
  session?: string;   // önceki parçanın döndürdüğü durum; ilk parçada undefined
  index: number; total: number;
  size: number;       // dosyanın toplam boyutu
  offset: number;     // parçanın bayt konumu
  data: Uint8Array;
}

Küçük resimler#

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

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

ThumbnailOptions#

Küçük resimler volume'ün .tf-thumbs/ klasöründe tutulur. Kaynak değişince yeniden üretilir; dosya silinince, taşınınca ya da adı değişince temizlenir.

sharpThumbnailer(options?)#

Okuduğu biçimler: jpg, jpeg, jfif, png, webp, gif, avif, tif, tiff, heic, heif. EXIF yönünü uygular, oranı korur, büyütmez. sharp yüklenemezse API çalışmaya devam eder, günlüğe bir kez uyarı yazılır ve orijinal görseller gönderilir.

Thumbnailer arayüzü#

interface Thumbnailer {
  extensions: string[];      // okuyabildiği uzantılar (küçük harf)
  extension?: string;        // üretilen dosya uzantısı, varsayılan "webp"
  generate(input: Uint8Array, size: number): Promise<Uint8Array>; // size×size kutusuna sığdır
}

Görsel işleme#

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

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

sharpImages(options?)#

Yazdığı biçimler: jpeg (mozjpeg), png (kalite < 100 ise paletli), webp, avif, gif. EXIF yönünü uygular, meta verileri siler, büyütmez. Kaynak ve hedef biçim destekliyorsa animasyon korunur. Bozuk girdide INVALID_IMAGE, piksel sınırında TOO_LARGE hatası verir. Aynı anda en fazla iki görsel işlenir, diğerleri sıra bekler.

ImageProcessor arayüzü#

interface ImageProcessor {
  extensions: string[];   // okuyabildiği uzantılar
  formats: ImageFormat[]; // yazabildiği biçimler: "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, varsayılan 80 */ }

Dosya sunumu#

createFileServer(options)#

Bir sürücüdeki dosyaları bir URL öneki altında sunan Web standardı handler.

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

Range, ETag/304, HEAD, doğru Content-Type ve ?download desteklenir. HTML ve SVG gibi etkin içerikler Content-Security-Policy: sandbox ile sunulur. GET/HEAD dışındaki yöntemler 405 döner.

serveFile(options)#

Kendi route'unuzda dosya yanıtı üretmek için alt düzey yardımcı.

Diğer yardımcılar: contentDisposition(type, filename) (RFC 6266/5987, UTF-8 adlar), parseRange(header, size) (ByteRange, "invalid" ya da null), etagOf(stat).

Node adaptörleri#

@thefinder/core/node. express.json() ya da koa-bodyparser gibi bir ayrıştırıcı gövdeyi önceden okumuşsa adaptör gövdeyi yeniden oluşturur.

Bir dosya sunucusunu da aynı şekilde bağlayabilirsiniz: app.get("/uploads/*", toExpress(createFileServer({ driver, prefix: "/uploads" }))).

Hatalar#

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

throw new TheFinderError("UNAUTHORIZED");           // mesaj varsayılanı kodun kendisi
throw new TheFinderError("FORBIDDEN", "Bu klasör size kapalı");

Hook'larda ya da sürücülerde fırlatılan TheFinderError istemciye kendi kodu ve mesajıyla iletilir. Diğer hatalar INTERNAL olur ve ayrıntıları yalnızca sunucu günlüğüne yazılır.

Yardımcılar#

interface ZipSource {
  name: string;          // arşiv içi yol; klasörler "/" ile biter
  mtime: number;
  size?: number;         // çok büyük dosyalarda zip64 kararı için
  open?: () => Promise<ReadableStream<Uint8Array>>;
}

Tipler#

Tüm tipler import type { … } from "@thefinder/core" ile alınabilir. Tarayıcı kodunda aynı tipler @thefinder/core/client üzerinden de gelir.

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 ve versions, o özellik kapalıysa null olur.

InitResult#

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

FileVersion#

{ id, size, createdAt, reason }. reason sürümü neyin değiştirdiğini söyler: edit, upload, replace, optimize, revert…

StorageStats#

VersionedFile: { id, path, name, exists, count, size, latest }. exists: false ise dosya silinmiş ya da theFinder dışında taşınmıştır, yani sürümleri sahipsizdir.

TransformResult#

Bu sayfa docs/api/tr/core.md dosyasından üretildi.