diff --git a/.komment/00000.json b/.komment/00000.json index 53b74d8..aaf24f5 100644 --- a/.komment/00000.json +++ b/.komment/00000.json @@ -4,12 +4,12 @@ "path": "src/index.ts", "content": { "structured": { - "description": "A `DocumentStore` class that manages structured files, which are collections of files organized into chunks based on their size. The store allows adding and updating files, checking for file existence, and loading and retrieving chunks as needed. The class utilizes an internal lookup table to efficiently manage the chunking process and provides methods to generate summaries and extract records of code chunks from the stored content.", + "description": "A DocumentStore class that manages structured data in chunks, ensuring each chunk contains files of a certain size. It allows for efficient insertion and updating of files, providing high-level functions such as `addFile`, `updateFile`, `outputSummary`, and `outputChunks`. The class utilizes JavaScript's built-in Map, Array, and Promise features to optimize storage and retrieval operations.", "items": [ { - "id": "249335bd-68db-f3bd-8547-f91e9345106a", + "id": "c2cf8602-37f8-e3a9-8044-7ad6893a539d", "ancestors": [], - "description": "Manages structured files, allowing for efficient storage and retrieval of file metadata and contents. It enables chunk-based loading, lookup, and updating of files, facilitating large-scale data processing and querying.", + "description": "Manages a collection of structured files (e.g., code chunks) and provides methods for loading, storing, updating, and retrieving files. It maintains metadata, lookup tables, and chunked storage to efficiently manage large collections of files.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "2 by default. It represents the size of each chunk in terms of files, which is used to store structured files efficiently. The value can be changed as needed for better performance or memory management." + "description": "1024 by default. It determines how many files can be stored in a single chunk, which affects how often new chunks need to be loaded or created." }, { "name": "namespace", "type_name": "string", - "description": "Used to create a unique identifier for the documents being stored. It is used as part of the file path when storing files on the remote server." + "description": "Used to create a unique identifier for each structured file, which helps differentiate between files with the same name but different namespaces." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the structured file." + "description": "Used to store the metadata of a document." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Not used within the given code snippet. It seems to be a template for meta data structure." + "description": "Not shown in the given code snippet." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to keep track of file paths within a structured file, with each sub-array representing a chunk containing files of a certain size." + "description": "2D array where each sub-array represents a chunk of files, and each element within a sub-array is a file path hashed to be unique for that chunk." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "2D array, where each inner array represents a chunk, and each element within that array is a file object within that chunk. It stores chunks of files organized in arrays." + "description": "2D array where each inner array represents a chunk of files. The `chunks` attribute stores chunks of files loaded from a remote provider or updated through file additions/removals." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "A list of files where each file contains its path, name, and other properties. It represents the actual content stored in the document store." + "description": "Used to store the actual files (as a sequence of chunks) that are loaded from a provider. It's an array where each element represents a chunk of files, which is concatenated with the next chunk when loading from a provider." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Not used in the provided code snippet." + "description": "Used to track the status of a document." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "5ebc9c4e-f3cc-b187-1247-16532dd37b08", + "id": "86128721-b0a1-298a-0842-cf7e6d716572", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Initializes an instance with required parameters: namespace and getRemote method. It sets properties, such as CHUNK_SIZE, namespace, getRemote, meta, metaTemplate, lookup, chunks, content, and status. It validates the input and throws errors if namespace or getRemote is missing.", + "description": "Initializes an instance with required namespace and getRemote method, and optional additional meta data. It sets properties such as CHUNK_SIZE, namespace, getRemote, meta, metaTemplate, lookup, chunks, content, and status.", "params": [ { "name": "namespace", "type_name": "string*", "optional": false, - "description": "Required to be specified when constructing an instance of this class. It represents a unique identifier for the namespace of the document store.", + "description": "Required, as indicated by the throw error if it is not provided. It is used to set the namespace property of the object instance.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required. It returns a promise that resolves to an object with property values of type any.", + "description": "Required to be passed to the constructor.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record*", "optional": true, - "description": "Used to add extra metadata properties.", + "description": "Used to provide additional metadata.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore('my-namespace', async (args) => {\n // Return a promise of metadata\n return { version: 'v1' };\n}, { integrationType: 'integration-type' });\n", - "description": "\nThis example instantiates the `DocumentStore` class with namespace 'my-namespace', gets remote metadata, and additional meta data." + "code": "const documentStore = new DocumentStore(\"my-namespace\", async () => {\n // code here\n}, { myMetaKey: \"my-meta-value\" });\n", + "description": "" }, "name": null, "location": { @@ -182,27 +182,27 @@ "docLength": 12 }, { - "id": "25021be8-61af-13b6-6e44-4d0d0e5382f9", + "id": "a4d83aa3-b308-58a7-bd4e-bc8431268926", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Updates the `updated_at` property of the `meta` object with the provided `updated_at` date. This method appears to be part of the `DocumentStore` class, responsible for managing document metadata.", + "description": "Updates the `updated_at` property of the `meta` object within the `DocumentStore` class, setting it to the provided `Date` value.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date*", - "description": "Passed to set the value of `this.meta.updated_at`." + "description": "Assigned to the property `updated_at` of the object `this.meta`." } ], "returns": { - "type_name": "undefined", - "description": "A property of an object." + "type_name": "void", + "description": "Equivalent to nothing or undefined." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\n\ndocumentStore.setUpdatedAt(new Date('2022-07-20T14:30:00.000Z'));\n", + "code": "const store = new DocumentStore(getRemote, integration);\nstore.setUpdatedAt(new Date('2023-02-20T14:30:00.000Z'));\n", "description": "" }, "name": "setUpdatedAt", @@ -221,20 +221,20 @@ "docLength": 7 }, { - "id": "1cb8ca1a-6089-3c91-7344-3e3cf75a858c", + "id": "4fd7d85e-3281-68a5-8344-c181f3798353", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Loads and updates the document store's metadata, lookup data, and chunks from a remote source or initializes them with default values if no data is available.", + "description": "Loads and updates the document store's metadata, lookup data, and chunk information from a remote source or initializes with default values if no data is available.", "params": [], "returns": { - "type_name": "async", - "description": "A promise that resolves to an object of type Summary with properties meta, lookup, and chunks." + "type_name": "void", + "description": "A special type that represents the absence of any object value. It does not explicitly return a value but instead modifies some properties and variables within its scope." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, metaTemplate);\nstore.loadSummary();\n", - "description": "\nIn this simple example, we're creating a new instance of `DocumentStore` with the provided `getRemote` and `metaTemplate`, then we call the `loadSummary` method to load the summary." + "code": "const documentStore = new DocumentStore(\n async (...args: any[]) => Promise.resolve({ /* return remote summary */ }),\n { /* set integration object */ }\n);\n\ndocumentStore.loadSummary();\n", + "description": "\nNote that `loadSummary` is called directly without any specific parameters as it is designed to be a part of the class." }, "name": "loadSummary", "location": { @@ -252,12 +252,12 @@ "docLength": 4 }, { - "id": "36607812-b700-2c9e-f947-d8d9384adac1", + "id": "31565757-a8d4-918b-2b49-8e1104a73b61", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a", - "1cb8ca1a-6089-3c91-7344-3e3cf75a858c" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d", + "4fd7d85e-3281-68a5-8344-c181f3798353" ], - "description": "Assigns meta values to object properties.", + "description": "Updates meta object with values from template or summary if available.", "name": null, "location": { "start": 121, @@ -271,20 +271,20 @@ "docLength": null }, { - "id": "db3118a6-c050-de87-4844-321d0b145760", + "id": "8dc0cabf-65f7-10a6-a346-625561de1f63", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Loads chunks and summary of data for a document, checking if the summary has been loaded first. If not, it calls the `loadSummary` method. Then, it iterates over chunk indices and loads corresponding chunks using the `loadChunk` method. Finally, it sets the `chunks` property to `true`.", + "description": "Asynchronously loads summary and chunks for a document store. If no summary exists, it first loads the summary. Then, it looks up chunk indices and loads each chunk individually before setting the `chunks` status to true.", "params": [], "returns": { - "type_name": "undefined", - "description": "A promise that resolves to nothing." + "type_name": "void", + "description": "0. It does not explicitly return a value." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.load();\n", - "description": "\nIt initializes a new instance of the DocumentStore and then calls its load method." + "code": "const documentStore = new DocumentStore('namespace', myGetRemote, { version: '1.0' });\ndocumentStore.load();\n", + "description": "\nThis code creates a new instance of `DocumentStore` with namespace `'namespace'`, gets remote function `myGetRemote`, and initializes metadata object `{ version: '1.0' }`. It then calls the `load()` method on this instance." }, "name": "load", "location": { @@ -302,28 +302,28 @@ "docLength": 3 }, { - "id": "78922cc8-ce9c-fca1-4b40-19ee32bdad51", + "id": "9a5515c0-0da2-88b8-3b4f-4b794bec4405", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Updates the metadata object of a `DocumentStore` class by merging it with additional metadata provided as an argument. The resulting metadata is stored in the `meta` property of the class. This allows dynamic modification of the metadata.", + "description": "Updates the metadata of an object by merging additional metadata with the existing metadata. The new metadata replaces any duplicate keys, and the updated metadata is stored in the `meta` property of the `DocumentStore` class.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record*", - "description": "Expected to be an object with string keys and values of any type. This object contains additional metadata that needs to be updated in the current metadata." + "description": "Used to merge with existing metadata. It is expected to be an object literal or a destructured object that contains additional key-value pairs to be added or updated in the metadata." } ], "returns": { - "type_name": "unction", - "description": "An updated meta object that combines the original meta object with the additional metadata." + "type_name": "void", + "description": "Indicating that it does not return any value or data." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.updateMetadata({ description: \"This is a sample description\" });\n", - "description": "\n\nThe above code illustrates how to update metadata with additional information in a class called `DocumentStore`." + "code": "const docStore = new DocumentStore();\ndocStore.updateMetadata({\n 'new-key': 'new-value',\n 'other-new-key': 'other-new-value'\n});\n", + "description": "" }, "name": "updateMetadata", "location": { @@ -338,28 +338,28 @@ "docLength": null }, { - "id": "fd0e3f18-d519-60af-b14f-138dcf8f2f00", + "id": "c738d653-298f-9c93-8e43-462830102e72", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Asynchronously loads a chunk of data from a remote location, concatenates it to the existing content, and stores it in an array of chunks. If loading fails, it returns false; otherwise, it returns true indicating successful loading.", + "description": "Asynchronously loads a chunk of structured data from a remote storage and concatenates it with the existing content, updating the internal state of the `DocumentStore` instance. If an error occurs during loading, it returns false; otherwise, it returns true indicating successful loading.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number*", - "description": "Required when calling this asynchronous function. It represents the index of the chunk to be loaded." + "description": "An index that identifies a specific chunk." } ], "returns": { "type_name": "Promise*", - "description": "Resolved to either `true` (if the chunk load is successful) or `false` (if an error occurs during loading)." + "description": "Resolved to a boolean indicating whether the chunk was loaded successfully (true) or an error occurred (false)." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.CHUNK_SIZE = 10;\ndocumentStore.loadChunk(0);\n", - "description": "\n\nThis code creates a new instance of the `DocumentStore` class and calls the `loadChunk` method to load a chunk with index 0." + "code": "const documentStore = new DocumentStore();\n\ndocumentStore.loadChunk(1).then((result) => {\n if (!result) {\n // chunk failed to load\n } else {\n // chunk loaded successfully\n }\n});\n", + "description": "\nThis example demonstrates the basic usage of the `loadChunk` method, which asynchronously loads a specific chunk and returns a promise indicating whether the loading was successful or not." }, "name": "loadChunk", "location": { @@ -377,27 +377,27 @@ "docLength": 11 }, { - "id": "e4ad9cc2-2da0-2091-7b4e-bd0b0a6cc17e", + "id": "e180c593-620b-4b97-b945-193e3a3ef7ba", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Asynchronously retrieves a file from a collection of structured files, given its path. It checks if the summary has been loaded and ensures that the corresponding chunk is loaded or loaded if necessary. The file index within the chunk is also verified before returning the requested file.", + "description": "Asynchronously retrieves a file from the DocumentStore based on its path, ensuring that the required summary has been loaded and the corresponding chunk is available. If not, it loads the chunk before retrieving the file.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Required for the function to operate correctly, representing the path of the file for which structured data is requested." + "description": "The path to a file that needs to be retrieved from an asynchronous operation, which returns a promise resolving with either a structured file or null if the file could not be found." } ], "returns": { "type_name": "Promise*", - "description": "Either a StructuredFile object or null." + "description": "Either a `StructuredFile` object or null, indicating whether the requested file exists in the data structure." }, "usage": { "language": "typescript", - "code": "async function main() {\n const documentStore = new DocumentStore();\n await documentStore.loadSummary();\n const file1 = await documentStore.getFile('path/to/file1');\n if (file1 === null) {\n console.error(\"File not found\");\n } else {\n // process the StructuredFile\n }\n}\n", + "code": "const documentStore = new DocumentStore(\n async (...args: any[]) => Promise.resolve({}), // implement getRemote method\n { ... } // implement integration object\n);\n\ntry {\n const file1 = await documentStore.getFile('path/to/file1');\n if (!file1) {\n console.error(\"File not found\");\n }\n} catch (error) {\n console.error(error);\n}\n", "description": "" }, "name": "getFile", @@ -416,28 +416,28 @@ "docLength": 10 }, { - "id": "842fe77c-ac67-36b1-294c-fb482d5335d1", + "id": "185cecdd-cc2a-a4b9-7a41-4e0719ec3fd4", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Adds a given path to the end of the lookup table. If the current subtable is full, it creates a new one. Otherwise, it appends the path to the existing subtable. This approach allows efficient storage and retrieval of paths in the DocumentStore class.", + "description": "Adds a path to the end of the last lookup subtable in the `lookup` array if it's not full, otherwise, creates a new subtable with the path. It ensures that each subtable has a maximum size defined by the `CHUNK_SIZE` property.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Required for execution." + "description": "Passed to the function when it is called, indicating a path that needs to be added to the end of the lookup subtable." } ], "returns": { - "type_name": "unction", - "description": "Undefined since it doesn't explicitly define a return statement." + "type_name": "void", + "description": "0 if the last lookup subtable is full and a new one is created or null otherwise." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup('path/to/document');\n", - "description": "" + "code": "const store = new DocumentStore(getRemote, integration);\nstore.addToEndOfLookup(\"path/to/file.txt\");\n", + "description": "\nIt adds a path to the last lookup subtable." }, "name": "addToEndOfLookup", "location": { @@ -455,28 +455,28 @@ "docLength": 6 }, { - "id": "11bb6b19-5d8a-5cb9-1a40-3ae81cd8a9bd", + "id": "2153794b-f69f-639a-fb49-71df330b3aba", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Adds a file to the end of the existing chunk or creates a new one if the current chunk is full, ensuring that each chunk does not exceed a specific size (`CHUNK_SIZE`).", + "description": "Adds a file to the end of an existing chunk or creates a new chunk if the current one is full, based on a predefined CHUNK_SIZE.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "An input variable that represents a file with structured data. It is used to determine whether it should be added to the existing chunk or create a new one." + "description": "Expected to be passed when calling this function." } ], "returns": { - "type_name": "unction", - "description": "Called as a higher-order function. It does not explicitly return any value, but it updates the state of an object by pushing a new file into either a newly created chunk or the last existing one." + "type_name": "void", + "description": "Equivalent to no return value. It does not explicitly return a value." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\n\ndocumentStore.CHUNK_SIZE = 5;\ndocumentStore.addToEndOfChunks({ /* file object */ });\n", - "description": "\nThis code creates a new instance of `DocumentStore`, sets `CHUNK_SIZE` to 5, and then calls the `addToEndOfChunks` method with a structured file as an argument." + "code": "const documentStore = new DocumentStore();\ndocumentStore.CHUNK_SIZE = 2;\ndocumentStore.addToEndOfChunks({/* structuredFile */});\n", + "description": "" }, "name": "addToEndOfChunks", "location": { @@ -494,27 +494,27 @@ "docLength": 10 }, { - "id": "c3ddb755-2082-9fa4-fc48-35a9ee911247", + "id": "c83f0f80-4619-338e-8e4a-2d18c58185e1", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Adds a file to the `DocumentStore`. If the store has no chunks, it throws an error. If the file exists, it updates the existing file; otherwise, it adds the new file to the end of the lookup and chunk lists and pushes it to the content array.", + "description": "Adds a structured file to the document store, checking if the store has been loaded and if the file exists before attempting to add it. If the file already exists, it updates its content; otherwise, it appends the file to the end of the lookup and chunks arrays.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Required to be present and have a valid path." + "description": "Required to be non-null and have a valid path property. If either condition is not met, the function returns false without adding the file." } ], "returns": { "type_name": "boolean*", - "description": "`true` if the file is successfully added, and `false` otherwise, indicating whether the operation was successful or not." + "description": "True if the file was successfully added and false otherwise." }, "usage": { "language": "typescript", - "code": "let store = new DocumentStore();\nstore.load(); // load data before adding files\nlet file1 = { path: 'path1', content: 'content1' };\nstore.addFile(file1); // successfully add a file\n\nlet file2 = { path: 'path1', content: 'newContent' };\nstore.addFile(file2); // update existing file\n", + "code": "let myDocumentStore = new DocumentStore(myGetRemote);\nmyDocumentStore.load();\n\nlet myFile1 = {\n path: 'path/to/file1',\n //... other properties\n};\nlet result = myDocumentStore.addFile(myFile1);\n\nif (result) {\n // File added successfully\n} else {\n // Error occurred while adding the file\n}\n", "description": "" }, "name": "addFile", @@ -533,27 +533,27 @@ "docLength": 10 }, { - "id": "b8a4e02a-a11c-e79d-e441-c76b56ba623a", + "id": "0780dbdd-fc9d-59bb-da43-5aa8edae0efb", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Asynchronously updates a file's metadata in the document store. It checks if the file exists, adds it to the chunk if necessary, loads the corresponding chunk if needed, and updates the file's index in the chunk and content arrays.", + "description": "Updates a file in the document store, handling cases where the file does not exist and ensuring that required chunks are loaded before updating. It returns a boolean indicating success or failure.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Required to be present for the function to continue processing." + "description": "Required for updating files. It represents a structured file that needs to be added or updated in the storage system." } ], "returns": { "type_name": "Promise*", - "description": "A promise that resolves to either true or false." + "description": "A promise that resolves to a boolean indicating whether the file was successfully updated. If an error occurs during the update process, the promise will resolve to false." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\nconst file1 = {\n path: '/path/to/file1',\n // other relevant fields...\n};\n\ndocumentStore.updateFile(file1).then(result => {\n if (result) console.log('File updated successfully');\n}).catch(error => {\n console.error('Error updating file:', error);\n});\n", + "code": "const documentStore = new DocumentStore();\nconst file = { path: 'path/to/file', content: 'file contents' };\n\ndocumentStore.updateFile(file).then((updated) => {\n if (updated) {\n // File updated successfully\n } else {\n // File update failed\n }\n});\n", "description": "" }, "name": "updateFile", @@ -572,19 +572,19 @@ "docLength": 10 }, { - "id": "10394081-0463-aba0-3643-ab31b6b4b7ce", + "id": "836bf1f1-7b53-4ca1-1540-d4b67721f6a6", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Returns an object containing two properties, `meta` and `lookup`, which are obtained from the current instance's `this.meta` and `this.lookup` attributes, respectively. The returned object represents a summary of the document store.", + "description": "Generates a summary object containing two properties, `meta` and `lookup`, which are references to corresponding properties within the `DocumentStore` class. The summary provides an overview of the document store's metadata and lookup data.", "params": [], "returns": { "type_name": "Summary*", - "description": "An object containing two properties: meta and lookup, both having values inherited from this reference." + "description": "An object containing two properties: meta and lookup." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nconst result = documentStore.outputSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\nconst summary = documentStore.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -603,19 +603,19 @@ "docLength": 6 }, { - "id": "ea63d1fb-c8e3-54ae-0a48-43bc9958c4a1", + "id": "349f5a77-f842-32b3-064b-cf696fe5b471", "ancestors": [ - "249335bd-68db-f3bd-8547-f91e9345106a" + "c2cf8602-37f8-e3a9-8044-7ad6893a539d" ], - "description": "Splits the `content` property into chunks based on the `CHUNK_SIZE`, generates chunk keys, and stores each chunk in a `Record` object. The method returns this `Record` containing chunked content.", + "description": "Breaks down the content into smaller chunks based on a specified size, generates unique keys for each chunk, and stores them in a Record object along with their corresponding contents. The method then returns this Record object.", "params": [], "returns": { "type_name": "Record*", - "description": "An object where keys are strings and values can be any data type." + "description": "A collection of key-value pairs where keys are strings and values can be of any data type, representing chunks of the input content with corresponding paths." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\nconst outputChunks = documentStore.outputChunks();\n// further processing of the outputChunks\n", + "code": "const documentStore = new DocumentStore(\n async (...args: any[]) => Promise.resolve({}),\n {\n version: '1.0',\n created_at: new Date(),\n updated_at: new Date()\n }\n);\n\nconst outputs = documentStore.outputChunks();\n\n// Outputs will be a Record where keys are string and values are array of bytes\n", "description": "" }, "name": "outputChunks", diff --git a/.komment/komment.json b/.komment/komment.json index 074dc89..71490a8 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,14 +1,15 @@ { "meta": { "version": "1", - "updated_at": "2024-07-10T18:18:12.447Z", + "updated_at": "2024-07-10T18:24:08.973Z", "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" + "4857c9e7-9349-41a8-96c5-56be5ffb04cf", + "75505a3a-f1af-4ca1-9174-9b908cdee0e4" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 41f1965..dfaf5bd 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,10 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Manages structured files, allowing for efficient storage and retrieval - * of file metadata and contents. It enables chunk-based loading, lookup, and updating - * of files, facilitating large-scale data processing and querying. + * @description Manages a collection of structured files (e.g., code chunks) and + * provides methods for loading, storing, updating, and retrieving files. It maintains + * metadata, lookup tables, and chunked storage to efficiently manage large collections + * of files. * * @implements {IDocumentStore} */ @@ -46,19 +47,17 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Initializes an instance with required parameters: namespace and - * getRemote method. It sets properties, such as CHUNK_SIZE, namespace, getRemote, - * meta, metaTemplate, lookup, chunks, content, and status. It validates the input - * and throws errors if namespace or getRemote is missing. + * @description Initializes an instance with required namespace and getRemote method, + * and optional additional meta data. It sets properties such as CHUNK_SIZE, namespace, + * getRemote, meta, metaTemplate, lookup, chunks, content, and status. * - * @param {string*} namespace - Required to be specified when constructing an instance - * of this class. It represents a unique identifier for the namespace of the document - * store. + * @param {string*} namespace - Required, as indicated by the throw error if it is + * not provided. It is used to set the namespace property of the object instance. * - * @param {(...args: any[]) => Promise>*} getRemote - Required. It - * returns a promise that resolves to an object with property values of type any. + * @param {(...args: any[]) => Promise>*} getRemote - Required to + * be passed to the constructor. * - * @param {Record*} additionalMeta - Used to add extra metadata properties. + * @param {Record*} additionalMeta - Used to provide additional metadata. */ constructor( namespace: string, @@ -88,13 +87,12 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` property of the `meta` object with the - * provided `updated_at` date. This method appears to be part of the `DocumentStore` - * class, responsible for managing document metadata. + * @description Updates the `updated_at` property of the `meta` object within the + * `DocumentStore` class, setting it to the provided `Date` value. * - * @param {Date*} updated_at - Passed to set the value of `this.meta.updated_at`. + * @param {Date*} updated_at - Assigned to the property `updated_at` of the object `this.meta`. * - * @returns {undefined} A property of an object. + * @returns {void} Equivalent to nothing or undefined. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; @@ -102,11 +100,12 @@ class DocumentStore implements IDocumentStore { /** * @description Loads and updates the document store's metadata, lookup data, and - * chunks from a remote source or initializes them with default values if no data is - * available. + * chunk information from a remote source or initializes with default values if no + * data is available. * - * @returns {async} A promise that resolves to an object of type Summary with properties - * meta, lookup, and chunks. + * @returns {void} A special type that represents the absence of any object value. + * It does not explicitly return a value but instead modifies some properties and + * variables within its scope. */ loadSummary = async () => { let summary: Summary = { @@ -135,7 +134,7 @@ 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]) => { - // Assigns meta values to object properties. + // Updates meta object with values from template or summary if available. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -144,12 +143,11 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Loads chunks and summary of data for a document, checking if the - * summary has been loaded first. If not, it calls the `loadSummary` method. Then, - * it iterates over chunk indices and loads corresponding chunks using the `loadChunk` - * method. Finally, it sets the `chunks` property to `true`. + * @description Asynchronously loads summary and chunks for a document store. If no + * summary exists, it first loads the summary. Then, it looks up chunk indices and + * loads each chunk individually before setting the `chunks` status to true. * - * @returns {undefined} A promise that resolves to nothing. + * @returns {void} 0. It does not explicitly return a value. */ load = async () => { if (!this.status.summary) { @@ -172,16 +170,15 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata object of a `DocumentStore` class by merging it - * with additional metadata provided as an argument. The resulting metadata is stored - * in the `meta` property of the class. This allows dynamic modification of the metadata. + * @description Updates the metadata of an object by merging additional metadata with + * the existing metadata. The new metadata replaces any duplicate keys, and the updated + * metadata is stored in the `meta` property of the `DocumentStore` class. * - * @param {Record*} additionalMeta - Expected to be an object with string - * keys and values of any type. This object contains additional metadata that needs - * to be updated in the current metadata. + * @param {Record*} additionalMeta - Used to merge with existing metadata. + * It is expected to be an object literal or a destructured object that contains + * additional key-value pairs to be added or updated in the metadata. * - * @returns {unction} An updated meta object that combines the original meta object - * with the additional metadata. + * @returns {void} Indicating that it does not return any value or data. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -197,15 +194,15 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Asynchronously loads a chunk of data from a remote location, concatenates - * it to the existing content, and stores it in an array of chunks. If loading fails, - * it returns false; otherwise, it returns true indicating successful loading. + * @description Asynchronously loads a chunk of structured data from a remote storage + * and concatenates it with the existing content, updating the internal state of the + * `DocumentStore` instance. If an error occurs during loading, it returns false; + * otherwise, it returns true indicating successful loading. * - * @param {number*} chunkIndex - Required when calling this asynchronous function. - * It represents the index of the chunk to be loaded. + * @param {number*} chunkIndex - An index that identifies a specific chunk. * - * @returns {Promise*} Resolved to either `true` (if the chunk load is - * successful) or `false` (if an error occurs during loading). + * @returns {Promise*} Resolved to a boolean indicating whether the chunk + * was loaded successfully (true) or an error occurred (false). */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -224,15 +221,16 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Asynchronously retrieves a file from a collection of structured files, - * given its path. It checks if the summary has been loaded and ensures that the - * corresponding chunk is loaded or loaded if necessary. The file index within the - * chunk is also verified before returning the requested file. + * @description Asynchronously retrieves a file from the DocumentStore based on its + * path, ensuring that the required summary has been loaded and the corresponding + * chunk is available. If not, it loads the chunk before retrieving the file. * - * @param {string*} path - Required for the function to operate correctly, representing - * the path of the file for which structured data is requested. + * @param {string*} path - The path to a file that needs to be retrieved from an + * asynchronous operation, which returns a promise resolving with either a structured + * file or null if the file could not be found. * - * @returns {Promise*} Either a StructuredFile object or null. + * @returns {Promise*} Either a `StructuredFile` object or + * null, indicating whether the requested file exists in the data structure. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -275,14 +273,15 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a given path to the end of the lookup table. If the current - * subtable is full, it creates a new one. Otherwise, it appends the path to the - * existing subtable. This approach allows efficient storage and retrieval of paths - * in the DocumentStore class. + * @description Adds a path to the end of the last lookup subtable in the `lookup` + * array if it's not full, otherwise, creates a new subtable with the path. It ensures + * that each subtable has a maximum size defined by the `CHUNK_SIZE` property. * - * @param {string*} path - Required for execution. + * @param {string*} path - Passed to the function when it is called, indicating a + * path that needs to be added to the end of the lookup subtable. * - * @returns {unction} Undefined since it doesn't explicitly define a return statement. + * @returns {void} 0 if the last lookup subtable is full and a new one is created or + * null otherwise. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -296,17 +295,12 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the end of the existing chunk or creates a new one if - * the current chunk is full, ensuring that each chunk does not exceed a specific - * size (`CHUNK_SIZE`). + * @description Adds a file to the end of an existing chunk or creates a new chunk + * if the current one is full, based on a predefined CHUNK_SIZE. * - * @param {StructuredFile*} file - An input variable that represents a file with - * structured data. It is used to determine whether it should be added to the existing - * chunk or create a new one. + * @param {StructuredFile*} file - Expected to be passed when calling this function. * - * @returns {unction} Called as a higher-order function. It does not explicitly return - * any value, but it updates the state of an object by pushing a new file into either - * a newly created chunk or the last existing one. + * @returns {void} Equivalent to no return value. It does not explicitly return a value. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -320,15 +314,16 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the `DocumentStore`. If the store has no chunks, it - * throws an error. If the file exists, it updates the existing file; otherwise, it - * adds the new file to the end of the lookup and chunk lists and pushes it to the - * content array. + * @description Adds a structured file to the document store, checking if the store + * has been loaded and if the file exists before attempting to add it. If the file + * already exists, it updates its content; otherwise, it appends the file to the end + * of the lookup and chunks arrays. * - * @param {StructuredFile*} file - Required to be present and have a valid path. + * @param {StructuredFile*} file - Required to be non-null and have a valid path + * property. If either condition is not met, the function returns false without adding + * the file. * - * @returns {boolean*} `true` if the file is successfully added, and `false` otherwise, - * indicating whether the operation was successful or not. + * @returns {boolean*} True if the file was successfully added and false otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -351,14 +346,16 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Asynchronously updates a file's metadata in the document store. It - * checks if the file exists, adds it to the chunk if necessary, loads the corresponding - * chunk if needed, and updates the file's index in the chunk and content arrays. + * @description Updates a file in the document store, handling cases where the file + * does not exist and ensuring that required chunks are loaded before updating. It + * returns a boolean indicating success or failure. * - * @param {StructuredFile*} file - Required to be present for the function to continue - * processing. + * @param {StructuredFile*} file - Required for updating files. It represents a + * structured file that needs to be added or updated in the storage system. * - * @returns {Promise*} A promise that resolves to either true or false. + * @returns {Promise*} A promise that resolves to a boolean indicating whether + * the file was successfully updated. If an error occurs during the update process, + * the promise will resolve to false. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -388,13 +385,12 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing two properties, `meta` and `lookup`, - * which are obtained from the current instance's `this.meta` and `this.lookup` - * attributes, respectively. The returned object represents a summary of the document - * store. + * @description Generates a summary object containing two properties, `meta` and + * `lookup`, which are references to corresponding properties within the `DocumentStore` + * class. The summary provides an overview of the document store's metadata and lookup + * data. * - * @returns {Summary*} An object containing two properties: meta and lookup, both - * having values inherited from this reference. + * @returns {Summary*} An object containing two properties: meta and lookup. */ outputSummary(): Summary { return { @@ -403,12 +399,13 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Splits the `content` property into chunks based on the `CHUNK_SIZE`, - * generates chunk keys, and stores each chunk in a `Record` object. The method returns - * this `Record` containing chunked content. + * @description Breaks down the content into smaller chunks based on a specified size, + * generates unique keys for each chunk, and stores them in a Record object along + * with their corresponding contents. The method then returns this Record object. * - * @returns {Record*} An object where keys are strings and values can - * be any data type. + * @returns {Record*} A collection of key-value pairs where keys are + * strings and values can be of any data type, representing chunks of the input content + * with corresponding paths. */ outputChunks(): Record { const outputs: Record = {};