@alwatr/nitrobase-engine 8.0.0 → 9.1.1

package/{dist/main.mjs → src/alwatr-nitrobase.ts}

@@ -1,25 +1,85 @@
-/* @alwatr/nitrobase-engine v8.0.0 */
-
-// src/alwatr-nitrobase.ts
-import { delay } from "@alwatr/nanolib";
-import { exitHook } from "@alwatr/nanolib/exit-hook";
-import { existsSync, readJson, resolve, unlink, writeJson } from "@alwatr/nanolib/node-fs";
-import { getStoreId, getStorePath } from "@alwatr/nitrobase-helper";
-import { CollectionReference, DocumentReference } from "@alwatr/nitrobase-reference";
+import {delay} from '@alwatr/delay';
+import {exitHook} from '@alwatr/exit-hook';
+import {getStoreId, getStorePath} from '@alwatr/nitrobase-helper';
+import {CollectionReference, DocumentReference} from '@alwatr/nitrobase-reference';
 import {
   StoreFileType,
   StoreFileExtension,
-  Region
-} from "@alwatr/nitrobase-types";
+  Region,
+  type StoreFileStat,
+  type StoreFileContext,
+  type CollectionContext,
+  type DocumentContext,
+  type StoreFileId,
+  type CollectionItem,
+} from '@alwatr/nitrobase-types';
+import {existsSync, readJson, resolve, unlink, writeJson} from '@alwatr/node-fs';
 
-// src/logger.ts
-import { createLogger, packageTracer } from "@alwatr/nanolib";
-__dev_mode__: packageTracer.add("@alwatr/nitrobase-engine", "8.0.0");
-var logger = /* @__PURE__ */ createLogger("@alwatr/nitrobase-engine");
+import {logger} from './logger.js';
+
+
+__dev_mode__: logger.logFileModule?.('alwatr-nitrobase');
+
+/**
+ * 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 class AlwatrNitrobase {
+  /**
+   * The Alwatr Nitrobase version string.
+   *
+   * Use for nitrobase file format version for check compatibility.
+   */
+  public static readonly version = __package_version__;
+
+  /**
+   * The root nitrobase file stat.
+   */
+  private static readonly rootDbStat__: StoreFileStat = {
+    name: '.nitrobase',
+    region: Region.Secret,
+    type: StoreFileType.Collection,
+    extension: StoreFileExtension.Json,
+    changeDebounce: 40,
+  };
+
+  /**
+   * `collectionReference` of all `storeFileStat`s.
+   * This is the root nitrobase collection.
+   */
+  private rootDb__;
+
+  /**
+   * Keep all loaded nitrobase file context loaded in memory.
+   */
+  private cacheReferences__: DictionaryReq<DocumentReference | CollectionReference> = {};
 
-// src/alwatr-nitrobase.ts
-__dev_mode__: logger.logFileModule?.("alwatr-nitrobase");
-var _AlwatrNitrobase = class _AlwatrNitrobase {
   /**
    * Constructs an AlwatrNitrobase instance with the provided configuration.
    *
@@ -32,19 +92,15 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * });
    * ```
    */
-  constructor(config) {
-    this.config = config;
-    /**
-     * Keep all loaded nitrobase file context loaded in memory.
-     */
-    this.cacheReferences__ = {};
-    var _a;
+  constructor(public readonly config: AlwatrNitrobaseConfig) {
     this.storeChanged_ = this.storeChanged_.bind(this);
-    logger.logMethodArgs?.("new", config);
-    (_a = this.config).defaultChangeDebounce ?? (_a.defaultChangeDebounce = 40);
+
+    logger.logMethodArgs?.('new', config);
+    this.config.defaultChangeDebounce ??= 40;
     this.rootDb__ = this.loadRootDb__();
     exitHook(this.exitHook__.bind(this));
   }
+
   /**
    * Checks if a nitrobase file with the given ID exists.
    *
@@ -57,12 +113,13 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * }
    * ```
    */
-  hasStore(storeId) {
+  public hasStore(storeId: StoreFileId): boolean {
     const id_ = getStoreId(storeId);
     const exists = this.rootDb__.hasItem(id_);
-    logger.logMethodFull?.("hasStore", id_, exists);
+    logger.logMethodFull?.('hasStore', id_, exists);
     return exists;
   }
+
   /**
    * Defines a new document with the given configuration and initial data.
    * If a document with the same ID already exists, an error is thrown.
@@ -85,16 +142,17 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * );
    * ```
    */
-  newDocument(stat, data) {
-    logger.logMethodArgs?.("newDocument", stat);
-    return this.newStoreFile_(
+  public newDocument<TDoc extends JsonObject = JsonObject>(stat: Omit<StoreFileStat, 'type'>, data: TDoc): void {
+    logger.logMethodArgs?.('newDocument', stat);
+    return this.newStoreFile__(
       {
         ...stat,
-        type: StoreFileType.Document
+        type: StoreFileType.Document,
       },
-      data
+      data,
     );
   }
+
   /**
    * Defines a new collection with the given configuration and initial data.
    * If a collection with the same ID already exists, an error is thrown.
@@ -111,45 +169,53 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * );
    * ```
    */
-  newCollection(stat) {
-    logger.logMethodArgs?.("newCollection", stat);
-    return this.newStoreFile_(
-      {
-        ...stat,
-        type: StoreFileType.Collection
-      }
-    );
+  public newCollection(stat: Omit<StoreFileStat, 'type'>): void {
+    logger.logMethodArgs?.('newCollection', stat);
+    return this.newStoreFile__({
+      ...stat,
+      type: StoreFileType.Collection,
+    });
   }
+
   /**
    * Defines a AlwatrNitrobaseFile with the given configuration and initial data.
    *
    * @param stat nitrobase file stat
    * @param data initial data for the document
    */
-  newStoreFile_(stat, data) {
-    logger.logMethodArgs?.("newStoreFile_", stat);
-    stat.changeDebounce ?? (stat.changeDebounce = this.config.defaultChangeDebounce);
-    let fileStoreRef;
+  private newStoreFile__(stat: StoreFileStat, data?: DictionaryOpt): void {
+    logger.logMethodArgs?.('newStoreFile__', stat);
+
+    (stat.changeDebounce as number | undefined) ??= this.config.defaultChangeDebounce;
+
+    let fileStoreRef: DocumentReference | CollectionReference;
     if (stat.type === StoreFileType.Document) {
-      if (data === void 0) {
-        logger.accident("newStoreFile_", "document_data_required", stat);
-        throw new Error("document_data_required", { cause: stat });
+      if (data === undefined) {
+        logger.accident('newStoreFile__', 'document_data_required', stat);
+        throw new Error('document_data_required', {cause: stat});
       }
       fileStoreRef = DocumentReference.newRefFromData(stat, data, this.storeChanged_);
-    } else if (stat.type === StoreFileType.Collection) {
+    }
+    else if (stat.type === StoreFileType.Collection) {
       fileStoreRef = CollectionReference.newRefFromData(stat, this.storeChanged_);
-    } else {
-      logger.accident("newStoreFile_", "store_file_type_not_supported", stat);
-      throw new Error("store_file_type_not_supported", { cause: stat });
     }
+    else {
+      logger.accident('newStoreFile__', 'store_file_type_not_supported', stat);
+      throw new Error('store_file_type_not_supported', {cause: stat});
+    }
+
     if (this.rootDb__.hasItem(fileStoreRef.id)) {
-      logger.accident("newStoreFile_", "store_file_already_defined", stat);
-      throw new Error("store_file_already_defined", { cause: stat });
+      logger.accident('newStoreFile__', 'store_file_already_defined', stat);
+      throw new Error('store_file_already_defined', {cause: stat});
     }
+
     this.rootDb__.addItem(fileStoreRef.id, stat);
     this.cacheReferences__[fileStoreRef.id] = fileStoreRef;
+
+    // fileStoreRef.save();
     this.storeChanged_(fileStoreRef);
   }
+
   /**
    * 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.
@@ -167,31 +233,37 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * userProfile.update({name: 'ali'});
    * ```
    */
-  async openDocument(documentId) {
+  public async openDocument<TDoc extends JsonObject>(documentId: StoreFileId): Promise<DocumentReference<TDoc>> {
     const id = getStoreId(documentId);
-    logger.logMethodArgs?.("openDocument", id);
+    logger.logMethodArgs?.('openDocument', id);
+
     if (Object.hasOwn(this.cacheReferences__, id)) {
       const ref = this.cacheReferences__[id];
       if (!(ref instanceof DocumentReference)) {
-        logger.accident("openDocument", "document_wrong_type", id);
-        throw new Error("document_wrong_type", { cause: id });
+        logger.accident('openDocument', 'document_wrong_type', id);
+        throw new Error('document_wrong_type', {cause: id});
       }
-      return this.cacheReferences__[id];
+      return this.cacheReferences__[id] as unknown as DocumentReference<TDoc>;
     }
+
     if (!this.rootDb__.hasItem(id)) {
-      logger.accident("openDocument", "document_not_found", id);
-      throw new Error("document_not_found", { cause: id });
+      logger.accident('openDocument', 'document_not_found', id);
+      throw new Error('document_not_found', {cause: id});
     }
+
     const storeStat = this.rootDb__.getItemData(id);
+
     if (storeStat.type != StoreFileType.Document) {
-      logger.accident("openDocument", "document_wrong_type", id);
-      throw new Error("document_wrong_type", { cause: id });
+      logger.accident('openDocument', 'document_wrong_type', id);
+      throw new Error('document_wrong_type', {cause: id});
     }
-    const context = await this.readContext__(storeStat);
+
+    const context = await this.readContext__<DocumentContext<TDoc>>(storeStat);
     const docRef = DocumentReference.newRefFromContext(context, this.storeChanged_);
-    this.cacheReferences__[id] = docRef;
+    this.cacheReferences__[id] = docRef as unknown as DocumentReference;
     return docRef;
   }
+
   /**
    * 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.
@@ -209,31 +281,39 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * orders.append({name: 'order 1'});
    * ```
    */
-  async openCollection(collectionId) {
+  public async openCollection<TItem extends JsonObject>(collectionId: StoreFileId): Promise<CollectionReference<TItem>> {
     const id = getStoreId(collectionId);
-    logger.logMethodArgs?.("openCollection", id);
+    logger.logMethodArgs?.('openCollection', id);
+
+    // try to get from cache
     if (Object.hasOwn(this.cacheReferences__, id)) {
       const ref = this.cacheReferences__[id];
       if (!(ref instanceof CollectionReference)) {
-        logger.accident("openCollection", "collection_wrong_type", id);
-        throw new Error("collection_wrong_type", { cause: id });
+        logger.accident('openCollection', 'collection_wrong_type', id);
+        throw new Error('collection_wrong_type', {cause: id});
       }
-      return this.cacheReferences__[id];
+      return this.cacheReferences__[id] as unknown as CollectionReference<TItem>;
     }
+
+    // load and create new collection reference
     if (!this.rootDb__.hasItem(id)) {
-      logger.accident("openCollection", "collection_not_found", id);
-      throw new Error("collection_not_found", { cause: id });
+      logger.accident('openCollection', 'collection_not_found', id);
+      throw new Error('collection_not_found', {cause: id});
     }
+
     const storeStat = this.rootDb__.getItemData(id);
+
     if (storeStat.type != StoreFileType.Collection) {
-      logger.accident("openCollection", "collection_wrong_type", id);
-      throw new Error("collection_not_found", { cause: id });
+      logger.accident('openCollection', 'collection_wrong_type', id);
+      throw new Error('collection_not_found', {cause: id});
     }
-    const context = await this.readContext__(storeStat);
+
+    const context = await this.readContext__<CollectionContext<TItem>>(storeStat);
     const colRef = CollectionReference.newRefFromContext(context, this.storeChanged_);
-    this.cacheReferences__[id] = colRef;
+    this.cacheReferences__[id] = colRef as unknown as CollectionReference;
     return colRef;
   }
+
   /**
    * Unloads the nitrobase file with the given id from memory.
    *
@@ -244,17 +324,18 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * alwatrStore.hasStore({name: 'user-list', region: Region.Secret}); // true
    * ```
    */
-  unloadStore(storeId) {
+  public unloadStore(storeId: StoreFileId): void {
     const id_ = getStoreId(storeId);
-    logger.logMethodArgs?.("unloadStore", id_);
+    logger.logMethodArgs?.('unloadStore', id_);
     const ref = this.cacheReferences__[id_];
-    if (ref === void 0) return;
+    if (ref === undefined) return;
     if (ref.hasUnprocessedChanges_ === true) {
       ref.updateDelayed_ = false;
       this.storeChanged_(ref);
     }
     delete this.cacheReferences__[id_];
   }
+
   /**
    * Remove document or collection from nitrobase and delete the file from disk.
    * If the file is not found, an error is thrown.
@@ -269,29 +350,32 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * alwatrStore.hasStore({name: 'user-list', region: Region.Secret}); // false
    * ```
    */
-  async removeStore(storeId) {
+  public async removeStore(storeId: StoreFileId): Promise<void> {
     const id_ = getStoreId(storeId);
-    logger.logMethodArgs?.("removeStore", id_);
+    logger.logMethodArgs?.('removeStore', id_);
     if (!this.rootDb__.hasItem(id_)) {
-      logger.accident("removeStore", "document_not_found", id_);
-      throw new Error("document_not_found", { cause: id_ });
+      logger.accident('removeStore', 'document_not_found', id_);
+      throw new Error('document_not_found', {cause: id_});
     }
     const ref = this.cacheReferences__[id_];
-    if (ref !== void 0) {
+    if (ref !== undefined) {
+      // direct unload to prevent save
       ref.freeze = true;
       ref.updateDelayed_ = false;
       ref.hasUnprocessedChanges_ = false;
-      delete this.cacheReferences__[id_];
+      delete this.cacheReferences__[id_]; // unload
     }
     const path = getStorePath(this.rootDb__.getItemData(id_));
     this.rootDb__.removeItem(id_);
     await delay.by(0);
     try {
       await unlink(resolve(this.config.rootPath, path));
-    } catch (error) {
-      logger.error("removeStore", "remove_file_failed", error, { id: storeId, path });
+    }
+    catch (error) {
+      logger.error('removeStore', 'remove_file_failed', error, {id: storeId, path});
     }
   }
+
   /**
    * Saves all changes in the nitrobase.
    *
@@ -301,8 +385,8 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * await alwatrStore.saveAll();
    * ```
    */
-  async saveAll() {
-    logger.logMethod?.("saveAll");
+  public async saveAll(): Promise<void> {
+    logger.logMethod?.('saveAll');
     for (const ref of Object.values(this.cacheReferences__)) {
       if (ref.hasUnprocessedChanges_ === true && ref.freeze !== true) {
         ref.updateDelayed_ = false;
@@ -310,20 +394,22 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
       }
     }
   }
+
   /**
    * 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.
    */
-  async readContext__(path) {
-    if (typeof path !== "string") path = getStorePath(path);
-    logger.logMethodArgs?.("readContext__", path);
+  private async readContext__<T extends StoreFileContext>(path: string | StoreFileStat): Promise<T> {
+    if (typeof path !== 'string') path = getStorePath(path);
+    logger.logMethodArgs?.('readContext__', path);
     logger.time?.(`readContext__time(${path})`);
-    const context = await readJson(resolve(this.config.rootPath, path));
+    const context = (await readJson(resolve(this.config.rootPath, path))) as T;
     logger.timeEnd?.(`readContext__time(${path})`);
     return context;
   }
+
   /**
    * Writes the context to the specified path.
    *
@@ -333,59 +419,67 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    * @param sync Indicates whether the write operation should be synchronous.
    * @returns A promise that resolves when the write operation is complete.
    */
-  writeContext__(path, context) {
-    if (typeof path !== "string") path = getStorePath(path);
-    logger.logMethodArgs?.("writeContext__", path);
+  private writeContext__<T extends StoreFileContext>(path: string | StoreFileStat, context: T): Promise<void> {
+    if (typeof path !== 'string') path = getStorePath(path);
+    logger.logMethodArgs?.('writeContext__', path);
     return writeJson(resolve(this.config.rootPath, path), context);
   }
+
   /**
    * Write nitrobase file context.
    *
    * @param from nitrobase file reference
    * @returns A promise that resolves when the write operation is complete.
    */
-  async storeChanged_(from) {
-    logger.logMethodArgs?.("storeChanged__", from.id);
+  protected async storeChanged_<T extends JsonObject>(from: DocumentReference<T> | CollectionReference<T>): Promise<void> {
+    logger.logMethodArgs?.('storeChanged__', from.id);
     const rev = from.getStoreMeta().rev;
     try {
       await this.writeContext__(from.path, from.getFullContext_());
       if (rev === from.getStoreMeta().rev) {
+        // Context not changed during saving
         from.hasUnprocessedChanges_ = false;
       }
-    } catch (error) {
-      logger.error("storeChanged__", "write_context_failed", { id: from.id, error });
+    }
+    catch (error) {
+      logger.error('storeChanged__', 'write_context_failed', {id: from.id, error});
     }
   }
+
   /**
    * Load storeFilesCollection or create new one.
    */
-  loadRootDb__() {
-    logger.logMethod?.("loadRootDb__");
-    const fullPath = resolve(this.config.rootPath, getStorePath(_AlwatrNitrobase.rootDbStat__));
+  private loadRootDb__(): CollectionReference<StoreFileStat> {
+    logger.logMethod?.('loadRootDb__');
+    const fullPath = resolve(this.config.rootPath, getStorePath(AlwatrNitrobase.rootDbStat__));
     if (!existsSync(fullPath)) {
       if (this.config.errorWhenNotInitialized === true) {
-        throw new Error("store_not_found", { cause: "Nitrobase not initialized" });
+        throw new Error('store_not_found', {cause: 'Nitrobase not initialized'});
       }
-      logger.banner("Initialize new alwatr-nitrobase");
-      return CollectionReference.newRefFromData(_AlwatrNitrobase.rootDbStat__, this.storeChanged_);
+
+      logger.banner('Initialize new alwatr-nitrobase');
+      return CollectionReference.newRefFromData(AlwatrNitrobase.rootDbStat__, this.storeChanged_);
     }
-    const context = readJson(fullPath, true);
-    return CollectionReference.newRefFromContext(context, this.storeChanged_, "root-db");
+    // else
+    const context = readJson<CollectionContext<StoreFileStat>>(fullPath, true);
+    return CollectionReference.newRefFromContext(context, this.storeChanged_, 'root-db');
   }
+
   /**
    * Save all nitrobase files.
    */
-  exitHook__() {
-    logger.logMethod?.("exitHook__");
+  private exitHook__(): void {
+    logger.logMethod?.('exitHook__');
     for (const ref of Object.values(this.cacheReferences__)) {
       logger.logProperty?.(`StoreFile.${ref.id}.hasUnprocessedChanges`, ref.hasUnprocessedChanges_);
       if (ref.hasUnprocessedChanges_ === true && ref.freeze !== true) {
-        logger.incident?.("exitHook__", "rescue_unsaved_context", { id: ref.id });
+        logger.incident?.('exitHook__', 'rescue_unsaved_context', {id: ref.id});
         writeJson(resolve(this.config.rootPath, ref.path), ref.getFullContext_(), true);
         ref.hasUnprocessedChanges_ = false;
       }
     }
   }
+
   /**
    * Get all nitrobase files.
    *
@@ -397,29 +491,8 @@ var _AlwatrNitrobase = class _AlwatrNitrobase {
    *   console.log(nitrobase.meta.id, nitrobase.data);
    * }
    */
-  getStoreList() {
-    logger.logMethod?.("getStoreList");
+  public getStoreList(): CollectionItem<Omit<StoreFileStat, 'schemaVer'>>[] {
+    logger.logMethod?.('getStoreList');
     return this.rootDb__.values();
   }
-};
-/**
- * The Alwatr Nitrobase version string.
- *
- * Use for nitrobase file format version for check compatibility.
- */
-_AlwatrNitrobase.version = "8.0.0";
-/**
- * The root nitrobase file stat.
- */
-_AlwatrNitrobase.rootDbStat__ = {
-  name: ".nitrobase",
-  region: Region.Secret,
-  type: StoreFileType.Collection,
-  extension: StoreFileExtension.Json,
-  changeDebounce: 40
-};
-var AlwatrNitrobase = _AlwatrNitrobase;
-export {
-  AlwatrNitrobase
-};
-//# sourceMappingURL=main.mjs.map
+}

package/src/logger.ts

@@ -0,0 +1,4 @@
+import {createLogger} from '@alwatr/logger';
+
+
+export const logger = /* #__PURE__ */ createLogger(__package_name__);

package/src/main.ts

@@ -0,0 +1 @@
+export * from './alwatr-nitrobase.js';