@alwatr/nitrobase-engine
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
241 lines • 8.43 kB
TypeScript
import { CollectionReference, DocumentReference } from '@alwatr/nitrobase-reference';
import { type StoreFileStat, type StoreFileId, type CollectionItem } from '@alwatr/nitrobase-types';
/**
* AlwatrNitrobase configuration.
*/
export interface AlwatrNitrobaseConfig {
/**
* The root path of the storage.
* This is where the AlwatrNitrobase will nitrobase its data.
*/
rootPath: string;
/**
* The save debounce timeout in milliseconds for minimal disk I/O usage.
* This is used to limit the frequency of disk writes for performance reasons.
* The recommended value is `40`.
*/
defaultChangeDebounce?: number;
/**
* If true, an error will be thrown when trying to read or write to a nitrobase file that is not initialized (new storage).
* The default value is `false` but highly recommended to set it to `true` in production to prevent data loss.
*/
errorWhenNotInitialized?: boolean;
}
/**
* AlwatrNitrobase engine.
*
* It provides methods to read, write, validate, and manage nitrobase files.
* It also provides methods to interact with `documents` and `collections` in the nitrobase.
*/
export declare class AlwatrNitrobase {
readonly config: AlwatrNitrobaseConfig;
/**
* The Alwatr Nitrobase version string.
*
* Use for nitrobase file format version for check compatibility.
*/
static readonly version: string;
/**
* The root nitrobase file stat.
*/
private static readonly rootDbStat__;
/**
* `collectionReference` of all `storeFileStat`s.
* This is the root nitrobase collection.
*/
private rootDb__;
/**
* Keep all loaded nitrobase file context loaded in memory.
*/
private cacheReferences__;
/**
* Constructs an AlwatrNitrobase instance with the provided configuration.
*
* @param config The configuration of the AlwatrNitrobase engine.
* @example
* ```typescript
* const alwatrStore = new AlwatrNitrobase({
* rootPath: './db',
* saveDebounce: 40,
* });
* ```
*/
constructor(config: AlwatrNitrobaseConfig);
/**
* Checks if a nitrobase file with the given ID exists.
*
* @param storeId - The ID of the nitrobase file to check.
* @returns `true` if the nitrobase file exists, `false` otherwise.
* @example
* ```typescript
* if (!alwatrStore.hasStore('user1/profile')) {
* alwatrStore.defineDocument(...)
* }
* ```
*/
hasStore(storeId: StoreFileId): boolean;
/**
* Defines a new document with the given configuration and initial data.
* If a document with the same ID already exists, an error is thrown.
*
* @param stat nitrobase file stat
* @param data initial data for the document
* @template TDoc document data type
* @example
* ```typescript
* await alwatrStore.newDocument<Order>(
* {
* name: 'profile',
* region: Region.PerUser,
* ownerId: 'user1',
* },
* {
* name: 'Ali',
* email: 'ali@alwatr.io',
* }
* );
* ```
*/
newDocument<TDoc extends JsonObject = JsonObject>(stat: Omit<StoreFileStat, 'type'>, data: TDoc): void;
/**
* Defines a new collection with the given configuration and initial data.
* If a collection with the same ID already exists, an error is thrown.
*
* @param stat nitrobase file stat
* @example
* ```typescript
* await alwatrStore.newCollection<Order>(
* {
* name: 'orders',
* region: Region.PerUser,
* ownerId: 'user1',
* }
* );
* ```
*/
newCollection(stat: Omit<StoreFileStat, 'type'>): void;
/**
* Defines a AlwatrNitrobaseFile with the given configuration and initial data.
*
* @param stat nitrobase file stat
* @param data initial data for the document
*/
newStoreFile_(stat: StoreFileStat, data?: DictionaryOpt): void;
/**
* Open a document with the given id and create and return a DocumentReference.
* If the document not exists or its not a document, an error is thrown.
*
* @template TDoc document data type
* @param documentId document id {@link StoreFileId}
* @returns document reference {@link DocumentReference}
* @example
* ```typescript
* const userProfile = await alwatrStore.openDocument<User>({
* name: 'user1/profile',
* region: Region.PerUser,
* ownerId: 'user1',
* });
* userProfile.update({name: 'ali'});
* ```
*/
openDocument<TDoc extends JsonObject>(documentId: StoreFileId): Promise<DocumentReference<TDoc>>;
/**
* Open a collection with the given id and create and return a CollectionReference.
* If the collection not exists or its not a collection, an error is thrown.
*
* @template TItem collection item data type
* @param collectionId collection id {@link StoreFileId}
* @returns collection reference {@link CollectionReference}
* @example
* ```typescript
* const orders = await alwatrStore.openCollection<Order>({
* name: 'orders',
* region: Region.PerUser,
* ownerId: 'user1',
* });
* orders.append({name: 'order 1'});
* ```
*/
openCollection<TItem extends JsonObject>(collectionId: StoreFileId): Promise<CollectionReference<TItem>>;
/**
* Unloads the nitrobase file with the given id from memory.
*
* @param storeId The unique identifier of the nitrobase file. {@link StoreFileId}
* @example
* ```typescript
* alwatrStore.unloadStore({name: 'user-list', region: Region.Secret});
* alwatrStore.hasStore({name: 'user-list', region: Region.Secret}); // true
* ```
*/
unloadStore(storeId: StoreFileId): void;
/**
* Remove document or collection from nitrobase and delete the file from disk.
* If the file is not found, an error is thrown.
* If the file is not unloaded, it will be unloaded first.
* You don't need to await this method to complete unless you want to make sure the file is deleted on disk.
*
* @param storeId The ID of the file to delete. {@link StoreFileId}
* @returns A Promise that resolves when the file is deleted.
* @example
* ```typescript
* alwatrStore.removeStore({name: 'user-list', region: Region.Secret});
* alwatrStore.hasStore({name: 'user-list', region: Region.Secret}); // false
* ```
*/
removeStore(storeId: StoreFileId): Promise<void>;
/**
* Saves all changes in the nitrobase.
*
* @returns A Promise that resolves when all changes are saved.
* @example
* ```typescript
* await alwatrStore.saveAll();
* ```
*/
saveAll(): Promise<void>;
/**
* Reads the context from a given path or StoreFileStat object.
*
* @param path The path or StoreFileStat object from which to read the context.
* @returns A promise that resolves to the context object.
*/
private readContext__;
/**
* Writes the context to the specified path.
*
* @template T The type of the context.
* @param path The path where the context will be written.
* @param context The context to be written.
* @param sync Indicates whether the write operation should be synchronous.
* @returns A promise that resolves when the write operation is complete.
*/
private writeContext__;
/**
* Write nitrobase file context.
*
* @param from nitrobase file reference
* @returns A promise that resolves when the write operation is complete.
*/
protected storeChanged_<T extends JsonObject>(from: DocumentReference<T> | CollectionReference<T>): Promise<void>;
/**
* Load storeFilesCollection or create new one.
*/
private loadRootDb__;
/**
* Save all nitrobase files.
*/
private exitHook__;
/**
* Get all nitrobase files.
*
* @returns all nitrobase files.
* @example
* ```typescript
* const storeList = alwatrStore.getStoreList();
* for (const nitrobase of storeList) {
* console.log(nitrobase.meta.id, nitrobase.data);
* }
*/
getStoreList(): CollectionItem<Omit<StoreFileStat, 'schemaVer'>>[];
}
//# sourceMappingURL=alwatr-nitrobase.d.ts.map