fs-zoo/lib/crud/types.d.ts

File system abstractions and implementations

import type { SnapshotNodeType } from './constants';
export interface CrudApi {
    /**
     * Creates a new collection.
     * @param path Slash separated ID of the collection to create.
     * @param options Write behavior options.
     */
    dir(path: string, options?: Pick<CrudPutOptions, 'throwIf'>): Promise<void>;
    /**
     * Creates a new resource, or overwrites an existing one.
     *
     * @param path Slash separated ID of the resource, document name.
     * @param data Blob content of the resource.
     * @param options Write behavior options.
     */
    put(path: string, data: Uint8Array, options?: CrudPutOptions): Promise<void>;
    /**
     * Creates a writable stream for a resource.
     *
     * @param path Slash separated ID of the resource, document name.
     * @param options Write behavior options.
     */
    write(path: string, options?: CrudPutOptions): Promise<WritableStream>;
    /**
     * Retrieves the content of a resource as a file.
     *
     * @param path Slash separated ID of the resource, document name.
     * @returns Blob content of the resource.
     */
    read(path: string): Promise<ReadableStream>;
    /**
     * Retrieves the resource as `File` object.
     *
     * @param path Slash separated ID of the resource, document name.
     * @returns File resource.
     */
    file?(path: string): Promise<File>;
    /**
     * Deletes a resource.
     *
     * @param path Slash separated ID of the resource, document name.
     * @param silent When true, does not throw an error if the collection or
     *               resource does not exist. Default is false.
     */
    del(path: string, silent?: boolean): Promise<void>;
    /**
     * Deletes all resources of a collection, and deletes recursively all
     * sub-collections.
     *
     * @param path Slash separated ID of a collection.
     * @param silent When true, does not throw an error if the collection or
     *     resource does not exist. Default is false.
     */
    drop(path: string, silent?: boolean): Promise<void>;
    /**
     * Fetches information about a resource.
     *
     * @param path Slash separated ID of the resource, document name, if any.
     * @returns Information about the resource.
     */
    info(path: string): Promise<CrudResourceInfo>;
    /**
     * Iterates over all resources of a collection.
     *
     * @param path Slash separated ID of a collection.
     * @returns Iterator of resources of the given type.
     */
    scan(path: string): AsyncIterableIterator<CrudCollectionEntry>;
    /**
     * Fetches a list of resources of a collection, and sub-collections.
     *
     * @param path Slash separated ID of a collection.
     * @returns List of resources of the given type, and sub-types.
     */
    list(path: string): Promise<CrudCollectionEntry[]>;
    /**
     * Creates a new CrudApi instance, with the collection specified by `path` as root.
     *
     * @param path Slash separated ID of a collection.
     * @returns A new CrudApi instance, with the given collection as root.
     */
    from(path: string): Promise<CrudApi>;
}
export interface CrudApiExtended extends CrudApi {
    /**
     * Creates a new collection.
     * @param path Slash separated ID of the collection to create.
     * @param options Write behavior options.
     */
    dir(path: string, options?: Pick<CrudPutOptions, 'throwIf'>): Promise<void>;
    /**
     * Checks if a resource exists. Returns its information if it does.
     *
     * @param path Slash separated ID of the resource, document name.
     * @returns Information about the resource if it exists, otherwise undefined.
     */
    exists(path: string): Promise<CrudResourceInfo | undefined>;
    /**
     * Creates a new resource, or overwrites an existing one.
     *
     * @param path Slash separated ID of the resource, document name.
     * @param data Blob content of the resource. If omitted, creates a new collection.
     * @param options Write behavior options.
     */
    put(path: string, data?: string | Uint8Array | undefined, options?: CrudPutOptions): Promise<void>;
    /**
     * Puts a JavaScript string in a resource as UTF-8 encoded text. Creates
     * a new resource if it does not exist, or overwrites an existing one.
     *
     * @param path Slash separated ID of the resource, document name.
     * @param text JavaScript string, to be stored as UTF-8 encoded text.
     * @param options Write behavior options.
     */
    putUtf8(path: string, text: string, options?: CrudPutOptions): Promise<void>;
    /**
     * Retrieves the content of a resource.
     *
     * @param path Slash separated ID of the resource, document name.
     * @returns Blob content of the resource.
     */
    get(path: string): Promise<Uint8Array>;
    /**
     * Retrieves the content of a resource by treating it as a UTF-8 string.
     *
     * @param path Slash separated ID of the resource, document name.
     * @returns JavaScript string.
     */
    getUtf8(path: string): Promise<string>;
    /**
     * Retrieves the resource as `File` object.
     *
     * @param path Slash separated ID of the resource, document name.
     * @returns File resource.
     */
    file(path: string): Promise<File>;
    /**
     * Creates a new CrudApiExtended instance, with the collection specified by `path` as root.
     *
     * @param path Slash separated ID of a collection.
     * @returns A new CrudApiExtended instance, with the given collection as root.
     */
    from(path: string): Promise<CrudApiExtended>;
    /**
     * Recursively scans a collection and its sub-collections.
     *
     * @param path Slash separated ID of a collection.
     * @returns Iterator of resources of the given type.
     */
    deepScan(path: string): AsyncIterableIterator<DeepCrudCollectionEntry>;
    /**
     * Copies a resource or collection to a new location. Does not modify the
     * original. If the `path` is a collection, recursively deeply copies all
     * resources within the collection.
     *
     * Recursive copy into "itself" are not allowed. Throws if the target
     * location already exists.
     *
     * @param path Slash separated ID of the resource or collection to copy.
     * @param target Slash separated ID of the target location.
     */
    cp(path: string, target: string): Promise<void>;
    /**
     * Converts the file system at the given path to a serializable snapshot. The
     * nested snapshot is best used for testing, for capturing the exact state of
     * the file system at a specific point in time.
     *
     * @param path Slash separated ID of the resource or collection to snapshot.
     * * @param fast If true, skips UTF-8 decoding for file contents and sorting directory entries.
     */
    toNested(path?: string, fast?: boolean): Promise<NestedSnapshot>;
    /**
     * Restores the file system at the given path from a snapshot.
     *
     * @param snapshot Snapshot to restore from.
     * @param path Slash separated ID of the resource or collection to restore.
     */
    fromNested(snapshot: NestedSnapshot, path?: string): Promise<void>;
    /**
     * Converts the file system at the given path to a flat snapshot. The flat
     * snapshot is most human-readable.
     *
     * @param path Slash separated ID of the resource or collection to snapshot.
     * @param fast If true, skips UTF-8 decoding for file contents.
     * @param folders If true, includes empty folders in the snapshot.
     * @param verbose If true, includes full folder and file entries, even if they
     *     can be shortened.
     */
    toFlat(path?: string, fast?: boolean, folders?: boolean, verbose?: boolean): Promise<FlatSnapshot>;
    /**
     * Restores the file system at the given path from a flat snapshot.
     *
     * @param snapshot Flat snapshot to restore from.
     * @param path Slash separated ID of the resource or collection to restore.
     */
    fromFlat(snapshot: FlatSnapshot, path?: string): Promise<void>;
    /**
     * Converts the file system at the given path to a stream of snapshot
     * entries. The stream snapshot is best suited for large file systems, or
     * streaming over the network.
     *
     * @param path Slash separated ID of the resource or collection to snapshot.
     */
    toBytes(path?: string): Promise<ReadableStream>;
    /**
     * Restores the file system at the given path from a stream of snapshot
     * entries.
     *
     * @param stream Readable stream of snapshot entries.
     * @param path Slash separated ID of the resource or collection to restore.
     */
    fromBytes(stream: ReadableStream, path?: string): Promise<void>;
}
export interface CrudPutOptions {
    /**
     * Specifies conditions for throwing an error.
     */
    throwIf?: 'exists' | 'missing';
    /**
     * Specifies the position where to write the data. If not set, or set to
     * `undefined` the existing resource is discarded and the new data replaces
     * it. If set, the new data will be inserted at the specified position. If
     * set, to `-1` the new data will be appended to the existing resource.
     */
    pos?: undefined | number | -1;
}
export interface CrudCollectionEntry {
    /** Kind of the resource, type or item. */
    type: 'resource' | 'collection';
    /** Name of the resource. */
    id: string;
}
export interface DeepCrudCollectionEntry extends CrudCollectionEntry {
    /**
     * Slash separated full path to the resource or collection.
     */
    path: string;
}
export interface CrudResourceInfo extends CrudCollectionEntry {
    /** Size of the resource in bytes. */
    size?: number;
    /** Timestamp when the resource last modified. */
    modified?: number;
    /** Timestamp when the resource was created. */
    created?: number;
    /** Whether the resource is readable. */
    readable?: boolean;
    /** Whether the resource is writable. */
    writable?: boolean;
}
export interface SnapshotFolderMetadata {
}
export interface SnapshotFileMetadata {
}
export type NestedSnapshot = NestedSnapshotFolder | NestedSnapshotFile;
export type NestedSnapshotFolder = [
    type: SnapshotNodeType.Folder,
    meta: SnapshotFolderMetadata,
    entries: [name: string, node: NestedSnapshot][]
];
export type NestedSnapshotFile = [type: SnapshotNodeType.File, meta: SnapshotFileMetadata, data: Uint8Array | string];
export interface FlatSnapshot {
    [path: string]: FlatSnapshotFile | FlatSnapshotFolder | FlatSnapshotFile[2] | null;
}
export type FlatSnapshotFile = [type: SnapshotNodeType.File, meta: SnapshotFileMetadata, data: Uint8Array | string];
export type FlatSnapshotFolder = [type: SnapshotNodeType.Folder, meta?: SnapshotFolderMetadata];
export type StreamSnapshot = StreamSnapshotEntry[];
export type StreamSnapshotEntry = StreamSnapshotFolder | StreamSnapshotFile | Uint8Array;
export type StreamSnapshotFolder = [type: SnapshotNodeType.Folder, dirname: string, meta?: SnapshotFolderMetadata];
export type StreamSnapshotFile = [type: SnapshotNodeType.File, filename: string, meta?: SnapshotFileMetadata];