@jupyterlite/services 0.1.0 → 0.7.0-rc.1

package/lib/contents/drive.d.ts

@@ -0,0 +1,278 @@
+import type { Contents, Drive } from '@jupyterlab/services';
+import { ServerConnection } from '@jupyterlab/services';
+import type { ISignal } from '@lumino/signaling';
+import type localforage from 'localforage';
+type IModel = Contents.IModel;
+/**
+ * The name of the drive.
+ */
+export declare const DRIVE_NAME = "BrowserStorage";
+/**
+ * A custom drive to store files in the browser storage.
+ */
+export declare class BrowserStorageDrive implements Contents.IDrive {
+    /**
+     * Construct a new localForage-powered contents provider
+     */
+    constructor(options: BrowserStorageDrive.IOptions);
+    /**
+     * Dispose the drive.
+     */
+    dispose(): void;
+    /**
+     * Whether the drive is disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * The name of the drive.
+     */
+    get name(): string;
+    /**
+     * The server settings of the drive.
+     */
+    get serverSettings(): ServerConnection.ISettings;
+    /**
+     * Signal emitted when a file operation takes place.
+     */
+    get fileChanged(): ISignal<Contents.IDrive, Contents.IChangedArgs>;
+    /**
+     * Get the download URL
+     */
+    getDownloadUrl(path: string): Promise<string>;
+    /**
+     * Finish any initialization after server has started and all extensions are applied.
+     *
+     * TODO: keep private?
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initialize all storage instances
+     */
+    protected initStorage(): Promise<void>;
+    /**
+     * A promise that resolves once all storage is fully initialized.
+     */
+    get ready(): Promise<void>;
+    /**
+     * A lazy reference to the underlying storage.
+     */
+    protected get storage(): Promise<LocalForage>;
+    /**
+     * A lazy reference to the underlying counters.
+     */
+    protected get counters(): Promise<LocalForage>;
+    /**
+     * A lazy reference to the underlying checkpoints.
+     */
+    protected get checkpoints(): Promise<LocalForage>;
+    /**
+     * Get default options for localForage instances
+     */
+    protected get defaultStorageOptions(): LocalForageOptions;
+    /**
+     * Initialize the default storage for contents.
+     */
+    protected createDefaultStorage(): LocalForage;
+    /**
+     * Initialize the default storage for counting file suffixes.
+     */
+    protected createDefaultCounters(): LocalForage;
+    /**
+     * Create the default checkpoint storage.
+     */
+    protected createDefaultCheckpoints(): LocalForage;
+    /**
+     * Clear all storage (files, counters, and checkpoints).
+     *
+     * @returns A promise which resolves when all storage is cleared.
+     */
+    clearStorage(): Promise<void>;
+    /**
+     * Create a new untitled file or directory in the specified directory path.
+     *
+     * @param options: The options used to create the file.
+     *
+     * @returns A promise which resolves with the created file content when the file is created.
+     */
+    newUntitled(options?: Contents.ICreateOptions): Promise<IModel>;
+    /**
+     * Copy a file into a given directory.
+     *
+     * @param path - The original file path.
+     * @param toDir - The destination directory path.
+     *
+     * @returns A promise which resolves with the new contents model when the
+     *  file is copied.
+     *
+     * #### Notes
+     * The server will select the name of the copied file.
+     */
+    copy(path: string, toDir: string): Promise<IModel>;
+    /**
+     * Get a file or directory.
+     *
+     * @param path: The path to the file.
+     * @param options: The options used to fetch the file.
+     *
+     * @returns A promise which resolves with the file content.
+     */
+    get(path: string, options?: Contents.IFetchOptions): Promise<IModel>;
+    /**
+     * Rename a file or directory.
+     *
+     * @param oldLocalPath - The original file path.
+     * @param newLocalPath - The new file path.
+     *
+     * @returns A promise which resolves with the new file content model when the file is renamed.
+     */
+    rename(oldLocalPath: string, newLocalPath: string): Promise<IModel>;
+    /**
+     * Save a file.
+     *
+     * @param path - The desired file path.
+     * @param options - Optional overrides to the model.
+     *
+     * @returns A promise which resolves with the file content model when the file is saved.
+     */
+    save(path: string, options?: Partial<IModel>): Promise<IModel>;
+    /**
+     * Delete a file from browser storage.
+     *
+     * Has no effect on server-backed files, which will re-appear with their
+     * original timestamp.
+     *
+     * @param path - The path to the file.
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * Remove the localForage and checkpoints for a path.
+     *
+     * @param path - The path to the file
+     */
+    protected forgetPath(path: string): Promise<void>;
+    /**
+     * Create a checkpoint for a file.
+     *
+     * @param path - The path of the file.
+     *
+     * @returns A promise which resolves with the new checkpoint model when the
+     *   checkpoint is created.
+     */
+    createCheckpoint(path: string): Promise<Contents.ICheckpointModel>;
+    /**
+     * List available checkpoints for a file.
+     *
+     * @param path - The path of the file.
+     *
+     * @returns A promise which resolves with a list of checkpoint models for
+     *    the file.
+     */
+    listCheckpoints(path: string): Promise<Contents.ICheckpointModel[]>;
+    protected normalizeCheckpoint(model: IModel, id: number): Contents.ICheckpointModel;
+    /**
+     * Restore a file to a known checkpoint state.
+     *
+     * @param path - The path of the file.
+     * @param checkpointID - The id of the checkpoint to restore.
+     *
+     * @returns A promise which resolves when the checkpoint is restored.
+     */
+    restoreCheckpoint(path: string, checkpointID: string): Promise<void>;
+    /**
+     * Delete a checkpoint for a file.
+     *
+     * @param path - The path of the file.
+     * @param checkpointID - The id of the checkpoint to delete.
+     *
+     * @returns A promise which resolves when the checkpoint is deleted.
+     */
+    deleteCheckpoint(path: string, checkpointID: string): Promise<void>;
+    /**
+     * Handle an upload chunk for a file.
+     * each chunk is base64 encoded, so we need to decode it and append it to the
+     * original content.
+     * @param newContent the new content to process, base64 encoded
+     * @param originalContent the original content, must be null or a binary string if chunked is true
+     * @param appendChunk whether the chunk should be appended to the originalContent
+     *
+     *
+     * @returns the decoded binary string, appended to the original content if requested
+     * /
+     */
+    private _handleUploadChunk;
+    /**
+     * Convert a binary string to an Uint8Array
+     * @param binaryString the binary string
+     * @returns the bytes of the binary string
+     */
+    private _binaryStringToBytes;
+    /**
+     * retrieve the contents for this path from the union of local storage and
+     * `api/contents/{path}/all.json`.
+     *
+     * @param path - The contents path to retrieve
+     *
+     * @returns A promise which resolves with a Map of contents, keyed by local file name
+     */
+    private _getFolder;
+    /**
+     * Attempt to recover the model from `{:path}/__all__.json` file, fall back to
+     * deriving the model (including content) off the file in `/files/`. Otherwise
+     * return `null`.
+     */
+    private _getServerContents;
+    /**
+     * A reducer for turning arbitrary binary into a string
+     */
+    protected reduceBytesToString: (data: string, byte: number) => string;
+    /**
+     * retrieve the contents for this path from `__index__.json` in the appropriate
+     * folder.
+     *
+     * @param newLocalPath - The new file path.
+     *
+     * @returns A promise which resolves with a Map of contents, keyed by local file name
+     */
+    private _getServerDirectory;
+    /**
+     * Increment the counter for a given file type.
+     * Used to avoid collisions when creating new untitled files.
+     *
+     * @param type The file type to increment the counter for.
+     */
+    private _incrementCounter;
+    private _serverContents;
+    private _isDisposed;
+    private _fileChanged;
+    private _storageName;
+    private _storageDrivers;
+    private _ready;
+    private _storage;
+    private _counters;
+    private _checkpoints;
+    private _localforage;
+    private _serverSettings;
+}
+/**
+ * A namespace for contents information.
+ */
+export declare namespace BrowserStorageDrive {
+    /**
+     * The options used to create a BrowserStorageDrive.
+     */
+    interface IOptions extends Drive.IOptions {
+        /**
+         * The name of the storage instance on e.g. IndexedDB, localStorage
+         */
+        storageName?: string | null;
+        /**
+         * The drivers to use for storage.
+         */
+        storageDrivers?: string[] | null;
+        /**
+         * The localForage instance to use.
+         */
+        localforage: typeof localforage;
+    }
+}
+export {};