FileSystemSyncAccessHandle.truncate() — Methode · JavaScript-Referenz

Signatur

FileSystemSyncAccessHandle.prototype.truncate(newSize)

Beschreibung

Die Methode truncate() setzt die Größe einer Datei im Origin Private File System (OPFS) auf einen festen Wert in Bytes. Ist newSize kleiner als die aktuelle Größe, werden die überzähligen Bytes am Ende entfernt. Ist der Wert größer, wird die Datei vergrößert und der neue Bereich mit Nullbytes (0x00) gefüllt.

Wie alle Methoden von FileSystemSyncAccessHandle arbeitet truncate() synchron. Deshalb steht sie nur in dedizierten Web Workern zur Verfügung, wo blockierende Aufrufe die Benutzeroberfläche nicht einfrieren. Typische Einsatzfälle: eine Datei vor dem Neuschreiben komplett leeren (truncate(0)), Log- oder Cache-Dateien auf eine Maximalgröße kürzen, Speicher für Datenbankdateien vorab reservieren (z. B. SQLite-WASM-Backends) oder einen abgebrochenen Schreibvorgang zurückrollen.

Steht die Dateiposition (der interne Cursor) hinter der neuen Größe, wird sie auf newSize zurückgesetzt. Änderungen landen im Dateisystem, spätestens aber nach flush() bzw. close() sind sie garantiert dauerhaft gespeichert.

Parameter

Name	Typ	Default	Beschreibung
$newSize Pflicht	number		Die neue Dateigröße in Bytes. Wird intern in einen `unsigned long long` umgewandelt, also als nicht-negative Ganzzahl behandelt.

Beispiele

Datei vor dem Neuschreiben leeren (im Worker)

// worker.js – als dedizierter Worker gestartet
const root = await navigator.storage.getDirectory();
const fileHandle = await root.getFileHandle('settings.json', { create: true });
const access = await fileHandle.createSyncAccessHandle();

try {
  const data = new TextEncoder().encode(JSON.stringify({ theme: 'dark' }));
  access.truncate(0);                 // alten Inhalt komplett entfernen
  access.write(data, { at: 0 });
  access.flush();
  console.log('Größe:', access.getSize());
} finally {
  access.close();
}

Größe: 16

Log-Datei auf maximale Größe begrenzen

const MAX_BYTES = 1024 * 1024; // 1 MiB

const root = await navigator.storage.getDirectory();
const log = await root.getFileHandle('app.log', { create: true });
const access = await log.createSyncAccessHandle();

try {
  const size = access.getSize();
  if (size > MAX_BYTES) {
    access.truncate(MAX_BYTES);
    console.log(`Log von ${size} auf ${MAX_BYTES} Bytes gekürzt`);
  }
} finally {
  access.close();
}

Log von 1310720 auf 1048576 Bytes gekürzt

Speicher vorab reservieren und Nullbytes prüfen

const root = await navigator.storage.getDirectory();
const fh = await root.getFileHandle('db.bin', { create: true });
const access = await fh.createSyncAccessHandle();

try {
  access.truncate(4096);               // auf 4 KiB vergrößern
  const buf = new Uint8Array(4);
  access.read(buf, { at: 4092 });
  console.log(access.getSize(), buf);
} catch (err) {
  if (err.name === 'QuotaExceededError') {
    console.error('Nicht genug Speicherkontingent');
  } else {
    throw err;
  }
} finally {
  access.close();
}

4096 Uint8Array(4) [0, 0, 0, 0]

// Wichtig · Fallstricke

Nur in dedizierten Workern: Im Hauptthread, in Shared Workern oder in Service Workern gibt es createSyncAccessHandle() nicht. Wer im Hauptthread die Dateigröße ändern will, nimmt FileSystemWritableFileStream.truncate().
Ausnahmen: InvalidStateError, wenn das Handle bereits mit close() geschlossen wurde. QuotaExceededError, wenn die neue Größe das Speicherkontingent des Ursprungs übersteigt. TypeError, wenn das zugrunde liegende Dateisystem keine Größenänderung erlaubt.
Rückgabetyp geändert: Chromium vor Version 108 gab ein Promise zurück. Wer alte Versionen unterstützen muss, kann vorsichtshalber await access.truncate(n) schreiben – bei undefined schadet das nicht.
Exklusive Sperre: Solange ein Sync-Handle offen ist, ist die Datei gesperrt. Andere createSyncAccessHandle()- oder createWritable()-Aufrufe schlagen fehl. Deshalb das Handle immer in finally schließen.
Negative Werte werden per WebIDL-Konvertierung zu sehr großen Zahlen und lösen meist einen QuotaExceededError aus. Prüfe newSize also vorher.

Siehe auch

FileSystemSyncAccessHandle.write() FileSystemSyncAccessHandle.read() FileSystemSyncAccessHandle.close() FileSystemSyncAccessHandle.flush() FileSystemSyncAccessHandle.getSize()