@alwatr/nitrobase-reference 7.2.0

package/README.md

@@ -0,0 +1,89 @@
+# Nitrobase
+
+**Extremely Fast and Compact JSON-Based In-Memory Database with Nginx Integration**
+
+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-performance accelerated Nginx server.
+
+## Key Features
+
+* **In-Memory Performance:** All data is stored in RAM, ensuring extremely fast reads and writes.
+* **JSON Simplicity:** Data is stored and managed in a straightforward JSON format.
+* **File Backup:** Automatic JSON file backup ensures data persistence.
+* **Nginx Integration:** Seamlessly serve your data over the web using accelerated Nginx.
+* **Compact Storage:** Efficient storage format minimizes disk space usage.
+
+## Installation
+
+```bash
+npm install @alwatr/nitrobase
+```
+
+## Getting Started
+
+### Create a Collection
+
+```js
+import { AlwatrNitrobase, Region } from '@alwatr/nitrobase';
+
+const alwatrStore = new AlwatrNitrobase({
+  rootPath: './db',
+  defaultChangeDebounce: 2_000, 
+});
+
+const postsCollectionId = {
+  name: 'post',
+  region: Region.PerUser,
+  ownerId: 'user_123',
+  schemaVer: 2,
+};
+
+alwatrStore.newCollection(postsCollectionId);
+
+const postsCollection = await alwatrStore.openCollection(postsCollectionId);
+
+postsCollection.addItem('post1', {
+  title: 'My First Post',
+  content: 'This is the content of my first post.'
+});
+```
+
+### Create a Document
+
+```js
+import { AlwatrNitrobase, Region } from '@alwatr/nitrobase';
+
+const alwatrStore = new AlwatrNitrobase({
+  rootPath: './db',
+  defaultChangeDebounce: 2_000, 
+});
+
+const docId = {
+  name: 'posts/my-first-post',
+  region: Region.Authenticated,
+};
+
+alwatrStore.newDocument(docId, {
+  title: 'My First Post',
+  content: 'This is the content of my first post.'
+});
+
+const myPost = await alwatrStore.openDocument(docId);
+```
+
+## Demo Code
+
+Explore the provided demo code (`collection.mjs`, `document.mjs`, `benchmark.mjs`) to see Alwatr Nitrobase in action and gain a deeper understanding of its capabilities.
+
+## Sponsors
+
+The following companies, organizations, and individuals support Nitrobase ongoing maintenance and development. Become a Sponsor to get your logo on our README and website.
+
+[![Exir Studio](https://avatars.githubusercontent.com/u/181194967?s=200&v=4)](https://exirstudio.com)
+
+## License
+
+This project is licensed under the AGPL-3.0 License.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues and pull requests.

package/dist/collection-reference.d.ts

@@ -0,0 +1,384 @@
+import { type StoreFileId, type CollectionContext, type CollectionItem, type CollectionItemMeta, type StoreFileMeta } from '@alwatr/nitrobase-types';
+import type { JsonObject } from '@alwatr/type-helper';
+/**
+ * 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, initialData: CollectionContext<TItem>['data'] | null, 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(): void;
+    /**
+     * Requests the Alwatr Nitrobase to save the collection immediately.
+     *
+     * @example
+     * ```typescript
+     * collectionRef.saveImmediate();
+     * ```
+     */
+    saveImmediate(): 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

package/dist/collection-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-reference.d.ts","sourceRoot":"","sources":["../src/collection-reference.ts"],"names":[],"mappings":"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"}

package/dist/document-reference.d.ts

@@ -0,0 +1,226 @@
+import { type StoreFileId, type DocumentContext, type StoreFileMeta } from '@alwatr/nitrobase-types';
+import type { JsonObject } from '@alwatr/type-helper';
+/**
+ * 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 initialData 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, initialData: 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