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

File system abstractions and implementations

export interface CrudApi {
    /**
     * 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?: Uint8Array | undefined, options?: CrudPutOptions) => Promise<void>;
    /**
     * 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.
     */
    getStream: (path: string) => Promise<ReadableStream>;
    /**
     * 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 {
    /**
     * 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 resource as `File` object.
     *
     * @param path Slash separated ID of the resource, document name.
     * @returns File resource.
     */
    getFile: (path: string) => Promise<File>;
    /**
     * 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>;
    /**
     * 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>;
    /**
     * 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>;
}
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 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;
}