Disposable Temporary Files

Built-in, native disposable temporary file manager integrated into __sys__.fs for creating short-lived scratch files with zero-config automatic cleanup.

XyPriss allows developers to generate temporary scratch files (such as PDF exports, image conversions, session tokens, or upload buffers) stored within an isolated user directory (__sys__.fs.tmpUserDir). All temporary files are safely tracked and automatically unlinked when TTL expires, when the server reloads or exits, or on demand.

Automatic Cleanup Triggers

API Reference

1. Sub-API Namespace (__sys__.fs.tmp)

• __sys__.fs.tmp.write(content, options?): Promise<TempFileResult> — Write temporary file (async).
• __sys__.fs.tmp.writeSync(content, options?): TempFileResult — Write temporary file (sync).
• __sys__.fs.tmp.read(path): Promise<string> — Read temporary file (async).
• __sys__.fs.tmp.readSync(path): string — Read temporary file (sync).
• __sys__.fs.tmp.remove(path): boolean — Remove a specific temporary file on disk.
• __sys__.fs.tmp.dir: string — Access the isolated user temporary directory (tmpUserDir).
• __sys__.fs.tmp.cleanup(): number / purge(): number — Purge all active temporary files in current session.

2. Direct Shorthand Methods (__sys__.fs)

• __sys__.fs.writeTempFile(content, options?): Promise<TempFileResult>
• __sys__.fs.writeTempFileSync(content, options?): TempFileResult
• Aliases: createTempFile, createTempFileSync, writeTmpFile, writeTmpFileSync
• __sys__.fs.cleanupTempFiles(): number

Configuration Options (TempFileOptions)

Return Handle (TempFileResult)

interface TempFileResult {
    /** Absolute path to the created temporary file inside tmpUserDir */
    path: string;
    /** Filename of the temporary file */
    filename: string;
    /** Size of the temporary file in bytes */
    size: number;
    /** Timestamp when the file was created (in ms) */
    createdAt: number;
    /** Expiration timestamp in ms (or null if no TTL) */
    expiresAt: number | null;
    /** Manually deletes the temporary file immediately. Returns true if deleted. */
    remove: () => boolean;
    /** Alias for remove() */
    cleanup: () => boolean;
}

Code Examples

1. Temporary PDF Export with 5-Minute TTL

import { __sys__ } from "xypriss";

// Create a disposable PDF report expiring in 5 minutes
const report = await __sys__.fs.writeTempFile(pdfBuffer, {
    prefix: "financial_report_",
    extension: ".pdf",
    ttl: "5m",
});

console.log(`Temporary PDF generated at: ${report.path}`);
// Deliver to client or pipeline...
// Will be automatically unlinked after 5 minutes or on server restart.

2. Immediate On-Demand Cleanup

import { __sys__ } from "xypriss";

const tmp = __sys__.fs.writeTmpFileSync(JSON.stringify(payload), {
    prefix: "cache_",
    extension: ".json",
});

try {
    // Process payload...
} finally {
    // Ensure immediate deletion as soon as processing completes
    tmp.cleanup();
}

3. Session Scratch Space with Shorthand Alias

import { __sys__ } from "xypriss";

const scratch = await __sys__.fs.createTempFile("temporary log data", {
    prefix: "user_session_",
    extension: ".log",
    ttl: "1h",
});