@aurios/jason/dist/data/collection.d.ts

A simple, lightweight, and embeddable JSON document database built on Bun.

import type { CollectionOptions, CollectionParam, Document } from "../types/index.js";
export default class Collection<Collections, K extends keyof Collections> {
    #private;
    /**
     * Constructs a new Collection.
     *
     * @param basePath - The base path where the collection data will be stored.
     * @param name - The name of the collection.
     * @param options - Options for the collection.
     * @param options.schema - The schema validation function for the collection.
     * @param options.concurrencyStrategy - The concurrency strategy of the collection.
     * @param options.cacheTimeout - The cache timeout in milliseconds.
     */
    constructor(basePath: string, name: K, options?: CollectionOptions<Document<Collections, K>>);
    /**
     * Creates a new document in the collection.
     *
     * Ensures that the collection exists. Generates a random id for the document and validates it against the schema.
     * If the document fails schema validation, it throws an error.
     *
     * If the concurrency strategy is "versioning", it adds versioning metadata to the document.
     *
     * @param data - The document data to be created.
     * @returns A promise that resolves to the created document.
     * @throws An error if the document failed schema validation or if the collection did not exist.
     */
    create(data: CollectionParam<Collections, K>): Promise<Document<Collections, K>>;
    /**
     * Reads a document from the collection.
     *
     * If the document was modified recently (less than 1 minute ago), it returns
     * the cached version. Otherwise, it reads from disk and updates the cache.
     *
     * If the document does not exist, it returns null.
     *
     * @param id - The id of the document to read.
     * @returns The document, or null if it does not exist.
     */
    read(id: string): Promise<Document<Collections, K> | null>;
    /**
     * Reads all documents from the collection.
     *
     * Returns an array of documents.
     *
     * @param options - Optional parameters to control the result.
     * @param options.skip - The number of documents to skip.
     * @param options.limit - The maximum number of documents to return.
     * @returns A promise that resolves to an array of documents.
     */
    readAll(options?: {
        skip?: number;
        limit?: number;
    }): Promise<Document<Collections, K>[]>;
    /**
     * Checks if a document with the specified id exists in the collection.
     *
     * @param id - The id of the document to check.
     * @returns A promise that resolves to true if the document exists, false otherwise.
     */
    has(id: string): Promise<boolean>;
    /**
     * Updates a document with the specified id using the provided data.
     *
     * If the concurrency strategy is "optimistic", it attempts to acquire a lock
     * before proceeding with the update. If the lock cannot be acquired, an error
     * is thrown. After updating, the lock is released.
     *
     * If the concurrency strategy is not "optimistic", the update is performed
     * without locking.
     *
     * @param id - The id of the document to be updated.
     * @param data - The partial data to update the document with.
     * @returns A promise that resolves to the updated document or null if the
     * document does not exist.
     * @throws An error if the lock cannot be acquired or if the update operation
     * encounters an error.
     */
    update(id: string, data: Partial<CollectionParam<Collections, K>>): Promise<Document<Collections, K> | null>;
    /**
     * Deletes a document with the specified id from the collection.
     *
     * @param id - The id of the document to delete.
     * @returns A promise that resolves to true if the document is successfully
     * deleted.
     * @throws DocumentNotFoundError if the document does not exist.
     * @throws DeleteOperationError if an error is encountered during the deletion
     * operation.
     */
    delete(id: string): Promise<boolean>;
    /**
     * Queries documents in the collection based on the provided filter function.
     *
     * Retrieves documents from the collection, applies the filter function to each
     * document, and returns an array of documents that match the filter criteria.
     * Supports concurrent processing and batch processing for efficiency.
     *
     * @param filter - A function that takes a document and returns a boolean
     * indicating whether the document matches the filter criteria.
     * @param options - Optional parameters to control the query execution.
     * @param options.batchSize - The number of documents to process in each batch.
     * @param options.skip - The number of documents to skip from the start of the
     * result.
     * @param options.limit - The maximum number of documents to return.
     * @returns A promise that resolves to an array of documents matching the filter
     * criteria.
     */
    query(filter: (doc: Document<Collections, K>) => boolean, options?: {
        batchSize?: number;
        skip?: number;
        limit?: number;
    }): Promise<Document<Collections, K>[]>;
}