@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
383 lines • 12.7 kB
TypeScript
import { type StoreFileId, type CollectionContext, type CollectionItem, type CollectionItemMeta, type StoreFileMeta } from '@alwatr/nitrobase-types';
/**
* Represents a reference to a collection of the AlwatrNitrobase.
* Provides methods to interact with the collection, such as retrieving, creating, updating, and deleting items.
*
* @template TItem - The data type of the collection items.
*/
export declare class CollectionReference<TItem extends JsonObject = JsonObject> {
private context__;
private updatedCallback__;
/**
* Alwatr nitrobase engine version string.
*/
static readonly version: string;
/**
* Alwatr nitrobase engine file format version number.
*/
static readonly fileFormatVersion = 3;
/**
* Creates new CollectionReference instance from stat.
*
* @param stat the collection stat.
* @param initialData the collection data.
* @param updatedCallback the callback to invoke when the collection changed.
* @template TItem The collection item data type.
* @returns A new collection reference class.
*/
static newRefFromData<TItem extends JsonObject>(stat: StoreFileId, updatedCallback: (from: CollectionReference<TItem>) => void, debugDomain?: string): CollectionReference<TItem>;
/**
* Creates new CollectionReference instance from CollectionContext.
*
* @param context the collection context.
* @param updatedCallback the callback to invoke when the collection changed.
* @template TItem The collection item data type.
* @returns A new collection reference class.
*/
static newRefFromContext<TItem extends JsonObject>(context: CollectionContext<TItem>, updatedCallback: (from: CollectionReference<TItem>) => void, debugDomain?: string): CollectionReference<TItem>;
/**
* Validates the collection context and try to migrate it to the latest version.
*/
private validateContext__;
/**
* Migrate the collection context to the latest.
*/
private migrateContext__;
/**
* The ID of the collection nitrobase file.
*/
readonly id: string;
/**
* The location path of the collection nitrobase file.
*/
readonly path: string;
/**
* Indicates whether the collection has unsaved changes.
*/
hasUnprocessedChanges_: boolean;
/**
* Logger instance for this collection.
*/
private logger__;
/**
* Collection reference have methods to get, set, update and save the Alwatr Nitrobase Collection.
* This class is dummy in saving and loading the collection from file.
* It's the responsibility of the Alwatr Nitrobase to save and load the collection.
*
* @param context__ Collection's context filled from the Alwatr Nitrobase (parent).
* @param updatedCallback__ updated callback to invoke when the collection is updated from the Alwatr Nitrobase (parent).
* @template TItem - Items data type.
* @example
* ```typescript
* const collectionRef = alwatrStore.col('blog/posts');
* ```
*/
constructor(context__: CollectionContext<TItem>, updatedCallback__: (from: CollectionReference<TItem>) => void, 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 collection data is frozen and cannot be saved.
*/
private _freeze;
/**
* Gets the freeze status of the collection data.
*
* @returns `true` if the collection data is frozen, `false` otherwise.
*
* @example
* ```typescript
* const isFrozen = collectionRef.freeze;
* console.log(isFrozen); // Output: false
* ```
*/
get freeze(): boolean;
/**
* Sets the freeze status of the collection data.
*
* @param value - The freeze status to set.
*
* @example
* ```typescript
* collectionRef.freeze = true;
* console.log(collectionRef.freeze); // Output: true
* ```
*/
set freeze(value: boolean);
/**
* Checks if an item exists in the collection.
*
* @param itemId - The ID of the item.
* @returns `true` if the item with the given ID exists in the collection, `false` otherwise.
*
* @example
* ```typescript
* const doesExist = collectionRef.hasItem('item1');
*
* if (doesExist) {
* collectionRef.addItem('item1', { key: 'value' });
* }
* ```
*/
hasItem(itemId: string | number): boolean;
/**
* Retrieves the metadata of the nitrobase file.
*
* @returns The metadata of the nitrobase file.
*
* @example
* ```typescript
* const metadata = collectionRef.getStoreMeta();
* ```
*/
getStoreMeta(): Readonly<StoreFileMeta>;
/**
* Retrieves an item from the collection. If the item does not exist, an error is thrown.
*
* @param itemId - The ID of the item.
* @returns The item with the given ID.
*/
private item__;
/**
* Retrieves an item's metadata from the collection. If the item does not exist, an error is thrown.
*
* @param itemId - The ID of the item.
* @returns The metadata of the item with the given ID.
* @example
* ```typescript
* const itemMeta = collectionRef.getItemMeta('item1');
* ```
*/
getItemMeta(itemId: string | number): Readonly<CollectionItemMeta>;
/**
* Retrieves an item's data from the collection. If the item does not exist, an error is thrown.
*
* @param itemId - The ID of the item.
* @returns The data of the item with the given ID.
*
* @example
* ```typescript
* const itemData = collectionRef.getItemData('item1');
* ```
*/
getItemData(itemId: string | number): TItem;
/**
* Direct access to an item.
* If the item does not exist, `undefined` is returned.
* **USE WITH CAUTION!**
*
* @param itemId - The ID of the item.
* @returns The data of the item with the given ID or `undefined` if the item does not exist.
*
* @example
* ```typescript
* collectionRef.getItemContext_('item1')?.data.name = 'test2';
* ```
*/
getItemContext_(itemId: string | number): CollectionItem<TItem> | undefined;
/**
* Add a new item to the collection.
* If an item with the given ID already exists, an error is thrown.
*
* @param itemId - The ID of the item to create.
* @param data - The initial data of the item.
*
* @example
* ```typescript
* collectionRef.addItem('item1', { key: 'value' });
* ```
*/
addItem(itemId: string | number, data: TItem): void;
/**
* Appends the given data to the collection with auto increment ID.
*
* @param data - The data to append.
* @returns The ID of the appended item.
*
* @example
* ```typescript
* const newId = collectionRef.appendItem({ key: 'value' });
* ```
*/
appendItem(data: TItem): string | number;
/**
* Removes an item from the collection.
*
* @param itemId - The ID of the item to delete.
*
* @example
* ```typescript
* collectionRef.removeItem('item1');
* collectionRef.hasItem('item1'); // Output: false
* ```
*/
removeItem(itemId: string | number): void;
/**
* Sets an item's data in the collection. Replaces the item's data with the given data.
*
* @param itemId - The ID of the item to set.
* @param data - The data to set for the item.
*
* @example
* ```typescript
* collectionRef.replaceItemData('item1', { a: 1, b: 2, c: 3 });
* ```
*/
replaceItemData(itemId: string | number, data: TItem): void;
/**
* Updates an item in the collection by merging a partial update into the item's data.
*
* @param itemId - The ID of the item to update.
* @param data - The part of data to merge into the item's data.
*
* @example
* ```typescript
* collectionRef.mergeItemData(itemId, partialUpdate);
* ```
*/
mergeItemData(itemId: string | number, data: Partial<TItem>): void;
/**
* Requests the Alwatr Nitrobase to save the collection.
* Saving may take some time in Alwatr Nitrobase due to the use of throttling.
*
* @example
* ```typescript
* collectionRef.save();
* ```
*/
save(itemId: string | number | null): void;
/**
* Requests the Alwatr Nitrobase to save the collection immediately.
*
* @example
* ```typescript
* collectionRef.saveImmediate();
* ```
*/
saveImmediate(itemId: string | number | null): void;
/**
* Retrieves the IDs of all items in the collection in array.
* Impact performance if the collection is large, use `ids()` instead.
*
* @returns Array of IDs of all items in the collection.
* @example
* ```typescript
* const ids = collectionRef.keys();
* ```
*/
keys(): string[];
/**
* Retrieves all items in the collection in array.
* Impact performance if the collection is large, use `items()` instead.
*
* @returns Array of all items in the collection.
* @example
* ```typescript
* const items = collectionRef.values();
* console.log('meta: %o', items[0].meta);
* console.log('data: %o', items[0].data);
* ```
*/
values(): CollectionItem<TItem>[];
/**
* Retrieves the IDs of all items in the collection.
* Use this method instead of `keys()` if the collection is large.
* This method is a generator and can be used in `for...of` loops.
* @returns Generator of IDs of all items in the collection.
* @example
* ```typescript
* for (const id of collectionRef.ids()) {
* const doc = collectionRef.get(id);
* }
* ```
*/
ids(): Generator<string, void, void>;
/**
* Retrieves all items in the collection.
* Use this method instead of `values()` if the collection is large.
* This method is a generator and can be used in `for...of` loops.
* @returns Generator of all items in the collection.
* @example
* ```typescript
* for (const item of collectionRef.items()) {
* console.log(item.data);
* }
*/
items(): Generator<CollectionItem<TItem>, void, void>;
/**
* Retrieves the full context of the collection.
*
* @returns The full context of the collection.
*
* @example
* ```typescript
* const context = collectionRef.getFullContext_();
* ```
*/
getFullContext_(): Readonly<CollectionContext<TItem>>;
updateDelayed_: boolean;
/**
* Update the document metadata and invoke the updated callback.
* This method is throttled to prevent multiple updates in a short time.
*
* @param itemId - The ID of the item to update.
*/
private updated__;
/**
* Refresh/recalculate the collection's metadata timestamp and revision.
*
* @param itemId - The ID of the item to update.
*/
protected refreshMeta_(itemId: string | number | null): void;
/**
* Generates the next auto increment ID.
*
* @returns The next auto increment ID.
* @example
* ```typescript
* const nextId = this.nextAutoIncrementId_();
* ```
*/
private nextAutoIncrementId__;
/**
* Retrieves the collection's extra metadata.
*
* @returns The collection's extra metadata.
*
* @example
* ```typescript
* const colExtraMeta = collectionRef.getExtraMeta();
* ```
*/
getExtraMeta<T extends JsonObject>(): T;
/**
* Sets/replace the collection's extra metadata.
*
* @param extraMeta The new collection's extra metadata.
*
* @example
* ```typescript
* collectionRef.replaceExtraMeta({ a: 1, b: 2, c: 3 });
* ```
*/
replaceExtraMeta<T extends JsonObject>(extraMeta: T): void;
/**
* Updates collection's extra metadata by merging a partial update.
*
* @param extraMeta The part of extra metadata to merge into the collection's extra metadata.
*
* @example
* ```typescript
* collectionRef.mergeExtraMeta({ c: 4 });
* ```
*/
mergeExtraMeta<T extends JsonObject>(extraMeta: Partial<T>): void;
}
//# sourceMappingURL=collection-reference.d.ts.map