@alwatr/nitrobase-reference
Version:
Nitrobase is a blazingly fast, lightweight database built on JSON. It stores data entirely in memory for lightning-quick access, while also providing a JSON file backup for persistence. You can easily serve your data over the web using our high-performanc
225 lines • 6.96 kB
TypeScript
import { type StoreFileId, type DocumentContext, type StoreFileMeta } from '@alwatr/nitrobase-types';
/**
* Represents a reference to a document of the AlwatrNitrobase.
* Provides methods to interact with the document, such as get, set, update and save.
*/
export declare class DocumentReference<TDoc extends JsonObject = JsonObject> {
private readonly context__;
private readonly updatedCallback__;
/**
* Alwatr nitrobase engine version string.
*/
static readonly version: string;
/**
* Alwatr nitrobase engine file format version number.
*/
static readonly fileFormatVersion = 3;
/**
* Creates new DocumentReference instance from stat and initial data.
*
* @param statId the document stat.
* @param data the document data.
* @param updatedCallback the callback to invoke when the document changed.
* @template TDoc The document data type.
* @returns A new document reference class.
*/
static newRefFromData<TDoc extends JsonObject>(statId: StoreFileId, data: TDoc, updatedCallback: (from: DocumentReference<TDoc>) => unknown, debugDomain?: string): DocumentReference<TDoc>;
/**
* Creates new DocumentReference instance from DocumentContext.
*
* @param context the document context.
* @param updatedCallback the callback to invoke when the document changed.
* @template TDoc The document data type.
* @returns A new document reference class.
*/
static newRefFromContext<TDoc extends JsonObject>(context: DocumentContext<TDoc>, updatedCallback: (from: DocumentReference<TDoc>) => unknown, debugDomain?: string): DocumentReference<TDoc>;
/**
* Validates the document context and try to migrate it to the latest version.
*/
private validateContext__;
/**
* Migrate the document context to the latest.
*/
private migrateContext__;
/**
* The ID of the document nitrobase file.
*/
readonly id: string;
/**
* The location path of the document nitrobase file.
*/
readonly path: string;
/**
* Indicates whether the document has unsaved changes.
*/
hasUnprocessedChanges_: boolean;
/**
* Logger instance for this document.
*/
private logger__;
/**
* Create a new document reference.
* Document reference have methods to get, set, update and save the AlwatrNitrobase Document.
*
* @param context__ Document's context filled from the Alwatr Nitrobase (parent).
* @param updatedCallback__ updated callback to invoke when the document is updated from the Alwatr Nitrobase (parent).
* @template TDoc The document data type.
*/
constructor(context__: DocumentContext<TDoc>, updatedCallback__: (from: DocumentReference<TDoc>) => unknown, debugDomain?: string);
/**
* Get nitrobase schema version
*
* @returns nitrobase schema version
*/
get schemaVer(): number;
/**
* Set nitrobase schema version for migrate
*/
set schemaVer(ver: number);
/**
* Indicates whether the document data is frozen and cannot be saved.
*/
private _freeze;
/**
* Gets the freeze status of the document data.
*
* @returns `true` if the document data is frozen, `false` otherwise.
*
* @example
* ```typescript
* const isFrozen = documentRef.freeze;
* console.log(isFrozen); // Output: false
* ```
*/
get freeze(): boolean;
/**
* Sets the freeze status of the document data.
*
* @param value - The freeze status to set.
*
* @example
* ```typescript
* documentRef.freeze = true;
* console.log(documentRef.freeze); // Output: true
* ```
*/
set freeze(value: boolean);
/**
* Retrieves the document's data.
*
* @returns The document's data.
*
* @example
* ```typescript
* const documentData = documentRef.getData();
* ```
*/
getData(): TDoc;
/**
* Retrieves the document's metadata.
*
* @returns The document's metadata.
*
* @example
* ```typescript
* const documentMeta = documentRef.getStoreMeta();
* ```
*/
getStoreMeta(): Readonly<StoreFileMeta>;
/**
* Sets the document's data. replacing the existing data.
*
* @param data The new document data.
*
* @example
* ```typescript
* documentRef.replaceData({ a: 1, b: 2, c: 3 });
* ```
*/
replaceData(data: TDoc): void;
/**
* Updates document's data by merging a partial update into the document's data.
*
* @param data The part of data to merge into the document's data.
*
* @example
* ```typescript
* documentRef.mergeData({ c: 4 });
* ```
*/
mergeData(data: Partial<TDoc>): void;
/**
* Requests the Alwatr Nitrobase to save the document.
* Saving may take some time in Alwatr Nitrobase due to the use of throttling.
*
* @example
* ```typescript
* documentRef.save();
* ```
*/
save(): void;
/**
* Requests the Alwatr Nitrobase to save the document immediately.
*
* @example
* ```typescript
* documentRef.saveImmediate();
* ```
*/
saveImmediate(): void;
/**
* Retrieves the full context of the document.
*
* @returns The full context of the document.
*
* @example
* ```typescript
* const context = documentRef.getFullContext_();
* ```
*/
getFullContext_(): Readonly<DocumentContext<TDoc>>;
updateDelayed_: boolean;
/**
* Update the document metadata and invoke the updated callback.
* This method is throttled to prevent multiple updates in a short time.
*/
private updated__;
/**
* Refresh/recalculate the document's metadata timestamp and revision.
*/
protected refreshMetadata_(): void;
/**
* Retrieves the document's extra metadata.
*
* @returns The document's extra metadata.
*
* @example
* ```typescript
* const colExtraMeta = documentRef.getExtraMeta();
* ```
*/
getExtraMeta<T extends JsonObject>(): T;
/**
* Sets/replace the document's extra metadata.
*
* @param extraMeta The new document's extra metadata.
*
* @example
* ```typescript
* documentRef.replaceExtraMeta({ a: 1, b: 2, c: 3 });
* ```
*/
replaceExtraMeta<T extends JsonObject>(extraMeta: T): void;
/**
* Updates document's extra metadata by merging a partial update.
*
* @param extraMeta The part of extra metadata to merge into the document's extra metadata.
*
* @example
* ```typescript
* documentRef.mergeExtraMeta({ c: 4 });
* ```
*/
mergeExtraMeta<T extends JsonObject>(extraMeta: Partial<T>): void;
}
//# sourceMappingURL=document-reference.d.ts.map