Documented 33 functions across 7 files

.komment/komment.json

@@ -0,0 +1,43 @@
+{
+  "meta": {
+    "version": "1",
+    "updated_at": "2024-07-18T13:08:15.703Z",
+    "created_at": "2024-07-10T16:34:39.374Z",
+    "pipelines": [
+      "c089e2e8-dd67-4bff-afef-c8f0f6b8a931",
+      "83f3455e-fd11-4539-9bc0-da663fa2c85d",
+      "18b02909-d08f-4b13-9964-3b4ee9ccbda8",
+      "7c8b9933-05d6-4176-b7aa-418bf1abbade",
+      "4857c9e7-9349-41a8-96c5-56be5ffb04cf",
+      "75505a3a-f1af-4ca1-9174-9b908cdee0e4",
+      "db654c98-5128-44f7-8691-252c69b9b5b7",
+      "fb518d01-fd0a-40bb-8d37-2ff5990c023b",
+      "49ec0772-f24b-4603-9a27-a31b96963bdf",
+      "e7cb8cbb-d12f-4f42-adcc-cdf3756c8071",
+      "ce9a50b9-f4ec-4487-80f0-aff229eec487",
+      "1f76280f-f42b-4585-ad9d-7178240fd285",
+      "ef450461-80fd-45dd-81f4-48c5335ad528",
+      "dbb10926-033f-4543-b4cc-bee6999543f8",
+      "521fe478-f3d3-4440-81b8-31b85cb89a46",
+      "bd56018a-a4ab-43de-aa64-a02ed61b32be",
+      "344dea1f-37c5-4706-b964-90ffeed56096",
+      "c355b024-a5e5-4eea-b745-fd2482d6e5c6",
+      "532c71df-781e-414b-98ad-8f67da7424a6",
+      "5c864a2d-0ee3-4c2e-8392-299b19565254",
+      "e47a1503-66d2-402a-a043-4b6b405c390f",
+      "8644b83e-a319-4f94-b5f8-b999ebf633bc",
+      "62f2bdd7-6e44-42b4-b522-4dce3d99e5aa"
+    ]
+  },
+  "lookup": [
+    [
+      "src/index.ts",
+      "tests/index.test.ts",
+      "types/IDocumentStore.d.ts",
+      "types/Meta.d.ts",
+      "types/StructuredFile.d.ts",
+      "types/Summary.d.ts",
+      "jest.config.js"
+    ]
+  ]
+}

src/index.ts

@@ -19,6 +19,13 @@ import { Summary } from "../types/Summary";
 const CHUNK_SIZE = 40;
 const DOCUMENT_STORE_VERSION = "1";
 
+/**
+ * @description Manages and organizes structured files, providing an interface to
+ * load, update, and retrieve files from a remote store, while also maintaining
+ * metadata and summaries for efficient storage and retrieval.
+ *
+ * @implements {IDocumentStore}
+ */
 class DocumentStore implements IDocumentStore {
   CHUNK_SIZE: number;
   namespace: string;
@@ -39,16 +46,17 @@ class DocumentStore implements IDocumentStore {
   };
 
   /**
-   * @description Sets up an instance of a DocumentStore class with various parameters
-   * such as getRemote and metadata. It also initializes
-   * internal arrays and objects to store chunk data, content, and other meta information.
+   * @description Initializes an object with several properties, including namespace,
+   * remote data fetching function, and metadata. It also sets default values for chunk
+   * size, timestamps, and lookup table. The object is initialized with default metadata
+   * and status flags.
    *
-   * @param { (...args: any[]) => Promise<Record<any, any>> } getRemote - 3rd party library or service that provides the functionality
-   * for generating high-quality documentation.
+   * @param {string} namespace - Required.
    *
-   * @param { Integration } integration - Integration object that provides information
-   * about the integration of the code documentation with other systems or services.
+   * @param {(...args: any[]) => Promise<Record<any, any>>} getRemote - Responsible for
+   * fetching data remotely.
    *
+   * @param {Record<string, any>} additionalMeta - Used to store custom metadata.
    */
   constructor(
     namespace: string,
@@ -78,19 +86,20 @@ class DocumentStore implements IDocumentStore {
   }
 
   /**
-   * @description Updates the `updated_at` field of an instance of the `Meta` class
-   * with the provided `updated_at` value.
+   * @description Updates the `updated_at` property within its `meta` object with a
+   * specified date. The method takes one argument, `updated_at`, which is expected to
+   * be an instance of Date.
    *
-   * @param { Date } updated_at - date and time when the document was last updated,
-   * which is then assigned to the `meta.updated_at` property of the document.
+   * @param {Date} updated_at - Intended to update a timestamp value.
    */
   setUpdatedAt = (updated_at: Date) => {
     this.meta.updated_at = updated_at;
   };
 
   /**
-   * @description Retrieves document summaries from a provider and updates local meta
-   * data based on the remote summary.
+   * @description Loads or updates a summary object from remote storage and merges it
+   * with local metadata. If no remote data exists, it creates a new default summary
+   * and populates the local metadata accordingly.
    */
   loadSummary = async () => {
     let summary: Summary = {
@@ -119,14 +128,16 @@ class DocumentStore implements IDocumentStore {
     this.meta.created_at = summary?.meta?.created_at || new Date();
     this.meta.updated_at = summary?.meta?.updated_at || new Date();
     Object.entries(this.metaTemplate).forEach(([key, value]) => {
+      // Updates meta values.
       this.meta[key] = summary?.meta?.[key] ?? value;
     });
     this.lookup = summary.lookup || [];
     this.status.summary = true;
   };
 
   /**
-   * Loads all files from the remote store
+   * @description Asynchronously loads document chunks into memory after verifying that
+   * the summary has been loaded, then sets the `chunks` status to true.
    */
   load = async () => {
     if (!this.status.summary) {
@@ -148,6 +159,13 @@ class DocumentStore implements IDocumentStore {
   getChunkSummaryPath = (): string =>
     `.${this.namespace}/${this.namespace}.json`;
 
+  /**
+   * @description Merges additional metadata into the existing metadata, replacing any
+   * duplicate keys with the new values. The existing metadata is updated with the
+   * merged properties from the provided `additionalMeta` object.
+   *
+   * @param {Record<string, any>} additionalMeta - Used to update metadata with new values.
+   */
   updateMetadata = (additionalMeta: Record<string, any>) => {
     this.meta = {
       ...this.meta,
@@ -162,15 +180,14 @@ class DocumentStore implements IDocumentStore {
     this.chunks[chunkIndex]?.length > 0;
 
   /**
-   * @description Loads a chunk from a provider based on its key, concats it to the
-   * content, and stores it in the chunks array if successful.
+   * @description Asynchronously loads a chunk of structured data from a remote source
+   * and updates the local store's content and chunks cache if it has not already been
+   * loaded.
    *
-   * @param { number } chunkIndex - 0-based index of a particular chunk within the
-   * overall sequence of chunks being loaded, and is used to identify the specific chunk
-   * to be loaded or loaded previously.
+   * @param {number} chunkIndex - Used to identify a specific chunk of data.
    *
-   * @returns { Promise<boolean> } a boolean value indicating whether the chunk was successfully
-   * loaded.
+   * @returns {Promise<boolean>} A boolean indicating whether the chunk was loaded
+   * successfully or not.
    */
   loadChunk = async (chunkIndex: number): Promise<boolean> => {
     if (!this.isChunkLoaded(chunkIndex)) {
@@ -189,14 +206,14 @@ class DocumentStore implements IDocumentStore {
     return true;
   };
   /**
-   * @description Checks if a file is loaded, loads it if not, and returns the file's
-   * contents if found in the specified chunk.
+   * @description Retrieves a file from a structured storage system based on its path,
+   * returning it as a promise that resolves to either a `StructuredFile` object or
+   * null if the file is not found.
    *
-   * @param { string } path - file path to be looked up in the chunk, and it is used
-   * to determine the chunk index and file index within that chunk.
+   * @param {string} path - Intended to identify the file to retrieve.
    *
-   * @returns { object } a file object containing the path, name, and other properties
-   * of the requested file.
+   * @returns {Promise<StructuredFile | null>} A promise that resolves to either a
+   * StructuredFile object or null if the file is not found.
    */
   getFile = async (path: string): Promise<StructuredFile | null> => {
     if (!this.status.summary)
@@ -239,10 +256,11 @@ class DocumentStore implements IDocumentStore {
     this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1;
 
   /**
-   * @description Updates a subtable containing paths based on a new input path, adding
-   * it to either the end or within an existing subtable if necessary.
+   * @description Adds paths to its internal lookup table. If the last subtable is full,
+   * it creates a new one; otherwise, it appends the path to the existing subtable.
+   * This maintains an efficient data structure for subsequent operations.
    *
-   * @param { string } path - path of a file to be looked up in the code's lookup table.
+   * @param {string} path - Used to add to the lookup table.
    */
   addToEndOfLookup = (path: string) => {
     // If the last lookup subtable is full, create a new one
@@ -256,14 +274,11 @@ class DocumentStore implements IDocumentStore {
     }
   };
   /**
-   * @description Manages the structure file's chunks, ensuring that each chunk contains
-   * only files of a certain size. If the last chunk is full or if the file to be added
-   * is too large for the remaining space in the previous chunk, a new chunk is created
-   * and the file is added to it. Otherwise, the file is added to the end of the previous
-   * chunk.
+   * @description Appends a file to the end of an existing chunk or creates a new chunk
+   * if the last one is full, thereby managing a collection of structured files divided
+   * into chunks of a fixed size (`this.CHUNK_SIZE`).
    *
-   * @param { StructuredFile } file - input file for which a chunk is being created or
-   * appended to an existing chunk.
+   * @param {StructuredFile} file - A file to be added.
    */
   addToEndOfChunks = (file: StructuredFile) => {
     // If the last lookup subtable is full, create a new one
@@ -277,14 +292,13 @@ class DocumentStore implements IDocumentStore {
     }
   };
   /**
-   * @description Adds a file to the end of the lookup and chunks arrays, updating the
-   * file if it already exists, and pushing it to the content array.
+   * @description Adds a file to its content and updates its lookup and chunk data
+   * structures accordingly. If the file already exists, it attempts to update it;
+   * otherwise, it appends the file to the end of the data structures.
    *
-   * @param { StructuredFile } file - file to be added to the structured file, which
-   * includes its path.
+   * @param {StructuredFile} file - Required to add files.
    *
-   * @returns { boolean } a list of file objects that have been successfully added to
-   * the content and chunks arrays.
+   * @returns {boolean} True if a file was successfully added and false otherwise.
    */
   addFile = (file: StructuredFile): boolean => {
     if (!this.status.chunks) throw Error("Must call .load before adding files");
@@ -307,14 +321,15 @@ class DocumentStore implements IDocumentStore {
     return true;
   };
   /**
-   * @description Updates a file in a chunk by checking if it exists, loading it if
-   * necessary, and storing it in the appropriate index in the chunk.
+   * @description Updates a file's contents within a chunked storage system. If the
+   * file does not exist, it adds the file; otherwise, it updates the file's index and
+   * content, ensuring that the requested chunk is loaded if necessary.
    *
-   * @param { any } file - file to be added or updated in the chunks array, and its
-   * path is checked for existence before loading the chunk if it hasn't been loaded yet.
+   * @param {StructuredFile} file - Mandatory.
    *
-   * @returns { Promise<boolean> } a reference to the updated file in the chunk, or `null` if the
-   * file does not exist.
+   * @returns {Promise<boolean>} A promise that resolves to either true or false. True
+   * indicates successful file update and false indicates an error occurred during
+   * updating the file.
    */
   updateFile = async (file: StructuredFile): Promise<boolean> => {
     if (!this.status.chunks)
@@ -344,10 +359,12 @@ class DocumentStore implements IDocumentStore {
     return true;
   };
   /**
-   * @description Generates high-quality documentation for code by returning an object
-   * containing the `meta` and `lookup` properties.
+   * @description Returns an object containing summary data, specifically meta and
+   * lookup information from the class instance's properties. This allows for concise
+   * representation of key details.
    *
-   * @returns { summary } an object containing `meta` and `lookup` properties.
+   * @returns {Summary} An object with two properties: meta and lookup. Both properties
+   * are references to existing objects, specifically this.meta and this.lookup.
    */
   outputSummary(): Summary {
     return {
@@ -356,10 +373,13 @@ class DocumentStore implements IDocumentStore {
     };
   }
   /**
-   * @description Generates a record of chunks of code based on the given content, using
-   * a specified chunk size and keying system.
+   * @description Splits a large content into smaller, fixed-size chunks and returns
+   * them as an object with chunk keys as properties and their corresponding values as
+   * contents. The chunk size is determined by the `CHUNK_SIZE` property of the class.
    *
-   * @returns { Record<string, any> } a record of chunks extracted from the given content.
+   * @returns {Record<string, any>} An object with key-value pairs where each key is a
+   * string and each value can be of any data type. The object represents a mapping
+   * between chunk keys and their corresponding content chunks.
    */
   outputChunks(): Record<string, any> {
     const outputs: Record<string, any> = {};