observablehq-file-attachments/lib/esm/AFileSystem.d.ts

Library to handle ObservableHQ's file attachments more flexibly, and to support virtualizing them.

/**
 * The main entry for creating a virtual data filesystem.
 *
 * ```javascript
 * import { AFileSystem, AFile} from '@bobkerns/file-attachments'
 *
 * F = new AFileSystem(
 *     {
 *         data: {
 *             // Arrays denote file versions.
 *             table1: [
 *                 FileAttachment('Table1.json'),
 *                 FileAttachment('Table1.json@2')
 *             ],
 *             table2: [AFile('table2', {data: [[1, 5, 3] [2, 6, 4]]})]
 *         },
 *         test: {
 *             table1: [FileAttachment('Table1-test.json')]
 *         }
 *     }
 *   });
 * // Make table2 appear in the /test directory as well.
 * F.copy('/data/table2', '/test/table2'); // Perhaps more like a hard link
 * // Label Version 2 of /data/table1 as 'release'
 * // It can then be referenced as /label/table1@release, even if additional
 * // versions are added later.
 * F.label('/data/table1@2', 'release');
 *
 * // The notebook awaits
 * TABLE1 = F.find('/data/table1').json();
 *
 * // Doesn't exist, so returns undefined
 * NO_FILE = F.find('/noFile').json();
 *
 * // To get an error if the file doesn't exist:
 * ERROR_FILE = F.find('/noFile').exists.json();
 *
 * // To get a file, once it is available
 * AWAIT_FILE = F.waitFor('/notYet').json();
 *
 * // To add a file:
 * F.add('/notYet', new AFile('notYet', {Some: 'data'}));
 *
 * // To get a file's data when added and receive updates.
 * UPDATED_FILE = F.watch('/updatedFile').json();
 *
 * // Add some updates.
 * {
 *     for (i in range(0, 10)) {
 *         await sleep(1000);
 *         F.add('/updatedFile', new AFile('/updatedFile', {data: i}));
 *     }
 * }
 *
 * // Metadata
 * METADATA_TABLE1 = F.metadata('/test/table2');
 * ```
 *
 * @module AFileSystem
 * @preferred
 * @packageDocumentation
 */
import { Regenerable, Tree, Metadata, VFile } from './types';
/**
 * The `AFileSystem` constructor takes a single argument, which represents an initial filesystem content.
 *
 * Every Object (not subclasses, but literal objects) represent a directory,
 * while every array holds the versions of a logical file.
 *
 * Versions are specified on lookup by appending _@version_ to the path. No version
 * specified is the same as `@latest`, which obtains the highest numbered version
 * (the last in the array). You can ignore named versions (labels), or even multiple
 * versions, but files are always identified by being in an array.
 *
 * A file can be any value, but normally they will be either an
 * [FileAttachment](https://observablehq.com/@observablehq/file-attachments) or an
 * [AFile](#AFile); they implement the same interface.
 *
 * The actual file is not returned, but rather an [AFileAwait](#AFileAwait). This is a proxy with the same
 * methods, but the methods return `undefined` if the file specified is not found.
 */
export declare class AFileSystem implements Regenerable {
    readOnly: boolean;
    name: string;
    tree: Tree;
    subscription: AsyncGenerator<this>;
    updateCount: number;
    errored: (e: Error) => void;
    updated: (n: this) => void;
    /**
     *
     * @param tree The specification of what directories and files to initialize the filesystem with
     * @param options Optional options: _readOnly_ and _name_
     */
    constructor(tree: Tree, options?: {
        readOnly?: boolean;
        name?: string;
    });
    /**
     * Find the file at the given (possibly versioned) path.
     *
     * @param path the full pathname to the desired file
     * @returns An {@link AFileAwait}
     */
    find(path: string): any;
    /**
     * Wait for the requested path. The return value is an async generator
     *  that yields when the requested path is available.
     * @param path Path to the file
     * @returns An async generator yielding a value for the file when it becomes available..
     */
    waitFor(path: string): AsyncGenerator<any, void, unknown>;
    /**
     * Wait for the requested path. The return value is an async generator
     * that yields once for each value stored at path.
     * @param path Path to the file
     * @param nullOK if true, `null` will be returned by the generator whenever the file does not exist; by default it is filtered out.
     * @returns An async generator yielding values for a file as it changes (new versions created/deleted).
     */
    watch(path: string, nullOK?: boolean): AsyncGenerator<any, void, unknown>;
    /**
     * Return the metadata for the requested path. Metadata can be associated with either a specific
     * version, or the entire collection of versions at a path. The results are merged.
     * @param path Path to the file
     * @returns Promise yielding Metadata or `null` if the file is not found.
     */
    metadata(path: string): Promise<Metadata | null>;
    /**
     * Add a new file at the specified path. If no version, or 'latest', adds a new version.
     * Otherwise sets the specified version or label.
     * @param path Path to store the file
     * @param file The file, either an [FileAttachment](https://observablehq.com/@observablehq/file-attachments) or an [[AFile]].
     * @returns the file
     */
    add(path: string, file: VFile): any;
    /**
     * Copy file from to. If 'latest' or unspecified, copies only the latest.
     * @param from Path to the existing file
     * @param to Path to the destination
     * @returns the file copied
     */
    copy(from: string, to: string): any;
    /**
     * Label the version at the specified path with 'label'.  A label selects a specific version of a file;
     * it is not a property of a file version.
     * @param path Path to the file
     * @param label Label to add to the file
     * @returns The file labeled.
     */
    label(path: string, label: string): any;
    /**
     * Preserve the class name across minification.
     */
    [Symbol.toStringTag]: 'AFileSystem';
}
//# sourceMappingURL=AFileSystem.d.ts.map