send-stream/dist/src/file-system-storage.d.ts

Streaming file serving library with Range and conditional-GET support from file system or any streaming sources.

import type { Dir, Dirent, Stats } from 'node:fs';
import { Readable } from 'node:stream';
import { Storage } from './storage';
import type { StorageRequestHeaders, StorageInfo } from './types';
import type { StreamRange } from './utils';
import type { FilePath, FileSystemStorageOptions, RegexpContentEncodingMapping, GenericFileSystemStorageOptions, GenericFileData, GenericFSModule } from './file-system-types';
/**
 * Escape HTML in path for this library (only replace & character since ", < and > are already excluded)
 * @param path - the path to escape
 * @returns the escaped path
 */
export declare function escapeHTMLInPath(path: string): string;
export declare const FORBIDDEN_CHARACTERS: RegExp;
/**
 * File system storage
 * @template FileDescriptor - file descriptor type
 */
export declare class GenericFileSystemStorage<FileDescriptor> extends Storage<FilePath, GenericFileData<FileDescriptor>> {
    /**
     * Root directory
     */
    readonly root: string;
    /**
     * Content encoding mappings array (or false if disabled)
     */
    readonly contentEncodingMappings: readonly RegexpContentEncodingMapping[] | false;
    /**
     * Ignore pattern (or false if disabled)
     */
    readonly ignorePattern: RegExp | false;
    /**
     * On directory action
     *
     * - 'serve-index' to serve directory's index.html
     * - 'list-files' to list directory files
     * - (or false if disabled)
     */
    readonly onDirectory: 'serve-index' | 'list-files' | false;
    /**
     * fs.open function
     */
    readonly fsOpen: (path: string, flags: number) => Promise<FileDescriptor>;
    /**
     * fs.fstat function
     */
    readonly fsFstat: (fd: FileDescriptor) => Promise<Stats>;
    /**
     * fs.close function
     */
    readonly fsClose: (fd: FileDescriptor) => Promise<void>;
    /**
     * fs.createReadStream function
     */
    readonly fsCreateReadStream: GenericFSModule<FileDescriptor>['createReadStream'];
    /**
     * fs.opendir function
     */
    readonly fsOpendir: ((path: string) => Promise<Dir>) | undefined;
    /**
     * fs.readdir function
     */
    readonly fsReaddir: (path: string, options: {
        withFileTypes: true;
    }) => Promise<Dirent[]>;
    /**
     * fs.constants constants
     */
    readonly fsConstants: GenericFSModule<FileDescriptor>['constants'];
    /**
     * Create file system storage
     * @param root - root folder path
     * @param opts - file system storage options
     */
    constructor(root: string, opts: GenericFileSystemStorageOptions<FileDescriptor>);
    /**
     * Parse and check url encoded path or path array
     * @param path - url encoded path or path array to be accessed from root
     * @returns path array
     * @throws when the path can not be parsed
     */
    parsePath(path: FilePath): {
        pathParts: readonly string[];
        haveTrailingSlash: boolean;
    };
    /**
     * Open file, return undefined if does not exist
     * @param path - file path
     * @returns file handle
     */
    safeOpen(path: string): Promise<FileDescriptor | undefined>;
    /**
     * Get Stat object from file descriptor
     * @param fd - file descriptor
     * @param _path - file path (unused but can be useful for caching on override)
     * @returns Stat object
     */
    stat(fd: FileDescriptor, _path: string): Promise<Stats>;
    /**
     * Close file descriptor
     * @param fd - file descriptor
     * @param _path - file path (unused but can be useful for caching on override)
     * @returns Stat object
     */
    earlyClose(fd: FileDescriptor, _path: string): Promise<void>;
    /**
     * Open file and retrieve storage information (filename, modification date, size, ...)
     * @param path - file path
     * @param requestHeaders - request headers
     * @returns StorageInfo object
     * @throws when the file can not be opened
     */
    open(path: FilePath, requestHeaders: StorageRequestHeaders): Promise<StorageInfo<GenericFileData<FileDescriptor>>>;
    /**
     * Async generator method to return the directory listing as HTML
     * @param storageInfo - storage information
     * @yields html parts
     */
    getDirectoryListing(storageInfo: StorageInfo<GenericFileData<FileDescriptor>>): AsyncGenerator<string, void, void>;
    /**
     * Returns the list of files from a directory
     * @param storageInfo - storage information
     * @returns the list of files
     */
    opendir(storageInfo: StorageInfo<GenericFileData<FileDescriptor>>): Promise<Dir | AsyncIterable<Dirent>>;
    /**
     * Create readable stream from storage information
     * @param storageInfo - storage information
     * @param range - range to use or undefined if size is unknown
     * @param autoClose - true if stream should close itself
     * @returns readable stream
     */
    createReadableStream(storageInfo: StorageInfo<GenericFileData<FileDescriptor>>, range: StreamRange | undefined, autoClose: boolean): Readable;
    /**
     * Close storage information
     * @param storageInfo - storage information
     * @returns void
     */
    close(storageInfo: StorageInfo<GenericFileData<FileDescriptor>>): Promise<void>;
}
export declare class FileSystemStorage extends GenericFileSystemStorage<number> {
    constructor(root: string, opts?: FileSystemStorageOptions);
}