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