@harperfast/harper 5.0.0-alpha.10

package/dist/resources/blob.d.ts

@@ -0,0 +1,137 @@
+/**
+ * This module provides a Blob class that can be used to store binary data in the database, and can be used to store large binary data in a file
+ * on the server. The Blob class is a subclass of the global Blob class, and can be used in the same way.
+ * The Blob-backed files begin with an 8-byte header:
+ * - The first 2 bytes indicate the type of storage:
+ * 		- 0: Uncompressed
+ * 		- 1: Compressed with deflate
+ * 	  - 0xff: Error state (followed by error message). A record can be saved prior to an error in saving a blob, so we must be capable of tracking and even replicating that state
+ * - The next 6 bytes are the size of the content
+ *   - While the file is being written, 0xffffffffffff is used as a placeholder to indicate that the file is not finished being written (this nicely matches the logic that if the written content size is less than the indicated content size, it is not finished)
+ *   - Note that for compressed data, the size is the uncompressed size, and the compressed size in the file
+ */
+import type { LMDBStore } from 'lmdb';
+import { RocksDatabase } from '@harperfast/rocksdb-js';
+type StorageInfo = {
+    storageIndex: number;
+    fileId: string;
+    store?: any;
+    filePath?: string;
+    recordId?: number;
+    contentBuffer?: Buffer;
+    source?: NodeJS.ReadableStream;
+    storageBuffer?: Buffer;
+    compress?: boolean;
+    flush?: boolean;
+    start?: number;
+    end?: number;
+    saving?: Promise<void>;
+    asString?: string;
+    deleteOnFailure?: boolean;
+};
+export declare const Blob: any;
+export declare let blobsWereEncoded: boolean;
+declare function InstanceOfBlobWithNoConstructor(): void;
+declare namespace InstanceOfBlobWithNoConstructor {
+    var prototype: any;
+}
+/**
+ * A blob that is backed by a file, and can be saved to the database as a reference
+ * Note that this is used instead of the native Blob class for a few reasons:
+ * 1. This has the built-in functionality for reading from the file-based storage
+ * 2. This support for streams and asynchronous access to data that may not have a known size ahead of time
+ * 3. This also avoids the Blob constructor which is expensive due to the transferred setup
+ * Harper still supports saving native Blobs, but when they blobs are retrieved from storage, they always use this class.
+ */
+declare class FileBackedBlob extends InstanceOfBlobWithNoConstructor {
+    #private;
+    type: string;
+    size: number;
+    finished: Promise<void>;
+    saveBeforeCommit: boolean;
+    saveInRecord: boolean;
+    constructor(options?: BlobCreationOptions);
+    on(type: string, callback: (error: Error) => void): void;
+    toJSON(): string | {
+        description: string;
+    };
+    text(): Promise<string>;
+    bytes(): Promise<Buffer>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    stream(): ReadableStream;
+    slice(start: number, end: number, type?: string): Blob;
+    get written(): Promise<void>;
+}
+/**
+ * Delete the file for the blob
+ * @param blob
+ */
+export declare function deleteBlob(blob: Blob): void;
+export declare function setDeletionDelay(delay: number): void;
+export type BlobCreationOptions = {
+    type?: string;
+    compress?: boolean;
+    flush?: boolean;
+    size?: number;
+    saveBeforeCommit?: boolean;
+};
+export declare function saveBlob(blob: FileBackedBlob, deleteOnFailure?: boolean): StorageInfo;
+export declare function getFileId(blob: Blob): string;
+export declare function isSaving(blob: Blob): string;
+export declare function getFilePathForBlob(blob: FileBackedBlob): string;
+export declare const databasePaths: Map<LMDBStore, string[]>;
+export declare function getRootBlobPathsForDB(store: LMDBStore): string[];
+export declare function deleteRootBlobPathsForDB(store: LMDBStore): Promise<any[]>;
+/**
+ * Encode blobs with file paths, so that they can be saved to the database
+ * @param callback
+ * @param encodingId
+ * @param objectToClear
+ */
+export declare function encodeBlobsWithFilePath<T>(callback: () => T, encodingId: number, store: LMDBStore): T;
+/**
+ * Encode blobs as buffers, so they can be transferred remotely
+ * @param callback
+ * @param encodingId
+ * @param objectToClear
+ */
+export declare function encodeBlobsAsBuffers<T>(callback: () => T): Promise<T>;
+/**
+ * Decode blobs, creating local storage to hold the blogs and returning a promise that resolves when all the blobs are written to disk
+ * @param callback
+ */
+export declare function decodeBlobsWithWrites(callback: () => void, store?: LMDBStore, blobCallback?: (blob: Blob) => void): Promise<void> | Promise<void[]>;
+/**
+ * Decode with a callback for when blobs are encountered, allowing for detecting of blobs
+ * @param callback
+ */
+export declare function decodeWithBlobCallback(callback: () => void, blobCallback: (blob: Blob) => void, rootStore?: LMDBStore): void;
+/**
+ * Decode with a callback for when blobs are encountered, allowing for detecting of blobs
+ * @param callback
+ */
+export declare function decodeFromDatabase<T>(callback: () => T, rootStore: LMDBStore): T;
+/**
+ * Delete blobs in an object, recursively searching for blobs
+ * @param object
+ */
+export declare function deleteBlobsInObject(object: any): void;
+/**
+ * Find all blobs in an object, recursively searching for Blob instances
+ * @param object
+ * @param callback
+ */
+export declare function findBlobsInObject(object: any, callback: (blob: Blob) => void): void;
+/**
+ * Do a shallow/fast search for blobs on the record and start saving them if they are supposed to be saved before a commit
+ * @param record
+ * @param store
+ */
+export declare function startPreCommitBlobsForRecord(record: any, store: LMDBStore | RocksDatabase, saveInRecord?: boolean): () => Promise<void[]>;
+/**
+ * Scans for blobs on the file system and then checks to verify they are referenced
+ * from the database, and if not, deletes them
+ * @param database
+ */
+export declare function cleanupOrphans(database: any, databaseName?: string): Promise<number>;
+export {};