From f7ca637beb5190354da1ee009c25770483c4d413 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 16:34:51 +0000 Subject: [PATCH 01/30] Added comments to 33 functions across 7 files --- .komment/00000.json | 1051 +++++++++++++++++++++++++++++++++++++ .komment/komment.json | 21 + src/index.ts | 178 ++++--- tests/index.test.ts | 65 +++ types/IDocumentStore.d.ts | 5 + types/Meta.d.ts | 4 + types/StructuredFile.d.ts | 4 + types/Summary.d.ts | 7 + 8 files changed, 1264 insertions(+), 71 deletions(-) create mode 100644 .komment/00000.json create mode 100644 .komment/komment.json diff --git a/.komment/00000.json b/.komment/00000.json new file mode 100644 index 0000000..58400c7 --- /dev/null +++ b/.komment/00000.json @@ -0,0 +1,1051 @@ +[ + { + "name": "index.ts", + "path": "src/index.ts", + "content": { + "structured": { + "description": "A `DocumentStore` class that manages adding, retrieving, and updating files in a specified namespace. It provides a high-quality summary of the code by generating an object with `meta` and `lookup` properties, or a record of chunks extracted from the given content. The class implements various methods such as `load`, `addFile`, `updateFile`, and `outputSummary`. It also utilizes various high-level packages like `Passive`, `Ok`, and `Hello`.", + "items": [ + { + "id": "8258e45d-b951-4d89-6549-286960791363", + "ancestors": [], + "description": "Provides a structured way of storing and retrieving code documentation, including files, chunks, and metadata. It offers features like loading high-quality summaries, updating metadata, and generating records of chunks.", + "interfaces": [ + "IDocumentStore" + ], + "superclass": null, + "is_abstract": false, + "fields": [ + { + "name": "CHUNK_SIZE", + "type_name": "number", + "description": "Used to define the size of a chunk for storing content." + }, + { + "name": "namespace", + "type_name": "string", + "description": "Required. It specifies the name or identifier of a specific area or domain that contains files or documents to be stored, managed, and retrieved by the Document Store." + }, + { + "name": "meta", + "type_name": { + "full": "{\n version: string;\n created_at: Date;\n updated_at: Date;\n [key: string]: any;\n }", + "pattern": "object", + "sub": [ + { + "name": "version", + "type_name": "string", + "value": null, + "visibility": null, + "is_static": false, + "is_optional": false, + "is_readonly": false + }, + { + "name": "created_at", + "type_name": "Date", + "value": null, + "visibility": null, + "is_static": false, + "is_optional": false, + "is_readonly": false + }, + { + "name": "updated_at", + "type_name": "Date", + "value": null, + "visibility": null, + "is_static": false, + "is_optional": false, + "is_readonly": false + } + ] + }, + "description": "Used to store version number, creation date, and update date of the document store instance." + }, + { + "name": "metaTemplate", + "type_name": { + "pattern": "generic", + "full": "Record", + "name": "Record", + "by": [ + "string", + "any" + ] + }, + "description": "Used to specify a template for the `meta` object in the generated documentation." + }, + { + "name": "lookup", + "type_name": "string[][]", + "description": "Used to store a list of file paths that are associated with chunks of code." + }, + { + "name": "chunks", + "type_name": "StructuredFile[][]", + "description": "Used to store chunks of content from the original document." + }, + { + "name": "content", + "type_name": "StructuredFile[]", + "description": "Used to store the actual files or content that will be stored in the document storage. It is initialized as an empty array when the class is created, and can be updated through methods such as `addFile()`." + }, + { + "name": "status", + "type_name": { + "full": "{\n summary: boolean;\n chunks: boolean;\n }", + "pattern": "object", + "sub": [ + { + "name": "summary", + "type_name": "boolean", + "value": null, + "visibility": null, + "is_static": false, + "is_optional": false, + "is_readonly": false + }, + { + "name": "chunks", + "type_name": "boolean", + "value": null, + "visibility": null, + "is_static": false, + "is_optional": false, + "is_readonly": false + } + ] + }, + "description": "Used to track the progress of loading documents" + } + ], + "name": "DocumentStore", + "location": { + "start": 22, + "insert": 22, + "offset": " ", + "indent": 0, + "comment": null + }, + "item_type": "class", + "length": 352, + "docLength": null + }, + { + "id": "36c48432-c42e-b388-f14c-92d323842cb2", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Establishes instance variables and sets default values for them. It also validates inputs, such as ensuring that `namespace` and `getRemote` are provided, and initializes objects to store metadata and chunks of data.", + "params": [ + { + "name": "namespace", + "type_name": "string", + "optional": false, + "description": "Required to initialize an instance of the class. It represents the name of the application or project for which the code is being generated.", + "default_value": null + }, + { + "name": "getRemote", + "type_name": "(...args: any[]) => Promise>", + "optional": false, + "description": "Required for calling the remote data retrieval method.", + "default_value": null + }, + { + "name": "additionalMeta", + "type_name": "Record", + "optional": true, + "description": "Used to provide additional metadata for the document store.", + "default_value": "{}" + } + ], + "usage": { + "language": "typescript", + "code": "const store = new DocumentStore('namespace', getRemote, { additionalMeta });\nstore.loadSummary();\n", + "description": "" + }, + "name": null, + "location": { + "start": 53, + "insert": 41, + "offset": " ", + "indent": 2, + "comment": { + "start": 40, + "end": 52 + } + }, + "item_type": "constructor", + "length": 26, + "docLength": 12 + }, + { + "id": "6fb22175-3e46-2589-da43-027dd7ced2e6", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Updates the `updated_at` metadata field of the `DocumentStore` instance by assigning the provided `Date` object directly to the `meta` object within the method body.", + "params": [ + { + "name": "updated_at", + "default_value": null, + "optional": false, + "type_name": "Date", + "description": "Used to update the metadata for the entity." + } + ], + "returns": { + "type_name": "void", + "description": "The result of updating the `meta` object's `updated_at` property with the provided `Date`." + }, + "usage": { + "language": "typescript", + "code": "const store = new DocumentStore(getRemote);\nstore.setUpdatedAt(new Date());\n", + "description": "" + }, + "name": "setUpdatedAt", + "location": { + "start": 87, + "insert": 80, + "offset": " ", + "indent": 2, + "comment": { + "start": 79, + "end": 86 + } + }, + "item_type": "function", + "length": 3, + "docLength": 7 + }, + { + "id": "524b45ed-f439-cbbd-2945-36418e6f57a8", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Retrieves and updates the document store's summary metadata from the remote source, and assigns it to the local `summary` object.", + "params": [], + "returns": { + "type_name": "Summary", + "description": "An object with properties `meta`, `lookup`, and `chunks`." + }, + "usage": { + "language": "typescript", + "code": "const documentStore = new DocumentStore({\n getRemote: (...args) => {\n return ...; // The implementation of the third party library or service that provides the functionality for generating high-quality documentation.\n },\n integration: {\n id: 'xxx', // Integration ID\n name: 'xxx', // Integration name\n description: 'xxx' // Integration description\n }\n});\ndocumentStore.loadSummary();\n", + "description": "" + }, + "name": "loadSummary", + "location": { + "start": 95, + "insert": 91, + "offset": " ", + "indent": 2, + "comment": { + "start": 90, + "end": 94 + } + }, + "item_type": "function", + "length": 32, + "docLength": 4 + }, + { + "id": "cefa0238-d667-0c9a-c74d-51d2189674fc", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363", + "524b45ed-f439-cbbd-2945-36418e6f57a8" + ], + "description": "* Iterates over the entries of an object `this.metaTemplate` using Object.entries()\n* For each entry, it checks if there is a corresponding key in the `summary.meta` object or default value is set by providing `value`\n* If a key-value pair is found in `summary.meta`, the value is assigned to `this.meta[key]`\n* Otherwise, the default value is assigned to `this.meta[key]`", + "name": null, + "location": { + "start": 121, + "insert": 122, + "offset": " ", + "indent": 6, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 3, + "docLength": null + }, + { + "id": "c7be8cc0-da04-44a1-b84d-1cc6818604ee", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Of the `DocumentStore` class asynchronously loads the summary and chunks of a document, setting `status.summary` and `status.chunks` to `true` upon completion.", + "params": [], + "returns": { + "type_name": "void", + "description": "Indicative of a function that does not return any values." + }, + "usage": { + "language": "typescript", + "code": "const docStore = new DocumentStore({getRemote, integration});\nawait docStore.load();\n// Use the loaded chunks\n", + "description": "" + }, + "name": "load", + "location": { + "start": 131, + "insert": 128, + "offset": " ", + "indent": 2, + "comment": { + "start": 127, + "end": 130 + } + }, + "item_type": "function", + "length": 12, + "docLength": 3 + }, + { + "id": "b7e0d6eb-5701-95b4-eb44-546612cc02ce", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Updates the metadata of an object by merging the existing metadata with additional metadata provided as an argument.", + "params": [ + { + "name": "additionalMeta", + "default_value": null, + "optional": false, + "type_name": "Record", + "description": "An object that contains additional metadata to be merged with the current metadata associated with the object." + } + ], + "returns": { + "type_name": "Recordstring", + "description": "An immutable object containing a combination of the existing metadata and the additional metadata passed as argument." + }, + "usage": { + "language": "typescript", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.updateMetadata({ version: \"1.0\", created_at: new Date() });\n", + "description": "" + }, + "name": "updateMetadata", + "location": { + "start": 151, + "insert": 151, + "offset": " ", + "indent": 2, + "comment": null + }, + "item_type": "function", + "length": 6, + "docLength": null + }, + { + "id": "8d35b66a-a865-37ac-334f-8048e891c3ce", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Of the `DocumentStore` class loads a chunk of data from a remote source and stores it in the object's internal state. If the chunk is already loaded, it returns `true`. Otherwise, it returns `false` after adding the chunk to the object's internal state.", + "params": [ + { + "name": "chunkIndex", + "default_value": null, + "optional": false, + "type_name": "number", + "description": "Used to identify the specific chunk being loaded." + } + ], + "returns": { + "type_name": "Promiseboolean", + "description": "True when the chunk is successfully loaded and False otherwise." + }, + "usage": { + "language": "typescript", + "code": "const docStore = new DocumentStore(getRemote, integration);\nconst chunkLoadedSuccessfully = await docStore.loadChunk(chunkIndex);\nif (chunkLoadedSuccessfully) {\n // do something with the loaded chunk\n} else {\n // handle error\n}\n", + "description": "" + }, + "name": "loadChunk", + "location": { + "start": 175, + "insert": 164, + "offset": " ", + "indent": 2, + "comment": { + "start": 163, + "end": 174 + } + }, + "item_type": "function", + "length": 16, + "docLength": 11 + }, + { + "id": "2898a487-c3c7-248c-5a44-de9231dcee0a", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Retrieves a file from a store based on its path, calculating the chunk it is located in and loading the chunk if necessary. It then returns the file within that chunk.", + "params": [ + { + "name": "path", + "default_value": null, + "optional": false, + "type_name": "string", + "description": "Used to specify the file path being searched for." + } + ], + "returns": { + "type_name": "StructuredFile", + "description": "Either a file or null if it does not exist or cannot be accessed." + }, + "usage": { + "language": "typescript", + "code": "const documentStore = new DocumentStore(getRemote, integration);\n\n// Load summary from remote storage\nawait documentStore.loadSummary();\n\n// Access a file\nconst file = await documentStore.getFile(\"path/to/file\");\n", + "description": "" + }, + "name": "getFile", + "location": { + "start": 201, + "insert": 191, + "offset": " ", + "indent": 2, + "comment": { + "start": 190, + "end": 200 + } + }, + "item_type": "function", + "length": 23, + "docLength": 10 + }, + { + "id": "c103b9f0-df34-18a7-224f-d52375955310", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "In the `DocumentStore` class adds a new path to the end of a lookup table if necessary, ensuring that the last subtable is not full and has enough space for additional entries.", + "params": [ + { + "name": "path", + "default_value": null, + "optional": false, + "type_name": "string", + "description": "Used to add a new subtable to the existing lookup table." + } + ], + "returns": { + "type_name": "array", + "description": "An augmented list of path." + }, + "usage": { + "language": "typescript", + "code": "const store = new DocumentStore(getRemote, integration);\nstore.addToEndOfLookup(\"path\");\n", + "description": "" + }, + "name": "addToEndOfLookup", + "location": { + "start": 247, + "insert": 241, + "offset": " ", + "indent": 2, + "comment": { + "start": 240, + "end": 246 + } + }, + "item_type": "function", + "length": 11, + "docLength": 6 + }, + { + "id": "9e87ab49-5442-7baa-1844-501f5833ef3d", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Adds a file to the end of an array of files stored in chunks, creating a new chunk if necessary to avoid exceeding the maximum size.", + "params": [ + { + "name": "file", + "default_value": null, + "optional": false, + "type_name": "StructuredFile", + "description": "Passed as an argument to the function." + } + ], + "returns": { + "type_name": "StructuredFile", + "description": "A new StructuredFile object containing the file added to the end of the chunks array." + }, + "usage": { + "language": "typescript", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks({\n \"filename\": \"README.md\",\n \"content\": \"# Welcome to my README\",\n});\n", + "description": "" + }, + "name": "addToEndOfChunks", + "location": { + "start": 268, + "insert": 258, + "offset": " ", + "indent": 2, + "comment": { + "start": 257, + "end": 267 + } + }, + "item_type": "function", + "length": 11, + "docLength": 10 + }, + { + "id": "693fd591-8316-50be-c64b-bb105acfd0f2", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Of the `DocumentStore` class allows adding a new file to the document store, checking for file existence and proper loading order before updating the content and pushing the file to the end of the `content` array.", + "params": [ + { + "name": "file", + "default_value": null, + "optional": false, + "type_name": "StructuredFile", + "description": "Used to represent a file that can be added to the content array of the object." + } + ], + "returns": { + "type_name": "boolean", + "description": "True when the file is successfully added to the content and False otherwise." + }, + "usage": { + "language": "typescript", + "code": "const docStore = new DocumentStore({getRemote, integration});\ndocStore.addFile(myFile);\n", + "description": "" + }, + "name": "addFile", + "location": { + "start": 289, + "insert": 279, + "offset": " ", + "indent": 2, + "comment": { + "start": 278, + "end": 288 + } + }, + "item_type": "function", + "length": 20, + "docLength": 10 + }, + { + "id": "925f26c0-737d-48b9-ed4f-5ec85c0736c3", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Of the `DocumentStore` class updates a file in the store by checking if it exists, loading the chunk if necessary, and storing the file in the chunk. It returns a boolean indicating whether the update was successful.", + "params": [ + { + "name": "file", + "default_value": null, + "optional": false, + "type_name": "StructuredFile", + "description": "Passed to update the file content in the Chunk." + } + ], + "returns": { + "type_name": "Promiseboolean", + "description": "True if the file was updated successfully and false otherwise." + }, + "usage": { + "language": "typescript", + "code": "let documentStore = new DocumentStore();\ndocumentStore.getRemote = async (...args) => {\n // call to 3rd party library or service that provides functionality for generating high-quality documentation.\n};\n\nlet file = await documentStore.updateFile(path);\n", + "description": "" + }, + "name": "updateFile", + "location": { + "start": 319, + "insert": 309, + "offset": " ", + "indent": 2, + "comment": { + "start": 308, + "end": 318 + } + }, + "item_type": "function", + "length": 27, + "docLength": 10 + }, + { + "id": "06441ba6-cadb-6eac-e546-287522d6b9e1", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Returns an object containing the `meta` and `lookup` properties of the current instance of the `DocumentStore` class.", + "params": [], + "returns": { + "type_name": "Summary", + "description": "An object containing two properties: `meta` and `lookup`." + }, + "usage": { + "language": "typescript", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputSummary();\n", + "description": "" + }, + "name": "outputSummary", + "location": { + "start": 352, + "insert": 346, + "offset": " ", + "indent": 2, + "comment": { + "start": 345, + "end": 351 + } + }, + "item_type": "function", + "length": 6, + "docLength": 6 + }, + { + "id": "1e592da2-d55e-d287-4142-08991fb64611", + "ancestors": [ + "8258e45d-b951-4d89-6549-286960791363" + ], + "description": "Of `DocumentStore` takes the contents of the document and splits it into chunks, storing each chunk in a map with a unique key based on its position in the document.", + "params": [], + "returns": { + "type_name": "Recordstring", + "description": "An object that maps string keys to any values." + }, + "usage": { + "language": "typescript", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.outputChunks(); // returns a dictionary of chunk paths and corresponding content\n", + "description": "\nIn this example, the `outputChunks()` method of the `DocumentStore` class is called to return a dictionary of chunk paths and corresponding content. The `getRemote` and `integration` parameters are passed as arguments to the constructor of the `DocumentStore` class." + }, + "name": "outputChunks", + "location": { + "start": 364, + "insert": 358, + "offset": " ", + "indent": 2, + "comment": { + "start": 357, + "end": 363 + } + }, + "item_type": "function", + "length": 9, + "docLength": 6 + } + ] + } + } + }, + { + "name": "index.test.ts", + "path": "tests/index.test.ts", + "content": { + "structured": { + "description": "A `DocumentStore` class that manages a collection of files and their metadata. The class provides methods for loading, adding, updating, and retrieving files from the store. It also includes tests for various use cases, such as creating an empty store, setting the summary file path, loading a summary file, and adding or updating files in the store. The code uses the `StructuredFile` type and the `mockSummary` function to generate mock summaries of files.", + "items": [ + { + "id": "54784b16-dc93-1eaa-c648-e6a9113abc03", + "ancestors": [], + "description": "Resolves a promise containing metadata and lookup information for a mock API endpoint. The metadata includes creation and update timestamps, while the lookup array contains paths to two files in the `src/` directory: `index.js`, `database.js`, and `component/index.js`.", + "params": [], + "returns": { + "type_name": "Object", + "description": "A meta object containing creation and update timestamps and a list of pipelines, as well as a lookup array with paths to two files and one directory in the src directory." + }, + "usage": { + "language": "typescript", + "code": "const mockSummary = () => {\n return Promise.resolve({\n meta: {\n created_at: \"2024-04-08T13:50:02.790Z\",\n updated_at: \"2024-04-08T13:50:02.790Z\",\n pipelines: [\"cd1d3bab-03db-494c-9e03-16ee456964fb\"],\n },\n lookup: [[\"src/index.js\", \"src/database.js\"], [\"src/component/index.js\"]],\n });\n };\n", + "description": "" + }, + "name": "mockSummary", + "location": { + "start": 6, + "insert": 6, + "offset": " ", + "indent": 0, + "comment": null + }, + "item_type": "function", + "length": 9, + "docLength": null + }, + { + "id": "d2c09581-f2ac-5d81-1943-78c80aecfaf5", + "ancestors": [], + "description": "Takes a chunk path as input and returns a resolved promise of either the mock summary or a file from the chunks array depending on the chunk path provided.", + "params": [ + { + "name": "chunkPath", + "default_value": null, + "optional": false, + "type_name": "string", + "description": "Used to determine which mock file to return based on its path relative to the namespace prefix." + } + ], + "returns": { + "type_name": "Promise", + "description": "Resolved with either a mock summary or one of the chunks." + }, + "usage": { + "language": "typescript", + "code": "const chunkPath = `.${NAMESPACE}/00001.json`;\ngetFileMock(chunkPath).then((data) => {\n // data will contain the contents of the file located at chunkPath\n});\n", + "description": "" + }, + "name": "getFileMock", + "location": { + "start": 16, + "insert": 16, + "offset": " ", + "indent": 0, + "comment": null + }, + "item_type": "function", + "length": 12, + "docLength": null + }, + { + "id": "42ef8453-2d77-95a8-554a-205aaf438ac1", + "ancestors": [], + "description": "Returns an array of objects, each representing a file or directory within a project. The objects contain information about the file's name, path, and content, including a description.", + "params": [], + "returns": { + "type_name": "Object", + "description": "An array of objects representing files and their contents. Each object in the array has three properties: name, path, and content, where content is a JSON object containing a string value representing the file's contents." + }, + "usage": { + "language": "typescript", + "code": "const chunks = () => ({\n \"00000\": [\n {\n name: \"mock-1\",\n path: \"src/index.js\",\n content: {\n description: \"duck\",\n },\n },\n {\n name: \"mock-2\",\n path: \"src/database.js\",\n content: {\n description: \"duckDB\",\n },\n },\n ],\n \"00001\": [\n {\n name: \"mock-3\",\n path: \"src/component/index.js\",\n content: {\n description: \"Component Duck\",\n },\n },\n ],\n});\n", + "description": "" + }, + "name": "chunks", + "location": { + "start": 29, + "insert": 29, + "offset": " ", + "indent": 0, + "comment": null + }, + "item_type": "function", + "length": 27, + "docLength": null + }, + { + "id": "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae", + "ancestors": [], + "description": "Tests various features of a DocumentStore.", + "name": null, + "location": { + "start": 72, + "insert": 73, + "offset": " ", + "indent": 2, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 127, + "docLength": null + }, + { + "id": "e39cefa6-6f3c-11b0-a543-efb3ad18b4be", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "Creates an instance of `DocumentStore` and calls its `outputSummary()` method, which returns a summary of the document store's contents.", + "name": null, + "location": { + "start": 73, + "insert": 74, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 7, + "docLength": null + }, + { + "id": "5d73bcf9-32c3-e396-aa42-d33f685393c0", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "Creates a new instance of `DocumentStore`, passing the namespace as an argument, and resolves a promise to obtain the chunk summary path based on the namespace.", + "name": null, + "location": { + "start": 80, + "insert": 81, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 7, + "docLength": null + }, + { + "id": "5189ae6a-225a-cc8e-c848-8ee549f24403", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "Loads a summary file and returns a summary object containing two items in its `lookup` property.", + "name": null, + "location": { + "start": 87, + "insert": 88, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 9, + "docLength": null + }, + { + "id": "eb9de803-c44e-7086-3645-bb43e4ad1879", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "1) creates a new instance of `DocumentStore`, 2) sets its chunk size to 2, and 3) loads all chunks using the `load()` method, after which it verifies that both the summary and output chunks contain two elements each.", + "name": null, + "location": { + "start": 96, + "insert": 97, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 17, + "docLength": null + }, + { + "id": "34a3eb46-440e-0b81-494c-98661494aa51", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "1) creates a new instance of `DocumentStore`, 2) sets the chunk size to 2, and 3) retrieves the file at the specified path (\"src/database.js\") using the `getFile()` method.", + "name": null, + "location": { + "start": 113, + "insert": 114, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 12, + "docLength": null + }, + { + "id": "dbc7e254-f2d7-9fb6-074a-20cd2a79b475", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "* Creates a new instance of `DocumentStore` with a mock `getFile` method.\n* Calls the `getFile` method on the `DocumentStore` instance with the file path \"src/index.js\".\n* Expects an error to be thrown due to the absence of the `load` method call before accessing the file.", + "name": null, + "location": { + "start": 125, + "insert": 126, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 9, + "docLength": null + }, + { + "id": "a7776b74-8dea-0d9e-d04a-c5b55b6c07d9", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "Adds a new file to a store and retrieves it back for verification.", + "name": null, + "location": { + "start": 134, + "insert": 135, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 14, + "docLength": null + }, + { + "id": "7a4f7b46-c275-bc9c-0443-1eba61261138", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "1) creates a new `DocumentStore` instance, 2) sets its `CHUNK_SIZE` to a specific value, and 3) updates an existing file using the `updateFile()` method, followed by retrieving the file using the `getFile()` method and verifying its path.", + "name": null, + "location": { + "start": 148, + "insert": 149, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 14, + "docLength": null + }, + { + "id": "b7d35d2d-cc97-1da7-314c-29d5ed647f1f", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "1) creates a new instance of `DocumentStore`, 2) sets properties on that instance, and 3) updates an existing file in the store by providing the same path but different content description.", + "name": null, + "location": { + "start": 162, + "insert": 163, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 18, + "docLength": null + }, + { + "id": "6b9dcf34-3a0d-5681-4948-1f6642e76ff8", + "ancestors": [ + "16a9564b-c1ba-8f9a-ae4b-ecfee46661ae" + ], + "description": "Updates an existing file in a document store by adding new content and verifying if the updated file's description matches the expected value.", + "name": null, + "location": { + "start": 180, + "insert": 181, + "offset": " ", + "indent": 4, + "comment": null + }, + "item_type": "higher_order_invocation", + "length": 18, + "docLength": null + } + ] + } + } + }, + { + "name": "IDocumentStore.d.ts", + "path": "types/IDocumentStore.d.ts", + "content": { + "structured": { + "description": "An interface for a document store that includes several properties and methods: `CHUNK_SIZE`, `namespace`, `meta`, `lookup`, and `status`. The `CHUNK_SIZE` property sets the size of chunks used for storing documents, while the `namespace` property specifies the namespace for the document store. The `meta` property provides metadata for the document store, and the `lookup` property is an array of strings representing the paths to chunks containing documents. The `status` property contains two properties: `summary`, which indicates whether the document store has a summary available, and `chunks`, which indicates whether the document store has any chunks available.", + "items": [ + { + "id": "780ab884-af40-379b-1348-8337e3c66a94", + "ancestors": [], + "description": "Defines a set of properties and methods for storing and managing documents. It includes the document chunk size, namespace, metadata, and a lookup array. Additionally, it provides a status object with summary and chunks properties.", + "name": "IDocumentStore", + "location": { + "start": 3, + "insert": 3, + "offset": " ", + "indent": 0, + "comment": null + }, + "item_type": "interface", + "length": 10, + "docLength": null + } + ] + } + } + }, + { + "name": "Meta.d.ts", + "path": "types/Meta.d.ts", + "content": { + "structured": { + "description": "An interface called `Meta` that represents a metadata object. The interface has four properties: `version`, `created_at`, `updated_at`, and an optional property with any type of value. The `version` property is a string representing the version number, the `created_at` and `updated_at` properties are Date objects representing the creation and last update time of the metadata object.", + "items": [ + { + "id": "ab4e3495-19b9-a8a0-7c4f-a600389893b7", + "ancestors": [], + "description": "Defines a set of properties that consist of a version, creation and update dates, and arbitrary data stored under key strings.", + "name": "Meta", + "location": { + "start": 1, + "insert": 1, + "offset": " ", + "indent": 0, + "comment": null + }, + "item_type": "interface", + "length": 6, + "docLength": null + } + ] + } + } + }, + { + "name": "StructuredFile.d.ts", + "path": "types/StructuredFile.d.ts", + "content": { + "structured": { + "description": "An interface named StructuredFile that consists of three properties: name, path, and content. The interface represents a file with structured data, allowing for easy manipulation and storage. The content property can hold any type of data, and the other two properties provide information about the file's identity and location.", + "items": [ + { + "id": "2801a404-7bff-0c82-9643-0b8059ca5fcc", + "ancestors": [], + "description": "Defines a set of properties for a file, including its name, path, and contents.", + "name": "StructuredFile", + "location": { + "start": 1, + "insert": 1, + "offset": " ", + "indent": 0, + "comment": null + }, + "item_type": "interface", + "length": 5, + "docLength": null + } + ] + } + } + }, + { + "name": "Summary.d.ts", + "path": "types/Summary.d.ts", + "content": { + "structured": { + "description": "An interface Summary, which consists of three properties: meta, lookup, and chunks. The meta property is of type Meta, while the lookup property is an array of strings, representing a two-dimensional matrix. The chunks property is optional and represents a list of strings, likely used for chunking the input data.", + "items": [ + { + "id": "026a21ea-5807-858f-2b43-e6bd784ef8dc", + "ancestors": [], + "description": "Defines a set of properties: `meta`, `lookup`, and `chunks`. The `meta` property is an object with additional information about the summary, while the `lookup` property is an array of arrays representing the lookup tables for each chunk. The `chunks` property can optionally be defined as an array of strings, representing the chunks of data in the summary.", + "name": "Summary", + "location": { + "start": 3, + "insert": 3, + "offset": " ", + "indent": 0, + "comment": null + }, + "item_type": "interface", + "length": 5, + "docLength": null + } + ] + } + } + }, + { + "name": "jest.config.js", + "path": "jest.config.js", + "content": { + "structured": { + "description": "configuration options for Jest, a popular JavaScript testing framework. The `preset` option sets the Jest preset to use, in this case \"ts-jest\". The `testEnvironment` option specifies that Jest should run tests in a Node environment. Finally, the `testMatch` option specifies which files should be searched for test files, using glob syntax to match files with extensions \".test.ts\".", + "items": [] + } + } + } +] \ No newline at end of file diff --git a/.komment/komment.json b/.komment/komment.json new file mode 100644 index 0000000..d64d3e4 --- /dev/null +++ b/.komment/komment.json @@ -0,0 +1,21 @@ +{ + "meta": { + "version": "1", + "updated_at": "2024-07-10T16:34:38.998Z", + "created_at": "2024-07-10T16:34:39.374Z", + "pipelines": [ + "c089e2e8-dd67-4bff-afef-c8f0f6b8a931" + ] + }, + "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" + ] + ] +} \ No newline at end of file diff --git a/src/index.ts b/src/index.ts index 4bb8303..6a9d2b1 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,6 +19,13 @@ import { Summary } from "../types/Summary"; const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; +/** + * @description Provides a structured way of storing and retrieving code documentation, + * including files, chunks, and metadata. It offers features like loading high-quality + * summaries, updating metadata, and generating records of chunks. + * + * @implements {IDocumentStore} + */ class DocumentStore implements IDocumentStore { CHUNK_SIZE: number; namespace: string; @@ -39,16 +46,18 @@ 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. - * - * @param { (...args: any[]) => Promise> } getRemote - 3rd party library or service that provides the functionality - * for generating high-quality documentation. - * - * @param { Integration } integration - Integration object that provides information - * about the integration of the code documentation with other systems or services. - * + * @description Establishes instance variables and sets default values for them. It + * also validates inputs, such as ensuring that `namespace` and `getRemote` are + * provided, and initializes objects to store metadata and chunks of data. + * + * @param {string} namespace - Required to initialize an instance of the class. It + * represents the name of the application or project for which the code is being generated. + * + * @param {(...args: any[]) => Promise>} getRemote - Required for + * calling the remote data retrieval method. + * + * @param {Record} additionalMeta - Used to provide additional metadata + * for the document store. */ constructor( namespace: string, @@ -78,19 +87,24 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` field of an instance of the `Meta` class - * with the provided `updated_at` value. - * - * @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. + * @description Updates the `updated_at` metadata field of the `DocumentStore` instance + * by assigning the provided `Date` object directly to the `meta` object within the + * method body. + * + * @param {Date} updated_at - Used to update the metadata for the entity. + * + * @returns {void} The result of updating the `meta` object's `updated_at` property + * with the provided `Date`. */ 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 Retrieves and updates the document store's summary metadata from the + * remote source, and assigns it to the local `summary` object. + * + * @returns {Summary} An object with properties `meta`, `lookup`, and `chunks`. */ loadSummary = async () => { let summary: Summary = { @@ -119,6 +133,12 @@ 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]) => { + // * Iterates over the entries of an object `this.metaTemplate` using Object.entries() + // * For each entry, it checks if there is a corresponding key in the `summary.meta` + // object or default value is set by providing `value` + // * If a key-value pair is found in `summary.meta`, the value is assigned to `this.meta[key]` + // * Otherwise, the default value is assigned to `this.meta[key]` + this.meta[key] = summary?.meta?.[key] ?? value; }); this.lookup = summary.lookup || []; @@ -126,7 +146,11 @@ class DocumentStore implements IDocumentStore { }; /** - * Loads all files from the remote store + * @description Of the `DocumentStore` class asynchronously loads the summary and + * chunks of a document, setting `status.summary` and `status.chunks` to `true` upon + * completion. + * + * @returns {void} Indicative of a function that does not return any values. */ load = async () => { if (!this.status.summary) { @@ -148,6 +172,16 @@ class DocumentStore implements IDocumentStore { getChunkSummaryPath = (): string => `.${this.namespace}/${this.namespace}.json`; + /** + * @description Updates the metadata of an object by merging the existing metadata + * with additional metadata provided as an argument. + * + * @param {Record} additionalMeta - An object that contains additional + * metadata to be merged with the current metadata associated with the object. + * + * @returns {Recordstring} An immutable object containing a combination of the existing + * metadata and the additional metadata passed as argument. + */ updateMetadata = (additionalMeta: Record) => { this.meta = { ...this.meta, @@ -162,15 +196,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. - * - * @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. - * - * @returns { Promise } a boolean value indicating whether the chunk was successfully - * loaded. + * @description Of the `DocumentStore` class loads a chunk of data from a remote + * source and stores it in the object's internal state. If the chunk is already loaded, + * it returns `true`. Otherwise, it returns `false` after adding the chunk to the + * object's internal state. + * + * @param {number} chunkIndex - Used to identify the specific chunk being loaded. + * + * @returns {Promiseboolean} True when the chunk is successfully loaded and False otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -189,14 +222,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. - * - * @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. - * - * @returns { object } a file object containing the path, name, and other properties - * of the requested file. + * @description Retrieves a file from a store based on its path, calculating the chunk + * it is located in and loading the chunk if necessary. It then returns the file + * within that chunk. + * + * @param {string} path - Used to specify the file path being searched for. + * + * @returns {StructuredFile} Either a file or null if it does not exist or cannot be + * accessed. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -239,10 +272,13 @@ 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. - * - * @param { string } path - path of a file to be looked up in the code's lookup table. + * @description In the `DocumentStore` class adds a new path to the end of a lookup + * table if necessary, ensuring that the last subtable is not full and has enough + * space for additional entries. + * + * @param {string} path - Used to add a new subtable to the existing lookup table. + * + * @returns {array} An augmented list of path. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -256,14 +292,13 @@ 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. - * - * @param { StructuredFile } file - input file for which a chunk is being created or - * appended to an existing chunk. + * @description Adds a file to the end of an array of files stored in chunks, creating + * a new chunk if necessary to avoid exceeding the maximum size. + * + * @param {StructuredFile} file - Passed as an argument to the function. + * + * @returns {StructuredFile} A new StructuredFile object containing the file added + * to the end of the chunks array. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -277,14 +312,15 @@ 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. - * - * @param { StructuredFile } file - file to be added to the structured file, which - * includes its path. - * - * @returns { boolean } a list of file objects that have been successfully added to - * the content and chunks arrays. + * @description Of the `DocumentStore` class allows adding a new file to the document + * store, checking for file existence and proper loading order before updating the + * content and pushing the file to the end of the `content` array. + * + * @param {StructuredFile} file - Used to represent a file that can be added to the + * content array of the object. + * + * @returns {boolean} True when the file is successfully added to the content and + * False otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -307,14 +343,13 @@ 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. - * - * @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. - * - * @returns { Promise } a reference to the updated file in the chunk, or `null` if the - * file does not exist. + * @description Of the `DocumentStore` class updates a file in the store by checking + * if it exists, loading the chunk if necessary, and storing the file in the chunk. + * It returns a boolean indicating whether the update was successful. + * + * @param {StructuredFile} file - Passed to update the file content in the Chunk. + * + * @returns {Promiseboolean} True if the file was updated successfully and false otherwise. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -344,10 +379,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Generates high-quality documentation for code by returning an object - * containing the `meta` and `lookup` properties. - * - * @returns { summary } an object containing `meta` and `lookup` properties. + * @description Returns an object containing the `meta` and `lookup` properties of + * the current instance of the `DocumentStore` class. + * + * @returns {Summary} An object containing two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -356,10 +391,11 @@ 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. - * - * @returns { Record } a record of chunks extracted from the given content. + * @description Of `DocumentStore` takes the contents of the document and splits it + * into chunks, storing each chunk in a map with a unique key based on its position + * in the document. + * + * @returns {Recordstring} An object that maps string keys to any values. */ outputChunks(): Record { const outputs: Record = {}; diff --git a/tests/index.test.ts b/tests/index.test.ts index 9c9dfe9..3fc87cb 100644 --- a/tests/index.test.ts +++ b/tests/index.test.ts @@ -3,6 +3,16 @@ import DocumentStore from "../src/"; const NAMESPACE = "duck"; +/** + * @description Resolves a promise containing metadata and lookup information for a + * mock API endpoint. The metadata includes creation and update timestamps, while the + * lookup array contains paths to two files in the `src/` directory: `index.js`, + * `database.js`, and `component/index.js`. + * + * @returns {Object} A meta object containing creation and update timestamps and a + * list of pipelines, as well as a lookup array with paths to two files and one + * directory in the src directory. + */ const mockSummary = () => Promise.resolve({ meta: { @@ -13,6 +23,15 @@ const mockSummary = () => lookup: [["src/index.js", "src/database.js"], ["src/component/index.js"]], }); +/** + * @description Takes a chunk path as input and returns a resolved promise of either + * the mock summary or a file from the chunks array depending on the chunk path provided. + * + * @param {string} chunkPath - Used to determine which mock file to return based on + * its path relative to the namespace prefix. + * + * @returns {Promise} Resolved with either a mock summary or one of the chunks. + */ const getFileMock = (chunkPath: string) => { switch (chunkPath) { case `.${NAMESPACE}/${NAMESPACE}.json`: @@ -26,6 +45,15 @@ const getFileMock = (chunkPath: string) => { } }; +/** + * @description Returns an array of objects, each representing a file or directory + * within a project. The objects contain information about the file's name, path, and + * content, including a description. + * + * @returns {Object} An array of objects representing files and their contents. Each + * object in the array has three properties: name, path, and content, where content + * is a JSON object containing a string value representing the file's contents. + */ const chunks = () => ({ "00000": [ { @@ -70,7 +98,12 @@ const fileToUpdate: StructuredFile = { }; describe("DocumentStore", () => { + // Tests various features of a DocumentStore. + test("creates an empty DocumentStore", () => { + // Creates an instance of `DocumentStore` and calls its `outputSummary()` method, + // which returns a summary of the document store's contents. + const newDocumentStore = new DocumentStore(NAMESPACE, () => Promise.resolve({}), ); @@ -78,6 +111,9 @@ describe("DocumentStore", () => { expect(summary.lookup.length).toBe(0); }); test("sets the summary file path based on namespace", () => { + // Creates a new instance of `DocumentStore`, passing the namespace as an argument, + // and resolves a promise to obtain the chunk summary path based on the namespace. + const newDocumentStore = new DocumentStore(NAMESPACE, () => Promise.resolve({}), ); @@ -85,6 +121,9 @@ describe("DocumentStore", () => { expect(summaryPath).toBe(".duck/duck.json"); }); test("loads a summary file", async () => { + // Loads a summary file and returns a summary object containing two items in its + // `lookup` property. + const newDocumentStore = new DocumentStore(NAMESPACE, mockSummary, { pipelines: [], }); @@ -94,6 +133,10 @@ describe("DocumentStore", () => { expect(summary.lookup.length).toBe(2); }); test("loads all chunks", async () => { + // 1) creates a new instance of `DocumentStore`, 2) sets its chunk size to 2, and 3) + // loads all chunks using the `load()` method, after which it verifies that both the + // summary and output chunks contain two elements each. + const newDocumentStore = new DocumentStore(NAMESPACE, getFileMock, { pipelines: [], }); @@ -111,6 +154,10 @@ describe("DocumentStore", () => { expect(Object.keys(outputChunks).length).toBe(2); }); test("get file content by path", async () => { + // 1) creates a new instance of `DocumentStore`, 2) sets the chunk size to 2, and 3) + // retrieves the file at the specified path ("src/database.js") using the `getFile()` + // method. + const newDocumentStore = new DocumentStore(NAMESPACE, getFileMock, { pipelines: [], }); @@ -123,6 +170,11 @@ describe("DocumentStore", () => { expect(retrievedFile?.path).toBe(fileToGet); }); test("error is thrown if load isn't called before file access", async () => { + // * Creates a new instance of `DocumentStore` with a mock `getFile` method. + // * Calls the `getFile` method on the `DocumentStore` instance with the file path "src/index.js". + // * Expects an error to be thrown due to the absence of the `load` method call before + // accessing the file. + const newDocumentStore = new DocumentStore(NAMESPACE, getFileMock, { pipelines: [], }); @@ -132,6 +184,8 @@ describe("DocumentStore", () => { ).rejects.toThrow(Error); }); test("add a new file to the store", async () => { + // Adds a new file to a store and retrieves it back for verification. + const newDocumentStore = new DocumentStore(NAMESPACE, getFileMock, { pipelines: [], }); @@ -146,6 +200,10 @@ describe("DocumentStore", () => { expect(retrievedFile?.path).toBe(fileToGet); }); test("updating a non-existent file adds it to the store", async () => { + // 1) creates a new `DocumentStore` instance, 2) sets its `CHUNK_SIZE` to a specific + // value, and 3) updates an existing file using the `updateFile()` method, followed + // by retrieving the file using the `getFile()` method and verifying its path. + const newDocumentStore = new DocumentStore(NAMESPACE, getFileMock, { pipelines: [], }); @@ -160,6 +218,10 @@ describe("DocumentStore", () => { expect(retrievedFile?.path).toBe(fileToGet); }); test("update an existing file in the store", async () => { + // 1) creates a new instance of `DocumentStore`, 2) sets properties on that instance, + // and 3) updates an existing file in the store by providing the same path but different + // content description. + const newDocumentStore = new DocumentStore(NAMESPACE, getFileMock, { pipelines: [], }); @@ -178,6 +240,9 @@ describe("DocumentStore", () => { ); }); test("adding an existing file updates it in the store", async () => { + // Updates an existing file in a document store by adding new content and verifying + // if the updated file's description matches the expected value. + const newDocumentStore = new DocumentStore(NAMESPACE, getFileMock, { pipelines: [], }); diff --git a/types/IDocumentStore.d.ts b/types/IDocumentStore.d.ts index f5632e3..9de1139 100644 --- a/types/IDocumentStore.d.ts +++ b/types/IDocumentStore.d.ts @@ -1,5 +1,10 @@ import { Meta } from "./Meta"; +/** + * @description Defines a set of properties and methods for storing and managing + * documents. It includes the document chunk size, namespace, metadata, and a lookup + * array. Additionally, it provides a status object with summary and chunks properties. + */ export interface IDocumentStore { CHUNK_SIZE: number; namespace: string; diff --git a/types/Meta.d.ts b/types/Meta.d.ts index c935e20..2143c23 100644 --- a/types/Meta.d.ts +++ b/types/Meta.d.ts @@ -1,3 +1,7 @@ +/** + * @description Defines a set of properties that consist of a version, creation and + * update dates, and arbitrary data stored under key strings. + */ export interface Meta { version: string; created_at: Date; diff --git a/types/StructuredFile.d.ts b/types/StructuredFile.d.ts index 488eafb..6746bd8 100644 --- a/types/StructuredFile.d.ts +++ b/types/StructuredFile.d.ts @@ -1,3 +1,7 @@ +/** + * @description Defines a set of properties for a file, including its name, path, and + * contents. + */ export interface StructuredFile { name: string; path: string; diff --git a/types/Summary.d.ts b/types/Summary.d.ts index 63bb58c..8b74e32 100644 --- a/types/Summary.d.ts +++ b/types/Summary.d.ts @@ -1,5 +1,12 @@ import { Meta } from './Meta'; +/** + * @description Defines a set of properties: `meta`, `lookup`, and `chunks`. The + * `meta` property is an object with additional information about the summary, while + * the `lookup` property is an array of arrays representing the lookup tables for + * each chunk. The `chunks` property can optionally be defined as an array of strings, + * representing the chunks of data in the summary. + */ export interface Summary { meta: Meta; lookup: string[][]; From eead8d7743c7c2426220133ff71016e12ccde0ef Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 17:41:49 +0000 Subject: [PATCH 02/30] Added comments to 15 functions across 1 file --- .komment/00000.json | 178 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 132 +++++++++++++++---------------- 3 files changed, 157 insertions(+), 158 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 58400c7..c4d1e24 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 adding, retrieving, and updating files in a specified namespace. It provides a high-quality summary of the code by generating an object with `meta` and `lookup` properties, or a record of chunks extracted from the given content. The class implements various methods such as `load`, `addFile`, `updateFile`, and `outputSummary`. It also utilizes various high-level packages like `Passive`, `Ok`, and `Hello`.", + "description": "A `DocumentStore` class that manages adding, retrieving, and updating documents in a designated folder. It also generates high-quality documentation for the code and outputs chunks of code based on the given content. The class uses various internal arrays and objects to store chunk data, content, and other meta information.", "items": [ { - "id": "8258e45d-b951-4d89-6549-286960791363", + "id": "8839d365-1371-87a3-9345-7e5e9ef93a3e", "ancestors": [], - "description": "Provides a structured way of storing and retrieving code documentation, including files, chunks, and metadata. It offers features like loading high-quality summaries, updating metadata, and generating records of chunks.", + "description": "Organizes and stores structured files, facilitating high-quality documentation for code. It manages chunk loading, updates status, and provides methods for adding, updating, and retrieving files.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "Used to define the size of a chunk for storing content." + "description": "5." }, { "name": "namespace", "type_name": "string", - "description": "Required. It specifies the name or identifier of a specific area or domain that contains files or documents to be stored, managed, and retrieved by the Document Store." + "description": "Required, it represents the name or identifier of the document store instance, which can be used to reference the instance in code and other systems." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store version number, creation date, and update date of the document store instance." + "description": "Used to store metadata for the document store." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to specify a template for the `meta` object in the generated documentation." + "description": "Used to specify the structure of the metadata object that stores information about the document, such as version number, creation date, updated date, etc." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a list of file paths that are associated with chunks of code." + "description": "Used to store a list of substrings that correspond to files within a particular chunk." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store chunks of content from the original document." + "description": "Used to store the chunks of content from the document, which can be later accessed through the `loadChunk()` method." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store the actual files or content that will be stored in the document storage. It is initialized as an empty array when the class is created, and can be updated through methods such as `addFile()`." + "description": "Used to store an array of files that make up the content of the document." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to track the progress of loading documents" + "description": "Used to track the progress of loading chunks and metadata." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "36c48432-c42e-b388-f14c-92d323842cb2", + "id": "077ac00e-bb79-ec83-1c43-bec4aa0cdfb0", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Establishes instance variables and sets default values for them. It also validates inputs, such as ensuring that `namespace` and `getRemote` are provided, and initializes objects to store metadata and chunks of data.", + "description": "Sets up instance variables for namespace, getRemote method, chunk size, and various metadata properties, including version number, creation and update dates, and custom metadata templates.", "params": [ { "name": "namespace", "type_name": "string", "optional": false, - "description": "Required to initialize an instance of the class. It represents the name of the application or project for which the code is being generated.", + "description": "Required for initializing an instance of the class. It represents the name of the namespace where the remote data will be stored or retrieved from.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>", "optional": false, - "description": "Required for calling the remote data retrieval method.", + "description": "Required for the constructor to run successfully.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record", "optional": true, - "description": "Used to provide additional metadata for the document store.", + "description": "An optional field to provide additional metadata for the document.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const store = new DocumentStore('namespace', getRemote, { additionalMeta });\nstore.loadSummary();\n", - "description": "" + "code": "const documentStore = new DocumentStore(\"my-namespace\", getRemote);\n", + "description": "\nIn this example, \"my-namespace\" is the namespace of the document store, and `getRemote` is a 3rd party library or service that provides the functionality for generating high-quality documentation." }, "name": null, "location": { @@ -182,18 +182,18 @@ "docLength": 12 }, { - "id": "6fb22175-3e46-2589-da43-027dd7ced2e6", + "id": "2aec80f4-d9c9-76a9-b34b-dc8099550122", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Updates the `updated_at` metadata field of the `DocumentStore` instance by assigning the provided `Date` object directly to the `meta` object within the method body.", + "description": "Updates the `updated_at` metadata field of the `DocumentStore` instance with the provided `Date`.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date", - "description": "Used to update the metadata for the entity." + "description": "Used to update the metadata's updated_at field." } ], "returns": { @@ -202,7 +202,7 @@ }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote);\nstore.setUpdatedAt(new Date());\n", + "code": "const updatedAt = new Date();\ndocumentStore.setUpdatedAt(updatedAt);\n\n// documentStore.meta.updated_at will now be set to the value of updatedAt\n", "description": "" }, "name": "setUpdatedAt", @@ -221,11 +221,11 @@ "docLength": 7 }, { - "id": "524b45ed-f439-cbbd-2945-36418e6f57a8", + "id": "c9ded360-0f0d-81b4-2240-d3ac642cd74a", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Retrieves and updates the document store's summary metadata from the remote source, and assigns it to the local `summary` object.", + "description": "Retrieves and updates the summary information for the document store, including the chunk list and meta data, based on the remote summary information available.", "params": [], "returns": { "type_name": "Summary", @@ -233,7 +233,7 @@ }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore({\n getRemote: (...args) => {\n return ...; // The implementation of the third party library or service that provides the functionality for generating high-quality documentation.\n },\n integration: {\n id: 'xxx', // Integration ID\n name: 'xxx', // Integration name\n description: 'xxx' // Integration description\n }\n});\ndocumentStore.loadSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary();\n", "description": "" }, "name": "loadSummary", @@ -252,12 +252,12 @@ "docLength": 4 }, { - "id": "cefa0238-d667-0c9a-c74d-51d2189674fc", + "id": "d39e3b48-db95-ee95-cd4c-368bcd16a9ea", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363", - "524b45ed-f439-cbbd-2945-36418e6f57a8" + "8839d365-1371-87a3-9345-7e5e9ef93a3e", + "c9ded360-0f0d-81b4-2240-d3ac642cd74a" ], - "description": "* Iterates over the entries of an object `this.metaTemplate` using Object.entries()\n* For each entry, it checks if there is a corresponding key in the `summary.meta` object or default value is set by providing `value`\n* If a key-value pair is found in `summary.meta`, the value is assigned to `this.meta[key]`\n* Otherwise, the default value is assigned to `this.meta[key]`", + "description": "Assigns the value of `summary.meta![key]` to `this.meta[key]` if present, otherwise assigns the value of `value`.", "name": null, "location": { "start": 121, @@ -271,19 +271,19 @@ "docLength": null }, { - "id": "c7be8cc0-da04-44a1-b84d-1cc6818604ee", + "id": "12e2cf58-6dc7-16a5-de48-e1431eb974b4", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Of the `DocumentStore` class asynchronously loads the summary and chunks of a document, setting `status.summary` and `status.chunks` to `true` upon completion.", + "description": "Of the `DocumentStore` class loads chunks of data asynchronously based on the chunk indices stored in the `lookup` map.", "params": [], "returns": { "type_name": "void", - "description": "Indicative of a function that does not return any values." + "description": "Indicative of the fact that it does not return any value after execution." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore({getRemote, integration});\nawait docStore.load();\n// Use the loaded chunks\n", + "code": "const ds = new DocumentStore(getRemote, integration);\nds.load();\n", "description": "" }, "name": "load", @@ -302,27 +302,27 @@ "docLength": 3 }, { - "id": "b7e0d6eb-5701-95b4-eb44-546612cc02ce", + "id": "dc19c78a-3ffd-5ba7-6a4a-5ec1c80cbdf4", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Updates the metadata of an object by merging the existing metadata with additional metadata provided as an argument.", + "description": "Updates the metadata of an object by combining its current metadata with additional metadata provided as an argument.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record", - "description": "An object that contains additional metadata to be merged with the current metadata associated with the object." + "description": "Added to the existing metadata object 'meta' of the class." } ], "returns": { "type_name": "Recordstring", - "description": "An immutable object containing a combination of the existing metadata and the additional metadata passed as argument." + "description": "An augmented version of the current `meta` object with additional metadata provided as the argument `additionalMeta`." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.updateMetadata({ version: \"1.0\", created_at: new Date() });\n", + "code": "const store = new DocumentStore(getRemote, integration);\nstore.updateMetadata({ version: '1.0.0', created_at: new Date(), updated_at: new Date() });\n", "description": "" }, "name": "updateMetadata", @@ -338,27 +338,27 @@ "docLength": null }, { - "id": "8d35b66a-a865-37ac-334f-8048e891c3ce", + "id": "4fd2ca9d-57f0-51ac-5448-00512f45c3ac", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Of the `DocumentStore` class loads a chunk of data from a remote source and stores it in the object's internal state. If the chunk is already loaded, it returns `true`. Otherwise, it returns `false` after adding the chunk to the object's internal state.", + "description": "Of the `DocumentStore` class asynchronously loads a chunk of documents from the remote storage and adds them to the local content, updating the chunk cache and the content array.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number", - "description": "Used to identify the specific chunk being loaded." + "description": "Representing an index of a chunk to be loaded from a remote location." } ], "returns": { "type_name": "Promiseboolean", - "description": "True when the chunk is successfully loaded and False otherwise." + "description": "True if the chunk is loaded successfully, and false otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\nconst chunkLoadedSuccessfully = await docStore.loadChunk(chunkIndex);\nif (chunkLoadedSuccessfully) {\n // do something with the loaded chunk\n} else {\n // handle error\n}\n", + "code": "const myDocumentStore = new DocumentStore();\nmyDocumentStore.setGetRemote((remoteFile) => {\n return fetch(remoteFile).then((response) => response.json());\n});\nmyDocumentStore.loadChunk(0);\n", "description": "" }, "name": "loadChunk", @@ -377,27 +377,27 @@ "docLength": 11 }, { - "id": "2898a487-c3c7-248c-5a44-de9231dcee0a", + "id": "c1b03903-dc82-5a9d-f64a-cec32ddc0ab6", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Retrieves a file from a store based on its path, calculating the chunk it is located in and loading the chunk if necessary. It then returns the file within that chunk.", + "description": "In the `DocumentStore` class allows for retrieval of a file from a specified path, checking the file's existence and loading it from a chunk if necessary.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string", - "description": "Used to specify the file path being searched for." + "description": "Used to specify the path of the file to be retrieved." } ], "returns": { "type_name": "StructuredFile", - "description": "Either a file or null if it does not exist or cannot be accessed." + "description": "Either null or a reference to a file within a specified chunk if it exists." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\n\n// Load summary from remote storage\nawait documentStore.loadSummary();\n\n// Access a file\nconst file = await documentStore.getFile(\"path/to/file\");\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.getFile(\"some_path\");\n", "description": "" }, "name": "getFile", @@ -416,27 +416,27 @@ "docLength": 10 }, { - "id": "c103b9f0-df34-18a7-224f-d52375955310", + "id": "b548e744-81cb-a394-9141-6d955da84755", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "In the `DocumentStore` class adds a new path to the end of a lookup table if necessary, ensuring that the last subtable is not full and has enough space for additional entries.", + "description": "Updates the lookup subtable of a `DocumentStore` instance based on the provided path, appending to the end of the table if necessary.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string", - "description": "Used to add a new subtable to the existing lookup table." + "description": "Used to insert a new path into the lookup subtable." } ], "returns": { "type_name": "array", - "description": "An augmented list of path." + "description": "An array of strings containing the new path added to the end of the lookup subtable." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.addToEndOfLookup(\"path\");\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup(\"path/to/file\");\n", "description": "" }, "name": "addToEndOfLookup", @@ -455,27 +455,27 @@ "docLength": 6 }, { - "id": "9e87ab49-5442-7baa-1844-501f5833ef3d", + "id": "d0e95f05-36a1-8d9a-df49-d25e94c0e703", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Adds a file to the end of an array of files stored in chunks, creating a new chunk if necessary to avoid exceeding the maximum size.", + "description": "In the `DocumentStore` class adds files to the end of chunks based on file size and chunk capacity, creating new chunks when necessary.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Passed as an argument to the function." + "description": "Passed to the function for inclusion in the chunks." } ], "returns": { "type_name": "StructuredFile", - "description": "A new StructuredFile object containing the file added to the end of the chunks array." + "description": "A new StructuredFile object that contains the file added to the end of the chunks array." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks({\n \"filename\": \"README.md\",\n \"content\": \"# Welcome to my README\",\n});\n", + "code": "let documentStore = new DocumentStore(getRemote);\ndocumentStore.addToEndOfChunks(file);\n", "description": "" }, "name": "addToEndOfChunks", @@ -494,27 +494,27 @@ "docLength": 10 }, { - "id": "693fd591-8316-50be-c64b-bb105acfd0f2", + "id": "55c8ceb8-5c67-6a99-3b46-8406615e8303", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Of the `DocumentStore` class allows adding a new file to the document store, checking for file existence and proper loading order before updating the content and pushing the file to the end of the `content` array.", + "description": "Of `DocumentStore` allows adding a file to the collection of stored files. It checks if the file exists and if the `status.chunks` property is set before adding it to the end of the lookup table and chunks list. If the file already exists, it updates its information instead of adding it again.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Used to represent a file that can be added to the content array of the object." + "description": "Used to represent a file to be added to the content of the object." } ], "returns": { "type_name": "boolean", - "description": "True when the file is successfully added to the content and False otherwise." + "description": "True when a file is successfully added to the content and false otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore({getRemote, integration});\ndocStore.addFile(myFile);\n", + "code": "const store = new DocumentStore();\nstore.getRemote = (...args) => Promise>;\nstore.metaTemplate = { version: \"1.0.0\", created_at: Date.now() };\nstore.namespace = \"my-namespace\";\n// add a file to the store\nconst file: StructuredFile = { path: \"/path/to/file\" };\nstore.addFile(file);\n", "description": "" }, "name": "addFile", @@ -533,27 +533,27 @@ "docLength": 10 }, { - "id": "925f26c0-737d-48b9-ed4f-5ec85c0736c3", + "id": "98ca3ee0-f75f-c8a5-bb4d-e2018ea4ae61", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Of the `DocumentStore` class updates a file in the store by checking if it exists, loading the chunk if necessary, and storing the file in the chunk. It returns a boolean indicating whether the update was successful.", + "description": "Of the `DocumentStore` class updates a file in the store by checking if it exists, loading any necessary chunks, and storing the updated file in the appropriate chunk index.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Passed to update the file content in the Chunk." + "description": "Passed as an argument to the function for updating a file." } ], "returns": { "type_name": "Promiseboolean", - "description": "True if the file was updated successfully and false otherwise." + "description": "Ether true or false depending on whether the file was updated successfully or not." }, "usage": { "language": "typescript", - "code": "let documentStore = new DocumentStore();\ndocumentStore.getRemote = async (...args) => {\n // call to 3rd party library or service that provides functionality for generating high-quality documentation.\n};\n\nlet file = await documentStore.updateFile(path);\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\n\ndocumentStore.updateFile({path:'index.js', content:'new content'});\n", "description": "" }, "name": "updateFile", @@ -572,11 +572,11 @@ "docLength": 10 }, { - "id": "06441ba6-cadb-6eac-e546-287522d6b9e1", + "id": "d578c872-a362-1e96-cd4d-19d8753f131f", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Returns an object containing the `meta` and `lookup` properties of the current instance of the `DocumentStore` class.", + "description": "Returns an object containing the `meta` and `lookup` properties of the `DocumentStore` instance.", "params": [], "returns": { "type_name": "Summary", @@ -585,7 +585,7 @@ "usage": { "language": "typescript", "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputSummary();\n", - "description": "" + "description": "\nIn this example, we create a new instance of the `DocumentStore` class and pass in two parameters to its constructor: `getRemote` and `integration`. We then call the `outputSummary()` method on the newly created object, which returns a summary of the document store's metadata." }, "name": "outputSummary", "location": { @@ -603,20 +603,20 @@ "docLength": 6 }, { - "id": "1e592da2-d55e-d287-4142-08991fb64611", + "id": "290fe286-de31-a596-0d45-4bbb84d82c07", "ancestors": [ - "8258e45d-b951-4d89-6549-286960791363" + "8839d365-1371-87a3-9345-7e5e9ef93a3e" ], - "description": "Of `DocumentStore` takes the contents of the document and splits it into chunks, storing each chunk in a map with a unique key based on its position in the document.", + "description": "Generates and returns a record of chunks extracted from a document store's content, using a specified chunk size and keying scheme.", "params": [], "returns": { "type_name": "Recordstring", - "description": "An object that maps string keys to any values." + "description": "An object with keys that correspond to chunk paths and values that are chunks of the original content." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.outputChunks(); // returns a dictionary of chunk paths and corresponding content\n", - "description": "\nIn this example, the `outputChunks()` method of the `DocumentStore` class is called to return a dictionary of chunk paths and corresponding content. The `getRemote` and `integration` parameters are passed as arguments to the constructor of the `DocumentStore` class." + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputChunks();\n", + "description": "" }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index d64d3e4..d5242c2 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,10 +1,11 @@ { "meta": { "version": "1", - "updated_at": "2024-07-10T16:34:38.998Z", + "updated_at": "2024-07-10T17:41:43.599Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ - "c089e2e8-dd67-4bff-afef-c8f0f6b8a931" + "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", + "83f3455e-fd11-4539-9bc0-da663fa2c85d" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 6a9d2b1..38d5062 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Provides a structured way of storing and retrieving code documentation, - * including files, chunks, and metadata. It offers features like loading high-quality - * summaries, updating metadata, and generating records of chunks. + * @description Organizes and stores structured files, facilitating high-quality + * documentation for code. It manages chunk loading, updates status, and provides + * methods for adding, updating, and retrieving files. * * @implements {IDocumentStore} */ @@ -46,18 +46,19 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Establishes instance variables and sets default values for them. It - * also validates inputs, such as ensuring that `namespace` and `getRemote` are - * provided, and initializes objects to store metadata and chunks of data. + * @description Sets up instance variables for namespace, getRemote method, chunk + * size, and various metadata properties, including version number, creation and + * update dates, and custom metadata templates. * - * @param {string} namespace - Required to initialize an instance of the class. It - * represents the name of the application or project for which the code is being generated. + * @param {string} namespace - Required for initializing an instance of the class. + * It represents the name of the namespace where the remote data will be stored or + * retrieved from. * * @param {(...args: any[]) => Promise>} getRemote - Required for - * calling the remote data retrieval method. + * the constructor to run successfully. * - * @param {Record} additionalMeta - Used to provide additional metadata - * for the document store. + * @param {Record} additionalMeta - An optional field to provide additional + * metadata for the document. */ constructor( namespace: string, @@ -88,10 +89,9 @@ class DocumentStore implements IDocumentStore { /** * @description Updates the `updated_at` metadata field of the `DocumentStore` instance - * by assigning the provided `Date` object directly to the `meta` object within the - * method body. + * with the provided `Date`. * - * @param {Date} updated_at - Used to update the metadata for the entity. + * @param {Date} updated_at - Used to update the metadata's updated_at field. * * @returns {void} The result of updating the `meta` object's `updated_at` property * with the provided `Date`. @@ -101,8 +101,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Retrieves and updates the document store's summary metadata from the - * remote source, and assigns it to the local `summary` object. + * @description Retrieves and updates the summary information for the document store, + * including the chunk list and meta data, based on the remote summary information available. * * @returns {Summary} An object with properties `meta`, `lookup`, and `chunks`. */ @@ -133,11 +133,8 @@ 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]) => { - // * Iterates over the entries of an object `this.metaTemplate` using Object.entries() - // * For each entry, it checks if there is a corresponding key in the `summary.meta` - // object or default value is set by providing `value` - // * If a key-value pair is found in `summary.meta`, the value is assigned to `this.meta[key]` - // * Otherwise, the default value is assigned to `this.meta[key]` + // Assigns the value of `summary.meta![key]` to `this.meta[key]` if present, otherwise + // assigns the value of `value`. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -146,11 +143,10 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Of the `DocumentStore` class asynchronously loads the summary and - * chunks of a document, setting `status.summary` and `status.chunks` to `true` upon - * completion. + * @description Of the `DocumentStore` class loads chunks of data asynchronously based + * on the chunk indices stored in the `lookup` map. * - * @returns {void} Indicative of a function that does not return any values. + * @returns {void} Indicative of the fact that it does not return any value after execution. */ load = async () => { if (!this.status.summary) { @@ -173,14 +169,14 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of an object by merging the existing metadata + * @description Updates the metadata of an object by combining its current metadata * with additional metadata provided as an argument. * - * @param {Record} additionalMeta - An object that contains additional - * metadata to be merged with the current metadata associated with the object. + * @param {Record} additionalMeta - Added to the existing metadata object + * 'meta' of the class. * - * @returns {Recordstring} An immutable object containing a combination of the existing - * metadata and the additional metadata passed as argument. + * @returns {Recordstring} An augmented version of the current `meta` object with + * additional metadata provided as the argument `additionalMeta`. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -196,14 +192,14 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Of the `DocumentStore` class loads a chunk of data from a remote - * source and stores it in the object's internal state. If the chunk is already loaded, - * it returns `true`. Otherwise, it returns `false` after adding the chunk to the - * object's internal state. + * @description Of the `DocumentStore` class asynchronously loads a chunk of documents + * from the remote storage and adds them to the local content, updating the chunk + * cache and the content array. * - * @param {number} chunkIndex - Used to identify the specific chunk being loaded. + * @param {number} chunkIndex - Representing an index of a chunk to be loaded from a + * remote location. * - * @returns {Promiseboolean} True when the chunk is successfully loaded and False otherwise. + * @returns {Promiseboolean} True if the chunk is loaded successfully, and false otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -222,14 +218,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from a store based on its path, calculating the chunk - * it is located in and loading the chunk if necessary. It then returns the file - * within that chunk. + * @description In the `DocumentStore` class allows for retrieval of a file from a + * specified path, checking the file's existence and loading it from a chunk if necessary. * - * @param {string} path - Used to specify the file path being searched for. + * @param {string} path - Used to specify the path of the file to be retrieved. * - * @returns {StructuredFile} Either a file or null if it does not exist or cannot be - * accessed. + * @returns {StructuredFile} Either null or a reference to a file within a specified + * chunk if it exists. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -272,13 +267,13 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description In the `DocumentStore` class adds a new path to the end of a lookup - * table if necessary, ensuring that the last subtable is not full and has enough - * space for additional entries. + * @description Updates the lookup subtable of a `DocumentStore` instance based on + * the provided path, appending to the end of the table if necessary. * - * @param {string} path - Used to add a new subtable to the existing lookup table. + * @param {string} path - Used to insert a new path into the lookup subtable. * - * @returns {array} An augmented list of path. + * @returns {array} An array of strings containing the new path added to the end of + * the lookup subtable. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -292,12 +287,12 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the end of an array of files stored in chunks, creating - * a new chunk if necessary to avoid exceeding the maximum size. + * @description In the `DocumentStore` class adds files to the end of chunks based + * on file size and chunk capacity, creating new chunks when necessary. * - * @param {StructuredFile} file - Passed as an argument to the function. + * @param {StructuredFile} file - Passed to the function for inclusion in the chunks. * - * @returns {StructuredFile} A new StructuredFile object containing the file added + * @returns {StructuredFile} A new StructuredFile object that contains the file added * to the end of the chunks array. */ addToEndOfChunks = (file: StructuredFile) => { @@ -312,15 +307,16 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Of the `DocumentStore` class allows adding a new file to the document - * store, checking for file existence and proper loading order before updating the - * content and pushing the file to the end of the `content` array. + * @description Of `DocumentStore` allows adding a file to the collection of stored + * files. It checks if the file exists and if the `status.chunks` property is set + * before adding it to the end of the lookup table and chunks list. If the file already + * exists, it updates its information instead of adding it again. * - * @param {StructuredFile} file - Used to represent a file that can be added to the - * content array of the object. + * @param {StructuredFile} file - Used to represent a file to be added to the content + * of the object. * - * @returns {boolean} True when the file is successfully added to the content and - * False otherwise. + * @returns {boolean} True when a file is successfully added to the content and false + * otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -344,12 +340,14 @@ class DocumentStore implements IDocumentStore { }; /** * @description Of the `DocumentStore` class updates a file in the store by checking - * if it exists, loading the chunk if necessary, and storing the file in the chunk. - * It returns a boolean indicating whether the update was successful. + * if it exists, loading any necessary chunks, and storing the updated file in the + * appropriate chunk index. * - * @param {StructuredFile} file - Passed to update the file content in the Chunk. + * @param {StructuredFile} file - Passed as an argument to the function for updating + * a file. * - * @returns {Promiseboolean} True if the file was updated successfully and false otherwise. + * @returns {Promiseboolean} Ether true or false depending on whether the file was + * updated successfully or not. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -380,7 +378,7 @@ class DocumentStore implements IDocumentStore { }; /** * @description Returns an object containing the `meta` and `lookup` properties of - * the current instance of the `DocumentStore` class. + * the `DocumentStore` instance. * * @returns {Summary} An object containing two properties: `meta` and `lookup`. */ @@ -391,11 +389,11 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Of `DocumentStore` takes the contents of the document and splits it - * into chunks, storing each chunk in a map with a unique key based on its position - * in the document. + * @description Generates and returns a record of chunks extracted from a document + * store's content, using a specified chunk size and keying scheme. * - * @returns {Recordstring} An object that maps string keys to any values. + * @returns {Recordstring} An object with keys that correspond to chunk paths and + * values that are chunks of the original content. */ outputChunks(): Record { const outputs: Record = {}; From 9f03393d5ac2d737d5e492d7ad985e65120a159d Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:06:16 +0000 Subject: [PATCH 03/30] [tc]Added comments to 13 functions across 1 file --- src/index.ts | 151 ++++++++++++++++++++++----------------------------- 1 file changed, 65 insertions(+), 86 deletions(-) diff --git a/src/index.ts b/src/index.ts index 38d5062..8175a37 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,13 +19,6 @@ import { Summary } from "../types/Summary"; const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; -/** - * @description Organizes and stores structured files, facilitating high-quality - * documentation for code. It manages chunk loading, updates status, and provides - * methods for adding, updating, and retrieving files. - * - * @implements {IDocumentStore} - */ class DocumentStore implements IDocumentStore { CHUNK_SIZE: number; namespace: string; @@ -46,19 +39,18 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up instance variables for namespace, getRemote method, chunk - * size, and various metadata properties, including version number, creation and - * update dates, and custom metadata templates. + * @description Sets up the necessary variables and properties for an instance of a + * class, including the namespace, getRemote method, meta data, and other properties. * - * @param {string} namespace - Required for initializing an instance of the class. - * It represents the name of the namespace where the remote data will be stored or - * retrieved from. + * @param {string} namespace - name of the document store or API endpoint where the + * content will be stored, and it is required to initialize the class. * - * @param {(...args: any[]) => Promise>} getRemote - Required for - * the constructor to run successfully. + * @param {(...args: any[]) => Promise>} getRemote - Promise of a + * remote data source that provides the documentation content. * - * @param {Record} additionalMeta - An optional field to provide additional - * metadata for the document. + * @param {Record} additionalMeta - metadata for the documentation + * generation, including the version number, creation and update dates, and other + * customizable fields. */ constructor( namespace: string, @@ -88,23 +80,20 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of the `DocumentStore` instance - * with the provided `Date`. - * - * @param {Date} updated_at - Used to update the metadata's updated_at field. + * @description Updates the `updated_at` metadata field with the provided `updated_at` + * value. * - * @returns {void} The result of updating the `meta` object's `updated_at` property - * with the provided `Date`. + * @param {Date} updated_at - date and time when the document was last updated, and + * it is assigned to the `meta.updated_at` property of the document to maintain its + * historical records. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates the summary information for the document store, - * including the chunk list and meta data, based on the remote summary information available. - * - * @returns {Summary} An object with properties `meta`, `lookup`, and `chunks`. + * @description Retrieves a Summary object from the remote Document Store, updates + * the local metadata and chunk information, and sets the status to "summary". */ loadSummary = async () => { let summary: Summary = { @@ -133,9 +122,6 @@ 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 the value of `summary.meta![key]` to `this.meta[key]` if present, otherwise - // assigns the value of `value`. - this.meta[key] = summary?.meta?.[key] ?? value; }); this.lookup = summary.lookup || []; @@ -143,10 +129,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Of the `DocumentStore` class loads chunks of data asynchronously based - * on the chunk indices stored in the `lookup` map. - * - * @returns {void} Indicative of the fact that it does not return any value after execution. + * @description Loads chunks of data if they are not already loaded, and sets the + * `chunks` status to `true`. */ load = async () => { if (!this.status.summary) { @@ -169,14 +153,12 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of an object by combining its current metadata - * with additional metadata provided as an argument. - * - * @param {Record} additionalMeta - Added to the existing metadata object - * 'meta' of the class. + * @description Updates the metadata of an object by combining its own metadata and + * any additional metadata provided as an argument. * - * @returns {Recordstring} An augmented version of the current `meta` object with - * additional metadata provided as the argument `additionalMeta`. + * @param {Record} additionalMeta - additional metadata to be merged + * with the existing metadata of the object, which is then assigned to the `meta` + * property of the object. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -192,14 +174,15 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Of the `DocumentStore` class asynchronously loads a chunk of documents - * from the remote storage and adds them to the local content, updating the chunk - * cache and the content array. + * @description Loads a specified chunk from a remote source and adds it to the + * internal content array if successful, returning `true`. * - * @param {number} chunkIndex - Representing an index of a chunk to be loaded from a - * remote location. + * @param {number} chunkIndex - 0-based index of the chunk being processed, which is + * used to determine whether the chunk has been loaded and to update the internal + * cache of chunks. * - * @returns {Promiseboolean} True if the chunk is loaded successfully, and false otherwise. + * @returns {Promise} a boolean value indicating whether the chunk was + * successfully loaded or not. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -218,13 +201,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description In the `DocumentStore` class allows for retrieval of a file from a - * specified path, checking the file's existence and loading it from a chunk if necessary. + * @description Retrieves a file from a summary and chunk index, checks if it's loaded, + * and returns the file or null if not found. * - * @param {string} path - Used to specify the path of the file to be retrieved. + * @param {string} path - path of a file within the structured files, and it is used + * to identify the chunk and file index within that chunk where the file resides. * - * @returns {StructuredFile} Either null or a reference to a file within a specified - * chunk if it exists. + * @returns {Promise} a `StructuredFile` object or `null` if + * the file is not found. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -267,13 +251,11 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Updates the lookup subtable of a `DocumentStore` instance based on - * the provided path, appending to the end of the table if necessary. + * @description Adds a new path to the end of the current lookup subtable or creates + * a new subtable if the last one is full. * - * @param {string} path - Used to insert a new path into the lookup subtable. - * - * @returns {array} An array of strings containing the new path added to the end of - * the lookup subtable. + * @param {string} path - subtable index or position where the given path should be + * added to the lookup table. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -287,13 +269,11 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description In the `DocumentStore` class adds files to the end of chunks based - * on file size and chunk capacity, creating new chunks when necessary. - * - * @param {StructuredFile} file - Passed to the function for inclusion in the chunks. + * @description Adds a file to either the beginning or end of an array of chunks based + * on if the last subtable is full or not. * - * @returns {StructuredFile} A new StructuredFile object that contains the file added - * to the end of the chunks array. + * @param {StructuredFile} file - file that needs to be added to the current chunk, + * and it is used to update the chunks array accordingly. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -307,16 +287,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Of `DocumentStore` allows adding a file to the collection of stored - * files. It checks if the file exists and if the `status.chunks` property is set - * before adding it to the end of the lookup table and chunks list. If the file already - * exists, it updates its information instead of adding it again. + * @description Adds a file to the end of a Structured File's chunks and content if + * the file exists, otherwise it throws an error. * - * @param {StructuredFile} file - Used to represent a file to be added to the content - * of the object. + * @param {StructuredFile} file - file to be added to the `StructuredFile` instance's + * content, and it is used to check if the file exists at the given path before adding + * it to the instance's content. * - * @returns {boolean} True when a file is successfully added to the content and false - * otherwise. + * @returns {boolean} a boolean value indicating whether the file was successfully + * added to the StructuredFile instance. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -339,15 +318,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Of the `DocumentStore` class updates a file in the store by checking - * if it exists, loading any necessary chunks, and storing the updated file in the - * appropriate chunk index. + * @description Updates a file in a StructuredFile object by checking if it exists, + * loading it if necessary, and storing it in the appropriate chunk and file index + * within that chunk. * - * @param {StructuredFile} file - Passed as an argument to the function for updating - * a file. + * @param {StructuredFile} file - file that is being updated or added to the + * StructuredFile object's content, and it must be a valid path for the file. * - * @returns {Promiseboolean} Ether true or false depending on whether the file was - * updated successfully or not. + * @returns {Promise} a `Promise` that resolves to a boolean value indicating + * whether the file was successfully updated. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -377,10 +356,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing the `meta` and `lookup` properties of - * the `DocumentStore` instance. + * @description Generates a summary of an object's properties, including the object's + * `meta` and `lookup` properties. * - * @returns {Summary} An object containing two properties: `meta` and `lookup`. + * @returns {Summary} an object containing `meta` and `lookup` properties. */ outputSummary(): Summary { return { @@ -389,11 +368,11 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Generates and returns a record of chunks extracted from a document - * store's content, using a specified chunk size and keying scheme. + * @description Generates a record of chunks from a given content by slicing it into + * smaller parts and assigning each part to a unique key in the function's output. * - * @returns {Recordstring} An object with keys that correspond to chunk paths and - * values that are chunks of the original content. + * @returns {Record} a record of chunks extracted from the input content, + * each with a unique key and corresponding chunk of content. */ outputChunks(): Record { const outputs: Record = {}; From 2d33a0a702ced5d29283a6c014e51ef58ab5d68e Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:08:00 +0000 Subject: [PATCH 04/30] [tc]Added comments to 13 functions across 1 file --- src/index.ts | 130 ++++++++++++++++++++++++++------------------------- 1 file changed, 67 insertions(+), 63 deletions(-) diff --git a/src/index.ts b/src/index.ts index 8175a37..1a91e8c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -39,18 +39,19 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up the necessary variables and properties for an instance of a - * class, including the namespace, getRemote method, meta data, and other properties. + * @description Sets up the necessary objects and properties for the DocuStore class, + * including the namespace, getRemote method, and metadata. * - * @param {string} namespace - name of the document store or API endpoint where the - * content will be stored, and it is required to initialize the class. + * @param {string} namespace - namespace for which the code generator is creating + * documentation, and it is required to be provided. * - * @param {(...args: any[]) => Promise>} getRemote - Promise of a - * remote data source that provides the documentation content. + * @param {(...args: any[]) => Promise>} getRemote - method that + * returns a Promise of a Record containing the document's data. * - * @param {Record} additionalMeta - metadata for the documentation - * generation, including the version number, creation and update dates, and other - * customizable fields. + * @param {Record} additionalMeta - metadata that can be added to the + * document store, such as version number, created and updated at timestamps, and + * other custom data, which can be used to modify or extend the default behavior of + * the function. */ constructor( namespace: string, @@ -80,20 +81,20 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field with the provided `updated_at` - * value. + * @description Sets the `updated_at` metadata for an instance, updating its value + * to the given `updated_at` date. * - * @param {Date} updated_at - date and time when the document was last updated, and - * it is assigned to the `meta.updated_at` property of the document to maintain its - * historical records. + * @param {Date} updated_at - timestamp when the record was last updated, and it is + * assigned to the `meta.updated_at` property within the function to maintain an + * updated version of the record's metadata. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves a Summary object from the remote Document Store, updates - * the local metadata and chunk information, and sets the status to "summary". + * @description Retrieves remote documentation data and updates local metadata, chunk + * information, and lookup table. */ loadSummary = async () => { let summary: Summary = { @@ -129,8 +130,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Loads chunks of data if they are not already loaded, and sets the - * `chunks` status to `true`. + * @description Loads chunks of data from a database based on their indices, marking + * them as loaded in the status object. */ load = async () => { if (!this.status.summary) { @@ -153,12 +154,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of an object by combining its own metadata and - * any additional metadata provided as an argument. + * @description Updates the `meta` property of an object by combining it with the + * provided `additionalMeta` property. * - * @param {Record} additionalMeta - additional metadata to be merged - * with the existing metadata of the object, which is then assigned to the `meta` - * property of the object. + * @param {Record} additionalMeta - metadata to be added to the current + * instance of `Record`. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -174,15 +174,16 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Loads a specified chunk from a remote source and adds it to the - * internal content array if successful, returning `true`. + * @description Retrieves a specific chunk from a remote source and adds it to the + * current content array if not already loaded, returning a boolean indicating + * successful loading. * - * @param {number} chunkIndex - 0-based index of the chunk being processed, which is - * used to determine whether the chunk has been loaded and to update the internal - * cache of chunks. + * @param {number} chunkIndex - 0-based index of a chunk within the total number of + * chunks in the StructuredFile collection, and is used to determine whether the chunk + * has already been loaded or not. * - * @returns {Promise} a boolean value indicating whether the chunk was - * successfully loaded or not. + * @returns {Promise} a `Promise` that resolves to `true` if the chunk was + * successfully loaded, or `false` otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -201,14 +202,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from a summary and chunk index, checks if it's loaded, - * and returns the file or null if not found. + * @description Retrieves a file from a summary, checks if it is in the correct chunk, + * and returns the file data if found, otherwise returns null. * - * @param {string} path - path of a file within the structured files, and it is used - * to identify the chunk and file index within that chunk where the file resides. + * @param {string} path - file path that is being searched for within the current + * chunk, and it is used to calculate the file's index within the chunk and return + * the corresponding file data. * - * @returns {Promise} a `StructuredFile` object or `null` if - * the file is not found. + * @returns {Promise} a `StructuredFile` object representing + * the file or null if it's not found. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -251,11 +253,12 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of the current lookup subtable or creates - * a new subtable if the last one is full. + * @description Updates the `lookup` subtable, adding a new entry to the last position + * if the last entry is full or reaching the maximum size, or adding a new entry to + * the last position of the previous entry otherwise. * - * @param {string} path - subtable index or position where the given path should be - * added to the lookup table. + * @param {string} path - path to be looked up in the subtable, and determines whether + * a new subtable needs to be created or an existing one expanded. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -269,11 +272,11 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to either the beginning or end of an array of chunks based - * on if the last subtable is full or not. + * @description Updates a structured file's chunks based on its size, either adding + * a new chunk if the last one is empty or appending to it if not. * - * @param {StructuredFile} file - file that needs to be added to the current chunk, - * and it is used to update the chunks array accordingly. + * @param {StructuredFile} file - file that is being processed and added to the + * `chunks` array in the structured file system. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -287,15 +290,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the end of a Structured File's chunks and content if - * the file exists, otherwise it throws an error. + * @description Adds a file to a Structured File instance's content and chunks, + * verifying that the file exists and that it has not been added previously. * - * @param {StructuredFile} file - file to be added to the `StructuredFile` instance's - * content, and it is used to check if the file exists at the given path before adding - * it to the instance's content. + * @param {StructuredFile} file - file to be added to the StructuredFile object's + * content, and it is used to check if the file exists and to update its metadata in + * the object. * * @returns {boolean} a boolean value indicating whether the file was successfully - * added to the StructuredFile instance. + * added to the list of files. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -318,15 +321,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in a StructuredFile object by checking if it exists, - * loading it if necessary, and storing it in the appropriate chunk and file index - * within that chunk. + * @description Updates a file in a structured file, checking if it already exists, + * loading it if necessary, and storing it in the appropriate chunk and file index positions. * - * @param {StructuredFile} file - file that is being updated or added to the - * StructuredFile object's content, and it must be a valid path for the file. + * @param {StructuredFile} file - file to be added, updated or retrieved, and it is + * used to verify its existence and + * check if it has already been loaded before updating the structured file's content. * - * @returns {Promise} a `Promise` that resolves to a boolean value indicating - * whether the file was successfully updated. + * @returns {Promise} a boolean value indicating whether the specified file + * was successfully added to the structured file. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -356,8 +359,8 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Generates a summary of an object's properties, including the object's - * `meta` and `lookup` properties. + * @description Generates a summary object containing the `meta` and `lookup` properties + * based on the internal state of the calling instance. * * @returns {Summary} an object containing `meta` and `lookup` properties. */ @@ -368,11 +371,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Generates a record of chunks from a given content by slicing it into - * smaller parts and assigning each part to a unique key in the function's output. + * @description Takes a `content` array and returns an object with keys that correspond + * to file paths for chunks of the content, each chunk being a slice of the original + * array. * - * @returns {Record} a record of chunks extracted from the input content, - * each with a unique key and corresponding chunk of content. + * @returns {Record} a Record containing Key-Value pairs + * of chunks from the given content. */ outputChunks(): Record { const outputs: Record = {}; From 61db63e952d85ecf4d0f70332ea0c5bd689840f0 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:10:42 +0000 Subject: [PATCH 05/30] Added comments to 15 functions across 1 file --- .komment/00000.json | 178 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 153 ++++++++++++++++++++---------------- 3 files changed, 176 insertions(+), 160 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index c4d1e24..5cac5e1 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 adding, retrieving, and updating documents in a designated folder. It also generates high-quality documentation for the code and outputs chunks of code based on the given content. The class uses various internal arrays and objects to store chunk data, content, and other meta information.", + "description": "A `DocumentStore` class that manages adding, retrieving, and updating documents in a specified namespace. It accepts a 3rd-party library or service for generating high-quality documentation. The class has various methods for loading, updating, and looking up files within the store, as well as producing summaries of the contents.", "items": [ { - "id": "8839d365-1371-87a3-9345-7e5e9ef93a3e", + "id": "c0dabdde-f75c-8fa4-f348-b8920f6cad6c", "ancestors": [], - "description": "Organizes and stores structured files, facilitating high-quality documentation for code. It manages chunk loading, updates status, and provides methods for adding, updating, and retrieving files.", + "description": "Organizes and stores code documentation for efficient retrieval", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "5." + "description": "25 by default, which represents the number of files that can be stored in each chunk." }, { "name": "namespace", "type_name": "string", - "description": "Required, it represents the name or identifier of the document store instance, which can be used to reference the instance in code and other systems." + "description": "Used to specify the name or identifier of the code documentation project or module, which helps in organizing and managing the files and contents within it." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata for the document store." + "description": "Used to store additional metadata about the document, such as its version number, creation date, and last update date}." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to specify the structure of the metadata object that stores information about the document, such as version number, creation date, updated date, etc." + "description": "Used for initializing the meta data of the document store with default values." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a list of substrings that correspond to files within a particular chunk." + "description": "Used to store a list of sub-arrays, where each sub-array represents a chunk of files. It acts as an index for retrieving specific chunks or files within the overall sequence of chunks being loaded." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store the chunks of content from the document, which can be later accessed through the `loadChunk()` method." + "description": "Used to store chunks of code in a specific structure, allowing for efficient retrieval and manipulation of files within those chunks." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store an array of files that make up the content of the document." + "description": "Used to store a sequence of files organized into chunks based on a chunk size and keying system." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to track the progress of loading chunks and metadata." + "description": "Used to store the status of the code documentation generation." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "077ac00e-bb79-ec83-1c43-bec4aa0cdfb0", + "id": "8e850073-ae98-2b8e-4a46-959cf6f75417", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Sets up instance variables for namespace, getRemote method, chunk size, and various metadata properties, including version number, creation and update dates, and custom metadata templates.", + "description": "Establishes instance variables for `namespace`, `getRemote`, `CHUNK_SIZE`, and other metadata, and initializes various internal arrays and objects.", "params": [ { "name": "namespace", "type_name": "string", "optional": false, - "description": "Required for initializing an instance of the class. It represents the name of the namespace where the remote data will be stored or retrieved from.", + "description": "Required for creating a new chunking client. It represents the root namespace of the document store where the chunks will be stored.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>", "optional": false, - "description": "Required for the constructor to run successfully.", + "description": "Required to be a function that retrieves data from a remote source.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record", "optional": true, - "description": "An optional field to provide additional metadata for the document.", + "description": "An optional field to store additional metadata about the document.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\"my-namespace\", getRemote);\n", - "description": "\nIn this example, \"my-namespace\" is the namespace of the document store, and `getRemote` is a 3rd party library or service that provides the functionality for generating high-quality documentation." + "code": "// Initialize DocumentStore instance with namespace and getRemote method\nconst store = new DocumentStore(\"my_namespace\", async (args) => {\n // Use args to retrieve content from a remote service or provider\n return { /* response from the remote service */ };\n});\n\n// Set updated_at value for meta data of the DocumentStore instance\nstore.setUpdatedAt(new Date());\n\n// Load summary from remote service and update local meta data\nawait store.loadSummary();\n", + "description": "" }, "name": null, "location": { @@ -182,18 +182,18 @@ "docLength": 12 }, { - "id": "2aec80f4-d9c9-76a9-b34b-dc8099550122", + "id": "f2f3f4b9-e401-9e92-1948-606b0c508ec7", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Updates the `updated_at` metadata field of the `DocumentStore` instance with the provided `Date`.", + "description": "Updates the `updated_at` metadata field of the `DocumentStore` instance by passing the provided `Date` object as an argument.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date", - "description": "Used to update the metadata's updated_at field." + "description": "Assigned to the `meta.updated_at` property of the current instance." } ], "returns": { @@ -202,7 +202,7 @@ }, "usage": { "language": "typescript", - "code": "const updatedAt = new Date();\ndocumentStore.setUpdatedAt(updatedAt);\n\n// documentStore.meta.updated_at will now be set to the value of updatedAt\n", + "code": "const documentStore = new DocumentStore();\n documentStore.getRemote(async () => {\n return fetch('https://some-url.com');\n });\n const updatedAt = Date.now()\n documentStore.setUpdatedAt(updatedAt);\n\n", "description": "" }, "name": "setUpdatedAt", @@ -221,15 +221,15 @@ "docLength": 7 }, { - "id": "c9ded360-0f0d-81b4-2240-d3ac642cd74a", + "id": "dadbd7ee-8c27-3399-404d-70ad44d8cb34", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Retrieves and updates the summary information for the document store, including the chunk list and meta data, based on the remote summary information available.", + "description": "Retrieves and updates the summary of documents stored in the Document Store, including meta information and chunk-level data.", "params": [], "returns": { "type_name": "Summary", - "description": "An object with properties `meta`, `lookup`, and `chunks`." + "description": "An object containing various metadata and chunk information." }, "usage": { "language": "typescript", @@ -252,12 +252,12 @@ "docLength": 4 }, { - "id": "d39e3b48-db95-ee95-cd4c-368bcd16a9ea", + "id": "041ff388-9e40-eb8b-3f42-bbb0e69eb184", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e", - "c9ded360-0f0d-81b4-2240-d3ac642cd74a" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c", + "dadbd7ee-8c27-3399-404d-70ad44d8cb34" ], - "description": "Assigns the value of `summary.meta![key]` to `this.meta[key]` if present, otherwise assigns the value of `value`.", + "description": "Updates an object `this.meta` by key-value pairing, \nusing a callback function to determine the value for each key.", "name": null, "location": { "start": 121, @@ -271,19 +271,19 @@ "docLength": null }, { - "id": "12e2cf58-6dc7-16a5-de48-e1431eb974b4", + "id": "69ce1aac-a362-7d94-e041-0698a87783cc", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Of the `DocumentStore` class loads chunks of data asynchronously based on the chunk indices stored in the `lookup` map.", + "description": "Of the `DocumentStore` class asynchronously loads chunks of data from a summary and updates the `status` property with the loaded chunks.", "params": [], "returns": { "type_name": "void", - "description": "Indicative of the fact that it does not return any value after execution." + "description": "Indicative of the function finishing its task without any return value." }, "usage": { "language": "typescript", - "code": "const ds = new DocumentStore(getRemote, integration);\nds.load();\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.load();\n", "description": "" }, "name": "load", @@ -302,27 +302,27 @@ "docLength": 3 }, { - "id": "dc19c78a-3ffd-5ba7-6a4a-5ec1c80cbdf4", + "id": "d9caa952-6738-e884-a849-0bd7be1fd249", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Updates the metadata of an object by combining its current metadata with additional metadata provided as an argument.", + "description": "Of the `DocumentStore` class updates the metadata of an object by merging the original metadata with additional metadata provided as an argument.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record", - "description": "Added to the existing metadata object 'meta' of the class." + "description": "Used to add or update additional metadata for the current instance of the class." } ], "returns": { "type_name": "Recordstring", - "description": "An augmented version of the current `meta` object with additional metadata provided as the argument `additionalMeta`." + "description": "An augmented metadata object combining the existing metadata and additional metadata provided as argument." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.updateMetadata({ version: '1.0.0', created_at: new Date(), updated_at: new Date() });\n", + "code": "let store = new DocumentStore(getRemote, integration);\nstore.updateMetadata({ version: '1.0', created_at: new Date() });\n", "description": "" }, "name": "updateMetadata", @@ -338,27 +338,27 @@ "docLength": null }, { - "id": "4fd2ca9d-57f0-51ac-5448-00512f45c3ac", + "id": "0fc40181-0794-1da7-694f-8b54d9afb3ea", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Of the `DocumentStore` class asynchronously loads a chunk of documents from the remote storage and adds them to the local content, updating the chunk cache and the content array.", + "description": "Of the `DocumentStore` class asyncously loads a chunk of data from a remote source and concatenaates it with the rest of the content, storing it in the `chunks` property. If the chunk is already loaded, the method returns `true`.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number", - "description": "Representing an index of a chunk to be loaded from a remote location." + "description": "Representing an index of a chunk to be loaded from the remote source." } ], "returns": { "type_name": "Promiseboolean", - "description": "True if the chunk is loaded successfully, and false otherwise." + "description": "True if the chunk was successfully loaded and false otherwise." }, "usage": { "language": "typescript", - "code": "const myDocumentStore = new DocumentStore();\nmyDocumentStore.setGetRemote((remoteFile) => {\n return fetch(remoteFile).then((response) => response.json());\n});\nmyDocumentStore.loadChunk(0);\n", + "code": "// create a new instance of the DocumentStore class\nconst store = new DocumentStore();\n\n// set up the getRemote function, which is responsible for fetching data from a remote server\nstore.getRemote = async (url) => {\n // make an API request to the specified URL and return the response\n const response = await fetch(url);\n return response.json();\n};\n\n// set up the integration object, which provides information about the integration of the code documentation\nstore.integration = {\n name: 'My Integration',\n version: '1.0.0'\n}\n\n// initialize the DocumentStore instance with the necessary metadata and internal arrays\nawait store.init();\n\n// load a chunk of data from a remote server\nconst loadedChunk = await store.loadChunk(0);\n", "description": "" }, "name": "loadChunk", @@ -377,28 +377,28 @@ "docLength": 11 }, { - "id": "c1b03903-dc82-5a9d-f64a-cec32ddc0ab6", + "id": "05d1da31-616d-6980-b74e-a78c75f152fa", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "In the `DocumentStore` class allows for retrieval of a file from a specified path, checking the file's existence and loading it from a chunk if necessary.", + "description": "Of the `DocumentStore` class retrieves a file from a chunk based on its path. It first checks if the summary has been loaded, then calculates the chunk and file indices, and finally returns the file data if found, otherwise returns null.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string", - "description": "Used to specify the path of the file to be retrieved." + "description": "Passed as input to the function. It represents the path of the file being searched for." } ], "returns": { "type_name": "StructuredFile", - "description": "Either null or a reference to a file within a specified chunk if it exists." + "description": "Either a loaded file or null if the file is not found or has not been loaded yet." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.getFile(\"some_path\");\n", - "description": "" + "code": "const store = new DocumentStore(getRemote, integration);\nstore.getFile('path/to/file').then((file) => {\n // do something with the file\n});\n", + "description": "\nThis is a basic example on how to use the `getFile` function of the `DocumentStore`. It shows the general syntax for calling the function and using the resulting promise. The actual implementation of the function will depend on the specific requirements of the class." }, "name": "getFile", "location": { @@ -416,27 +416,27 @@ "docLength": 10 }, { - "id": "b548e744-81cb-a394-9141-6d955da84755", + "id": "4aa87d8b-7f44-068a-724e-4f9564e16348", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Updates the lookup subtable of a `DocumentStore` instance based on the provided path, appending to the end of the table if necessary.", + "description": "Updates the `lookup` subtable of a `DocumentStore` instance based on the provided path, inserting new elements or expanding an existing one if necessary.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string", - "description": "Used to insert a new path into the lookup subtable." + "description": "Used to add new entries to the lookup subtable." } ], "returns": { - "type_name": "array", - "description": "An array of strings containing the new path added to the end of the lookup subtable." + "type_name": "string", + "description": "A new subtable added to the existing lookup table or the path if no new subtable is created." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup(\"path/to/file\");\n", + "code": "// The class instance is created and passed as a parameter in the constructor function\nconst store = new DocumentStore(getRemote, integration);\n\n// Adding to the end of lookup array\nstore.addToEndOfLookup('path');\n", "description": "" }, "name": "addToEndOfLookup", @@ -455,27 +455,27 @@ "docLength": 6 }, { - "id": "d0e95f05-36a1-8d9a-df49-d25e94c0e703", + "id": "a72afd67-cf02-bfae-734e-1b905ef8b91b", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "In the `DocumentStore` class adds files to the end of chunks based on file size and chunk capacity, creating new chunks when necessary.", + "description": "In the `DocumentStore` class appends files to an array of chunks based on the file's size and the current length of the chunks array.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Passed to the function for inclusion in the chunks." + "description": "Passed as an argument to the function." } ], "returns": { "type_name": "StructuredFile", - "description": "A new StructuredFile object that contains the file added to the end of the chunks array." + "description": "A new chunk containing the given file if the last subtable is full, or the existing chunk with the added file otherwise." }, "usage": { "language": "typescript", - "code": "let documentStore = new DocumentStore(getRemote);\ndocumentStore.addToEndOfChunks(file);\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks({ name: 'example_file', size: 20 });\ndocumentStore.addToEndOfChunks({ name: 'example_file_2', size: 10 });\n", "description": "" }, "name": "addToEndOfChunks", @@ -494,27 +494,27 @@ "docLength": 10 }, { - "id": "55c8ceb8-5c67-6a99-3b46-8406615e8303", + "id": "f9570bb7-5b07-2783-b342-e48e5444b1ab", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Of `DocumentStore` allows adding a file to the collection of stored files. It checks if the file exists and if the `status.chunks` property is set before adding it to the end of the lookup table and chunks list. If the file already exists, it updates its information instead of adding it again.", + "description": "Of the `DocumentStore` class allows adding a file to the document store if certain conditions are met, including that the file exists and has not been loaded before. If successful, the method updates the file's metadata and adds it to the end of the lookup and chunks lists.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Used to represent a file to be added to the content of the object." + "description": "Passed as an object containing file path, and other related information." } ], "returns": { "type_name": "boolean", - "description": "True when a file is successfully added to the content and false otherwise." + "description": "`true` if the file was successfully added to the lookups and chunks, otherwise it returns `false`." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore();\nstore.getRemote = (...args) => Promise>;\nstore.metaTemplate = { version: \"1.0.0\", created_at: Date.now() };\nstore.namespace = \"my-namespace\";\n// add a file to the store\nconst file: StructuredFile = { path: \"/path/to/file\" };\nstore.addFile(file);\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addFile({ path: \"path/to/file\", content: \"file contents\" });\nconst fileExists = docStore.fileExists(\"path/to/file\"); // true or false\nconst fileContent = docStore.updateFile(\"path/to/file\", { content: \"new file contents\" });\n", "description": "" }, "name": "addFile", @@ -533,27 +533,27 @@ "docLength": 10 }, { - "id": "98ca3ee0-f75f-c8a5-bb4d-e2018ea4ae61", + "id": "12bfdc86-7a4d-669e-9243-ca3b92a1fb4f", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Of the `DocumentStore` class updates a file in the store by checking if it exists, loading any necessary chunks, and storing the updated file in the appropriate chunk index.", + "description": "Of the `DocumentStore` class updates a file in the store by checking if it exists, loading the chunk if necessary, and adding or updating the file in the chunk.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Passed as an argument to the function for updating a file." + "description": "Passed as an argument to the function." } ], "returns": { "type_name": "Promiseboolean", - "description": "Ether true or false depending on whether the file was updated successfully or not." + "description": "Whether the file was successfully updated or not." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\n\ndocumentStore.updateFile({path:'index.js', content:'new content'});\n", + "code": "const updateFile = async (file: StructuredFile): Promise => {\n if (!this.status.chunks)\n throw Error(\"Must call .load before updating files\");\n\n if (!file) return false;\n\n const chunkIndex = this.getChunkFileIsIn(file.path);\n if (chunkIndex === -1) {\n try {\n await this.loadChunk(chunkIndex);\n this.addFile(file);\n this.content[chunkIndex * this.CHUNK_SIZE + fileIndexInChunk] = file;\n return true;\n } catch (error) {\n console.error(error);\n return false;\n }\n }\n}\n", "description": "" }, "name": "updateFile", @@ -572,9 +572,9 @@ "docLength": 10 }, { - "id": "d578c872-a362-1e96-cd4d-19d8753f131f", + "id": "24cc185f-1cd6-92ba-f141-c66eaf290e44", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], "description": "Returns an object containing the `meta` and `lookup` properties of the `DocumentStore` instance.", "params": [], @@ -585,7 +585,7 @@ "usage": { "language": "typescript", "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputSummary();\n", - "description": "\nIn this example, we create a new instance of the `DocumentStore` class and pass in two parameters to its constructor: `getRemote` and `integration`. We then call the `outputSummary()` method on the newly created object, which returns a summary of the document store's metadata." + "description": "" }, "name": "outputSummary", "location": { @@ -603,19 +603,19 @@ "docLength": 6 }, { - "id": "290fe286-de31-a596-0d45-4bbb84d82c07", + "id": "5caa9c5b-1342-fe91-6d4a-d670ff348aee", "ancestors": [ - "8839d365-1371-87a3-9345-7e5e9ef93a3e" + "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" ], - "description": "Generates and returns a record of chunks extracted from a document store's content, using a specified chunk size and keying scheme.", + "description": "Of the `DocumentStore` class takes the contents of a document and splits them into chunks, storing each chunk in a specific path within a record.", "params": [], "returns": { "type_name": "Recordstring", - "description": "An object with keys that correspond to chunk paths and values that are chunks of the original content." + "description": "An object containing key-value pairs where each key corresponds to a chunk path and each value corresponds to a chunk of text." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputChunks();\n", + "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote(/* provide args for getRemote function */)\ndocumentStore.namespace = /* provide namespace string */;\ndocumentStore.metaTemplate = {\n /* provide metadata template object */\n};\ndocumentStore.lookup = [\n /* provide lookup array */\n];\ndocumentStore.chunks = [\n /* provide chunks array */\n];\ndocumentStore.content = [\n /* provide content array */\n];\ndocumentStore.status = {\n summary: true,\n chunks: true,\n};\nconst outputs = documentStore.outputChunks();\n", "description": "" }, "name": "outputChunks", diff --git a/.komment/komment.json b/.komment/komment.json index d5242c2..a79bd2c 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,11 +1,12 @@ { "meta": { "version": "1", - "updated_at": "2024-07-10T17:41:43.599Z", + "updated_at": "2024-07-10T18:10:36.813Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", - "83f3455e-fd11-4539-9bc0-da663fa2c85d" + "83f3455e-fd11-4539-9bc0-da663fa2c85d", + "18b02909-d08f-4b13-9964-3b4ee9ccbda8" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 1a91e8c..03bd550 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,6 +19,11 @@ import { Summary } from "../types/Summary"; const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; +/** + * @description Organizes and stores code documentation for efficient retrieval + * + * @implements {IDocumentStore} + */ class DocumentStore implements IDocumentStore { CHUNK_SIZE: number; namespace: string; @@ -39,19 +44,17 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up the necessary objects and properties for the DocuStore class, - * including the namespace, getRemote method, and metadata. + * @description Establishes instance variables for `namespace`, `getRemote`, `CHUNK_SIZE`, + * and other metadata, and initializes various internal arrays and objects. * - * @param {string} namespace - namespace for which the code generator is creating - * documentation, and it is required to be provided. + * @param {string} namespace - Required for creating a new chunking client. It + * represents the root namespace of the document store where the chunks will be stored. * - * @param {(...args: any[]) => Promise>} getRemote - method that - * returns a Promise of a Record containing the document's data. + * @param {(...args: any[]) => Promise>} getRemote - Required to be + * a function that retrieves data from a remote source. * - * @param {Record} additionalMeta - metadata that can be added to the - * document store, such as version number, created and updated at timestamps, and - * other custom data, which can be used to modify or extend the default behavior of - * the function. + * @param {Record} additionalMeta - An optional field to store additional + * metadata about the document. */ constructor( namespace: string, @@ -81,20 +84,24 @@ class DocumentStore implements IDocumentStore { } /** - * @description Sets the `updated_at` metadata for an instance, updating its value - * to the given `updated_at` date. + * @description Updates the `updated_at` metadata field of the `DocumentStore` instance + * by passing the provided `Date` object as an argument. + * + * @param {Date} updated_at - Assigned to the `meta.updated_at` property of the current + * instance. * - * @param {Date} updated_at - timestamp when the record was last updated, and it is - * assigned to the `meta.updated_at` property within the function to maintain an - * updated version of the record's metadata. + * @returns {void} The result of updating the `meta` object's `updated_at` property + * with the provided `Date`. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves remote documentation data and updates local metadata, chunk - * information, and lookup table. + * @description Retrieves and updates the summary of documents stored in the Document + * Store, including meta information and chunk-level data. + * + * @returns {Summary} An object containing various metadata and chunk information. */ loadSummary = async () => { let summary: Summary = { @@ -123,6 +130,9 @@ 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 an object `this.meta` by key-value pairing, + // using a callback function to determine the value for each key. + this.meta[key] = summary?.meta?.[key] ?? value; }); this.lookup = summary.lookup || []; @@ -130,8 +140,11 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Loads chunks of data from a database based on their indices, marking - * them as loaded in the status object. + * @description Of the `DocumentStore` class asynchronously loads chunks of data from + * a summary and updates the `status` property with the loaded chunks. + * + * @returns {void} Indicative of the function finishing its task without any return + * value. */ load = async () => { if (!this.status.summary) { @@ -154,11 +167,14 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the `meta` property of an object by combining it with the - * provided `additionalMeta` property. + * @description Of the `DocumentStore` class updates the metadata of an object by + * merging the original metadata with additional metadata provided as an argument. + * + * @param {Record} additionalMeta - Used to add or update additional + * metadata for the current instance of the class. * - * @param {Record} additionalMeta - metadata to be added to the current - * instance of `Record`. + * @returns {Recordstring} An augmented metadata object combining the existing metadata + * and additional metadata provided as argument. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -174,16 +190,14 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Retrieves a specific chunk from a remote source and adds it to the - * current content array if not already loaded, returning a boolean indicating - * successful loading. + * @description Of the `DocumentStore` class asyncously loads a chunk of data from a + * remote source and concatenaates it with the rest of the content, storing it in the + * `chunks` property. If the chunk is already loaded, the method returns `true`. * - * @param {number} chunkIndex - 0-based index of a chunk within the total number of - * chunks in the StructuredFile collection, and is used to determine whether the chunk - * has already been loaded or not. + * @param {number} chunkIndex - Representing an index of a chunk to be loaded from + * the remote source. * - * @returns {Promise} a `Promise` that resolves to `true` if the chunk was - * successfully loaded, or `false` otherwise. + * @returns {Promiseboolean} True if the chunk was successfully loaded and false otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -202,15 +216,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from a summary, checks if it is in the correct chunk, - * and returns the file data if found, otherwise returns null. + * @description Of the `DocumentStore` class retrieves a file from a chunk based on + * its path. It first checks if the summary has been loaded, then calculates the chunk + * and file indices, and finally returns the file data if found, otherwise returns null. * - * @param {string} path - file path that is being searched for within the current - * chunk, and it is used to calculate the file's index within the chunk and return - * the corresponding file data. + * @param {string} path - Passed as input to the function. It represents the path of + * the file being searched for. * - * @returns {Promise} a `StructuredFile` object representing - * the file or null if it's not found. + * @returns {StructuredFile} Either a loaded file or null if the file is not found + * or has not been loaded yet. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -253,12 +267,13 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Updates the `lookup` subtable, adding a new entry to the last position - * if the last entry is full or reaching the maximum size, or adding a new entry to - * the last position of the previous entry otherwise. + * @description Updates the `lookup` subtable of a `DocumentStore` instance based on + * the provided path, inserting new elements or expanding an existing one if necessary. * - * @param {string} path - path to be looked up in the subtable, and determines whether - * a new subtable needs to be created or an existing one expanded. + * @param {string} path - Used to add new entries to the lookup subtable. + * + * @returns {string} A new subtable added to the existing lookup table or the path + * if no new subtable is created. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -272,11 +287,13 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Updates a structured file's chunks based on its size, either adding - * a new chunk if the last one is empty or appending to it if not. + * @description In the `DocumentStore` class appends files to an array of chunks based + * on the file's size and the current length of the chunks array. + * + * @param {StructuredFile} file - Passed as an argument to the function. * - * @param {StructuredFile} file - file that is being processed and added to the - * `chunks` array in the structured file system. + * @returns {StructuredFile} A new chunk containing the given file if the last subtable + * is full, or the existing chunk with the added file otherwise. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -290,15 +307,16 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to a Structured File instance's content and chunks, - * verifying that the file exists and that it has not been added previously. + * @description Of the `DocumentStore` class allows adding a file to the document + * store if certain conditions are met, including that the file exists and has not + * been loaded before. If successful, the method updates the file's metadata and adds + * it to the end of the lookup and chunks lists. * - * @param {StructuredFile} file - file to be added to the StructuredFile object's - * content, and it is used to check if the file exists and to update its metadata in - * the object. + * @param {StructuredFile} file - Passed as an object containing file path, and other + * related information. * - * @returns {boolean} a boolean value indicating whether the file was successfully - * added to the list of files. + * @returns {boolean} `true` if the file was successfully added to the lookups and + * chunks, otherwise it returns `false`. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -321,15 +339,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in a structured file, checking if it already exists, - * loading it if necessary, and storing it in the appropriate chunk and file index positions. + * @description Of the `DocumentStore` class updates a file in the store by checking + * if it exists, loading the chunk if necessary, and adding or updating the file in + * the chunk. * - * @param {StructuredFile} file - file to be added, updated or retrieved, and it is - * used to verify its existence and - * check if it has already been loaded before updating the structured file's content. + * @param {StructuredFile} file - Passed as an argument to the function. * - * @returns {Promise} a boolean value indicating whether the specified file - * was successfully added to the structured file. + * @returns {Promiseboolean} Whether the file was successfully updated or not. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -359,10 +375,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Generates a summary object containing the `meta` and `lookup` properties - * based on the internal state of the calling instance. + * @description Returns an object containing the `meta` and `lookup` properties of + * the `DocumentStore` instance. * - * @returns {Summary} an object containing `meta` and `lookup` properties. + * @returns {Summary} An object containing two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -371,12 +387,11 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Takes a `content` array and returns an object with keys that correspond - * to file paths for chunks of the content, each chunk being a slice of the original - * array. + * @description Of the `DocumentStore` class takes the contents of a document and + * splits them into chunks, storing each chunk in a specific path within a record. * - * @returns {Record} a Record containing Key-Value pairs - * of chunks from the given content. + * @returns {Recordstring} An object containing key-value pairs where each key + * corresponds to a chunk path and each value corresponds to a chunk of text. */ outputChunks(): Record { const outputs: Record = {}; From 48891c4dbb5ecb2acfb07a3c286c1791a20deeae Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:11:21 +0000 Subject: [PATCH 06/30] [tc]Added comments to 13 functions across 1 file --- src/index.ts | 153 +++++++++++++++++++++++---------------------------- 1 file changed, 70 insertions(+), 83 deletions(-) diff --git a/src/index.ts b/src/index.ts index 03bd550..cb48aab 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,11 +19,6 @@ import { Summary } from "../types/Summary"; const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; -/** - * @description Organizes and stores code documentation for efficient retrieval - * - * @implements {IDocumentStore} - */ class DocumentStore implements IDocumentStore { CHUNK_SIZE: number; namespace: string; @@ -44,17 +39,20 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Establishes instance variables for `namespace`, `getRemote`, `CHUNK_SIZE`, - * and other metadata, and initializes various internal arrays and objects. + * @description Establishes an instance of a class for document generation. It sets + * properties such as `CHUNK_SIZE`, `namespace`, and `getRemote`, and initializes + * other properties like `meta`, `lookup`, `chunks`, and `content`. * - * @param {string} namespace - Required for creating a new chunking client. It - * represents the root namespace of the document store where the chunks will be stored. + * @param {string} namespace - name of the module or application for which the + * documentation is being generated. * - * @param {(...args: any[]) => Promise>} getRemote - Required to be - * a function that retrieves data from a remote source. + * @param {(...args: any[]) => Promise>} getRemote - method that + * retrieves the document from the remote storage, which is required to initialize + * the Document Store object. * - * @param {Record} additionalMeta - An optional field to store additional - * metadata about the document. + * @param {Record} additionalMeta - metadata of the document store that + * can be used to update or manipulate the document store's properties, and it is + * optional and can have any value. */ constructor( namespace: string, @@ -84,24 +82,19 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of the `DocumentStore` instance - * by passing the provided `Date` object as an argument. - * - * @param {Date} updated_at - Assigned to the `meta.updated_at` property of the current - * instance. + * @description Updates the `updated_at` metadata field of an object, passing the + * given `updated_at` date as argument. * - * @returns {void} The result of updating the `meta` object's `updated_at` property - * with the provided `Date`. + * @param {Date} updated_at - updated date of the meta object, which is then assigned + * to the `meta.updated_at` property within the function. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates the summary of documents stored in the Document - * Store, including meta information and chunk-level data. - * - * @returns {Summary} An object containing various metadata and chunk information. + * @description Retrieves a summary from the remote document store and updates the + * local meta data and chunk information. It also sets the status to 'summary'. */ loadSummary = async () => { let summary: Summary = { @@ -130,9 +123,6 @@ 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 an object `this.meta` by key-value pairing, - // using a callback function to determine the value for each key. - this.meta[key] = summary?.meta?.[key] ?? value; }); this.lookup = summary.lookup || []; @@ -140,11 +130,9 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Of the `DocumentStore` class asynchronously loads chunks of data from - * a summary and updates the `status` property with the loaded chunks. - * - * @returns {void} Indicative of the function finishing its task without any return - * value. + * @description Loads chunks of data from an external source, retrieving them if they + * are not already available. It then sets a boolean indicating that all chunks have + * been loaded. */ load = async () => { if (!this.status.summary) { @@ -167,14 +155,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Of the `DocumentStore` class updates the metadata of an object by - * merging the original metadata with additional metadata provided as an argument. - * - * @param {Record} additionalMeta - Used to add or update additional - * metadata for the current instance of the class. + * @description Updates the metadata of an object by merging the existing metadata + * with any additional metadata provided as an argument. * - * @returns {Recordstring} An augmented metadata object combining the existing metadata - * and additional metadata provided as argument. + * @param {Record} additionalMeta - metadata to be merged with the + * existing metadata of the object, enlarging its capabilities. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -190,14 +175,16 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Of the `DocumentStore` class asyncously loads a chunk of data from a - * remote source and concatenaates it with the rest of the content, storing it in the - * `chunks` property. If the chunk is already loaded, the method returns `true`. + * @description Loads a chunk of data from a remote source, adds it to the content + * array, and stores it in the chunks object. It returns `true` if successful, or + * `false` otherwise. * - * @param {number} chunkIndex - Representing an index of a chunk to be loaded from - * the remote source. + * @param {number} chunkIndex - 0-based index of the chunk being loaded, which is + * used to determine whether the chunk has already been loaded and to update the + * corresponding array properties in the `chunks` object. * - * @returns {Promiseboolean} True if the chunk was successfully loaded and false otherwise. + * @returns {Promise} a boolean value indicating whether the chunk was + * successfully loaded or not. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -216,15 +203,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Of the `DocumentStore` class retrieves a file from a chunk based on - * its path. It first checks if the summary has been loaded, then calculates the chunk - * and file indices, and finally returns the file data if found, otherwise returns null. + * @description Retrieves a file from a summary and returns a structured file object + * or null if not found. * - * @param {string} path - Passed as input to the function. It represents the path of - * the file being searched for. + * @param {string} path - file path that the function is called on, which the function + * uses to determine which chunk and file index it corresponds to. * - * @returns {StructuredFile} Either a loaded file or null if the file is not found - * or has not been loaded yet. + * @returns {Promise} a `StructuredFile` object representing + * the file at the specified path, or `null` if the file is not found. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -267,13 +253,12 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Updates the `lookup` subtable of a `DocumentStore` instance based on - * the provided path, inserting new elements or expanding an existing one if necessary. + * @description Adds a new path to the end of the current lookup subtable or creates + * a new subtable if the last one is full and not at maximum size. * - * @param {string} path - Used to add new entries to the lookup subtable. - * - * @returns {string} A new subtable added to the existing lookup table or the path - * if no new subtable is created. + * @param {string} path - 0-based index of a subtable in the `lookup` array, indicating + * whether to add a new subtable or expand an existing one based on the current length + * of the subtable. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -287,13 +272,13 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description In the `DocumentStore` class appends files to an array of chunks based - * on the file's size and the current length of the chunks array. - * - * @param {StructuredFile} file - Passed as an argument to the function. + * @description Updates a structured file's chunks by either adding a new chunk at + * the end or appending to the last existing one, depending on whether the last chunk + * is full. * - * @returns {StructuredFile} A new chunk containing the given file if the last subtable - * is full, or the existing chunk with the added file otherwise. + * @param {StructuredFile} file - file that is being added to the StructuredFile's + * chunks subtable, either creating a new chunk if the last one is full or adding to + * the last one otherwise. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -307,16 +292,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Of the `DocumentStore` class allows adding a file to the document - * store if certain conditions are met, including that the file exists and has not - * been loaded before. If successful, the method updates the file's metadata and adds - * it to the end of the lookup and chunks lists. + * @description Adds a file to a StructuredFile object's content and chunks, checks + * if the file already exists, and updates or pushes it to the end of the lookup and + * chunks arrays if necessary. * - * @param {StructuredFile} file - Passed as an object containing file path, and other - * related information. + * @param {StructuredFile} file - file that needs to be added to the StructuredFile + * instance's content, and it provides the path of the file to be added. * - * @returns {boolean} `true` if the file was successfully added to the lookups and - * chunks, otherwise it returns `false`. + * @returns {boolean} a boolean value indicating whether the file was successfully + * added to the Structured File's content. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -339,13 +323,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Of the `DocumentStore` class updates a file in the store by checking - * if it exists, loading the chunk if necessary, and adding or updating the file in - * the chunk. + * @description Updates a file in the StructuredFile object's content by checking if + * it exists, loading the chunk if necessary, and storing it in the chunks array. * - * @param {StructuredFile} file - Passed as an argument to the function. + * @param {StructuredFile} file - file that needs to be updated or added to the + * structured file, and its presence and validity are verified before updating the + * structured file's content. * - * @returns {Promiseboolean} Whether the file was successfully updated or not. + * @returns {Promise} a boolean value indicating whether the specified file + * was successfully updated or not. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -376,9 +362,9 @@ class DocumentStore implements IDocumentStore { }; /** * @description Returns an object containing the `meta` and `lookup` properties of - * the `DocumentStore` instance. + * the parent class. * - * @returns {Summary} An object containing two properties: `meta` and `lookup`. + * @returns {Summary} an object containing `meta` and `lookup` properties. */ outputSummary(): Summary { return { @@ -387,11 +373,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Of the `DocumentStore` class takes the contents of a document and - * splits them into chunks, storing each chunk in a specific path within a record. + * @description Takes a string `content` and splits it into chunks of a specified + * size, creating a new Record object with each chunk's content as its own key-value + * pair. * - * @returns {Recordstring} An object containing key-value pairs where each key - * corresponds to a chunk path and each value corresponds to a chunk of text. + * @returns {Record} a record of chunks extracted from a given content, + * each represented as a key-value pair. */ outputChunks(): Record { const outputs: Record = {}; From 5e48c25b661fe04a9254b1b4e7c27f74bd5941c7 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:13:09 +0000 Subject: [PATCH 07/30] [tc]Added comments to 13 functions across 1 file --- src/index.ts | 132 +++++++++++++++++++++++++-------------------------- 1 file changed, 64 insertions(+), 68 deletions(-) diff --git a/src/index.ts b/src/index.ts index cb48aab..692d88b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -39,20 +39,20 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Establishes an instance of a class for document generation. It sets - * properties such as `CHUNK_SIZE`, `namespace`, and `getRemote`, and initializes - * other properties like `meta`, `lookup`, `chunks`, and `content`. + * @description Sets up an instance of the `DocumentStore` class, with a required + * namespace, getRemote method, and additional metadata. It initializes properties + * such as chunk size, namespace, getRemote, meta, and more. * - * @param {string} namespace - name of the module or application for which the - * documentation is being generated. + * @param {string} namespace - name of the code's namespace or package, which is used + * to store and retrieve documentation content. * * @param {(...args: any[]) => Promise>} getRemote - method that - * retrieves the document from the remote storage, which is required to initialize - * the Document Store object. + * retrieves data from a remote source and returns a Promise of a Record containing + * the retrieved data. * - * @param {Record} additionalMeta - metadata of the document store that - * can be used to update or manipulate the document store's properties, and it is - * optional and can have any value. + * @param {Record} additionalMeta - additional metadata that can be + * applied to the document, including the version number of the document store, the + * creation and update dates, and any other custom metadata. */ constructor( namespace: string, @@ -82,19 +82,19 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of an object, passing the - * given `updated_at` date as argument. + * @description Sets the `updated_at` metadata field to the provided `updated_at` value. * - * @param {Date} updated_at - updated date of the meta object, which is then assigned - * to the `meta.updated_at` property within the function. + * @param {Date} updated_at - date and time of the last update to the object, and by + * assigning it to the `meta.updated_at` property, the function updates the `updated_at` + * timestamp for the object in the database. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves a summary from the remote document store and updates the - * local meta data and chunk information. It also sets the status to 'summary'. + * @description Retrieves a remote Summary object and updates the local `Summary` + * object with the received data. If no data is received, it logs a message to the console. */ loadSummary = async () => { let summary: Summary = { @@ -130,9 +130,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Loads chunks of data from an external source, retrieving them if they - * are not already available. It then sets a boolean indicating that all chunks have - * been loaded. + * @description Retrieves and loads chunks of data if they are not already loaded, + * marking them as loaded in the status object. */ load = async () => { if (!this.status.summary) { @@ -155,11 +154,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of an object by merging the existing metadata - * with any additional metadata provided as an argument. + * @description Updates the `meta` object of an instance by combining its own `meta` + * property and the provided `additionalMeta`. * - * @param {Record} additionalMeta - metadata to be merged with the - * existing metadata of the object, enlarging its capabilities. + * @param {Record} additionalMeta - metadata to be combined with the + * existing metadata of the object instance, expanding its properties and values. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -175,16 +174,15 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Loads a chunk of data from a remote source, adds it to the content - * array, and stores it in the chunks object. It returns `true` if successful, or - * `false` otherwise. + * @description Loads a specific chunk from a remote location and adds it to the + * content and chunks collections if successful, returning `true`. * - * @param {number} chunkIndex - 0-based index of the chunk being loaded, which is - * used to determine whether the chunk has already been loaded and to update the - * corresponding array properties in the `chunks` object. + * @param {number} chunkIndex - 0-based index of a particular chunk within the code's + * content, which the function uses to determine whether the chunk has already been + * loaded and whether it can be added to the content. * - * @returns {Promise} a boolean value indicating whether the chunk was - * successfully loaded or not. + * @returns {Promise} a `Promise` that resolves to a boolean value indicating + * whether the chunk was loaded successfully or not. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -203,14 +201,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from a summary and returns a structured file object - * or null if not found. + * @description Retrieves a file from the local storage based on its path, checks if + * the chunk it is in has been loaded and if the file index in the chunk matches the + * provided path. If the file is not found or the chunk is not loaded, it returns `null`. * - * @param {string} path - file path that the function is called on, which the function - * uses to determine which chunk and file index it corresponds to. + * @param {string} path - file path to which the function applies its logic for + * retrieving the structured file or null if not found. * - * @returns {Promise} a `StructuredFile` object representing - * the file at the specified path, or `null` if the file is not found. + * @returns {Promise} a `StructuredFile` object or `null`, + * depending on whether the file exists and has been loaded. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -253,12 +252,12 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of the current lookup subtable or creates - * a new subtable if the last one is full and not at maximum size. + * @description Maintains a subtable to store path components and checks if the last + * subtable is full, creating a new one when necessary, or adding the new path component + * to the existing one when it's not. * - * @param {string} path - 0-based index of a subtable in the `lookup` array, indicating - * whether to add a new subtable or expand an existing one based on the current length - * of the subtable. + * @param {string} path - subtable path to be looked up in the existing ones stored + * in the `lookup` array. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -272,13 +271,12 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Updates a structured file's chunks by either adding a new chunk at - * the end or appending to the last existing one, depending on whether the last chunk - * is full. + * @description Adds a file to the end of a list of chunks if the last chunk is full + * or if the file fits within the remaining space in the previous chunk. Otherwise, + * it appends the file to the end of the previous chunk. * - * @param {StructuredFile} file - file that is being added to the StructuredFile's - * chunks subtable, either creating a new chunk if the last one is full or adding to - * the last one otherwise. + * @param {StructuredFile} file - file to be added to the last subtable or the previous + * subtable if it is already full. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -292,15 +290,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to a StructuredFile object's content and chunks, checks - * if the file already exists, and updates or pushes it to the end of the lookup and - * chunks arrays if necessary. + * @description Adds a file to a Structured File instance's content and chunks, + * validating that the file exists and that it has not already been added. * - * @param {StructuredFile} file - file that needs to be added to the StructuredFile - * instance's content, and it provides the path of the file to be added. + * @param {StructuredFile} file - file that needs to be added to the Structured File + * object's content, and it is used to determine whether the file already exists in + * the object's content and to update it if necessary. * * @returns {boolean} a boolean value indicating whether the file was successfully - * added to the Structured File's content. + * added to the structured file or not. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -323,15 +321,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the StructuredFile object's content by checking if - * it exists, loading the chunk if necessary, and storing it in the chunks array. + * @description Updates a file in the structured file, checking if the file exists, + * loading it if necessary, and storing it in the chunk and content arrays. * - * @param {StructuredFile} file - file that needs to be updated or added to the - * structured file, and its presence and validity are verified before updating the - * structured file's content. + * @param {StructuredFile} file - file that needs to be added or updated, and it is + * used to determine whether the file already exists in the StructuredFile instance's + * content and chunks, and if not, to add it to the content and chunk files. * - * @returns {Promise} a boolean value indicating whether the specified file - * was successfully updated or not. + * @returns {Promise} a boolean value indicating whether the file was + * successfully updated. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -361,8 +359,8 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing the `meta` and `lookup` properties of - * the parent class. + * @description Generates a summary object containing metadata (`meta`) and a dictionary + * (`lookup`) obtained from the parent class instance. * * @returns {Summary} an object containing `meta` and `lookup` properties. */ @@ -373,12 +371,10 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Takes a string `content` and splits it into chunks of a specified - * size, creating a new Record object with each chunk's content as its own key-value - * pair. + * @description Generates a record of chunks created by slicing the input content + * into fixed-size chunks, and returns the chunk path-to-content mapping. * - * @returns {Record} a record of chunks extracted from a given content, - * each represented as a key-value pair. + * @returns {Record} a record of chunk data, keyed by unique chunk identifiers. */ outputChunks(): Record { const outputs: Record = {}; From f6adceb547fa6cb4d9c907498d1e567237aa6b9e Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:14:27 +0000 Subject: [PATCH 08/30] [tc]Added comments to 13 functions across 1 file --- src/index.ts | 131 ++++++++++++++++++++++++++------------------------- 1 file changed, 67 insertions(+), 64 deletions(-) diff --git a/src/index.ts b/src/index.ts index 692d88b..8bd8f4c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -39,20 +39,22 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up an instance of the `DocumentStore` class, with a required - * namespace, getRemote method, and additional metadata. It initializes properties - * such as chunk size, namespace, getRemote, meta, and more. + * @description Sets up the necessary properties and variables for a document generator, + * including the chunk size, namespace, getRemote method, meta data, and various + * status flags. * - * @param {string} namespace - name of the code's namespace or package, which is used - * to store and retrieve documentation content. + * @param {string} namespace - name of the code repository or project that the + * documentation is for, and it is used to determine the prefix for the generated + * documentation's namespace. * * @param {(...args: any[]) => Promise>} getRemote - method that - * retrieves data from a remote source and returns a Promise of a Record containing - * the retrieved data. + * retrieves remote data, which is then passed to the constructor as a promise that + * resolves to a Record object containing the remote data. * - * @param {Record} additionalMeta - additional metadata that can be - * applied to the document, including the version number of the document store, the - * creation and update dates, and any other custom metadata. + * @param {Record} additionalMeta - additional metadata that will be + * included in the generated documentation, such as the version number of the document + * store, the date and time of creation and update, and any other custom metadata + * that can be used to describe the document or its content. */ constructor( namespace: string, @@ -82,19 +84,19 @@ class DocumentStore implements IDocumentStore { } /** - * @description Sets the `updated_at` metadata field to the provided `updated_at` value. + * @description Updates the `updated_at` metadata field of an object with the given + * `updated_at` value. * - * @param {Date} updated_at - date and time of the last update to the object, and by - * assigning it to the `meta.updated_at` property, the function updates the `updated_at` - * timestamp for the object in the database. + * @param {Date} updated_at - date and time of when the code was last updated, which + * is then assigned to the `meta.updated_at` property within the function. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves a remote Summary object and updates the local `Summary` - * object with the received data. If no data is received, it logs a message to the console. + * @description Retrieves and updates the local document store's metadata and chunk + * information, and sets the `summary` property to the remote summary if available. */ loadSummary = async () => { let summary: Summary = { @@ -130,8 +132,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Retrieves and loads chunks of data if they are not already loaded, - * marking them as loaded in the status object. + * @description Loads chunks of data from an API based on their indices, and sets the + * `chunks` status to `true`. */ load = async () => { if (!this.status.summary) { @@ -154,11 +156,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the `meta` object of an instance by combining its own `meta` - * property and the provided `additionalMeta`. + * @description Updates the metadata of an object by merging the original metadata + * with additional metadata provided as an argument. * - * @param {Record} additionalMeta - metadata to be combined with the - * existing metadata of the object instance, expanding its properties and values. + * @param {Record} additionalMeta - additional metadata to be merged + * with the existing `meta` property of the object when the `Record` is constructed. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -175,14 +177,14 @@ class DocumentStore implements IDocumentStore { /** * @description Loads a specific chunk from a remote location and adds it to the - * content and chunks collections if successful, returning `true`. + * content array if successful, returning `true`. * - * @param {number} chunkIndex - 0-based index of a particular chunk within the code's - * content, which the function uses to determine whether the chunk has already been - * loaded and whether it can be added to the content. + * @param {number} chunkIndex - 0-based index of the chunk to be loaded from the + * remote source, which is used to determine whether the chunk has already been loaded + * and to update the local content and chunk cache. * - * @returns {Promise} a `Promise` that resolves to a boolean value indicating - * whether the chunk was loaded successfully or not. + * @returns {Promise} a boolean value indicating whether the chunk was + * successfully loaded or not. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -201,15 +203,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from the local storage based on its path, checks if - * the chunk it is in has been loaded and if the file index in the chunk matches the - * provided path. If the file is not found or the chunk is not loaded, it returns `null`. + * @description Retrieves a file from the given path within the loaded chunks, checking + * if it's already loaded and returning it if found, otherwise loading it and returning + * it. * - * @param {string} path - file path to which the function applies its logic for - * retrieving the structured file or null if not found. + * @param {string} path - file path to be looked up in the structured files, and it + * is used to calculate the chunk index and file index within that chunk. * - * @returns {Promise} a `StructuredFile` object or `null`, - * depending on whether the file exists and has been loaded. + * @returns {Promise} a `StructuredFile` object containing the + * file metadata and contents, or `null` if the file is not found. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -252,12 +254,11 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Maintains a subtable to store path components and checks if the last - * subtable is full, creating a new one when necessary, or adding the new path component - * to the existing one when it's not. + * @description Updates the lookup table to accommodate a new path by either adding + * it to the end of the existing table or creating a new table if the last one is full. * - * @param {string} path - subtable path to be looked up in the existing ones stored - * in the `lookup` array. + * @param {string} path - path to be looked up in the lookup subtable, and it is used + * to determine whether a new subtable needs to be created or an existing one expanded. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -271,12 +272,11 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the end of a list of chunks if the last chunk is full - * or if the file fits within the remaining space in the previous chunk. Otherwise, - * it appends the file to the end of the previous chunk. + * @description Checks if the last subtable is full and, if so, creates a new one; + * otherwise, it adds the input file to the end of the current subtable. * - * @param {StructuredFile} file - file to be added to the last subtable or the previous - * subtable if it is already full. + * @param {StructuredFile} file - file that is being added to the structured file's + * chunks array. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -290,15 +290,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to a Structured File instance's content and chunks, - * validating that the file exists and that it has not already been added. + * @description Adds a file to the end of the `content` array and the end of the + * chunks array if the file exists, otherwise it throws an error. * - * @param {StructuredFile} file - file that needs to be added to the Structured File - * object's content, and it is used to determine whether the file already exists in - * the object's content and to update it if necessary. + * @param {StructuredFile} file - file to be added to the StructuredFile instance's + * content, and it is used to determine whether the file exists and to perform updates + * if necessary. * * @returns {boolean} a boolean value indicating whether the file was successfully - * added to the structured file or not. + * added to the collection of files. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -321,15 +321,16 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the structured file, checking if the file exists, - * loading it if necessary, and storing it in the chunk and content arrays. + * @description Updates a file in a structured file system by checking if it exists, + * adding it to the list of files if it doesn't, loading the chunk if it's not already + * loaded, and storing the file in the chunk. * - * @param {StructuredFile} file - file that needs to be added or updated, and it is - * used to determine whether the file already exists in the StructuredFile instance's - * content and chunks, and if not, to add it to the content and chunk files. + * @param {StructuredFile} file - file that needs to be added or updated in the + * structured file, and it is used to determine whether the file already exists in + * the structured file and whether it needs to be loaded from disk. * - * @returns {Promise} a boolean value indicating whether the file was - * successfully updated. + * @returns {Promise} a `Promise` that resolves to `true` if the file was + * successfully updated, or `false` otherwise. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -359,10 +360,11 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Generates a summary object containing metadata (`meta`) and a dictionary - * (`lookup`) obtained from the parent class instance. + * @description Returns an object containing the `meta` and `lookup` properties of + * the parent class. * - * @returns {Summary} an object containing `meta` and `lookup` properties. + * @returns {Summary} an object containing the `meta` and `lookup` properties of the + * original code. */ outputSummary(): Summary { return { @@ -371,10 +373,11 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Generates a record of chunks created by slicing the input content - * into fixed-size chunks, and returns the chunk path-to-content mapping. + * @description Slices a given string into chunks, creating a Record of + * chunk keys and corresponding chunks. It returns an Output object with chunk keys + * as keys and chunk values as values. * - * @returns {Record} a record of chunk data, keyed by unique chunk identifiers. + * @returns {Record} a Record of chunks extracted from the input content. */ outputChunks(): Record { const outputs: Record = {}; From 34f33e136178af2e5277b3ffd13a45a19df04460 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:14:53 +0000 Subject: [PATCH 09/30] Added comments to 15 functions across 1 file --- .komment/00000.json | 180 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 150 +++++++++++++++++++---------------- 3 files changed, 174 insertions(+), 161 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 5cac5e1..96c0a16 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 adding, retrieving, and updating documents in a specified namespace. It accepts a 3rd-party library or service for generating high-quality documentation. The class has various methods for loading, updating, and looking up files within the store, as well as producing summaries of the contents.", + "description": "A `DocumentStore` class that manages adding, retrieving, and updating documents in a specified namespace. It also generates high-quality documentation for the code. The class has various methods for loading and updating documents, as well as generating summaries and chunking the content. It uses TypeScript's type annotations and inference to provide a robust and flexible way of working with the code.", "items": [ { - "id": "c0dabdde-f75c-8fa4-f348-b8920f6cad6c", + "id": "7ae99ce0-23ea-5885-3f4c-ce24514c719c", "ancestors": [], - "description": "Organizes and stores code documentation for efficient retrieval", + "description": "Provides a centralized storage and management system for files within a codebase, enabling efficient retrieval and manipulation of documents through various methods.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "25 by default, which represents the number of files that can be stored in each chunk." + "description": "5, which represents the size of each chunk that can be stored in the document store." }, { "name": "namespace", "type_name": "string", - "description": "Used to specify the name or identifier of the code documentation project or module, which helps in organizing and managing the files and contents within it." + "description": "Required for creating an instance of the `DocumentStore`. It represents the root namespace or directory where the document files are stored." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store additional metadata about the document, such as its version number, creation date, and last update date}." + "description": "Used to store metadata for the document, such as version, created date, updated date, and other information.\"" }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used for initializing the meta data of the document store with default values." + "description": "Used to define a template for generating high-quality documentation." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a list of sub-arrays, where each sub-array represents a chunk of files. It acts as an index for retrieving specific chunks or files within the overall sequence of chunks being loaded." + "description": "Used to store a list of sub-arrays representing chunks of code." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store chunks of code in a specific structure, allowing for efficient retrieval and manipulation of files within those chunks." + "description": "Used to store chunks of code data, which can be loaded and manipulated by the DocumentStore methods." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store a sequence of files organized into chunks based on a chunk size and keying system." + "description": "Used to store the actual code files that make up the document." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to store the status of the code documentation generation." + "description": "Used to store information about the status of the documentation generation process." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "8e850073-ae98-2b8e-4a46-959cf6f75417", + "id": "1d856338-cdb5-49ad-024e-24a72a5e7e29", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Establishes instance variables for `namespace`, `getRemote`, `CHUNK_SIZE`, and other metadata, and initializes various internal arrays and objects.", + "description": "Sets up various properties and variables required for the class's functionality, including the namespace, getRemote method, chunk size, and metadata.", "params": [ { "name": "namespace", "type_name": "string", "optional": false, - "description": "Required for creating a new chunking client. It represents the root namespace of the document store where the chunks will be stored.", + "description": "Required. It represents the name of the document store to which the chunk data will be written.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>", "optional": false, - "description": "Required to be a function that retrieves data from a remote source.", + "description": "Required for initialization of the class.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record", "optional": true, - "description": "An optional field to store additional metadata about the document.", + "description": "An optional parameter that can be used to provide additional metadata for the document.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "// Initialize DocumentStore instance with namespace and getRemote method\nconst store = new DocumentStore(\"my_namespace\", async (args) => {\n // Use args to retrieve content from a remote service or provider\n return { /* response from the remote service */ };\n});\n\n// Set updated_at value for meta data of the DocumentStore instance\nstore.setUpdatedAt(new Date());\n\n// Load summary from remote service and update local meta data\nawait store.loadSummary();\n", - "description": "" + "code": "const documentStore = new DocumentStore(\n \"my-namespace\",\n async (...args) => {\n // This function returns a Promise that resolves to a Record\n const result = await myRemoteService.fetchDocument(...args);\n return result;\n },\n { additionalMeta: { key1: \"value1\", key2: \"value2\" } }\n);\n", + "description": "\nThis code creates an instance of the DocumentStore class with a namespace, a getRemote method that returns a Promise that resolves to a Record, and an optional metadata object. The constructor also initializes internal arrays and objects to store chunk data, content, and other meta information. The `updated_at` field of the `meta` property is set using the `setUpdatedAt()` method." }, "name": null, "location": { @@ -182,28 +182,28 @@ "docLength": 12 }, { - "id": "f2f3f4b9-e401-9e92-1948-606b0c508ec7", + "id": "a999e909-be5f-8fa1-4e45-a03cb9d7cecc", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Updates the `updated_at` metadata field of the `DocumentStore` instance by passing the provided `Date` object as an argument.", + "description": "Updates the `updated_at` metadata field of the `DocumentStore` instance, providing the latest `Date` object as an argument.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date", - "description": "Assigned to the `meta.updated_at` property of the current instance." + "description": "Used to update the metadata's updated_at field." } ], "returns": { "type_name": "void", - "description": "The result of updating the `meta` object's `updated_at` property with the provided `Date`." + "description": "The updated value of the `meta.updated_at` property." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\n documentStore.getRemote(async () => {\n return fetch('https://some-url.com');\n });\n const updatedAt = Date.now()\n documentStore.setUpdatedAt(updatedAt);\n\n", - "description": "" + "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.setUpdatedAt(new Date());\n", + "description": "\nIn this example, a new instance of the `DocumentStore` class is created and passed in the getRemote parameter which represents 3rd party library or service that provides the functionality for generating high-quality documentation. The setUpdatedAt method is then called on the `documentStore` object with a new Date() as the argument." }, "name": "setUpdatedAt", "location": { @@ -221,19 +221,19 @@ "docLength": 7 }, { - "id": "dadbd7ee-8c27-3399-404d-70ad44d8cb34", + "id": "6856be5f-5200-81ac-df47-1ed1c7832083", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Retrieves and updates the summary of documents stored in the Document Store, including meta information and chunk-level data.", + "description": "Retrieves and updates summary information for a document store, including version number, creation date, and lookup data. It also populates the `meta` property with default values and merges any remote summary data with local metadata.", "params": [], "returns": { "type_name": "Summary", - "description": "An object containing various metadata and chunk information." + "description": "An object containing meta data and other information about the document store." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary();\n// Use the summary object here\n", "description": "" }, "name": "loadSummary", @@ -252,12 +252,12 @@ "docLength": 4 }, { - "id": "041ff388-9e40-eb8b-3f42-bbb0e69eb184", + "id": "c15bede7-a252-c7a3-9a4c-48fae665ce93", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c", - "dadbd7ee-8c27-3399-404d-70ad44d8cb34" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c", + "6856be5f-5200-81ac-df47-1ed1c7832083" ], - "description": "Updates an object `this.meta` by key-value pairing, \nusing a callback function to determine the value for each key.", + "description": "Updates an object `this.meta` by setting values for each key-value pair found in the `summary?.meta` object or the original value if `summary?.meta` is null or undefined.", "name": null, "location": { "start": 121, @@ -271,19 +271,19 @@ "docLength": null }, { - "id": "69ce1aac-a362-7d94-e041-0698a87783cc", + "id": "fc83259e-d110-49b6-594b-2c19448f50a4", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Of the `DocumentStore` class asynchronously loads chunks of data from a summary and updates the `status` property with the loaded chunks.", + "description": "Of the `DocumentStore` class loads chunks of data from a summary and sets the `chunks` property to `true` once loaded.", "params": [], "returns": { "type_name": "void", - "description": "Indicative of the function finishing its task without any return value." + "description": "Indicated by the absence of a return statement." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.load();\n", + "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.load();\n", "description": "" }, "name": "load", @@ -302,27 +302,27 @@ "docLength": 3 }, { - "id": "d9caa952-6738-e884-a849-0bd7be1fd249", + "id": "6c50a33e-b2e3-e39d-9544-b39d1e2ae99d", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Of the `DocumentStore` class updates the metadata of an object by merging the original metadata with additional metadata provided as an argument.", + "description": "Within the `DocumentStore` class updates the metadata of an object by combining the existing metadata with any additional metadata provided as an argument.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record", - "description": "Used to add or update additional metadata for the current instance of the class." + "description": "Used to update the metadata of an object by combining it with the existing metadata of the object." } ], "returns": { "type_name": "Recordstring", - "description": "An augmented metadata object combining the existing metadata and additional metadata provided as argument." + "description": "An augmented metadata object containing the existing metadata and additional metadata." }, "usage": { "language": "typescript", - "code": "let store = new DocumentStore(getRemote, integration);\nstore.updateMetadata({ version: '1.0', created_at: new Date() });\n", + "code": "// create new instance of DocumentStore\nconst documentStore = new DocumentStore();\n\n// set up remote function\ndocumentStore.getRemote = async (...args) => {\n return fetch('https://example.com/api/docs', {\n method: 'GET',\n headers: {\n 'Accept': 'application/json'\n }\n }).then(response => response.json());\n};\n\n// update meta data\ndocumentStore.updateMetadata({\n version: '1.0.0',\n created_at: new Date(),\n updated_at: new Date()\n});\n\n// retrieve chunks and content\nconst chunks = await documentStore.getChunks();\nconst content = await documentStore.getContent();\n", "description": "" }, "name": "updateMetadata", @@ -338,18 +338,18 @@ "docLength": null }, { - "id": "0fc40181-0794-1da7-694f-8b54d9afb3ea", + "id": "df59e717-f8a7-46b7-3b45-1e686330744f", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Of the `DocumentStore` class asyncously loads a chunk of data from a remote source and concatenaates it with the rest of the content, storing it in the `chunks` property. If the chunk is already loaded, the method returns `true`.", + "description": "Is an asynchronous function in the `DocumentStore` class that loads a chunk of data from the remote storage and adds it to the local content array, returning `true` on success or `false` otherwise.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number", - "description": "Representing an index of a chunk to be loaded from the remote source." + "description": "An index of a chunk to be loaded from a remote location." } ], "returns": { @@ -358,7 +358,7 @@ }, "usage": { "language": "typescript", - "code": "// create a new instance of the DocumentStore class\nconst store = new DocumentStore();\n\n// set up the getRemote function, which is responsible for fetching data from a remote server\nstore.getRemote = async (url) => {\n // make an API request to the specified URL and return the response\n const response = await fetch(url);\n return response.json();\n};\n\n// set up the integration object, which provides information about the integration of the code documentation\nstore.integration = {\n name: 'My Integration',\n version: '1.0.0'\n}\n\n// initialize the DocumentStore instance with the necessary metadata and internal arrays\nawait store.init();\n\n// load a chunk of data from a remote server\nconst loadedChunk = await store.loadChunk(0);\n", + "code": "const store = new DocumentStore(getRemote, integration); // create a new instance of the class with necessary parameters\nstore.loadChunk(0); // load the first chunk of data from the remote server\n// do something with the content in chunk 0\nstore.loadChunk(1); // load the second chunk of data from the remote server\n// do something with the content in chunk 1\n", "description": "" }, "name": "loadChunk", @@ -377,28 +377,28 @@ "docLength": 11 }, { - "id": "05d1da31-616d-6980-b74e-a78c75f152fa", + "id": "9baf22b5-85f9-ef9a-0f44-f68f7c23c157", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Of the `DocumentStore` class retrieves a file from a chunk based on its path. It first checks if the summary has been loaded, then calculates the chunk and file indices, and finally returns the file data if found, otherwise returns null.", + "description": "Retrieves a file from a document store by calculating its chunk index and file index within that chunk, loading the chunk if necessary, and returning the file object if found.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string", - "description": "Passed as input to the function. It represents the path of the file being searched for." + "description": "Used to specify the file path for which summary is required." } ], "returns": { "type_name": "StructuredFile", - "description": "Either a loaded file or null if the file is not found or has not been loaded yet." + "description": "A specific object that contains file metadata and content." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.getFile('path/to/file').then((file) => {\n // do something with the file\n});\n", - "description": "\nThis is a basic example on how to use the `getFile` function of the `DocumentStore`. It shows the general syntax for calling the function and using the resulting promise. The actual implementation of the function will depend on the specific requirements of the class." + "code": "const store = new DocumentStore(getRemote, integration);\nstore.loadSummary();\nconst file = await store.getFile(\"path_of_file\");\n", + "description": "" }, "name": "getFile", "location": { @@ -416,27 +416,27 @@ "docLength": 10 }, { - "id": "4aa87d8b-7f44-068a-724e-4f9564e16348", + "id": "b15c05b3-11ca-b69b-b84d-baac2305d826", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Updates the `lookup` subtable of a `DocumentStore` instance based on the provided path, inserting new elements or expanding an existing one if necessary.", + "description": "Modifies the `lookup` array of a `DocumentStore` class based on its current size and the provided `path` string.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string", - "description": "Used to add new entries to the lookup subtable." + "description": "Used to add a new subtable to the existing lookup table." } ], "returns": { - "type_name": "string", - "description": "A new subtable added to the existing lookup table or the path if no new subtable is created." + "type_name": "array", + "description": "A new subtable or the existing one extended with the given path as an element." }, "usage": { "language": "typescript", - "code": "// The class instance is created and passed as a parameter in the constructor function\nconst store = new DocumentStore(getRemote, integration);\n\n// Adding to the end of lookup array\nstore.addToEndOfLookup('path');\n", + "code": "let documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup(\"path\");\n// If the last lookup subtable is full, create a new one\nif (this.lookup.length === 0 || this.lookup[this.lookup.length - 1].length === this.CHUNK_SIZE) {\n this.lookup.push([\"path\"]);\n} else {\n this.lookup[this.lookup.length - 1].push(\"path\");\n}\n", "description": "" }, "name": "addToEndOfLookup", @@ -455,11 +455,11 @@ "docLength": 6 }, { - "id": "a72afd67-cf02-bfae-734e-1b905ef8b91b", + "id": "f68effe6-57c2-a19b-fd46-b75988d4d375", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "In the `DocumentStore` class appends files to an array of chunks based on the file's size and the current length of the chunks array.", + "description": "In the `DocumentStore` class adds files to the end of existing chunks or creates new chunks if the last one is full, maintaining the chunk size.", "params": [ { "name": "file", @@ -471,11 +471,11 @@ ], "returns": { "type_name": "StructuredFile", - "description": "A new chunk containing the given file if the last subtable is full, or the existing chunk with the added file otherwise." + "description": "A new chunk with the given file added to it." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks({ name: 'example_file', size: 20 });\ndocumentStore.addToEndOfChunks({ name: 'example_file_2', size: 10 });\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks(file);\n", "description": "" }, "name": "addToEndOfChunks", @@ -494,27 +494,27 @@ "docLength": 10 }, { - "id": "f9570bb7-5b07-2783-b342-e48e5444b1ab", + "id": "c6644767-735e-7d9b-0c45-b97bc650ff19", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Of the `DocumentStore` class allows adding a file to the document store if certain conditions are met, including that the file exists and has not been loaded before. If successful, the method updates the file's metadata and adds it to the end of the lookup and chunks lists.", + "description": "Of the `DocumentStore` class allows for the addition of new files to the document store, checking for file existence and validity before updating the store with the added file.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Passed as an object containing file path, and other related information." + "description": "Passed to the function as an object." } ], "returns": { "type_name": "boolean", - "description": "`true` if the file was successfully added to the lookups and chunks, otherwise it returns `false`." + "description": "`true` if the file was successfully added to the content and `false` otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addFile({ path: \"path/to/file\", content: \"file contents\" });\nconst fileExists = docStore.fileExists(\"path/to/file\"); // true or false\nconst fileContent = docStore.updateFile(\"path/to/file\", { content: \"new file contents\" });\n", + "code": "const store = new DocumentStore({ getRemote, integration });\nstore.addFile(StructuredFile);\n", "description": "" }, "name": "addFile", @@ -533,27 +533,27 @@ "docLength": 10 }, { - "id": "12bfdc86-7a4d-669e-9243-ca3b92a1fb4f", + "id": "098b65a6-7f5c-b4a4-f444-4236f98c4b1b", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Of the `DocumentStore` class updates a file in the store by checking if it exists, loading the chunk if necessary, and adding or updating the file in the chunk.", + "description": "Of the `DocumentStore` class updates a file in the store by checking its existence, loading it if necessary, and storing it in the appropriate chunk and index positions.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Passed as an argument to the function." + "description": "Passed to update a single file within the application's storage." } ], "returns": { "type_name": "Promiseboolean", - "description": "Whether the file was successfully updated or not." + "description": "True if the file was updated successfully, and false otherwise." }, "usage": { "language": "typescript", - "code": "const updateFile = async (file: StructuredFile): Promise => {\n if (!this.status.chunks)\n throw Error(\"Must call .load before updating files\");\n\n if (!file) return false;\n\n const chunkIndex = this.getChunkFileIsIn(file.path);\n if (chunkIndex === -1) {\n try {\n await this.loadChunk(chunkIndex);\n this.addFile(file);\n this.content[chunkIndex * this.CHUNK_SIZE + fileIndexInChunk] = file;\n return true;\n } catch (error) {\n console.error(error);\n return false;\n }\n }\n}\n", + "code": "const docStore = new DocumentStore(getRemote);\n\n// Load a document\ndocStore.load(\"path/to/document\");\n\n// Update a file in the document\ndocStore.updateFile({ path: \"path/to/file\", contents: \"new content\" });\n", "description": "" }, "name": "updateFile", @@ -572,9 +572,9 @@ "docLength": 10 }, { - "id": "24cc185f-1cd6-92ba-f141-c66eaf290e44", + "id": "57575d04-d61b-b6a2-384b-8918e9ce9c1a", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], "description": "Returns an object containing the `meta` and `lookup` properties of the `DocumentStore` instance.", "params": [], @@ -584,7 +584,7 @@ }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputSummary();\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\n\n // initialize the summary\n docStore.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -603,19 +603,19 @@ "docLength": 6 }, { - "id": "5caa9c5b-1342-fe91-6d4a-d670ff348aee", + "id": "5a242ae3-9fdc-08ae-3846-842a10958e58", "ancestors": [ - "c0dabdde-f75c-8fa4-f348-b8920f6cad6c" + "7ae99ce0-23ea-5885-3f4c-ce24514c719c" ], - "description": "Of the `DocumentStore` class takes the contents of a document and splits them into chunks, storing each chunk in a specific path within a record.", + "description": "Of the `DocumentStore` class generates an output object containing chunks of the document, where each chunk is represented by a key-value pair consisting of the chunk path and the chunk contents.", "params": [], "returns": { "type_name": "Recordstring", - "description": "An object containing key-value pairs where each key corresponds to a chunk path and each value corresponds to a chunk of text." + "description": "A collection of key-value pairs where the keys are chunk paths and the values are chunks of text." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote(/* provide args for getRemote function */)\ndocumentStore.namespace = /* provide namespace string */;\ndocumentStore.metaTemplate = {\n /* provide metadata template object */\n};\ndocumentStore.lookup = [\n /* provide lookup array */\n];\ndocumentStore.chunks = [\n /* provide chunks array */\n];\ndocumentStore.content = [\n /* provide content array */\n];\ndocumentStore.status = {\n summary: true,\n chunks: true,\n};\nconst outputs = documentStore.outputChunks();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.content = [{id:123, name:'hello'}, {id:456, name:'world'}]\ndocumentStore.outputChunks()\n// Outputs {\n \"0\": [{id:123, name:'hello'}],\n \"1\": [{id:456, name:'world'}]\n}\n", "description": "" }, "name": "outputChunks", diff --git a/.komment/komment.json b/.komment/komment.json index a79bd2c..ad070de 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,12 +1,13 @@ { "meta": { "version": "1", - "updated_at": "2024-07-10T18:10:36.813Z", + "updated_at": "2024-07-10T18:14:48.001Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", "83f3455e-fd11-4539-9bc0-da663fa2c85d", - "18b02909-d08f-4b13-9964-3b4ee9ccbda8" + "18b02909-d08f-4b13-9964-3b4ee9ccbda8", + "7c8b9933-05d6-4176-b7aa-418bf1abbade" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 8bd8f4c..0429ef2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,6 +19,13 @@ import { Summary } from "../types/Summary"; const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; +/** + * @description Provides a centralized storage and management system for files within + * a codebase, enabling efficient retrieval and manipulation of documents through + * various methods. + * + * @implements {IDocumentStore} + */ class DocumentStore implements IDocumentStore { CHUNK_SIZE: number; namespace: string; @@ -39,22 +46,17 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up the necessary properties and variables for a document generator, - * including the chunk size, namespace, getRemote method, meta data, and various - * status flags. + * @description Sets up various properties and variables required for the class's + * functionality, including the namespace, getRemote method, chunk size, and metadata. * - * @param {string} namespace - name of the code repository or project that the - * documentation is for, and it is used to determine the prefix for the generated - * documentation's namespace. + * @param {string} namespace - Required. It represents the name of the document store + * to which the chunk data will be written. * - * @param {(...args: any[]) => Promise>} getRemote - method that - * retrieves remote data, which is then passed to the constructor as a promise that - * resolves to a Record object containing the remote data. + * @param {(...args: any[]) => Promise>} getRemote - Required for + * initialization of the class. * - * @param {Record} additionalMeta - additional metadata that will be - * included in the generated documentation, such as the version number of the document - * store, the date and time of creation and update, and any other custom metadata - * that can be used to describe the document or its content. + * @param {Record} additionalMeta - An optional parameter that can be + * used to provide additional metadata for the document. */ constructor( namespace: string, @@ -84,19 +86,25 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of an object with the given - * `updated_at` value. + * @description Updates the `updated_at` metadata field of the `DocumentStore` instance, + * providing the latest `Date` object as an argument. + * + * @param {Date} updated_at - Used to update the metadata's updated_at field. * - * @param {Date} updated_at - date and time of when the code was last updated, which - * is then assigned to the `meta.updated_at` property within the function. + * @returns {void} The updated value of the `meta.updated_at` property. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates the local document store's metadata and chunk - * information, and sets the `summary` property to the remote summary if available. + * @description Retrieves and updates summary information for a document store, + * including version number, creation date, and lookup data. It also populates the + * `meta` property with default values and merges any remote summary data with local + * metadata. + * + * @returns {Summary} An object containing meta data and other information about the + * document store. */ loadSummary = async () => { let summary: Summary = { @@ -125,6 +133,9 @@ 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 an object `this.meta` by setting values for each key-value pair found in + // the `summary?.meta` object or the original value if `summary?.meta` is null or undefined. + this.meta[key] = summary?.meta?.[key] ?? value; }); this.lookup = summary.lookup || []; @@ -132,8 +143,10 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Loads chunks of data from an API based on their indices, and sets the - * `chunks` status to `true`. + * @description Of the `DocumentStore` class loads chunks of data from a summary and + * sets the `chunks` property to `true` once loaded. + * + * @returns {void} Indicated by the absence of a return statement. */ load = async () => { if (!this.status.summary) { @@ -156,11 +169,14 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of an object by merging the original metadata - * with additional metadata provided as an argument. + * @description Within the `DocumentStore` class updates the metadata of an object + * by combining the existing metadata with any additional metadata provided as an argument. + * + * @param {Record} additionalMeta - Used to update the metadata of an + * object by combining it with the existing metadata of the object. * - * @param {Record} additionalMeta - additional metadata to be merged - * with the existing `meta` property of the object when the `Record` is constructed. + * @returns {Recordstring} An augmented metadata object containing the existing + * metadata and additional metadata. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -176,15 +192,13 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Loads a specific chunk from a remote location and adds it to the - * content array if successful, returning `true`. + * @description Is an asynchronous function in the `DocumentStore` class that loads + * a chunk of data from the remote storage and adds it to the local content array, + * returning `true` on success or `false` otherwise. * - * @param {number} chunkIndex - 0-based index of the chunk to be loaded from the - * remote source, which is used to determine whether the chunk has already been loaded - * and to update the local content and chunk cache. + * @param {number} chunkIndex - An index of a chunk to be loaded from a remote location. * - * @returns {Promise} a boolean value indicating whether the chunk was - * successfully loaded or not. + * @returns {Promiseboolean} True if the chunk was successfully loaded and false otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -203,15 +217,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from the given path within the loaded chunks, checking - * if it's already loaded and returning it if found, otherwise loading it and returning - * it. + * @description Retrieves a file from a document store by calculating its chunk index + * and file index within that chunk, loading the chunk if necessary, and returning + * the file object if found. * - * @param {string} path - file path to be looked up in the structured files, and it - * is used to calculate the chunk index and file index within that chunk. + * @param {string} path - Used to specify the file path for which summary is required. * - * @returns {Promise} a `StructuredFile` object containing the - * file metadata and contents, or `null` if the file is not found. + * @returns {StructuredFile} A specific object that contains file metadata and content. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -254,11 +266,13 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Updates the lookup table to accommodate a new path by either adding - * it to the end of the existing table or creating a new table if the last one is full. + * @description Modifies the `lookup` array of a `DocumentStore` class based on its + * current size and the provided `path` string. * - * @param {string} path - path to be looked up in the lookup subtable, and it is used - * to determine whether a new subtable needs to be created or an existing one expanded. + * @param {string} path - Used to add a new subtable to the existing lookup table. + * + * @returns {array} A new subtable or the existing one extended with the given path + * as an element. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -272,11 +286,12 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Checks if the last subtable is full and, if so, creates a new one; - * otherwise, it adds the input file to the end of the current subtable. + * @description In the `DocumentStore` class adds files to the end of existing chunks + * or creates new chunks if the last one is full, maintaining the chunk size. + * + * @param {StructuredFile} file - Passed as an argument to the function. * - * @param {StructuredFile} file - file that is being added to the structured file's - * chunks array. + * @returns {StructuredFile} A new chunk with the given file added to it. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -290,15 +305,14 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the end of the `content` array and the end of the - * chunks array if the file exists, otherwise it throws an error. + * @description Of the `DocumentStore` class allows for the addition of new files to + * the document store, checking for file existence and validity before updating the + * store with the added file. * - * @param {StructuredFile} file - file to be added to the StructuredFile instance's - * content, and it is used to determine whether the file exists and to perform updates - * if necessary. + * @param {StructuredFile} file - Passed to the function as an object. * - * @returns {boolean} a boolean value indicating whether the file was successfully - * added to the collection of files. + * @returns {boolean} `true` if the file was successfully added to the content and + * `false` otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -321,16 +335,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in a structured file system by checking if it exists, - * adding it to the list of files if it doesn't, loading the chunk if it's not already - * loaded, and storing the file in the chunk. + * @description Of the `DocumentStore` class updates a file in the store by checking + * its existence, loading it if necessary, and storing it in the appropriate chunk + * and index positions. * - * @param {StructuredFile} file - file that needs to be added or updated in the - * structured file, and it is used to determine whether the file already exists in - * the structured file and whether it needs to be loaded from disk. + * @param {StructuredFile} file - Passed to update a single file within the application's + * storage. * - * @returns {Promise} a `Promise` that resolves to `true` if the file was - * successfully updated, or `false` otherwise. + * @returns {Promiseboolean} True if the file was updated successfully, and false otherwise. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -361,10 +373,9 @@ class DocumentStore implements IDocumentStore { }; /** * @description Returns an object containing the `meta` and `lookup` properties of - * the parent class. + * the `DocumentStore` instance. * - * @returns {Summary} an object containing the `meta` and `lookup` properties of the - * original code. + * @returns {Summary} An object containing two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -373,11 +384,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Slices a given string into chunks, creating a Record of - * chunk keys and corresponding chunks. It returns an Output object with chunk keys - * as keys and chunk values as values. + * @description Of the `DocumentStore` class generates an output object containing + * chunks of the document, where each chunk is represented by a key-value pair + * consisting of the chunk path and the chunk contents. * - * @returns {Record} a Record of chunks extracted from the input content. + * @returns {Recordstring} A collection of key-value pairs where the keys are chunk + * paths and the values are chunks of text. */ outputChunks(): Record { const outputs: Record = {}; From 6c971fbe93887f3e9e63a16eface09463933b0a1 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:15:38 +0000 Subject: [PATCH 10/30] [tc]Added comments to 13 functions across 1 file --- src/index.ts | 156 ++++++++++++++++++++++++--------------------------- 1 file changed, 74 insertions(+), 82 deletions(-) diff --git a/src/index.ts b/src/index.ts index 0429ef2..83df801 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,13 +19,6 @@ import { Summary } from "../types/Summary"; const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; -/** - * @description Provides a centralized storage and management system for files within - * a codebase, enabling efficient retrieval and manipulation of documents through - * various methods. - * - * @implements {IDocumentStore} - */ class DocumentStore implements IDocumentStore { CHUNK_SIZE: number; namespace: string; @@ -46,17 +39,19 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up various properties and variables required for the class's - * functionality, including the namespace, getRemote method, chunk size, and metadata. + * @description Sets up an instance of a class for generating high-quality documentation + * for given code. It takes the namespace, getRemote method, additional meta data, + * and sets properties for chunk size, namespace, getRemote method, meta data, and status. * - * @param {string} namespace - Required. It represents the name of the document store - * to which the chunk data will be written. + * @param {string} namespace - name of the code repository or module that the constructor + * belongs to. * - * @param {(...args: any[]) => Promise>} getRemote - Required for - * initialization of the class. + * @param {(...args: any[]) => Promise>} getRemote - Promise function + * that retrieves data from a remote source and returns it as a Record object. * - * @param {Record} additionalMeta - An optional parameter that can be - * used to provide additional metadata for the document. + * @param {Record} additionalMeta - metadata that should be included in + * the documentation, such as version number, creation and update dates, and any + * additional fields specified by the caller. */ constructor( namespace: string, @@ -86,25 +81,20 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of the `DocumentStore` instance, - * providing the latest `Date` object as an argument. - * - * @param {Date} updated_at - Used to update the metadata's updated_at field. + * @description Updates the `updated_at` metadata for an object by assigning the + * provided `updated_at` value to the `meta` object's `updated_at` property. * - * @returns {void} The updated value of the `meta.updated_at` property. + * @param {Date} updated_at - timestamp when the metadata was last updated, and it + * is assigned to the `meta.updated_at` property within the function. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates summary information for a document store, - * including version number, creation date, and lookup data. It also populates the - * `meta` property with default values and merges any remote summary data with local - * metadata. - * - * @returns {Summary} An object containing meta data and other information about the - * document store. + * @description Retrieves a summary document from the remote Document Store, updates + * the local `meta` object with the retrieved information, and stores it in the local + * `lookup`. */ loadSummary = async () => { let summary: Summary = { @@ -133,9 +123,6 @@ 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 an object `this.meta` by setting values for each key-value pair found in - // the `summary?.meta` object or the original value if `summary?.meta` is null or undefined. - this.meta[key] = summary?.meta?.[key] ?? value; }); this.lookup = summary.lookup || []; @@ -143,10 +130,11 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Of the `DocumentStore` class loads chunks of data from a summary and - * sets the `chunks` property to `true` once loaded. - * - * @returns {void} Indicated by the absence of a return statement. + * @description Loads chunks of data from an API, given a lookup table and a status + * object. It initializes the status object's summary property if it is not already + * set and then iterates over the chunk indices provided by the lookup table and calls + * the `loadChunk` function for each one to load the corresponding chunk of data. + * Finally, it sets the `chunks` property of the status object to `true`. */ load = async () => { if (!this.status.summary) { @@ -169,14 +157,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Within the `DocumentStore` class updates the metadata of an object - * by combining the existing metadata with any additional metadata provided as an argument. - * - * @param {Record} additionalMeta - Used to update the metadata of an - * object by combining it with the existing metadata of the object. + * @description Updates the metadata of an object by merging the existing metadata + * with additional metadata provided as an argument. * - * @returns {Recordstring} An augmented metadata object containing the existing - * metadata and additional metadata. + * @param {Record} additionalMeta - additional metadata to be combined + * with the existing meta data of the object, in the `meta` property of the object. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -192,13 +177,16 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Is an asynchronous function in the `DocumentStore` class that loads - * a chunk of data from the remote storage and adds it to the local content array, - * returning `true` on success or `false` otherwise. + * @description Loads a chunk of data from the remote source, combining it with the + * local content, and storing it in the `chunks` object. It returns `true` if the + * chunk was loaded successfully, or `false` otherwise. * - * @param {number} chunkIndex - An index of a chunk to be loaded from a remote location. + * @param {number} chunkIndex - 0-based index of a specific chunk within the overall + * set of chunks being loaded, and is used to determine whether the corresponding + * chunk has already been loaded and to update the local content and cache accordingly. * - * @returns {Promiseboolean} True if the chunk was successfully loaded and false otherwise. + * @returns {Promise} a boolean value indicating whether the chunk was loaded + * successfully or not. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -217,13 +205,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from a document store by calculating its chunk index - * and file index within that chunk, loading the chunk if necessary, and returning - * the file object if found. + * @description Retrieves a file from a summary by calculating its chunk index and + * file index within that chunk, loading the chunk if necessary, and returning the file. * - * @param {string} path - Used to specify the file path for which summary is required. + * @param {string} path - file path to be looked up in the structured files, and it + * is used to calculate the chunk index and file index within that chunk. * - * @returns {StructuredFile} A specific object that contains file metadata and content. + * @returns {Promise} a `StructuredFile` object representing + * the file at the specified path within the current summary. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -266,13 +255,12 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Modifies the `lookup` array of a `DocumentStore` class based on its - * current size and the provided `path` string. + * @description Adds a new path to the end of a lookup subtable if it is full or if + * the last element of the table is at maximum length. * - * @param {string} path - Used to add a new subtable to the existing lookup table. - * - * @returns {array} A new subtable or the existing one extended with the given path - * as an element. + * @param {string} path - subtable index to which the function adds an entry if the + * last subtable is full or if the entry already exists in the last subtable and + * exceeds the maximum size allowed. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -286,12 +274,12 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description In the `DocumentStore` class adds files to the end of existing chunks - * or creates new chunks if the last one is full, maintaining the chunk size. - * - * @param {StructuredFile} file - Passed as an argument to the function. + * @description Adds a file to the end of an array of chunks if the last chunk is + * full or if the file cannot fit in the current chunk. * - * @returns {StructuredFile} A new chunk with the given file added to it. + * @param {StructuredFile} file - file being processed and is added to the appropriate + * subtable within the `StructuredFile` object's `chunks` array based on whether the + * last subtable is full or not. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -305,14 +293,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Of the `DocumentStore` class allows for the addition of new files to - * the document store, checking for file existence and validity before updating the - * store with the added file. + * @description Adds a file to a Structured File instance's content and chunks, + * checking for file existence and validating the addition process. * - * @param {StructuredFile} file - Passed to the function as an object. + * @param {StructuredFile} file - file to be added to the StructuredFile instance, + * providing its path for checking file existence and adding it to the content array + * if valid. * - * @returns {boolean} `true` if the file was successfully added to the content and - * `false` otherwise. + * @returns {boolean} a boolean indicating whether the file was successfully added + * to the structured file system. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -335,14 +324,17 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Of the `DocumentStore` class updates a file in the store by checking - * its existence, loading it if necessary, and storing it in the appropriate chunk - * and index positions. + * @description Updates a file in a StructuredFile collection. It checks if the file + * exists and if it has already been loaded, then it adds the file to the collection + * if it hasn't been loaded yet, and returns `true`. * - * @param {StructuredFile} file - Passed to update a single file within the application's - * storage. + * @param {StructuredFile} file - file that needs to be updated or added to the + * structured file, and it is used to check if the file exists, add it to the structured + * file if it does not exist, and update the contents of the appropriate chunk and + * file index within the chunk if it already exists. * - * @returns {Promiseboolean} True if the file was updated successfully, and false otherwise. + * @returns {Promise} a boolean value indicating whether the file was + * successfully updated or not. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -372,10 +364,11 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing the `meta` and `lookup` properties of - * the `DocumentStore` instance. + * @description Returns an object containing the metadata (`meta`) and a list of + * Lookup objects (`lookup`) of the given code. * - * @returns {Summary} An object containing two properties: `meta` and `lookup`. + * @returns {Summary} an object containing the `meta` and `lookup` properties of the + * underlying object. */ outputSummary(): Summary { return { @@ -384,12 +377,11 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Of the `DocumentStore` class generates an output object containing - * chunks of the document, where each chunk is represented by a key-value pair - * consisting of the chunk path and the chunk contents. + * @description Generates a Record of chunk objects by slicing the given content into + * chunks, and mapping each chunk to its corresponding path using a key-value pair. * - * @returns {Recordstring} A collection of key-value pairs where the keys are chunk - * paths and the values are chunks of text. + * @returns {Record} a Record containing key-value pairs + * representing chunks of the original content. */ outputChunks(): Record { const outputs: Record = {}; From 32a2ef3a2733b14ea34c9ef3176b1fb92c92952c Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:18:19 +0000 Subject: [PATCH 11/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 240 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 175 +++++++++++++++++------------- 3 files changed, 224 insertions(+), 196 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 96c0a16..53b74d8 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 adding, retrieving, and updating documents in a specified namespace. It also generates high-quality documentation for the code. The class has various methods for loading and updating documents, as well as generating summaries and chunking the content. It uses TypeScript's type annotations and inference to provide a robust and flexible way of working with the code.", + "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.", "items": [ { - "id": "7ae99ce0-23ea-5885-3f4c-ce24514c719c", + "id": "249335bd-68db-f3bd-8547-f91e9345106a", "ancestors": [], - "description": "Provides a centralized storage and management system for files within a codebase, enabling efficient retrieval and manipulation of documents through various methods.", + "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.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "5, which represents the size of each chunk that can be stored in the document store." + "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." }, { "name": "namespace", "type_name": "string", - "description": "Required for creating an instance of the `DocumentStore`. It represents the root namespace or directory where the document files are stored." + "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." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata for the document, such as version, created date, updated date, and other information.\"" + "description": "Used to store metadata about the structured file." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to define a template for generating high-quality documentation." + "description": "Not used within the given code snippet. It seems to be a template for meta data structure." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a list of sub-arrays representing chunks of code." + "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." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store chunks of code data, which can be loaded and manipulated by the DocumentStore methods." + "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." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store the actual code files that make up the document." + "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." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to store information about the status of the documentation generation process." + "description": "Not used in the provided code snippet." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "1d856338-cdb5-49ad-024e-24a72a5e7e29", + "id": "5ebc9c4e-f3cc-b187-1247-16532dd37b08", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Sets up various properties and variables required for the class's functionality, including the namespace, getRemote method, chunk size, and metadata.", + "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.", "params": [ { "name": "namespace", - "type_name": "string", + "type_name": "string*", "optional": false, - "description": "Required. It represents the name of the document store to which the chunk data will be written.", + "description": "Required to be specified when constructing an instance of this class. It represents a unique identifier for the namespace of the document store.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>", + "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required for initialization of the class.", + "description": "Required. It returns a promise that resolves to an object with property values of type any.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record", + "type_name": "Record*", "optional": true, - "description": "An optional parameter that can be used to provide additional metadata for the document.", + "description": "Used to add extra metadata properties.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\n \"my-namespace\",\n async (...args) => {\n // This function returns a Promise that resolves to a Record\n const result = await myRemoteService.fetchDocument(...args);\n return result;\n },\n { additionalMeta: { key1: \"value1\", key2: \"value2\" } }\n);\n", - "description": "\nThis code creates an instance of the DocumentStore class with a namespace, a getRemote method that returns a Promise that resolves to a Record, and an optional metadata object. The constructor also initializes internal arrays and objects to store chunk data, content, and other meta information. The `updated_at` field of the `meta` property is set using the `setUpdatedAt()` method." + "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." }, "name": null, "location": { @@ -182,28 +182,28 @@ "docLength": 12 }, { - "id": "a999e909-be5f-8fa1-4e45-a03cb9d7cecc", + "id": "25021be8-61af-13b6-6e44-4d0d0e5382f9", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Updates the `updated_at` metadata field of the `DocumentStore` instance, providing the latest `Date` object as an argument.", + "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.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date", - "description": "Used to update the metadata's updated_at field." + "type_name": "Date*", + "description": "Passed to set the value of `this.meta.updated_at`." } ], "returns": { - "type_name": "void", - "description": "The updated value of the `meta.updated_at` property." + "type_name": "undefined", + "description": "A property of an object." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.setUpdatedAt(new Date());\n", - "description": "\nIn this example, a new instance of the `DocumentStore` class is created and passed in the getRemote parameter which represents 3rd party library or service that provides the functionality for generating high-quality documentation. The setUpdatedAt method is then called on the `documentStore` object with a new Date() as the argument." + "code": "const documentStore = new DocumentStore(getRemote);\n\ndocumentStore.setUpdatedAt(new Date('2022-07-20T14:30:00.000Z'));\n", + "description": "" }, "name": "setUpdatedAt", "location": { @@ -221,20 +221,20 @@ "docLength": 7 }, { - "id": "6856be5f-5200-81ac-df47-1ed1c7832083", + "id": "1cb8ca1a-6089-3c91-7344-3e3cf75a858c", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Retrieves and updates summary information for a document store, including version number, creation date, and lookup data. It also populates the `meta` property with default values and merges any remote summary data with local metadata.", + "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.", "params": [], "returns": { - "type_name": "Summary", - "description": "An object containing meta data and other information about the document store." + "type_name": "async", + "description": "A promise that resolves to an object of type Summary with properties meta, lookup, and chunks." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary();\n// Use the summary object here\n", - "description": "" + "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." }, "name": "loadSummary", "location": { @@ -252,12 +252,12 @@ "docLength": 4 }, { - "id": "c15bede7-a252-c7a3-9a4c-48fae665ce93", + "id": "36607812-b700-2c9e-f947-d8d9384adac1", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c", - "6856be5f-5200-81ac-df47-1ed1c7832083" + "249335bd-68db-f3bd-8547-f91e9345106a", + "1cb8ca1a-6089-3c91-7344-3e3cf75a858c" ], - "description": "Updates an object `this.meta` by setting values for each key-value pair found in the `summary?.meta` object or the original value if `summary?.meta` is null or undefined.", + "description": "Assigns meta values to object properties.", "name": null, "location": { "start": 121, @@ -271,20 +271,20 @@ "docLength": null }, { - "id": "fc83259e-d110-49b6-594b-2c19448f50a4", + "id": "db3118a6-c050-de87-4844-321d0b145760", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Of the `DocumentStore` class loads chunks of data from a summary and sets the `chunks` property to `true` once loaded.", + "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`.", "params": [], "returns": { - "type_name": "void", - "description": "Indicated by the absence of a return statement." + "type_name": "undefined", + "description": "A promise that resolves to nothing." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.load();\n", - "description": "" + "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." }, "name": "load", "location": { @@ -302,28 +302,28 @@ "docLength": 3 }, { - "id": "6c50a33e-b2e3-e39d-9544-b39d1e2ae99d", + "id": "78922cc8-ce9c-fca1-4b40-19ee32bdad51", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Within the `DocumentStore` class updates the metadata of an object by combining the existing metadata with any additional metadata provided as an argument.", + "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.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record", - "description": "Used to update the metadata of an object by combining it with the existing metadata of the object." + "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." } ], "returns": { - "type_name": "Recordstring", - "description": "An augmented metadata object containing the existing metadata and additional metadata." + "type_name": "unction", + "description": "An updated meta object that combines the original meta object with the additional metadata." }, "usage": { "language": "typescript", - "code": "// create new instance of DocumentStore\nconst documentStore = new DocumentStore();\n\n// set up remote function\ndocumentStore.getRemote = async (...args) => {\n return fetch('https://example.com/api/docs', {\n method: 'GET',\n headers: {\n 'Accept': 'application/json'\n }\n }).then(response => response.json());\n};\n\n// update meta data\ndocumentStore.updateMetadata({\n version: '1.0.0',\n created_at: new Date(),\n updated_at: new Date()\n});\n\n// retrieve chunks and content\nconst chunks = await documentStore.getChunks();\nconst content = await documentStore.getContent();\n", - "description": "" + "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`." }, "name": "updateMetadata", "location": { @@ -338,28 +338,28 @@ "docLength": null }, { - "id": "df59e717-f8a7-46b7-3b45-1e686330744f", + "id": "fd0e3f18-d519-60af-b14f-138dcf8f2f00", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Is an asynchronous function in the `DocumentStore` class that loads a chunk of data from the remote storage and adds it to the local content array, returning `true` on success or `false` otherwise.", + "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.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number", - "description": "An index of a chunk to be loaded from a remote location." + "type_name": "number*", + "description": "Required when calling this asynchronous function. It represents the index of the chunk to be loaded." } ], "returns": { - "type_name": "Promiseboolean", - "description": "True if the chunk was successfully loaded and false otherwise." + "type_name": "Promise*", + "description": "Resolved to either `true` (if the chunk load is successful) or `false` (if an error occurs during loading)." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration); // create a new instance of the class with necessary parameters\nstore.loadChunk(0); // load the first chunk of data from the remote server\n// do something with the content in chunk 0\nstore.loadChunk(1); // load the second chunk of data from the remote server\n// do something with the content in chunk 1\n", - "description": "" + "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." }, "name": "loadChunk", "location": { @@ -377,27 +377,27 @@ "docLength": 11 }, { - "id": "9baf22b5-85f9-ef9a-0f44-f68f7c23c157", + "id": "e4ad9cc2-2da0-2091-7b4e-bd0b0a6cc17e", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Retrieves a file from a document store by calculating its chunk index and file index within that chunk, loading the chunk if necessary, and returning the file object if found.", + "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.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "Used to specify the file path for which summary is required." + "type_name": "string*", + "description": "Required for the function to operate correctly, representing the path of the file for which structured data is requested." } ], "returns": { - "type_name": "StructuredFile", - "description": "A specific object that contains file metadata and content." + "type_name": "Promise*", + "description": "Either a StructuredFile object or null." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.loadSummary();\nconst file = await store.getFile(\"path_of_file\");\n", + "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", "description": "" }, "name": "getFile", @@ -416,27 +416,27 @@ "docLength": 10 }, { - "id": "b15c05b3-11ca-b69b-b84d-baac2305d826", + "id": "842fe77c-ac67-36b1-294c-fb482d5335d1", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Modifies the `lookup` array of a `DocumentStore` class based on its current size and the provided `path` string.", + "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.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "Used to add a new subtable to the existing lookup table." + "type_name": "string*", + "description": "Required for execution." } ], "returns": { - "type_name": "array", - "description": "A new subtable or the existing one extended with the given path as an element." + "type_name": "unction", + "description": "Undefined since it doesn't explicitly define a return statement." }, "usage": { "language": "typescript", - "code": "let documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup(\"path\");\n// If the last lookup subtable is full, create a new one\nif (this.lookup.length === 0 || this.lookup[this.lookup.length - 1].length === this.CHUNK_SIZE) {\n this.lookup.push([\"path\"]);\n} else {\n this.lookup[this.lookup.length - 1].push(\"path\");\n}\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup('path/to/document');\n", "description": "" }, "name": "addToEndOfLookup", @@ -455,28 +455,28 @@ "docLength": 6 }, { - "id": "f68effe6-57c2-a19b-fd46-b75988d4d375", + "id": "11bb6b19-5d8a-5cb9-1a40-3ae81cd8a9bd", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "In the `DocumentStore` class adds files to the end of existing chunks or creates new chunks if the last one is full, maintaining the chunk size.", + "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`).", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Passed as an argument to the function." + "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." } ], "returns": { - "type_name": "StructuredFile", - "description": "A new chunk with the given file added to it." + "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." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks(file);\n", - "description": "" + "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." }, "name": "addToEndOfChunks", "location": { @@ -494,27 +494,27 @@ "docLength": 10 }, { - "id": "c6644767-735e-7d9b-0c45-b97bc650ff19", + "id": "c3ddb755-2082-9fa4-fc48-35a9ee911247", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Of the `DocumentStore` class allows for the addition of new files to the document store, checking for file existence and validity before updating the store with the added file.", + "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.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Passed to the function as an object." + "type_name": "StructuredFile*", + "description": "Required to be present and have a valid path." } ], "returns": { - "type_name": "boolean", - "description": "`true` if the file was successfully added to the content and `false` otherwise." + "type_name": "boolean*", + "description": "`true` if the file is successfully added, and `false` otherwise, indicating whether the operation was successful or not." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore({ getRemote, integration });\nstore.addFile(StructuredFile);\n", + "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", "description": "" }, "name": "addFile", @@ -533,27 +533,27 @@ "docLength": 10 }, { - "id": "098b65a6-7f5c-b4a4-f444-4236f98c4b1b", + "id": "b8a4e02a-a11c-e79d-e441-c76b56ba623a", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Of the `DocumentStore` class updates a file in the store by checking its existence, loading it if necessary, and storing it in the appropriate chunk and index positions.", + "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.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Passed to update a single file within the application's storage." + "type_name": "StructuredFile*", + "description": "Required to be present for the function to continue processing." } ], "returns": { - "type_name": "Promiseboolean", - "description": "True if the file was updated successfully, and false otherwise." + "type_name": "Promise*", + "description": "A promise that resolves to either true or false." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote);\n\n// Load a document\ndocStore.load(\"path/to/document\");\n\n// Update a file in the document\ndocStore.updateFile({ path: \"path/to/file\", contents: \"new content\" });\n", + "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", "description": "" }, "name": "updateFile", @@ -572,19 +572,19 @@ "docLength": 10 }, { - "id": "57575d04-d61b-b6a2-384b-8918e9ce9c1a", + "id": "10394081-0463-aba0-3643-ab31b6b4b7ce", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Returns an object containing the `meta` and `lookup` properties of the `DocumentStore` instance.", + "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.", "params": [], "returns": { - "type_name": "Summary", - "description": "An object containing two properties: `meta` and `lookup`." + "type_name": "Summary*", + "description": "An object containing two properties: meta and lookup, both having values inherited from this reference." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\n\n // initialize the summary\n docStore.outputSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\nconst result = documentStore.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -603,19 +603,19 @@ "docLength": 6 }, { - "id": "5a242ae3-9fdc-08ae-3846-842a10958e58", + "id": "ea63d1fb-c8e3-54ae-0a48-43bc9958c4a1", "ancestors": [ - "7ae99ce0-23ea-5885-3f4c-ce24514c719c" + "249335bd-68db-f3bd-8547-f91e9345106a" ], - "description": "Of the `DocumentStore` class generates an output object containing chunks of the document, where each chunk is represented by a key-value pair consisting of the chunk path and the chunk contents.", + "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.", "params": [], "returns": { - "type_name": "Recordstring", - "description": "A collection of key-value pairs where the keys are chunk paths and the values are chunks of text." + "type_name": "Record*", + "description": "An object where keys are strings and values can be any data type." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.content = [{id:123, name:'hello'}, {id:456, name:'world'}]\ndocumentStore.outputChunks()\n// Outputs {\n \"0\": [{id:123, name:'hello'}],\n \"1\": [{id:456, name:'world'}]\n}\n", + "code": "const documentStore = new DocumentStore();\nconst outputChunks = documentStore.outputChunks();\n// further processing of the outputChunks\n", "description": "" }, "name": "outputChunks", diff --git a/.komment/komment.json b/.komment/komment.json index ad070de..074dc89 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,13 +1,14 @@ { "meta": { "version": "1", - "updated_at": "2024-07-10T18:14:48.001Z", + "updated_at": "2024-07-10T18:18:12.447Z", "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" + "7c8b9933-05d6-4176-b7aa-418bf1abbade", + "4857c9e7-9349-41a8-96c5-56be5ffb04cf" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 83df801..41f1965 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,6 +19,13 @@ import { Summary } from "../types/Summary"; 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. + * + * @implements {IDocumentStore} + */ class DocumentStore implements IDocumentStore { CHUNK_SIZE: number; namespace: string; @@ -39,19 +46,19 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up an instance of a class for generating high-quality documentation - * for given code. It takes the namespace, getRemote method, additional meta data, - * and sets properties for chunk size, namespace, getRemote method, meta data, and status. + * @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. * - * @param {string} namespace - name of the code repository or module that the constructor - * belongs to. + * @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 {(...args: any[]) => Promise>} getRemote - Promise function - * that retrieves data from a remote source and returns it as a Record object. + * @param {(...args: any[]) => Promise>*} getRemote - Required. It + * returns a promise that resolves to an object with property values of type any. * - * @param {Record} additionalMeta - metadata that should be included in - * the documentation, such as version number, creation and update dates, and any - * additional fields specified by the caller. + * @param {Record*} additionalMeta - Used to add extra metadata properties. */ constructor( namespace: string, @@ -81,20 +88,25 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata for an object by assigning the - * provided `updated_at` value to the `meta` object's `updated_at` property. + * @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. + * + * @param {Date*} updated_at - Passed to set the value of `this.meta.updated_at`. * - * @param {Date} updated_at - timestamp when the metadata was last updated, and it - * is assigned to the `meta.updated_at` property within the function. + * @returns {undefined} A property of an object. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves a summary document from the remote Document Store, updates - * the local `meta` object with the retrieved information, and stores it in the local - * `lookup`. + * @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. + * + * @returns {async} A promise that resolves to an object of type Summary with properties + * meta, lookup, and chunks. */ loadSummary = async () => { let summary: Summary = { @@ -123,6 +135,8 @@ 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. + this.meta[key] = summary?.meta?.[key] ?? value; }); this.lookup = summary.lookup || []; @@ -130,11 +144,12 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Loads chunks of data from an API, given a lookup table and a status - * object. It initializes the status object's summary property if it is not already - * set and then iterates over the chunk indices provided by the lookup table and calls - * the `loadChunk` function for each one to load the corresponding chunk of data. - * Finally, it sets the `chunks` property of the status object to `true`. + * @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`. + * + * @returns {undefined} A promise that resolves to nothing. */ load = async () => { if (!this.status.summary) { @@ -157,11 +172,16 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of an object by merging the existing metadata - * with additional metadata provided as an argument. + * @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. + * + * @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 - additional metadata to be combined - * with the existing meta data of the object, in the `meta` property of the object. + * @returns {unction} An updated meta object that combines the original meta object + * with the additional metadata. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -177,16 +197,15 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Loads a chunk of data from the remote source, combining it with the - * local content, and storing it in the `chunks` object. It returns `true` if the - * chunk was loaded successfully, or `false` otherwise. + * @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. * - * @param {number} chunkIndex - 0-based index of a specific chunk within the overall - * set of chunks being loaded, and is used to determine whether the corresponding - * chunk has already been loaded and to update the local content and cache accordingly. + * @param {number*} chunkIndex - Required when calling this asynchronous function. + * It represents the index of the chunk to be loaded. * - * @returns {Promise} a boolean value indicating whether the chunk was loaded - * successfully or not. + * @returns {Promise*} Resolved to either `true` (if the chunk load is + * successful) or `false` (if an error occurs during loading). */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -205,14 +224,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from a summary by calculating its chunk index and - * file index within that chunk, loading the chunk if necessary, and returning the file. + * @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. * - * @param {string} path - file path to be looked up in the structured files, and it - * is used to calculate the chunk index and file index within that chunk. + * @param {string*} path - Required for the function to operate correctly, representing + * the path of the file for which structured data is requested. * - * @returns {Promise} a `StructuredFile` object representing - * the file at the specified path within the current summary. + * @returns {Promise*} Either a StructuredFile object or null. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -255,12 +275,14 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of a lookup subtable if it is full or if - * the last element of the table is at maximum length. + * @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. * - * @param {string} path - subtable index to which the function adds an entry if the - * last subtable is full or if the entry already exists in the last subtable and - * exceeds the maximum size allowed. + * @param {string*} path - Required for execution. + * + * @returns {unction} Undefined since it doesn't explicitly define a return statement. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -274,12 +296,17 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the end of an array of chunks if the last chunk is - * full or if the file cannot fit in the current chunk. + * @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`). + * + * @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 - file being processed and is added to the appropriate - * subtable within the `StructuredFile` object's `chunks` array based on whether the - * last subtable is full or not. + * @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. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -293,15 +320,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to a Structured File instance's content and chunks, - * checking for file existence and validating the addition process. + * @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. * - * @param {StructuredFile} file - file to be added to the StructuredFile instance, - * providing its path for checking file existence and adding it to the content array - * if valid. + * @param {StructuredFile*} file - Required to be present and have a valid path. * - * @returns {boolean} a boolean indicating whether the file was successfully added - * to the structured file system. + * @returns {boolean*} `true` if the file is successfully added, and `false` otherwise, + * indicating whether the operation was successful or not. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -324,17 +351,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in a StructuredFile collection. It checks if the file - * exists and if it has already been loaded, then it adds the file to the collection - * if it hasn't been loaded yet, and returns `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. * - * @param {StructuredFile} file - file that needs to be updated or added to the - * structured file, and it is used to check if the file exists, add it to the structured - * file if it does not exist, and update the contents of the appropriate chunk and - * file index within the chunk if it already exists. + * @param {StructuredFile*} file - Required to be present for the function to continue + * processing. * - * @returns {Promise} a boolean value indicating whether the file was - * successfully updated or not. + * @returns {Promise*} A promise that resolves to either true or false. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -364,11 +388,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing the metadata (`meta`) and a list of - * Lookup objects (`lookup`) of the given code. + * @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. * - * @returns {Summary} an object containing the `meta` and `lookup` properties of the - * underlying object. + * @returns {Summary*} An object containing two properties: meta and lookup, both + * having values inherited from this reference. */ outputSummary(): Summary { return { @@ -377,11 +403,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Generates a Record of chunk objects by slicing the given content into - * chunks, and mapping each chunk to its corresponding path using a key-value pair. + * @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. * - * @returns {Record} a Record containing key-value pairs - * representing chunks of the original content. + * @returns {Record*} An object where keys are strings and values can + * be any data type. */ outputChunks(): Record { const outputs: Record = {}; From 7de56bee671319f08ae9d779e6eb12561167ce59 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:24:15 +0000 Subject: [PATCH 12/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 206 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 175 ++++++++++++++++++----------------- 3 files changed, 192 insertions(+), 194 deletions(-) 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 = {}; From cacdd057fd2f25c66cc078118269a1e3a78c19ff Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 18:27:11 +0000 Subject: [PATCH 13/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 192 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 175 +++++++++++++++++++------------------- 3 files changed, 188 insertions(+), 184 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index aaf24f5..5a5c386 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 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.", + "description": "A DocumentStore class that manages a collection of structured files and their associated metadata. It provides methods for adding files, updating existing files, and retrieving file data in a chunked format. The class uses an internal lookup table to efficiently locate and manage large amounts of structured data.", "items": [ { - "id": "c2cf8602-37f8-e3a9-8044-7ad6893a539d", + "id": "20abaa5f-937f-59bd-cc42-fc66285ba272", "ancestors": [], - "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.", + "description": "Manages and organizes structured files into chunks, providing a way to load, update, and retrieve files from a remote data source while maintaining metadata about the files and their organization.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "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." + "description": "100 by default, representing the maximum size of a chunk in terms of files or bytes, used for efficient storage and retrieval of large amounts of data." }, { "name": "namespace", "type_name": "string", - "description": "Used to create a unique identifier for each structured file, which helps differentiate between files with the same name but different namespaces." + "description": "Used as a prefix for file paths to uniquely identify them within the document store. It serves as a namespace for the files, allowing multiple documents with similar file names to coexist in the store." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store the metadata of a document." + "description": "An object containing version, created_at, updated_at." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Not shown in the given code snippet." + "description": "Used to specify a template for creating metadata objects." }, { "name": "lookup", "type_name": "string[][]", - "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." + "description": "Used to store subtables of file paths in a structured way, with each subtable representing a chunk and containing up to CHUNK_SIZE number of files." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "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." + "description": "2D array of chunks, where each chunk is a sub-array of files, grouped by size into fixed-size groups. Each file contains metadata such as path and name." }, { "name": "content", "type_name": "StructuredFile[]", - "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." + "description": "2-dimensional array, where each inner array represents a chunk of structured files stored in the document store. The array's length corresponds to the total number of chunks." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to track the status of a document." + "description": "Used to check if the chunks are loaded." } ], "name": "DocumentStore", @@ -133,37 +133,37 @@ "docLength": null }, { - "id": "86128721-b0a1-298a-0842-cf7e6d716572", + "id": "a45b8f5a-9134-509e-014b-28c8234d9bb9", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Initializes an instance with provided namespace, getRemote method, and optional additional metadata. It sets default properties like CHUNK_SIZE, updates metadata template, creates empty lists for lookup, chunks, content, and status, and validates required inputs.", "params": [ { "name": "namespace", "type_name": "string*", "optional": false, - "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.", + "description": "Required, as indicated by the error thrown if it is not provided. It specifies the namespace for the constructed object.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required to be passed to the constructor.", + "description": "Required, which means it should be provided when calling this function. It returns a promise that resolves to an object containing any number of key-value pairs.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record*", "optional": true, - "description": "Used to provide additional metadata.", + "description": "Passed to create or update metadata for the namespace.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\"my-namespace\", async () => {\n // code here\n}, { myMetaKey: \"my-meta-value\" });\n", + "code": "const documentStore = new DocumentStore('my-namespace', async (...args: any[]) => Promise.resolve({} as Record));\n", "description": "" }, "name": null, @@ -182,27 +182,27 @@ "docLength": 12 }, { - "id": "a4d83aa3-b308-58a7-bd4e-bc8431268926", + "id": "eed61295-f174-17a7-ec4c-cb58fc691ef4", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "description": "Updates the `updated_at` property of the `meta` object within the `DocumentStore` class, setting it to the provided `Date` value.", + "description": "Updates the `updated_at` property of the `meta` object within an instance of the `DocumentStore` class with the specified `updated_at` Date value. This update operation sets the timestamp for when the document was last updated.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date*", - "description": "Assigned to the property `updated_at` of the object `this.meta`." + "description": "Assigned to the `updated_at` property of an object's meta attribute." } ], "returns": { "type_name": "void", - "description": "Equivalent to nothing or undefined." + "description": "Indicating that it does not return any specific value." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.setUpdatedAt(new Date('2023-02-20T14:30:00.000Z'));\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.setUpdatedAt(new Date('2023-03-12T14:30:00.000Z'));\n", "description": "" }, "name": "setUpdatedAt", @@ -221,20 +221,20 @@ "docLength": 7 }, { - "id": "4fd7d85e-3281-68a5-8344-c181f3798353", + "id": "48aa33b4-7cd9-7a86-de43-f10383c9c83c", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Loads or generates a document summary from a remote source and updates the local summary metadata. If no remote data is available, it creates an empty summary. The method then sets the local document store's version, creation date, and update date accordingly.", "params": [], "returns": { "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." + "description": "Effectively a null response as it does not explicitly return any value from its execution path." }, "usage": { "language": "typescript", - "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." + "code": "const store = new DocumentStore(getRemote, metaTemplate);\nstore.loadSummary().then(() => {\n console.info(\"Loaded summary\");\n});\n", + "description": "" }, "name": "loadSummary", "location": { @@ -252,12 +252,12 @@ "docLength": 4 }, { - "id": "31565757-a8d4-918b-2b49-8e1104a73b61", + "id": "6e8752bb-2237-30b8-a046-032d9da485d9", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d", - "4fd7d85e-3281-68a5-8344-c181f3798353" + "20abaa5f-937f-59bd-cc42-fc66285ba272", + "48aa33b4-7cd9-7a86-de43-f10383c9c83c" ], - "description": "Updates meta object with values from template or summary if available.", + "description": "Maps object entries to meta properties.", "name": null, "location": { "start": 121, @@ -271,20 +271,20 @@ "docLength": null }, { - "id": "8dc0cabf-65f7-10a6-a346-625561de1f63", + "id": "4367802b-6ecd-7a92-9a42-af642f0eb924", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Asynchronously loads summary data and chunk indices from the `lookup` array. It then loads corresponding chunks using the `loadChunk` method, setting the `chunks` property to `true` once complete.", "params": [], "returns": { "type_name": "void", - "description": "0. It does not explicitly return a value." + "description": "Denoted by its absence of explicit return statement." }, "usage": { "language": "typescript", - "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." + "code": "const store = new DocumentStore();\nstore.CHUNK_SIZE = 10;\nstore.namespace = 'namespace';\nstore.getRemote = async () => ({ data: 'mocked-data' });\nstore.meta = { version: '1.0', created_at: new Date(), updated_at: new Date() };\nstore.lookup = [['chunk-1'], ['chunk-2'], ['chunk-3']];\nawait store.load();\n", + "description": "" }, "name": "load", "location": { @@ -302,27 +302,27 @@ "docLength": 3 }, { - "id": "9a5515c0-0da2-88b8-3b4f-4b794bec4405", + "id": "88d9f7cd-b624-f5b3-5f4c-5258e924cc6c", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Updates the metadata object by merging additional metadata with the existing metadata. This method takes an object `additionalMeta` as input and assigns it to the `meta` property of the class, overwriting any duplicate keys.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record*", - "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." + "description": "Expected to be an object containing metadata key-value pairs. This object will be merged with the existing `this.meta` object." } ], "returns": { "type_name": "void", - "description": "Indicating that it does not return any value or data." + "description": "An empty value that does not have any specific type." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore();\ndocStore.updateMetadata({\n 'new-key': 'new-value',\n 'other-new-key': 'other-new-value'\n});\n", + "code": "const documentStore = new DocumentStore();\nconst meta = {\n version: '1.0',\n created_at: new Date('2022-01-01'),\n};\n\ndocumentStore.updateMetadata(meta);\n", "description": "" }, "name": "updateMetadata", @@ -338,28 +338,28 @@ "docLength": null }, { - "id": "c738d653-298f-9c93-8e43-462830102e72", + "id": "9284ee7e-bae1-9ca1-d747-de4645d3c6d1", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Asynchronously loads a chunk of structured files from a remote location, concatenates it with the existing content, and stores it in a cache. If loading fails, it returns false; otherwise, it returns true.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number*", - "description": "An index that identifies a specific chunk." + "description": "Used as an index to identify specific chunks, likely referring to their position or order within a larger dataset." } ], "returns": { "type_name": "Promise*", - "description": "Resolved to a boolean indicating whether the chunk was loaded successfully (true) or an error occurred (false)." + "description": "Resolved to either true or false, indicating whether the chunk was successfully loaded or an error occurred during loading." }, "usage": { "language": "typescript", - "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." + "code": "async main() {\n const documentStore = new DocumentStore();\n await documentStore.loadChunk(0);\n}\n", + "description": "\n\nNote: The `loadChunk` method is being called with `chunkIndex` set to 0." }, "name": "loadChunk", "location": { @@ -377,27 +377,27 @@ "docLength": 11 }, { - "id": "e180c593-620b-4b97-b945-193e3a3ef7ba", + "id": "a7509732-c211-fea3-dd40-81a545469d37", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Asynchronously retrieves a file from a structured storage, ensuring that the summary has been loaded and the necessary chunk is available. It calculates the chunk index and checks if the chunk is loaded; if not, it loads the chunk before returning the requested file.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "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." + "description": "Required for the function to calculate the chunk it belongs to, retrieve the file index within that chunk and verify the correctness of the chunk/lookup before returning the requested file." } ], "returns": { "type_name": "Promise*", - "description": "Either a `StructuredFile` object or null, indicating whether the requested file exists in the data structure." + "description": "Either a structured file object if the file exists or null if it does not." }, "usage": { "language": "typescript", - "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", + "code": "const store = new DocumentStore(\n // your getRemote implementation,\n // your integration object\n);\ntry {\n const file = await store.getFile('path/to/file');\n} catch (error) {\n console.error(error);\n}\n", "description": "" }, "name": "getFile", @@ -416,28 +416,28 @@ "docLength": 10 }, { - "id": "185cecdd-cc2a-a4b9-7a41-4e0719ec3fd4", + "id": "6fdbf6f5-e460-7a9f-274f-3af7d6dc9963", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Adds a path to the end of the lookup table. If the last subtable is full, it creates a new one; otherwise, it appends the path to the existing subtable. The lookup table stores paths and ensures efficient retrieval of related documents.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Passed to the function when it is called, indicating a path that needs to be added to the end of the lookup subtable." + "description": "Required for method execution." } ], "returns": { "type_name": "void", - "description": "0 if the last lookup subtable is full and a new one is created or null otherwise." + "description": "Indicating that it does not return any value." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.addToEndOfLookup(\"path/to/file.txt\");\n", - "description": "\nIt adds a path to the last lookup subtable." + "code": "let store = new DocumentStore(getRemote);\nstore.addToEndOfLookup('path/to/document');\n", + "description": "\nIn this code, an instance of the DocumentStore class named \"store\" is created with a getRemote method. Then, the addToEndOfLookup method is called on that instance to add a path to the lookup array." }, "name": "addToEndOfLookup", "location": { @@ -455,27 +455,27 @@ "docLength": 6 }, { - "id": "2153794b-f69f-639a-fb49-71df330b3aba", + "id": "52bbb15e-46c2-ea94-2e4d-11f3213741c1", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Adds a file to the end of a chunk in an array of chunks, ensuring that each chunk does not exceed a specified size (`CHUNK_SIZE`). If the last chunk is full, it creates a new one.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Expected to be passed when calling this function." + "description": "Implied to be an instance of the StructuredFile class, representing a structured file or chunk." } ], "returns": { "type_name": "void", - "description": "Equivalent to no return value. It does not explicitly return a value." + "description": "Equivalent to nothing or undefined." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.CHUNK_SIZE = 2;\ndocumentStore.addToEndOfChunks({/* structuredFile */});\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfChunks(file1);\ndocStore.addToEndOfChunks(file2);\n", "description": "" }, "name": "addToEndOfChunks", @@ -494,27 +494,27 @@ "docLength": 10 }, { - "id": "c83f0f80-4619-338e-8e4a-2d18c58185e1", + "id": "33e405f5-87bb-30ac-4c41-dfa39da16419", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Adds a structured file to the `DocumentStore` instance, checking if the document is already present and updating it if necessary. If not, it appends the file path to lookup and chunks lists, and pushes the file to content array.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "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." + "description": "Required for adding files to the object's content. It represents an instance of a structured file that has a path property, which is checked before attempting to add the file." } ], "returns": { "type_name": "boolean*", - "description": "True if the file was successfully added and false otherwise." + "description": "True if a file is successfully added and false otherwise." }, "usage": { "language": "typescript", - "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", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.load();\nconst file1 = { path: 'file1.txt', content: 'This is a test' };\ndocumentStore.addFile(file1); // Returns true if successful, false otherwise.\n", "description": "" }, "name": "addFile", @@ -533,28 +533,28 @@ "docLength": 10 }, { - "id": "0780dbdd-fc9d-59bb-da43-5aa8edae0efb", + "id": "84bc96c1-4111-2b81-2f4b-b6dcda429c54", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Updates a file in the document store. It checks if the file exists, loads the corresponding chunk if necessary, and replaces the old file with the new one. The method returns a boolean indicating success or failure of the update operation.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Required for updating files. It represents a structured file that needs to be added or updated in the storage system." + "description": "Required to be non-null. If null, the function returns false." } ], "returns": { "type_name": "Promise*", - "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." + "description": "A promise that resolves to a boolean value. The boolean indicates whether the file was successfully updated (true) or not (false)." }, "usage": { "language": "typescript", - "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": "" + "code": "const docStore = new DocumentStore();\nconst file1: StructuredFile = {\n path: 'path/to/file1',\n content: 'content of file1'\n};\nconst result = await docStore.updateFile(file1);\n", + "description": "\n\nThis example demonstrates how to create a new instance of the `DocumentStore` class and use its `updateFile` method." }, "name": "updateFile", "location": { @@ -572,11 +572,11 @@ "docLength": 10 }, { - "id": "836bf1f1-7b53-4ca1-1540-d4b67721f6a6", + "id": "31102eaa-3d44-67a5-2741-3e0a00973107", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Returns an object containing two properties, `meta` and `lookup`, with values taken from the `this.meta` and `this.lookup` attributes respectively, of the `DocumentStore` class. The returned object is a summary representation of the document store's metadata and lookup information.", "params": [], "returns": { "type_name": "Summary*", @@ -584,8 +584,8 @@ }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nconst summary = documentStore.outputSummary();\n", - "description": "" + "code": "const store = new DocumentStore();\nstore.getRemote = () => Promise.resolve({ foo: 'bar' });\nconst summary = store.outputSummary();\n", + "description": "\nThis code creates a new instance of `DocumentStore`, assigns it a dummy getRemote method and then calls the outputSummary method, storing its result in the variable named 'summary'." }, "name": "outputSummary", "location": { @@ -603,20 +603,20 @@ "docLength": 6 }, { - "id": "349f5a77-f842-32b3-064b-cf696fe5b471", + "id": "d2f4b060-bee9-f1ad-204e-9c076b20993e", "ancestors": [ - "c2cf8602-37f8-e3a9-8044-7ad6893a539d" + "20abaa5f-937f-59bd-cc42-fc66285ba272" ], - "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.", + "description": "Divides the content into chunks based on the `CHUNK_SIZE`, generates corresponding chunk keys, and stores these chunks in a record with their respective keys as property names. The method returns this record containing all output chunks.", "params": [], "returns": { "type_name": "Record*", - "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." + "description": "A mapping from string keys to arbitrary values. The returned record contains chunked data stored in the `outputs` object, where each key corresponds to a unique chunk identifier." }, "usage": { "language": "typescript", - "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": "" + "code": "const documentStore = new DocumentStore(getRemote, integration);\nconst outputs = documentStore.outputChunks();\n", + "description": "\nThis code initializes a DocumentStore object with getRemote and integration parameters. Then it calls the outputChunks() method to generate chunked data and assigns it to the 'outputs' variable." }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index 71490a8..3017d31 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-10T18:24:08.973Z", + "updated_at": "2024-07-10T18:27:04.690Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -9,7 +9,8 @@ "18b02909-d08f-4b13-9964-3b4ee9ccbda8", "7c8b9933-05d6-4176-b7aa-418bf1abbade", "4857c9e7-9349-41a8-96c5-56be5ffb04cf", - "75505a3a-f1af-4ca1-9174-9b908cdee0e4" + "75505a3a-f1af-4ca1-9174-9b908cdee0e4", + "db654c98-5128-44f7-8691-252c69b9b5b7" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index dfaf5bd..2ca2452 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,10 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @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. + * @description Manages and organizes structured files into chunks, providing a way + * to load, update, and retrieve files from a remote data source while maintaining + * metadata about the files and their organization. * * @implements {IDocumentStore} */ @@ -47,17 +46,20 @@ class DocumentStore implements IDocumentStore { }; /** - * @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. + * @description Initializes an instance with provided namespace, getRemote method, + * and optional additional metadata. It sets default properties like CHUNK_SIZE, + * updates metadata template, creates empty lists for lookup, chunks, content, and + * status, and validates required inputs. * - * @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 {string*} namespace - Required, as indicated by the error thrown if it is + * not provided. It specifies the namespace for the constructed object. * - * @param {(...args: any[]) => Promise>*} getRemote - Required to - * be passed to the constructor. + * @param {(...args: any[]) => Promise>*} getRemote - Required, which + * means it should be provided when calling this function. It returns a promise that + * resolves to an object containing any number of key-value pairs. * - * @param {Record*} additionalMeta - Used to provide additional metadata. + * @param {Record*} additionalMeta - Passed to create or update metadata + * for the namespace. */ constructor( namespace: string, @@ -87,25 +89,27 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` property of the `meta` object within the - * `DocumentStore` class, setting it to the provided `Date` value. + * @description Updates the `updated_at` property of the `meta` object within an + * instance of the `DocumentStore` class with the specified `updated_at` Date value. + * This update operation sets the timestamp for when the document was last updated. * - * @param {Date*} updated_at - Assigned to the property `updated_at` of the object `this.meta`. + * @param {Date*} updated_at - Assigned to the `updated_at` property of an object's + * meta attribute. * - * @returns {void} Equivalent to nothing or undefined. + * @returns {void} Indicating that it does not return any specific value. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @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. + * @description Loads or generates a document summary from a remote source and updates + * the local summary metadata. If no remote data is available, it creates an empty + * summary. The method then sets the local document store's version, creation date, + * and update date accordingly. * - * @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. + * @returns {void} Effectively a null response as it does not explicitly return any + * value from its execution path. */ loadSummary = async () => { let summary: Summary = { @@ -134,7 +138,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]) => { - // Updates meta object with values from template or summary if available. + // Maps object entries to meta properties. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -143,11 +147,11 @@ class DocumentStore implements IDocumentStore { }; /** - * @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. + * @description Asynchronously loads summary data and chunk indices from the `lookup` + * array. It then loads corresponding chunks using the `loadChunk` method, setting + * the `chunks` property to `true` once complete. * - * @returns {void} 0. It does not explicitly return a value. + * @returns {void} Denoted by its absence of explicit return statement. */ load = async () => { if (!this.status.summary) { @@ -170,15 +174,15 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @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. + * @description Updates the metadata object by merging additional metadata with the + * existing metadata. This method takes an object `additionalMeta` as input and assigns + * it to the `meta` property of the class, overwriting any duplicate keys. * - * @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. + * @param {Record*} additionalMeta - Expected to be an object containing + * metadata key-value pairs. This object will be merged with the existing `this.meta` + * object. * - * @returns {void} Indicating that it does not return any value or data. + * @returns {void} An empty value that does not have any specific type. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -194,15 +198,15 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @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. + * @description Asynchronously loads a chunk of structured files from a remote location, + * concatenates it with the existing content, and stores it in a cache. If loading + * fails, it returns false; otherwise, it returns true. * - * @param {number*} chunkIndex - An index that identifies a specific chunk. + * @param {number*} chunkIndex - Used as an index to identify specific chunks, likely + * referring to their position or order within a larger dataset. * - * @returns {Promise*} Resolved to a boolean indicating whether the chunk - * was loaded successfully (true) or an error occurred (false). + * @returns {Promise*} Resolved to either true or false, indicating whether + * the chunk was successfully loaded or an error occurred during loading. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -221,16 +225,17 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @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. + * @description Asynchronously retrieves a file from a structured storage, ensuring + * that the summary has been loaded and the necessary chunk is available. It calculates + * the chunk index and checks if the chunk is loaded; if not, it loads the chunk + * before returning the requested file. * - * @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. + * @param {string*} path - Required for the function to calculate the chunk it belongs + * to, retrieve the file index within that chunk and verify the correctness of the + * chunk/lookup before returning the requested file. * - * @returns {Promise*} Either a `StructuredFile` object or - * null, indicating whether the requested file exists in the data structure. + * @returns {Promise*} Either a structured file object if the + * file exists or null if it does not. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -273,15 +278,13 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @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. + * @description Adds a path to the end of the lookup table. If the last subtable is + * full, it creates a new one; otherwise, it appends the path to the existing subtable. + * The lookup table stores paths and ensures efficient retrieval of related documents. * - * @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. + * @param {string*} path - Required for method execution. * - * @returns {void} 0 if the last lookup subtable is full and a new one is created or - * null otherwise. + * @returns {void} Indicating that it does not return any value. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -295,12 +298,14 @@ class DocumentStore implements IDocumentStore { } }; /** - * @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. + * @description Adds a file to the end of a chunk in an array of chunks, ensuring + * that each chunk does not exceed a specified size (`CHUNK_SIZE`). If the last chunk + * is full, it creates a new one. * - * @param {StructuredFile*} file - Expected to be passed when calling this function. + * @param {StructuredFile*} file - Implied to be an instance of the StructuredFile + * class, representing a structured file or chunk. * - * @returns {void} Equivalent to no return value. It does not explicitly return a value. + * @returns {void} Equivalent to nothing or undefined. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -314,16 +319,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @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. + * @description Adds a structured file to the `DocumentStore` instance, checking if + * the document is already present and updating it if necessary. If not, it appends + * the file path to lookup and chunks lists, and pushes the file to content array. * - * @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. + * @param {StructuredFile*} file - Required for adding files to the object's content. + * It represents an instance of a structured file that has a path property, which is + * checked before attempting to add the file. * - * @returns {boolean*} True if the file was successfully added and false otherwise. + * @returns {boolean*} True if a file is successfully added and false otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -346,16 +350,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @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. + * @description Updates a file in the document store. It checks if the file exists, + * loads the corresponding chunk if necessary, and replaces the old file with the new + * one. The method returns a boolean indicating success or failure of the update operation. * - * @param {StructuredFile*} file - Required for updating files. It represents a - * structured file that needs to be added or updated in the storage system. + * @param {StructuredFile*} file - Required to be non-null. If null, the function + * returns 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. + * @returns {Promise*} A promise that resolves to a boolean value. The boolean + * indicates whether the file was successfully updated (true) or not (false). */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -385,10 +388,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @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. + * @description Returns an object containing two properties, `meta` and `lookup`, + * with values taken from the `this.meta` and `this.lookup` attributes respectively, + * of the `DocumentStore` class. The returned object is a summary representation of + * the document store's metadata and lookup information. * * @returns {Summary*} An object containing two properties: meta and lookup. */ @@ -399,13 +402,13 @@ class DocumentStore implements IDocumentStore { }; } /** - * @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. + * @description Divides the content into chunks based on the `CHUNK_SIZE`, generates + * corresponding chunk keys, and stores these chunks in a record with their respective + * keys as property names. The method returns this record containing all output chunks. * - * @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. + * @returns {Record*} A mapping from string keys to arbitrary values. + * The returned record contains chunked data stored in the `outputs` object, where + * each key corresponds to a unique chunk identifier. */ outputChunks(): Record { const outputs: Record = {}; From f297d3e4634017945e8800eba380632c1a92c5de Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 10 Jul 2024 22:04:03 +0000 Subject: [PATCH 14/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 216 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 180 ++++++++++++++++++----------------- 3 files changed, 203 insertions(+), 198 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 5a5c386..82ce601 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 a collection of structured files and their associated metadata. It provides methods for adding files, updating existing files, and retrieving file data in a chunked format. The class uses an internal lookup table to efficiently locate and manage large amounts of structured data.", + "description": "A DocumentStore class that manages structured files by organizing their contents into chunks and maintaining an index for efficient lookup and retrieval. The class provides methods for adding files, updating existing ones, and generating summaries and records of chunks. It utilizes arrays to store file paths, chunks, and content, with chunk size control for optimizing memory usage.", "items": [ { - "id": "20abaa5f-937f-59bd-cc42-fc66285ba272", + "id": "1cf68203-f64f-a695-8e4c-9d0ef4907991", "ancestors": [], - "description": "Manages and organizes structured files into chunks, providing a way to load, update, and retrieve files from a remote data source while maintaining metadata about the files and their organization.", + "description": "Is responsible for managing and storing a collection of structured files (e.g., JSON documents) with metadata and file lookup functionality. It allows for efficient loading, updating, and retrieval of files, as well as generating summaries and chunking the content for storage or transmission.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "100 by default, representing the maximum size of a chunk in terms of files or bytes, used for efficient storage and retrieval of large amounts of data." + "description": "Used to specify the maximum size of a chunk, which represents a group of files that can be loaded together from storage." }, { "name": "namespace", "type_name": "string", - "description": "Used as a prefix for file paths to uniquely identify them within the document store. It serves as a namespace for the files, allowing multiple documents with similar file names to coexist in the store." + "description": "Used to store the namespace for the chunk paths, allowing for organization of chunks within a specific namespace or directory structure." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "An object containing version, created_at, updated_at." + "description": "An object with properties such as version, created_at, updated_at." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to specify a template for creating metadata objects." + "description": "Used to generate high-quality documentation for code by returning an object containing the `meta` and `lookup` properties." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store subtables of file paths in a structured way, with each subtable representing a chunk and containing up to CHUNK_SIZE number of files." + "description": "2-dimensional array representing a mapping between file paths to their corresponding chunk indexes and file indices within those chunks. It's used for efficient lookup and loading of files from disk storage." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "2D array of chunks, where each chunk is a sub-array of files, grouped by size into fixed-size groups. Each file contains metadata such as path and name." + "description": "2D array where each sub-array represents a chunk of files, with each file represented as a structured object containing path, name, and other properties." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "2-dimensional array, where each inner array represents a chunk of structured files stored in the document store. The array's length corresponds to the total number of chunks." + "description": "Used to store a collection of files. It contains all the structured file data that has been loaded into the document store, organized by chunk." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to check if the chunks are loaded." + "description": "Used to track the status of the document store." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "a45b8f5a-9134-509e-014b-28c8234d9bb9", + "id": "b7037d1c-7b1b-9cbf-8f4b-57f06cef095b", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Initializes an instance with provided namespace, getRemote method, and optional additional metadata. It sets default properties like CHUNK_SIZE, updates metadata template, creates empty lists for lookup, chunks, content, and status, and validates required inputs.", + "description": "Initializes an instance with a namespace, a getRemote method, and optional additional metadata. It sets default properties, validates input, and creates internal state (meta, lookup, chunks, content, and status). The constructor ensures that the namespace and getRemote method are provided.", "params": [ { "name": "namespace", "type_name": "string*", "optional": false, - "description": "Required, as indicated by the error thrown if it is not provided. It specifies the namespace for the constructed object.", + "description": "Required to be passed. It represents the namespace for which the constructor initializes its internal state.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required, which means it should be provided when calling this function. It returns a promise that resolves to an object containing any number of key-value pairs.", + "description": "Required for constructor initialization. It returns a promise that resolves to an object with properties of any type when invoked with zero or more arguments.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record*", "optional": true, - "description": "Passed to create or update metadata for the namespace.", + "description": "Used to initialize an object that holds additional metadata for the namespace.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore('my-namespace', async (...args: any[]) => Promise.resolve({} as Record));\n", - "description": "" + "code": "const docStore = new DocumentStore('myNamespace', async (...args: any[]) => {\n // your implementation of getRemote function\n}, {key1: 'value1', key2: 'value2'});\n\n// use the created instance\n", + "description": "\nThis example creates a new instance of `DocumentStore` with namespace `myNamespace`, a `getRemote` method that returns a promise, and some additional metadata." }, "name": null, "location": { @@ -182,27 +182,27 @@ "docLength": 12 }, { - "id": "eed61295-f174-17a7-ec4c-cb58fc691ef4", + "id": "3dac190f-7053-60b1-9940-246163506416", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Updates the `updated_at` property of the `meta` object within an instance of the `DocumentStore` class with the specified `updated_at` Date value. This update operation sets the timestamp for when the document was last updated.", + "description": "Updates the `updated_at` property with the provided `Date` object, effectively setting the updated timestamp for the document.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date*", - "description": "Assigned to the `updated_at` property of an object's meta attribute." + "description": "Assigned to `this.meta.updated_at`. It represents the date when the data was last updated." } ], "returns": { - "type_name": "void", - "description": "Indicating that it does not return any specific value." + "type_name": "unction", + "description": "An instance method that sets the property `updated_at` of the object's metadata (`meta`)." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.setUpdatedAt(new Date('2023-03-12T14:30:00.000Z'));\n", + "code": "const store = new DocumentStore(getRemote);\nstore.setUpdatedAt(new Date('2022-07-25T14:30:00.000Z'));\n", "description": "" }, "name": "setUpdatedAt", @@ -221,19 +221,19 @@ "docLength": 7 }, { - "id": "48aa33b4-7cd9-7a86-de43-f10383c9c83c", + "id": "1d741c06-7daf-5391-6c4d-22366b16cd89", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Loads or generates a document summary from a remote source and updates the local summary metadata. If no remote data is available, it creates an empty summary. The method then sets the local document store's version, creation date, and update date accordingly.", + "description": "Loads and updates the document summary from a remote source, storing it locally if available. If no data is retrieved, it initializes an empty summary with default values. It then sets local metadata fields based on the loaded or default summary values.", "params": [], "returns": { - "type_name": "void", - "description": "Effectively a null response as it does not explicitly return any value from its execution path." + "type_name": "asynchronous", + "description": "A `Promise` that resolves to an object of type `Summary`." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, metaTemplate);\nstore.loadSummary().then(() => {\n console.info(\"Loaded summary\");\n});\n", + "code": "const store = new DocumentStore(\n async (...args: any[]) => {\n // implement getRemote function here\n }\n);\n\nstore.loadSummary();\n", "description": "" }, "name": "loadSummary", @@ -252,12 +252,12 @@ "docLength": 4 }, { - "id": "6e8752bb-2237-30b8-a046-032d9da485d9", + "id": "dd95865d-3ffd-46a6-ef45-74587f35cb24", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272", - "48aa33b4-7cd9-7a86-de43-f10383c9c83c" + "1cf68203-f64f-a695-8e4c-9d0ef4907991", + "1d741c06-7daf-5391-6c4d-22366b16cd89" ], - "description": "Maps object entries to meta properties.", + "description": "Maps metaTemplate keys to their corresponding values.", "name": null, "location": { "start": 121, @@ -271,19 +271,19 @@ "docLength": null }, { - "id": "4367802b-6ecd-7a92-9a42-af642f0eb924", + "id": "42641b96-833e-8e95-384d-aefda31f0143", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Asynchronously loads summary data and chunk indices from the `lookup` array. It then loads corresponding chunks using the `loadChunk` method, setting the `chunks` property to `true` once complete.", + "description": "Asynchronously loads and prepares data for display by checking if summary exists, loading it if not, and then retrieving specific chunks based on lookup indices, ultimately setting the `chunks` status to true upon completion.", "params": [], "returns": { - "type_name": "void", - "description": "Denoted by its absence of explicit return statement." + "type_name": "asynchronous", + "description": "An undefined state indicating that it has started execution and is still running." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore();\nstore.CHUNK_SIZE = 10;\nstore.namespace = 'namespace';\nstore.getRemote = async () => ({ data: 'mocked-data' });\nstore.meta = { version: '1.0', created_at: new Date(), updated_at: new Date() };\nstore.lookup = [['chunk-1'], ['chunk-2'], ['chunk-3']];\nawait store.load();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.load();\nif (documentStore.status.chunks) {\n // Now you can work with loaded chunks and content.\n}\n", "description": "" }, "name": "load", @@ -302,28 +302,28 @@ "docLength": 3 }, { - "id": "88d9f7cd-b624-f5b3-5f4c-5258e924cc6c", + "id": "d9c04527-6ff2-b4b6-2a4c-12edae7e1d85", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Updates the metadata object by merging additional metadata with the existing metadata. This method takes an object `additionalMeta` as input and assigns it to the `meta` property of the class, overwriting any duplicate keys.", + "description": "Updates the metadata object by merging it with an additional metadata object provided as an argument, allowing for dynamic modification and extension of metadata properties.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record*", - "description": "Expected to be an object containing metadata key-value pairs. This object will be merged with the existing `this.meta` object." + "description": "Defined to represent an object with key-value pairs where keys are strings and values can be of any data type. It holds additional metadata information that needs to be updated in the current metadata object." } ], "returns": { - "type_name": "void", - "description": "An empty value that does not have any specific type." + "type_name": "ƒunction", + "description": "Ƒ an object where the properties are merged from the current metadata (`this.meta`) and additional metadata (`additionalMeta`)." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\nconst meta = {\n version: '1.0',\n created_at: new Date('2022-01-01'),\n};\n\ndocumentStore.updateMetadata(meta);\n", - "description": "" + "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.updateMetadata({ author: \"John Doe\" });\n", + "description": "\nThis code creates a new instance of `DocumentStore` and then updates its metadata with additional information." }, "name": "updateMetadata", "location": { @@ -338,28 +338,28 @@ "docLength": null }, { - "id": "9284ee7e-bae1-9ca1-d747-de4645d3c6d1", + "id": "05a4dc6b-aa73-4da1-2349-54f9d2bef53e", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Asynchronously loads a chunk of structured files from a remote location, concatenates it with the existing content, and stores it in a cache. If loading fails, it returns false; otherwise, it returns true.", + "description": "Asynchronously loads a chunk of structured files from a remote location, concatenates it with the existing content, and stores it in the `chunks` object. If an error occurs during loading, it returns `false`.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number*", - "description": "Used as an index to identify specific chunks, likely referring to their position or order within a larger dataset." + "description": "Required for the asynchronous chunk loading process. It represents an index that uniquely identifies a chunk of data to be loaded from a remote location." } ], "returns": { - "type_name": "Promise*", - "description": "Resolved to either true or false, indicating whether the chunk was successfully loaded or an error occurred during loading." + "type_name": "Promiseboolean", + "description": "Resolved to either true or false." }, "usage": { "language": "typescript", - "code": "async main() {\n const documentStore = new DocumentStore();\n await documentStore.loadChunk(0);\n}\n", - "description": "\n\nNote: The `loadChunk` method is being called with `chunkIndex` set to 0." + "code": "async function main() {\n const documentStore = new DocumentStore();\n await documentStore.loadChunk(0);\n}\n", + "description": "\nNote that this code snippet assumes that `DocumentStore` has been initialized correctly and `loadChunk` is called within the scope of the `documentStore` instance." }, "name": "loadChunk", "location": { @@ -377,28 +377,28 @@ "docLength": 11 }, { - "id": "a7509732-c211-fea3-dd40-81a545469d37", + "id": "4b40437b-c422-389e-1344-939c735058a4", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Asynchronously retrieves a file from a structured storage, ensuring that the summary has been loaded and the necessary chunk is available. It calculates the chunk index and checks if the chunk is loaded; if not, it loads the chunk before returning the requested file.", + "description": "Asynchronously retrieves a file from storage, given its path. It first checks if the document summary has been loaded and then loads the corresponding chunk and file index if necessary, before returning the requested file or null if it doesn't exist.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Required for the function to calculate the chunk it belongs to, retrieve the file index within that chunk and verify the correctness of the chunk/lookup before returning the requested file." + "description": "Required for calculating the chunk it is in and file index within that chunk, which are used to access the structured file or return null if not found or not loaded." } ], "returns": { - "type_name": "Promise*", - "description": "Either a structured file object if the file exists or null if it does not." + "type_name": "PromiseStructuredFile", + "description": "Either a `StructuredFile` object or null." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(\n // your getRemote implementation,\n // your integration object\n);\ntry {\n const file = await store.getFile('path/to/file');\n} catch (error) {\n console.error(error);\n}\n", - "description": "" + "code": "const docStore = new DocumentStore();\nawait docStore.loadSummary();\n\ntry {\n const file = await docStore.getFile('path/to/file');\n} catch (error) {\n console.error(error);\n}\n", + "description": "\nThis code sets up a `DocumentStore` instance and then calls the `getFile` method with a specific path." }, "name": "getFile", "location": { @@ -416,28 +416,28 @@ "docLength": 10 }, { - "id": "6fdbf6f5-e460-7a9f-274f-3af7d6dc9963", + "id": "7378d4f1-3a4b-34a2-ef4d-492c2c802092", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Adds a path to the end of the lookup table. If the last subtable is full, it creates a new one; otherwise, it appends the path to the existing subtable. The lookup table stores paths and ensures efficient retrieval of related documents.", + "description": "Adds a new path to the end of the last lookup subtable if it is not full, or creates a new one if the previous one is full. It uses an array of arrays (lookup) to store paths in chunks of size CHUNK_SIZE.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Required for method execution." + "description": "Required for the function to work properly. It represents a path that needs to be added to the lookup table." } ], "returns": { - "type_name": "void", - "description": "Indicating that it does not return any value." + "type_name": "unction", + "description": "To be used as an event handler for adding a new path to the end of the lookup subtable." }, "usage": { "language": "typescript", - "code": "let store = new DocumentStore(getRemote);\nstore.addToEndOfLookup('path/to/document');\n", - "description": "\nIn this code, an instance of the DocumentStore class named \"store\" is created with a getRemote method. Then, the addToEndOfLookup method is called on that instance to add a path to the lookup array." + "code": "let store = new DocumentStore();\nstore CHUNK_SIZE = 3;\nstore.addToEndOfLookup('path/to/lookup'); // Add a path to the lookup\nstore.addToEndOfLookup('path/to/new/lookup');\nstore.addToEndOfLookup('path/to/yet/another/lookup');\n", + "description": "\nThe above example demonstrates adding multiple paths to the end of the `lookup` array." }, "name": "addToEndOfLookup", "location": { @@ -455,27 +455,27 @@ "docLength": 6 }, { - "id": "52bbb15e-46c2-ea94-2e4d-11f3213741c1", + "id": "b51a6c97-c0dc-0988-294a-c4da7c4b25e4", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Adds a file to the end of a chunk in an array of chunks, ensuring that each chunk does not exceed a specified size (`CHUNK_SIZE`). If the last chunk is full, it creates a new one.", + "description": "Adds a file to the end of an existing chunk or creates a new chunk if the current one is full, according to the predefined `CHUNK_SIZE`. It modifies the internal state of the object by updating its `chunks` property.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Implied to be an instance of the StructuredFile class, representing a structured file or chunk." + "description": "Expected to be an object or value that represents a file, but its exact structure and content are not specified." } ], "returns": { - "type_name": "void", - "description": "Equivalent to nothing or undefined." + "type_name": "undefined", + "description": "Implicit since there are no explicit statements that assign a value to it." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfChunks(file1);\ndocStore.addToEndOfChunks(file2);\n", + "code": "const store = new DocumentStore(\n async (...args: any[]) => Promise.resolve({ /* ... */ }),\n /* ... */\n);\n\nstore.addToEndOfChunks({\n namespace: 'test',\n content: 'this is a test',\n meta: {\n version: '1.0',\n },\n});\n", "description": "" }, "name": "addToEndOfChunks", @@ -494,27 +494,27 @@ "docLength": 10 }, { - "id": "33e405f5-87bb-30ac-4c41-dfa39da16419", + "id": "f88e2e07-0a15-53b1-a24b-dd53e8c03ae5", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Adds a structured file to the `DocumentStore` instance, checking if the document is already present and updating it if necessary. If not, it appends the file path to lookup and chunks lists, and pushes the file to content array.", + "description": "Adds a file to the store if it meets certain conditions. The file must have a path and not exist already, or be updated successfully if it does. The method returns a boolean indicating success or failure.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Required for adding files to the object's content. It represents an instance of a structured file that has a path property, which is checked before attempting to add the file." + "description": "Required to be not null. It represents a file that needs to be added to the content, specified by its path." } ], "returns": { "type_name": "boolean*", - "description": "True if a file is successfully added and false otherwise." + "description": "True if a file was successfully added and false otherwise." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.load();\nconst file1 = { path: 'file1.txt', content: 'This is a test' };\ndocumentStore.addFile(file1); // Returns true if successful, false otherwise.\n", + "code": "let store = new DocumentStore();\nstore.load();\nlet file1 = { path: 'file1.txt', content: 'Hello' };\nlet result1 = store.addFile(file1);\nif (result1) {\n let file2 = { path: 'file2.txt', content: 'World' };\n let result2 = store.addFile(file2);\n}\n", "description": "" }, "name": "addFile", @@ -533,28 +533,28 @@ "docLength": 10 }, { - "id": "84bc96c1-4111-2b81-2f4b-b6dcda429c54", + "id": "c824704b-d147-cb8c-e343-9bc02e9ae549", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Updates a file in the document store. It checks if the file exists, loads the corresponding chunk if necessary, and replaces the old file with the new one. The method returns a boolean indicating success or failure of the update operation.", + "description": "Asynchronously updates a file within a document's chunks, adding it if it does not exist. If the chunk is not loaded, it loads it first. The method returns a boolean indicating success or failure of the update operation.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Required to be non-null. If null, the function returns false." + "description": "Required for updating files." } ], "returns": { - "type_name": "Promise*", - "description": "A promise that resolves to a boolean value. The boolean indicates whether the file was successfully updated (true) or not (false)." + "type_name": "Promiseboolean", + "description": "Resolved to either `true` or `false`, indicating whether the file update operation was successful or failed respectively." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore();\nconst file1: StructuredFile = {\n path: 'path/to/file1',\n content: 'content of file1'\n};\nconst result = await docStore.updateFile(file1);\n", - "description": "\n\nThis example demonstrates how to create a new instance of the `DocumentStore` class and use its `updateFile` method." + "code": "const documentStore = new DocumentStore(getRemote, { ... });\nconst file1 = {\n path: 'file1.txt',\n data: 'Hello, World!'\n};\ndocumentStore.updateFile(file1).then((updated) => {\n if (updated) {\n // Update successful\n } else {\n // Update failed\n }\n});\n", + "description": "" }, "name": "updateFile", "location": { @@ -572,20 +572,20 @@ "docLength": 10 }, { - "id": "31102eaa-3d44-67a5-2741-3e0a00973107", + "id": "a900ab66-1a8b-199d-8e4f-5ed8a27eca9d", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Returns an object containing two properties, `meta` and `lookup`, with values taken from the `this.meta` and `this.lookup` attributes respectively, of the `DocumentStore` class. The returned object is a summary representation of the document store's metadata and lookup information.", + "description": "Returns an object with two properties, `meta` and `lookup`, which are populated from the instance variables `this.meta` and `this.lookup`, respectively. This method provides a summary representation of the document store's metadata and lookup data.", "params": [], "returns": { "type_name": "Summary*", - "description": "An object containing two properties: meta and lookup." + "description": "An object with two properties: meta and lookup, both inherited from this object." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore();\nstore.getRemote = () => Promise.resolve({ foo: 'bar' });\nconst summary = store.outputSummary();\n", - "description": "\nThis code creates a new instance of `DocumentStore`, assigns it a dummy getRemote method and then calls the outputSummary method, storing its result in the variable named 'summary'." + "code": "const store = new DocumentStore(getRemote, integration);\nconst result = store.outputSummary();\n", + "description": "" }, "name": "outputSummary", "location": { @@ -603,20 +603,20 @@ "docLength": 6 }, { - "id": "d2f4b060-bee9-f1ad-204e-9c076b20993e", + "id": "0dce4884-669f-f49a-ba41-c2a8e25b44b3", "ancestors": [ - "20abaa5f-937f-59bd-cc42-fc66285ba272" + "1cf68203-f64f-a695-8e4c-9d0ef4907991" ], - "description": "Divides the content into chunks based on the `CHUNK_SIZE`, generates corresponding chunk keys, and stores these chunks in a record with their respective keys as property names. The method returns this record containing all output chunks.", + "description": "Splits its content into chunks, converts each chunk to a string, and stores them in a record as key-value pairs where keys are generated using the `chunkKeyToChunkPath` function. The method returns this record.", "params": [], "returns": { - "type_name": "Record*", - "description": "A mapping from string keys to arbitrary values. The returned record contains chunked data stored in the `outputs` object, where each key corresponds to a unique chunk identifier." + "type_name": "Recordstring", + "description": "An object containing a set of key-value pairs. Each key corresponds to a string path and each value corresponds to a chunk of content from the original data." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nconst outputs = documentStore.outputChunks();\n", - "description": "\nThis code initializes a DocumentStore object with getRemote and integration parameters. Then it calls the outputChunks() method to generate chunked data and assigns it to the 'outputs' variable." + "code": "const store = new DocumentStore();\nstore.CHUNK_SIZE = 1024;\nstore.outputChunks()\n", + "description": "\nThis code creates an instance of a `DocumentStore` and then calls its `outputChunks()` method." }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index 3017d31..b43a08a 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-10T18:27:04.690Z", + "updated_at": "2024-07-10T22:03:56.437Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -10,7 +10,8 @@ "7c8b9933-05d6-4176-b7aa-418bf1abbade", "4857c9e7-9349-41a8-96c5-56be5ffb04cf", "75505a3a-f1af-4ca1-9174-9b908cdee0e4", - "db654c98-5128-44f7-8691-252c69b9b5b7" + "db654c98-5128-44f7-8691-252c69b9b5b7", + "fb518d01-fd0a-40bb-8d37-2ff5990c023b" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 2ca2452..69fea9c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,10 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Manages and organizes structured files into chunks, providing a way - * to load, update, and retrieve files from a remote data source while maintaining - * metadata about the files and their organization. + * @description Is responsible for managing and storing a collection of structured + * files (e.g., JSON documents) with metadata and file lookup functionality. It allows + * for efficient loading, updating, and retrieval of files, as well as generating + * summaries and chunking the content for storage or transmission. * * @implements {IDocumentStore} */ @@ -46,20 +47,20 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Initializes an instance with provided namespace, getRemote method, - * and optional additional metadata. It sets default properties like CHUNK_SIZE, - * updates metadata template, creates empty lists for lookup, chunks, content, and - * status, and validates required inputs. + * @description Initializes an instance with a namespace, a getRemote method, and + * optional additional metadata. It sets default properties, validates input, and + * creates internal state (meta, lookup, chunks, content, and status). The constructor + * ensures that the namespace and getRemote method are provided. * - * @param {string*} namespace - Required, as indicated by the error thrown if it is - * not provided. It specifies the namespace for the constructed object. + * @param {string*} namespace - Required to be passed. It represents the namespace + * for which the constructor initializes its internal state. * - * @param {(...args: any[]) => Promise>*} getRemote - Required, which - * means it should be provided when calling this function. It returns a promise that - * resolves to an object containing any number of key-value pairs. + * @param {(...args: any[]) => Promise>*} getRemote - Required for + * constructor initialization. It returns a promise that resolves to an object with + * properties of any type when invoked with zero or more arguments. * - * @param {Record*} additionalMeta - Passed to create or update metadata - * for the namespace. + * @param {Record*} additionalMeta - Used to initialize an object that + * holds additional metadata for the namespace. */ constructor( namespace: string, @@ -89,27 +90,26 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` property of the `meta` object within an - * instance of the `DocumentStore` class with the specified `updated_at` Date value. - * This update operation sets the timestamp for when the document was last updated. + * @description Updates the `updated_at` property with the provided `Date` object, + * effectively setting the updated timestamp for the document. * - * @param {Date*} updated_at - Assigned to the `updated_at` property of an object's - * meta attribute. + * @param {Date*} updated_at - Assigned to `this.meta.updated_at`. It represents the + * date when the data was last updated. * - * @returns {void} Indicating that it does not return any specific value. + * @returns {unction} An instance method that sets the property `updated_at` of the + * object's metadata (`meta`). */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Loads or generates a document summary from a remote source and updates - * the local summary metadata. If no remote data is available, it creates an empty - * summary. The method then sets the local document store's version, creation date, - * and update date accordingly. + * @description Loads and updates the document summary from a remote source, storing + * it locally if available. If no data is retrieved, it initializes an empty summary + * with default values. It then sets local metadata fields based on the loaded or + * default summary values. * - * @returns {void} Effectively a null response as it does not explicitly return any - * value from its execution path. + * @returns {asynchronous} A `Promise` that resolves to an object of type `Summary`. */ loadSummary = async () => { let summary: Summary = { @@ -138,7 +138,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]) => { - // Maps object entries to meta properties. + // Maps metaTemplate keys to their corresponding values. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -147,11 +147,12 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Asynchronously loads summary data and chunk indices from the `lookup` - * array. It then loads corresponding chunks using the `loadChunk` method, setting - * the `chunks` property to `true` once complete. + * @description Asynchronously loads and prepares data for display by checking if + * summary exists, loading it if not, and then retrieving specific chunks based on + * lookup indices, ultimately setting the `chunks` status to true upon completion. * - * @returns {void} Denoted by its absence of explicit return statement. + * @returns {asynchronous} An undefined state indicating that it has started execution + * and is still running. */ load = async () => { if (!this.status.summary) { @@ -174,15 +175,17 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata object by merging additional metadata with the - * existing metadata. This method takes an object `additionalMeta` as input and assigns - * it to the `meta` property of the class, overwriting any duplicate keys. + * @description Updates the metadata object by merging it with an additional metadata + * object provided as an argument, allowing for dynamic modification and extension + * of metadata properties. * - * @param {Record*} additionalMeta - Expected to be an object containing - * metadata key-value pairs. This object will be merged with the existing `this.meta` + * @param {Record*} additionalMeta - Defined to represent an object with + * key-value pairs where keys are strings and values can be of any data type. It holds + * additional metadata information that needs to be updated in the current metadata * object. * - * @returns {void} An empty value that does not have any specific type. + * @returns {ƒunction} Ƒ an object where the properties are merged from the current + * metadata (`this.meta`) and additional metadata (`additionalMeta`). */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -199,14 +202,14 @@ class DocumentStore implements IDocumentStore { /** * @description Asynchronously loads a chunk of structured files from a remote location, - * concatenates it with the existing content, and stores it in a cache. If loading - * fails, it returns false; otherwise, it returns true. + * concatenates it with the existing content, and stores it in the `chunks` object. + * If an error occurs during loading, it returns `false`. * - * @param {number*} chunkIndex - Used as an index to identify specific chunks, likely - * referring to their position or order within a larger dataset. + * @param {number*} chunkIndex - Required for the asynchronous chunk loading process. + * It represents an index that uniquely identifies a chunk of data to be loaded from + * a remote location. * - * @returns {Promise*} Resolved to either true or false, indicating whether - * the chunk was successfully loaded or an error occurred during loading. + * @returns {Promiseboolean} Resolved to either true or false. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -225,17 +228,16 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Asynchronously retrieves a file from a structured storage, ensuring - * that the summary has been loaded and the necessary chunk is available. It calculates - * the chunk index and checks if the chunk is loaded; if not, it loads the chunk - * before returning the requested file. + * @description Asynchronously retrieves a file from storage, given its path. It first + * checks if the document summary has been loaded and then loads the corresponding + * chunk and file index if necessary, before returning the requested file or null if + * it doesn't exist. * - * @param {string*} path - Required for the function to calculate the chunk it belongs - * to, retrieve the file index within that chunk and verify the correctness of the - * chunk/lookup before returning the requested file. + * @param {string*} path - Required for calculating the chunk it is in and file index + * within that chunk, which are used to access the structured file or return null if + * not found or not loaded. * - * @returns {Promise*} Either a structured file object if the - * file exists or null if it does not. + * @returns {PromiseStructuredFile} Either a `StructuredFile` object or null. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -278,13 +280,15 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a path to the end of the lookup table. If the last subtable is - * full, it creates a new one; otherwise, it appends the path to the existing subtable. - * The lookup table stores paths and ensures efficient retrieval of related documents. + * @description Adds a new path to the end of the last lookup subtable if it is not + * full, or creates a new one if the previous one is full. It uses an array of arrays + * (lookup) to store paths in chunks of size CHUNK_SIZE. * - * @param {string*} path - Required for method execution. + * @param {string*} path - Required for the function to work properly. It represents + * a path that needs to be added to the lookup table. * - * @returns {void} Indicating that it does not return any value. + * @returns {unction} To be used as an event handler for adding a new path to the end + * of the lookup subtable. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -298,14 +302,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the end of a chunk in an array of chunks, ensuring - * that each chunk does not exceed a specified size (`CHUNK_SIZE`). If the last chunk - * is full, it creates a new one. + * @description Adds a file to the end of an existing chunk or creates a new chunk + * if the current one is full, according to the predefined `CHUNK_SIZE`. It modifies + * the internal state of the object by updating its `chunks` property. * - * @param {StructuredFile*} file - Implied to be an instance of the StructuredFile - * class, representing a structured file or chunk. + * @param {StructuredFile*} file - Expected to be an object or value that represents + * a file, but its exact structure and content are not specified. * - * @returns {void} Equivalent to nothing or undefined. + * @returns {undefined} Implicit since there are no explicit statements that assign + * a value to it. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -319,15 +324,14 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a structured file to the `DocumentStore` instance, checking if - * the document is already present and updating it if necessary. If not, it appends - * the file path to lookup and chunks lists, and pushes the file to content array. + * @description Adds a file to the store if it meets certain conditions. The file + * must have a path and not exist already, or be updated successfully if it does. The + * method returns a boolean indicating success or failure. * - * @param {StructuredFile*} file - Required for adding files to the object's content. - * It represents an instance of a structured file that has a path property, which is - * checked before attempting to add the file. + * @param {StructuredFile*} file - Required to be not null. It represents a file that + * needs to be added to the content, specified by its path. * - * @returns {boolean*} True if a file is successfully added and false otherwise. + * @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"); @@ -350,15 +354,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the document store. It checks if the file exists, - * loads the corresponding chunk if necessary, and replaces the old file with the new - * one. The method returns a boolean indicating success or failure of the update operation. + * @description Asynchronously updates a file within a document's chunks, adding it + * if it does not exist. If the chunk is not loaded, it loads it first. The method + * returns a boolean indicating success or failure of the update operation. * - * @param {StructuredFile*} file - Required to be non-null. If null, the function - * returns false. + * @param {StructuredFile*} file - Required for updating files. * - * @returns {Promise*} A promise that resolves to a boolean value. The boolean - * indicates whether the file was successfully updated (true) or not (false). + * @returns {Promiseboolean} Resolved to either `true` or `false`, indicating whether + * the file update operation was successful or failed respectively. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -388,12 +391,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing two properties, `meta` and `lookup`, - * with values taken from the `this.meta` and `this.lookup` attributes respectively, - * of the `DocumentStore` class. The returned object is a summary representation of - * the document store's metadata and lookup information. + * @description Returns an object with two properties, `meta` and `lookup`, which are + * populated from the instance variables `this.meta` and `this.lookup`, respectively. + * This method provides a summary representation of the document store's metadata and + * lookup data. * - * @returns {Summary*} An object containing two properties: meta and lookup. + * @returns {Summary*} An object with two properties: meta and lookup, both inherited + * from this object. */ outputSummary(): Summary { return { @@ -402,13 +406,13 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Divides the content into chunks based on the `CHUNK_SIZE`, generates - * corresponding chunk keys, and stores these chunks in a record with their respective - * keys as property names. The method returns this record containing all output chunks. + * @description Splits its content into chunks, converts each chunk to a string, and + * stores them in a record as key-value pairs where keys are generated using the + * `chunkKeyToChunkPath` function. The method returns this record. * - * @returns {Record*} A mapping from string keys to arbitrary values. - * The returned record contains chunked data stored in the `outputs` object, where - * each key corresponds to a unique chunk identifier. + * @returns {Recordstring} An object containing a set of key-value pairs. Each key + * corresponds to a string path and each value corresponds to a chunk of content from + * the original data. */ outputChunks(): Record { const outputs: Record = {}; From e7b96fd8b698e5f4aa486de786f0fee9c62e81c2 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Thu, 11 Jul 2024 08:03:27 +0000 Subject: [PATCH 15/30] Added comments to 15 functions across 1 file --- .komment/00000.json | 232 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 159 ++++++++++++----------------- 3 files changed, 184 insertions(+), 212 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 82ce601..ee42806 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 by organizing their contents into chunks and maintaining an index for efficient lookup and retrieval. The class provides methods for adding files, updating existing ones, and generating summaries and records of chunks. It utilizes arrays to store file paths, chunks, and content, with chunk size control for optimizing memory usage.", + "description": "A `DocumentStore` class for managing adding, retrieving, and updating documentation for code. It includes several methods for performing these actions, such as `loadSummary`, `load`, `addFile`, and `updateFile`. The code also uses various types and packages, including `IDocumentStore`, `StructuredFile`, `SUMMARY`, and `CHUNK_SIZE`. Overall, the code appears to provide a way to organize and manage documentation for code in a structured manner.", "items": [ { - "id": "1cf68203-f64f-a695-8e4c-9d0ef4907991", + "id": "a35f71f6-f4c7-2184-cb49-6f8eceb5b941", "ancestors": [], - "description": "Is responsible for managing and storing a collection of structured files (e.g., JSON documents) with metadata and file lookup functionality. It allows for efficient loading, updating, and retrieval of files, as well as generating summaries and chunking the content for storage or transmission.", + "description": "Stores and manages structured files for generating high-quality documentation. It loads and organizes content, handles chunking and summary creation, and provides methods for updating and querying the document store.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "Used to specify the maximum size of a chunk, which represents a group of files that can be loaded together from storage." + "description": "Used to define the size of each chunk in the code document store." }, { "name": "namespace", "type_name": "string", - "description": "Used to store the namespace for the chunk paths, allowing for organization of chunks within a specific namespace or directory structure." + "description": "Required for creating a DocumentStore instance. It represents the name or identifier of the domain or application to which the document store belongs." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "An object with properties such as version, created_at, updated_at." + "description": "Used to store metadata about the document collection, such as version number, creation date, and update date." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to generate high-quality documentation for code by returning an object containing the `meta` and `lookup` properties." + "description": "Used for initializing internal arrays and objects to store chunk data, content, or other meta information." }, { "name": "lookup", "type_name": "string[][]", - "description": "2-dimensional array representing a mapping between file paths to their corresponding chunk indexes and file indices within those chunks. It's used for efficient lookup and loading of files from disk storage." + "description": "Used to store a list of sub-arrays, each representing a chunk of files within a larger document structure." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "2D array where each sub-array represents a chunk of files, with each file represented as a structured object containing path, name, and other properties." + "description": "Used to store chunks of content from the DocumentStore's internal arrays." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store a collection of files. It contains all the structured file data that has been loaded into the document store, organized by chunk." + "description": "Used to store the contents of files within the document store. It is used as a variable for method calls such as `addFile` and `updateFile`." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to track the status of the document store." + "description": "Used to store information about the state of the document store, such as whether the summary has been loaded or not." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "b7037d1c-7b1b-9cbf-8f4b-57f06cef095b", + "id": "acba2c29-7903-5a93-084a-18251e6aa2c5", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Initializes an instance with a namespace, a getRemote method, and optional additional metadata. It sets default properties, validates input, and creates internal state (meta, lookup, chunks, content, and status). The constructor ensures that the namespace and getRemote method are provided.", + "description": "Sets up the class with a required namespace and getRemote method, initializes instance variables for chunk size, namespace, getRemote, metadata, and lookup arrays, and sets status to false for summary and chunks.", "params": [ { "name": "namespace", - "type_name": "string*", + "type_name": "string", "optional": false, - "description": "Required to be passed. It represents the namespace for which the constructor initializes its internal state.", + "description": "Required, it represents the namespace for the document store.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>*", + "type_name": "(...args: any[]) => Promise>", "optional": false, - "description": "Required for constructor initialization. It returns a promise that resolves to an object with properties of any type when invoked with zero or more arguments.", + "description": "Required for constructing the chunker instance.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record*", + "type_name": "Record", "optional": true, - "description": "Used to initialize an object that holds additional metadata for the namespace.", + "description": "Used to store any additional metadata required by the function.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore('myNamespace', async (...args: any[]) => {\n // your implementation of getRemote function\n}, {key1: 'value1', key2: 'value2'});\n\n// use the created instance\n", - "description": "\nThis example creates a new instance of `DocumentStore` with namespace `myNamespace`, a `getRemote` method that returns a promise, and some additional metadata." + "code": "const documentStore = new DocumentStore(\n \"my-namespace\",\n async (...args) => {\n // Get remote docs from a provider\n },\n { version: \"1.0\" }\n);\n\n// Set the updated_at field of the meta object with a new Date() value\ndocumentStore.setUpdatedAt(new Date());\n\n// Load document summaries from a provider and update local meta data based on the remote summary\nawait documentStore.loadSummary();\n", + "description": "" }, "name": null, "location": { @@ -182,27 +182,27 @@ "docLength": 12 }, { - "id": "3dac190f-7053-60b1-9940-246163506416", + "id": "b431a994-a1eb-a9bf-b84c-c00c54ad64f2", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Updates the `updated_at` property with the provided `Date` object, effectively setting the updated timestamp for the document.", + "description": "Updates the `updated_at` metadata for the document.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date*", - "description": "Assigned to `this.meta.updated_at`. It represents the date when the data was last updated." + "type_name": "Date", + "description": "Used to update the `updated_at` metadata of an entity." } ], "returns": { - "type_name": "unction", - "description": "An instance method that sets the property `updated_at` of the object's metadata (`meta`)." + "type_name": "void", + "description": "The result of updating the `meta` object's `updated_at` property with the provided `Date`." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote);\nstore.setUpdatedAt(new Date('2022-07-25T14:30:00.000Z'));\n", + "code": "const store = new DocumentStore(getRemote, integration);\nstore.setUpdatedAt(new Date());\n", "description": "" }, "name": "setUpdatedAt", @@ -221,19 +221,19 @@ "docLength": 7 }, { - "id": "1d741c06-7daf-5391-6c4d-22366b16cd89", + "id": "e1aad662-7b87-3ea6-b64d-80c873f32a4e", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Loads and updates the document summary from a remote source, storing it locally if available. If no data is retrieved, it initializes an empty summary with default values. It then sets local metadata fields based on the loaded or default summary values.", + "description": "Retrieves and updates a summary of documents stored in the store, including meta-data and chunk information.", "params": [], "returns": { - "type_name": "asynchronous", - "description": "A `Promise` that resolves to an object of type `Summary`." + "type_name": "Summary", + "description": "An object containing metadata and chunk information." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(\n async (...args: any[]) => {\n // implement getRemote function here\n }\n);\n\nstore.loadSummary();\n", + "code": "const docStore = new DocumentStore(getRemote);\ndocStore.loadSummary();\n", "description": "" }, "name": "loadSummary", @@ -252,12 +252,12 @@ "docLength": 4 }, { - "id": "dd95865d-3ffd-46a6-ef45-74587f35cb24", + "id": "2308d1bd-4571-dfb9-854a-122be7d3a602", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991", - "1d741c06-7daf-5391-6c4d-22366b16cd89" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941", + "e1aad662-7b87-3ea6-b64d-80c873f32a4e" ], - "description": "Maps metaTemplate keys to their corresponding values.", + "description": "Assigns values to meta object properties, using either \nthe provided `summary.meta` object or the default value.", "name": null, "location": { "start": 121, @@ -271,19 +271,19 @@ "docLength": null }, { - "id": "42641b96-833e-8e95-384d-aefda31f0143", + "id": "8affd1e3-0165-1ca9-6542-f2facb534dbb", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Asynchronously loads and prepares data for display by checking if summary exists, loading it if not, and then retrieving specific chunks based on lookup indices, ultimately setting the `chunks` status to true upon completion.", + "description": "Asynchronous loads chunks of data from an index, updating the `status.chunks` property to indicate successful loading.", "params": [], "returns": { - "type_name": "asynchronous", - "description": "An undefined state indicating that it has started execution and is still running." + "type_name": "void", + "description": "Indicative that it does not have a return statement." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.load();\nif (documentStore.status.chunks) {\n // Now you can work with loaded chunks and content.\n}\n", + "code": "let documentStore = new DocumentStore(getRemote);\ndocumentStore.CHUNK_SIZE = 100;\ndocumentStore.namespace = 'my-namespace';\ndocumentStore.metaTemplate = {\n version: '1.0.0',\n created_at: Date,\n updated_at: Date,\n};\nawait documentStore.load();\n", "description": "" }, "name": "load", @@ -302,28 +302,28 @@ "docLength": 3 }, { - "id": "d9c04527-6ff2-b4b6-2a4c-12edae7e1d85", + "id": "34b963b3-6525-3489-524e-98846f861801", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Updates the metadata object by merging it with an additional metadata object provided as an argument, allowing for dynamic modification and extension of metadata properties.", + "description": "Updates the metadata field of the class by merging the existing metadata with an additional metadata object.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record*", - "description": "Defined to represent an object with key-value pairs where keys are strings and values can be of any data type. It holds additional metadata information that needs to be updated in the current metadata object." + "type_name": "Record", + "description": "Used to add additional metadata to the function's meta data." } ], "returns": { - "type_name": "ƒunction", - "description": "Ƒ an object where the properties are merged from the current metadata (`this.meta`) and additional metadata (`additionalMeta`)." + "type_name": "Recordstring", + "description": "An immutable object containing the updated metadata data." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.updateMetadata({ author: \"John Doe\" });\n", - "description": "\nThis code creates a new instance of `DocumentStore` and then updates its metadata with additional information." + "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.updateMetadata({ version: '1.0', created_at: Date.now() });\n", + "description": "" }, "name": "updateMetadata", "location": { @@ -338,28 +338,28 @@ "docLength": null }, { - "id": "05a4dc6b-aa73-4da1-2349-54f9d2bef53e", + "id": "49e3ed05-4e7c-7c87-824c-3fde323f38f1", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Asynchronously loads a chunk of structured files from a remote location, concatenates it with the existing content, and stores it in the `chunks` object. If an error occurs during loading, it returns `false`.", + "description": "Async loads a chunk of data from a remote source and concats it with the existing content of the class, updating the internal chunks array.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number*", - "description": "Required for the asynchronous chunk loading process. It represents an index that uniquely identifies a chunk of data to be loaded from a remote location." + "type_name": "number", + "description": "Used to reference the specific chunk being loaded, with values ranging from 0 to the total number of chunks - 1." } ], "returns": { "type_name": "Promiseboolean", - "description": "Resolved to either true or false." + "description": "True if the chunk was successfully loaded and false otherwise." }, "usage": { "language": "typescript", - "code": "async function main() {\n const documentStore = new DocumentStore();\n await documentStore.loadChunk(0);\n}\n", - "description": "\nNote that this code snippet assumes that `DocumentStore` has been initialized correctly and `loadChunk` is called within the scope of the `documentStore` instance." + "code": "const documentStore = new DocumentStore({getRemote: () => fetch('https://example.com/api')});\nawait documentStore.loadChunk(0);\n", + "description": "" }, "name": "loadChunk", "location": { @@ -377,28 +377,28 @@ "docLength": 11 }, { - "id": "4b40437b-c422-389e-1344-939c735058a4", + "id": "f08e4830-42bc-87b1-a444-9c7cfddab6a0", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Asynchronously retrieves a file from storage, given its path. It first checks if the document summary has been loaded and then loads the corresponding chunk and file index if necessary, before returning the requested file or null if it doesn't exist.", + "description": "Retrieves a file from storage based on its path, loading the necessary chunks if not already loaded. It then returns the file index within the chunk.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Required for calculating the chunk it is in and file index within that chunk, which are used to access the structured file or return null if not found or not loaded." + "type_name": "string", + "description": "Used to specify the file path to be loaded." } ], "returns": { - "type_name": "PromiseStructuredFile", - "description": "Either a `StructuredFile` object or null." + "type_name": "StructuredFile", + "description": "Either null if it's not a valid file path or a reference to a StructuredFile object containing information about the file located in the specified chunk and index within that chunk." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore();\nawait docStore.loadSummary();\n\ntry {\n const file = await docStore.getFile('path/to/file');\n} catch (error) {\n console.error(error);\n}\n", - "description": "\nThis code sets up a `DocumentStore` instance and then calls the `getFile` method with a specific path." + "code": "const getFile = async (path: string): Promise => {\n const documentStore: DocumentStore = new DocumentStore();\n return await documentStore.getFile(path);\n}\n", + "description": "" }, "name": "getFile", "location": { @@ -416,28 +416,28 @@ "docLength": 10 }, { - "id": "7378d4f1-3a4b-34a2-ef4d-492c2c802092", + "id": "bbe85948-2f1a-afaf-4f42-5ed60899a637", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Adds a new path to the end of the last lookup subtable if it is not full, or creates a new one if the previous one is full. It uses an array of arrays (lookup) to store paths in chunks of size CHUNK_SIZE.", + "description": "Updates the lookup subtable by adding new path to the end or creating a new subtable if the last one is full.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Required for the function to work properly. It represents a path that needs to be added to the lookup table." + "type_name": "string", + "description": "The path to be added to the end of the lookup subtable." } ], "returns": { - "type_name": "unction", - "description": "To be used as an event handler for adding a new path to the end of the lookup subtable." + "type_name": "string", + "description": "The new path added to the end of the lookup table." }, "usage": { "language": "typescript", - "code": "let store = new DocumentStore();\nstore CHUNK_SIZE = 3;\nstore.addToEndOfLookup('path/to/lookup'); // Add a path to the lookup\nstore.addToEndOfLookup('path/to/new/lookup');\nstore.addToEndOfLookup('path/to/yet/another/lookup');\n", - "description": "\nThe above example demonstrates adding multiple paths to the end of the `lookup` array." + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.CHUNK_SIZE = 10;\ndocumentStore.namespace = 'my-namespace';\ndocumentStore.metaTemplate = {\n version: '1.0',\n created_at: new Date(),\n};\ndocumentStore.lookup = [];\ndocumentStore.chunks = [];\ndocumentStore.content = [];\ndocumentStore.status = {\n summary: false,\n chunks: false,\n};\n", + "description": "\nHere is an example of how the method `addToEndOfLookup` could be used in practice:\n" }, "name": "addToEndOfLookup", "location": { @@ -455,27 +455,27 @@ "docLength": 6 }, { - "id": "b51a6c97-c0dc-0988-294a-c4da7c4b25e4", + "id": "6305eadc-2e9b-5099-3848-fe78852ded5d", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Adds a file to the end of an existing chunk or creates a new chunk if the current one is full, according to the predefined `CHUNK_SIZE`. It modifies the internal state of the object by updating its `chunks` property.", + "description": "Manages the chunks of a structured file, adding new files to the end of an existing chunk or creating a new one if the last one is full.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Expected to be an object or value that represents a file, but its exact structure and content are not specified." + "type_name": "StructuredFile", + "description": "Represented by an object containing various properties related to the file being processed, such as its name, size, and content." } ], "returns": { - "type_name": "undefined", - "description": "Implicit since there are no explicit statements that assign a value to it." + "type_name": "StructuredFile", + "description": "A new chunk containing the given file if the last lookup subtable is full, otherwise it adds the file to the end of the previous chunk." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(\n async (...args: any[]) => Promise.resolve({ /* ... */ }),\n /* ... */\n);\n\nstore.addToEndOfChunks({\n namespace: 'test',\n content: 'this is a test',\n meta: {\n version: '1.0',\n },\n});\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks(file);\n", "description": "" }, "name": "addToEndOfChunks", @@ -494,27 +494,27 @@ "docLength": 10 }, { - "id": "f88e2e07-0a15-53b1-a24b-dd53e8c03ae5", + "id": "4d27688f-8f39-d7b4-6343-174bdfebbad2", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Adds a file to the store if it meets certain conditions. The file must have a path and not exist already, or be updated successfully if it does. The method returns a boolean indicating success or failure.", + "description": "Allows adding a file to the document store if the file exists and the status has chunks, otherwise it throws an error.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Required to be not null. It represents a file that needs to be added to the content, specified by its path." + "type_name": "StructuredFile", + "description": "Passed to the function as an argument." } ], "returns": { - "type_name": "boolean*", - "description": "True if a file was successfully added and false otherwise." + "type_name": "boolean", + "description": "1 if the file was added successfully and 0 otherwise." }, "usage": { "language": "typescript", - "code": "let store = new DocumentStore();\nstore.load();\nlet file1 = { path: 'file1.txt', content: 'Hello' };\nlet result1 = store.addFile(file1);\nif (result1) {\n let file2 = { path: 'file2.txt', content: 'World' };\n let result2 = store.addFile(file2);\n}\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addFile(file);\n", "description": "" }, "name": "addFile", @@ -533,27 +533,27 @@ "docLength": 10 }, { - "id": "c824704b-d147-cb8c-e343-9bc02e9ae549", + "id": "7b574861-e53d-1085-9e4f-a5ef25640dbf", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Asynchronously updates a file within a document's chunks, adding it if it does not exist. If the chunk is not loaded, it loads it first. The method returns a boolean indicating success or failure of the update operation.", + "description": "Updates a file in the store by checking if it exists, loading the chunk if necessary, and storing the updated file index in the chunk.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Required for updating files." + "type_name": "StructuredFile", + "description": "Passed to the function for updating." } ], "returns": { "type_name": "Promiseboolean", - "description": "Resolved to either `true` or `false`, indicating whether the file update operation was successful or failed respectively." + "description": "True if the file was successfully updated and false otherwise." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, { ... });\nconst file1 = {\n path: 'file1.txt',\n data: 'Hello, World!'\n};\ndocumentStore.updateFile(file1).then((updated) => {\n if (updated) {\n // Update successful\n } else {\n // Update failed\n }\n});\n", + "code": "const docStore = new DocumentStore({\ngetRemote, integration});\ndocStore.updateFile(file);\n", "description": "" }, "name": "updateFile", @@ -572,19 +572,19 @@ "docLength": 10 }, { - "id": "a900ab66-1a8b-199d-8e4f-5ed8a27eca9d", + "id": "1aae3ddf-86ae-30b5-7a43-c0be17cb7c81", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Returns an object with two properties, `meta` and `lookup`, which are populated from the instance variables `this.meta` and `this.lookup`, respectively. This method provides a summary representation of the document store's metadata and lookup data.", + "description": "Returns an object containing the class's `meta` and `lookup` properties.", "params": [], "returns": { - "type_name": "Summary*", - "description": "An object with two properties: meta and lookup, both inherited from this object." + "type_name": "Summary", + "description": "An object containing `meta` and `lookup`." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nconst result = store.outputSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -603,20 +603,20 @@ "docLength": 6 }, { - "id": "0dce4884-669f-f49a-ba41-c2a8e25b44b3", + "id": "ac3d5dcc-015e-6d96-f048-3b9d58202053", "ancestors": [ - "1cf68203-f64f-a695-8e4c-9d0ef4907991" + "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" ], - "description": "Splits its content into chunks, converts each chunk to a string, and stores them in a record as key-value pairs where keys are generated using the `chunkKeyToChunkPath` function. The method returns this record.", + "description": "Generates and returns a record of chunks extracted from a larger document, keyed by chunk path.", "params": [], "returns": { "type_name": "Recordstring", - "description": "An object containing a set of key-value pairs. Each key corresponds to a string path and each value corresponds to a chunk of content from the original data." + "description": "A collection of key-value pairs where each key is a unique identifier for a chunk of content and the corresponding value is the actual chunk of content." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore();\nstore.CHUNK_SIZE = 1024;\nstore.outputChunks()\n", - "description": "\nThis code creates an instance of a `DocumentStore` and then calls its `outputChunks()` method." + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputChunks();\n", + "description": "" }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index b43a08a..360d3cf 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-10T22:03:56.437Z", + "updated_at": "2024-07-11T08:03:21.154Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -11,7 +11,8 @@ "4857c9e7-9349-41a8-96c5-56be5ffb04cf", "75505a3a-f1af-4ca1-9174-9b908cdee0e4", "db654c98-5128-44f7-8691-252c69b9b5b7", - "fb518d01-fd0a-40bb-8d37-2ff5990c023b" + "fb518d01-fd0a-40bb-8d37-2ff5990c023b", + "49ec0772-f24b-4603-9a27-a31b96963bdf" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 69fea9c..3de949d 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,10 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Is responsible for managing and storing a collection of structured - * files (e.g., JSON documents) with metadata and file lookup functionality. It allows - * for efficient loading, updating, and retrieval of files, as well as generating - * summaries and chunking the content for storage or transmission. + * @description Stores and manages structured files for generating high-quality + * documentation. It loads and organizes content, handles chunking and summary creation, + * and provides methods for updating and querying the document store. * * @implements {IDocumentStore} */ @@ -47,20 +46,18 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Initializes an instance with a namespace, a getRemote method, and - * optional additional metadata. It sets default properties, validates input, and - * creates internal state (meta, lookup, chunks, content, and status). The constructor - * ensures that the namespace and getRemote method are provided. + * @description Sets up the class with a required namespace and getRemote method, + * initializes instance variables for chunk size, namespace, getRemote, metadata, and + * lookup arrays, and sets status to false for summary and chunks. * - * @param {string*} namespace - Required to be passed. It represents the namespace - * for which the constructor initializes its internal state. + * @param {string} namespace - Required, it represents the namespace for the document + * store. * - * @param {(...args: any[]) => Promise>*} getRemote - Required for - * constructor initialization. It returns a promise that resolves to an object with - * properties of any type when invoked with zero or more arguments. + * @param {(...args: any[]) => Promise>} getRemote - Required for + * constructing the chunker instance. * - * @param {Record*} additionalMeta - Used to initialize an object that - * holds additional metadata for the namespace. + * @param {Record} additionalMeta - Used to store any additional metadata + * required by the function. */ constructor( namespace: string, @@ -90,26 +87,22 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` property with the provided `Date` object, - * effectively setting the updated timestamp for the document. + * @description Updates the `updated_at` metadata for the document. * - * @param {Date*} updated_at - Assigned to `this.meta.updated_at`. It represents the - * date when the data was last updated. + * @param {Date} updated_at - Used to update the `updated_at` metadata of an entity. * - * @returns {unction} An instance method that sets the property `updated_at` of the - * object's metadata (`meta`). + * @returns {void} The result of updating the `meta` object's `updated_at` property + * with the provided `Date`. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Loads and updates the document summary from a remote source, storing - * it locally if available. If no data is retrieved, it initializes an empty summary - * with default values. It then sets local metadata fields based on the loaded or - * default summary values. + * @description Retrieves and updates a summary of documents stored in the store, + * including meta-data and chunk information. * - * @returns {asynchronous} A `Promise` that resolves to an object of type `Summary`. + * @returns {Summary} An object containing metadata and chunk information. */ loadSummary = async () => { let summary: Summary = { @@ -138,7 +131,8 @@ 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]) => { - // Maps metaTemplate keys to their corresponding values. + // Assigns values to meta object properties, using either + // the provided `summary.meta` object or the default value. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -147,12 +141,10 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Asynchronously loads and prepares data for display by checking if - * summary exists, loading it if not, and then retrieving specific chunks based on - * lookup indices, ultimately setting the `chunks` status to true upon completion. + * @description Asynchronous loads chunks of data from an index, updating the + * `status.chunks` property to indicate successful loading. * - * @returns {asynchronous} An undefined state indicating that it has started execution - * and is still running. + * @returns {void} Indicative that it does not have a return statement. */ load = async () => { if (!this.status.summary) { @@ -175,17 +167,13 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata object by merging it with an additional metadata - * object provided as an argument, allowing for dynamic modification and extension - * of metadata properties. + * @description Updates the metadata field of the class by merging the existing + * metadata with an additional metadata object. * - * @param {Record*} additionalMeta - Defined to represent an object with - * key-value pairs where keys are strings and values can be of any data type. It holds - * additional metadata information that needs to be updated in the current metadata - * object. + * @param {Record} additionalMeta - Used to add additional metadata to + * the function's meta data. * - * @returns {ƒunction} Ƒ an object where the properties are merged from the current - * metadata (`this.meta`) and additional metadata (`additionalMeta`). + * @returns {Recordstring} An immutable object containing the updated metadata data. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -201,15 +189,13 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Asynchronously loads a chunk of structured files from a remote location, - * concatenates it with the existing content, and stores it in the `chunks` object. - * If an error occurs during loading, it returns `false`. + * @description Async loads a chunk of data from a remote source and concats it with + * the existing content of the class, updating the internal chunks array. * - * @param {number*} chunkIndex - Required for the asynchronous chunk loading process. - * It represents an index that uniquely identifies a chunk of data to be loaded from - * a remote location. + * @param {number} chunkIndex - Used to reference the specific chunk being loaded, + * with values ranging from 0 to the total number of chunks - 1. * - * @returns {Promiseboolean} Resolved to either true or false. + * @returns {Promiseboolean} True if the chunk was successfully loaded and false otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -228,16 +214,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Asynchronously retrieves a file from storage, given its path. It first - * checks if the document summary has been loaded and then loads the corresponding - * chunk and file index if necessary, before returning the requested file or null if - * it doesn't exist. + * @description Retrieves a file from storage based on its path, loading the necessary + * chunks if not already loaded. It then returns the file index within the chunk. * - * @param {string*} path - Required for calculating the chunk it is in and file index - * within that chunk, which are used to access the structured file or return null if - * not found or not loaded. + * @param {string} path - Used to specify the file path to be loaded. * - * @returns {PromiseStructuredFile} Either a `StructuredFile` object or null. + * @returns {StructuredFile} Either null if it's not a valid file path or a reference + * to a StructuredFile object containing information about the file located in the + * specified chunk and index within that chunk. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -280,15 +264,12 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of the last lookup subtable if it is not - * full, or creates a new one if the previous one is full. It uses an array of arrays - * (lookup) to store paths in chunks of size CHUNK_SIZE. + * @description Updates the lookup subtable by adding new path to the end or creating + * a new subtable if the last one is full. * - * @param {string*} path - Required for the function to work properly. It represents - * a path that needs to be added to the lookup table. + * @param {string} path - The path to be added to the end of the lookup subtable. * - * @returns {unction} To be used as an event handler for adding a new path to the end - * of the lookup subtable. + * @returns {string} The new path added to the end of the lookup table. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -302,15 +283,14 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the end of an existing chunk or creates a new chunk - * if the current one is full, according to the predefined `CHUNK_SIZE`. It modifies - * the internal state of the object by updating its `chunks` property. + * @description Manages the chunks of a structured file, adding new files to the end + * of an existing chunk or creating a new one if the last one is full. * - * @param {StructuredFile*} file - Expected to be an object or value that represents - * a file, but its exact structure and content are not specified. + * @param {StructuredFile} file - Represented by an object containing various properties + * related to the file being processed, such as its name, size, and content. * - * @returns {undefined} Implicit since there are no explicit statements that assign - * a value to it. + * @returns {StructuredFile} A new chunk containing the given file if the last lookup + * subtable is full, otherwise it adds the file to the end of the previous chunk. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -324,14 +304,12 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the store if it meets certain conditions. The file - * must have a path and not exist already, or be updated successfully if it does. The - * method returns a boolean indicating success or failure. + * @description Allows adding a file to the document store if the file exists and the + * status has chunks, otherwise it throws an error. * - * @param {StructuredFile*} file - Required to be not null. It represents a file that - * needs to be added to the content, specified by its path. + * @param {StructuredFile} file - Passed to the function as an argument. * - * @returns {boolean*} True if a file was successfully added and false otherwise. + * @returns {boolean} 1 if the file was added successfully and 0 otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -354,14 +332,12 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Asynchronously updates a file within a document's chunks, adding it - * if it does not exist. If the chunk is not loaded, it loads it first. The method - * returns a boolean indicating success or failure of the update operation. + * @description Updates a file in the store by checking if it exists, loading the + * chunk if necessary, and storing the updated file index in the chunk. * - * @param {StructuredFile*} file - Required for updating files. + * @param {StructuredFile} file - Passed to the function for updating. * - * @returns {Promiseboolean} Resolved to either `true` or `false`, indicating whether - * the file update operation was successful or failed respectively. + * @returns {Promiseboolean} True if the file was successfully updated and false otherwise. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -391,13 +367,9 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object with two properties, `meta` and `lookup`, which are - * populated from the instance variables `this.meta` and `this.lookup`, respectively. - * This method provides a summary representation of the document store's metadata and - * lookup data. + * @description Returns an object containing the class's `meta` and `lookup` properties. * - * @returns {Summary*} An object with two properties: meta and lookup, both inherited - * from this object. + * @returns {Summary} An object containing `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -406,13 +378,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Splits its content into chunks, converts each chunk to a string, and - * stores them in a record as key-value pairs where keys are generated using the - * `chunkKeyToChunkPath` function. The method returns this record. + * @description Generates and returns a record of chunks extracted from a larger + * document, keyed by chunk path. * - * @returns {Recordstring} An object containing a set of key-value pairs. Each key - * corresponds to a string path and each value corresponds to a chunk of content from - * the original data. + * @returns {Recordstring} A collection of key-value pairs where each key is a unique + * identifier for a chunk of content and the corresponding value is the actual chunk + * of content. */ outputChunks(): Record { const outputs: Record = {}; From b4211b38a3fa3418dfc4ecd4088f698751e8b073 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Thu, 11 Jul 2024 08:16:08 +0000 Subject: [PATCH 16/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 234 +++++++++++++++++++----------------------- .komment/komment.json | 5 +- src/index.ts | 147 +++++++++++++------------- 3 files changed, 184 insertions(+), 202 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index ee42806..fe578bf 100644 --- a/.komment/00000.json +++ b/.komment/00000.json @@ -4,12 +4,12 @@ "path": "src/index.ts", "content": { "structured": { - "description": "A `DocumentStore` class for managing adding, retrieving, and updating documentation for code. It includes several methods for performing these actions, such as `loadSummary`, `load`, `addFile`, and `updateFile`. The code also uses various types and packages, including `IDocumentStore`, `StructuredFile`, `SUMMARY`, and `CHUNK_SIZE`. Overall, the code appears to provide a way to organize and manage documentation for code in a structured manner.", + "description": "A DocumentStore class that manages structured data files by dividing them into chunks and storing these chunks in lookup subtables. The store can add new files, update existing ones, and provide summaries of the stored documents. It uses an internal array to keep track of file paths, another for chunked files, and a third for content.", "items": [ { - "id": "a35f71f6-f4c7-2184-cb49-6f8eceb5b941", + "id": "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba", "ancestors": [], - "description": "Stores and manages structured files for generating high-quality documentation. It loads and organizes content, handles chunking and summary creation, and provides methods for updating and querying the document store.", + "description": "Is a data structure designed to efficiently manage and load structured files (e.g., JSON) from remote sources, handling chunking, caching, and lookup operations for fast access and retrieval of file contents.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "Used to define the size of each chunk in the code document store." + "description": "256 by default. It represents the maximum size of each chunk of files within a sequence, ensuring that chunks do not become too large or too small." }, { "name": "namespace", "type_name": "string", - "description": "Required for creating a DocumentStore instance. It represents the name or identifier of the domain or application to which the document store belongs." + "description": "Used to define a unique identifier for each document or file stored in the store, allowing for efficient lookup and retrieval of specific documents." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the document collection, such as version number, creation date, and update date." + "description": "Used to store metadata about the structured file." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used for initializing internal arrays and objects to store chunk data, content, or other meta information." + "description": "Not defined within the given code snippet. It seems to be a property for storing metadata templates or configurations." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a list of sub-arrays, each representing a chunk of files within a larger document structure." + "description": "2D array that stores file paths, it contains subtables which are arrays of strings representing file paths within each chunk of the document." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store chunks of content from the DocumentStore's internal arrays." + "description": "Used to store the chunks of files loaded from a provider into memory, with each chunk representing a group of files with similar sizes and stored as an array of file objects." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store the contents of files within the document store. It is used as a variable for method calls such as `addFile` and `updateFile`." + "description": "Used to store a list of files, where each file is represented by a `StructuredFile` object. The content includes information about the files such as their paths, names, and other properties." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to store information about the state of the document store, such as whether the summary has been loaded or not." + "description": "Used to store the current status of the document." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "acba2c29-7903-5a93-084a-18251e6aa2c5", + "id": "56b36345-db8f-3ab9-8a4b-ecf499dc467e", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Sets up the class with a required namespace and getRemote method, initializes instance variables for chunk size, namespace, getRemote, metadata, and lookup arrays, and sets status to false for summary and chunks.", + "description": "Initializes an instance by validating required parameters, setting default properties, and creating metadata with version information, timestamps, and additional user-provided data.", "params": [ { "name": "namespace", - "type_name": "string", + "type_name": "string*", "optional": false, - "description": "Required, it represents the namespace for the document store.", + "description": "Required. It represents the namespace for this document store instance and is used to identify it uniquely.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>", + "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required for constructing the chunker instance.", + "description": "Required to be provided when constructing an object. It seems to represent a remote method that returns a promise resolving to a dictionary.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record", + "type_name": "Record*", "optional": true, - "description": "Used to store any additional metadata required by the function.", + "description": "Used to represent additional metadata about the namespace. It contains key-value pairs where keys are strings and values can be of any type.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\n \"my-namespace\",\n async (...args) => {\n // Get remote docs from a provider\n },\n { version: \"1.0\" }\n);\n\n// Set the updated_at field of the meta object with a new Date() value\ndocumentStore.setUpdatedAt(new Date());\n\n// Load document summaries from a provider and update local meta data based on the remote summary\nawait documentStore.loadSummary();\n", - "description": "" + "code": "const documentStore = new DocumentStore('namespace', async () => {\n // getRemote implementation\n return { foo: 'bar' };\n}, { extraMetaKey: 'extraMetaValue' });\n", + "description": "\nThis will create a new instance of the `DocumentStore` class with namespace `'namespace'`, using the provided `getRemote` method, and additional metadata `{ extraMetaKey: 'extraMetaValue' }`." }, "name": null, "location": { @@ -182,27 +182,23 @@ "docLength": 12 }, { - "id": "b431a994-a1eb-a9bf-b84c-c00c54ad64f2", + "id": "ffa0e742-e740-0ab8-ab41-568bd8cb6548", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Updates the `updated_at` metadata for the document.", + "description": "Updates the `updated_at` property with the provided `Date` object, effectively changing the timestamp when the document was last updated.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date", - "description": "Used to update the `updated_at` metadata of an entity." + "type_name": "Date*", + "description": "Assigned to `this.meta.updated_at`." } ], - "returns": { - "type_name": "void", - "description": "The result of updating the `meta` object's `updated_at` property with the provided `Date`." - }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.setUpdatedAt(new Date());\n", + "code": "const store = new DocumentStore();\nconst updated_at = new Date('2023-01-25T14:30:00.000Z');\nstore.setUpdatedAt(updated_at);\n", "description": "" }, "name": "setUpdatedAt", @@ -221,19 +217,15 @@ "docLength": 7 }, { - "id": "e1aad662-7b87-3ea6-b64d-80c873f32a4e", + "id": "6b10bae6-6671-9897-9444-769fc2393d3d", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Retrieves and updates a summary of documents stored in the store, including meta-data and chunk information.", + "description": "Loads and updates metadata and data from a remote source, merging local and remote data. If no data is stored, it logs a message and sets default values.", "params": [], - "returns": { - "type_name": "Summary", - "description": "An object containing metadata and chunk information." - }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote);\ndocStore.loadSummary();\n", + "code": "const documentStore = new DocumentStore();\ndocumentStore.metaTemplate = {template: 'template'};\nawait documentStore.loadSummary();\n", "description": "" }, "name": "loadSummary", @@ -252,12 +244,12 @@ "docLength": 4 }, { - "id": "2308d1bd-4571-dfb9-854a-122be7d3a602", + "id": "03692d3e-ca07-5b8d-3a4e-2bdf8428e2ee", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941", - "e1aad662-7b87-3ea6-b64d-80c873f32a4e" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba", + "6b10bae6-6671-9897-9444-769fc2393d3d" ], - "description": "Assigns values to meta object properties, using either \nthe provided `summary.meta` object or the default value.", + "description": "Maps metaTemplate properties to meta properties with fallbacks.", "name": null, "location": { "start": 121, @@ -271,20 +263,16 @@ "docLength": null }, { - "id": "8affd1e3-0165-1ca9-6542-f2facb534dbb", + "id": "6c121aa5-3b41-6299-f24c-a978e34bd980", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Asynchronous loads chunks of data from an index, updating the `status.chunks` property to indicate successful loading.", + "description": "Asynchronously loads document summary and chunks when called. It first checks if the summary is loaded, then loads chunks based on the lookup indices. Once all chunks are loaded, it sets the `chunks` status to true.", "params": [], - "returns": { - "type_name": "void", - "description": "Indicative that it does not have a return statement." - }, "usage": { "language": "typescript", - "code": "let documentStore = new DocumentStore(getRemote);\ndocumentStore.CHUNK_SIZE = 100;\ndocumentStore.namespace = 'my-namespace';\ndocumentStore.metaTemplate = {\n version: '1.0.0',\n created_at: Date,\n updated_at: Date,\n};\nawait documentStore.load();\n", - "description": "" + "code": "const docStore = new DocumentStore();\ndocStore.getRemote = async (args: any[]) => Promise.resolve({});\n\nawait docStore.load();\n", + "description": "\nNote that this code snippet assumes the existence of `getRemote` property on `DocumentStore` instance, as specified in the parent class code provided." }, "name": "load", "location": { @@ -302,27 +290,23 @@ "docLength": 3 }, { - "id": "34b963b3-6525-3489-524e-98846f861801", + "id": "c4d8b2fd-b05e-5d8c-4740-3c0b38792ae2", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Updates the metadata field of the class by merging the existing metadata with an additional metadata object.", + "description": "Updates the metadata object by merging it with additional metadata provided as an argument. It uses the spread operator to combine the existing metadata with the new metadata, resulting in a new updated metadata object.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record", - "description": "Used to add additional metadata to the function's meta data." + "type_name": "Record*", + "description": "Passed as an argument to this function." } ], - "returns": { - "type_name": "Recordstring", - "description": "An immutable object containing the updated metadata data." - }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.updateMetadata({ version: '1.0', created_at: Date.now() });\n", + "code": "const ds = new DocumentStore();\nds.updateMetadata({\n customField: 'someValue',\n});\n", "description": "" }, "name": "updateMetadata", @@ -338,27 +322,27 @@ "docLength": null }, { - "id": "49e3ed05-4e7c-7c87-824c-3fde323f38f1", + "id": "54eff05c-e84f-f997-7342-6fa3540012ae", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Async loads a chunk of data from a remote source and concats it with the existing content of the class, updating the internal chunks array.", + "description": "Asynchronously loads a chunk of structured files from a remote location if it's not already loaded, and updates the local storage with the new content. It returns a boolean indicating whether the load was successful or not.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number", - "description": "Used to reference the specific chunk being loaded, with values ranging from 0 to the total number of chunks - 1." + "type_name": "number*", + "description": "Used as an index for accessing the chunks of data stored in the `chunks` object. It represents the specific chunk to be loaded from the remote location." } ], "returns": { - "type_name": "Promiseboolean", - "description": "True if the chunk was successfully loaded and false otherwise." + "type_name": "Promise*", + "description": "Resolved to either `true` (if the chunk loading is successful) or `false` (in case of an error)." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore({getRemote: () => fetch('https://example.com/api')});\nawait documentStore.loadChunk(0);\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\n\ndocumentStore.loadChunk(1).then((result) => {\n if (!result) {\n console.error(\"Failed to load chunk\");\n } else {\n // do something with the loaded chunk\n }\n});\n", "description": "" }, "name": "loadChunk", @@ -377,27 +361,27 @@ "docLength": 11 }, { - "id": "f08e4830-42bc-87b1-a444-9c7cfddab6a0", + "id": "b3159cd7-47e6-83a4-f44b-36fbe4ef093a", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Retrieves a file from storage based on its path, loading the necessary chunks if not already loaded. It then returns the file index within the chunk.", + "description": "Asynchronously retrieves a file from storage based on its path, ensuring that the required summary is loaded first and loading the corresponding chunk if necessary.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "Used to specify the file path to be loaded." + "type_name": "string*", + "description": "Used to specify the path of the file for which the structured file information should be retrieved." } ], "returns": { - "type_name": "StructuredFile", - "description": "Either null if it's not a valid file path or a reference to a StructuredFile object containing information about the file located in the specified chunk and index within that chunk." + "type_name": "Promise*", + "description": "Resolved to either a structured file object (of type StructuredFile) or null." }, "usage": { "language": "typescript", - "code": "const getFile = async (path: string): Promise => {\n const documentStore: DocumentStore = new DocumentStore();\n return await documentStore.getFile(path);\n}\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary();\n\nconst file1 = await documentStore.getFile('path/to/file1');\nconst file2 = await documentStore.getFile('path/to/file2');\n", "description": "" }, "name": "getFile", @@ -416,28 +400,24 @@ "docLength": 10 }, { - "id": "bbe85948-2f1a-afaf-4f42-5ed60899a637", + "id": "727487bc-b1fe-daab-eb49-763a41753caf", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Updates the lookup subtable by adding new path to the end or creating a new subtable if the last one is full.", + "description": "Adds a path to the end of the current lookup subtable if it's not full, otherwise creates a new one. It checks if the last subtable is empty or has reached its chunk size before adding the path.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "The path to be added to the end of the lookup subtable." + "type_name": "string*", + "description": "Passed as an argument to the function, which it uses to determine whether to create a new subtable in the `lookup` array or add the path to the last existing subtable." } ], - "returns": { - "type_name": "string", - "description": "The new path added to the end of the lookup table." - }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.CHUNK_SIZE = 10;\ndocumentStore.namespace = 'my-namespace';\ndocumentStore.metaTemplate = {\n version: '1.0',\n created_at: new Date(),\n};\ndocumentStore.lookup = [];\ndocumentStore.chunks = [];\ndocumentStore.content = [];\ndocumentStore.status = {\n summary: false,\n chunks: false,\n};\n", - "description": "\nHere is an example of how the method `addToEndOfLookup` could be used in practice:\n" + "code": "const documentStore = new DocumentStore();\ndocumentStore CHUNK_SIZE = 10;\ndocumentStore.addToEndOfLookup(\"path1\");\ndocumentStore.addToEndOfLookup(\"path2\");\ndocumentStore.addToEndOfLookup(\"path3\");\n", + "description": "\n\nNote: The above example is a minimal illustration of the usage of `addToEndOfLookup` method in the class `DocumentStore`." }, "name": "addToEndOfLookup", "location": { @@ -455,28 +435,24 @@ "docLength": 6 }, { - "id": "6305eadc-2e9b-5099-3848-fe78852ded5d", + "id": "7c066604-f908-feb0-f240-61129040b2cc", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Manages the chunks of a structured file, adding new files to the end of an existing chunk or creating a new one if the last one is full.", + "description": "Adds a `StructuredFile` to either a new or an existing chunk, depending on whether the last chunk is full. It ensures that each chunk does not exceed the specified `CHUNK_SIZE`.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Represented by an object containing various properties related to the file being processed, such as its name, size, and content." + "type_name": "StructuredFile*", + "description": "Required for processing and manipulation within the function." } ], - "returns": { - "type_name": "StructuredFile", - "description": "A new chunk containing the given file if the last lookup subtable is full, otherwise it adds the file to the end of the previous chunk." - }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks(file);\n", - "description": "" + "code": "const file1 = new StructuredFile();\nconst file2 = new StructuredFile();\n\ndocumentStore.addToEndOfChunks(file1);\ndocumentStore.addToEndOfChunks(file2);\n", + "description": "\nIt adds two structured files to the end of the chunks." }, "name": "addToEndOfChunks", "location": { @@ -494,27 +470,27 @@ "docLength": 10 }, { - "id": "4d27688f-8f39-d7b4-6343-174bdfebbad2", + "id": "8098b249-995e-dcaf-ea48-7d1379f326fd", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Allows adding a file to the document store if the file exists and the status has chunks, otherwise it throws an error.", + "description": "Adds a file to the store if it exists and its path has not been previously added. If the file already exists, it updates the existing file; otherwise, it appends the new file to the end of the lookup and chunk lists.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Passed to the function as an argument." + "type_name": "StructuredFile*", + "description": "Mandatory for the function to execute successfully. It must be provided with valid data, specifically including a path property." } ], "returns": { - "type_name": "boolean", - "description": "1 if the file was added successfully and 0 otherwise." + "type_name": "boolean*", + "description": "True if the file was successfully added, and false otherwise." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addFile(file);\n", + "code": "const documentStore = new DocumentStore();\ndocumentStore.load().then(() => {\n const file1 = { path: 'file1.txt', content: 'Hello World' };\n const result1 = documentStore.addFile(file1);\n if (result1) console.log('File added successfully');\n});\n", "description": "" }, "name": "addFile", @@ -533,27 +509,27 @@ "docLength": 10 }, { - "id": "7b574861-e53d-1085-9e4f-a5ef25640dbf", + "id": "0178bd9b-6fa2-f383-4348-0d4a604d7e2e", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Updates a file in the store by checking if it exists, loading the chunk if necessary, and storing the updated file index in the chunk.", + "description": "Updates a file by adding or replacing it in a chunk, if the chunk exists and is loaded. If not loaded, it loads the chunk first. The method returns a boolean indicating success.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Passed to the function for updating." + "type_name": "StructuredFile*", + "description": "Required for this method. If no file is provided, it returns false immediately." } ], "returns": { - "type_name": "Promiseboolean", - "description": "True if the file was successfully updated and false otherwise." + "type_name": "Promise*", + "description": "Either a promise that resolves to `true` if the file update operation is successful or `false` otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore({\ngetRemote, integration});\ndocStore.updateFile(file);\n", + "code": "const store = new DocumentStore(getRemote, integration);\nstore.load();\nconst file = {\n path: '/path/to/file',\n contents: 'file content'\n};\nstore.updateFile(file).then(result => console.log(result));\n", "description": "" }, "name": "updateFile", @@ -572,19 +548,19 @@ "docLength": 10 }, { - "id": "1aae3ddf-86ae-30b5-7a43-c0be17cb7c81", + "id": "3efe624f-b41c-3eba-d144-cd456cec1d1b", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Returns an object containing the class's `meta` and `lookup` properties.", + "description": "Returns an object with two properties, `meta` and `lookup`, which are initialized from the corresponding instance variables `this.meta` and `this.lookup`. The purpose is to provide a compact representation of the document store's metadata and lookup data.", "params": [], "returns": { - "type_name": "Summary", - "description": "An object containing `meta` and `lookup`." + "type_name": "Summary*", + "description": "An object with two properties: meta and lookup." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputSummary();\n", + "code": "const store = new DocumentStore(getRemote, integration);\nconst summary = store.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -603,19 +579,19 @@ "docLength": 6 }, { - "id": "ac3d5dcc-015e-6d96-f048-3b9d58202053", + "id": "78c42646-c9a9-1bad-a04e-e6e6a31d48ed", "ancestors": [ - "a35f71f6-f4c7-2184-cb49-6f8eceb5b941" + "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" ], - "description": "Generates and returns a record of chunks extracted from a larger document, keyed by chunk path.", + "description": "Splits its internal content into chunks, each with a fixed size specified by `CHUNK_SIZE`, and stores them as key-value pairs in a Record object, where keys are generated from chunk indices using `chunkIndexToChunkKey` and `chunkKeyToChunkPath`.", "params": [], "returns": { - "type_name": "Recordstring", - "description": "A collection of key-value pairs where each key is a unique identifier for a chunk of content and the corresponding value is the actual chunk of content." + "type_name": "Record*", + "description": "A collection of key-value pairs where keys are strings and values are of any data type." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputChunks();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\n\ndocumentStore.outputChunks();\n", "description": "" }, "name": "outputChunks", diff --git a/.komment/komment.json b/.komment/komment.json index 360d3cf..772d9fb 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-11T08:03:21.154Z", + "updated_at": "2024-07-11T08:16:01.246Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -12,7 +12,8 @@ "75505a3a-f1af-4ca1-9174-9b908cdee0e4", "db654c98-5128-44f7-8691-252c69b9b5b7", "fb518d01-fd0a-40bb-8d37-2ff5990c023b", - "49ec0772-f24b-4603-9a27-a31b96963bdf" + "49ec0772-f24b-4603-9a27-a31b96963bdf", + "e7cb8cbb-d12f-4f42-adcc-cdf3756c8071" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 3de949d..787e24a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Stores and manages structured files for generating high-quality - * documentation. It loads and organizes content, handles chunking and summary creation, - * and provides methods for updating and querying the document store. + * @description Is a data structure designed to efficiently manage and load structured + * files (e.g., JSON) from remote sources, handling chunking, caching, and lookup + * operations for fast access and retrieval of file contents. * * @implements {IDocumentStore} */ @@ -46,18 +46,20 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up the class with a required namespace and getRemote method, - * initializes instance variables for chunk size, namespace, getRemote, metadata, and - * lookup arrays, and sets status to false for summary and chunks. + * @description Initializes an instance by validating required parameters, setting + * default properties, and creating metadata with version information, timestamps, + * and additional user-provided data. * - * @param {string} namespace - Required, it represents the namespace for the document - * store. + * @param {string*} namespace - Required. It represents the namespace for this document + * store instance and is used to identify it uniquely. * - * @param {(...args: any[]) => Promise>} getRemote - Required for - * constructing the chunker instance. + * @param {(...args: any[]) => Promise>*} getRemote - Required to + * be provided when constructing an object. It seems to represent a remote method + * that returns a promise resolving to a dictionary. * - * @param {Record} additionalMeta - Used to store any additional metadata - * required by the function. + * @param {Record*} additionalMeta - Used to represent additional metadata + * about the namespace. It contains key-value pairs where keys are strings and values + * can be of any type. */ constructor( namespace: string, @@ -87,22 +89,18 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata for the document. + * @description Updates the `updated_at` property with the provided `Date` object, + * effectively changing the timestamp when the document was last updated. * - * @param {Date} updated_at - Used to update the `updated_at` metadata of an entity. - * - * @returns {void} The result of updating the `meta` object's `updated_at` property - * with the provided `Date`. + * @param {Date*} updated_at - Assigned to `this.meta.updated_at`. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates a summary of documents stored in the store, - * including meta-data and chunk information. - * - * @returns {Summary} An object containing metadata and chunk information. + * @description Loads and updates metadata and data from a remote source, merging + * local and remote data. If no data is stored, it logs a message and sets default values. */ loadSummary = async () => { let summary: Summary = { @@ -131,8 +129,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 values to meta object properties, using either - // the provided `summary.meta` object or the default value. + // Maps metaTemplate properties to meta properties with fallbacks. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -141,10 +138,9 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Asynchronous loads chunks of data from an index, updating the - * `status.chunks` property to indicate successful loading. - * - * @returns {void} Indicative that it does not have a return statement. + * @description Asynchronously loads document summary and chunks when called. It first + * checks if the summary is loaded, then loads chunks based on the lookup indices. + * Once all chunks are loaded, it sets the `chunks` status to true. */ load = async () => { if (!this.status.summary) { @@ -167,13 +163,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata field of the class by merging the existing - * metadata with an additional metadata object. + * @description Updates the metadata object by merging it with additional metadata + * provided as an argument. It uses the spread operator to combine the existing + * metadata with the new metadata, resulting in a new updated metadata object. * - * @param {Record} additionalMeta - Used to add additional metadata to - * the function's meta data. - * - * @returns {Recordstring} An immutable object containing the updated metadata data. + * @param {Record*} additionalMeta - Passed as an argument to this function. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -189,13 +183,16 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Async loads a chunk of data from a remote source and concats it with - * the existing content of the class, updating the internal chunks array. + * @description Asynchronously loads a chunk of structured files from a remote location + * if it's not already loaded, and updates the local storage with the new content. + * It returns a boolean indicating whether the load was successful or not. * - * @param {number} chunkIndex - Used to reference the specific chunk being loaded, - * with values ranging from 0 to the total number of chunks - 1. + * @param {number*} chunkIndex - Used as an index for accessing the chunks of data + * stored in the `chunks` object. It represents the specific chunk to be loaded from + * the remote location. * - * @returns {Promiseboolean} True if the chunk was successfully loaded and false otherwise. + * @returns {Promise*} Resolved to either `true` (if the chunk loading is + * successful) or `false` (in case of an error). */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -214,14 +211,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from storage based on its path, loading the necessary - * chunks if not already loaded. It then returns the file index within the chunk. + * @description Asynchronously retrieves a file from storage based on its path, + * ensuring that the required summary is loaded first and loading the corresponding + * chunk if necessary. * - * @param {string} path - Used to specify the file path to be loaded. + * @param {string*} path - Used to specify the path of the file for which the structured + * file information should be retrieved. * - * @returns {StructuredFile} Either null if it's not a valid file path or a reference - * to a StructuredFile object containing information about the file located in the - * specified chunk and index within that chunk. + * @returns {Promise*} Resolved to either a structured file + * object (of type StructuredFile) or null. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -264,12 +262,13 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Updates the lookup subtable by adding new path to the end or creating - * a new subtable if the last one is full. - * - * @param {string} path - The path to be added to the end of the lookup subtable. + * @description Adds a path to the end of the current lookup subtable if it's not + * full, otherwise creates a new one. It checks if the last subtable is empty or has + * reached its chunk size before adding the path. * - * @returns {string} The new path added to the end of the lookup table. + * @param {string*} path - Passed as an argument to the function, which it uses to + * determine whether to create a new subtable in the `lookup` array or add the path + * to the last existing subtable. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -283,14 +282,12 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Manages the chunks of a structured file, adding new files to the end - * of an existing chunk or creating a new one if the last one is full. - * - * @param {StructuredFile} file - Represented by an object containing various properties - * related to the file being processed, such as its name, size, and content. + * @description Adds a `StructuredFile` to either a new or an existing chunk, depending + * on whether the last chunk is full. It ensures that each chunk does not exceed the + * specified `CHUNK_SIZE`. * - * @returns {StructuredFile} A new chunk containing the given file if the last lookup - * subtable is full, otherwise it adds the file to the end of the previous chunk. + * @param {StructuredFile*} file - Required for processing and manipulation within + * the function. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -304,12 +301,14 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Allows adding a file to the document store if the file exists and the - * status has chunks, otherwise it throws an error. + * @description Adds a file to the store if it exists and its path has not been + * previously added. If the file already exists, it updates the existing file; + * otherwise, it appends the new file to the end of the lookup and chunk lists. * - * @param {StructuredFile} file - Passed to the function as an argument. + * @param {StructuredFile*} file - Mandatory for the function to execute successfully. + * It must be provided with valid data, specifically including a path property. * - * @returns {boolean} 1 if the file was added successfully and 0 otherwise. + * @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"); @@ -332,12 +331,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the store by checking if it exists, loading the - * chunk if necessary, and storing the updated file index in the chunk. + * @description Updates a file by adding or replacing it in a chunk, if the chunk + * exists and is loaded. If not loaded, it loads the chunk first. The method returns + * a boolean indicating success. * - * @param {StructuredFile} file - Passed to the function for updating. + * @param {StructuredFile*} file - Required for this method. If no file is provided, + * it returns false immediately. * - * @returns {Promiseboolean} True if the file was successfully updated and false otherwise. + * @returns {Promise*} Either a promise that resolves to `true` if the file + * update operation is successful or `false` otherwise. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -367,9 +369,12 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing the class's `meta` and `lookup` properties. + * @description Returns an object with two properties, `meta` and `lookup`, which are + * initialized from the corresponding instance variables `this.meta` and `this.lookup`. + * The purpose is to provide a compact representation of the document store's metadata + * and lookup data. * - * @returns {Summary} An object containing `meta` and `lookup`. + * @returns {Summary*} An object with two properties: meta and lookup. */ outputSummary(): Summary { return { @@ -378,12 +383,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Generates and returns a record of chunks extracted from a larger - * document, keyed by chunk path. + * @description Splits its internal content into chunks, each with a fixed size + * specified by `CHUNK_SIZE`, and stores them as key-value pairs in a Record object, + * where keys are generated from chunk indices using `chunkIndexToChunkKey` and `chunkKeyToChunkPath`. * - * @returns {Recordstring} A collection of key-value pairs where each key is a unique - * identifier for a chunk of content and the corresponding value is the actual chunk - * of content. + * @returns {Record*} A collection of key-value pairs where keys are + * strings and values are of any data type. */ outputChunks(): Record { const outputs: Record = {}; From 86393001dc099e0809b51faabb79bea2e001b1e5 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Thu, 11 Jul 2024 09:25:37 +0000 Subject: [PATCH 17/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 180 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 142 ++++++++++++++++----------------- 3 files changed, 160 insertions(+), 167 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index fe578bf..369748f 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 data files by dividing them into chunks and storing these chunks in lookup subtables. The store can add new files, update existing ones, and provide summaries of the stored documents. It uses an internal array to keep track of file paths, another for chunked files, and a third for content.", + "description": "A class called DocumentStore that provides an efficient way to manage and store structured files, which are composed of chunks of code with a specified size. The class utilizes two main data structures: `lookup` and `chunks`, both of which are arrays of file paths and chunked content respectively. It also includes methods for adding new files, updating existing ones, loading chunks as needed, and generating summaries and records of the stored chunks.", "items": [ { - "id": "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba", + "id": "749b009b-0d66-d5a4-2f4f-56de149adb1f", "ancestors": [], - "description": "Is a data structure designed to efficiently manage and load structured files (e.g., JSON) from remote sources, handling chunking, caching, and lookup operations for fast access and retrieval of file contents.", + "description": "Manages structured files and their chunks, providing methods for loading, updating, and retrieving files, as well as maintaining metadata and lookup tables. It is designed to efficiently store and retrieve large amounts of data organized into chunks.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "256 by default. It represents the maximum size of each chunk of files within a sequence, ensuring that chunks do not become too large or too small." + "description": "1-based index for chunks within a document, which determines how many files should be contained within each chunk." }, { "name": "namespace", "type_name": "string", - "description": "Used to define a unique identifier for each document or file stored in the store, allowing for efficient lookup and retrieval of specific documents." + "description": "Used to store a namespace for files, allowing them to be uniquely identified within the document structure." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the structured file." + "description": "Used to store metadata about the document." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Not defined within the given code snippet. It seems to be a property for storing metadata templates or configurations." + "description": "Not used anywhere in this code. It seems to be a leftover from another development iteration or a comment for future reference." }, { "name": "lookup", "type_name": "string[][]", - "description": "2D array that stores file paths, it contains subtables which are arrays of strings representing file paths within each chunk of the document." + "description": "2D array representing a lookup table for files in the document store. It stores file paths as strings and maps them to chunk indices and file indexes within those chunks." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store the chunks of files loaded from a provider into memory, with each chunk representing a group of files with similar sizes and stored as an array of file objects." + "description": "2D array that stores the structured files within each chunk, with each inner array representing a chunk's contents and its length being equal to the specified CHUNK_SIZE." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store a list of files, where each file is represented by a `StructuredFile` object. The content includes information about the files such as their paths, names, and other properties." + "description": "An array that stores all the files in the document store. It contains an ordered sequence of file objects. Each object represents a file in the document, including its path and other properties." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to store the current status of the document." + "description": "Not fully defined in the given code snippet." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "56b36345-db8f-3ab9-8a4b-ecf499dc467e", + "id": "9a556866-844a-36a5-ef4e-a5f3cc8ba534", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Initializes an instance by validating required parameters, setting default properties, and creating metadata with version information, timestamps, and additional user-provided data.", + "description": "Initializes an instance with a namespace, getRemote method, and optional additional metadata. It sets properties such as CHUNK_SIZE, namespace, and meta data, and initializes arrays to store chunks, content, and lookup values. It also sets the status of the document store.", "params": [ { "name": "namespace", "type_name": "string*", "optional": false, - "description": "Required. It represents the namespace for this document store instance and is used to identify it uniquely.", + "description": "Required.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required to be provided when constructing an object. It seems to represent a remote method that returns a promise resolving to a dictionary.", + "description": "Used to retrieve data from a remote source asynchronously.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record*", "optional": true, - "description": "Used to represent additional metadata about the namespace. It contains key-value pairs where keys are strings and values can be of any type.", + "description": "Used to provide extra metadata information for the data being stored.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore('namespace', async () => {\n // getRemote implementation\n return { foo: 'bar' };\n}, { extraMetaKey: 'extraMetaValue' });\n", - "description": "\nThis will create a new instance of the `DocumentStore` class with namespace `'namespace'`, using the provided `getRemote` method, and additional metadata `{ extraMetaKey: 'extraMetaValue' }`." + "code": "const doc = new DocumentStore(\"my-namespace\", async (...args) => {\n // Implementation of getRemote method\n}, { key: \"value\" });\n", + "description": "" }, "name": null, "location": { @@ -182,23 +182,23 @@ "docLength": 12 }, { - "id": "ffa0e742-e740-0ab8-ab41-568bd8cb6548", + "id": "d2728daf-9f85-8ebe-e843-1c9fd352653c", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Updates the `updated_at` property with the provided `Date` object, effectively changing the timestamp when the document was last updated.", + "description": "Updates the `updated_at` property of its own object with a new `Date` value provided as an argument, effectively changing the timestamp for when this document was last updated.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date*", - "description": "Assigned to `this.meta.updated_at`." + "description": "Intended to update the `updated_at` property of an object." } ], "usage": { "language": "typescript", - "code": "const store = new DocumentStore();\nconst updated_at = new Date('2023-01-25T14:30:00.000Z');\nstore.setUpdatedAt(updated_at);\n", + "code": "const documentStore = new DocumentStore();\nconst updatedDate = new Date();\n\ndocumentStore.setUpdatedAt(updatedDate);\n", "description": "" }, "name": "setUpdatedAt", @@ -217,15 +217,15 @@ "docLength": 7 }, { - "id": "6b10bae6-6671-9897-9444-769fc2393d3d", + "id": "5e23666c-96bb-32ab-704a-4cc1e46c7ce8", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Loads and updates metadata and data from a remote source, merging local and remote data. If no data is stored, it logs a message and sets default values.", + "description": "Retrieves and updates local summary data from a remote store, merging it with the local meta template to produce a final summary object. If no remote data is available, it logs a message indicating no stored docs yet.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.metaTemplate = {template: 'template'};\nawait documentStore.loadSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote);\n\ndocumentStore.loadSummary();\n", "description": "" }, "name": "loadSummary", @@ -244,12 +244,12 @@ "docLength": 4 }, { - "id": "03692d3e-ca07-5b8d-3a4e-2bdf8428e2ee", + "id": "e795c74d-aeb9-c2b9-6b4f-9a2c6c8b1030", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba", - "6b10bae6-6671-9897-9444-769fc2393d3d" + "749b009b-0d66-d5a4-2f4f-56de149adb1f", + "5e23666c-96bb-32ab-704a-4cc1e46c7ce8" ], - "description": "Maps metaTemplate properties to meta properties with fallbacks.", + "description": "Maps meta template keys to values from a summary object.", "name": null, "location": { "start": 121, @@ -263,16 +263,16 @@ "docLength": null }, { - "id": "6c121aa5-3b41-6299-f24c-a978e34bd980", + "id": "a7514402-76e8-f3a8-9e46-732d738cb683", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Asynchronously loads document summary and chunks when called. It first checks if the summary is loaded, then loads chunks based on the lookup indices. Once all chunks are loaded, it sets the `chunks` status to true.", + "description": "Asynchronously loads the document's summary and chunks from an external source, if not already loaded, and sets the `chunks` property to `true` once all chunks are loaded.", "params": [], "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore();\ndocStore.getRemote = async (args: any[]) => Promise.resolve({});\n\nawait docStore.load();\n", - "description": "\nNote that this code snippet assumes the existence of `getRemote` property on `DocumentStore` instance, as specified in the parent class code provided." + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.load().then(() => {\n // Do something with loaded data\n});\n", + "description": "" }, "name": "load", "location": { @@ -290,24 +290,24 @@ "docLength": 3 }, { - "id": "c4d8b2fd-b05e-5d8c-4740-3c0b38792ae2", + "id": "8f33155d-9bc5-e79d-0542-78cdbfd93895", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Updates the metadata object by merging it with additional metadata provided as an argument. It uses the spread operator to combine the existing metadata with the new metadata, resulting in a new updated metadata object.", + "description": "Updates the metadata object by merging it with an additional metadata object passed as an argument, effectively updating the existing metadata with new key-value pairs.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record*", - "description": "Passed as an argument to this function." + "description": "Used to add new metadata properties." } ], "usage": { "language": "typescript", - "code": "const ds = new DocumentStore();\nds.updateMetadata({\n customField: 'someValue',\n});\n", - "description": "" + "code": "const store = new DocumentStore(getRemote);\nstore.updateMetadata({ \"integration\": \"my-integration\" });\n", + "description": "\nIn this case, the user creates a new instance of `DocumentStore`, which has its own metadata properties." }, "name": "updateMetadata", "location": { @@ -322,28 +322,28 @@ "docLength": null }, { - "id": "54eff05c-e84f-f997-7342-6fa3540012ae", + "id": "ac001e36-3bda-e9ac-8d43-7c331908e065", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Asynchronously loads a chunk of structured files from a remote location if it's not already loaded, and updates the local storage with the new content. It returns a boolean indicating whether the load was successful or not.", + "description": "Loads a specific chunk of data asynchronously and updates the internal state if the chunk has not been loaded previously. If an error occurs during loading, it returns false; otherwise, it returns true to indicate success.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number*", - "description": "Used as an index for accessing the chunks of data stored in the `chunks` object. It represents the specific chunk to be loaded from the remote location." + "description": "Used to identify a specific chunk of data to load." } ], "returns": { "type_name": "Promise*", - "description": "Resolved to either `true` (if the chunk loading is successful) or `false` (in case of an error)." + "description": "Resolved to either true or false depending on whether the chunk loading operation was successful or failed." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\n\ndocumentStore.loadChunk(1).then((result) => {\n if (!result) {\n console.error(\"Failed to load chunk\");\n } else {\n // do something with the loaded chunk\n }\n});\n", - "description": "" + "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadChunk(0);\nif (!documentStore.status.chunks) {\n console.error(\"Failed to load chunk\");\n}\n", + "description": "\nThis code creates a `DocumentStore` instance with the provided `getRemote` function and integration. Then it attempts to load the first chunk using the `loadChunk` method, which returns a promise that resolves to a boolean value indicating whether the loading was successful or not." }, "name": "loadChunk", "location": { @@ -361,27 +361,27 @@ "docLength": 11 }, { - "id": "b3159cd7-47e6-83a4-f44b-36fbe4ef093a", + "id": "3c18bfe1-13c3-3a8d-304c-1c44d75a70ab", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Asynchronously retrieves a file from storage based on its path, ensuring that the required summary is loaded first and loading the corresponding chunk if necessary.", + "description": "Asynchronously retrieves a file from a chunk-based storage system, given its path. It first checks if the summary is loaded and loads the corresponding chunk if necessary. If the file exists in the chunk, it returns the file object; otherwise, it returns null.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Used to specify the path of the file for which the structured file information should be retrieved." + "description": "Used to specify the file path." } ], "returns": { "type_name": "Promise*", - "description": "Resolved to either a structured file object (of type StructuredFile) or null." + "description": "A promise that resolves to either a `StructuredFile` object or null." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary();\n\nconst file1 = await documentStore.getFile('path/to/file1');\nconst file2 = await documentStore.getFile('path/to/file2');\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.loadSummary();\nconst structuredFile = await documentStore.getFile(\"path/to/file\");\nif (structuredFile) {\n // do something with the file\n} else {\n // handle file not found\n}\n", "description": "" }, "name": "getFile", @@ -400,24 +400,24 @@ "docLength": 10 }, { - "id": "727487bc-b1fe-daab-eb49-763a41753caf", + "id": "29705d3d-f1ef-dcaa-4240-7b665f270a6b", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Adds a path to the end of the current lookup subtable if it's not full, otherwise creates a new one. It checks if the last subtable is empty or has reached its chunk size before adding the path.", + "description": "Adds a new path to the end of the lookup subtable. If the last subtable is full, it creates a new one; otherwise, it appends the path to the existing subtable.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Passed as an argument to the function, which it uses to determine whether to create a new subtable in the `lookup` array or add the path to the last existing subtable." + "description": "Used to store or update a lookup table." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore CHUNK_SIZE = 10;\ndocumentStore.addToEndOfLookup(\"path1\");\ndocumentStore.addToEndOfLookup(\"path2\");\ndocumentStore.addToEndOfLookup(\"path3\");\n", - "description": "\n\nNote: The above example is a minimal illustration of the usage of `addToEndOfLookup` method in the class `DocumentStore`." + "code": "const documentStore = new DocumentStore(...);\n\ndocumentStore.addToEndOfLookup('path1');\ndocumentStore.addToEndOfLookup('path2');\n", + "description": "\nThis code creates a new instance of `DocumentStore` and adds two paths to its lookup." }, "name": "addToEndOfLookup", "location": { @@ -435,24 +435,24 @@ "docLength": 6 }, { - "id": "7c066604-f908-feb0-f240-61129040b2cc", + "id": "50227ebc-d1fe-50a6-b44f-99471049fea1", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Adds a `StructuredFile` to either a new or an existing chunk, depending on whether the last chunk is full. It ensures that each chunk does not exceed the specified `CHUNK_SIZE`.", + "description": "Adds a new file to an existing chunk or creates a new chunk if the current one is full, ensuring that each chunk does not exceed a specified size (`CHUNK_SIZE`).", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Required for processing and manipulation within the function." + "description": "Intended to add files to chunks." } ], "usage": { "language": "typescript", - "code": "const file1 = new StructuredFile();\nconst file2 = new StructuredFile();\n\ndocumentStore.addToEndOfChunks(file1);\ndocumentStore.addToEndOfChunks(file2);\n", - "description": "\nIt adds two structured files to the end of the chunks." + "code": "documentStore = new DocumentStore();\nstructuredFile: StructuredFile;\n// Assume structuredFile has been set with necessary data.\n\ndocumentStore.addToEndOfChunks(structuredFile);\n", + "description": "\nNote that this code snippet assumes a pre-existing instance of the `DocumentStore` class and a valid `structuredFile`." }, "name": "addToEndOfChunks", "location": { @@ -470,27 +470,27 @@ "docLength": 10 }, { - "id": "8098b249-995e-dcaf-ea48-7d1379f326fd", + "id": "5659990e-dd99-bc8e-af4e-469eed140e74", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Adds a file to the store if it exists and its path has not been previously added. If the file already exists, it updates the existing file; otherwise, it appends the new file to the end of the lookup and chunk lists.", + "description": "Adds a structured file to the document store, updating it if the file already exists, and adding it to the end of lookup and chunks lists if not. It returns true on success or false with error information if failed.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Mandatory for the function to execute successfully. It must be provided with valid data, specifically including a path property." + "description": "Required for adding files to the collection." } ], "returns": { "type_name": "boolean*", - "description": "True if the file was successfully added, and false otherwise." + "description": "True if the file is successfully added and updated, and false otherwise." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.load().then(() => {\n const file1 = { path: 'file1.txt', content: 'Hello World' };\n const result1 = documentStore.addFile(file1);\n if (result1) console.log('File added successfully');\n});\n", + "code": "const documentStore = new DocumentStore(...); // Initialize the DocumentStore instance\nconst file: StructuredFile = { path: 'path/to/file.txt' }; \ndocumentStore.addFile(file); // Add a new file to the DocumentStore", "description": "" }, "name": "addFile", @@ -509,27 +509,27 @@ "docLength": 10 }, { - "id": "0178bd9b-6fa2-f383-4348-0d4a604d7e2e", + "id": "e8c1efbc-b1ac-af93-f64d-4563730c3937", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Updates a file by adding or replacing it in a chunk, if the chunk exists and is loaded. If not loaded, it loads the chunk first. The method returns a boolean indicating success.", + "description": "Updates an existing file or adds a new one to the store, checking for valid file path and loading chunks as necessary.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Required for this method. If no file is provided, it returns false immediately." + "description": "Used to update a file's information." } ], "returns": { "type_name": "Promise*", - "description": "Either a promise that resolves to `true` if the file update operation is successful or `false` otherwise." + "description": "Either a boolean indicating whether the file was successfully updated or an error occurred during the update process." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.load();\nconst file = {\n path: '/path/to/file',\n contents: 'file content'\n};\nstore.updateFile(file).then(result => console.log(result));\n", + "code": "const documentStore = new DocumentStore();\nconst file1: StructuredFile = { path: 'path/file1.txt', content: 'Hello, World!' };\ndocumentStore.updateFile(file1).then((success) => console.log(success));", "description": "" }, "name": "updateFile", @@ -548,19 +548,19 @@ "docLength": 10 }, { - "id": "3efe624f-b41c-3eba-d144-cd456cec1d1b", + "id": "70475eaa-175f-6cad-f244-f8a348707f42", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Returns an object with two properties, `meta` and `lookup`, which are initialized from the corresponding instance variables `this.meta` and `this.lookup`. The purpose is to provide a compact representation of the document store's metadata and lookup data.", + "description": "Returns an object with two properties, `meta` and `lookup`, which are likely metadata and a lookup table, respectively. This method provides a summary representation of the document store's data.", "params": [], "returns": { "type_name": "Summary*", - "description": "An object with two properties: meta and lookup." + "description": "An object with two properties: meta and lookup, both containing values from the this object." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nconst summary = store.outputSummary();\n", + "code": "const store = new DocumentStore();\nstore.outputSummary().meta.version;\nstore.outputSummary().lookup.forEach(array => {\n array.forEach(chunk => {\n // Process chunk\n });\n});\n", "description": "" }, "name": "outputSummary", @@ -579,19 +579,19 @@ "docLength": 6 }, { - "id": "78c42646-c9a9-1bad-a04e-e6e6a31d48ed", + "id": "3be62dc1-335e-d68f-0a46-124d14052afa", "ancestors": [ - "0e6ee1bd-a5fc-299f-7c4f-eee91cd758ba" + "749b009b-0d66-d5a4-2f4f-56de149adb1f" ], - "description": "Splits its internal content into chunks, each with a fixed size specified by `CHUNK_SIZE`, and stores them as key-value pairs in a Record object, where keys are generated from chunk indices using `chunkIndexToChunkKey` and `chunkKeyToChunkPath`.", + "description": "Divides the content into chunks based on the `CHUNK_SIZE`, generates keys for each chunk, and stores them as key-value pairs in an object called `outputs`. The method returns this object.", "params": [], "returns": { "type_name": "Record*", - "description": "A collection of key-value pairs where keys are strings and values are of any data type." + "description": "An object that maps string keys to values of various types." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\n\ndocumentStore.outputChunks();\n", + "code": "const documentStore = new DocumentStore();\ndocumentStore.CHUNK_SIZE = 1024;\ndocumentStore.outputChunks().then(outputs => {\n // Process the outputs here.\n});\n", "description": "" }, "name": "outputChunks", diff --git a/.komment/komment.json b/.komment/komment.json index 772d9fb..7caab4e 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-11T08:16:01.246Z", + "updated_at": "2024-07-11T09:25:30.811Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -13,7 +13,8 @@ "db654c98-5128-44f7-8691-252c69b9b5b7", "fb518d01-fd0a-40bb-8d37-2ff5990c023b", "49ec0772-f24b-4603-9a27-a31b96963bdf", - "e7cb8cbb-d12f-4f42-adcc-cdf3756c8071" + "e7cb8cbb-d12f-4f42-adcc-cdf3756c8071", + "ce9a50b9-f4ec-4487-80f0-aff229eec487" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 787e24a..0a469c8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,10 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Is a data structure designed to efficiently manage and load structured - * files (e.g., JSON) from remote sources, handling chunking, caching, and lookup - * operations for fast access and retrieval of file contents. + * @description Manages structured files and their chunks, providing methods for + * loading, updating, and retrieving files, as well as maintaining metadata and lookup + * tables. It is designed to efficiently store and retrieve large amounts of data + * organized into chunks. * * @implements {IDocumentStore} */ @@ -46,20 +47,18 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Initializes an instance by validating required parameters, setting - * default properties, and creating metadata with version information, timestamps, - * and additional user-provided data. + * @description Initializes an instance with a namespace, getRemote method, and + * optional additional metadata. It sets properties such as CHUNK_SIZE, namespace, + * and meta data, and initializes arrays to store chunks, content, and lookup values. + * It also sets the status of the document store. * - * @param {string*} namespace - Required. It represents the namespace for this document - * store instance and is used to identify it uniquely. + * @param {string*} namespace - Required. * - * @param {(...args: any[]) => Promise>*} getRemote - Required to - * be provided when constructing an object. It seems to represent a remote method - * that returns a promise resolving to a dictionary. + * @param {(...args: any[]) => Promise>*} getRemote - Used to retrieve + * data from a remote source asynchronously. * - * @param {Record*} additionalMeta - Used to represent additional metadata - * about the namespace. It contains key-value pairs where keys are strings and values - * can be of any type. + * @param {Record*} additionalMeta - Used to provide extra metadata + * information for the data being stored. */ constructor( namespace: string, @@ -89,18 +88,20 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` property with the provided `Date` object, - * effectively changing the timestamp when the document was last updated. + * @description Updates the `updated_at` property of its own object with a new `Date` + * value provided as an argument, effectively changing the timestamp for when this + * document was last updated. * - * @param {Date*} updated_at - Assigned to `this.meta.updated_at`. + * @param {Date*} updated_at - Intended to update the `updated_at` property of an object. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Loads and updates metadata and data from a remote source, merging - * local and remote data. If no data is stored, it logs a message and sets default values. + * @description Retrieves and updates local summary data from a remote store, merging + * it with the local meta template to produce a final summary object. If no remote + * data is available, it logs a message indicating no stored docs yet. */ loadSummary = async () => { let summary: Summary = { @@ -129,7 +130,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]) => { - // Maps metaTemplate properties to meta properties with fallbacks. + // Maps meta template keys to values from a summary object. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -138,9 +139,9 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Asynchronously loads document summary and chunks when called. It first - * checks if the summary is loaded, then loads chunks based on the lookup indices. - * Once all chunks are loaded, it sets the `chunks` status to true. + * @description Asynchronously loads the document's summary and chunks from an external + * source, if not already loaded, and sets the `chunks` property to `true` once all + * chunks are loaded. */ load = async () => { if (!this.status.summary) { @@ -163,11 +164,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata object by merging it with additional metadata - * provided as an argument. It uses the spread operator to combine the existing - * metadata with the new metadata, resulting in a new updated metadata object. + * @description Updates the metadata object by merging it with an additional metadata + * object passed as an argument, effectively updating the existing metadata with new + * key-value pairs. * - * @param {Record*} additionalMeta - Passed as an argument to this function. + * @param {Record*} additionalMeta - Used to add new metadata properties. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -183,16 +184,14 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Asynchronously loads a chunk of structured files from a remote location - * if it's not already loaded, and updates the local storage with the new content. - * It returns a boolean indicating whether the load was successful or not. + * @description Loads a specific chunk of data asynchronously and updates the internal + * state if the chunk has not been loaded previously. If an error occurs during + * loading, it returns false; otherwise, it returns true to indicate success. * - * @param {number*} chunkIndex - Used as an index for accessing the chunks of data - * stored in the `chunks` object. It represents the specific chunk to be loaded from - * the remote location. + * @param {number*} chunkIndex - Used to identify a specific chunk of data to load. * - * @returns {Promise*} Resolved to either `true` (if the chunk loading is - * successful) or `false` (in case of an error). + * @returns {Promise*} Resolved to either true or false depending on whether + * the chunk loading operation was successful or failed. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -211,15 +210,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Asynchronously retrieves a file from storage based on its path, - * ensuring that the required summary is loaded first and loading the corresponding - * chunk if necessary. + * @description Asynchronously retrieves a file from a chunk-based storage system, + * given its path. It first checks if the summary is loaded and loads the corresponding + * chunk if necessary. If the file exists in the chunk, it returns the file object; + * otherwise, it returns null. * - * @param {string*} path - Used to specify the path of the file for which the structured - * file information should be retrieved. + * @param {string*} path - Used to specify the file path. * - * @returns {Promise*} Resolved to either a structured file - * object (of type StructuredFile) or null. + * @returns {Promise*} A promise that resolves to either a + * `StructuredFile` object or null. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -262,13 +261,10 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a path to the end of the current lookup subtable if it's not - * full, otherwise creates a new one. It checks if the last subtable is empty or has - * reached its chunk size before adding the path. + * @description Adds a new path to the end of the lookup subtable. If the last subtable + * is full, it creates a new one; otherwise, it appends the path to the existing subtable. * - * @param {string*} path - Passed as an argument to the function, which it uses to - * determine whether to create a new subtable in the `lookup` array or add the path - * to the last existing subtable. + * @param {string*} path - Used to store or update a lookup table. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -282,12 +278,10 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a `StructuredFile` to either a new or an existing chunk, depending - * on whether the last chunk is full. It ensures that each chunk does not exceed the - * specified `CHUNK_SIZE`. + * @description Adds a new file to an existing chunk or creates a new chunk if the + * current one is full, ensuring that each chunk does not exceed a specified size (`CHUNK_SIZE`). * - * @param {StructuredFile*} file - Required for processing and manipulation within - * the function. + * @param {StructuredFile*} file - Intended to add files to chunks. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -301,14 +295,14 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the store if it exists and its path has not been - * previously added. If the file already exists, it updates the existing file; - * otherwise, it appends the new file to the end of the lookup and chunk lists. + * @description Adds a structured file to the document store, updating it if the file + * already exists, and adding it to the end of lookup and chunks lists if not. It + * returns true on success or false with error information if failed. * - * @param {StructuredFile*} file - Mandatory for the function to execute successfully. - * It must be provided with valid data, specifically including a path property. + * @param {StructuredFile*} file - Required for adding files to the collection. * - * @returns {boolean*} True if the file was successfully added, and false otherwise. + * @returns {boolean*} True if the file is successfully added and updated, and false + * otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -331,15 +325,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file by adding or replacing it in a chunk, if the chunk - * exists and is loaded. If not loaded, it loads the chunk first. The method returns - * a boolean indicating success. + * @description Updates an existing file or adds a new one to the store, checking for + * valid file path and loading chunks as necessary. * - * @param {StructuredFile*} file - Required for this method. If no file is provided, - * it returns false immediately. + * @param {StructuredFile*} file - Used to update a file's information. * - * @returns {Promise*} Either a promise that resolves to `true` if the file - * update operation is successful or `false` otherwise. + * @returns {Promise*} Either a boolean indicating whether the file was + * successfully updated or an error occurred during the update process. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -370,11 +362,11 @@ class DocumentStore implements IDocumentStore { }; /** * @description Returns an object with two properties, `meta` and `lookup`, which are - * initialized from the corresponding instance variables `this.meta` and `this.lookup`. - * The purpose is to provide a compact representation of the document store's metadata - * and lookup data. + * likely metadata and a lookup table, respectively. This method provides a summary + * representation of the document store's data. * - * @returns {Summary*} An object with two properties: meta and lookup. + * @returns {Summary*} An object with two properties: meta and lookup, both containing + * values from the this object. */ outputSummary(): Summary { return { @@ -383,12 +375,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Splits its internal content into chunks, each with a fixed size - * specified by `CHUNK_SIZE`, and stores them as key-value pairs in a Record object, - * where keys are generated from chunk indices using `chunkIndexToChunkKey` and `chunkKeyToChunkPath`. + * @description Divides the content into chunks based on the `CHUNK_SIZE`, generates + * keys for each chunk, and stores them as key-value pairs in an object called + * `outputs`. The method returns this object. * - * @returns {Record*} A collection of key-value pairs where keys are - * strings and values are of any data type. + * @returns {Record*} An object that maps string keys to values of various + * types. */ outputChunks(): Record { const outputs: Record = {}; From d2693296b7a087a1bbceebde44c886b1fa7bf09c Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Thu, 11 Jul 2024 09:40:22 +0000 Subject: [PATCH 18/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 178 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 135 ++++++++++++++++---------------- 3 files changed, 159 insertions(+), 159 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 369748f..b76823c 100644 --- a/.komment/00000.json +++ b/.komment/00000.json @@ -4,12 +4,12 @@ "path": "src/index.ts", "content": { "structured": { - "description": "A class called DocumentStore that provides an efficient way to manage and store structured files, which are composed of chunks of code with a specified size. The class utilizes two main data structures: `lookup` and `chunks`, both of which are arrays of file paths and chunked content respectively. It also includes methods for adding new files, updating existing ones, loading chunks as needed, and generating summaries and records of the stored chunks.", + "description": "A `DocumentStore` class that manages a structured file containing files and chunks of files. It provides methods for adding new files to the structure, updating existing files in chunks, and generating high-quality documentation for the code. The code also includes a chunking system for organizing files into chunks based on a specified chunk size and keying system.", "items": [ { - "id": "749b009b-0d66-d5a4-2f4f-56de149adb1f", + "id": "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768", "ancestors": [], - "description": "Manages structured files and their chunks, providing methods for loading, updating, and retrieving files, as well as maintaining metadata and lookup tables. It is designed to efficiently store and retrieve large amounts of data organized into chunks.", + "description": "Manages a structured file containing code, organizing it into chunks based on file size and keying system, and providing methods for adding, updating, and querying files within the structure.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "1-based index for chunks within a document, which determines how many files should be contained within each chunk." + "description": "Used to define the size of each chunk in the structured file, which determines the number of files that can be stored within a single chunk." }, { "name": "namespace", "type_name": "string", - "description": "Used to store a namespace for files, allowing them to be uniquely identified within the document structure." + "description": "Used to specify the namespace for the structured files, which is the container for all the code in this module" }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the document." + "description": "Used to store metadata about the document store instance, such as its version number, creation date, and last update date." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Not used anywhere in this code. It seems to be a leftover from another development iteration or a comment for future reference." + "description": "Used to define a template for the generated meta documentation." }, { "name": "lookup", "type_name": "string[][]", - "description": "2D array representing a lookup table for files in the document store. It stores file paths as strings and maps them to chunk indices and file indexes within those chunks." + "description": "Used to store a table of file paths that map to chunks of code, allowing for fast lookups of files within a chunk or across multiple chunks." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "2D array that stores the structured files within each chunk, with each inner array representing a chunk's contents and its length being equal to the specified CHUNK_SIZE." + "description": "Used to store the structured files in a code's content, organized into chunks based on their size." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "An array that stores all the files in the document store. It contains an ordered sequence of file objects. Each object represents a file in the document, including its path and other properties." + "description": "Used to store a list of files that make up the content of the document, including their paths and file sizes." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Not fully defined in the given code snippet." + "description": "Used to track the state of the store (e.g., if all chunks are loaded)" } ], "name": "DocumentStore", @@ -133,37 +133,37 @@ "docLength": null }, { - "id": "9a556866-844a-36a5-ef4e-a5f3cc8ba534", + "id": "000f97da-5d59-7ba5-e245-c10719c89d0f", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Initializes an instance with a namespace, getRemote method, and optional additional metadata. It sets properties such as CHUNK_SIZE, namespace, and meta data, and initializes arrays to store chunks, content, and lookup values. It also sets the status of the document store.", + "description": "Sets up instance variables to store namespace, getRemote method, and additional metadata. It also initializes chunk size, sets default values for version, created/updated dates, and populates lookup, chunks, and content arrays.", "params": [ { "name": "namespace", "type_name": "string*", "optional": false, - "description": "Required.", + "description": "Required. Its purpose is to provide the name or identifier for the document store, which serves as an alias for accessing the data within the function.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Used to retrieve data from a remote source asynchronously.", + "description": "Used to provide a remote method that retrieves data for the document store.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record*", "optional": true, - "description": "Used to provide extra metadata information for the data being stored.", + "description": "Intended to store additional metadata related to the document.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const doc = new DocumentStore(\"my-namespace\", async (...args) => {\n // Implementation of getRemote method\n}, { key: \"value\" });\n", + "code": "const myDocStore = new DocumentStore(\"my-namespace\", (...args) => getRemote(args), { additionalMeta: {} });\n", "description": "" }, "name": null, @@ -182,23 +182,23 @@ "docLength": 12 }, { - "id": "d2728daf-9f85-8ebe-e843-1c9fd352653c", + "id": "f4103f74-ec2e-5e88-4648-f122e8d0bcf8", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Updates the `updated_at` property of its own object with a new `Date` value provided as an argument, effectively changing the timestamp for when this document was last updated.", + "description": "Updates the `updatedAt` metadata field of an instance with the provided `Date` value, synchronizing the in-memory representation with the stored date.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date*", - "description": "Intended to update the `updated_at` property of an object." + "description": "Used to update the \"updated at\" metadata for an entity." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\nconst updatedDate = new Date();\n\ndocumentStore.setUpdatedAt(updatedDate);\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.setUpdatedAt(new Date());\n", "description": "" }, "name": "setUpdatedAt", @@ -217,15 +217,15 @@ "docLength": 7 }, { - "id": "5e23666c-96bb-32ab-704a-4cc1e46c7ce8", + "id": "d52dd231-066e-0188-fa42-7f6b322d1374", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Retrieves and updates local summary data from a remote store, merging it with the local meta template to produce a final summary object. If no remote data is available, it logs a message indicating no stored docs yet.", + "description": "Retrieves and merges summary information from the local store with remote data, updating the local store's metadata and chunk lists.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\n\ndocumentStore.loadSummary();\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\nawait docStore.loadSummary(); // loads the summary from a remote store\n", "description": "" }, "name": "loadSummary", @@ -244,12 +244,12 @@ "docLength": 4 }, { - "id": "e795c74d-aeb9-c2b9-6b4f-9a2c6c8b1030", + "id": "c9ca0b54-c4c5-59b2-2b48-d449862cf6b9", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f", - "5e23666c-96bb-32ab-704a-4cc1e46c7ce8" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768", + "d52dd231-066e-0188-fa42-7f6b322d1374" ], - "description": "Maps meta template keys to values from a summary object.", + "description": "Updates an object's property with the value from `summary.meta` or the original value if `summary.meta` is null or undefined.", "name": null, "location": { "start": 121, @@ -263,15 +263,15 @@ "docLength": null }, { - "id": "a7514402-76e8-f3a8-9e46-732d738cb683", + "id": "66ef23f5-cf1f-faa4-c54e-ae67b3cbedcb", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Asynchronously loads the document's summary and chunks from an external source, if not already loaded, and sets the `chunks` property to `true` once all chunks are loaded.", + "description": "Loads chunks of data asynchronously based on the current status of the document store, ensuring that all chunks are loaded when the method completes.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.load().then(() => {\n // Do something with loaded data\n});\n", + "code": "const DocumentStore = new IDocumentStore();\nconst getRemote = (...args: any[]) => Promise>; // 3rd party library or service that provides the functionality\n\n// set up instance of a DocumentStore class with various parameters\nDocumentStore.CHUNK_SIZE = 50;\nDocumentStore.namespace = \"my-namespace\";\nDocumentStore.getRemote = getRemote;\nDocumentStore.metaTemplate = { // metadata\n version: '1.2.3',\n created_at: new Date(),\n updated_at: new Date(),\n};\n\n// initialize internal arrays and objects to store chunk data, content, and other meta information\nconst lookup = [];\nconst chunks = [];\nconst content = [];\nconst status = {\n summary: false,\n chunks: false,\n}\n\n// call the load function to retrieve the data from the remote service\nDocumentStore.load();\n", "description": "" }, "name": "load", @@ -290,24 +290,24 @@ "docLength": 3 }, { - "id": "8f33155d-9bc5-e79d-0542-78cdbfd93895", + "id": "70f2f0ca-7d6b-af8d-2c44-ae0e3823d30b", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Updates the metadata object by merging it with an additional metadata object passed as an argument, effectively updating the existing metadata with new key-value pairs.", + "description": "Updates the metadata field of the class by combining the current metadata with additional metadata provided as an argument.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record*", - "description": "Used to add new metadata properties." + "description": "Used to add new metadata to the existing metadata stored in the `this.meta` object." } ], "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote);\nstore.updateMetadata({ \"integration\": \"my-integration\" });\n", - "description": "\nIn this case, the user creates a new instance of `DocumentStore`, which has its own metadata properties." + "code": "const documentStore = new DocumentStore();\ndocumentStore.updateMetadata({version: '1.0', created_at: new Date(), updated_at: new Date()});\n", + "description": "" }, "name": "updateMetadata", "location": { @@ -322,28 +322,28 @@ "docLength": null }, { - "id": "ac001e36-3bda-e9ac-8d43-7c331908e065", + "id": "73a9661d-5f6f-eb89-2942-de75b051e42d", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Loads a specific chunk of data asynchronously and updates the internal state if the chunk has not been loaded previously. If an error occurs during loading, it returns false; otherwise, it returns true to indicate success.", + "description": "Async loads a chunk of data from the server, checks if it has already been loaded, and if not, concats it with the existing content and stores it in the `chunks` property. Returns `true` if successful, `false` otherwise.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number*", - "description": "Used to identify a specific chunk of data to load." + "description": "Used to identify the specific chunk being loaded out of the total number of chunks." } ], "returns": { "type_name": "Promise*", - "description": "Resolved to either true or false depending on whether the chunk loading operation was successful or failed." + "description": "A resolved promise if the chunk is successfully loaded and the content is appended to the internal `content` array, or rejected with `false` if an error occurs during loading." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadChunk(0);\nif (!documentStore.status.chunks) {\n console.error(\"Failed to load chunk\");\n}\n", - "description": "\nThis code creates a `DocumentStore` instance with the provided `getRemote` function and integration. Then it attempts to load the first chunk using the `loadChunk` method, which returns a promise that resolves to a boolean value indicating whether the loading was successful or not." + "code": "const docStore = new DocumentStore(getRemote);\nawait docStore.loadChunk(10);\n", + "description": "\nThe loadChunk method loads a chunk of data from a remote source, and returns a boolean value indicating whether the operation was successful or not. The parameter is an integer that represents the chunk index to be loaded." }, "name": "loadChunk", "location": { @@ -361,27 +361,27 @@ "docLength": 11 }, { - "id": "3c18bfe1-13c3-3a8d-304c-1c44d75a70ab", + "id": "7bc7b6a7-0f4e-1dad-3540-f55d64348529", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Asynchronously retrieves a file from a chunk-based storage system, given its path. It first checks if the summary is loaded and loads the corresponding chunk if necessary. If the file exists in the chunk, it returns the file object; otherwise, it returns null.", + "description": "Retrieves a file from the store based on its path, checking for its availability in the loaded chunks and returning it if found.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Used to specify the file path." + "description": "Used to specify the file path to be retrieved, with its purpose being to identify the file within the chunked data." } ], "returns": { "type_name": "Promise*", - "description": "A promise that resolves to either a `StructuredFile` object or null." + "description": "Either a StructuredFile object or null if the file cannot be found or has not been loaded." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.loadSummary();\nconst structuredFile = await documentStore.getFile(\"path/to/file\");\nif (structuredFile) {\n // do something with the file\n} else {\n // handle file not found\n}\n", + "code": "// create a new instance of DocumentStore using getRemote and integration\nconst docstore = new DocumentStore(getRemote, integration);\n\n// load the summary file for the code documentation\nawait docstore.loadSummary();\n\n// retrieve a specific file from the code documentation\nconst myFile = await docstore.getFile(\"path/to/file\");\n", "description": "" }, "name": "getFile", @@ -400,24 +400,24 @@ "docLength": 10 }, { - "id": "29705d3d-f1ef-dcaa-4240-7b665f270a6b", + "id": "cc565ae3-c24c-ee93-a643-6722865fc6cf", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Adds a new path to the end of the lookup subtable. If the last subtable is full, it creates a new one; otherwise, it appends the path to the existing subtable.", + "description": "Adds a new path to the end of the current lookup subtable if necessary, ensuring the table's size does not exceed the maximum allowed.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Used to store or update a lookup table." + "description": "Used to provide an additional string to be added to the lookup subtable, if necessary creating a new subtable if the last one is full." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(...);\n\ndocumentStore.addToEndOfLookup('path1');\ndocumentStore.addToEndOfLookup('path2');\n", - "description": "\nThis code creates a new instance of `DocumentStore` and adds two paths to its lookup." + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfLookup(\"path/to/file1\");\ndocStore.addToEndOfLookup(\"path/to/file2\");\n", + "description": "" }, "name": "addToEndOfLookup", "location": { @@ -435,24 +435,24 @@ "docLength": 6 }, { - "id": "50227ebc-d1fe-50a6-b44f-99471049fea1", + "id": "28d0de60-313e-a19f-b549-f829a1aecaac", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Adds a new file to an existing chunk or creates a new chunk if the current one is full, ensuring that each chunk does not exceed a specified size (`CHUNK_SIZE`).", + "description": "Adds new files to the end of existing chunks or creates a new chunk if the last one is full.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Intended to add files to chunks." + "description": "Used to add new files to the chunks array at the end." } ], "usage": { "language": "typescript", - "code": "documentStore = new DocumentStore();\nstructuredFile: StructuredFile;\n// Assume structuredFile has been set with necessary data.\n\ndocumentStore.addToEndOfChunks(structuredFile);\n", - "description": "\nNote that this code snippet assumes a pre-existing instance of the `DocumentStore` class and a valid `structuredFile`." + "code": "const documentStore = new DocumentStore({ getRemote, integration });\ndocumentStore.addToEndOfChunks(file);\n", + "description": "" }, "name": "addToEndOfChunks", "location": { @@ -470,27 +470,27 @@ "docLength": 10 }, { - "id": "5659990e-dd99-bc8e-af4e-469eed140e74", + "id": "4f34a0a1-24ae-9ab1-af45-c9831511941b", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Adds a structured file to the document store, updating it if the file already exists, and adding it to the end of lookup and chunks lists if not. It returns true on success or false with error information if failed.", + "description": "Adds a file to the store by checking its existence, updating the file if it exists, and then adding it to the end of the lookup and chunks arrays.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Required for adding files to the collection." + "description": "Used to represent a file path that can be added to the content of an instance of the `ContentfulManagement` class." } ], "returns": { "type_name": "boolean*", - "description": "True if the file is successfully added and updated, and false otherwise." + "description": "1 when a file is successfully added to the content and 0 otherwise." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(...); // Initialize the DocumentStore instance\nconst file: StructuredFile = { path: 'path/to/file.txt' }; \ndocumentStore.addFile(file); // Add a new file to the DocumentStore", + "code": "const addFile = (file: StructuredFile): boolean => {\n if (!this.status.chunks) throw Error(\"Must call .load before adding files\");\n if (!file || !file.path) return false;\n\n if (this.fileExists(file.path)) {\n try {\n this.updateFile(file);\n return true;\n } catch (error) {\n console.error(error);\n return false;\n }\n }\n\n this.addToEndOfLookup(file.path);\n this.addToEndOfChunks(file);\n\n this.content.push(file);\n return true;\n }\n", "description": "" }, "name": "addFile", @@ -509,27 +509,27 @@ "docLength": 10 }, { - "id": "e8c1efbc-b1ac-af93-f64d-4563730c3937", + "id": "5f485833-a9d8-aab3-ab4a-60bd97dbae37", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Updates an existing file or adds a new one to the store, checking for valid file path and loading chunks as necessary.", + "description": "Updates a file in the store by checking its existence, loading it if necessary, and storing it in the appropriate chunk and index position.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Used to update a file's information." + "description": "Used to represent a file being updated. Its purpose is to store information about the file, such as its path, for the update operation." } ], "returns": { "type_name": "Promise*", - "description": "Either a boolean indicating whether the file was successfully updated or an error occurred during the update process." + "description": "A boolean value indicating whether the file was successfully updated or not." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\nconst file1: StructuredFile = { path: 'path/file1.txt', content: 'Hello, World!' };\ndocumentStore.updateFile(file1).then((success) => console.log(success));", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.updateFile({path: \"/some/file\"});\n", "description": "" }, "name": "updateFile", @@ -548,19 +548,19 @@ "docLength": 10 }, { - "id": "70475eaa-175f-6cad-f244-f8a348707f42", + "id": "020f09c8-5136-179a-6746-4e333d37fda3", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Returns an object with two properties, `meta` and `lookup`, which are likely metadata and a lookup table, respectively. This method provides a summary representation of the document store's data.", + "description": "Summarizes an object containing metadata (`meta`) and a lookup table (`lookup`).", "params": [], "returns": { "type_name": "Summary*", - "description": "An object with two properties: meta and lookup, both containing values from the this object." + "description": "An object containing two properties: `meta` and `lookup`." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore();\nstore.outputSummary().meta.version;\nstore.outputSummary().lookup.forEach(array => {\n array.forEach(chunk => {\n // Process chunk\n });\n});\n", + "code": "const store = new DocumentStore(getRemote, integration);\nconst summary = store.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -579,20 +579,20 @@ "docLength": 6 }, { - "id": "3be62dc1-335e-d68f-0a46-124d14052afa", + "id": "d6b9b198-1f45-88b5-1e44-6cfa7c8edba1", "ancestors": [ - "749b009b-0d66-d5a4-2f4f-56de149adb1f" + "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" ], - "description": "Divides the content into chunks based on the `CHUNK_SIZE`, generates keys for each chunk, and stores them as key-value pairs in an object called `outputs`. The method returns this object.", + "description": "Extracts chunks of a document based on a chunk size and stores them in an object.", "params": [], "returns": { "type_name": "Record*", - "description": "An object that maps string keys to values of various types." + "description": "An object containing key-value pairs where each key is a unique identifier for a chunk of text and each value is the contents of that chunk." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.CHUNK_SIZE = 1024;\ndocumentStore.outputChunks().then(outputs => {\n // Process the outputs here.\n});\n", - "description": "" + "code": "const store = new DocumentStore(getRemote, integration);\nstore.outputChunks();\n", + "description": "\nThis code will output a Record object containing chunk data." }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index 7caab4e..15ed784 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-11T09:25:30.811Z", + "updated_at": "2024-07-11T09:40:15.160Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -14,7 +14,8 @@ "fb518d01-fd0a-40bb-8d37-2ff5990c023b", "49ec0772-f24b-4603-9a27-a31b96963bdf", "e7cb8cbb-d12f-4f42-adcc-cdf3756c8071", - "ce9a50b9-f4ec-4487-80f0-aff229eec487" + "ce9a50b9-f4ec-4487-80f0-aff229eec487", + "1f76280f-f42b-4585-ad9d-7178240fd285" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 0a469c8..61938de 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,10 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Manages structured files and their chunks, providing methods for - * loading, updating, and retrieving files, as well as maintaining metadata and lookup - * tables. It is designed to efficiently store and retrieve large amounts of data - * organized into chunks. + * @description Manages a structured file containing code, organizing it into chunks + * based on file size and keying system, and providing methods for adding, updating, + * and querying files within the structure. * * @implements {IDocumentStore} */ @@ -47,18 +46,19 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Initializes an instance with a namespace, getRemote method, and - * optional additional metadata. It sets properties such as CHUNK_SIZE, namespace, - * and meta data, and initializes arrays to store chunks, content, and lookup values. - * It also sets the status of the document store. + * @description Sets up instance variables to store namespace, getRemote method, and + * additional metadata. It also initializes chunk size, sets default values for + * version, created/updated dates, and populates lookup, chunks, and content arrays. * - * @param {string*} namespace - Required. + * @param {string*} namespace - Required. Its purpose is to provide the name or + * identifier for the document store, which serves as an alias for accessing the data + * within the function. * - * @param {(...args: any[]) => Promise>*} getRemote - Used to retrieve - * data from a remote source asynchronously. + * @param {(...args: any[]) => Promise>*} getRemote - Used to provide + * a remote method that retrieves data for the document store. * - * @param {Record*} additionalMeta - Used to provide extra metadata - * information for the data being stored. + * @param {Record*} additionalMeta - Intended to store additional metadata + * related to the document. */ constructor( namespace: string, @@ -88,20 +88,18 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` property of its own object with a new `Date` - * value provided as an argument, effectively changing the timestamp for when this - * document was last updated. + * @description Updates the `updatedAt` metadata field of an instance with the provided + * `Date` value, synchronizing the in-memory representation with the stored date. * - * @param {Date*} updated_at - Intended to update the `updated_at` property of an object. + * @param {Date*} updated_at - Used to update the "updated at" metadata for an entity. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates local summary data from a remote store, merging - * it with the local meta template to produce a final summary object. If no remote - * data is available, it logs a message indicating no stored docs yet. + * @description Retrieves and merges summary information from the local store with + * remote data, updating the local store's metadata and chunk lists. */ loadSummary = async () => { let summary: Summary = { @@ -130,7 +128,8 @@ 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]) => { - // Maps meta template keys to values from a summary object. + // Updates an object's property with the value from `summary.meta` or the original + // value if `summary.meta` is null or undefined. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -139,9 +138,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Asynchronously loads the document's summary and chunks from an external - * source, if not already loaded, and sets the `chunks` property to `true` once all - * chunks are loaded. + * @description Loads chunks of data asynchronously based on the current status of + * the document store, ensuring that all chunks are loaded when the method completes. */ load = async () => { if (!this.status.summary) { @@ -164,11 +162,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata object by merging it with an additional metadata - * object passed as an argument, effectively updating the existing metadata with new - * key-value pairs. + * @description Updates the metadata field of the class by combining the current + * metadata with additional metadata provided as an argument. * - * @param {Record*} additionalMeta - Used to add new metadata properties. + * @param {Record*} additionalMeta - Used to add new metadata to the + * existing metadata stored in the `this.meta` object. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -184,14 +182,16 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Loads a specific chunk of data asynchronously and updates the internal - * state if the chunk has not been loaded previously. If an error occurs during - * loading, it returns false; otherwise, it returns true to indicate success. + * @description Async loads a chunk of data from the server, checks if it has already + * been loaded, and if not, concats it with the existing content and stores it in the + * `chunks` property. Returns `true` if successful, `false` otherwise. * - * @param {number*} chunkIndex - Used to identify a specific chunk of data to load. + * @param {number*} chunkIndex - Used to identify the specific chunk being loaded out + * of the total number of chunks. * - * @returns {Promise*} Resolved to either true or false depending on whether - * the chunk loading operation was successful or failed. + * @returns {Promise*} A resolved promise if the chunk is successfully loaded + * and the content is appended to the internal `content` array, or rejected with + * `false` if an error occurs during loading. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -210,15 +210,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Asynchronously retrieves a file from a chunk-based storage system, - * given its path. It first checks if the summary is loaded and loads the corresponding - * chunk if necessary. If the file exists in the chunk, it returns the file object; - * otherwise, it returns null. + * @description Retrieves a file from the store based on its path, checking for its + * availability in the loaded chunks and returning it if found. * - * @param {string*} path - Used to specify the file path. + * @param {string*} path - Used to specify the file path to be retrieved, with its + * purpose being to identify the file within the chunked data. * - * @returns {Promise*} A promise that resolves to either a - * `StructuredFile` object or null. + * @returns {Promise*} Either a StructuredFile object or null + * if the file cannot be found or has not been loaded. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -261,10 +260,11 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of the lookup subtable. If the last subtable - * is full, it creates a new one; otherwise, it appends the path to the existing subtable. + * @description Adds a new path to the end of the current lookup subtable if necessary, + * ensuring the table's size does not exceed the maximum allowed. * - * @param {string*} path - Used to store or update a lookup table. + * @param {string*} path - Used to provide an additional string to be added to the + * lookup subtable, if necessary creating a new subtable if the last one is full. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -278,10 +278,11 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a new file to an existing chunk or creates a new chunk if the - * current one is full, ensuring that each chunk does not exceed a specified size (`CHUNK_SIZE`). + * @description Adds new files to the end of existing chunks or creates a new chunk + * if the last one is full. * - * @param {StructuredFile*} file - Intended to add files to chunks. + * @param {StructuredFile*} file - Used to add new files to the chunks array at the + * end. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -295,14 +296,13 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a structured file to the document store, updating it if the file - * already exists, and adding it to the end of lookup and chunks lists if not. It - * returns true on success or false with error information if failed. + * @description Adds a file to the store by checking its existence, updating the file + * if it exists, and then adding it to the end of the lookup and chunks arrays. * - * @param {StructuredFile*} file - Required for adding files to the collection. + * @param {StructuredFile*} file - Used to represent a file path that can be added + * to the content of an instance of the `ContentfulManagement` class. * - * @returns {boolean*} True if the file is successfully added and updated, and false - * otherwise. + * @returns {boolean*} 1 when a file is successfully added to the content and 0 otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -325,13 +325,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates an existing file or adds a new one to the store, checking for - * valid file path and loading chunks as necessary. + * @description Updates a file in the store by checking its existence, loading it if + * necessary, and storing it in the appropriate chunk and index position. * - * @param {StructuredFile*} file - Used to update a file's information. + * @param {StructuredFile*} file - Used to represent a file being updated. Its purpose + * is to store information about the file, such as its path, for the update operation. * - * @returns {Promise*} Either a boolean indicating whether the file was - * successfully updated or an error occurred during the update process. + * @returns {Promise*} A boolean value indicating whether the file was + * successfully updated or not. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -361,12 +362,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object with two properties, `meta` and `lookup`, which are - * likely metadata and a lookup table, respectively. This method provides a summary - * representation of the document store's data. + * @description Summarizes an object containing metadata (`meta`) and a lookup table + * (`lookup`). * - * @returns {Summary*} An object with two properties: meta and lookup, both containing - * values from the this object. + * @returns {Summary*} An object containing two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -375,12 +374,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Divides the content into chunks based on the `CHUNK_SIZE`, generates - * keys for each chunk, and stores them as key-value pairs in an object called - * `outputs`. The method returns this object. + * @description Extracts chunks of a document based on a chunk size and stores them + * in an object. * - * @returns {Record*} An object that maps string keys to values of various - * types. + * @returns {Record*} An object containing key-value pairs where each + * key is a unique identifier for a chunk of text and each value is the contents of + * that chunk. */ outputChunks(): Record { const outputs: Record = {}; From 0e9c11b28995944c0e8431392a93730b7c662e50 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Thu, 11 Jul 2024 10:57:18 +0000 Subject: [PATCH 19/30] Added comments to 15 functions across 1 file --- .komment/00000.json | 228 +++++++++++++++++++++++------------------- .komment/komment.json | 5 +- src/index.ts | 145 +++++++++++++++------------ 3 files changed, 209 insertions(+), 169 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index b76823c..a240206 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 a structured file containing files and chunks of files. It provides methods for adding new files to the structure, updating existing files in chunks, and generating high-quality documentation for the code. The code also includes a chunking system for organizing files into chunks based on a specified chunk size and keying system.", + "description": "A `DocumentStore` class that manages adding, retrieving, and updating files in a specific namespace-based folder structure. It takes in various parameters such as getRemote and additionalMeta and sets up an instance of a DocumentStore class with various parameters such as getRemote and additionalMeta. The code also includes functions for loading summary, loading chunks, getting file, adding file, and updating file.", "items": [ { - "id": "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768", + "id": "2f6fca88-3718-4191-f04b-0f145abb9930", "ancestors": [], - "description": "Manages a structured file containing code, organizing it into chunks based on file size and keying system, and providing methods for adding, updating, and querying files within the structure.", + "description": "Manages a structured file system for storing and retrieving code documentation. It provides methods for adding, updating, and loading files, as well as generating high-quality documentation outputs.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "Used to define the size of each chunk in the structured file, which determines the number of files that can be stored within a single chunk." + "description": "5, which represents the size of each chunk that stores files in the document store." }, { "name": "namespace", "type_name": "string", - "description": "Used to specify the namespace for the structured files, which is the container for all the code in this module" + "description": "Required to store the name or identifier of the namespace for which the instance of DocumentStore will work." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the document store instance, such as its version number, creation date, and last update date." + "description": "Used to store information about the metadata of the document." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to define a template for the generated meta documentation." + "description": "Used to set the template for meta data." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a table of file paths that map to chunks of code, allowing for fast lookups of files within a chunk or across multiple chunks." + "description": "Used to store a list of substrings that correspond to chunks of content in the document store." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store the structured files in a code's content, organized into chunks based on their size." + "description": "Used to store chunks of code in a particular order based on their file names." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store a list of files that make up the content of the document, including their paths and file sizes." + "description": "Used to store the actual code files." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to track the state of the store (e.g., if all chunks are loaded)" + "description": "Used to store information about the status of the document store, such as whether it has been loaded or not." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "000f97da-5d59-7ba5-e245-c10719c89d0f", + "id": "e65925a7-07ab-3180-c149-076a19c38dac", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Sets up instance variables to store namespace, getRemote method, and additional metadata. It also initializes chunk size, sets default values for version, created/updated dates, and populates lookup, chunks, and content arrays.", + "description": "Sets up various instance variables such as `namespace`, `getRemote`, `meta`, and `lookup`. It also initializes the `chunks` and `content` arrays, and sets the `status` object to false for both `summary` and `chunks`.", "params": [ { "name": "namespace", - "type_name": "string*", + "type_name": "string", "optional": false, - "description": "Required. Its purpose is to provide the name or identifier for the document store, which serves as an alias for accessing the data within the function.", + "description": "Used to set the namespace for the API calls.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>*", + "type_name": "(...args: any[]) => Promise>", "optional": false, - "description": "Used to provide a remote method that retrieves data for the document store.", + "description": "Required for initializing the instance of the class. It is used to fetch data from a remote source, which will be stored in the `content` property of the class instance.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record*", + "type_name": "Record", "optional": true, - "description": "Intended to store additional metadata related to the document.", + "description": "Used to store metadata that is not part of the standard document store version, such as custom properties or values that need to be associated with the chunk or the content.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const myDocStore = new DocumentStore(\"my-namespace\", (...args) => getRemote(args), { additionalMeta: {} });\n", - "description": "" + "code": "const myDocStore = new DocumentStore(\"my_namespace\", (...args) => {\n // getRemote method implementation here\n}, {\n additionalMetaDataHere: \"example\"\n});\n\nmyDocStore.setUpdatedAt(new Date());\nawait myDocStore.loadSummary();\n", + "description": "\nThe above example demonstrates how the DocumentStore constructor can be used to create an instance of a DocumentStore class with custom parameters such as getRemote and metadata. It also shows how the setUpdatedAt method can be used to update the meta data, and how the loadSummary method can be used to retrieve document summaries from a provider and update local meta data based on the remote summary." }, "name": null, "location": { @@ -182,20 +182,24 @@ "docLength": 12 }, { - "id": "f4103f74-ec2e-5e88-4648-f122e8d0bcf8", + "id": "7bee1690-6a61-8894-104f-a5d1d0021613", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Updates the `updatedAt` metadata field of an instance with the provided `Date` value, synchronizing the in-memory representation with the stored date.", + "description": "Updates the `updated_at` metadata field of the object, which stores information about when the document was last updated.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date*", - "description": "Used to update the \"updated at\" metadata for an entity." + "type_name": "Date", + "description": "Used to update the `updated_at` metadata field of the entity." } ], + "returns": { + "type_name": "Date", + "description": "The updated `updated_at` field for the current object." + }, "usage": { "language": "typescript", "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.setUpdatedAt(new Date());\n", @@ -217,15 +221,19 @@ "docLength": 7 }, { - "id": "d52dd231-066e-0188-fa42-7f6b322d1374", + "id": "6bb503c7-9268-66ae-6542-7d8987218a54", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Retrieves and merges summary information from the local store with remote data, updating the local store's metadata and chunk lists.", + "description": "Retrieves and updates summary information from the document store, merging it with the local metadata template, and storing it back in the document store.", "params": [], + "returns": { + "type_name": "Summary", + "description": "An object containing meta data and two arrays: lookup and chunks." + }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\nawait docStore.loadSummary(); // loads the summary from a remote store\n", + "code": "const documentStore = new DocumentStore();\ndocumentStore.CHUNK_SIZE = 100;\ndocumentStore.namespace = 'example';\ndocumentStore.getRemote = (...args) => {\n // implementation of remote call goes here\n};\ndocumentStore.metaTemplate = {};\ndocumentStore.lookup = [];\ndocumentStore.chunks = [];\ndocumentStore.content = [];\ndocumentStore.status = {};\n\n// Load the summary from the server\nawait documentStore.loadSummary();\n\n// Use the loaded summary to retrieve data from the store\nconst chunkData = documentStore.getChunk(10);\n", "description": "" }, "name": "loadSummary", @@ -244,12 +252,12 @@ "docLength": 4 }, { - "id": "c9ca0b54-c4c5-59b2-2b48-d449862cf6b9", + "id": "e6929d79-1d35-0681-4147-24e6f8e228b7", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768", - "d52dd231-066e-0188-fa42-7f6b322d1374" + "2f6fca88-3718-4191-f04b-0f145abb9930", + "6bb503c7-9268-66ae-6542-7d8987218a54" ], - "description": "Updates an object's property with the value from `summary.meta` or the original value if `summary.meta` is null or undefined.", + "description": "Sets the value of `this.meta` object properties using the `summary.meta` property as a fallback if it's undefined, or the original value if it's not defined in `summary.meta`.", "name": null, "location": { "start": 121, @@ -263,15 +271,19 @@ "docLength": null }, { - "id": "66ef23f5-cf1f-faa4-c54e-ae67b3cbedcb", + "id": "92e66cd4-c9e3-12a0-0749-f331456fb69a", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Loads chunks of data asynchronously based on the current status of the document store, ensuring that all chunks are loaded when the method completes.", + "description": "Asyncly loads chunks of data from the server based on their indices, and sets the `chunks` property to `true` once loading is complete.", "params": [], + "returns": { + "type_name": "boolean", + "description": "Whether the chunks have been loaded successfully or not." + }, "usage": { "language": "typescript", - "code": "const DocumentStore = new IDocumentStore();\nconst getRemote = (...args: any[]) => Promise>; // 3rd party library or service that provides the functionality\n\n// set up instance of a DocumentStore class with various parameters\nDocumentStore.CHUNK_SIZE = 50;\nDocumentStore.namespace = \"my-namespace\";\nDocumentStore.getRemote = getRemote;\nDocumentStore.metaTemplate = { // metadata\n version: '1.2.3',\n created_at: new Date(),\n updated_at: new Date(),\n};\n\n// initialize internal arrays and objects to store chunk data, content, and other meta information\nconst lookup = [];\nconst chunks = [];\nconst content = [];\nconst status = {\n summary: false,\n chunks: false,\n}\n\n// call the load function to retrieve the data from the remote service\nDocumentStore.load();\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.load(); //load summary and chunks of code\n", "description": "" }, "name": "load", @@ -290,23 +302,27 @@ "docLength": 3 }, { - "id": "70f2f0ca-7d6b-af8d-2c44-ae0e3823d30b", + "id": "168a9f8b-cbad-63a9-6549-6d33250d2d38", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Updates the metadata field of the class by combining the current metadata with additional metadata provided as an argument.", + "description": "Updates the metadata of a document by combining the existing metadata with any additional metadata provided as an argument, creating a new metadata object that includes all the updated values.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record*", - "description": "Used to add new metadata to the existing metadata stored in the `this.meta` object." + "type_name": "Record", + "description": "Used to provide additional metadata to be merged with the existing metadata of the component." } ], + "returns": { + "type_name": "Object", + "description": "An updated version of the `meta` object by combining it with the provided `additionalMeta` object." + }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.updateMetadata({version: '1.0', created_at: new Date(), updated_at: new Date()});\n", + "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.updateMetadata({version:'1.0', created_at: new Date(), updated_at: new Date()});\n", "description": "" }, "name": "updateMetadata", @@ -322,28 +338,28 @@ "docLength": null }, { - "id": "73a9661d-5f6f-eb89-2942-de75b051e42d", + "id": "7e334bd2-3cc3-cd87-9a46-17ae84d245d1", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Async loads a chunk of data from the server, checks if it has already been loaded, and if not, concats it with the existing content and stores it in the `chunks` property. Returns `true` if successful, `false` otherwise.", + "description": "Async loads a specific chunk from a remote source and adds it to the document store's content and chunks array if successful.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number*", - "description": "Used to identify the specific chunk being loaded out of the total number of chunks." + "type_name": "number", + "description": "Used to indicate which chunk to load from the server." } ], "returns": { - "type_name": "Promise*", - "description": "A resolved promise if the chunk is successfully loaded and the content is appended to the internal `content` array, or rejected with `false` if an error occurs during loading." + "type_name": "boolean", + "description": "True if the chunk was successfully loaded and false otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote);\nawait docStore.loadChunk(10);\n", - "description": "\nThe loadChunk method loads a chunk of data from a remote source, and returns a boolean value indicating whether the operation was successful or not. The parameter is an integer that represents the chunk index to be loaded." + "code": "const docStore = new DocumentStore(getRemote, integration);\nawait docStore.loadChunk(0)\nif (docStore.status.chunks) {\n // Access chunk data\n}\n", + "description": "" }, "name": "loadChunk", "location": { @@ -361,27 +377,27 @@ "docLength": 11 }, { - "id": "7bc7b6a7-0f4e-1dad-3540-f55d64348529", + "id": "c5fde800-c266-48a4-fc45-82212945def5", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Retrieves a file from the store based on its path, checking for its availability in the loaded chunks and returning it if found.", + "description": "Retrieves a file from a summary file and loads it into memory if necessary. It calculates the chunk and file index within that chunk, and checks if the file is already loaded in the correct chunk before returning it.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Used to specify the file path to be retrieved, with its purpose being to identify the file within the chunked data." + "type_name": "string", + "description": "Used to specify the file path being looked up." } ], "returns": { - "type_name": "Promise*", - "description": "Either a StructuredFile object or null if the file cannot be found or has not been loaded." + "type_name": "StructuredFile|null", + "description": "A file object or null if it's not found." }, "usage": { "language": "typescript", - "code": "// create a new instance of DocumentStore using getRemote and integration\nconst docstore = new DocumentStore(getRemote, integration);\n\n// load the summary file for the code documentation\nawait docstore.loadSummary();\n\n// retrieve a specific file from the code documentation\nconst myFile = await docstore.getFile(\"path/to/file\");\n", + "code": "const getFile = async (path: string): Promise => {\n const documentStore = new DocumentStore(getRemote);\n return await documentStore.getFile(path);\n};\n", "description": "" }, "name": "getFile", @@ -400,23 +416,27 @@ "docLength": 10 }, { - "id": "cc565ae3-c24c-ee93-a643-6722865fc6cf", + "id": "957457af-f25e-7784-2c4d-c6b7ce552b40", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Adds a new path to the end of the current lookup subtable if necessary, ensuring the table's size does not exceed the maximum allowed.", + "description": "Adds a new document to the end of the lookup table if it is full or appends it to the last existing entry in the table otherwise.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Used to provide an additional string to be added to the lookup subtable, if necessary creating a new subtable if the last one is full." + "type_name": "string", + "description": "Passed to the function as an argument. Its purpose is to represent the path or location where the new element should be added to the lookup subtable." } ], + "returns": { + "type_name": "string[]", + "description": "An array of strings." + }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfLookup(\"path/to/file1\");\ndocStore.addToEndOfLookup(\"path/to/file2\");\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup('somePath');\n", "description": "" }, "name": "addToEndOfLookup", @@ -435,23 +455,27 @@ "docLength": 6 }, { - "id": "28d0de60-313e-a19f-b549-f829a1aecaac", + "id": "66a11c94-0503-7798-354b-e1b693e89388", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Adds new files to the end of existing chunks or creates a new chunk if the last one is full.", + "description": "Adds files to the end of chunks if the last subtable is full or if the current chunk is at its maximum size.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Used to add new files to the chunks array at the end." + "type_name": "StructuredFile", + "description": "Used to add a file to the end of an array of chunks." } ], + "returns": { + "type_name": "number[]", + "description": "The updated length of the chunks array after adding a new file to the end of it." + }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore({ getRemote, integration });\ndocumentStore.addToEndOfChunks(file);\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks(file);\n", "description": "" }, "name": "addToEndOfChunks", @@ -470,27 +494,27 @@ "docLength": 10 }, { - "id": "4f34a0a1-24ae-9ab1-af45-c9831511941b", + "id": "d8973255-23ad-ed86-e04a-cc9c1c015dea", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Adds a file to the store by checking its existence, updating the file if it exists, and then adding it to the end of the lookup and chunks arrays.", + "description": "Adds a file to the document store if certain conditions are met, including that the `status.chunks` property is set and the provided file path exists. It updates the file in the store if it already exists, or adds it to the end of the lookup and chunks arrays if it does not exist.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Used to represent a file path that can be added to the content of an instance of the `ContentfulManagement` class." + "type_name": "StructuredFile", + "description": "Used to represent a file to be added to the content library." } ], "returns": { - "type_name": "boolean*", - "description": "1 when a file is successfully added to the content and 0 otherwise." + "type_name": "boolean", + "description": "True when the file is successfully added to the content, and false otherwise." }, "usage": { "language": "typescript", - "code": "const addFile = (file: StructuredFile): boolean => {\n if (!this.status.chunks) throw Error(\"Must call .load before adding files\");\n if (!file || !file.path) return false;\n\n if (this.fileExists(file.path)) {\n try {\n this.updateFile(file);\n return true;\n } catch (error) {\n console.error(error);\n return false;\n }\n }\n\n this.addToEndOfLookup(file.path);\n this.addToEndOfChunks(file);\n\n this.content.push(file);\n return true;\n }\n", + "code": "let docStore = new DocumentStore();\ndocStore.getRemote = async (file) => {\n let data = await fetch(file);\n return JSON.parse(data);\n}\ndocStore.addFile(\"https://example.com/document.txt\");\ndocStore.updateFile({\n path: \"https://example.com/document2.txt\",\n content: \"This is some new content\",\n});\n", "description": "" }, "name": "addFile", @@ -509,9 +533,9 @@ "docLength": 10 }, { - "id": "5f485833-a9d8-aab3-ab4a-60bd97dbae37", + "id": "15a9ce07-1cd4-d2aa-0844-d4de6d5161aa", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], "description": "Updates a file in the store by checking its existence, loading it if necessary, and storing it in the appropriate chunk and index position.", "params": [ @@ -519,17 +543,17 @@ "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Used to represent a file being updated. Its purpose is to store information about the file, such as its path, for the update operation." + "type_name": "StructuredFile", + "description": "Used to represent a file to be updated or added to the cache. Its purpose is to provide the file information for updating or adding it to the cache." } ], "returns": { - "type_name": "Promise*", - "description": "A boolean value indicating whether the file was successfully updated or not." + "type_name": "boolean", + "description": "Whether the file was updated successfully or not." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.updateFile({path: \"/some/file\"});\n", + "code": "const store = new DocumentStore({\n getRemote: async () => {\n return {\n \"chunks\": [{ \"name\": \"chunk1\", \"path\": \"/path/to/file1.txt\" }, { \"name\": \"chunk2\", \"path\": \"/path/to/file2.txt\" }],\n \"content\": [\n { \"path\": \"/path/to/file1.txt\", \"data\": \"this is the first file's data\" },\n { \"path\": \"/path/to/file2.txt\", \"data\": \"this is the second file's data\" }\n ]\n };\n },\n meta: {\n version: \"1.0.0\",\n created_at: new Date(),\n updated_at: new Date()\n }\n});\n\nconst result = await store.updateFile({ name: \"file3.txt\", path: \"/path/to/file3.txt\" });\n", "description": "" }, "name": "updateFile", @@ -548,19 +572,19 @@ "docLength": 10 }, { - "id": "020f09c8-5136-179a-6746-4e333d37fda3", + "id": "24da14cf-fcf8-76a6-ba41-d8723be0ce46", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Summarizes an object containing metadata (`meta`) and a lookup table (`lookup`).", + "description": "Generates an object summarizing the meta and lookup data of the document store.", "params": [], "returns": { - "type_name": "Summary*", - "description": "An object containing two properties: `meta` and `lookup`." + "type_name": "Summary", + "description": "A combination of two properties: `meta` and `lookup`." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nconst summary = store.outputSummary();\n", + "code": "const myDocumentStore = new DocumentStore(getRemote, integration);\nmyDocumentStore.outputSummary(); // { meta: ..., lookup: ... }\n", "description": "" }, "name": "outputSummary", @@ -579,20 +603,20 @@ "docLength": 6 }, { - "id": "d6b9b198-1f45-88b5-1e44-6cfa7c8edba1", + "id": "3439e126-4c64-dfa8-9541-263b48c34e2f", "ancestors": [ - "0f508e8b-11e6-e5a2-8a4b-fdcfd0f20768" + "2f6fca88-3718-4191-f04b-0f145abb9930" ], - "description": "Extracts chunks of a document based on a chunk size and stores them in an object.", + "description": "Generates and returns a Record object containing chunks of the document, where each chunk is represented by a key-value pair consisting of the chunk path and the chunk content.", "params": [], "returns": { - "type_name": "Record*", - "description": "An object containing key-value pairs where each key is a unique identifier for a chunk of text and each value is the contents of that chunk." + "type_name": "Record", + "description": "A collection of key-value pairs where each key is a unique chunk identifier and each value is the contents of that chunk." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.outputChunks();\n", - "description": "\nThis code will output a Record object containing chunk data." + "code": "const store = new DocumentStore(getRemote, integration);\nstore.outputChunks()\n", + "description": "" }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index 15ed784..1216f5b 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-11T09:40:15.160Z", + "updated_at": "2024-07-11T10:57:11.815Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -15,7 +15,8 @@ "49ec0772-f24b-4603-9a27-a31b96963bdf", "e7cb8cbb-d12f-4f42-adcc-cdf3756c8071", "ce9a50b9-f4ec-4487-80f0-aff229eec487", - "1f76280f-f42b-4585-ad9d-7178240fd285" + "1f76280f-f42b-4585-ad9d-7178240fd285", + "ef450461-80fd-45dd-81f4-48c5335ad528" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 61938de..7793d10 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Manages a structured file containing code, organizing it into chunks - * based on file size and keying system, and providing methods for adding, updating, - * and querying files within the structure. + * @description Manages a structured file system for storing and retrieving code + * documentation. It provides methods for adding, updating, and loading files, as + * well as generating high-quality documentation outputs. * * @implements {IDocumentStore} */ @@ -46,19 +46,19 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up instance variables to store namespace, getRemote method, and - * additional metadata. It also initializes chunk size, sets default values for - * version, created/updated dates, and populates lookup, chunks, and content arrays. + * @description Sets up various instance variables such as `namespace`, `getRemote`, + * `meta`, and `lookup`. It also initializes the `chunks` and `content` arrays, and + * sets the `status` object to false for both `summary` and `chunks`. * - * @param {string*} namespace - Required. Its purpose is to provide the name or - * identifier for the document store, which serves as an alias for accessing the data - * within the function. + * @param {string} namespace - Used to set the namespace for the API calls. * - * @param {(...args: any[]) => Promise>*} getRemote - Used to provide - * a remote method that retrieves data for the document store. + * @param {(...args: any[]) => Promise>} getRemote - Required for + * initializing the instance of the class. It is used to fetch data from a remote + * source, which will be stored in the `content` property of the class instance. * - * @param {Record*} additionalMeta - Intended to store additional metadata - * related to the document. + * @param {Record} additionalMeta - Used to store metadata that is not + * part of the standard document store version, such as custom properties or values + * that need to be associated with the chunk or the content. */ constructor( namespace: string, @@ -88,18 +88,24 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updatedAt` metadata field of an instance with the provided - * `Date` value, synchronizing the in-memory representation with the stored date. + * @description Updates the `updated_at` metadata field of the object, which stores + * information about when the document was last updated. * - * @param {Date*} updated_at - Used to update the "updated at" metadata for an entity. + * @param {Date} updated_at - Used to update the `updated_at` metadata field of the + * entity. + * + * @returns {Date} The updated `updated_at` field for the current object. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and merges summary information from the local store with - * remote data, updating the local store's metadata and chunk lists. + * @description Retrieves and updates summary information from the document store, + * merging it with the local metadata template, and storing it back in the document + * store. + * + * @returns {Summary} An object containing meta data and two arrays: lookup and chunks. */ loadSummary = async () => { let summary: Summary = { @@ -128,8 +134,8 @@ 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 an object's property with the value from `summary.meta` or the original - // value if `summary.meta` is null or undefined. + // Sets the value of `this.meta` object properties using the `summary.meta` property + // as a fallback if it's undefined, or the original value if it's not defined in `summary.meta`. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -138,8 +144,10 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Loads chunks of data asynchronously based on the current status of - * the document store, ensuring that all chunks are loaded when the method completes. + * @description Asyncly loads chunks of data from the server based on their indices, + * and sets the `chunks` property to `true` once loading is complete. + * + * @returns {boolean} Whether the chunks have been loaded successfully or not. */ load = async () => { if (!this.status.summary) { @@ -162,11 +170,15 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata field of the class by combining the current - * metadata with additional metadata provided as an argument. + * @description Updates the metadata of a document by combining the existing metadata + * with any additional metadata provided as an argument, creating a new metadata + * object that includes all the updated values. * - * @param {Record*} additionalMeta - Used to add new metadata to the - * existing metadata stored in the `this.meta` object. + * @param {Record} additionalMeta - Used to provide additional metadata + * to be merged with the existing metadata of the component. + * + * @returns {Object} An updated version of the `meta` object by combining it with the + * provided `additionalMeta` object. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -182,16 +194,12 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Async loads a chunk of data from the server, checks if it has already - * been loaded, and if not, concats it with the existing content and stores it in the - * `chunks` property. Returns `true` if successful, `false` otherwise. + * @description Async loads a specific chunk from a remote source and adds it to the + * document store's content and chunks array if successful. * - * @param {number*} chunkIndex - Used to identify the specific chunk being loaded out - * of the total number of chunks. + * @param {number} chunkIndex - Used to indicate which chunk to load from the server. * - * @returns {Promise*} A resolved promise if the chunk is successfully loaded - * and the content is appended to the internal `content` array, or rejected with - * `false` if an error occurs during loading. + * @returns {boolean} True if the chunk was successfully loaded and false otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -210,14 +218,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from the store based on its path, checking for its - * availability in the loaded chunks and returning it if found. + * @description Retrieves a file from a summary file and loads it into memory if + * necessary. It calculates the chunk and file index within that chunk, and checks + * if the file is already loaded in the correct chunk before returning it. * - * @param {string*} path - Used to specify the file path to be retrieved, with its - * purpose being to identify the file within the chunked data. + * @param {string} path - Used to specify the file path being looked up. * - * @returns {Promise*} Either a StructuredFile object or null - * if the file cannot be found or has not been loaded. + * @returns {StructuredFile|null} A file object or null if it's not found. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -260,11 +267,14 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of the current lookup subtable if necessary, - * ensuring the table's size does not exceed the maximum allowed. + * @description Adds a new document to the end of the lookup table if it is full or + * appends it to the last existing entry in the table otherwise. + * + * @param {string} path - Passed to the function as an argument. Its purpose is to + * represent the path or location where the new element should be added to the lookup + * subtable. * - * @param {string*} path - Used to provide an additional string to be added to the - * lookup subtable, if necessary creating a new subtable if the last one is full. + * @returns {string[]} An array of strings. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -278,11 +288,13 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds new files to the end of existing chunks or creates a new chunk - * if the last one is full. + * @description Adds files to the end of chunks if the last subtable is full or if + * the current chunk is at its maximum size. + * + * @param {StructuredFile} file - Used to add a file to the end of an array of chunks. * - * @param {StructuredFile*} file - Used to add new files to the chunks array at the - * end. + * @returns {number[]} The updated length of the chunks array after adding a new file + * to the end of it. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -296,13 +308,16 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the store by checking its existence, updating the file - * if it exists, and then adding it to the end of the lookup and chunks arrays. + * @description Adds a file to the document store if certain conditions are met, + * including that the `status.chunks` property is set and the provided file path + * exists. It updates the file in the store if it already exists, or adds it to the + * end of the lookup and chunks arrays if it does not exist. * - * @param {StructuredFile*} file - Used to represent a file path that can be added - * to the content of an instance of the `ContentfulManagement` class. + * @param {StructuredFile} file - Used to represent a file to be added to the content + * library. * - * @returns {boolean*} 1 when a file is successfully added to the content and 0 otherwise. + * @returns {boolean} True when the file is successfully added to the content, and + * false otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -328,11 +343,11 @@ class DocumentStore implements IDocumentStore { * @description Updates a file in the store by checking its existence, loading it if * necessary, and storing it in the appropriate chunk and index position. * - * @param {StructuredFile*} file - Used to represent a file being updated. Its purpose - * is to store information about the file, such as its path, for the update operation. + * @param {StructuredFile} file - Used to represent a file to be updated or added to + * the cache. Its purpose is to provide the file information for updating or adding + * it to the cache. * - * @returns {Promise*} A boolean value indicating whether the file was - * successfully updated or not. + * @returns {boolean} Whether the file was updated successfully or not. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -362,10 +377,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Summarizes an object containing metadata (`meta`) and a lookup table - * (`lookup`). + * @description Generates an object summarizing the meta and lookup data of the + * document store. * - * @returns {Summary*} An object containing two properties: `meta` and `lookup`. + * @returns {Summary} A combination of two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -374,12 +389,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Extracts chunks of a document based on a chunk size and stores them - * in an object. + * @description Generates and returns a Record object containing chunks of the document, + * where each chunk is represented by a key-value pair consisting of the chunk path + * and the chunk content. * - * @returns {Record*} An object containing key-value pairs where each - * key is a unique identifier for a chunk of text and each value is the contents of - * that chunk. + * @returns {Record} A collection of key-value pairs where each key is a + * unique chunk identifier and each value is the contents of that chunk. */ outputChunks(): Record { const outputs: Record = {}; From a341213f5f0397ac724167dbf34a242b7878b276 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Thu, 11 Jul 2024 11:00:03 +0000 Subject: [PATCH 20/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 230 +++++++++++++++++++----------------------- .komment/komment.json | 5 +- src/index.ts | 151 +++++++++++++-------------- 3 files changed, 176 insertions(+), 210 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index a240206..40176e9 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 adding, retrieving, and updating files in a specific namespace-based folder structure. It takes in various parameters such as getRemote and additionalMeta and sets up an instance of a DocumentStore class with various parameters such as getRemote and additionalMeta. The code also includes functions for loading summary, loading chunks, getting file, adding file, and updating file.", + "description": "A class called DocumentStore that manages a structured file system for storing and retrieving files based on their paths. It provides several methods for adding, updating, and looking up files in the system, including loading and unloading chunks of files, adding files to the end of a chunk or creating a new chunk if necessary, and outputting summaries or chunks of the file system. The class uses TypeScript packages such as `string_decoder` and `util`.", "items": [ { - "id": "2f6fca88-3718-4191-f04b-0f145abb9930", + "id": "ca42b4a8-1551-e782-9c4f-ee063f96de04", "ancestors": [], - "description": "Manages a structured file system for storing and retrieving code documentation. It provides methods for adding, updating, and loading files, as well as generating high-quality documentation outputs.", + "description": "Is responsible for managing and organizing code chunks based on their contents, creating a structured file that can be used for efficient content retrieval and manipulation.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "5, which represents the size of each chunk that stores files in the document store." + "description": "16777215 (0x664000). It represents the size of each chunk of code stored in the lookup table." }, { "name": "namespace", "type_name": "string", - "description": "Required to store the name or identifier of the namespace for which the instance of DocumentStore will work." + "description": "Used to define the namespace of the document store, which is required when creating a new instance of the `DocumentStore` class." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store information about the metadata of the document." + "description": "Used to store metadata about the content of the document, such as its version number, creation and update dates, and other information that can be used to manage the document and its content.}." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to set the template for meta data." + "description": "Used to define the template for meta data." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a list of substrings that correspond to chunks of content in the document store." + "description": "Used to store a two-dimensional array where each subarray represents a chunk, and each element within that subarray represents a file path stored at a specific index in that chunk." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store chunks of code in a particular order based on their file names." + "description": "Used to store chunks of code in a structured way, with each chunk containing a group of files of similar size." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store the actual code files." + "description": "Used to store all added files, including their paths and chunks index." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to store information about the status of the document store, such as whether it has been loaded or not." + "description": "Used to track whether the store has finished loading files (summary: true) or not(summary: false)." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "e65925a7-07ab-3180-c149-076a19c38dac", + "id": "5c005061-4a98-6b88-f14a-75554498ac9c", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Sets up various instance variables such as `namespace`, `getRemote`, `meta`, and `lookup`. It also initializes the `chunks` and `content` arrays, and sets the `status` object to false for both `summary` and `chunks`.", + "description": "Sets up class variables and properties, including `CHUNK_SIZE`, `namespace`, `getRemote`, `meta`, `lookup`, `chunks`, and `content`. It also checks for required inputs and sets default values for some properties.", "params": [ { "name": "namespace", - "type_name": "string", + "type_name": "string*", "optional": false, - "description": "Used to set the namespace for the API calls.", + "description": "Used to set the name space for the chunker, which allows the chunker to identify which chunks belong to the same namespace.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>", + "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required for initializing the instance of the class. It is used to fetch data from a remote source, which will be stored in the `content` property of the class instance.", + "description": "Required to return a promise containing a record with data.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record", + "type_name": "Record*", "optional": true, - "description": "Used to store metadata that is not part of the standard document store version, such as custom properties or values that need to be associated with the chunk or the content.", + "description": "Used to store custom metadata for the document.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const myDocStore = new DocumentStore(\"my_namespace\", (...args) => {\n // getRemote method implementation here\n}, {\n additionalMetaDataHere: \"example\"\n});\n\nmyDocStore.setUpdatedAt(new Date());\nawait myDocStore.loadSummary();\n", - "description": "\nThe above example demonstrates how the DocumentStore constructor can be used to create an instance of a DocumentStore class with custom parameters such as getRemote and metadata. It also shows how the setUpdatedAt method can be used to update the meta data, and how the loadSummary method can be used to retrieve document summaries from a provider and update local meta data based on the remote summary." + "code": "const documentStore = new DocumentStore(\"my-namespace\", getRemoteMethod, { additionalMeta });\ndocumentStore.loadSummary();\n", + "description": "" }, "name": null, "location": { @@ -182,24 +182,20 @@ "docLength": 12 }, { - "id": "7bee1690-6a61-8894-104f-a5d1d0021613", + "id": "908a15dd-7075-0e93-bf4e-12f0c3409d48", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Updates the `updated_at` metadata field of the object, which stores information about when the document was last updated.", + "description": "Updates the `updatedAt` metadata property with the provided `Date` object.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date", - "description": "Used to update the `updated_at` metadata field of the entity." + "type_name": "Date*", + "description": "Used to update the \"updated at\" metadata of the object being updated." } ], - "returns": { - "type_name": "Date", - "description": "The updated `updated_at` field for the current object." - }, "usage": { "language": "typescript", "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.setUpdatedAt(new Date());\n", @@ -221,20 +217,16 @@ "docLength": 7 }, { - "id": "6bb503c7-9268-66ae-6542-7d8987218a54", + "id": "7591bb3e-df47-afa5-f641-1831c1f92326", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Retrieves and updates summary information from the document store, merging it with the local metadata template, and storing it back in the document store.", + "description": "Updates and stores summary information in the local store based on remote information, and sets metadata properties for the local store.", "params": [], - "returns": { - "type_name": "Summary", - "description": "An object containing meta data and two arrays: lookup and chunks." - }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.CHUNK_SIZE = 100;\ndocumentStore.namespace = 'example';\ndocumentStore.getRemote = (...args) => {\n // implementation of remote call goes here\n};\ndocumentStore.metaTemplate = {};\ndocumentStore.lookup = [];\ndocumentStore.chunks = [];\ndocumentStore.content = [];\ndocumentStore.status = {};\n\n// Load the summary from the server\nawait documentStore.loadSummary();\n\n// Use the loaded summary to retrieve data from the store\nconst chunkData = documentStore.getChunk(10);\n", - "description": "" + "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.loadSummary();\n", + "description": "\nHere, the loadSummary function is called to download the summary of documents from a remote source." }, "name": "loadSummary", "location": { @@ -252,12 +244,12 @@ "docLength": 4 }, { - "id": "e6929d79-1d35-0681-4147-24e6f8e228b7", + "id": "98331336-679b-8e8a-4c45-afe45ef2f5c4", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930", - "6bb503c7-9268-66ae-6542-7d8987218a54" + "ca42b4a8-1551-e782-9c4f-ee063f96de04", + "7591bb3e-df47-afa5-f641-1831c1f92326" ], - "description": "Sets the value of `this.meta` object properties using the `summary.meta` property as a fallback if it's undefined, or the original value if it's not defined in `summary.meta`.", + "description": "Updates the `this.meta` object with values from the `summary.meta` object or the provided `value`, if the `summary` object is not defined or does not have a property for the specified key.", "name": null, "location": { "start": 121, @@ -271,19 +263,15 @@ "docLength": null }, { - "id": "92e66cd4-c9e3-12a0-0749-f331456fb69a", + "id": "7cbb6863-86a1-72bb-0044-fb20b693df1f", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Asyncly loads chunks of data from the server based on their indices, and sets the `chunks` property to `true` once loading is complete.", + "description": "Async loads the document chunks by iterating through the chunk indices and loading each chunk synchronously using the `loadChunk` method. It also sets the `chunks` property to `true` once all chunks have been loaded.", "params": [], - "returns": { - "type_name": "boolean", - "description": "Whether the chunks have been loaded successfully or not." - }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.load(); //load summary and chunks of code\n", + "code": "const store = new DocumentStore(getRemote);\nstore.load();\n", "description": "" }, "name": "load", @@ -302,27 +290,23 @@ "docLength": 3 }, { - "id": "168a9f8b-cbad-63a9-6549-6d33250d2d38", + "id": "12db6d76-5d1e-64a5-274e-fa20e96e3b84", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Updates the metadata of a document by combining the existing metadata with any additional metadata provided as an argument, creating a new metadata object that includes all the updated values.", + "description": "Updates the metadata of a document by combining the existing metadata and additional metadata passed as an argument, creating a new metadata object that includes both.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record", - "description": "Used to provide additional metadata to be merged with the existing metadata of the component." + "type_name": "Record*", + "description": "Used to update the metadata by adding new key-value pairs to the existing ones." } ], - "returns": { - "type_name": "Object", - "description": "An updated version of the `meta` object by combining it with the provided `additionalMeta` object." - }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.updateMetadata({version:'1.0', created_at: new Date(), updated_at: new Date()});\n", + "code": "// Instantiate the DocumentStore class with the getRemote parameter and the integration object.\nconst documentStore = new DocumentStore(getRemote, integration);\n\n// Update metadata by passing a record of additional meta information to the updateMetadata method.\ndocumentStore.updateMetadata({ version: \"1.0.0\" });\n", "description": "" }, "name": "updateMetadata", @@ -338,27 +322,27 @@ "docLength": null }, { - "id": "7e334bd2-3cc3-cd87-9a46-17ae84d245d1", + "id": "946898a7-7531-db97-8b45-0e9f2e6d3ab8", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Async loads a specific chunk from a remote source and adds it to the document store's content and chunks array if successful.", + "description": "Async loads a chunk of the document from the server, given its index, and appends it to the content and chunks collections if successful.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number", - "description": "Used to indicate which chunk to load from the server." + "type_name": "number*", + "description": "Used to identify the chunk being loaded. It serves as an index to access the appropriate chunk data from the `chunks` array." } ], "returns": { - "type_name": "boolean", - "description": "True if the chunk was successfully loaded and false otherwise." + "type_name": "Promise*", + "description": "Resolved to true if the chunk was loaded successfully, or false otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\nawait docStore.loadChunk(0)\nif (docStore.status.chunks) {\n // Access chunk data\n}\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.loadChunk(0);\n", "description": "" }, "name": "loadChunk", @@ -377,27 +361,27 @@ "docLength": 11 }, { - "id": "c5fde800-c266-48a4-fc45-82212945def5", + "id": "08b11a36-878f-7d97-cd46-ba854d1814eb", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Retrieves a file from a summary file and loads it into memory if necessary. It calculates the chunk and file index within that chunk, and checks if the file is already loaded in the correct chunk before returning it.", + "description": "Retrieves a file from the store based on its path. It first checks if the summary has been loaded, then calculates the chunk it is in and loads it if necessary. Finally, it returns the file index within that chunk.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "Used to specify the file path being looked up." + "type_name": "string*", + "description": "Used to identify the file being retrieved, which must match the path of a file in the current summary." } ], "returns": { - "type_name": "StructuredFile|null", - "description": "A file object or null if it's not found." + "type_name": "Promise*", + "description": "Either a StructuredFile object or null if the file cannot be found or has already been loaded." }, "usage": { "language": "typescript", - "code": "const getFile = async (path: string): Promise => {\n const documentStore = new DocumentStore(getRemote);\n return await documentStore.getFile(path);\n};\n", + "code": "const docStore = new DocumentStore(getRemote);\n// Load summary\ndocStore.loadSummary();\n// Get a file from the store\nconst file = await docStore.getFile(\"path/to/file\");\n", "description": "" }, "name": "getFile", @@ -416,27 +400,23 @@ "docLength": 10 }, { - "id": "957457af-f25e-7784-2c4d-c6b7ce552b40", + "id": "fcc560b4-31c1-8da9-6245-541014c03b97", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Adds a new document to the end of the lookup table if it is full or appends it to the last existing entry in the table otherwise.", + "description": "Adds a new path to the end of the lookup subtable if it's not already full, or appends it to the last entry in the table otherwise.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "Passed to the function as an argument. Its purpose is to represent the path or location where the new element should be added to the lookup subtable." + "type_name": "string*", + "description": "Used to add a new entry to the lookup subtable, either by creating a new table if it does not exist or by adding a new entry to an existing one." } ], - "returns": { - "type_name": "string[]", - "description": "An array of strings." - }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup('somePath');\n", + "code": "const docStore = new DocumentStore();\n\ndocStore.getRemote = async () => {\n // this function returns a promise of a document object\n return { content: \"This is some sample text\" };\n};\n\n// Call addToEndOfLookup method with the path argument \ndocStore.addToEndOfLookup(\"some/path\");\n", "description": "" }, "name": "addToEndOfLookup", @@ -455,27 +435,23 @@ "docLength": 6 }, { - "id": "66a11c94-0503-7798-354b-e1b693e89388", + "id": "da2cfc75-9144-bcbd-2145-a9e23a9cb8b9", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Adds files to the end of chunks if the last subtable is full or if the current chunk is at its maximum size.", + "description": "Adds new files to the end of existing chunks or creates a new chunk if the last one is full, maintaining a fixed chunk size.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Used to add a file to the end of an array of chunks." + "type_name": "StructuredFile*", + "description": "Used to add a file to the end of a list of chunks." } ], - "returns": { - "type_name": "number[]", - "description": "The updated length of the chunks array after adding a new file to the end of it." - }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks(file);\n", + "code": "const store = new DocumentStore({ getRemote, integration });\nstore.addToEndOfChunks(file); // Adds a file to the last chunk if it is full, otherwise adds the file to the last lookup subtable.\n", "description": "" }, "name": "addToEndOfChunks", @@ -494,27 +470,27 @@ "docLength": 10 }, { - "id": "d8973255-23ad-ed86-e04a-cc9c1c015dea", + "id": "c117558c-2938-849c-2c4e-76f7d8b8f1b3", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Adds a file to the document store if certain conditions are met, including that the `status.chunks` property is set and the provided file path exists. It updates the file in the store if it already exists, or adds it to the end of the lookup and chunks arrays if it does not exist.", + "description": "Adds a file to the document store if the file exists and has not already been added. If the file exists, it updates its metadata and adds it to the end of the lookup and chunks lists.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Used to represent a file to be added to the content library." + "type_name": "StructuredFile*", + "description": "Used to represent a file that can be added to the content." } ], "returns": { - "type_name": "boolean", - "description": "True when the file is successfully added to the content, and false otherwise." + "type_name": "boolean*", + "description": "1 if the file was successfully added to the lookup and chunks, and 0 otherwise." }, "usage": { "language": "typescript", - "code": "let docStore = new DocumentStore();\ndocStore.getRemote = async (file) => {\n let data = await fetch(file);\n return JSON.parse(data);\n}\ndocStore.addFile(\"https://example.com/document.txt\");\ndocStore.updateFile({\n path: \"https://example.com/document2.txt\",\n content: \"This is some new content\",\n});\n", + "code": "const docStore = new DocumentStore();\nlet file = {path:\"/path/to/file\", content:\"content of the file\"};\ndocStore.addFile(file);\n", "description": "" }, "name": "addFile", @@ -533,27 +509,27 @@ "docLength": 10 }, { - "id": "15a9ce07-1cd4-d2aa-0844-d4de6d5161aa", + "id": "55404fb6-7114-63a3-4a47-f0b4797d6678", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Updates a file in the store by checking its existence, loading it if necessary, and storing it in the appropriate chunk and index position.", + "description": "Updates a file in the store by checking if it exists, loading any necessary chunks, and storing the updated file in the appropriate position within the chunk.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Used to represent a file to be updated or added to the cache. Its purpose is to provide the file information for updating or adding it to the cache." + "type_name": "StructuredFile*", + "description": "Used to represent a file within the application's file system, with its path serving as the reference for updating the file's status within the chunks." } ], "returns": { - "type_name": "boolean", - "description": "Whether the file was updated successfully or not." + "type_name": "Promise*", + "description": "Ether *true or *false depending on whether the file was successfully updated." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore({\n getRemote: async () => {\n return {\n \"chunks\": [{ \"name\": \"chunk1\", \"path\": \"/path/to/file1.txt\" }, { \"name\": \"chunk2\", \"path\": \"/path/to/file2.txt\" }],\n \"content\": [\n { \"path\": \"/path/to/file1.txt\", \"data\": \"this is the first file's data\" },\n { \"path\": \"/path/to/file2.txt\", \"data\": \"this is the second file's data\" }\n ]\n };\n },\n meta: {\n version: \"1.0.0\",\n created_at: new Date(),\n updated_at: new Date()\n }\n});\n\nconst result = await store.updateFile({ name: \"file3.txt\", path: \"/path/to/file3.txt\" });\n", + "code": "const updateFile = async (file: StructuredFile): Promise => {\n const documentStore = new DocumentStore(getRemote, integration);\n await documentStore.updateFile(file);\n};\n\n// example of how the method would be called\nconst fileToUpdate = {\n path: '/path/to/file',\n content: 'file content here'\n}\nupdateFile(fileToUpdate);\n", "description": "" }, "name": "updateFile", @@ -572,20 +548,20 @@ "docLength": 10 }, { - "id": "24da14cf-fcf8-76a6-ba41-d8723be0ce46", + "id": "d7ff2f96-db33-75b4-f64d-1929e2ecf6d2", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Generates an object summarizing the meta and lookup data of the document store.", + "description": "Returns an object containing the class's `meta` and `lookup` properties, providing a concise summary of its state.", "params": [], "returns": { - "type_name": "Summary", - "description": "A combination of two properties: `meta` and `lookup`." + "type_name": "Summary*", + "description": "An object containing two properties: `meta` and `lookup`." }, "usage": { "language": "typescript", - "code": "const myDocumentStore = new DocumentStore(getRemote, integration);\nmyDocumentStore.outputSummary(); // { meta: ..., lookup: ... }\n", - "description": "" + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.metaTemplate = {\n version: '1.0',\n created_at: new Date(),\n updated_at: new Date()\n};\ndocumentStore.lookup = ['firstName', 'lastName'];\nconst summary = documentStore.outputSummary();\n", + "description": "\nIn this example, the end user first instantiates a `DocumentStore` class with the necessary parameters for getting remote and integrations. They then set up the metaTemplate object and the lookup array. Finally, they call the `outputSummary()` method to generate the summary of the data in the `documentStore`. The resulting summary is stored in the `summary` variable.\nNote that this is just an illustrative example and may not be applicable or suitable for any specific use case." }, "name": "outputSummary", "location": { @@ -603,19 +579,19 @@ "docLength": 6 }, { - "id": "3439e126-4c64-dfa8-9541-263b48c34e2f", + "id": "93ef91ec-c0ea-eda9-8546-5ceca66eb738", "ancestors": [ - "2f6fca88-3718-4191-f04b-0f145abb9930" + "ca42b4a8-1551-e782-9c4f-ee063f96de04" ], - "description": "Generates and returns a Record object containing chunks of the document, where each chunk is represented by a key-value pair consisting of the chunk path and the chunk content.", + "description": "Generates an object containing key-value pairs, where each key corresponds to a chunk of the document and each value is the contents of that chunk.", "params": [], "returns": { - "type_name": "Record", - "description": "A collection of key-value pairs where each key is a unique chunk identifier and each value is the contents of that chunk." + "type_name": "Record*", + "description": "An object containing key-value pairs where the keys are string chunk paths and the values are the corresponding chunk of text." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.outputChunks()\n", + "code": "const documentStore = new DocumentStore(getRemote, integration); // Setup instance of DocumentStore with getRemote and integration objects\ndocumentStore.CHUNK_SIZE = 20; // set chunk size to 20\n\nconst outputs: Record = documentStore.outputChunks(); // Generate chunks using the outputChunks method\n\n", "description": "" }, "name": "outputChunks", diff --git a/.komment/komment.json b/.komment/komment.json index 1216f5b..7aa782a 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-11T10:57:11.815Z", + "updated_at": "2024-07-11T10:59:56.158Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -16,7 +16,8 @@ "e7cb8cbb-d12f-4f42-adcc-cdf3756c8071", "ce9a50b9-f4ec-4487-80f0-aff229eec487", "1f76280f-f42b-4585-ad9d-7178240fd285", - "ef450461-80fd-45dd-81f4-48c5335ad528" + "ef450461-80fd-45dd-81f4-48c5335ad528", + "dbb10926-033f-4543-b4cc-bee6999543f8" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 7793d10..30ca7c7 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Manages a structured file system for storing and retrieving code - * documentation. It provides methods for adding, updating, and loading files, as - * well as generating high-quality documentation outputs. + * @description Is responsible for managing and organizing code chunks based on their + * contents, creating a structured file that can be used for efficient content retrieval + * and manipulation. * * @implements {IDocumentStore} */ @@ -46,19 +46,18 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up various instance variables such as `namespace`, `getRemote`, - * `meta`, and `lookup`. It also initializes the `chunks` and `content` arrays, and - * sets the `status` object to false for both `summary` and `chunks`. + * @description Sets up class variables and properties, including `CHUNK_SIZE`, + * `namespace`, `getRemote`, `meta`, `lookup`, `chunks`, and `content`. It also checks + * for required inputs and sets default values for some properties. * - * @param {string} namespace - Used to set the namespace for the API calls. + * @param {string*} namespace - Used to set the name space for the chunker, which + * allows the chunker to identify which chunks belong to the same namespace. * - * @param {(...args: any[]) => Promise>} getRemote - Required for - * initializing the instance of the class. It is used to fetch data from a remote - * source, which will be stored in the `content` property of the class instance. + * @param {(...args: any[]) => Promise>*} getRemote - Required to + * return a promise containing a record with data. * - * @param {Record} additionalMeta - Used to store metadata that is not - * part of the standard document store version, such as custom properties or values - * that need to be associated with the chunk or the content. + * @param {Record*} additionalMeta - Used to store custom metadata for + * the document. */ constructor( namespace: string, @@ -88,24 +87,18 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of the object, which stores - * information about when the document was last updated. + * @description Updates the `updatedAt` metadata property with the provided `Date` object. * - * @param {Date} updated_at - Used to update the `updated_at` metadata field of the - * entity. - * - * @returns {Date} The updated `updated_at` field for the current object. + * @param {Date*} updated_at - Used to update the "updated at" metadata of the object + * being updated. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates summary information from the document store, - * merging it with the local metadata template, and storing it back in the document - * store. - * - * @returns {Summary} An object containing meta data and two arrays: lookup and chunks. + * @description Updates and stores summary information in the local store based on + * remote information, and sets metadata properties for the local store. */ loadSummary = async () => { let summary: Summary = { @@ -134,8 +127,9 @@ 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]) => { - // Sets the value of `this.meta` object properties using the `summary.meta` property - // as a fallback if it's undefined, or the original value if it's not defined in `summary.meta`. + // Updates the `this.meta` object with values from the `summary.meta` object or the + // provided `value`, if the `summary` object is not defined or does not have a property + // for the specified key. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -144,10 +138,9 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Asyncly loads chunks of data from the server based on their indices, - * and sets the `chunks` property to `true` once loading is complete. - * - * @returns {boolean} Whether the chunks have been loaded successfully or not. + * @description Async loads the document chunks by iterating through the chunk indices + * and loading each chunk synchronously using the `loadChunk` method. It also sets + * the `chunks` property to `true` once all chunks have been loaded. */ load = async () => { if (!this.status.summary) { @@ -171,14 +164,11 @@ class DocumentStore implements IDocumentStore { /** * @description Updates the metadata of a document by combining the existing metadata - * with any additional metadata provided as an argument, creating a new metadata - * object that includes all the updated values. + * and additional metadata passed as an argument, creating a new metadata object that + * includes both. * - * @param {Record} additionalMeta - Used to provide additional metadata - * to be merged with the existing metadata of the component. - * - * @returns {Object} An updated version of the `meta` object by combining it with the - * provided `additionalMeta` object. + * @param {Record*} additionalMeta - Used to update the metadata by + * adding new key-value pairs to the existing ones. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -194,12 +184,14 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Async loads a specific chunk from a remote source and adds it to the - * document store's content and chunks array if successful. + * @description Async loads a chunk of the document from the server, given its index, + * and appends it to the content and chunks collections if successful. * - * @param {number} chunkIndex - Used to indicate which chunk to load from the server. + * @param {number*} chunkIndex - Used to identify the chunk being loaded. It serves + * as an index to access the appropriate chunk data from the `chunks` array. * - * @returns {boolean} True if the chunk was successfully loaded and false otherwise. + * @returns {Promise*} Resolved to true if the chunk was loaded successfully, + * or false otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -218,13 +210,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from a summary file and loads it into memory if - * necessary. It calculates the chunk and file index within that chunk, and checks - * if the file is already loaded in the correct chunk before returning it. + * @description Retrieves a file from the store based on its path. It first checks + * if the summary has been loaded, then calculates the chunk it is in and loads it + * if necessary. Finally, it returns the file index within that chunk. * - * @param {string} path - Used to specify the file path being looked up. + * @param {string*} path - Used to identify the file being retrieved, which must match + * the path of a file in the current summary. * - * @returns {StructuredFile|null} A file object or null if it's not found. + * @returns {Promise*} Either a StructuredFile object or null + * if the file cannot be found or has already been loaded. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -267,14 +261,12 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new document to the end of the lookup table if it is full or - * appends it to the last existing entry in the table otherwise. - * - * @param {string} path - Passed to the function as an argument. Its purpose is to - * represent the path or location where the new element should be added to the lookup - * subtable. + * @description Adds a new path to the end of the lookup subtable if it's not already + * full, or appends it to the last entry in the table otherwise. * - * @returns {string[]} An array of strings. + * @param {string*} path - Used to add a new entry to the lookup subtable, either by + * creating a new table if it does not exist or by adding a new entry to an existing + * one. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -288,13 +280,10 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds files to the end of chunks if the last subtable is full or if - * the current chunk is at its maximum size. - * - * @param {StructuredFile} file - Used to add a file to the end of an array of chunks. + * @description Adds new files to the end of existing chunks or creates a new chunk + * if the last one is full, maintaining a fixed chunk size. * - * @returns {number[]} The updated length of the chunks array after adding a new file - * to the end of it. + * @param {StructuredFile*} file - Used to add a file to the end of a list of chunks. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -308,16 +297,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the document store if certain conditions are met, - * including that the `status.chunks` property is set and the provided file path - * exists. It updates the file in the store if it already exists, or adds it to the - * end of the lookup and chunks arrays if it does not exist. + * @description Adds a file to the document store if the file exists and has not + * already been added. If the file exists, it updates its metadata and adds it to the + * end of the lookup and chunks lists. * - * @param {StructuredFile} file - Used to represent a file to be added to the content - * library. + * @param {StructuredFile*} file - Used to represent a file that can be added to the + * content. * - * @returns {boolean} True when the file is successfully added to the content, and - * false otherwise. + * @returns {boolean*} 1 if the file was successfully added to the lookup and chunks, + * and 0 otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -340,14 +328,16 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the store by checking its existence, loading it if - * necessary, and storing it in the appropriate chunk and index position. + * @description Updates a file in the store by checking if it exists, loading any + * necessary chunks, and storing the updated file in the appropriate position within + * the chunk. * - * @param {StructuredFile} file - Used to represent a file to be updated or added to - * the cache. Its purpose is to provide the file information for updating or adding - * it to the cache. + * @param {StructuredFile*} file - Used to represent a file within the application's + * file system, with its path serving as the reference for updating the file's status + * within the chunks. * - * @returns {boolean} Whether the file was updated successfully or not. + * @returns {Promise*} Ether *true or *false depending on whether the file + * was successfully updated. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -377,10 +367,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Generates an object summarizing the meta and lookup data of the - * document store. + * @description Returns an object containing the class's `meta` and `lookup` properties, + * providing a concise summary of its state. * - * @returns {Summary} A combination of two properties: `meta` and `lookup`. + * @returns {Summary*} An object containing two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -389,12 +379,11 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Generates and returns a Record object containing chunks of the document, - * where each chunk is represented by a key-value pair consisting of the chunk path - * and the chunk content. + * @description Generates an object containing key-value pairs, where each key + * corresponds to a chunk of the document and each value is the contents of that chunk. * - * @returns {Record} A collection of key-value pairs where each key is a - * unique chunk identifier and each value is the contents of that chunk. + * @returns {Record*} An object containing key-value pairs where the + * keys are string chunk paths and the values are the corresponding chunk of text. */ outputChunks(): Record { const outputs: Record = {}; From 3e285a4d82105aee50807bee3b9d1ac551e5b000 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Thu, 11 Jul 2024 11:04:16 +0000 Subject: [PATCH 21/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 182 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 139 ++++++++++++++++---------------- 3 files changed, 162 insertions(+), 164 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 40176e9..26c3a85 100644 --- a/.komment/00000.json +++ b/.komment/00000.json @@ -4,12 +4,12 @@ "path": "src/index.ts", "content": { "structured": { - "description": "A class called DocumentStore that manages a structured file system for storing and retrieving files based on their paths. It provides several methods for adding, updating, and looking up files in the system, including loading and unloading chunks of files, adding files to the end of a chunk or creating a new chunk if necessary, and outputting summaries or chunks of the file system. The class uses TypeScript packages such as `string_decoder` and `util`.", + "description": "A DocumentStore class that manages structured data files, dividing each file into chunks based on a specified chunk size. The store keeps track of the lookup table and chunks, allowing for efficient retrieval and addition of files. The class provides methods for adding files, updating existing ones, and generating summaries and records of chunks.", "items": [ { - "id": "ca42b4a8-1551-e782-9c4f-ee063f96de04", + "id": "f3c4f7db-cd89-ef84-f649-e72684e525e9", "ancestors": [], - "description": "Is responsible for managing and organizing code chunks based on their contents, creating a structured file that can be used for efficient content retrieval and manipulation.", + "description": "Is designed to manage structured files and provide a mechanism for loading, storing, and retrieving file data, as well as generating documentation and records of chunks of code.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "16777215 (0x664000). It represents the size of each chunk of code stored in the lookup table." + "description": "1 by default. It determines how many files each chunk will hold before a new chunk is created, ensuring that chunks do not exceed a certain size limit." }, { "name": "namespace", "type_name": "string", - "description": "Used to define the namespace of the document store, which is required when creating a new instance of the `DocumentStore` class." + "description": "Used to store a namespace for storing documents and metadata. It seems that this namespace is used as part of the path when retrieving or storing chunks of code." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the content of the document, such as its version number, creation and update dates, and other information that can be used to manage the document and its content.}." + "description": "Used to store metadata about the structured file." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to define the template for meta data." + "description": "Not defined anywhere in this code snippet." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a two-dimensional array where each subarray represents a chunk, and each element within that subarray represents a file path stored at a specific index in that chunk." + "description": "Used to store a lookup table of file paths within each chunk of the document's content." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store chunks of code in a structured way, with each chunk containing a group of files of similar size." + "description": "2D array of file chunks, where each chunk contains a fixed number (CHUNK_SIZE) of files. The index of the outer array represents the chunk ID, and the inner array contains the files within that chunk." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store all added files, including their paths and chunks index." + "description": "2-dimensional array, where each inner array represents a chunk of files loaded from the provider. The array is used to store the file objects that have been successfully added to the structured file." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to track whether the store has finished loading files (summary: true) or not(summary: false)." + "description": "Used to keep track of the status of the document store." } ], "name": "DocumentStore", @@ -133,37 +133,37 @@ "docLength": null }, { - "id": "5c005061-4a98-6b88-f14a-75554498ac9c", + "id": "705aa0ee-e8f4-778a-6547-32fb777359c4", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Sets up class variables and properties, including `CHUNK_SIZE`, `namespace`, `getRemote`, `meta`, `lookup`, `chunks`, and `content`. It also checks for required inputs and sets default values for some properties.", + "description": "Initializes an instance with required properties such as namespace, getRemote method, and optional additional metadata. It sets default values for CHUNK_SIZE, updates meta information, and initializes various arrays and status flags for the document store.", "params": [ { "name": "namespace", "type_name": "string*", "optional": false, - "description": "Used to set the name space for the chunker, which allows the chunker to identify which chunks belong to the same namespace.", + "description": "Required for the constructor.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required to return a promise containing a record with data.", + "description": "Used to fetch data from a remote source.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record*", "optional": true, - "description": "Used to store custom metadata for the document.", + "description": "Used to add custom metadata to the object.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\"my-namespace\", getRemoteMethod, { additionalMeta });\ndocumentStore.loadSummary();\n", + "code": "const documentStore = new DocumentStore(\n 'my-namespace',\n async (...args: any[]) => {\n // Implementation of getRemote method\n },\n { some: 'additional', meta: 'information' }\n);\n", "description": "" }, "name": null, @@ -182,23 +182,23 @@ "docLength": 12 }, { - "id": "908a15dd-7075-0e93-bf4e-12f0c3409d48", + "id": "b99de814-2260-ce80-a940-c16e80bb1d23", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Updates the `updatedAt` metadata property with the provided `Date` object.", + "description": "Updates the `updated_at` property with a given `Date` value, effectively setting or updating the document's last updated timestamp.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date*", - "description": "Used to update the \"updated at\" metadata of the object being updated." + "description": "Used to update the `updated_at` property." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.setUpdatedAt(new Date());\n", + "code": "const store = new DocumentStore();\nstore.setUpdatedAt(new Date('2022-01-01T12:00:00.000Z'));\n", "description": "" }, "name": "setUpdatedAt", @@ -217,16 +217,16 @@ "docLength": 7 }, { - "id": "7591bb3e-df47-afa5-f641-1831c1f92326", + "id": "c75cbeb5-3ed8-27bb-df46-e544fa9e5b58", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Updates and stores summary information in the local store based on remote information, and sets metadata properties for the local store.", + "description": "Retrieves and updates the summary data from the remote storage, merging it with local metadata if available, and sets the `status.summary` property to `true`.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.loadSummary();\n", - "description": "\nHere, the loadSummary function is called to download the summary of documents from a remote source." + "code": "const documentStore = new DocumentStore(\n async (...args) => {\n // implementation of getRemote function\n },\n {\n namespace: 'my-namespace',\n CHUNK_SIZE: 100,\n metaTemplate: {\n author: '',\n description: '',\n },\n }\n);\n\nawait documentStore.loadSummary();\n", + "description": "" }, "name": "loadSummary", "location": { @@ -244,12 +244,12 @@ "docLength": 4 }, { - "id": "98331336-679b-8e8a-4c45-afe45ef2f5c4", + "id": "0107ad7c-1c2c-2fbd-6b4b-f8a3575e96a0", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04", - "7591bb3e-df47-afa5-f641-1831c1f92326" + "f3c4f7db-cd89-ef84-f649-e72684e525e9", + "c75cbeb5-3ed8-27bb-df46-e544fa9e5b58" ], - "description": "Updates the `this.meta` object with values from the `summary.meta` object or the provided `value`, if the `summary` object is not defined or does not have a property for the specified key.", + "description": "Updates meta properties.", "name": null, "location": { "start": 121, @@ -263,15 +263,15 @@ "docLength": null }, { - "id": "7cbb6863-86a1-72bb-0044-fb20b693df1f", + "id": "4394771a-b76f-ee8f-a843-59576b1e0915", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Async loads the document chunks by iterating through the chunk indices and loading each chunk synchronously using the `loadChunk` method. It also sets the `chunks` property to `true` once all chunks have been loaded.", + "description": "Asynchronously loads and prepares document data for retrieval, comprising loading a summary if not already available and then loading individual chunks according to their indices in the `lookup` array.", "params": [], "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote);\nstore.load();\n", + "code": "const docStore = new DocumentStore(\n async (...args: any[]) => Promise.resolve({ /* some data */ }),\n);\nawait docStore.load();\n", "description": "" }, "name": "load", @@ -290,24 +290,24 @@ "docLength": 3 }, { - "id": "12db6d76-5d1e-64a5-274e-fa20e96e3b84", + "id": "c2cc3b08-0a67-9db2-6c44-0aeb541d8592", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Updates the metadata of a document by combining the existing metadata and additional metadata passed as an argument, creating a new metadata object that includes both.", + "description": "Updates the metadata of an object by merging it with existing metadata. The `additionalMeta` parameter is a key-value pair that contains new or updated metadata properties, which are then combined with the existing metadata using the spread operator (`...`).", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record*", - "description": "Used to update the metadata by adding new key-value pairs to the existing ones." + "description": "Intended to add new metadata information." } ], "usage": { "language": "typescript", - "code": "// Instantiate the DocumentStore class with the getRemote parameter and the integration object.\nconst documentStore = new DocumentStore(getRemote, integration);\n\n// Update metadata by passing a record of additional meta information to the updateMetadata method.\ndocumentStore.updateMetadata({ version: \"1.0.0\" });\n", - "description": "" + "code": "const documentStore = new DocumentStore();\ndocumentStore.updateMetadata({\n lastUpdated: new Date(),\n author: 'John Doe',\n});\n", + "description": "\nThis code creates a new instance of the `DocumentStore` class, and then updates its `meta` property with additional metadata." }, "name": "updateMetadata", "location": { @@ -322,28 +322,28 @@ "docLength": null }, { - "id": "946898a7-7531-db97-8b45-0e9f2e6d3ab8", + "id": "ae4527bd-df03-80aa-1b4a-4372e320dbd4", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Async loads a chunk of the document from the server, given its index, and appends it to the content and chunks collections if successful.", + "description": "Asynchronously loads a chunk of structured files from a remote location and updates the local content and chunks cache. If loading fails, it returns false; otherwise, it returns true.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number*", - "description": "Used to identify the chunk being loaded. It serves as an index to access the appropriate chunk data from the `chunks` array." + "description": "Used to identify specific chunk for loading." } ], "returns": { "type_name": "Promise*", - "description": "Resolved to true if the chunk was loaded successfully, or false otherwise." + "description": "A promise that resolves to a boolean value indicating whether the chunk was successfully loaded or not." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.loadChunk(0);\n", - "description": "" + "code": "documentStore.loadChunk(0).then((result) => {\n if (result) {\n // The chunk was loaded successfully.\n } else {\n // An error occurred during chunk loading.\n }\n}).catch((error) => {\n // Handle the error that occurred during chunk loading.\n});\n", + "description": "\n" }, "name": "loadChunk", "location": { @@ -361,27 +361,27 @@ "docLength": 11 }, { - "id": "08b11a36-878f-7d97-cd46-ba854d1814eb", + "id": "501fc0f4-312e-68b1-2446-aaa5ca6ec531", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Retrieves a file from the store based on its path. It first checks if the summary has been loaded, then calculates the chunk it is in and loads it if necessary. Finally, it returns the file index within that chunk.", + "description": "Asynchronously retrieves a structured file from storage. It checks if the summary is loaded, loads the required chunk if necessary, and returns the requested file if found.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Used to identify the file being retrieved, which must match the path of a file in the current summary." + "description": "Used to specify the file path that needs to be retrieved." } ], "returns": { "type_name": "Promise*", - "description": "Either a StructuredFile object or null if the file cannot be found or has already been loaded." + "description": "Either a StructuredFile object if the file exists and can be loaded successfully, or null if the file does not exist or cannot be loaded." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote);\n// Load summary\ndocStore.loadSummary();\n// Get a file from the store\nconst file = await docStore.getFile(\"path/to/file\");\n", + "code": "const documentStore = new DocumentStore();\n\ndocumentStore.loadSummary().then(() => {\n documentStore.getFile('path/to/file.txt').then(file => {\n // process file\n }).catch(error => {\n console.error(error);\n });\n}).catch(error => {\n console.error(error);\n});\n", "description": "" }, "name": "getFile", @@ -400,24 +400,24 @@ "docLength": 10 }, { - "id": "fcc560b4-31c1-8da9-6245-541014c03b97", + "id": "5df446d9-6217-0a82-e54a-8ae23293bb1c", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Adds a new path to the end of the lookup subtable if it's not already full, or appends it to the last entry in the table otherwise.", + "description": "Adds a new path to the end of the lookup subtable. If the current subtable is full, it creates a new one; otherwise, it appends the path to the existing subtable.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string*", - "description": "Used to add a new entry to the lookup subtable, either by creating a new table if it does not exist or by adding a new entry to an existing one." + "description": "Used to add to the end of the lookup subtable." } ], "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore();\n\ndocStore.getRemote = async () => {\n // this function returns a promise of a document object\n return { content: \"This is some sample text\" };\n};\n\n// Call addToEndOfLookup method with the path argument \ndocStore.addToEndOfLookup(\"some/path\");\n", - "description": "" + "code": "const documentStore = new DocumentStore();\ndocumentStore.addToEndOfLookup('path/to/first/document');\ndocumentStore.addToEndOfLookup('path/to/second/document');\n", + "description": "\nThis example illustrates adding two paths to the lookup array." }, "name": "addToEndOfLookup", "location": { @@ -435,24 +435,24 @@ "docLength": 6 }, { - "id": "da2cfc75-9144-bcbd-2145-a9e23a9cb8b9", + "id": "d82b341b-6f2c-db96-4d45-c4e542ba876f", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Adds new files to the end of existing chunks or creates a new chunk if the last one is full, maintaining a fixed chunk size.", + "description": "Adds files to the end of existing chunks or creates a new chunk if the last one is full, ensuring that each chunk does not exceed a fixed size (`CHUNK_SIZE`). It efficiently handles file storage and organization.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Used to add a file to the end of a list of chunks." + "description": "Used to add to existing chunks or create new ones." } ], "usage": { "language": "typescript", - "code": "const store = new DocumentStore({ getRemote, integration });\nstore.addToEndOfChunks(file); // Adds a file to the last chunk if it is full, otherwise adds the file to the last lookup subtable.\n", - "description": "" + "code": "const documentStore = new DocumentStore();\n\nconst file1: StructuredFile = { /* your data */ };\nconst file2: StructuredFile = { /* your data */ };\n\ndocumentStore.addToEndOfChunks(file1);\ndocumentStore.addToEndOfChunks(file2);\n", + "description": "\nNote that the actual implementation of `StructuredFile` is not provided, and would need to be defined separately." }, "name": "addToEndOfChunks", "location": { @@ -470,28 +470,28 @@ "docLength": 10 }, { - "id": "c117558c-2938-849c-2c4e-76f7d8b8f1b3", + "id": "b02443ac-f4ac-11a7-6441-b9374c816d42", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Adds a file to the document store if the file exists and has not already been added. If the file exists, it updates its metadata and adds it to the end of the lookup and chunks lists.", + "description": "Adds a file to the store, checking if it already exists and updating its content accordingly. If the file does not exist, it adds it to the end of the lookup table and chunks, then pushes it to the content array.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Used to represent a file that can be added to the content." + "description": "Required for adding a file to the content." } ], "returns": { "type_name": "boolean*", - "description": "1 if the file was successfully added to the lookup and chunks, and 0 otherwise." + "description": "True if a file was successfully added and false otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore();\nlet file = {path:\"/path/to/file\", content:\"content of the file\"};\ndocStore.addFile(file);\n", - "description": "" + "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.load();\ndocumentStore.addFile(new StructuredFile(\"path/to/file\", \"file content\"));\n", + "description": "\nThis code creates a new instance of the `DocumentStore` class, loads it with a remote service using `getRemote`, and then adds a file to the store." }, "name": "addFile", "location": { @@ -509,27 +509,27 @@ "docLength": 10 }, { - "id": "55404fb6-7114-63a3-4a47-f0b4797d6678", + "id": "c8420c97-83ca-48a8-4b4b-c02c968dfb80", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Updates a file in the store by checking if it exists, loading any necessary chunks, and storing the updated file in the appropriate position within the chunk.", + "description": "Updates a structured file in memory by adding it to the store if it doesn't exist, or updating its content in a chunk if it does exist. It loads chunks as needed and returns a boolean indicating success.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile*", - "description": "Used to represent a file within the application's file system, with its path serving as the reference for updating the file's status within the chunks." + "description": "Used to update or add a file." } ], "returns": { "type_name": "Promise*", - "description": "Ether *true or *false depending on whether the file was successfully updated." + "description": "Either a boolean indicating whether the file was updated successfully (true) or an error occurred during update (false)." }, "usage": { "language": "typescript", - "code": "const updateFile = async (file: StructuredFile): Promise => {\n const documentStore = new DocumentStore(getRemote, integration);\n await documentStore.updateFile(file);\n};\n\n// example of how the method would be called\nconst fileToUpdate = {\n path: '/path/to/file',\n content: 'file content here'\n}\nupdateFile(fileToUpdate);\n", + "code": "const documentStore = new DocumentStore();\nconst file = {\n path: 'test.txt',\n content: 'Hello, world!'\n};\n\ndocumentStore.updateFile(file).then((result) => console.log(result));\n", "description": "" }, "name": "updateFile", @@ -548,20 +548,20 @@ "docLength": 10 }, { - "id": "d7ff2f96-db33-75b4-f64d-1929e2ecf6d2", + "id": "7f53e5c3-e405-6bb5-b044-96a522784b98", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Returns an object containing the class's `meta` and `lookup` properties, providing a concise summary of its state.", + "description": "Returns an object containing two properties, `meta` and `lookup`, which are references to the corresponding instance variables. This method provides a summary of the document store's state.", "params": [], "returns": { "type_name": "Summary*", - "description": "An object containing two properties: `meta` and `lookup`." + "description": "An object with two properties: meta and lookup, both containing values from this object." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.metaTemplate = {\n version: '1.0',\n created_at: new Date(),\n updated_at: new Date()\n};\ndocumentStore.lookup = ['firstName', 'lastName'];\nconst summary = documentStore.outputSummary();\n", - "description": "\nIn this example, the end user first instantiates a `DocumentStore` class with the necessary parameters for getting remote and integrations. They then set up the metaTemplate object and the lookup array. Finally, they call the `outputSummary()` method to generate the summary of the data in the `documentStore`. The resulting summary is stored in the `summary` variable.\nNote that this is just an illustrative example and may not be applicable or suitable for any specific use case." + "code": "const store = new DocumentStore(getRemote, integration);\nconst summary = store.outputSummary();\n", + "description": "" }, "name": "outputSummary", "location": { @@ -579,19 +579,19 @@ "docLength": 6 }, { - "id": "93ef91ec-c0ea-eda9-8546-5ceca66eb738", + "id": "95c05ae1-3e9e-8a84-614c-0ddb73682150", "ancestors": [ - "ca42b4a8-1551-e782-9c4f-ee063f96de04" + "f3c4f7db-cd89-ef84-f649-e72684e525e9" ], - "description": "Generates an object containing key-value pairs, where each key corresponds to a chunk of the document and each value is the contents of that chunk.", + "description": "Breaks down the content into chunks based on the `CHUNK_SIZE`, generates keys for each chunk, and stores them in an object along with their corresponding values. It returns this object.", "params": [], "returns": { "type_name": "Record*", - "description": "An object containing key-value pairs where the keys are string chunk paths and the values are the corresponding chunk of text." + "description": "An object where each key is a string and its corresponding value is of any data type." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration); // Setup instance of DocumentStore with getRemote and integration objects\ndocumentStore.CHUNK_SIZE = 20; // set chunk size to 20\n\nconst outputs: Record = documentStore.outputChunks(); // Generate chunks using the outputChunks method\n\n", + "code": "let documentStore = new DocumentStore();\n// set parameters for getRemote and meta data\ndocumentStore.getRemote = (...args) => Promise.resolve({/*data*/});\ndocumentStore.meta.version = '1.0';\ndocumentStore.CHUNK_SIZE = 100;\n\nconst outputs = documentStore.outputChunks();\n", "description": "" }, "name": "outputChunks", diff --git a/.komment/komment.json b/.komment/komment.json index 7aa782a..c14dbed 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-11T10:59:56.158Z", + "updated_at": "2024-07-11T11:04:09.678Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -17,7 +17,8 @@ "ce9a50b9-f4ec-4487-80f0-aff229eec487", "1f76280f-f42b-4585-ad9d-7178240fd285", "ef450461-80fd-45dd-81f4-48c5335ad528", - "dbb10926-033f-4543-b4cc-bee6999543f8" + "dbb10926-033f-4543-b4cc-bee6999543f8", + "521fe478-f3d3-4440-81b8-31b85cb89a46" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 30ca7c7..e398ce5 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Is responsible for managing and organizing code chunks based on their - * contents, creating a structured file that can be used for efficient content retrieval - * and manipulation. + * @description Is designed to manage structured files and provide a mechanism for + * loading, storing, and retrieving file data, as well as generating documentation + * and records of chunks of code. * * @implements {IDocumentStore} */ @@ -46,18 +46,18 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up class variables and properties, including `CHUNK_SIZE`, - * `namespace`, `getRemote`, `meta`, `lookup`, `chunks`, and `content`. It also checks - * for required inputs and sets default values for some properties. + * @description Initializes an instance with required properties such as namespace, + * getRemote method, and optional additional metadata. It sets default values for + * CHUNK_SIZE, updates meta information, and initializes various arrays and status + * flags for the document store. * - * @param {string*} namespace - Used to set the name space for the chunker, which - * allows the chunker to identify which chunks belong to the same namespace. + * @param {string*} namespace - Required for the constructor. * - * @param {(...args: any[]) => Promise>*} getRemote - Required to - * return a promise containing a record with data. + * @param {(...args: any[]) => Promise>*} getRemote - Used to fetch + * data from a remote source. * - * @param {Record*} additionalMeta - Used to store custom metadata for - * the document. + * @param {Record*} additionalMeta - Used to add custom metadata to the + * object. */ constructor( namespace: string, @@ -87,18 +87,18 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updatedAt` metadata property with the provided `Date` object. + * @description Updates the `updated_at` property with a given `Date` value, effectively + * setting or updating the document's last updated timestamp. * - * @param {Date*} updated_at - Used to update the "updated at" metadata of the object - * being updated. + * @param {Date*} updated_at - Used to update the `updated_at` property. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Updates and stores summary information in the local store based on - * remote information, and sets metadata properties for the local store. + * @description Retrieves and updates the summary data from the remote storage, merging + * it with local metadata if available, and sets the `status.summary` property to `true`. */ loadSummary = async () => { let summary: Summary = { @@ -127,9 +127,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]) => { - // Updates the `this.meta` object with values from the `summary.meta` object or the - // provided `value`, if the `summary` object is not defined or does not have a property - // for the specified key. + // Updates meta properties. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -138,9 +136,9 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Async loads the document chunks by iterating through the chunk indices - * and loading each chunk synchronously using the `loadChunk` method. It also sets - * the `chunks` property to `true` once all chunks have been loaded. + * @description Asynchronously loads and prepares document data for retrieval, + * comprising loading a summary if not already available and then loading individual + * chunks according to their indices in the `lookup` array. */ load = async () => { if (!this.status.summary) { @@ -163,12 +161,12 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of a document by combining the existing metadata - * and additional metadata passed as an argument, creating a new metadata object that - * includes both. + * @description Updates the metadata of an object by merging it with existing metadata. + * The `additionalMeta` parameter is a key-value pair that contains new or updated + * metadata properties, which are then combined with the existing metadata using the + * spread operator (`...`). * - * @param {Record*} additionalMeta - Used to update the metadata by - * adding new key-value pairs to the existing ones. + * @param {Record*} additionalMeta - Intended to add new metadata information. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -184,14 +182,14 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Async loads a chunk of the document from the server, given its index, - * and appends it to the content and chunks collections if successful. + * @description Asynchronously loads a chunk of structured files from a remote location + * and updates the local content and chunks cache. If loading fails, it returns false; + * otherwise, it returns true. * - * @param {number*} chunkIndex - Used to identify the chunk being loaded. It serves - * as an index to access the appropriate chunk data from the `chunks` array. + * @param {number*} chunkIndex - Used to identify specific chunk for loading. * - * @returns {Promise*} Resolved to true if the chunk was loaded successfully, - * or false otherwise. + * @returns {Promise*} A promise that resolves to a boolean value indicating + * whether the chunk was successfully loaded or not. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -210,15 +208,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from the store based on its path. It first checks - * if the summary has been loaded, then calculates the chunk it is in and loads it - * if necessary. Finally, it returns the file index within that chunk. + * @description Asynchronously retrieves a structured file from storage. It checks + * if the summary is loaded, loads the required chunk if necessary, and returns the + * requested file if found. * - * @param {string*} path - Used to identify the file being retrieved, which must match - * the path of a file in the current summary. + * @param {string*} path - Used to specify the file path that needs to be retrieved. * - * @returns {Promise*} Either a StructuredFile object or null - * if the file cannot be found or has already been loaded. + * @returns {Promise*} Either a StructuredFile object if the + * file exists and can be loaded successfully, or null if the file does not exist or + * cannot be loaded. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -261,12 +259,11 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of the lookup subtable if it's not already - * full, or appends it to the last entry in the table otherwise. + * @description Adds a new path to the end of the lookup subtable. If the current + * subtable is full, it creates a new one; otherwise, it appends the path to the + * existing subtable. * - * @param {string*} path - Used to add a new entry to the lookup subtable, either by - * creating a new table if it does not exist or by adding a new entry to an existing - * one. + * @param {string*} path - Used to add to the end of the lookup subtable. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -280,10 +277,11 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds new files to the end of existing chunks or creates a new chunk - * if the last one is full, maintaining a fixed chunk size. + * @description Adds files to the end of existing chunks or creates a new chunk if + * the last one is full, ensuring that each chunk does not exceed a fixed size + * (`CHUNK_SIZE`). It efficiently handles file storage and organization. * - * @param {StructuredFile*} file - Used to add a file to the end of a list of chunks. + * @param {StructuredFile*} file - Used to add to existing chunks or create new ones. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -297,15 +295,13 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the document store if the file exists and has not - * already been added. If the file exists, it updates its metadata and adds it to the - * end of the lookup and chunks lists. + * @description Adds a file to the store, checking if it already exists and updating + * its content accordingly. If the file does not exist, it adds it to the end of the + * lookup table and chunks, then pushes it to the content array. * - * @param {StructuredFile*} file - Used to represent a file that can be added to the - * content. + * @param {StructuredFile*} file - Required for adding a file to the content. * - * @returns {boolean*} 1 if the file was successfully added to the lookup and chunks, - * and 0 otherwise. + * @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"); @@ -328,16 +324,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the store by checking if it exists, loading any - * necessary chunks, and storing the updated file in the appropriate position within - * the chunk. + * @description Updates a structured file in memory by adding it to the store if it + * doesn't exist, or updating its content in a chunk if it does exist. It loads chunks + * as needed and returns a boolean indicating success. * - * @param {StructuredFile*} file - Used to represent a file within the application's - * file system, with its path serving as the reference for updating the file's status - * within the chunks. + * @param {StructuredFile*} file - Used to update or add a file. * - * @returns {Promise*} Ether *true or *false depending on whether the file - * was successfully updated. + * @returns {Promise*} Either a boolean indicating whether the file was + * updated successfully (true) or an error occurred during update (false). */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -367,10 +361,12 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing the class's `meta` and `lookup` properties, - * providing a concise summary of its state. + * @description Returns an object containing two properties, `meta` and `lookup`, + * which are references to the corresponding instance variables. This method provides + * a summary of the document store's state. * - * @returns {Summary*} An object containing two properties: `meta` and `lookup`. + * @returns {Summary*} An object with two properties: meta and lookup, both containing + * values from this object. */ outputSummary(): Summary { return { @@ -379,11 +375,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Generates an object containing key-value pairs, where each key - * corresponds to a chunk of the document and each value is the contents of that chunk. + * @description Breaks down the content into chunks based on the `CHUNK_SIZE`, generates + * keys for each chunk, and stores them in an object along with their corresponding + * values. It returns this object. * - * @returns {Record*} An object containing key-value pairs where the - * keys are string chunk paths and the values are the corresponding chunk of text. + * @returns {Record*} An object where each key is a string and its + * corresponding value is of any data type. */ outputChunks(): Record { const outputs: Record = {}; From 25165ac3834de5a7a9e998e47192c791367c385c Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Thu, 11 Jul 2024 21:01:31 +0000 Subject: [PATCH 22/30] Added comments to 15 functions across 1 file --- .komment/00000.json | 218 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 131 ++++++++++++------------- 3 files changed, 175 insertions(+), 179 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 26c3a85..a168eed 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 data files, dividing each file into chunks based on a specified chunk size. The store keeps track of the lookup table and chunks, allowing for efficient retrieval and addition of files. The class provides methods for adding files, updating existing ones, and generating summaries and records of chunks.", + "description": "A `DocumentStore` class that handles adding, retrieving, and updating documents in a specified namespace. It provides methods for loading metadata, adding files to the content and chunks arrays, and generating high-quality documentation. The code uses TypeScript's type system and various packages such as `chalk` for formatting output.", "items": [ { - "id": "f3c4f7db-cd89-ef84-f649-e72684e525e9", + "id": "8830d820-8835-98ac-cd4c-f3a08aaa4f3a", "ancestors": [], - "description": "Is designed to manage structured files and provide a mechanism for loading, storing, and retrieving file data, as well as generating documentation and records of chunks of code.", + "description": "Stores and manages structured files, providing a simple way to access and manipulate content.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "1 by default. It determines how many files each chunk will hold before a new chunk is created, ensuring that chunks do not exceed a certain size limit." + "description": "Used to specify the size of each chunk in bytes for storing code documentation." }, { "name": "namespace", "type_name": "string", - "description": "Used to store a namespace for storing documents and metadata. It seems that this namespace is used as part of the path when retrieving or storing chunks of code." + "description": "Used to specify the namespace for the document store, which determines how the documents are organized and accessed." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the structured file." + "description": "Used to store high-quality documentation information about the chunked code." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Not defined anywhere in this code snippet." + "description": "Used to define a default template for the metadata of documents stored in the store." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a lookup table of file paths within each chunk of the document's content." + "description": "Used to store a list of sub-arrays representing the chunks of content within each chunk." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "2D array of file chunks, where each chunk contains a fixed number (CHUNK_SIZE) of files. The index of the outer array represents the chunk ID, and the inner array contains the files within that chunk." + "description": "Used to store chunks of code in a structured format for easy retrieval and manipulation." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "2-dimensional array, where each inner array represents a chunk of files loaded from the provider. The array is used to store the file objects that have been successfully added to the structured file." + "description": "Used to store files in the document store." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to keep track of the status of the document store." + "description": "Used to store information about the status of the document store such as whether the summary was last updated" } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "705aa0ee-e8f4-778a-6547-32fb777359c4", + "id": "cdee0421-267d-7cb3-8147-9d4b36763ed5", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Initializes an instance with required properties such as namespace, getRemote method, and optional additional metadata. It sets default values for CHUNK_SIZE, updates meta information, and initializes various arrays and status flags for the document store.", + "description": "Sets up the class variables and methods, including the namespace, getRemote method, and meta data.", "params": [ { "name": "namespace", - "type_name": "string*", + "type_name": "string", "optional": false, - "description": "Required for the constructor.", + "description": "Required to initialize an instance of the class, serving as a unique identifier for the object's purpose or environment.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>*", + "type_name": "(...args: any[]) => Promise>", "optional": false, - "description": "Used to fetch data from a remote source.", + "description": "Required for constructing an instance of the class.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record*", + "type_name": "Record", "optional": true, - "description": "Used to add custom metadata to the object.", + "description": "Used to store additional metadata related to the document that can be used to customize the document's behavior or appearance.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\n 'my-namespace',\n async (...args: any[]) => {\n // Implementation of getRemote method\n },\n { some: 'additional', meta: 'information' }\n);\n", - "description": "" + "code": "const getRemote = async (...args) => {\n // Implement your remote function here\n};\n\nconst namespace = \"my-namespace\";\nconst additionalMeta = { foo: \"bar\" };\nconst documentStore = new DocumentStore(namespace, getRemote, additionalMeta);\n", + "description": "\nIn this example, the end-user is creating an instance of the `DocumentStore` class with a namespace and a remote function, as well as providing some additional metadata. The constructor will then initialize the internal arrays and objects to store chunk data, content, and other meta information." }, "name": null, "location": { @@ -182,23 +182,23 @@ "docLength": 12 }, { - "id": "b99de814-2260-ce80-a940-c16e80bb1d23", + "id": "1604c226-9a37-2183-f24c-62d6b2ca8cb6", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Updates the `updated_at` property with a given `Date` value, effectively setting or updating the document's last updated timestamp.", + "description": "Updates the `updated_at` metadata field of an instance with the provided `Date`.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date*", - "description": "Used to update the `updated_at` property." + "type_name": "Date", + "description": "Used to update the date when the object was last updated." } ], "usage": { "language": "typescript", - "code": "const store = new DocumentStore();\nstore.setUpdatedAt(new Date('2022-01-01T12:00:00.000Z'));\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\n const updatedAt = new Date();\n documentStore.setUpdatedAt(updatedAt);\n", "description": "" }, "name": "setUpdatedAt", @@ -217,15 +217,15 @@ "docLength": 7 }, { - "id": "c75cbeb5-3ed8-27bb-df46-e544fa9e5b58", + "id": "609ac296-a222-4aa1-2149-8834db8cff76", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Retrieves and updates the summary data from the remote storage, merging it with local metadata if available, and sets the `status.summary` property to `true`.", + "description": "Retrieves and updates a summary of documents in the store, including meta information and chunk data.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\n async (...args) => {\n // implementation of getRemote function\n },\n {\n namespace: 'my-namespace',\n CHUNK_SIZE: 100,\n metaTemplate: {\n author: '',\n description: '',\n },\n }\n);\n\nawait documentStore.loadSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.loadSummary();\n", "description": "" }, "name": "loadSummary", @@ -244,12 +244,12 @@ "docLength": 4 }, { - "id": "0107ad7c-1c2c-2fbd-6b4b-f8a3575e96a0", + "id": "2a6d813a-ac43-c58c-5b4a-fe56bef92c8e", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9", - "c75cbeb5-3ed8-27bb-df46-e544fa9e5b58" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a", + "609ac296-a222-4aa1-2149-8834db8cff76" ], - "description": "Updates meta properties.", + "description": "Updates `this.meta` object with values from `summary.meta` or original `value` if `summary.meta` is null or undefined.", "name": null, "location": { "start": 121, @@ -263,15 +263,15 @@ "docLength": null }, { - "id": "4394771a-b76f-ee8f-a843-59576b1e0915", + "id": "01b8698e-0fc1-ab80-b540-138371e7a54a", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Asynchronously loads and prepares document data for retrieval, comprising loading a summary if not already available and then loading individual chunks according to their indices in the `lookup` array.", + "description": "Async loads chunks of data from the storage when the `status.summary` is not set or expired. It then sets the `chunks` property to `true`.", "params": [], "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(\n async (...args: any[]) => Promise.resolve({ /* some data */ }),\n);\nawait docStore.load();\n", + "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.load();\n", "description": "" }, "name": "load", @@ -290,24 +290,24 @@ "docLength": 3 }, { - "id": "c2cc3b08-0a67-9db2-6c44-0aeb541d8592", + "id": "657609a9-a8d5-8da0-a44e-21d45b604ff9", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Updates the metadata of an object by merging it with existing metadata. The `additionalMeta` parameter is a key-value pair that contains new or updated metadata properties, which are then combined with the existing metadata using the spread operator (`...`).", + "description": "Updates the metadata of a document by combining the existing metadata with additional metadata provided as an argument, resulting in a new updated metadata object.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record*", - "description": "Intended to add new metadata information." + "type_name": "Record", + "description": "Used to add new metadata to the existing metadata of an object." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.updateMetadata({\n lastUpdated: new Date(),\n author: 'John Doe',\n});\n", - "description": "\nThis code creates a new instance of the `DocumentStore` class, and then updates its `meta` property with additional metadata." + "code": "const docStore = new DocumentStore(getRemote);\ndocStore.updateMetadata({ version: \"1.0\", created_at: new Date() });\n", + "description": "" }, "name": "updateMetadata", "location": { @@ -322,28 +322,28 @@ "docLength": null }, { - "id": "ae4527bd-df03-80aa-1b4a-4372e320dbd4", + "id": "becac836-a921-418c-f341-08b74cedf9d8", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Asynchronously loads a chunk of structured files from a remote location and updates the local content and chunks cache. If loading fails, it returns false; otherwise, it returns true.", + "description": "Async loads a chunk of data from the server and concatenates it with the existing content, storing the new chunk in the object's internal state.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number*", - "description": "Used to identify specific chunk for loading." + "type_name": "number", + "description": "Used to identify the specific chunk being loaded. It serves as an index into the `chunks` array, allowing the function to access the appropriate chunk of data." } ], "returns": { - "type_name": "Promise*", - "description": "A promise that resolves to a boolean value indicating whether the chunk was successfully loaded or not." + "type_name": "Promise", + "description": "Resolved to true if the chunk was loaded successfully and false otherwise." }, "usage": { "language": "typescript", - "code": "documentStore.loadChunk(0).then((result) => {\n if (result) {\n // The chunk was loaded successfully.\n } else {\n // An error occurred during chunk loading.\n }\n}).catch((error) => {\n // Handle the error that occurred during chunk loading.\n});\n", - "description": "\n" + "code": "const docStore = new DocumentStore(getRemote);\nawait docStore.loadChunk(0); // loads chunk with index 0\n", + "description": "" }, "name": "loadChunk", "location": { @@ -361,28 +361,28 @@ "docLength": 11 }, { - "id": "501fc0f4-312e-68b1-2446-aaa5ca6ec531", + "id": "769a776f-561a-0bbc-994f-fc0912a824a4", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Asynchronously retrieves a structured file from storage. It checks if the summary is loaded, loads the required chunk if necessary, and returns the requested file if found.", + "description": "Retrieves a file from a summary, calculating its chunk and index within that chunk, before loading it if necessary. It then returns the file object.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Used to specify the file path that needs to be retrieved." + "type_name": "string", + "description": "Used to specify the file path to retrieve from the summary." } ], "returns": { - "type_name": "Promise*", - "description": "Either a StructuredFile object if the file exists and can be loaded successfully, or null if the file does not exist or cannot be loaded." + "type_name": "Promise", + "description": "Either a structured file object or null." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\n\ndocumentStore.loadSummary().then(() => {\n documentStore.getFile('path/to/file.txt').then(file => {\n // process file\n }).catch(error => {\n console.error(error);\n });\n}).catch(error => {\n console.error(error);\n});\n", - "description": "" + "code": "const documentStore = new DocumentStore(); // create a new instance of the class\ndocumentStore.getFile('path/to/file'); // get the file with the given path\n", + "description": "\nThe `getFile` function returns the `StructuredFile` object if the file is found, and null otherwise." }, "name": "getFile", "location": { @@ -400,24 +400,24 @@ "docLength": 10 }, { - "id": "5df446d9-6217-0a82-e54a-8ae23293bb1c", + "id": "3722e87a-127a-0899-8941-e862a463a232", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Adds a new path to the end of the lookup subtable. If the current subtable is full, it creates a new one; otherwise, it appends the path to the existing subtable.", + "description": "Adds a new path to the end of an existing lookup subtable or creates a new subtable if the last one is full, preserving the chunk size.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Used to add to the end of the lookup subtable." + "type_name": "string", + "description": "Used to specify the path to add to the lookup subtable." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.addToEndOfLookup('path/to/first/document');\ndocumentStore.addToEndOfLookup('path/to/second/document');\n", - "description": "\nThis example illustrates adding two paths to the lookup array." + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup('path');\n", + "description": "" }, "name": "addToEndOfLookup", "location": { @@ -435,24 +435,24 @@ "docLength": 6 }, { - "id": "d82b341b-6f2c-db96-4d45-c4e542ba876f", + "id": "9505cdd5-2b79-8eb0-6949-4b9ee325ccd4", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Adds files to the end of existing chunks or creates a new chunk if the last one is full, ensuring that each chunk does not exceed a fixed size (`CHUNK_SIZE`). It efficiently handles file storage and organization.", + "description": "Updates the chunks array by adding the provided file to the end of the last chunk or creating a new one if necessary.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Used to add to existing chunks or create new ones." + "type_name": "StructuredFile", + "description": "Used to add a new file to the chunks array." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\n\nconst file1: StructuredFile = { /* your data */ };\nconst file2: StructuredFile = { /* your data */ };\n\ndocumentStore.addToEndOfChunks(file1);\ndocumentStore.addToEndOfChunks(file2);\n", - "description": "\nNote that the actual implementation of `StructuredFile` is not provided, and would need to be defined separately." + "code": "let docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfChunks(file);\n", + "description": "" }, "name": "addToEndOfChunks", "location": { @@ -470,28 +470,28 @@ "docLength": 10 }, { - "id": "b02443ac-f4ac-11a7-6441-b9374c816d42", + "id": "2fcec2fb-b93d-289d-b244-d05da6b2829b", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Adds a file to the store, checking if it already exists and updating its content accordingly. If the file does not exist, it adds it to the end of the lookup table and chunks, then pushes it to the content array.", + "description": "Adds a new file to the document store by checking if the status has chunks, checking if the file exists, updating the file if it exists, and adding the file to the end of the lookup and chunks.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Required for adding a file to the content." + "type_name": "StructuredFile", + "description": "Used to represent a file to be added to the content of an instance of the `ContentManager` class." } ], "returns": { - "type_name": "boolean*", - "description": "True if a file was successfully added and false otherwise." + "type_name": "boolean", + "description": "True if the file was successfully added to the lookup and chunks, otherwise false." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.load();\ndocumentStore.addFile(new StructuredFile(\"path/to/file\", \"file content\"));\n", - "description": "\nThis code creates a new instance of the `DocumentStore` class, loads it with a remote service using `getRemote`, and then adds a file to the store." + "code": "const docStore = new DocumentStore({getRemote: (...args) => {\n return fetch('https://your-api-url', {\n method: 'POST',\n body: JSON.stringify({\n type: 'document',\n content: args[0],\n }),\n });\n}, integration: new Integration({\n name: 'your-integration-name',\n version: '1.0.0',\n})});\nconst file = {path: '/some/file.txt', content: 'Hello, World!'};\nconst result = docStore.addFile(file);\n", + "description": "" }, "name": "addFile", "location": { @@ -509,27 +509,27 @@ "docLength": 10 }, { - "id": "c8420c97-83ca-48a8-4b4b-c02c968dfb80", + "id": "6741d53d-3472-a4ab-0f44-a17b3c4c8fe4", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Updates a structured file in memory by adding it to the store if it doesn't exist, or updating its content in a chunk if it does exist. It loads chunks as needed and returns a boolean indicating success.", + "description": "Updates a file in the store by checking its existence, loading it if necessary, and storing it in the correct chunk and index position.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Used to update or add a file." + "type_name": "StructuredFile", + "description": "Used to represent a file that needs to be updated, indicating whether it exists or not in the current chunk, and its position in the chunk if it does exist." } ], "returns": { - "type_name": "Promise*", - "description": "Either a boolean indicating whether the file was updated successfully (true) or an error occurred during update (false)." + "type_name": "Promise", + "description": "True if the file was successfully updated and false otherwise." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\nconst file = {\n path: 'test.txt',\n content: 'Hello, world!'\n};\n\ndocumentStore.updateFile(file).then((result) => console.log(result));\n", + "code": "const store = new DocumentStore(getRemote, integration);\nawait store.updateFile({ path: \"path/to/file\", content: \"new file content\" });\n// The method above will update the content of a file at \"path/to/file\" with the new content provided.\n", "description": "" }, "name": "updateFile", @@ -548,19 +548,19 @@ "docLength": 10 }, { - "id": "7f53e5c3-e405-6bb5-b044-96a522784b98", + "id": "f999b6b8-938f-3286-df48-15d992102847", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Returns an object containing two properties, `meta` and `lookup`, which are references to the corresponding instance variables. This method provides a summary of the document store's state.", + "description": "Returns an object containing the `meta` and `lookup` properties, which are likely used to store and retrieve document-related information.", "params": [], "returns": { - "type_name": "Summary*", - "description": "An object with two properties: meta and lookup, both containing values from this object." + "type_name": "Summary", + "description": "An object containing two properties: `meta` and `lookup`." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nconst summary = store.outputSummary();\n", + "code": "const store = new DocumentStore(getRemote, integration);\nstore.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -579,20 +579,20 @@ "docLength": 6 }, { - "id": "95c05ae1-3e9e-8a84-614c-0ddb73682150", + "id": "026ebfca-c5e0-66b5-824b-f9edb3d7cae0", "ancestors": [ - "f3c4f7db-cd89-ef84-f649-e72684e525e9" + "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" ], - "description": "Breaks down the content into chunks based on the `CHUNK_SIZE`, generates keys for each chunk, and stores them in an object along with their corresponding values. It returns this object.", + "description": "Creates an object containing chunks of the document, where each chunk is represented as a key-value pair with the chunk path as the key and the chunk content as the value.", "params": [], "returns": { - "type_name": "Record*", - "description": "An object where each key is a string and its corresponding value is of any data type." + "type_name": "Record", + "description": "An object containing key-value pairs where each key is a chunk path and each value is the corresponding chunk of text." }, "usage": { "language": "typescript", - "code": "let documentStore = new DocumentStore();\n// set parameters for getRemote and meta data\ndocumentStore.getRemote = (...args) => Promise.resolve({/*data*/});\ndocumentStore.meta.version = '1.0';\ndocumentStore.CHUNK_SIZE = 100;\n\nconst outputs = documentStore.outputChunks();\n", - "description": "" + "code": "const documentStore = new DocumentStore({\n getRemote: (...args: any[]) => Promise>;\n}, integration);\n\n// Create a record of chunks\nconst chunkRecords: Record = documentStore.outputChunks();\n", + "description": "\nThis example demonstrates how to create a record of chunks using the `outputChunks()` method and the `DocumentStore` class. The method is called on an instance of the `DocumentStore` class that has been initialized with the necessary parameters for generating high-quality documentation, such as the third-party library or service that provides the functionality and the integration object. The method returns a record of chunks that can be used to store and manage chunk data in various parts of the code." }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index c14dbed..5e8375e 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-11T11:04:09.678Z", + "updated_at": "2024-07-11T21:01:25.528Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -18,7 +18,8 @@ "1f76280f-f42b-4585-ad9d-7178240fd285", "ef450461-80fd-45dd-81f4-48c5335ad528", "dbb10926-033f-4543-b4cc-bee6999543f8", - "521fe478-f3d3-4440-81b8-31b85cb89a46" + "521fe478-f3d3-4440-81b8-31b85cb89a46", + "bd56018a-a4ab-43de-aa64-a02ed61b32be" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index e398ce5..1f76e76 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,8 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Is designed to manage structured files and provide a mechanism for - * loading, storing, and retrieving file data, as well as generating documentation - * and records of chunks of code. + * @description Stores and manages structured files, providing a simple way to access + * and manipulate content. * * @implements {IDocumentStore} */ @@ -46,18 +45,18 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Initializes an instance with required properties such as namespace, - * getRemote method, and optional additional metadata. It sets default values for - * CHUNK_SIZE, updates meta information, and initializes various arrays and status - * flags for the document store. + * @description Sets up the class variables and methods, including the namespace, + * getRemote method, and meta data. * - * @param {string*} namespace - Required for the constructor. + * @param {string} namespace - Required to initialize an instance of the class, serving + * as a unique identifier for the object's purpose or environment. * - * @param {(...args: any[]) => Promise>*} getRemote - Used to fetch - * data from a remote source. + * @param {(...args: any[]) => Promise>} getRemote - Required for + * constructing an instance of the class. * - * @param {Record*} additionalMeta - Used to add custom metadata to the - * object. + * @param {Record} additionalMeta - Used to store additional metadata + * related to the document that can be used to customize the document's behavior or + * appearance. */ constructor( namespace: string, @@ -87,18 +86,18 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` property with a given `Date` value, effectively - * setting or updating the document's last updated timestamp. + * @description Updates the `updated_at` metadata field of an instance with the + * provided `Date`. * - * @param {Date*} updated_at - Used to update the `updated_at` property. + * @param {Date} updated_at - Used to update the date when the object was last updated. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates the summary data from the remote storage, merging - * it with local metadata if available, and sets the `status.summary` property to `true`. + * @description Retrieves and updates a summary of documents in the store, including + * meta information and chunk data. */ loadSummary = async () => { let summary: Summary = { @@ -127,7 +126,8 @@ 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 properties. + // Updates `this.meta` object with values from `summary.meta` or original `value` if + // `summary.meta` is null or undefined. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -136,9 +136,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Asynchronously loads and prepares document data for retrieval, - * comprising loading a summary if not already available and then loading individual - * chunks according to their indices in the `lookup` array. + * @description Async loads chunks of data from the storage when the `status.summary` + * is not set or expired. It then sets the `chunks` property to `true`. */ load = async () => { if (!this.status.summary) { @@ -161,12 +160,12 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of an object by merging it with existing metadata. - * The `additionalMeta` parameter is a key-value pair that contains new or updated - * metadata properties, which are then combined with the existing metadata using the - * spread operator (`...`). + * @description Updates the metadata of a document by combining the existing metadata + * with additional metadata provided as an argument, resulting in a new updated + * metadata object. * - * @param {Record*} additionalMeta - Intended to add new metadata information. + * @param {Record} additionalMeta - Used to add new metadata to the + * existing metadata of an object. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -182,14 +181,15 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Asynchronously loads a chunk of structured files from a remote location - * and updates the local content and chunks cache. If loading fails, it returns false; - * otherwise, it returns true. + * @description Async loads a chunk of data from the server and concatenates it with + * the existing content, storing the new chunk in the object's internal state. * - * @param {number*} chunkIndex - Used to identify specific chunk for loading. + * @param {number} chunkIndex - Used to identify the specific chunk being loaded. It + * serves as an index into the `chunks` array, allowing the function to access the + * appropriate chunk of data. * - * @returns {Promise*} A promise that resolves to a boolean value indicating - * whether the chunk was successfully loaded or not. + * @returns {Promise} Resolved to true if the chunk was loaded successfully + * and false otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -208,15 +208,12 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Asynchronously retrieves a structured file from storage. It checks - * if the summary is loaded, loads the required chunk if necessary, and returns the - * requested file if found. + * @description Retrieves a file from a summary, calculating its chunk and index + * within that chunk, before loading it if necessary. It then returns the file object. * - * @param {string*} path - Used to specify the file path that needs to be retrieved. + * @param {string} path - Used to specify the file path to retrieve from the summary. * - * @returns {Promise*} Either a StructuredFile object if the - * file exists and can be loaded successfully, or null if the file does not exist or - * cannot be loaded. + * @returns {Promise} Either a structured file object or null. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -259,11 +256,10 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of the lookup subtable. If the current - * subtable is full, it creates a new one; otherwise, it appends the path to the - * existing subtable. + * @description Adds a new path to the end of an existing lookup subtable or creates + * a new subtable if the last one is full, preserving the chunk size. * - * @param {string*} path - Used to add to the end of the lookup subtable. + * @param {string} path - Used to specify the path to add to the lookup subtable. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -277,11 +273,10 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds files to the end of existing chunks or creates a new chunk if - * the last one is full, ensuring that each chunk does not exceed a fixed size - * (`CHUNK_SIZE`). It efficiently handles file storage and organization. + * @description Updates the chunks array by adding the provided file to the end of + * the last chunk or creating a new one if necessary. * - * @param {StructuredFile*} file - Used to add to existing chunks or create new ones. + * @param {StructuredFile} file - Used to add a new file to the chunks array. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -295,13 +290,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the store, checking if it already exists and updating - * its content accordingly. If the file does not exist, it adds it to the end of the - * lookup table and chunks, then pushes it to the content array. + * @description Adds a new file to the document store by checking if the status has + * chunks, checking if the file exists, updating the file if it exists, and adding + * the file to the end of the lookup and chunks. * - * @param {StructuredFile*} file - Required for adding a file to the content. + * @param {StructuredFile} file - Used to represent a file to be added to the content + * of an instance of the `ContentManager` class. * - * @returns {boolean*} True if a file was successfully added and false otherwise. + * @returns {boolean} True if the file was successfully added to the lookup and chunks, + * otherwise false. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -324,14 +321,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a structured file in memory by adding it to the store if it - * doesn't exist, or updating its content in a chunk if it does exist. It loads chunks - * as needed and returns a boolean indicating success. + * @description Updates a file in the store by checking its existence, loading it if + * necessary, and storing it in the correct chunk and index position. * - * @param {StructuredFile*} file - Used to update or add a file. + * @param {StructuredFile} file - Used to represent a file that needs to be updated, + * indicating whether it exists or not in the current chunk, and its position in the + * chunk if it does exist. * - * @returns {Promise*} Either a boolean indicating whether the file was - * updated successfully (true) or an error occurred during update (false). + * @returns {Promise} True if the file was successfully updated and false otherwise. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -361,12 +358,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing two properties, `meta` and `lookup`, - * which are references to the corresponding instance variables. This method provides - * a summary of the document store's state. + * @description Returns an object containing the `meta` and `lookup` properties, which + * are likely used to store and retrieve document-related information. * - * @returns {Summary*} An object with two properties: meta and lookup, both containing - * values from this object. + * @returns {Summary} An object containing two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -375,12 +370,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Breaks down the content into chunks based on the `CHUNK_SIZE`, generates - * keys for each chunk, and stores them in an object along with their corresponding - * values. It returns this object. + * @description Creates an object containing chunks of the document, where each chunk + * is represented as a key-value pair with the chunk path as the key and the chunk + * content as the value. * - * @returns {Record*} An object where each key is a string and its - * corresponding value is of any data type. + * @returns {Record} An object containing key-value pairs where each key + * is a chunk path and each value is the corresponding chunk of text. */ outputChunks(): Record { const outputs: Record = {}; From ca5d022f92821323f6d00b0156b75cd93f16ad3d Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Fri, 12 Jul 2024 05:16:25 +0000 Subject: [PATCH 23/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 212 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 135 ++++++++++++++------------- 3 files changed, 181 insertions(+), 171 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index a168eed..c86bd24 100644 --- a/.komment/00000.json +++ b/.komment/00000.json @@ -4,12 +4,12 @@ "path": "src/index.ts", "content": { "structured": { - "description": "A `DocumentStore` class that handles adding, retrieving, and updating documents in a specified namespace. It provides methods for loading metadata, adding files to the content and chunks arrays, and generating high-quality documentation. The code uses TypeScript's type system and various packages such as `chalk` for formatting output.", + "description": "A DocumentStore class that manages structured files, allowing users to add and update files while maintaining chunked storage for efficient querying. The store utilizes an internal lookup table and chunk array to optimize file retrieval. The code provides methods for adding and updating files, loading chunks, and generating summaries of the stored data. It employs a metadata structure (meta) and lookup subtable to efficiently locate files within the store.", "items": [ { - "id": "8830d820-8835-98ac-cd4c-f3a08aaa4f3a", + "id": "cd224204-9704-a7bc-b94b-41f37246ba35", "ancestors": [], - "description": "Stores and manages structured files, providing a simple way to access and manipulate content.", + "description": "Manages a collection of files (code chunks) and provides methods to load, update, and retrieve files from the store. It maintains metadata about the files, ensures chunking for efficient storage and retrieval, and offers output methods for generating documentation and extracting code records.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "Used to specify the size of each chunk in bytes for storing code documentation." + "description": "1024 by default, which determines the maximum size of each chunk in a structured file. It controls how many files are grouped together in a single chunk for efficient storage and retrieval." }, { "name": "namespace", "type_name": "string", - "description": "Used to specify the namespace for the document store, which determines how the documents are organized and accessed." + "description": "Used to prefix file paths when generating chunk paths or summary paths, allowing for unique identification and organization of files within the document store." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store high-quality documentation information about the chunked code." + "description": "Used to store metadata about the document." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to define a default template for the metadata of documents stored in the store." + "description": "Used to generate high-quality documentation for code by returning an object containing the `meta` and `lookup` properties." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a list of sub-arrays representing the chunks of content within each chunk." + "description": "2D array where each subarray contains a list of file paths for that chunk, which helps in searching and indexing files." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store chunks of code in a structured format for easy retrieval and manipulation." + "description": "2D array, where each subarray represents a chunk of files, and each file is represented by its path, name, and other properties. It stores chunks of structured files for efficient loading and retrieval." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store files in the document store." + "description": "Used to store the actual content (StructuredFiles) that are part of a document, which is loaded from remote storage into the DocumentStore's memory." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to store information about the status of the document store such as whether the summary was last updated" + "description": "Used to track the loading status of the document store." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "cdee0421-267d-7cb3-8147-9d4b36763ed5", + "id": "f4abebf8-f314-2cb5-1942-6200684f7f02", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Sets up the class variables and methods, including the namespace, getRemote method, and meta data.", + "description": "Initializes an instance with required properties such as namespace, getRemote method, and additional metadata. It also sets default values for other properties like CHUNK_SIZE, lookup array, chunks array, content array, and status object.", "params": [ { "name": "namespace", - "type_name": "string", + "type_name": "string*", "optional": false, - "description": "Required to initialize an instance of the class, serving as a unique identifier for the object's purpose or environment.", + "description": "Required to be set.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>", + "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required for constructing an instance of the class.", + "description": "Intended to retrieve data remotely.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record", + "type_name": "Record*", "optional": true, - "description": "Used to store additional metadata related to the document that can be used to customize the document's behavior or appearance.", + "description": "Used to provide additional metadata information.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const getRemote = async (...args) => {\n // Implement your remote function here\n};\n\nconst namespace = \"my-namespace\";\nconst additionalMeta = { foo: \"bar\" };\nconst documentStore = new DocumentStore(namespace, getRemote, additionalMeta);\n", - "description": "\nIn this example, the end-user is creating an instance of the `DocumentStore` class with a namespace and a remote function, as well as providing some additional metadata. The constructor will then initialize the internal arrays and objects to store chunk data, content, and other meta information." + "code": "const documentStore = new DocumentStore('myNamespace', async (args) => {\n // Return a promise with a record of any type and any value\n return { /* some data */ };\n}, { foo: 'bar' });\n", + "description": "\nThis example shows the creation of a new instance of the `DocumentStore` class, passing in `'myNamespace'`, an asynchronous function as `getRemote`, and an additional meta object with a single key-value pair." }, "name": null, "location": { @@ -182,23 +182,23 @@ "docLength": 12 }, { - "id": "1604c226-9a37-2183-f24c-62d6b2ca8cb6", + "id": "d6301b2c-4bdc-0ca5-7d4c-d0b7196ce989", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Updates the `updated_at` metadata field of an instance with the provided `Date`.", + "description": "Updates the `updated_at` property of its instance with the provided `updated_at` date. This method modifies the internal state of the object, updating the timestamp indicating when the document was last updated.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date", - "description": "Used to update the date when the object was last updated." + "type_name": "Date*", + "description": "Used to update the value of the `updated_at` property." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\n const updatedAt = new Date();\n documentStore.setUpdatedAt(updatedAt);\n", + "code": "const documentStore = new DocumentStore(\n async (...args: any[]) => {\n // Remote implementation\n }\n);\n\n// Updating updated_at with a Date object\ndocumentStore.setUpdatedAt(new Date('2022-07-25T14:30:00.000Z'));\n", "description": "" }, "name": "setUpdatedAt", @@ -217,16 +217,16 @@ "docLength": 7 }, { - "id": "609ac296-a222-4aa1-2149-8834db8cff76", + "id": "9721b4ae-de77-2098-a74b-ccf833f7fa5c", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Retrieves and updates a summary of documents in the store, including meta information and chunk data.", + "description": "Loads and updates the summary data from a remote source or uses a local template if no data is available, then applies the loaded data to its own properties and sets a status flag indicating whether a summary is loaded.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.loadSummary();\n", - "description": "" + "code": "const documentStore = new DocumentStore(getRemote, metaTemplate);\ndocumentStore.loadSummary();\n", + "description": "\nNote: This code assumes that 'getRemote' and 'metaTemplate' are defined elsewhere in your project." }, "name": "loadSummary", "location": { @@ -244,12 +244,12 @@ "docLength": 4 }, { - "id": "2a6d813a-ac43-c58c-5b4a-fe56bef92c8e", + "id": "c541fca4-0896-dc99-1343-e2c61e05824c", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a", - "609ac296-a222-4aa1-2149-8834db8cff76" + "cd224204-9704-a7bc-b94b-41f37246ba35", + "9721b4ae-de77-2098-a74b-ccf833f7fa5c" ], - "description": "Updates `this.meta` object with values from `summary.meta` or original `value` if `summary.meta` is null or undefined.", + "description": "Assigns default values to object properties.", "name": null, "location": { "start": 121, @@ -263,16 +263,16 @@ "docLength": null }, { - "id": "01b8698e-0fc1-ab80-b540-138371e7a54a", + "id": "627ea6ee-a9ba-cf9d-d043-9d269fe63211", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Async loads chunks of data from the storage when the `status.summary` is not set or expired. It then sets the `chunks` property to `true`.", + "description": "Loads and initializes document data. If the summary is not loaded, it calls `loadSummary()`. Then, it looks up chunk indices and loads corresponding chunks using `loadChunk()` method. Finally, it sets the `chunks` property to `true`.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote);\ndocumentStore.load();\n", - "description": "" + "code": "const documentStore = new DocumentStore(\n getRemote: async () => ({ /* return value */ }),\n namespace: 'namespace',\n CHUNK_SIZE: 100,\n);\n\ndocumentStore.load();\n", + "description": "\nThis code creates a new instance of the `DocumentStore` class and calls its `load()` method." }, "name": "load", "location": { @@ -290,23 +290,23 @@ "docLength": 3 }, { - "id": "657609a9-a8d5-8da0-a44e-21d45b604ff9", + "id": "459a4788-e967-6ba9-6f48-3d9e240cd6cd", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Updates the metadata of a document by combining the existing metadata with additional metadata provided as an argument, resulting in a new updated metadata object.", + "description": "Updates the metadata object by merging it with an additional metadata record. The resulting metadata object is assigned back to the instance property `meta`. This allows for incremental modification of the metadata over time.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record", - "description": "Used to add new metadata to the existing metadata of an object." + "type_name": "Record*", + "description": "Intended to provide additional metadata for updating." } ], "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote);\ndocStore.updateMetadata({ version: \"1.0\", created_at: new Date() });\n", + "code": "const store = new DocumentStore(getRemote, integration);\nstore.updateMetadata({ customProperty: 'CustomValue' });\n", "description": "" }, "name": "updateMetadata", @@ -322,27 +322,27 @@ "docLength": null }, { - "id": "becac836-a921-418c-f341-08b74cedf9d8", + "id": "ed542a78-61db-baaa-6147-ec63098503e8", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Async loads a chunk of data from the server and concatenates it with the existing content, storing the new chunk in the object's internal state.", + "description": "Loads a chunk of structured files from a remote location, checks if it's already loaded, and updates the local state with the new data. If an error occurs during loading, it returns false; otherwise, it returns true.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number", - "description": "Used to identify the specific chunk being loaded. It serves as an index into the `chunks` array, allowing the function to access the appropriate chunk of data." + "type_name": "number*", + "description": "Used to identify the chunk to load from remote storage." } ], "returns": { - "type_name": "Promise", - "description": "Resolved to true if the chunk was loaded successfully and false otherwise." + "type_name": "Promise*", + "description": "Resolved to either true or false." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote);\nawait docStore.loadChunk(0); // loads chunk with index 0\n", + "code": "const documentStore = new DocumentStore();\ndocumentStore.CHUNK_SIZE = 100;\nawait documentStore.loadChunk(0);\n", "description": "" }, "name": "loadChunk", @@ -361,28 +361,28 @@ "docLength": 11 }, { - "id": "769a776f-561a-0bbc-994f-fc0912a824a4", + "id": "9f3609ea-1e0d-f7a2-5645-3e9d4ff1cf43", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Retrieves a file from a summary, calculating its chunk and index within that chunk, before loading it if necessary. It then returns the file object.", + "description": "Asynchronously retrieves a file with the given path from an array of chunks, loading the chunk if necessary and checking its integrity. It returns the file object or null if it does not exist.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "Used to specify the file path to retrieve from the summary." + "type_name": "string*", + "description": "Used to specify a file path." } ], "returns": { - "type_name": "Promise", - "description": "Either a structured file object or null." + "type_name": "Promise*", + "description": "Either a StructuredFile object or null. If the file exists and is successfully loaded, it returns the StructuredFile object; otherwise, it returns null." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(); // create a new instance of the class\ndocumentStore.getFile('path/to/file'); // get the file with the given path\n", - "description": "\nThe `getFile` function returns the `StructuredFile` object if the file is found, and null otherwise." + "code": "documentStore.status.summary = true;\nconst file = await documentStore.getFile('path/to/file');\nif (file) {\n // use the retrieved file\n} else {\n // handle null return\n}\n", + "description": "" }, "name": "getFile", "location": { @@ -400,23 +400,23 @@ "docLength": 10 }, { - "id": "3722e87a-127a-0899-8941-e862a463a232", + "id": "77029d0d-1db2-8483-af44-b2346cc95571", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Adds a new path to the end of an existing lookup subtable or creates a new subtable if the last one is full, preserving the chunk size.", + "description": "Adds paths to the last lookup subtable or creates a new one if it's full, maintaining a fixed chunk size (`CHUNK_SIZE`). It ensures efficient storage and retrieval of document paths in a hierarchical structure.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "Used to specify the path to add to the lookup subtable." + "type_name": "string*", + "description": "Used to add to the end of the lookup table." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup('path');\n", + "code": "let documentStore = new DocumentStore(\n // getRemote implementation,\n // namespace and other params...\n);\n\ndocumentStore.addToEndOfLookup(\"path1\");\ndocumentStore.addToEndOfLookup(\"path2\");\n", "description": "" }, "name": "addToEndOfLookup", @@ -435,23 +435,23 @@ "docLength": 6 }, { - "id": "9505cdd5-2b79-8eb0-6949-4b9ee325ccd4", + "id": "15a3c27c-074a-b89b-1b49-3879170b2b8e", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Updates the chunks array by adding the provided file to the end of the last chunk or creating a new one if necessary.", + "description": "Adds a file to the last lookup subtable if it's not full, or creates a new one if the current table is full. It maintains an array of chunks with a fixed size and keeps track of the files within each chunk.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Used to add a new file to the chunks array." + "type_name": "StructuredFile*", + "description": "Intended to be appended at the end of chunks." } ], "usage": { "language": "typescript", - "code": "let docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfChunks(file);\n", + "code": "const store = new DocumentStore();\nstore.CHUNK_SIZE = 5;\nstore.addToEndOfChunks({structuredData: 'first file'});\nstore.addToEndOfChunks({structuredData: 'second file'});\nstore.addToEndOfChunks({structuredData: 'third file'});", "description": "" }, "name": "addToEndOfChunks", @@ -470,27 +470,27 @@ "docLength": 10 }, { - "id": "2fcec2fb-b93d-289d-b244-d05da6b2829b", + "id": "446245a4-4122-e393-9f4b-fc11a8c5e6e8", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Adds a new file to the document store by checking if the status has chunks, checking if the file exists, updating the file if it exists, and adding the file to the end of the lookup and chunks.", + "description": "Adds a structured file to the store. If the file already exists, it updates its content; otherwise, it appends it to the end of the lookup and chunks arrays, and pushes it into the content array.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Used to represent a file to be added to the content of an instance of the `ContentManager` class." + "type_name": "StructuredFile*", + "description": "Used to add files to the system." } ], "returns": { - "type_name": "boolean", - "description": "True if the file was successfully added to the lookup and chunks, otherwise false." + "type_name": "boolean*", + "description": "True if a file has been successfully added to the collection and false otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore({getRemote: (...args) => {\n return fetch('https://your-api-url', {\n method: 'POST',\n body: JSON.stringify({\n type: 'document',\n content: args[0],\n }),\n });\n}, integration: new Integration({\n name: 'your-integration-name',\n version: '1.0.0',\n})});\nconst file = {path: '/some/file.txt', content: 'Hello, World!'};\nconst result = docStore.addFile(file);\n", + "code": "let documentStore = new DocumentStore(getRemote, integration);\nlet structuredFile = {\n path: 'file.txt',\n content: 'Hello World'\n};\ndocumentStore.addFile(structuredFile); // returns boolean value indicating success/failure", "description": "" }, "name": "addFile", @@ -509,27 +509,27 @@ "docLength": 10 }, { - "id": "6741d53d-3472-a4ab-0f44-a17b3c4c8fe4", + "id": "079a1bf1-b3d3-de90-7740-81418bb023b8", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Updates a file in the store by checking its existence, loading it if necessary, and storing it in the correct chunk and index position.", + "description": "Updates a structured file with a given path. It checks if the file exists and loads the corresponding chunk if necessary. If successful, it replaces the old file content with the new one in both chunk and content arrays.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Used to represent a file that needs to be updated, indicating whether it exists or not in the current chunk, and its position in the chunk if it does exist." + "type_name": "StructuredFile*", + "description": "Intended to update an existing file." } ], "returns": { - "type_name": "Promise", - "description": "True if the file was successfully updated and false otherwise." + "type_name": "Promise*", + "description": "A promise that resolves to either true or false indicating whether the file update operation was successful or not." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nawait store.updateFile({ path: \"path/to/file\", content: \"new file content\" });\n// The method above will update the content of a file at \"path/to/file\" with the new content provided.\n", + "code": "const documentStore = new DocumentStore();\n\nconst file1: StructuredFile = { path: \"file1.txt\", content: \"Hello\" };\nconst file2: StructuredFile = { path: \"file2.txt\", content: \"World\" };\n\ndocumentStore.updateFile(file1).then((success) => {\n if (success) {\n documentStore.updateFile(file2);\n }\n});\n", "description": "" }, "name": "updateFile", @@ -548,19 +548,19 @@ "docLength": 10 }, { - "id": "f999b6b8-938f-3286-df48-15d992102847", + "id": "41a7df5d-24ce-5987-454c-85f10565b2f4", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Returns an object containing the `meta` and `lookup` properties, which are likely used to store and retrieve document-related information.", + "description": "Returns an object containing two properties: `meta` and `lookup`. This summary likely represents a condensed version of the document's metadata and lookup information, facilitating efficient retrieval or display of key data.", "params": [], "returns": { - "type_name": "Summary", - "description": "An object containing two properties: `meta` and `lookup`." + "type_name": "Summary*", + "description": "An object containing two properties: `meta` and `lookup`, both having values inherited from the instance properties `this.meta` and `this.lookup`." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.outputSummary();\n", + "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote = async () => ({});\nconst result = documentStore.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -579,20 +579,20 @@ "docLength": 6 }, { - "id": "026ebfca-c5e0-66b5-824b-f9edb3d7cae0", + "id": "4022b960-51d9-989e-c247-ceab8c31a63f", "ancestors": [ - "8830d820-8835-98ac-cd4c-f3a08aaa4f3a" + "cd224204-9704-a7bc-b94b-41f37246ba35" ], - "description": "Creates an object containing chunks of the document, where each chunk is represented as a key-value pair with the chunk path as the key and the chunk content as the value.", + "description": "Splits its internal content into fixed-size chunks, maps each chunk to a unique key using the `chunkIndexToChunkKey` and `chunkKeyToChunkPath` methods, and returns a record containing these key-value pairs.", "params": [], "returns": { - "type_name": "Record", - "description": "An object containing key-value pairs where each key is a chunk path and each value is the corresponding chunk of text." + "type_name": "Record*", + "description": "An object where keys are strings and values can be of any data type, representing a mapping between chunk keys and corresponding chunks of content." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore({\n getRemote: (...args: any[]) => Promise>;\n}, integration);\n\n// Create a record of chunks\nconst chunkRecords: Record = documentStore.outputChunks();\n", - "description": "\nThis example demonstrates how to create a record of chunks using the `outputChunks()` method and the `DocumentStore` class. The method is called on an instance of the `DocumentStore` class that has been initialized with the necessary parameters for generating high-quality documentation, such as the third-party library or service that provides the functionality and the integration object. The method returns a record of chunks that can be used to store and manage chunk data in various parts of the code." + "code": "const documentStore = new DocumentStore(...);\n\ndocumentStore.CHUNK_SIZE = 1024;\nconst outputs = documentStore.outputChunks();\n", + "description": "" }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index 5e8375e..5269ef4 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-11T21:01:25.528Z", + "updated_at": "2024-07-12T05:16:18.392Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -19,7 +19,8 @@ "ef450461-80fd-45dd-81f4-48c5335ad528", "dbb10926-033f-4543-b4cc-bee6999543f8", "521fe478-f3d3-4440-81b8-31b85cb89a46", - "bd56018a-a4ab-43de-aa64-a02ed61b32be" + "bd56018a-a4ab-43de-aa64-a02ed61b32be", + "344dea1f-37c5-4706-b964-90ffeed56096" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 1f76e76..23c2041 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,8 +20,10 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Stores and manages structured files, providing a simple way to access - * and manipulate content. + * @description Manages a collection of files (code chunks) and provides methods to + * load, update, and retrieve files from the store. It maintains metadata about the + * files, ensures chunking for efficient storage and retrieval, and offers output + * methods for generating documentation and extracting code records. * * @implements {IDocumentStore} */ @@ -45,18 +47,18 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up the class variables and methods, including the namespace, - * getRemote method, and meta data. + * @description Initializes an instance with required properties such as namespace, + * getRemote method, and additional metadata. It also sets default values for other + * properties like CHUNK_SIZE, lookup array, chunks array, content array, and status + * object. * - * @param {string} namespace - Required to initialize an instance of the class, serving - * as a unique identifier for the object's purpose or environment. + * @param {string*} namespace - Required to be set. * - * @param {(...args: any[]) => Promise>} getRemote - Required for - * constructing an instance of the class. + * @param {(...args: any[]) => Promise>*} getRemote - Intended to + * retrieve data remotely. * - * @param {Record} additionalMeta - Used to store additional metadata - * related to the document that can be used to customize the document's behavior or - * appearance. + * @param {Record*} additionalMeta - Used to provide additional metadata + * information. */ constructor( namespace: string, @@ -86,18 +88,20 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of an instance with the - * provided `Date`. + * @description Updates the `updated_at` property of its instance with the provided + * `updated_at` date. This method modifies the internal state of the object, updating + * the timestamp indicating when the document was last updated. * - * @param {Date} updated_at - Used to update the date when the object was last updated. + * @param {Date*} updated_at - Used to update the value of the `updated_at` property. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates a summary of documents in the store, including - * meta information and chunk data. + * @description Loads and updates the summary data from a remote source or uses a + * local template if no data is available, then applies the loaded data to its own + * properties and sets a status flag indicating whether a summary is loaded. */ loadSummary = async () => { let summary: Summary = { @@ -126,8 +130,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]) => { - // Updates `this.meta` object with values from `summary.meta` or original `value` if - // `summary.meta` is null or undefined. + // Assigns default values to object properties. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -136,8 +139,9 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Async loads chunks of data from the storage when the `status.summary` - * is not set or expired. It then sets the `chunks` property to `true`. + * @description Loads and initializes document data. If the summary is not loaded, + * it calls `loadSummary()`. Then, it looks up chunk indices and loads corresponding + * chunks using `loadChunk()` method. Finally, it sets the `chunks` property to `true`. */ load = async () => { if (!this.status.summary) { @@ -160,12 +164,12 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of a document by combining the existing metadata - * with additional metadata provided as an argument, resulting in a new updated - * metadata object. + * @description Updates the metadata object by merging it with an additional metadata + * record. The resulting metadata object is assigned back to the instance property + * `meta`. This allows for incremental modification of the metadata over time. * - * @param {Record} additionalMeta - Used to add new metadata to the - * existing metadata of an object. + * @param {Record*} additionalMeta - Intended to provide additional + * metadata for updating. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -181,15 +185,13 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Async loads a chunk of data from the server and concatenates it with - * the existing content, storing the new chunk in the object's internal state. + * @description Loads a chunk of structured files from a remote location, checks if + * it's already loaded, and updates the local state with the new data. If an error + * occurs during loading, it returns false; otherwise, it returns true. * - * @param {number} chunkIndex - Used to identify the specific chunk being loaded. It - * serves as an index into the `chunks` array, allowing the function to access the - * appropriate chunk of data. + * @param {number*} chunkIndex - Used to identify the chunk to load from remote storage. * - * @returns {Promise} Resolved to true if the chunk was loaded successfully - * and false otherwise. + * @returns {Promise*} Resolved to either true or false. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -208,12 +210,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from a summary, calculating its chunk and index - * within that chunk, before loading it if necessary. It then returns the file object. + * @description Asynchronously retrieves a file with the given path from an array of + * chunks, loading the chunk if necessary and checking its integrity. It returns the + * file object or null if it does not exist. * - * @param {string} path - Used to specify the file path to retrieve from the summary. + * @param {string*} path - Used to specify a file path. * - * @returns {Promise} Either a structured file object or null. + * @returns {Promise*} Either a StructuredFile object or null. + * If the file exists and is successfully loaded, it returns the StructuredFile object; + * otherwise, it returns null. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -256,10 +261,11 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of an existing lookup subtable or creates - * a new subtable if the last one is full, preserving the chunk size. + * @description Adds paths to the last lookup subtable or creates a new one if it's + * full, maintaining a fixed chunk size (`CHUNK_SIZE`). It ensures efficient storage + * and retrieval of document paths in a hierarchical structure. * - * @param {string} path - Used to specify the path to add to the lookup subtable. + * @param {string*} path - Used to add to the end of the lookup table. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -273,10 +279,11 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Updates the chunks array by adding the provided file to the end of - * the last chunk or creating a new one if necessary. + * @description Adds a file to the last lookup subtable if it's not full, or creates + * a new one if the current table is full. It maintains an array of chunks with a + * fixed size and keeps track of the files within each chunk. * - * @param {StructuredFile} file - Used to add a new file to the chunks array. + * @param {StructuredFile*} file - Intended to be appended at the end of chunks. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -290,15 +297,14 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a new file to the document store by checking if the status has - * chunks, checking if the file exists, updating the file if it exists, and adding - * the file to the end of the lookup and chunks. + * @description Adds a structured file to the store. If the file already exists, it + * updates its content; otherwise, it appends it to the end of the lookup and chunks + * arrays, and pushes it into the content array. * - * @param {StructuredFile} file - Used to represent a file to be added to the content - * of an instance of the `ContentManager` class. + * @param {StructuredFile*} file - Used to add files to the system. * - * @returns {boolean} True if the file was successfully added to the lookup and chunks, - * otherwise false. + * @returns {boolean*} True if a file has been successfully added to the collection + * and false otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -321,14 +327,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the store by checking its existence, loading it if - * necessary, and storing it in the correct chunk and index position. + * @description Updates a structured file with a given path. It checks if the file + * exists and loads the corresponding chunk if necessary. If successful, it replaces + * the old file content with the new one in both chunk and content arrays. * - * @param {StructuredFile} file - Used to represent a file that needs to be updated, - * indicating whether it exists or not in the current chunk, and its position in the - * chunk if it does exist. + * @param {StructuredFile*} file - Intended to update an existing file. * - * @returns {Promise} True if the file was successfully updated and false otherwise. + * @returns {Promise*} A promise that resolves to either true or false + * indicating whether the file update operation was successful or not. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -358,10 +364,12 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing the `meta` and `lookup` properties, which - * are likely used to store and retrieve document-related information. + * @description Returns an object containing two properties: `meta` and `lookup`. + * This summary likely represents a condensed version of the document's metadata and + * lookup information, facilitating efficient retrieval or display of key data. * - * @returns {Summary} An object containing two properties: `meta` and `lookup`. + * @returns {Summary*} An object containing two properties: `meta` and `lookup`, both + * having values inherited from the instance properties `this.meta` and `this.lookup`. */ outputSummary(): Summary { return { @@ -370,12 +378,13 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Creates an object containing chunks of the document, where each chunk - * is represented as a key-value pair with the chunk path as the key and the chunk - * content as the value. + * @description Splits its internal content into fixed-size chunks, maps each chunk + * to a unique key using the `chunkIndexToChunkKey` and `chunkKeyToChunkPath` methods, + * and returns a record containing these key-value pairs. * - * @returns {Record} An object containing key-value pairs where each key - * is a chunk path and each value is the corresponding chunk of text. + * @returns {Record*} An object where keys are strings and values can + * be of any data type, representing a mapping between chunk keys and corresponding + * chunks of content. */ outputChunks(): Record { const outputs: Record = {}; From 388723cc6b75c8256cf6b00541eec88abc4f13d6 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Fri, 12 Jul 2024 05:21:15 +0000 Subject: [PATCH 24/30] Added comments to 15 functions across 1 file --- .komment/00000.json | 212 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 138 +++++++++++++-------------- 3 files changed, 175 insertions(+), 180 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index c86bd24..beae2d4 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, allowing users to add and update files while maintaining chunked storage for efficient querying. The store utilizes an internal lookup table and chunk array to optimize file retrieval. The code provides methods for adding and updating files, loading chunks, and generating summaries of the stored data. It employs a metadata structure (meta) and lookup subtable to efficiently locate files within the store.", + "description": "A DocumentStore class that manages adding, retrieving, and updating files in a designated folder. It accepts a constructor parameter representing a third-party library or service that generates high-quality documentation, along with additional metadata that can be used to customize the document store's behavior. The class provides methods for loading and updating the document summary, as well as adding and updating individual files. It also includes properties for storing chunk data, content, and other meta information.", "items": [ { - "id": "cd224204-9704-a7bc-b94b-41f37246ba35", + "id": "2e83609e-de98-86a8-b648-0ce786451e62", "ancestors": [], - "description": "Manages a collection of files (code chunks) and provides methods to load, update, and retrieve files from the store. It maintains metadata about the files, ensures chunking for efficient storage and retrieval, and offers output methods for generating documentation and extracting code records.", + "description": "Provides an implementation for storing and retrieving code documentation in a structured manner, allowing for efficient access and manipulation of files and chunks within a specified namespace.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "1024 by default, which determines the maximum size of each chunk in a structured file. It controls how many files are grouped together in a single chunk for efficient storage and retrieval." + "description": "Used to specify the size of a chunk in bytes for storing code documentation." }, { "name": "namespace", "type_name": "string", - "description": "Used to prefix file paths when generating chunk paths or summary paths, allowing for unique identification and organization of files within the document store." + "description": "Used to specify the namespace for the document store, which determines how the documents are organized and accessed." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the document." + "description": "Used to store metadata about the document, such as version, creation date, and update date." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to generate high-quality documentation for code by returning an object containing the `meta` and `lookup` properties." + "description": "Used to specify a template for customizing the structure of the metadata." }, { "name": "lookup", "type_name": "string[][]", - "description": "2D array where each subarray contains a list of file paths for that chunk, which helps in searching and indexing files." + "description": "Used to store a list of sub-arrays containing file paths that correspond to the chunks stored in the document store. It plays a crucial role in storing and retrieving files from the document store." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "2D array, where each subarray represents a chunk of files, and each file is represented by its path, name, and other properties. It stores chunks of structured files for efficient loading and retrieval." + "description": "Used to store chunks of code content. It is used to store the content of the document in a structured way, making it easier to access and manipulate the content." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store the actual content (StructuredFiles) that are part of a document, which is loaded from remote storage into the DocumentStore's memory." + "description": "Used to store the actual content of the documents, which can be accessed through the `addFile()` method" }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to track the loading status of the document store." + "description": "Used to store information about the status of the documentation, such as whether it has been summarized or if chunks have been loaded." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "f4abebf8-f314-2cb5-1942-6200684f7f02", + "id": "2abae119-7d54-da8b-924a-deafb4bff4be", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Initializes an instance with required properties such as namespace, getRemote method, and additional metadata. It also sets default values for other properties like CHUNK_SIZE, lookup array, chunks array, content array, and status object.", + "description": "Sets up instance variables for namespace, getRemote method, chunk size, metadata, and other properties, ensuring they are not null or undefined before initialization.", "params": [ { "name": "namespace", - "type_name": "string*", + "type_name": "string", "optional": false, - "description": "Required to be set.", + "description": "Required. Its purpose is to provide a unique name or identifier for the remote document.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>*", + "type_name": "(...args: any[]) => Promise>", "optional": false, - "description": "Intended to retrieve data remotely.", + "description": "Required to retrieve data from an external source.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record*", + "type_name": "Record", "optional": true, - "description": "Used to provide additional metadata information.", + "description": "Used to store custom metadata for the document.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore('myNamespace', async (args) => {\n // Return a promise with a record of any type and any value\n return { /* some data */ };\n}, { foo: 'bar' });\n", - "description": "\nThis example shows the creation of a new instance of the `DocumentStore` class, passing in `'myNamespace'`, an asynchronous function as `getRemote`, and an additional meta object with a single key-value pair." + "code": "const documentStore = new DocumentStore(namespace, getRemote);\ndocumentStore.setUpdatedAt(new Date());\ndocumentStore.loadSummary();\n", + "description": "" }, "name": null, "location": { @@ -182,24 +182,24 @@ "docLength": 12 }, { - "id": "d6301b2c-4bdc-0ca5-7d4c-d0b7196ce989", + "id": "c7ef7154-ca8b-81b2-b041-b7b59ce1202d", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Updates the `updated_at` property of its instance with the provided `updated_at` date. This method modifies the internal state of the object, updating the timestamp indicating when the document was last updated.", + "description": "Updates the `updated_at` metadata field of an instance by assigning the provided `Date` object to it.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date*", - "description": "Used to update the value of the `updated_at` property." + "type_name": "Date", + "description": "Used to update the `updated_at` metadata field for the current object." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\n async (...args: any[]) => {\n // Remote implementation\n }\n);\n\n// Updating updated_at with a Date object\ndocumentStore.setUpdatedAt(new Date('2022-07-25T14:30:00.000Z'));\n", - "description": "" + "code": "const documentStore = new DocumentStore();\ndocumentStore.setUpdatedAt(new Date());\n", + "description": "\nIn this example, `DocumentStore` is a class that contains methods and properties for storing and managing document data, such as `getRemote`, `metaTemplate`, `lookup`, `chunks`, `content`, `status`. The method `setUpdatedAt()` takes an argument of type `Date` representing the updated date.\nThis example shows how to use the `setUpdatedAt()` method by creating a new instance of `DocumentStore` and calling its `setUpdatedAt()` method with a `new Date()` object as an argument." }, "name": "setUpdatedAt", "location": { @@ -217,16 +217,16 @@ "docLength": 7 }, { - "id": "9721b4ae-de77-2098-a74b-ccf833f7fa5c", + "id": "6c7e133c-5867-73b7-a242-c73d2b0dcdee", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Loads and updates the summary data from a remote source or uses a local template if no data is available, then applies the loaded data to its own properties and sets a status flag indicating whether a summary is loaded.", + "description": "Retrieves and updates the document summary information, including meta data and chunk information, and assigns it to the instance's `summary` property.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, metaTemplate);\ndocumentStore.loadSummary();\n", - "description": "\nNote: This code assumes that 'getRemote' and 'metaTemplate' are defined elsewhere in your project." + "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary(); // Load summary data from remote storage.\n", + "description": "" }, "name": "loadSummary", "location": { @@ -244,12 +244,12 @@ "docLength": 4 }, { - "id": "c541fca4-0896-dc99-1343-e2c61e05824c", + "id": "c9af65eb-8713-519b-8c4c-dea95ebf6a32", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35", - "9721b4ae-de77-2098-a74b-ccf833f7fa5c" + "2e83609e-de98-86a8-b648-0ce786451e62", + "6c7e133c-5867-73b7-a242-c73d2b0dcdee" ], - "description": "Assigns default values to object properties.", + "description": "Updates the `this.meta` object with values from the `summary.meta` object or the original `value`, if the `summary` object doesn't have an entry for the key.", "name": null, "location": { "start": 121, @@ -263,16 +263,16 @@ "docLength": null }, { - "id": "627ea6ee-a9ba-cf9d-d043-9d269fe63211", + "id": "47e08d28-a541-8384-e646-7aa86ec96616", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Loads and initializes document data. If the summary is not loaded, it calls `loadSummary()`. Then, it looks up chunk indices and loads corresponding chunks using `loadChunk()` method. Finally, it sets the `chunks` property to `true`.", + "description": "Async loads chunks of data from a summary and sets the `chunks` status to true once loaded.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\n getRemote: async () => ({ /* return value */ }),\n namespace: 'namespace',\n CHUNK_SIZE: 100,\n);\n\ndocumentStore.load();\n", - "description": "\nThis code creates a new instance of the `DocumentStore` class and calls its `load()` method." + "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.load();\n", + "description": "" }, "name": "load", "location": { @@ -290,24 +290,24 @@ "docLength": 3 }, { - "id": "459a4788-e967-6ba9-6f48-3d9e240cd6cd", + "id": "fc7f219c-8fc3-2392-064e-c6ee991bb5e6", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Updates the metadata object by merging it with an additional metadata record. The resulting metadata object is assigned back to the instance property `meta`. This allows for incremental modification of the metadata over time.", + "description": "Updates the metadata of an object by combining its current metadata with additional metadata provided as an argument, storing the resulting metadata in the `meta` property of the class instance.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record*", - "description": "Intended to provide additional metadata for updating." + "type_name": "Record", + "description": "Used to add additional metadata to the existing metadata object." } ], "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nstore.updateMetadata({ customProperty: 'CustomValue' });\n", - "description": "" + "code": "const documentStore = new DocumentStore(getRemote, integration);\n documentStore.updateMetadata({\n version: '1.0',\n created_at: Date.now(),\n updated_at: Date.now()\n });\n", + "description": "\nIn this example, `updateMetadata` is called on an instance of the `DocumentStore` class to update its metadata. The method takes a record of key-value pairs as an argument, where the keys are the names of the properties that should be updated, and the values are the new values for those properties. In this case, the version, created_at, and updated_at properties are all updated to the current date and time." }, "name": "updateMetadata", "location": { @@ -322,27 +322,27 @@ "docLength": null }, { - "id": "ed542a78-61db-baaa-6147-ec63098503e8", + "id": "548d36ea-41b4-928f-e64f-9664b34b946c", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Loads a chunk of structured files from a remote location, checks if it's already loaded, and updates the local state with the new data. If an error occurs during loading, it returns false; otherwise, it returns true.", + "description": "Ynchronously retrieves and appends a chunk of data to the store's content, marking it as loaded upon success.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number*", - "description": "Used to identify the chunk to load from remote storage." + "type_name": "number", + "description": "Used to represent the index of a chunk that needs to be loaded from the remote server." } ], "returns": { - "type_name": "Promise*", - "description": "Resolved to either true or false." + "type_name": "Promise", + "description": "Resolved when the chunk is loaded successfully, and rejected otherwise." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.CHUNK_SIZE = 100;\nawait documentStore.loadChunk(0);\n", + "code": "const store = new DocumentStore(getRemote, integration);\nawait store.loadChunk(123); // Load chunk number 123\n", "description": "" }, "name": "loadChunk", @@ -361,27 +361,27 @@ "docLength": 11 }, { - "id": "9f3609ea-1e0d-f7a2-5645-3e9d4ff1cf43", + "id": "ae75e735-383d-4691-4649-fef8aab3d752", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Asynchronously retrieves a file with the given path from an array of chunks, loading the chunk if necessary and checking its integrity. It returns the file object or null if it does not exist.", + "description": "Retrieves a file from the store based on its path, loading the necessary chunks and checking for correctness of the chunk and lookup.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Used to specify a file path." + "type_name": "string", + "description": "Used to identify a file within a chunk." } ], "returns": { - "type_name": "Promise*", - "description": "Either a StructuredFile object or null. If the file exists and is successfully loaded, it returns the StructuredFile object; otherwise, it returns null." + "type_name": "Promise", + "description": "A promise that resolves to either a StructuredFile object or null." }, "usage": { "language": "typescript", - "code": "documentStore.status.summary = true;\nconst file = await documentStore.getFile('path/to/file');\nif (file) {\n // use the retrieved file\n} else {\n // handle null return\n}\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.loadSummary().then(() => {\n const file = documentStore.getFile('path/to/file');\n});\n", "description": "" }, "name": "getFile", @@ -400,23 +400,23 @@ "docLength": 10 }, { - "id": "77029d0d-1db2-8483-af44-b2346cc95571", + "id": "96541505-95ab-74a4-204a-decc433f0321", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Adds paths to the last lookup subtable or creates a new one if it's full, maintaining a fixed chunk size (`CHUNK_SIZE`). It ensures efficient storage and retrieval of document paths in a hierarchical structure.", + "description": "Updates the lookup subtable by adding a new entry or appending to the existing one based on the current table size and length.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Used to add to the end of the lookup table." + "type_name": "string", + "description": "Used to specify the path to be added to the end of the lookup subtable." } ], "usage": { "language": "typescript", - "code": "let documentStore = new DocumentStore(\n // getRemote implementation,\n // namespace and other params...\n);\n\ndocumentStore.addToEndOfLookup(\"path1\");\ndocumentStore.addToEndOfLookup(\"path2\");\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup(\"path\");\n", "description": "" }, "name": "addToEndOfLookup", @@ -435,23 +435,23 @@ "docLength": 6 }, { - "id": "15a3c27c-074a-b89b-1b49-3879170b2b8e", + "id": "f4449ff0-cf9a-54b4-e34c-43459f8a31a1", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Adds a file to the last lookup subtable if it's not full, or creates a new one if the current table is full. It maintains an array of chunks with a fixed size and keeps track of the files within each chunk.", + "description": "Adds files to the end of existing chunks or creates new ones if necessary, maintaining a maximum size for each chunk.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Intended to be appended at the end of chunks." + "type_name": "StructuredFile", + "description": "Used to represent a file that needs to be added to the chunks array." } ], "usage": { "language": "typescript", - "code": "const store = new DocumentStore();\nstore.CHUNK_SIZE = 5;\nstore.addToEndOfChunks({structuredData: 'first file'});\nstore.addToEndOfChunks({structuredData: 'second file'});\nstore.addToEndOfChunks({structuredData: 'third file'});", + "code": "let documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks(file);\n", "description": "" }, "name": "addToEndOfChunks", @@ -470,27 +470,27 @@ "docLength": 10 }, { - "id": "446245a4-4122-e393-9f4b-fc11a8c5e6e8", + "id": "da01e283-02c0-4494-3946-0c9af773f930", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Adds a structured file to the store. If the file already exists, it updates its content; otherwise, it appends it to the end of the lookup and chunks arrays, and pushes it into the content array.", + "description": "Allows adding a file to the document store if certain conditions are met, including the file existing at the specified path and the `load` method being called before adding files.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Used to add files to the system." + "type_name": "StructuredFile", + "description": "Used to represent a file that can be added to the content of the object." } ], "returns": { - "type_name": "boolean*", - "description": "True if a file has been successfully added to the collection and false otherwise." + "type_name": "boolean", + "description": "True when a file is successfully added to the structured file and False otherwise." }, "usage": { "language": "typescript", - "code": "let documentStore = new DocumentStore(getRemote, integration);\nlet structuredFile = {\n path: 'file.txt',\n content: 'Hello World'\n};\ndocumentStore.addFile(structuredFile); // returns boolean value indicating success/failure", + "code": "const docStore = new DocumentStore();\ndocStore.addFile(file);\nconst file = new StructuredFile(\"path/to/file\");\n", "description": "" }, "name": "addFile", @@ -509,27 +509,27 @@ "docLength": 10 }, { - "id": "079a1bf1-b3d3-de90-7740-81418bb023b8", + "id": "f412d059-3f17-c0ab-0143-28a81a497832", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Updates a structured file with a given path. It checks if the file exists and loads the corresponding chunk if necessary. If successful, it replaces the old file content with the new one in both chunk and content arrays.", + "description": "Updates a file in the store by checking if it exists, loading any necessary chunks, and updating the file's position in the chunk.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Intended to update an existing file." + "type_name": "StructuredFile", + "description": "Used to represent a file being updated, passed by reference from the caller." } ], "returns": { - "type_name": "Promise*", - "description": "A promise that resolves to either true or false indicating whether the file update operation was successful or not." + "type_name": "Promise", + "description": "True if the file was updated successfully and false otherwise." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\n\nconst file1: StructuredFile = { path: \"file1.txt\", content: \"Hello\" };\nconst file2: StructuredFile = { path: \"file2.txt\", content: \"World\" };\n\ndocumentStore.updateFile(file1).then((success) => {\n if (success) {\n documentStore.updateFile(file2);\n }\n});\n", + "code": "const docStore = new DocumentStore(getRemote);\ndocStore.updateFile(file);\n", "description": "" }, "name": "updateFile", @@ -548,19 +548,19 @@ "docLength": 10 }, { - "id": "41a7df5d-24ce-5987-454c-85f10565b2f4", + "id": "f9b3c736-9436-4396-3348-c8c484c717b8", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Returns an object containing two properties: `meta` and `lookup`. This summary likely represents a condensed version of the document's metadata and lookup information, facilitating efficient retrieval or display of key data.", + "description": "Summarizes the class's internal state by returning an object containing `meta` and `lookup` properties.", "params": [], "returns": { - "type_name": "Summary*", - "description": "An object containing two properties: `meta` and `lookup`, both having values inherited from the instance properties `this.meta` and `this.lookup`." + "type_name": "Summary", + "description": "An object containing two properties: `meta` and `lookup`." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote = async () => ({});\nconst result = documentStore.outputSummary();\n", + "code": "const docStore = new DocumentStore({ getRemote, integration }); // Set up an instance of a DocumentStore class with various parameters\ndocStore.outputSummary(); // Call the outputSummary() method to generate high-quality documentation.\n", "description": "" }, "name": "outputSummary", @@ -579,19 +579,19 @@ "docLength": 6 }, { - "id": "4022b960-51d9-989e-c247-ceab8c31a63f", + "id": "3d6194af-76de-1cb3-a940-c2b0ac67bcdd", "ancestors": [ - "cd224204-9704-a7bc-b94b-41f37246ba35" + "2e83609e-de98-86a8-b648-0ce786451e62" ], - "description": "Splits its internal content into fixed-size chunks, maps each chunk to a unique key using the `chunkIndexToChunkKey` and `chunkKeyToChunkPath` methods, and returns a record containing these key-value pairs.", + "description": "Creates a new Record object containing chunks of the original content, each chunk represented by a key-value pair where the key is the path to the chunk and the value is the chunk of content.", "params": [], "returns": { - "type_name": "Record*", - "description": "An object where keys are strings and values can be of any data type, representing a mapping between chunk keys and corresponding chunks of content." + "type_name": "Record", + "description": "A mapping of string chunk keys to their corresponding chunks of text." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(...);\n\ndocumentStore.CHUNK_SIZE = 1024;\nconst outputs = documentStore.outputChunks();\n", + "code": "const documentStore = new DocumentStore({ getRemote });\nconst outputChunks = documentStore.outputChunks();\n", "description": "" }, "name": "outputChunks", diff --git a/.komment/komment.json b/.komment/komment.json index 5269ef4..4fadbdc 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-12T05:16:18.392Z", + "updated_at": "2024-07-12T05:21:09.509Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -20,7 +20,8 @@ "dbb10926-033f-4543-b4cc-bee6999543f8", "521fe478-f3d3-4440-81b8-31b85cb89a46", "bd56018a-a4ab-43de-aa64-a02ed61b32be", - "344dea1f-37c5-4706-b964-90ffeed56096" + "344dea1f-37c5-4706-b964-90ffeed56096", + "c355b024-a5e5-4eea-b745-fd2482d6e5c6" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 23c2041..24ee476 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,10 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Manages a collection of files (code chunks) and provides methods to - * load, update, and retrieve files from the store. It maintains metadata about the - * files, ensures chunking for efficient storage and retrieval, and offers output - * methods for generating documentation and extracting code records. + * @description Provides an implementation for storing and retrieving code documentation + * in a structured manner, allowing for efficient access and manipulation of files + * and chunks within a specified namespace. * * @implements {IDocumentStore} */ @@ -47,18 +46,18 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Initializes an instance with required properties such as namespace, - * getRemote method, and additional metadata. It also sets default values for other - * properties like CHUNK_SIZE, lookup array, chunks array, content array, and status - * object. + * @description Sets up instance variables for namespace, getRemote method, chunk + * size, metadata, and other properties, ensuring they are not null or undefined + * before initialization. * - * @param {string*} namespace - Required to be set. + * @param {string} namespace - Required. Its purpose is to provide a unique name or + * identifier for the remote document. * - * @param {(...args: any[]) => Promise>*} getRemote - Intended to - * retrieve data remotely. + * @param {(...args: any[]) => Promise>} getRemote - Required to + * retrieve data from an external source. * - * @param {Record*} additionalMeta - Used to provide additional metadata - * information. + * @param {Record} additionalMeta - Used to store custom metadata for + * the document. */ constructor( namespace: string, @@ -88,20 +87,19 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` property of its instance with the provided - * `updated_at` date. This method modifies the internal state of the object, updating - * the timestamp indicating when the document was last updated. + * @description Updates the `updated_at` metadata field of an instance by assigning + * the provided `Date` object to it. * - * @param {Date*} updated_at - Used to update the value of the `updated_at` property. + * @param {Date} updated_at - Used to update the `updated_at` metadata field for the + * current object. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Loads and updates the summary data from a remote source or uses a - * local template if no data is available, then applies the loaded data to its own - * properties and sets a status flag indicating whether a summary is loaded. + * @description Retrieves and updates the document summary information, including + * meta data and chunk information, and assigns it to the instance's `summary` property. */ loadSummary = async () => { let summary: Summary = { @@ -130,7 +128,8 @@ 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 default values to object properties. + // Updates the `this.meta` object with values from the `summary.meta` object or the + // original `value`, if the `summary` object doesn't have an entry for the key. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -139,9 +138,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Loads and initializes document data. If the summary is not loaded, - * it calls `loadSummary()`. Then, it looks up chunk indices and loads corresponding - * chunks using `loadChunk()` method. Finally, it sets the `chunks` property to `true`. + * @description Async loads chunks of data from a summary and sets the `chunks` status + * to true once loaded. */ load = async () => { if (!this.status.summary) { @@ -164,12 +162,12 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata object by merging it with an additional metadata - * record. The resulting metadata object is assigned back to the instance property - * `meta`. This allows for incremental modification of the metadata over time. + * @description Updates the metadata of an object by combining its current metadata + * with additional metadata provided as an argument, storing the resulting metadata + * in the `meta` property of the class instance. * - * @param {Record*} additionalMeta - Intended to provide additional - * metadata for updating. + * @param {Record} additionalMeta - Used to add additional metadata to + * the existing metadata object. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -185,13 +183,14 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Loads a chunk of structured files from a remote location, checks if - * it's already loaded, and updates the local state with the new data. If an error - * occurs during loading, it returns false; otherwise, it returns true. + * @description Ynchronously retrieves and appends a chunk of data to the store's + * content, marking it as loaded upon success. * - * @param {number*} chunkIndex - Used to identify the chunk to load from remote storage. + * @param {number} chunkIndex - Used to represent the index of a chunk that needs to + * be loaded from the remote server. * - * @returns {Promise*} Resolved to either true or false. + * @returns {Promise} Resolved when the chunk is loaded successfully, and + * rejected otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -210,15 +209,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Asynchronously retrieves a file with the given path from an array of - * chunks, loading the chunk if necessary and checking its integrity. It returns the - * file object or null if it does not exist. + * @description Retrieves a file from the store based on its path, loading the necessary + * chunks and checking for correctness of the chunk and lookup. * - * @param {string*} path - Used to specify a file path. + * @param {string} path - Used to identify a file within a chunk. * - * @returns {Promise*} Either a StructuredFile object or null. - * If the file exists and is successfully loaded, it returns the StructuredFile object; - * otherwise, it returns null. + * @returns {Promise} A promise that resolves to either a + * StructuredFile object or null. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -261,11 +258,11 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds paths to the last lookup subtable or creates a new one if it's - * full, maintaining a fixed chunk size (`CHUNK_SIZE`). It ensures efficient storage - * and retrieval of document paths in a hierarchical structure. + * @description Updates the lookup subtable by adding a new entry or appending to the + * existing one based on the current table size and length. * - * @param {string*} path - Used to add to the end of the lookup table. + * @param {string} path - Used to specify the path to be added to the end of the + * lookup subtable. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -279,11 +276,11 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the last lookup subtable if it's not full, or creates - * a new one if the current table is full. It maintains an array of chunks with a - * fixed size and keeps track of the files within each chunk. + * @description Adds files to the end of existing chunks or creates new ones if + * necessary, maintaining a maximum size for each chunk. * - * @param {StructuredFile*} file - Intended to be appended at the end of chunks. + * @param {StructuredFile} file - Used to represent a file that needs to be added to + * the chunks array. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -297,14 +294,15 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a structured file to the store. If the file already exists, it - * updates its content; otherwise, it appends it to the end of the lookup and chunks - * arrays, and pushes it into the content array. + * @description Allows adding a file to the document store if certain conditions are + * met, including the file existing at the specified path and the `load` method being + * called before adding files. * - * @param {StructuredFile*} file - Used to add files to the system. + * @param {StructuredFile} file - Used to represent a file that can be added to the + * content of the object. * - * @returns {boolean*} True if a file has been successfully added to the collection - * and false otherwise. + * @returns {boolean} True when a file is successfully added to the structured file + * and False otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -327,14 +325,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a structured file with a given path. It checks if the file - * exists and loads the corresponding chunk if necessary. If successful, it replaces - * the old file content with the new one in both chunk and content arrays. + * @description Updates a file in the store by checking if it exists, loading any + * necessary chunks, and updating the file's position in the chunk. * - * @param {StructuredFile*} file - Intended to update an existing file. + * @param {StructuredFile} file - Used to represent a file being updated, passed by + * reference from the caller. * - * @returns {Promise*} A promise that resolves to either true or false - * indicating whether the file update operation was successful or not. + * @returns {Promise} True if the file was updated successfully and false otherwise. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -364,12 +361,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing two properties: `meta` and `lookup`. - * This summary likely represents a condensed version of the document's metadata and - * lookup information, facilitating efficient retrieval or display of key data. + * @description Summarizes the class's internal state by returning an object containing + * `meta` and `lookup` properties. * - * @returns {Summary*} An object containing two properties: `meta` and `lookup`, both - * having values inherited from the instance properties `this.meta` and `this.lookup`. + * @returns {Summary} An object containing two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -378,13 +373,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Splits its internal content into fixed-size chunks, maps each chunk - * to a unique key using the `chunkIndexToChunkKey` and `chunkKeyToChunkPath` methods, - * and returns a record containing these key-value pairs. + * @description Creates a new Record object containing chunks of the original content, + * each chunk represented by a key-value pair where the key is the path to the chunk + * and the value is the chunk of content. * - * @returns {Record*} An object where keys are strings and values can - * be of any data type, representing a mapping between chunk keys and corresponding - * chunks of content. + * @returns {Record} A mapping of string chunk keys to their corresponding + * chunks of text. */ outputChunks(): Record { const outputs: Record = {}; From aeb97afba3098d213b746ddba34918147dfd9112 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Fri, 12 Jul 2024 05:27:00 +0000 Subject: [PATCH 25/30] [tc]Added comments to 15 functions across 1 file --- .komment/00000.json | 212 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 126 ++++++++++++------------- 3 files changed, 171 insertions(+), 172 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index beae2d4..2a9b647 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 adding, retrieving, and updating files in a designated folder. It accepts a constructor parameter representing a third-party library or service that generates high-quality documentation, along with additional metadata that can be used to customize the document store's behavior. The class provides methods for loading and updating the document summary, as well as adding and updating individual files. It also includes properties for storing chunk data, content, and other meta information.", + "description": "An class called `DocumentStore` that manages a collection of files and their contents. It provides methods for adding, updating, and looking up files in the collection, as well as outputting summary information about the files. The code also uses several high-level packages, including `btoa` (base64 encoding), `Error` (for handling errors), `console.log` (for debugging), and `Promise` (for asynchronous operations).", "items": [ { - "id": "2e83609e-de98-86a8-b648-0ce786451e62", + "id": "201361aa-202a-a4b0-474c-7245ff886fee", "ancestors": [], - "description": "Provides an implementation for storing and retrieving code documentation in a structured manner, allowing for efficient access and manipulation of files and chunks within a specified namespace.", + "description": "Manages a collection of files and their contents, providing functions to add, update, and retrieve files for use in code generation. It also generates high-quality documentation and chunks of code based on the given content.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "Used to specify the size of a chunk in bytes for storing code documentation." + "description": "48 in this implementation, indicating the size of each chunk for file management purposes." }, { "name": "namespace", "type_name": "string", - "description": "Used to specify the namespace for the document store, which determines how the documents are organized and accessed." + "description": "Used to specify the root namespace for the documents stored by the class, allowing for more organized and structured storage of files." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the document, such as version, creation date, and update date." + "description": "Used to store metadata about the code's structure, such as version number, creation date, and update date}." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to specify a template for customizing the structure of the metadata." + "description": "Used to specify a template for generating the metadata for a code chunk." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a list of sub-arrays containing file paths that correspond to the chunks stored in the document store. It plays a crucial role in storing and retrieving files from the document store." + "description": "Used to store the file paths for a set of chunks that are associated with the code's content." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store chunks of code content. It is used to store the content of the document in a structured way, making it easier to access and manipulate the content." + "description": "Used to store chunks of files in a code, each chunk containing multiple files of a specific size." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store the actual content of the documents, which can be accessed through the `addFile()` method" + "description": "Used to store the files added to the document store, which can be accessed through the methods `addFile` and `outputChunks`." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to store information about the status of the documentation, such as whether it has been summarized or if chunks have been loaded." + "description": "Used to track the loading state of chunks in the document store." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "2abae119-7d54-da8b-924a-deafb4bff4be", + "id": "6dcd7b9a-bcae-61b6-f948-ec3ccccd4b1f", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Sets up instance variables for namespace, getRemote method, chunk size, metadata, and other properties, ensuring they are not null or undefined before initialization.", + "description": "Sets up instance variables for namespace, getRemote method, chunk size, and meta data. It also initializes lookup, chunks, content, and status objects.", "params": [ { "name": "namespace", - "type_name": "string", + "type_name": "string*", "optional": false, - "description": "Required. Its purpose is to provide a unique name or identifier for the remote document.", + "description": "Required to identify the name space for the content being processed.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>", + "type_name": "(...args: any[]) => Promise>*", "optional": false, - "description": "Required to retrieve data from an external source.", + "description": "Used to fetch remote data for chunking.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record", + "type_name": "Record*", "optional": true, - "description": "Used to store custom metadata for the document.", + "description": "Used to provide additional metadata for the document store, such as version number or creation date.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(namespace, getRemote);\ndocumentStore.setUpdatedAt(new Date());\ndocumentStore.loadSummary();\n", - "description": "" + "code": "const documentStore = new DocumentStore(\n \"my-namespace\",\n getRemote, //3rd party library or service that provides the functionality\n { version: \"1.0.0\" } //Additional meta data to store locally\n);\n", + "description": "\nIn this example, we are creating a new instance of the `DocumentStore` class with a namespace called `\"my-namespace\"` and passing in a function for getting remote documents as well as additional meta data to be stored locally." }, "name": null, "location": { @@ -182,24 +182,24 @@ "docLength": 12 }, { - "id": "c7ef7154-ca8b-81b2-b041-b7b59ce1202d", + "id": "d9ccdb2a-dea6-27b6-8140-f591dd37df93", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Updates the `updated_at` metadata field of an instance by assigning the provided `Date` object to it.", + "description": "Updates the instance variable `meta.updated_at` with the provided `Date` object, serving as a proxy for the document's last updated time.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date", - "description": "Used to update the `updated_at` metadata field for the current object." + "type_name": "Date*", + "description": "Used to update the object's `meta` property with the current date time value, ensuring that the object's last updated timestamp remains up-to-date." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.setUpdatedAt(new Date());\n", - "description": "\nIn this example, `DocumentStore` is a class that contains methods and properties for storing and managing document data, such as `getRemote`, `metaTemplate`, `lookup`, `chunks`, `content`, `status`. The method `setUpdatedAt()` takes an argument of type `Date` representing the updated date.\nThis example shows how to use the `setUpdatedAt()` method by creating a new instance of `DocumentStore` and calling its `setUpdatedAt()` method with a `new Date()` object as an argument." + "code": "const myDocumentStore = new DocumentStore(getRemote, integration);\nmyDocumentStore.setUpdatedAt(new Date());\n", + "description": "" }, "name": "setUpdatedAt", "location": { @@ -217,15 +217,15 @@ "docLength": 7 }, { - "id": "6c7e133c-5867-73b7-a242-c73d2b0dcdee", + "id": "8bcaf073-bcd8-d986-8846-ba768ea85a9d", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Retrieves and updates the document summary information, including meta data and chunk information, and assigns it to the instance's `summary` property.", + "description": "Retrieves and updates summary information from remote storage, merges it with local data, and stores it locally.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary(); // Load summary data from remote storage.\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.loadSummary();\n", "description": "" }, "name": "loadSummary", @@ -244,12 +244,12 @@ "docLength": 4 }, { - "id": "c9af65eb-8713-519b-8c4c-dea95ebf6a32", + "id": "3818fa16-b25e-b3a1-de4e-46662c061f12", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62", - "6c7e133c-5867-73b7-a242-c73d2b0dcdee" + "201361aa-202a-a4b0-474c-7245ff886fee", + "8bcaf073-bcd8-d986-8846-ba768ea85a9d" ], - "description": "Updates the `this.meta` object with values from the `summary.meta` object or the original `value`, if the `summary` object doesn't have an entry for the key.", + "description": "Updates `this.meta` with values from `summary.meta` or the original value of `value`, depending on the existence and value of `summary.meta`.", "name": null, "location": { "start": 121, @@ -263,15 +263,15 @@ "docLength": null }, { - "id": "47e08d28-a541-8384-e646-7aa86ec96616", + "id": "b3d439ab-0492-d68b-894f-e7f92a933ebd", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Async loads chunks of data from a summary and sets the `chunks` status to true once loaded.", + "description": "Async loads chunks of data from a summary, setting `status.chunks` to `true` upon completion.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.load();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.load();\n", "description": "" }, "name": "load", @@ -290,24 +290,24 @@ "docLength": 3 }, { - "id": "fc7f219c-8fc3-2392-064e-c6ee991bb5e6", + "id": "c0fb979d-2522-08ae-9341-ef4f2a2a9ab9", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Updates the metadata of an object by combining its current metadata with additional metadata provided as an argument, storing the resulting metadata in the `meta` property of the class instance.", + "description": "Updates the metadata of an object by combining its current metadata with any additional metadata provided as an argument, resulting in a new, updated metadata object.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record", - "description": "Used to add additional metadata to the existing metadata object." + "type_name": "Record*", + "description": "Used to update the `meta` property of an object by combining its current value with new metadata values.*" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\n documentStore.updateMetadata({\n version: '1.0',\n created_at: Date.now(),\n updated_at: Date.now()\n });\n", - "description": "\nIn this example, `updateMetadata` is called on an instance of the `DocumentStore` class to update its metadata. The method takes a record of key-value pairs as an argument, where the keys are the names of the properties that should be updated, and the values are the new values for those properties. In this case, the version, created_at, and updated_at properties are all updated to the current date and time." + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.updateMetadata({\n version: '1.0',\n created_at: new Date(),\n updated_at: new Date(),\n});\n", + "description": "" }, "name": "updateMetadata", "location": { @@ -322,27 +322,27 @@ "docLength": null }, { - "id": "548d36ea-41b4-928f-e64f-9664b34b946c", + "id": "0d05adb9-9b02-8db0-6640-284abbfbc861", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Ynchronously retrieves and appends a chunk of data to the store's content, marking it as loaded upon success.", + "description": "Asyncously checks if a given chunk has been loaded, loads it if not, and concats it with the content if successful.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number", - "description": "Used to represent the index of a chunk that needs to be loaded from the remote server." + "type_name": "number*", + "description": "Used to represent the index of a particular chunk in the list of chunks." } ], "returns": { - "type_name": "Promise", - "description": "Resolved when the chunk is loaded successfully, and rejected otherwise." + "type_name": "Promise*", + "description": "Resolved to true if the chunk was successfully loaded and false otherwise." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nawait store.loadChunk(123); // Load chunk number 123\n", + "code": "const store = new DocumentStore(getRemote, integration);\nawait store.loadChunk(2); // Load chunk 2\nconst content = store.content; // Get the content of the loaded chunk\n", "description": "" }, "name": "loadChunk", @@ -361,28 +361,28 @@ "docLength": 11 }, { - "id": "ae75e735-383d-4691-4649-fef8aab3d752", + "id": "356a50cd-fe06-d295-354f-8a0d5d18b35e", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Retrieves a file from the store based on its path, loading the necessary chunks and checking for correctness of the chunk and lookup.", + "description": "Retrieves a file from a summary data structure, calculating its chunk and file index within that chunk, and loading the chunk if necessary.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "Used to identify a file within a chunk." + "type_name": "string*", + "description": "Used to represent the file path being searched for within the model's chunks." } ], "returns": { - "type_name": "Promise", - "description": "A promise that resolves to either a StructuredFile object or null." + "type_name": "Promise*", + "description": "Either a StructuredFile object or null depending on the file's presence in the specified chunk and its loading status." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.loadSummary().then(() => {\n const file = documentStore.getFile('path/to/file');\n});\n", - "description": "" + "code": "const path = \"path/to/file\";\nconst file = documentStore.getFile(path);\n", + "description": "\nThis code retrieves a file from the Document Store instance using the `getFile` method and stores it in the `file` variable." }, "name": "getFile", "location": { @@ -400,23 +400,23 @@ "docLength": 10 }, { - "id": "96541505-95ab-74a4-204a-decc433f0321", + "id": "807e3936-db81-0cb7-4c4b-cd2aabe402cd", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Updates the lookup subtable by adding a new entry or appending to the existing one based on the current table size and length.", + "description": "Adds a new path to the end of the lookup subtable if it's full or if the last element in the subtable is at capacity.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string", - "description": "Used to specify the path to be added to the end of the lookup subtable." + "type_name": "string*", + "description": "Used to add new elements to the end of an internal array for storing substrings, which is the purpose of the function." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfLookup(\"path\");\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfLookup(\"path\");\n", "description": "" }, "name": "addToEndOfLookup", @@ -435,23 +435,23 @@ "docLength": 6 }, { - "id": "f4449ff0-cf9a-54b4-e34c-43459f8a31a1", + "id": "99db71b2-3866-ecaf-4b40-01a86cf30313", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Adds files to the end of existing chunks or creates new ones if necessary, maintaining a maximum size for each chunk.", + "description": "Manages the chunking of files based on file size, adding new files to the end of existing chunks or creating new chunks if necessary.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Used to represent a file that needs to be added to the chunks array." + "type_name": "StructuredFile*", + "description": "Used to add a new file to the end of the chunked data." } ], "usage": { "language": "typescript", - "code": "let documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.addToEndOfChunks(file);\n", + "code": "const file = new StructuredFile(); // create a new instance of the StructuredFile class\nfile.addToEndOfChunks(documentStore); // add the newly created structured file to the end of the lookup subtable\n\nconst files = documentStore.lookup; // retrieve the lookup subtable\nfiles[files.length - 1].push(file); // push the new StructuredFile instance onto the last lookup subtable\n", "description": "" }, "name": "addToEndOfChunks", @@ -470,27 +470,27 @@ "docLength": 10 }, { - "id": "da01e283-02c0-4494-3946-0c9af773f930", + "id": "530e52e3-d6ff-42a9-8b46-5f614f73fe0a", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Allows adding a file to the document store if certain conditions are met, including the file existing at the specified path and the `load` method being called before adding files.", + "description": "Adds a file to the collection of files stored by the class, checking for file existence and proper loading state beforehand.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Used to represent a file that can be added to the content of the object." + "type_name": "StructuredFile*", + "description": "Used to represent the file to be added to the content library." } ], "returns": { - "type_name": "boolean", - "description": "True when a file is successfully added to the structured file and False otherwise." + "type_name": "boolean*", + "description": "1 when a file is successfully added to the content and 0 otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore();\ndocStore.addFile(file);\nconst file = new StructuredFile(\"path/to/file\");\n", + "code": "const docStore = new DocumentStore();\nconst file1 = { path: \"path/to/file1\", content: \"This is file1\" };\nconst file2 = { path: \"path/to/file2\", content: \"This is file2\" };\n\ndocStore.addFile(file1); // Add the first file to the store\ndocStore.addFile(file2); // Add the second file to the store\n", "description": "" }, "name": "addFile", @@ -509,28 +509,28 @@ "docLength": 10 }, { - "id": "f412d059-3f17-c0ab-0143-28a81a497832", + "id": "09495ab9-1694-4b84-3041-ccc54529be48", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Updates a file in the store by checking if it exists, loading any necessary chunks, and updating the file's position in the chunk.", + "description": "Updates a file in the store by checking if it exists, loading the appropriate chunk if necessary, and storing the updated file in the chunk.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile", - "description": "Used to represent a file being updated, passed by reference from the caller." + "type_name": "StructuredFile*", + "description": "Used to update an existing file or add a new one." } ], "returns": { - "type_name": "Promise", - "description": "True if the file was updated successfully and false otherwise." + "type_name": "Promise*", + "description": "True if the file was successfully updated and false otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote);\ndocStore.updateFile(file);\n", - "description": "" + "code": "const docStore = new DocumentStore(getRemote, integration);\nconst file: StructuredFile = { path: \"path/to/file.txt\", contents: \"some contents\" };\ndocStore.updateFile(file)\n .then((result) => console.log(\"Result: \", result))\n .catch((error) => console.error(\"Error: \", error));\n", + "description": "\nThe code first creates an instance of the `DocumentStore` class using the constructor, passing in the `getRemote` and integration objects as parameters. Then it creates a `StructuredFile` object with some sample data, and then calls the `updateFile` method on the `docStore` object to update the file. The result is logged to the console." }, "name": "updateFile", "location": { @@ -548,19 +548,19 @@ "docLength": 10 }, { - "id": "f9b3c736-9436-4396-3348-c8c484c717b8", + "id": "78888ed2-6aa7-14ad-0849-5199f8b542e2", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Summarizes the class's internal state by returning an object containing `meta` and `lookup` properties.", + "description": "Summarizes an object containing metadata and a lookup map, returning a new object with the same properties.", "params": [], "returns": { - "type_name": "Summary", + "type_name": "Summary*", "description": "An object containing two properties: `meta` and `lookup`." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore({ getRemote, integration }); // Set up an instance of a DocumentStore class with various parameters\ndocStore.outputSummary(); // Call the outputSummary() method to generate high-quality documentation.\n", + "code": "let docStore = new DocumentStore(getRemote, integration);\ndocStore.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -579,20 +579,20 @@ "docLength": 6 }, { - "id": "3d6194af-76de-1cb3-a940-c2b0ac67bcdd", + "id": "47f09a8f-4254-bc99-df44-9765a3cb314c", "ancestors": [ - "2e83609e-de98-86a8-b648-0ce786451e62" + "201361aa-202a-a4b0-474c-7245ff886fee" ], - "description": "Creates a new Record object containing chunks of the original content, each chunk represented by a key-value pair where the key is the path to the chunk and the value is the chunk of content.", + "description": "Iterates through the document content, slicing it into chunks, and storing each chunk in a new key-value pair in an output object.", "params": [], "returns": { - "type_name": "Record", - "description": "A mapping of string chunk keys to their corresponding chunks of text." + "type_name": "Record*", + "description": "An object mapping chunk keys to their corresponding chuncks." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore({ getRemote });\nconst outputChunks = documentStore.outputChunks();\n", - "description": "" + "code": "// Create instance of DocumentStore class\nconst documentStore = new DocumentStore(getRemote, integration);\n\n// Initialize DocumentStore with necessary parameters\ndocumentStore.init();\n\n// Get list of chunks\nconst chunkList = documentStore.outputChunks();\n\n// Iterate over chunks and retrieve content\nchunkList.forEach((chunk) => {\n const content = chunk.content;\n});\n", + "description": "\nThe code creates an instance of the `DocumentStore` class, passing in necessary parameters for initialization. It then calls the `init()` method to initialize the internal arrays and objects to store chunk data, content, and other meta information. Finally, it calls the `outputChunks()` method to get a list of chunks, which can be iterated over and used to retrieve the content for each chunk." }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index 4fadbdc..3d3ca4c 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-12T05:21:09.509Z", + "updated_at": "2024-07-12T05:26:53.330Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -21,7 +21,8 @@ "521fe478-f3d3-4440-81b8-31b85cb89a46", "bd56018a-a4ab-43de-aa64-a02ed61b32be", "344dea1f-37c5-4706-b964-90ffeed56096", - "c355b024-a5e5-4eea-b745-fd2482d6e5c6" + "c355b024-a5e5-4eea-b745-fd2482d6e5c6", + "532c71df-781e-414b-98ad-8f67da7424a6" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 24ee476..9274083 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,9 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Provides an implementation for storing and retrieving code documentation - * in a structured manner, allowing for efficient access and manipulation of files - * and chunks within a specified namespace. + * @description Manages a collection of files and their contents, providing functions + * to add, update, and retrieve files for use in code generation. It also generates + * high-quality documentation and chunks of code based on the given content. * * @implements {IDocumentStore} */ @@ -47,17 +47,16 @@ class DocumentStore implements IDocumentStore { /** * @description Sets up instance variables for namespace, getRemote method, chunk - * size, metadata, and other properties, ensuring they are not null or undefined - * before initialization. + * size, and meta data. It also initializes lookup, chunks, content, and status objects. * - * @param {string} namespace - Required. Its purpose is to provide a unique name or - * identifier for the remote document. + * @param {string*} namespace - Required to identify the name space for the content + * being processed. * - * @param {(...args: any[]) => Promise>} getRemote - Required to - * retrieve data from an external source. + * @param {(...args: any[]) => Promise>*} getRemote - Used to fetch + * remote data for chunking. * - * @param {Record} additionalMeta - Used to store custom metadata for - * the document. + * @param {Record*} additionalMeta - Used to provide additional metadata + * for the document store, such as version number or creation date. */ constructor( namespace: string, @@ -87,19 +86,20 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of an instance by assigning - * the provided `Date` object to it. + * @description Updates the instance variable `meta.updated_at` with the provided + * `Date` object, serving as a proxy for the document's last updated time. * - * @param {Date} updated_at - Used to update the `updated_at` metadata field for the - * current object. + * @param {Date*} updated_at - Used to update the object's `meta` property with the + * current date time value, ensuring that the object's last updated timestamp remains + * up-to-date. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates the document summary information, including - * meta data and chunk information, and assigns it to the instance's `summary` property. + * @description Retrieves and updates summary information from remote storage, merges + * it with local data, and stores it locally. */ loadSummary = async () => { let summary: Summary = { @@ -128,8 +128,8 @@ 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 the `this.meta` object with values from the `summary.meta` object or the - // original `value`, if the `summary` object doesn't have an entry for the key. + // Updates `this.meta` with values from `summary.meta` or the original value of + // `value`, depending on the existence and value of `summary.meta`. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -138,8 +138,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Async loads chunks of data from a summary and sets the `chunks` status - * to true once loaded. + * @description Async loads chunks of data from a summary, setting `status.chunks` + * to `true` upon completion. */ load = async () => { if (!this.status.summary) { @@ -163,11 +163,11 @@ class DocumentStore implements IDocumentStore { /** * @description Updates the metadata of an object by combining its current metadata - * with additional metadata provided as an argument, storing the resulting metadata - * in the `meta` property of the class instance. + * with any additional metadata provided as an argument, resulting in a new, updated + * metadata object. * - * @param {Record} additionalMeta - Used to add additional metadata to - * the existing metadata object. + * @param {Record*} additionalMeta - Used to update the `meta` property + * of an object by combining its current value with new metadata values.* */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -183,14 +183,14 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Ynchronously retrieves and appends a chunk of data to the store's - * content, marking it as loaded upon success. + * @description Asyncously checks if a given chunk has been loaded, loads it if not, + * and concats it with the content if successful. * - * @param {number} chunkIndex - Used to represent the index of a chunk that needs to - * be loaded from the remote server. + * @param {number*} chunkIndex - Used to represent the index of a particular chunk + * in the list of chunks. * - * @returns {Promise} Resolved when the chunk is loaded successfully, and - * rejected otherwise. + * @returns {Promise*} Resolved to true if the chunk was successfully loaded + * and false otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -209,13 +209,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from the store based on its path, loading the necessary - * chunks and checking for correctness of the chunk and lookup. + * @description Retrieves a file from a summary data structure, calculating its chunk + * and file index within that chunk, and loading the chunk if necessary. * - * @param {string} path - Used to identify a file within a chunk. + * @param {string*} path - Used to represent the file path being searched for within + * the model's chunks. * - * @returns {Promise} A promise that resolves to either a - * StructuredFile object or null. + * @returns {Promise*} Either a StructuredFile object or null + * depending on the file's presence in the specified chunk and its loading status. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -258,11 +259,11 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Updates the lookup subtable by adding a new entry or appending to the - * existing one based on the current table size and length. + * @description Adds a new path to the end of the lookup subtable if it's full or if + * the last element in the subtable is at capacity. * - * @param {string} path - Used to specify the path to be added to the end of the - * lookup subtable. + * @param {string*} path - Used to add new elements to the end of an internal array + * for storing substrings, which is the purpose of the function. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -276,11 +277,11 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds files to the end of existing chunks or creates new ones if - * necessary, maintaining a maximum size for each chunk. + * @description Manages the chunking of files based on file size, adding new files + * to the end of existing chunks or creating new chunks if necessary. * - * @param {StructuredFile} file - Used to represent a file that needs to be added to - * the chunks array. + * @param {StructuredFile*} file - Used to add a new file to the end of the chunked + * data. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -294,15 +295,13 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Allows adding a file to the document store if certain conditions are - * met, including the file existing at the specified path and the `load` method being - * called before adding files. + * @description Adds a file to the collection of files stored by the class, checking + * for file existence and proper loading state beforehand. * - * @param {StructuredFile} file - Used to represent a file that can be added to the - * content of the object. + * @param {StructuredFile*} file - Used to represent the file to be added to the + * content library. * - * @returns {boolean} True when a file is successfully added to the structured file - * and False otherwise. + * @returns {boolean*} 1 when a file is successfully added to the content and 0 otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -325,13 +324,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the store by checking if it exists, loading any - * necessary chunks, and updating the file's position in the chunk. + * @description Updates a file in the store by checking if it exists, loading the + * appropriate chunk if necessary, and storing the updated file in the chunk. * - * @param {StructuredFile} file - Used to represent a file being updated, passed by - * reference from the caller. + * @param {StructuredFile*} file - Used to update an existing file or add a new one. * - * @returns {Promise} True if the file was updated successfully and false otherwise. + * @returns {Promise*} True if the file was successfully updated and false + * otherwise. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -361,10 +360,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Summarizes the class's internal state by returning an object containing - * `meta` and `lookup` properties. + * @description Summarizes an object containing metadata and a lookup map, returning + * a new object with the same properties. * - * @returns {Summary} An object containing two properties: `meta` and `lookup`. + * @returns {Summary*} An object containing two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -373,12 +372,11 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Creates a new Record object containing chunks of the original content, - * each chunk represented by a key-value pair where the key is the path to the chunk - * and the value is the chunk of content. + * @description Iterates through the document content, slicing it into chunks, and + * storing each chunk in a new key-value pair in an output object. * - * @returns {Record} A mapping of string chunk keys to their corresponding - * chunks of text. + * @returns {Record*} An object mapping chunk keys to their corresponding + * chuncks. */ outputChunks(): Record { const outputs: Record = {}; From f65521475276db3315c54e118fa877c04e830e84 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Fri, 12 Jul 2024 09:07:53 +0000 Subject: [PATCH 26/30] Added comments to 15 functions across 1 file --- .komment/00000.json | 208 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 125 +++++++++++++------------ 3 files changed, 168 insertions(+), 170 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 2a9b647..7ee5d63 100644 --- a/.komment/00000.json +++ b/.komment/00000.json @@ -4,12 +4,12 @@ "path": "src/index.ts", "content": { "structured": { - "description": "An class called `DocumentStore` that manages a collection of files and their contents. It provides methods for adding, updating, and looking up files in the collection, as well as outputting summary information about the files. The code also uses several high-level packages, including `btoa` (base64 encoding), `Error` (for handling errors), `console.log` (for debugging), and `Promise` (for asynchronous operations).", + "description": "A DocumentStore class that manages adding, retrieving, and updating documents in a specified namespace. It also provides methods for generating high-quality documentation and outputting chunks of code based on the given content. The class uses various packages such as `passing-api` and `highland` to perform its functions.", "items": [ { - "id": "201361aa-202a-a4b0-474c-7245ff886fee", + "id": "ee29f824-943b-c1b4-964f-bf43e6e55b2f", "ancestors": [], - "description": "Manages a collection of files and their contents, providing functions to add, update, and retrieve files for use in code generation. It also generates high-quality documentation and chunks of code based on the given content.", + "description": "Provides a centralized storage and management system for files, handling chunking, loading, and metadata for high-quality documentation generation.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "48 in this implementation, indicating the size of each chunk for file management purposes." + "description": "5, which represents the size of each chunk in bytes for storing and retrieving files from a remote store." }, { "name": "namespace", "type_name": "string", - "description": "Used to specify the root namespace for the documents stored by the class, allowing for more organized and structured storage of files." + "description": "A name or identifier for the document store, which can be used to refer to it from other parts of the code." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store metadata about the code's structure, such as version number, creation date, and update date}." + "description": "Used to store high-quality documentation-related metadata." }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to specify a template for generating the metadata for a code chunk." + "description": "Used to provide a template for generating high-quality documentation for code." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store the file paths for a set of chunks that are associated with the code's content." + "description": "Used to store a list of sub-arrays, where each sub-array contains a chunk index and a file index within that chunk." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store chunks of files in a code, each chunk containing multiple files of a specific size." + "description": "Used to store the chunks of content from the original code, allowing for efficient retrieval of files within a particular chunk." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store the files added to the document store, which can be accessed through the methods `addFile` and `outputChunks`." + "description": "Used to store the contents of the documents." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to track the loading state of chunks in the document store." + "description": "Used to store information about the status of the document store" } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "6dcd7b9a-bcae-61b6-f948-ec3ccccd4b1f", + "id": "e39b354b-a990-7492-9a47-9501729db645", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Sets up instance variables for namespace, getRemote method, chunk size, and meta data. It also initializes lookup, chunks, content, and status objects.", + "description": "Sets up instance variables such as `CHUNK_SIZE`, `namespace`, `getRemote`, and `meta`, as well as initializing objects such as `lookup`, `chunks`, and `content`.", "params": [ { "name": "namespace", - "type_name": "string*", + "type_name": "string", "optional": false, - "description": "Required to identify the name space for the content being processed.", + "description": "Required to identify the name of a specific data store, such as a database or file system, where the chunked data will be stored.", "default_value": null }, { "name": "getRemote", - "type_name": "(...args: any[]) => Promise>*", + "type_name": "(...args: any[]) => Promise>", "optional": false, - "description": "Used to fetch remote data for chunking.", + "description": "Used to fetch data from a remote source, such as an API or database, and return it as a promise.", "default_value": null }, { "name": "additionalMeta", - "type_name": "Record*", + "type_name": "Record", "optional": true, - "description": "Used to provide additional metadata for the document store, such as version number or creation date.", + "description": "Used to store additional metadata about the document that can be used for customization or tracking purposes.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\n \"my-namespace\",\n getRemote, //3rd party library or service that provides the functionality\n { version: \"1.0.0\" } //Additional meta data to store locally\n);\n", - "description": "\nIn this example, we are creating a new instance of the `DocumentStore` class with a namespace called `\"my-namespace\"` and passing in a function for getting remote documents as well as additional meta data to be stored locally." + "code": "const documentStore = new DocumentStore(\n \"example-namespace\",\n async (...args) => {\n // getRemote implementation goes here\n },\n {\n version: \"1.0.0\",\n created_at: new Date(),\n updated_at: new Date(),\n additionalMeta: {},\n }\n);\n", + "description": "\nThis code instantiates a DocumentStore object with the namespace \"example-namespace\" and provides an implementation for getRemote method. The additionalMeta parameter is an optional object that can be used to add additional metadata to the document store." }, "name": null, "location": { @@ -182,23 +182,23 @@ "docLength": 12 }, { - "id": "d9ccdb2a-dea6-27b6-8140-f591dd37df93", + "id": "582c42b2-5c3c-beac-3548-cb27e24f1477", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Updates the instance variable `meta.updated_at` with the provided `Date` object, serving as a proxy for the document's last updated time.", + "description": "Updates the `updated_at` metadata field of the object, by setting it to the provided `Date` value.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, - "type_name": "Date*", - "description": "Used to update the object's `meta` property with the current date time value, ensuring that the object's last updated timestamp remains up-to-date." + "type_name": "Date", + "description": "Used to update the `updated_at` metadata field of an entity." } ], "usage": { "language": "typescript", - "code": "const myDocumentStore = new DocumentStore(getRemote, integration);\nmyDocumentStore.setUpdatedAt(new Date());\n", + "code": "const store = new DocumentStore();\nstore.setUpdatedAt(new Date()); // Update the updated_at field with current time.\n", "description": "" }, "name": "setUpdatedAt", @@ -217,15 +217,15 @@ "docLength": 7 }, { - "id": "8bcaf073-bcd8-d986-8846-ba768ea85a9d", + "id": "74b63f05-a80a-bcb1-2c4b-b81d868bed7d", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Retrieves and updates summary information from remote storage, merges it with local data, and stores it locally.", + "description": "Retrieves and updates a summary of documents stored in the store, including metadata and chunk information.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.loadSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary();\n", "description": "" }, "name": "loadSummary", @@ -244,12 +244,12 @@ "docLength": 4 }, { - "id": "3818fa16-b25e-b3a1-de4e-46662c061f12", + "id": "9b4daeca-55a7-9192-c945-b8561c2df96c", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee", - "8bcaf073-bcd8-d986-8846-ba768ea85a9d" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f", + "74b63f05-a80a-bcb1-2c4b-b81d868bed7d" ], - "description": "Updates `this.meta` with values from `summary.meta` or the original value of `value`, depending on the existence and value of `summary.meta`.", + "description": "Updates the `this.meta` object with values from `summary.meta` or the original value if `summary.meta` is null or undefined.", "name": null, "location": { "start": 121, @@ -263,15 +263,15 @@ "docLength": null }, { - "id": "b3d439ab-0492-d68b-894f-e7f92a933ebd", + "id": "6a2161bc-1e90-17bc-aa44-ce1fb0b6a21c", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Async loads chunks of data from a summary, setting `status.chunks` to `true` upon completion.", + "description": "Asyncily loads chunks of data from storage based on a provided list of chunk indices, setting the `chunks` property to `true` upon completion.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.load();\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\n\nawait docStore.load();\n", "description": "" }, "name": "load", @@ -290,23 +290,23 @@ "docLength": 3 }, { - "id": "c0fb979d-2522-08ae-9341-ef4f2a2a9ab9", + "id": "73fa576b-8ba0-f488-414c-07a1fa72c6e5", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Updates the metadata of an object by combining its current metadata with any additional metadata provided as an argument, resulting in a new, updated metadata object.", + "description": "Updates the metadata of the instance by combining its current metadata with additional metadata provided as an argument, assigning the resulting object to the `meta` property.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, - "type_name": "Record*", - "description": "Used to update the `meta` property of an object by combining its current value with new metadata values.*" + "type_name": "Record", + "description": "Used to provide additional metadata to update the existing metadata of the object." } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.updateMetadata({\n version: '1.0',\n created_at: new Date(),\n updated_at: new Date(),\n});\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.updateMetadata({ version: '1.0.0', created_at: Date.now() });\n", "description": "" }, "name": "updateMetadata", @@ -322,27 +322,27 @@ "docLength": null }, { - "id": "0d05adb9-9b02-8db0-6640-284abbfbc861", + "id": "0709d86a-5ad4-c5a8-a349-cd6516f040be", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Asyncously checks if a given chunk has been loaded, loads it if not, and concats it with the content if successful.", + "description": "Asyncously checks if a chunk is loaded, retrieves it from the server if not, and appends it to the internal content and chunks arrays if successful.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, - "type_name": "number*", - "description": "Used to represent the index of a particular chunk in the list of chunks." + "type_name": "number", + "description": "Used to identify the specific chunk being loaded." } ], "returns": { - "type_name": "Promise*", - "description": "Resolved to true if the chunk was successfully loaded and false otherwise." + "type_name": "Promise", + "description": "True if the chunk was successfully loaded and false otherwise." }, "usage": { "language": "typescript", - "code": "const store = new DocumentStore(getRemote, integration);\nawait store.loadChunk(2); // Load chunk 2\nconst content = store.content; // Get the content of the loaded chunk\n", + "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote = async (key) => {\n // do some magic to retrieve the data from a remote location\n};\nawait documentStore.loadChunk(0);\n", "description": "" }, "name": "loadChunk", @@ -361,28 +361,28 @@ "docLength": 11 }, { - "id": "356a50cd-fe06-d295-354f-8a0d5d18b35e", + "id": "c8f89bf8-783d-0e93-f44f-372598c56e8c", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Retrieves a file from a summary data structure, calculating its chunk and file index within that chunk, and loading the chunk if necessary.", + "description": "Retrieves a file from the store based on its path, loading the necessary chunks and files if not already loaded. It returns the file or `null` if not found.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Used to represent the file path being searched for within the model's chunks." + "type_name": "string", + "description": "Used to represent the file path that the function will check for existence and load if necessary." } ], "returns": { - "type_name": "Promise*", - "description": "Either a StructuredFile object or null depending on the file's presence in the specified chunk and its loading status." + "type_name": "Promise", + "description": "A promise that resolves to a StructuredFile object or null if the file cannot be found in the specified chunk." }, "usage": { "language": "typescript", - "code": "const path = \"path/to/file\";\nconst file = documentStore.getFile(path);\n", - "description": "\nThis code retrieves a file from the Document Store instance using the `getFile` method and stores it in the `file` variable." + "code": "const getFile = async (path: string): Promise => {\n const store = new DocumentStore(getRemote, integration);\n // calling method getFile to access structured file\n await store.getFile('some/path'); \n}\n", + "description": "\nThis calls the `getFile` function of the `DocumentStore` class using the `getRemote` and `integration` methods. The `getFile` function then uses the `this` context to call other methods in the class such as `getChunkFileIsIn`, `isChunkLoaded`, `loadChunk`, `getFileIndexInChunk`, and `chunks`." }, "name": "getFile", "location": { @@ -400,23 +400,23 @@ "docLength": 10 }, { - "id": "807e3936-db81-0cb7-4c4b-cd2aabe402cd", + "id": "0a32c675-0a38-6ea3-fc44-48093d5f2b1c", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Adds a new path to the end of the lookup subtable if it's full or if the last element in the subtable is at capacity.", + "description": "Adds a new document path to the end of an existing lookup subtable or creates a new table if the last one is full, preserving the chunk size.", "params": [ { "name": "path", "default_value": null, "optional": false, - "type_name": "string*", - "description": "Used to add new elements to the end of an internal array for storing substrings, which is the purpose of the function." + "type_name": "string", + "description": "Used to add a new element to the end of the lookup subtable." } ], "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfLookup(\"path\");\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfLookup(\"path/to/file\");\n", "description": "" }, "name": "addToEndOfLookup", @@ -435,23 +435,23 @@ "docLength": 6 }, { - "id": "99db71b2-3866-ecaf-4b40-01a86cf30313", + "id": "6a710976-4226-8098-5741-7cc047e44144", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Manages the chunking of files based on file size, adding new files to the end of existing chunks or creating new chunks if necessary.", + "description": "Manages the chunking of files based on file size, creating new chunks if the last one is full or appending to it otherwise.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Used to add a new file to the end of the chunked data." + "type_name": "StructuredFile", + "description": "Used to add new files to an array of chunks for processing." } ], "usage": { "language": "typescript", - "code": "const file = new StructuredFile(); // create a new instance of the StructuredFile class\nfile.addToEndOfChunks(documentStore); // add the newly created structured file to the end of the lookup subtable\n\nconst files = documentStore.lookup; // retrieve the lookup subtable\nfiles[files.length - 1].push(file); // push the new StructuredFile instance onto the last lookup subtable\n", + "code": "let docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfChunks(file);\n", "description": "" }, "name": "addToEndOfChunks", @@ -470,27 +470,27 @@ "docLength": 10 }, { - "id": "530e52e3-d6ff-42a9-8b46-5f614f73fe0a", + "id": "99e120cb-0aef-cdb1-ac46-ebae4d34daee", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Adds a file to the collection of files stored by the class, checking for file existence and proper loading state beforehand.", + "description": "Allows adding a file to the collection of documents, checking for file existence and properly updating the content array if successful.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Used to represent the file to be added to the content library." + "type_name": "StructuredFile", + "description": "Used to represent a file that needs to be added to the content manager's chunks or lookups." } ], "returns": { - "type_name": "boolean*", - "description": "1 when a file is successfully added to the content and 0 otherwise." + "type_name": "boolean", + "description": "True if the file was successfully added to the content array and false otherwise." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore();\nconst file1 = { path: \"path/to/file1\", content: \"This is file1\" };\nconst file2 = { path: \"path/to/file2\", content: \"This is file2\" };\n\ndocStore.addFile(file1); // Add the first file to the store\ndocStore.addFile(file2); // Add the second file to the store\n", + "code": "let documentStore = new DocumentStore({ getRemote, integration });\ndocumentStore.addFile(file); // where file is a StructuredFile object with path and content properties\n", "description": "" }, "name": "addFile", @@ -509,28 +509,28 @@ "docLength": 10 }, { - "id": "09495ab9-1694-4b84-3041-ccc54529be48", + "id": "422a10ed-1dce-62b3-584e-99e4d60678e0", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Updates a file in the store by checking if it exists, loading the appropriate chunk if necessary, and storing the updated file in the chunk.", + "description": "Updates a file in the store by checking its existence, loading it if necessary, and storing it in the correct chunk and index position.", "params": [ { "name": "file", "default_value": null, "optional": false, - "type_name": "StructuredFile*", - "description": "Used to update an existing file or add a new one." + "type_name": "StructuredFile", + "description": "Used to represent a file within the application's data structure. Its purpose is to provide a reference to the file that needs to be updated." } ], "returns": { - "type_name": "Promise*", - "description": "True if the file was successfully updated and false otherwise." + "type_name": "Promise", + "description": "Ether true or false depending on whether the file was successfully updated or not." }, "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\nconst file: StructuredFile = { path: \"path/to/file.txt\", contents: \"some contents\" };\ndocStore.updateFile(file)\n .then((result) => console.log(\"Result: \", result))\n .catch((error) => console.error(\"Error: \", error));\n", - "description": "\nThe code first creates an instance of the `DocumentStore` class using the constructor, passing in the `getRemote` and integration objects as parameters. Then it creates a `StructuredFile` object with some sample data, and then calls the `updateFile` method on the `docStore` object to update the file. The result is logged to the console." + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.updateFile(file); // file is a StructuredFile object that contains file metadata and content.\n", + "description": "\nThe updateFile method takes a single argument of type StructuredFile, which is a class that represents a file with metadata and content. It then updates the file in the DocumentStore's internal arrays and objects." }, "name": "updateFile", "location": { @@ -548,19 +548,19 @@ "docLength": 10 }, { - "id": "78888ed2-6aa7-14ad-0849-5199f8b542e2", + "id": "fc07d4eb-2680-abbe-ef48-d49763b88239", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Summarizes an object containing metadata and a lookup map, returning a new object with the same properties.", + "description": "Returns an object containing the `meta` and `lookup` properties, which are likely used to store and retrieve metadata and data for documents managed by the class.", "params": [], "returns": { - "type_name": "Summary*", + "type_name": "Summary", "description": "An object containing two properties: `meta` and `lookup`." }, "usage": { "language": "typescript", - "code": "let docStore = new DocumentStore(getRemote, integration);\ndocStore.outputSummary();\n", + "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote(/* params */);\ndocumentStore.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -579,20 +579,20 @@ "docLength": 6 }, { - "id": "47f09a8f-4254-bc99-df44-9765a3cb314c", + "id": "0e0d8eb1-bdf8-109f-7a4b-5956cfb16085", "ancestors": [ - "201361aa-202a-a4b0-474c-7245ff886fee" + "ee29f824-943b-c1b4-964f-bf43e6e55b2f" ], - "description": "Iterates through the document content, slicing it into chunks, and storing each chunk in a new key-value pair in an output object.", + "description": "Generates and returns an object containing chunks of the original document,keyed by their chunk paths.", "params": [], "returns": { - "type_name": "Record*", - "description": "An object mapping chunk keys to their corresponding chuncks." + "type_name": "Record", + "description": "An object containing chunk data." }, "usage": { "language": "typescript", - "code": "// Create instance of DocumentStore class\nconst documentStore = new DocumentStore(getRemote, integration);\n\n// Initialize DocumentStore with necessary parameters\ndocumentStore.init();\n\n// Get list of chunks\nconst chunkList = documentStore.outputChunks();\n\n// Iterate over chunks and retrieve content\nchunkList.forEach((chunk) => {\n const content = chunk.content;\n});\n", - "description": "\nThe code creates an instance of the `DocumentStore` class, passing in necessary parameters for initialization. It then calls the `init()` method to initialize the internal arrays and objects to store chunk data, content, and other meta information. Finally, it calls the `outputChunks()` method to get a list of chunks, which can be iterated over and used to retrieve the content for each chunk." + "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote = async () => {\n const response = await fetch('https://api.example.com/');\n return JSON.parse(response);\n};\nawait documentStore.initialize('integration_name', '1.0.0');\nconst chunks = documentStore.outputChunks();\n", + "description": "" }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index 3d3ca4c..d8349fe 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-12T05:26:53.330Z", + "updated_at": "2024-07-12T09:07:47.272Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -22,7 +22,8 @@ "bd56018a-a4ab-43de-aa64-a02ed61b32be", "344dea1f-37c5-4706-b964-90ffeed56096", "c355b024-a5e5-4eea-b745-fd2482d6e5c6", - "532c71df-781e-414b-98ad-8f67da7424a6" + "532c71df-781e-414b-98ad-8f67da7424a6", + "5c864a2d-0ee3-4c2e-8392-299b19565254" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 9274083..6db163a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,8 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Manages a collection of files and their contents, providing functions - * to add, update, and retrieve files for use in code generation. It also generates - * high-quality documentation and chunks of code based on the given content. + * @description Provides a centralized storage and management system for files, + * handling chunking, loading, and metadata for high-quality documentation generation. * * @implements {IDocumentStore} */ @@ -46,17 +45,18 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up instance variables for namespace, getRemote method, chunk - * size, and meta data. It also initializes lookup, chunks, content, and status objects. + * @description Sets up instance variables such as `CHUNK_SIZE`, `namespace`, + * `getRemote`, and `meta`, as well as initializing objects such as `lookup`, `chunks`, + * and `content`. * - * @param {string*} namespace - Required to identify the name space for the content - * being processed. + * @param {string} namespace - Required to identify the name of a specific data store, + * such as a database or file system, where the chunked data will be stored. * - * @param {(...args: any[]) => Promise>*} getRemote - Used to fetch - * remote data for chunking. + * @param {(...args: any[]) => Promise>} getRemote - Used to fetch + * data from a remote source, such as an API or database, and return it as a promise. * - * @param {Record*} additionalMeta - Used to provide additional metadata - * for the document store, such as version number or creation date. + * @param {Record} additionalMeta - Used to store additional metadata + * about the document that can be used for customization or tracking purposes. */ constructor( namespace: string, @@ -86,20 +86,18 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the instance variable `meta.updated_at` with the provided - * `Date` object, serving as a proxy for the document's last updated time. + * @description Updates the `updated_at` metadata field of the object, by setting it + * to the provided `Date` value. * - * @param {Date*} updated_at - Used to update the object's `meta` property with the - * current date time value, ensuring that the object's last updated timestamp remains - * up-to-date. + * @param {Date} updated_at - Used to update the `updated_at` metadata field of an entity. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates summary information from remote storage, merges - * it with local data, and stores it locally. + * @description Retrieves and updates a summary of documents stored in the store, + * including metadata and chunk information. */ loadSummary = async () => { let summary: Summary = { @@ -128,8 +126,8 @@ 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 `this.meta` with values from `summary.meta` or the original value of - // `value`, depending on the existence and value of `summary.meta`. + // Updates the `this.meta` object with values from `summary.meta` or the original + // value if `summary.meta` is null or undefined. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -138,8 +136,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Async loads chunks of data from a summary, setting `status.chunks` - * to `true` upon completion. + * @description Asyncily loads chunks of data from storage based on a provided list + * of chunk indices, setting the `chunks` property to `true` upon completion. */ load = async () => { if (!this.status.summary) { @@ -162,12 +160,12 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of an object by combining its current metadata - * with any additional metadata provided as an argument, resulting in a new, updated - * metadata object. + * @description Updates the metadata of the instance by combining its current metadata + * with additional metadata provided as an argument, assigning the resulting object + * to the `meta` property. * - * @param {Record*} additionalMeta - Used to update the `meta` property - * of an object by combining its current value with new metadata values.* + * @param {Record} additionalMeta - Used to provide additional metadata + * to update the existing metadata of the object. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -183,14 +181,12 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Asyncously checks if a given chunk has been loaded, loads it if not, - * and concats it with the content if successful. + * @description Asyncously checks if a chunk is loaded, retrieves it from the server + * if not, and appends it to the internal content and chunks arrays if successful. * - * @param {number*} chunkIndex - Used to represent the index of a particular chunk - * in the list of chunks. + * @param {number} chunkIndex - Used to identify the specific chunk being loaded. * - * @returns {Promise*} Resolved to true if the chunk was successfully loaded - * and false otherwise. + * @returns {Promise} True if the chunk was successfully loaded and false otherwise. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -209,14 +205,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from a summary data structure, calculating its chunk - * and file index within that chunk, and loading the chunk if necessary. + * @description Retrieves a file from the store based on its path, loading the necessary + * chunks and files if not already loaded. It returns the file or `null` if not found. * - * @param {string*} path - Used to represent the file path being searched for within - * the model's chunks. + * @param {string} path - Used to represent the file path that the function will check + * for existence and load if necessary. * - * @returns {Promise*} Either a StructuredFile object or null - * depending on the file's presence in the specified chunk and its loading status. + * @returns {Promise} A promise that resolves to a StructuredFile + * object or null if the file cannot be found in the specified chunk. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -259,11 +255,10 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new path to the end of the lookup subtable if it's full or if - * the last element in the subtable is at capacity. + * @description Adds a new document path to the end of an existing lookup subtable + * or creates a new table if the last one is full, preserving the chunk size. * - * @param {string*} path - Used to add new elements to the end of an internal array - * for storing substrings, which is the purpose of the function. + * @param {string} path - Used to add a new element to the end of the lookup subtable. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -277,11 +272,10 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Manages the chunking of files based on file size, adding new files - * to the end of existing chunks or creating new chunks if necessary. + * @description Manages the chunking of files based on file size, creating new chunks + * if the last one is full or appending to it otherwise. * - * @param {StructuredFile*} file - Used to add a new file to the end of the chunked - * data. + * @param {StructuredFile} file - Used to add new files to an array of chunks for processing. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -295,13 +289,14 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the collection of files stored by the class, checking - * for file existence and proper loading state beforehand. + * @description Allows adding a file to the collection of documents, checking for + * file existence and properly updating the content array if successful. * - * @param {StructuredFile*} file - Used to represent the file to be added to the - * content library. + * @param {StructuredFile} file - Used to represent a file that needs to be added to + * the content manager's chunks or lookups. * - * @returns {boolean*} 1 when a file is successfully added to the content and 0 otherwise. + * @returns {boolean} True if the file was successfully added to the content array + * and false otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -324,13 +319,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the store by checking if it exists, loading the - * appropriate chunk if necessary, and storing the updated file in the chunk. + * @description Updates a file in the store by checking its existence, loading it if + * necessary, and storing it in the correct chunk and index position. * - * @param {StructuredFile*} file - Used to update an existing file or add a new one. + * @param {StructuredFile} file - Used to represent a file within the application's + * data structure. Its purpose is to provide a reference to the file that needs to + * be updated. * - * @returns {Promise*} True if the file was successfully updated and false - * otherwise. + * @returns {Promise} Ether true or false depending on whether the file was + * successfully updated or not. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -360,10 +357,11 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Summarizes an object containing metadata and a lookup map, returning - * a new object with the same properties. + * @description Returns an object containing the `meta` and `lookup` properties, which + * are likely used to store and retrieve metadata and data for documents managed by + * the class. * - * @returns {Summary*} An object containing two properties: `meta` and `lookup`. + * @returns {Summary} An object containing two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -372,11 +370,10 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Iterates through the document content, slicing it into chunks, and - * storing each chunk in a new key-value pair in an output object. + * @description Generates and returns an object containing chunks of the original + * document,keyed by their chunk paths. * - * @returns {Record*} An object mapping chunk keys to their corresponding - * chuncks. + * @returns {Record} An object containing chunk data. */ outputChunks(): Record { const outputs: Record = {}; From 4183f9ab1a5074dbe9caaf4b72ed90d4408ab348 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Fri, 12 Jul 2024 13:13:13 +0000 Subject: [PATCH 27/30] Added comments to 15 functions across 1 file --- .komment/00000.json | 176 +++++++++++++++++++++--------------------- .komment/komment.json | 5 +- src/index.ts | 124 +++++++++++++++-------------- 3 files changed, 156 insertions(+), 149 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 7ee5d63..5bc2ce9 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 adding, retrieving, and updating documents in a specified namespace. It also provides methods for generating high-quality documentation and outputting chunks of code based on the given content. The class uses various packages such as `passing-api` and `highland` to perform its functions.", + "description": "A `DocumentStore` class for managing adding, retrieving, and updating documents in a specified folder. It includes functions for loading and summarizing documents, as well as methods for updating files and generating high-quality documentation. The code also uses various types and packages such as `PassType`, `GetRemote`, `StructuredFile`, and `Summarry`. Overall, the code provides a flexible and structured approach to managing and organizing documents.", "items": [ { - "id": "ee29f824-943b-c1b4-964f-bf43e6e55b2f", + "id": "b3dde4d0-0c04-e6b8-f94b-b717b02da80a", "ancestors": [], - "description": "Provides a centralized storage and management system for files, handling chunking, loading, and metadata for high-quality documentation generation.", + "description": "Stores and manages code documentation, providing an interface for loading, updating, and querying the content.", "interfaces": [ "IDocumentStore" ], @@ -19,12 +19,12 @@ { "name": "CHUNK_SIZE", "type_name": "number", - "description": "5, which represents the size of each chunk in bytes for storing and retrieving files from a remote store." + "description": "512 by default, which defines the size of each chunk in the code storage." }, { "name": "namespace", "type_name": "string", - "description": "A name or identifier for the document store, which can be used to refer to it from other parts of the code." + "description": "Required. It provides a unique identifier for the code document store, which is used to generate high-quality documentation." }, { "name": "meta", @@ -61,7 +61,7 @@ } ] }, - "description": "Used to store high-quality documentation-related metadata." + "description": "Used to store information about the document" }, { "name": "metaTemplate", @@ -74,22 +74,22 @@ "any" ] }, - "description": "Used to provide a template for generating high-quality documentation for code." + "description": "Used to provide information about the metadata of the document." }, { "name": "lookup", "type_name": "string[][]", - "description": "Used to store a list of sub-arrays, where each sub-array contains a chunk index and a file index within that chunk." + "description": "Used to store a list of file paths that correspond to chunks of code, keyed by chunk index." }, { "name": "chunks", "type_name": "StructuredFile[][]", - "description": "Used to store the chunks of content from the original code, allowing for efficient retrieval of files within a particular chunk." + "description": "Used to store chunks of content." }, { "name": "content", "type_name": "StructuredFile[]", - "description": "Used to store the contents of the documents." + "description": "Responsible for storing the contents of the document chunks in the internal array." }, { "name": "status", @@ -117,7 +117,7 @@ } ] }, - "description": "Used to store information about the status of the document store" + "description": "Used to track the state of the document store, including whether summary was last updated and whether chunks were loaded." } ], "name": "DocumentStore", @@ -133,38 +133,38 @@ "docLength": null }, { - "id": "e39b354b-a990-7492-9a47-9501729db645", + "id": "8708e7e0-9cfd-63bb-c744-97510241eaec", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Sets up instance variables such as `CHUNK_SIZE`, `namespace`, `getRemote`, and `meta`, as well as initializing objects such as `lookup`, `chunks`, and `content`.", + "description": "Sets up various properties and variables required to store and manage documents, including the namespace, getRemote method, meta data, and chunk-related parameters.", "params": [ { "name": "namespace", "type_name": "string", "optional": false, - "description": "Required to identify the name of a specific data store, such as a database or file system, where the chunked data will be stored.", + "description": "Required for the construction of the Document Store constructor. It represents the unique name or identifier of the document store, which can be used to differentiate it from other document stores in a given environment.", "default_value": null }, { "name": "getRemote", "type_name": "(...args: any[]) => Promise>", "optional": false, - "description": "Used to fetch data from a remote source, such as an API or database, and return it as a promise.", + "description": "Used to retrieve data remotely.", "default_value": null }, { "name": "additionalMeta", "type_name": "Record", "optional": true, - "description": "Used to store additional metadata about the document that can be used for customization or tracking purposes.", + "description": "Used to provide additional metadata for the document, such as version number or creation date.", "default_value": "{}" } ], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(\n \"example-namespace\",\n async (...args) => {\n // getRemote implementation goes here\n },\n {\n version: \"1.0.0\",\n created_at: new Date(),\n updated_at: new Date(),\n additionalMeta: {},\n }\n);\n", - "description": "\nThis code instantiates a DocumentStore object with the namespace \"example-namespace\" and provides an implementation for getRemote method. The additionalMeta parameter is an optional object that can be used to add additional metadata to the document store." + "code": "const namespace = \"my-namespace\";\nconst getRemoteMethod = async (...args) => { /* implementation of remote method */ };\nconst additionalMeta = { /* metadata object */ };\n\n// create a new instance of DocumentStore with the provided parameters\nconst documentStore = new DocumentStore(namespace, getRemoteMethod, additionalMeta);\n", + "description": "" }, "name": null, "location": { @@ -182,23 +182,23 @@ "docLength": 12 }, { - "id": "582c42b2-5c3c-beac-3548-cb27e24f1477", + "id": "b532784a-8bc4-34bd-b845-b66a3613aa9e", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Updates the `updated_at` metadata field of the object, by setting it to the provided `Date` value.", + "description": "Updates the `updated_at` metadata field of an object, by setting it to the provided `Date` value.", "params": [ { "name": "updated_at", "default_value": null, "optional": false, "type_name": "Date", - "description": "Used to update the `updated_at` metadata field of an entity." + "description": "Used to update the `updated_at` metadata of an object." } ], "usage": { "language": "typescript", - "code": "const store = new DocumentStore();\nstore.setUpdatedAt(new Date()); // Update the updated_at field with current time.\n", + "code": "// Initialize DocumentStore with remote function and integration object\nconst documentStore = new DocumentStore(getRemote, integration);\n\n// Set updated at time\ndocumentStore.setUpdatedAt(new Date());\n", "description": "" }, "name": "setUpdatedAt", @@ -217,15 +217,15 @@ "docLength": 7 }, { - "id": "74b63f05-a80a-bcb1-2c4b-b81d868bed7d", + "id": "47940390-1fbd-bea2-6840-795713d648e5", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Retrieves and updates a summary of documents stored in the store, including metadata and chunk information.", + "description": "Retrieves and updates the summary data for the documents stored in the local store, using remote information if available.", "params": [], "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\nawait documentStore.loadSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.loadSummary();\n", "description": "" }, "name": "loadSummary", @@ -244,12 +244,12 @@ "docLength": 4 }, { - "id": "9b4daeca-55a7-9192-c945-b8561c2df96c", + "id": "ad84e589-f4d3-dc8d-1945-6a28b1dade93", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f", - "74b63f05-a80a-bcb1-2c4b-b81d868bed7d" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a", + "47940390-1fbd-bea2-6840-795713d648e5" ], - "description": "Updates the `this.meta` object with values from `summary.meta` or the original value if `summary.meta` is null or undefined.", + "description": "Updates the `this.meta` object's property values based on \nthe `summary.meta` object and an optional default value.", "name": null, "location": { "start": 121, @@ -263,15 +263,15 @@ "docLength": null }, { - "id": "6a2161bc-1e90-17bc-aa44-ce1fb0b6a21c", + "id": "12f01fee-84ea-94bd-f242-d6aebf66a20f", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Asyncily loads chunks of data from storage based on a provided list of chunk indices, setting the `chunks` property to `true` upon completion.", + "description": "Retrieves and loads chunks of data from the storage, based on their indices, and sets the `chunks` property to `true`.", "params": [], "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\n\nawait docStore.load();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.load().then(() => {\n // Use the loaded content here\n});\n", "description": "" }, "name": "load", @@ -290,23 +290,23 @@ "docLength": 3 }, { - "id": "73fa576b-8ba0-f488-414c-07a1fa72c6e5", + "id": "3b5d1e3f-968d-ed95-9447-ca0dd7bd38cc", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Updates the metadata of the instance by combining its current metadata with additional metadata provided as an argument, assigning the resulting object to the `meta` property.", + "description": "Updates the metadata of an object by merging the existing metadata with additional metadata provided as an argument.", "params": [ { "name": "additionalMeta", "default_value": null, "optional": false, "type_name": "Record", - "description": "Used to provide additional metadata to update the existing metadata of the object." + "description": "Used to add or update metadata for the component." } ], "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.updateMetadata({ version: '1.0.0', created_at: Date.now() });\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.updateMetadata({ version: '1.0', created_at: new Date() });\n", "description": "" }, "name": "updateMetadata", @@ -322,27 +322,27 @@ "docLength": null }, { - "id": "0709d86a-5ad4-c5a8-a349-cd6516f040be", + "id": "bb016c57-6713-9b8c-7a41-2301a0fc173b", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Asyncously checks if a chunk is loaded, retrieves it from the server if not, and appends it to the internal content and chunks arrays if successful.", + "description": "Loads a chunk of the document from the server and adds it to the document's content and chunks array if successful.", "params": [ { "name": "chunkIndex", "default_value": null, "optional": false, "type_name": "number", - "description": "Used to identify the specific chunk being loaded." + "description": "Used to represent the index of the chunk being loaded, which serves as a reference for checking if the chunk has already been loaded or not." } ], "returns": { "type_name": "Promise", - "description": "True if the chunk was successfully loaded and false otherwise." + "description": "Resolved when the chunk is loaded successfully, and rejected when there is an error." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote = async (key) => {\n // do some magic to retrieve the data from a remote location\n};\nawait documentStore.loadChunk(0);\n", + "code": "const store = new DocumentStore(getRemote);\nconst chunkLoaded = await store.loadChunk(100);\n", "description": "" }, "name": "loadChunk", @@ -361,28 +361,28 @@ "docLength": 11 }, { - "id": "c8f89bf8-783d-0e93-f44f-372598c56e8c", + "id": "87a9bdaf-5b4c-3dbd-d24b-004065eab39a", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Retrieves a file from the store based on its path, loading the necessary chunks and files if not already loaded. It returns the file or `null` if not found.", + "description": "Retrieves a file from the store based on its path, checking if it is already loaded and returning it if found, or loading it if necessary.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string", - "description": "Used to represent the file path that the function will check for existence and load if necessary." + "description": "Used to represent the file path that needs to be retrieved." } ], "returns": { "type_name": "Promise", - "description": "A promise that resolves to a StructuredFile object or null if the file cannot be found in the specified chunk." + "description": "A promise that resolves to a StructuredFile object or null if the file is not found in the specified chunk." }, "usage": { "language": "typescript", - "code": "const getFile = async (path: string): Promise => {\n const store = new DocumentStore(getRemote, integration);\n // calling method getFile to access structured file\n await store.getFile('some/path'); \n}\n", - "description": "\nThis calls the `getFile` function of the `DocumentStore` class using the `getRemote` and `integration` methods. The `getFile` function then uses the `this` context to call other methods in the class such as `getChunkFileIsIn`, `isChunkLoaded`, `loadChunk`, `getFileIndexInChunk`, and `chunks`." + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.CHUNK_SIZE = 10;\ndocumentStore.namespace = 'example';\nawait documentStore.loadSummary();\nconst structuredFile = await documentStore.getFile('path/to/file');\n", + "description": "" }, "name": "getFile", "location": { @@ -400,23 +400,23 @@ "docLength": 10 }, { - "id": "0a32c675-0a38-6ea3-fc44-48093d5f2b1c", + "id": "881a598d-88b7-a19d-4242-87421a2ee841", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Adds a new document path to the end of an existing lookup subtable or creates a new table if the last one is full, preserving the chunk size.", + "description": "Updates the lookup subtable based on the provided path. If the last subtable is full, create a new one; otherwise, append the path to the existing subtable.", "params": [ { "name": "path", "default_value": null, "optional": false, "type_name": "string", - "description": "Used to add a new element to the end of the lookup subtable." + "description": "Intended to represent a path to add to the end of the lookup table." } ], "usage": { "language": "typescript", - "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfLookup(\"path/to/file\");\n", + "code": "const docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfLookup(\"path\");\n", "description": "" }, "name": "addToEndOfLookup", @@ -435,23 +435,23 @@ "docLength": 6 }, { - "id": "6a710976-4226-8098-5741-7cc047e44144", + "id": "5a49562b-8589-0c99-944e-e80e82717313", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Manages the chunking of files based on file size, creating new chunks if the last one is full or appending to it otherwise.", + "description": "Adds a new file to the end of an array of chunks if the last one is full or if the current chunk is not full, and pushes it to the appropriate position in the chunk array.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Used to add new files to an array of chunks for processing." + "description": "Passed to add a file to an array of files, called chunks, within a larger data structure." } ], "usage": { "language": "typescript", - "code": "let docStore = new DocumentStore(getRemote, integration);\ndocStore.addToEndOfChunks(file);\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\n// addToEndOfChunks(file)\ndocumentStore.addToEndOfChunks(structuredFile);\n\n", "description": "" }, "name": "addToEndOfChunks", @@ -470,27 +470,27 @@ "docLength": 10 }, { - "id": "99e120cb-0aef-cdb1-ac46-ebae4d34daee", + "id": "e9b6e47e-5590-5d85-b745-4c6cceae3657", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Allows adding a file to the collection of documents, checking for file existence and properly updating the content array if successful.", + "description": "Adds a file to the collection of stored files. It first checks if the `status.chunks` property is set and if the input file exists at its path. If so, it updates the file in the collection and returns `true`. Otherwise, it appends the file to the end of the lookup table and chunks list and returns `true`.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Used to represent a file that needs to be added to the content manager's chunks or lookups." + "description": "Used to represent a file that is being added to the content library." } ], "returns": { "type_name": "boolean", - "description": "True if the file was successfully added to the content array and false otherwise." + "description": "`true` if the file was successfully added to the content, and `false` otherwise." }, "usage": { "language": "typescript", - "code": "let documentStore = new DocumentStore({ getRemote, integration });\ndocumentStore.addFile(file); // where file is a StructuredFile object with path and content properties\n", + "code": "// Create new instance of DocumentStore\nconst documentStore = new DocumentStore(getRemote, integration);\n// Add file to store\ndocumentStore.addFile({\n path: \"path/to/file\",\n content: \"file content\"\n});\n// Update existing file in store\ndocumentStore.updateFile(\"existing-file\", {\n path: \"updated-file-path\",\n content: \"updated-file-content\"\n});\n", "description": "" }, "name": "addFile", @@ -509,28 +509,28 @@ "docLength": 10 }, { - "id": "422a10ed-1dce-62b3-584e-99e4d60678e0", + "id": "2b1d9107-8359-9abb-df42-c6b4e2ebf6ac", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Updates a file in the store by checking its existence, loading it if necessary, and storing it in the correct chunk and index position.", + "description": "Updates a file in the store by checking if it exists, loading it if necessary, and storing it in the appropriate chunk and index position.", "params": [ { "name": "file", "default_value": null, "optional": false, "type_name": "StructuredFile", - "description": "Used to represent a file within the application's data structure. Its purpose is to provide a reference to the file that needs to be updated." + "description": "Used to represent a file that needs to be updated or added to the content library." } ], "returns": { "type_name": "Promise", - "description": "Ether true or false depending on whether the file was successfully updated or not." + "description": "Whether the file was updated successfully or not." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.updateFile(file); // file is a StructuredFile object that contains file metadata and content.\n", - "description": "\nThe updateFile method takes a single argument of type StructuredFile, which is a class that represents a file with metadata and content. It then updates the file in the DocumentStore's internal arrays and objects." + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.updateFile({\n path: \"path/to/file\",\n content: \"New content\"\n});\n", + "description": "" }, "name": "updateFile", "location": { @@ -548,19 +548,19 @@ "docLength": 10 }, { - "id": "fc07d4eb-2680-abbe-ef48-d49763b88239", + "id": "d42d5f63-ba14-f592-9f49-57a104d8a3a5", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Returns an object containing the `meta` and `lookup` properties, which are likely used to store and retrieve metadata and data for documents managed by the class.", + "description": "Returns an object containing `meta` and `lookup` properties, which are presumably used to summarize or represent the contents of the document store.", "params": [], "returns": { "type_name": "Summary", - "description": "An object containing two properties: `meta` and `lookup`." + "description": "An object consisting of two properties: `meta` and `lookup`." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote(/* params */);\ndocumentStore.outputSummary();\n", + "code": "const documentStore = new DocumentStore(getRemote, integration);\ndocumentStore.outputSummary();\n", "description": "" }, "name": "outputSummary", @@ -579,20 +579,20 @@ "docLength": 6 }, { - "id": "0e0d8eb1-bdf8-109f-7a4b-5956cfb16085", + "id": "411bd430-23b2-c3b5-1048-a4206864644f", "ancestors": [ - "ee29f824-943b-c1b4-964f-bf43e6e55b2f" + "b3dde4d0-0c04-e6b8-f94b-b717b02da80a" ], - "description": "Generates and returns an object containing chunks of the original document,keyed by their chunk paths.", + "description": "Generates an object with chunk-related metadata and content for each chunk in the document. The method iterates through the document's content, slices it into chunks, and assigns a unique identifier to each chunk.", "params": [], "returns": { "type_name": "Record", - "description": "An object containing chunk data." + "description": "An object where each key is a chunk path and the corresponding value is the contents of that chunk." }, "usage": { "language": "typescript", - "code": "const documentStore = new DocumentStore();\ndocumentStore.getRemote = async () => {\n const response = await fetch('https://api.example.com/');\n return JSON.parse(response);\n};\nawait documentStore.initialize('integration_name', '1.0.0');\nconst chunks = documentStore.outputChunks();\n", - "description": "" + "code": "const docStore = new DocumentStore({getRemote, integration});\nconst outputChunks = docStore.outputChunks();\n// Do something with the chunked content\n", + "description": "\nThe end user can then use the `outputChunks()` method to get the chunks of the content in the document store and process them as needed. The method returns a record that contains an entry for each chunk, where the key is the path of the chunk and the value is the chunk itself." }, "name": "outputChunks", "location": { diff --git a/.komment/komment.json b/.komment/komment.json index d8349fe..3f27a5c 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-12T09:07:47.272Z", + "updated_at": "2024-07-12T13:13:07.524Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -23,7 +23,8 @@ "344dea1f-37c5-4706-b964-90ffeed56096", "c355b024-a5e5-4eea-b745-fd2482d6e5c6", "532c71df-781e-414b-98ad-8f67da7424a6", - "5c864a2d-0ee3-4c2e-8392-299b19565254" + "5c864a2d-0ee3-4c2e-8392-299b19565254", + "e47a1503-66d2-402a-a043-4b6b405c390f" ] }, "lookup": [ diff --git a/src/index.ts b/src/index.ts index 6db163a..7f97adb 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,8 +20,8 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Provides a centralized storage and management system for files, - * handling chunking, loading, and metadata for high-quality documentation generation. + * @description Stores and manages code documentation, providing an interface for + * loading, updating, and querying the content. * * @implements {IDocumentStore} */ @@ -45,18 +45,19 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up instance variables such as `CHUNK_SIZE`, `namespace`, - * `getRemote`, and `meta`, as well as initializing objects such as `lookup`, `chunks`, - * and `content`. + * @description Sets up various properties and variables required to store and manage + * documents, including the namespace, getRemote method, meta data, and chunk-related + * parameters. * - * @param {string} namespace - Required to identify the name of a specific data store, - * such as a database or file system, where the chunked data will be stored. + * @param {string} namespace - Required for the construction of the Document Store + * constructor. It represents the unique name or identifier of the document store, + * which can be used to differentiate it from other document stores in a given environment. * - * @param {(...args: any[]) => Promise>} getRemote - Used to fetch - * data from a remote source, such as an API or database, and return it as a promise. + * @param {(...args: any[]) => Promise>} getRemote - Used to retrieve + * data remotely. * - * @param {Record} additionalMeta - Used to store additional metadata - * about the document that can be used for customization or tracking purposes. + * @param {Record} additionalMeta - Used to provide additional metadata + * for the document, such as version number or creation date. */ constructor( namespace: string, @@ -86,18 +87,18 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of the object, by setting it + * @description Updates the `updated_at` metadata field of an object, by setting it * to the provided `Date` value. * - * @param {Date} updated_at - Used to update the `updated_at` metadata field of an entity. + * @param {Date} updated_at - Used to update the `updated_at` metadata of an object. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates a summary of documents stored in the store, - * including metadata and chunk information. + * @description Retrieves and updates the summary data for the documents stored in + * the local store, using remote information if available. */ loadSummary = async () => { let summary: Summary = { @@ -126,8 +127,8 @@ 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 the `this.meta` object with values from `summary.meta` or the original - // value if `summary.meta` is null or undefined. + // Updates the `this.meta` object's property values based on + // the `summary.meta` object and an optional default value. this.meta[key] = summary?.meta?.[key] ?? value; }); @@ -136,8 +137,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Asyncily loads chunks of data from storage based on a provided list - * of chunk indices, setting the `chunks` property to `true` upon completion. + * @description Retrieves and loads chunks of data from the storage, based on their + * indices, and sets the `chunks` property to `true`. */ load = async () => { if (!this.status.summary) { @@ -160,12 +161,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of the instance by combining its current metadata - * with additional metadata provided as an argument, assigning the resulting object - * to the `meta` property. + * @description Updates the metadata of an object by merging the existing metadata + * with additional metadata provided as an argument. * - * @param {Record} additionalMeta - Used to provide additional metadata - * to update the existing metadata of the object. + * @param {Record} additionalMeta - Used to add or update metadata for + * the component. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -181,12 +181,15 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Asyncously checks if a chunk is loaded, retrieves it from the server - * if not, and appends it to the internal content and chunks arrays if successful. + * @description Loads a chunk of the document from the server and adds it to the + * document's content and chunks array if successful. * - * @param {number} chunkIndex - Used to identify the specific chunk being loaded. + * @param {number} chunkIndex - Used to represent the index of the chunk being loaded, + * which serves as a reference for checking if the chunk has already been loaded or + * not. * - * @returns {Promise} True if the chunk was successfully loaded and false otherwise. + * @returns {Promise} Resolved when the chunk is loaded successfully, and + * rejected when there is an error. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -205,14 +208,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from the store based on its path, loading the necessary - * chunks and files if not already loaded. It returns the file or `null` if not found. + * @description Retrieves a file from the store based on its path, checking if it is + * already loaded and returning it if found, or loading it if necessary. * - * @param {string} path - Used to represent the file path that the function will check - * for existence and load if necessary. + * @param {string} path - Used to represent the file path that needs to be retrieved. * * @returns {Promise} A promise that resolves to a StructuredFile - * object or null if the file cannot be found in the specified chunk. + * object or null if the file is not found in the specified chunk. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -255,10 +257,11 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Adds a new document path to the end of an existing lookup subtable - * or creates a new table if the last one is full, preserving the chunk size. + * @description Updates the lookup subtable based on the provided path. If the last + * subtable is full, create a new one; otherwise, append the path to the existing subtable. * - * @param {string} path - Used to add a new element to the end of the lookup subtable. + * @param {string} path - Intended to represent a path to add to the end of the lookup + * table. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -272,10 +275,12 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Manages the chunking of files based on file size, creating new chunks - * if the last one is full or appending to it otherwise. + * @description Adds a new file to the end of an array of chunks if the last one is + * full or if the current chunk is not full, and pushes it to the appropriate position + * in the chunk array. * - * @param {StructuredFile} file - Used to add new files to an array of chunks for processing. + * @param {StructuredFile} file - Passed to add a file to an array of files, called + * chunks, within a larger data structure. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -289,14 +294,16 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Allows adding a file to the collection of documents, checking for - * file existence and properly updating the content array if successful. + * @description Adds a file to the collection of stored files. It first checks if the + * `status.chunks` property is set and if the input file exists at its path. If so, + * it updates the file in the collection and returns `true`. Otherwise, it appends + * the file to the end of the lookup table and chunks list and returns `true`. * - * @param {StructuredFile} file - Used to represent a file that needs to be added to - * the content manager's chunks or lookups. + * @param {StructuredFile} file - Used to represent a file that is being added to the + * content library. * - * @returns {boolean} True if the file was successfully added to the content array - * and false otherwise. + * @returns {boolean} `true` if the file was successfully added to the content, and + * `false` otherwise. */ addFile = (file: StructuredFile): boolean => { if (!this.status.chunks) throw Error("Must call .load before adding files"); @@ -319,15 +326,13 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the store by checking its existence, loading it if - * necessary, and storing it in the correct chunk and index position. + * @description Updates a file in the store by checking if it exists, loading it if + * necessary, and storing it in the appropriate chunk and index position. * - * @param {StructuredFile} file - Used to represent a file within the application's - * data structure. Its purpose is to provide a reference to the file that needs to - * be updated. + * @param {StructuredFile} file - Used to represent a file that needs to be updated + * or added to the content library. * - * @returns {Promise} Ether true or false depending on whether the file was - * successfully updated or not. + * @returns {Promise} Whether the file was updated successfully or not. */ updateFile = async (file: StructuredFile): Promise => { if (!this.status.chunks) @@ -357,11 +362,10 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing the `meta` and `lookup` properties, which - * are likely used to store and retrieve metadata and data for documents managed by - * the class. + * @description Returns an object containing `meta` and `lookup` properties, which + * are presumably used to summarize or represent the contents of the document store. * - * @returns {Summary} An object containing two properties: `meta` and `lookup`. + * @returns {Summary} An object consisting of two properties: `meta` and `lookup`. */ outputSummary(): Summary { return { @@ -370,10 +374,12 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Generates and returns an object containing chunks of the original - * document,keyed by their chunk paths. + * @description Generates an object with chunk-related metadata and content for each + * chunk in the document. The method iterates through the document's content, slices + * it into chunks, and assigns a unique identifier to each chunk. * - * @returns {Record} An object containing chunk data. + * @returns {Record} An object where each key is a chunk path and the + * corresponding value is the contents of that chunk. */ outputChunks(): Record { const outputs: Record = {}; From 2fb91f30f0c1a7ee3c5f6d40ada7983fe573069c Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Sun, 14 Jul 2024 22:28:17 +0000 Subject: [PATCH 28/30] Added comments to 1 function across 1 file --- .komment/00000.json | 6 +++--- .komment/komment.json | 5 +++-- types/Meta.d.ts | 5 +++-- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index 5bc2ce9..b377055 100644 --- a/.komment/00000.json +++ b/.komment/00000.json @@ -938,12 +938,12 @@ "path": "types/Meta.d.ts", "content": { "structured": { - "description": "An interface called `Meta` that represents a metadata object. The interface has four properties: `version`, `created_at`, `updated_at`, and an optional property with any type of value. The `version` property is a string representing the version number, the `created_at` and `updated_at` properties are Date objects representing the creation and last update time of the metadata object.", + "description": "An interface called `Meta` that represents a metadata object with properties for version, created date, updated date, and arbitrary key-value pairs. The interface uses type annotations to specify the types of each property, including dates and objects.", "items": [ { - "id": "ab4e3495-19b9-a8a0-7c4f-a600389893b7", + "id": "266813fd-c121-a8b2-4e45-53bac5206499", "ancestors": [], - "description": "Defines a set of properties that consist of a version, creation and update dates, and arbitrary data stored under key strings.", + "description": "Defines a data structure with four properties: `version`, `createdAt`, `updatedAt`, and an arbitrary key-value pair `[key: string]` where the value can be any type.", "name": "Meta", "location": { "start": 1, diff --git a/.komment/komment.json b/.komment/komment.json index 3f27a5c..1d145fc 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-12T13:13:07.524Z", + "updated_at": "2024-07-14T22:28:11.628Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -24,7 +24,8 @@ "c355b024-a5e5-4eea-b745-fd2482d6e5c6", "532c71df-781e-414b-98ad-8f67da7424a6", "5c864a2d-0ee3-4c2e-8392-299b19565254", - "e47a1503-66d2-402a-a043-4b6b405c390f" + "e47a1503-66d2-402a-a043-4b6b405c390f", + "8644b83e-a319-4f94-b5f8-b999ebf633bc" ] }, "lookup": [ diff --git a/types/Meta.d.ts b/types/Meta.d.ts index 2143c23..638fbc1 100644 --- a/types/Meta.d.ts +++ b/types/Meta.d.ts @@ -1,6 +1,7 @@ /** - * @description Defines a set of properties that consist of a version, creation and - * update dates, and arbitrary data stored under key strings. + * @description Defines a data structure with four properties: `version`, `createdAt`, + * `updatedAt`, and an arbitrary key-value pair `[key: string]` where the value can + * be any type. */ export interface Meta { version: string; From b917c236e5156c30f70702181cd767387e15d407 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Thu, 18 Jul 2024 13:08:21 +0000 Subject: [PATCH 29/30] Added comments to 1 function across 1 file --- .komment/00000.json | 6 +++--- .komment/komment.json | 5 +++-- types/Meta.d.ts | 8 +++++--- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/.komment/00000.json b/.komment/00000.json index b377055..5f6ff73 100644 --- a/.komment/00000.json +++ b/.komment/00000.json @@ -938,12 +938,12 @@ "path": "types/Meta.d.ts", "content": { "structured": { - "description": "An interface called `Meta` that represents a metadata object with properties for version, created date, updated date, and arbitrary key-value pairs. The interface uses type annotations to specify the types of each property, including dates and objects.", + "description": "An interface called `Meta` that represents a metadata object. The interface has four properties: `version`, `created_at`, `updated_at`, and `[key: string]: any`. The `version` property is a string, while the `created_at` and `updated_at` properties are Date objects. The `any` key allows for any type of value to be stored in the object.", "items": [ { - "id": "266813fd-c121-a8b2-4e45-53bac5206499", + "id": "1bc0b5a2-46e3-a68a-c040-e9d6b6976640", "ancestors": [], - "description": "Defines a data structure with four properties: `version`, `createdAt`, `updatedAt`, and an arbitrary key-value pair `[key: string]` where the value can be any type.", + "description": "Defines an object with four properties: `version`, `createdAt`, `updatedAt`, and `[key: string]`. The `version` property is of type `string`, while the `createdAt` and `updatedAt` properties are of type `Date`. The `[key: string]` property is akin to an empty array, allowing any type of value to be stored within it.", "name": "Meta", "location": { "start": 1, diff --git a/.komment/komment.json b/.komment/komment.json index 1d145fc..7d35b3a 100644 --- a/.komment/komment.json +++ b/.komment/komment.json @@ -1,7 +1,7 @@ { "meta": { "version": "1", - "updated_at": "2024-07-14T22:28:11.628Z", + "updated_at": "2024-07-18T13:08:15.703Z", "created_at": "2024-07-10T16:34:39.374Z", "pipelines": [ "c089e2e8-dd67-4bff-afef-c8f0f6b8a931", @@ -25,7 +25,8 @@ "532c71df-781e-414b-98ad-8f67da7424a6", "5c864a2d-0ee3-4c2e-8392-299b19565254", "e47a1503-66d2-402a-a043-4b6b405c390f", - "8644b83e-a319-4f94-b5f8-b999ebf633bc" + "8644b83e-a319-4f94-b5f8-b999ebf633bc", + "62f2bdd7-6e44-42b4-b522-4dce3d99e5aa" ] }, "lookup": [ diff --git a/types/Meta.d.ts b/types/Meta.d.ts index 638fbc1..61488b3 100644 --- a/types/Meta.d.ts +++ b/types/Meta.d.ts @@ -1,7 +1,9 @@ /** - * @description Defines a data structure with four properties: `version`, `createdAt`, - * `updatedAt`, and an arbitrary key-value pair `[key: string]` where the value can - * be any type. + * @description Defines an object with four properties: `version`, `createdAt`, + * `updatedAt`, and `[key: string]`. The `version` property is of type `string`, while + * the `createdAt` and `updatedAt` properties are of type `Date`. The `[key: string]` + * property is akin to an empty array, allowing any type of value to be stored within + * it. */ export interface Meta { version: string; From d01f87849dbc73ea3b3b502a6a5f100828765346 Mon Sep 17 00:00:00 2001 From: "komment-ai-beta[bot]" <146334705+komment-ai-beta[bot]@users.noreply.github.com> Date: Wed, 4 Sep 2024 11:00:38 +0000 Subject: [PATCH 30/30] Added comments to 15 items across 1 file --- src/index.ts | 172 +++++++++++++++++++++++++-------------------------- 1 file changed, 86 insertions(+), 86 deletions(-) diff --git a/src/index.ts b/src/index.ts index 7f97adb..b9f2b7a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,9 +20,10 @@ const CHUNK_SIZE = 40; const DOCUMENT_STORE_VERSION = "1"; /** - * @description Stores and manages code documentation, providing an interface for - * loading, updating, and querying the content. - * + * @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 { @@ -45,19 +46,17 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Sets up various properties and variables required to store and manage - * documents, including the namespace, getRemote method, meta data, and chunk-related - * parameters. - * - * @param {string} namespace - Required for the construction of the Document Store - * constructor. It represents the unique name or identifier of the document store, - * which can be used to differentiate it from other document stores in a given environment. - * - * @param {(...args: any[]) => Promise>} getRemote - Used to retrieve - * data remotely. - * - * @param {Record} additionalMeta - Used to provide additional metadata - * for the document, such as version number or creation date. + * @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 {string} namespace - Required. + * + * @param {(...args: any[]) => Promise>} getRemote - Responsible for + * fetching data remotely. + * + * @param {Record} additionalMeta - Used to store custom metadata. */ constructor( namespace: string, @@ -87,18 +86,20 @@ class DocumentStore implements IDocumentStore { } /** - * @description Updates the `updated_at` metadata field of an object, by setting it - * to the provided `Date` value. - * - * @param {Date} updated_at - Used to update the `updated_at` metadata of an object. + * @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 - Intended to update a timestamp value. */ setUpdatedAt = (updated_at: Date) => { this.meta.updated_at = updated_at; }; /** - * @description Retrieves and updates the summary data for the documents stored in - * the local store, using remote information if available. + * @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 = { @@ -127,9 +128,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]) => { - // Updates the `this.meta` object's property values based on - // the `summary.meta` object and an optional default value. - + // Updates meta values. this.meta[key] = summary?.meta?.[key] ?? value; }); this.lookup = summary.lookup || []; @@ -137,8 +136,8 @@ class DocumentStore implements IDocumentStore { }; /** - * @description Retrieves and loads chunks of data from the storage, based on their - * indices, and sets the `chunks` property to `true`. + * @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) { @@ -161,11 +160,11 @@ class DocumentStore implements IDocumentStore { `.${this.namespace}/${this.namespace}.json`; /** - * @description Updates the metadata of an object by merging the existing metadata - * with additional metadata provided as an argument. - * - * @param {Record} additionalMeta - Used to add or update metadata for - * the component. + * @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} additionalMeta - Used to update metadata with new values. */ updateMetadata = (additionalMeta: Record) => { this.meta = { @@ -181,15 +180,14 @@ class DocumentStore implements IDocumentStore { this.chunks[chunkIndex]?.length > 0; /** - * @description Loads a chunk of the document from the server and adds it to the - * document's content and chunks array if successful. - * - * @param {number} chunkIndex - Used to represent the index of the chunk being loaded, - * which serves as a reference for checking if the chunk has already been loaded or - * not. - * - * @returns {Promise} Resolved when the chunk is loaded successfully, and - * rejected when there is an error. + * @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 - Used to identify a specific chunk of data. + * + * @returns {Promise} A boolean indicating whether the chunk was loaded + * successfully or not. */ loadChunk = async (chunkIndex: number): Promise => { if (!this.isChunkLoaded(chunkIndex)) { @@ -208,13 +206,14 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Retrieves a file from the store based on its path, checking if it is - * already loaded and returning it if found, or loading it if necessary. - * - * @param {string} path - Used to represent the file path that needs to be retrieved. - * - * @returns {Promise} A promise that resolves to a StructuredFile - * object or null if the file is not 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 - Intended to identify the file to retrieve. + * + * @returns {Promise} A promise that resolves to either a + * StructuredFile object or null if the file is not found. */ getFile = async (path: string): Promise => { if (!this.status.summary) @@ -257,11 +256,11 @@ class DocumentStore implements IDocumentStore { this.lookup.findIndex((sub) => sub.includes(this.getFileHash(path))) > -1; /** - * @description Updates the lookup subtable based on the provided path. If the last - * subtable is full, create a new one; otherwise, append the path to the existing subtable. - * - * @param {string} path - Intended to represent a path to add to the end of the lookup - * table. + * @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 - Used to add to the lookup table. */ addToEndOfLookup = (path: string) => { // If the last lookup subtable is full, create a new one @@ -275,12 +274,11 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a new file to the end of an array of chunks if the last one is - * full or if the current chunk is not full, and pushes it to the appropriate position - * in the chunk array. - * - * @param {StructuredFile} file - Passed to add a file to an array of files, called - * chunks, within a larger data structure. + * @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 - A file to be added. */ addToEndOfChunks = (file: StructuredFile) => { // If the last lookup subtable is full, create a new one @@ -294,16 +292,13 @@ class DocumentStore implements IDocumentStore { } }; /** - * @description Adds a file to the collection of stored files. It first checks if the - * `status.chunks` property is set and if the input file exists at its path. If so, - * it updates the file in the collection and returns `true`. Otherwise, it appends - * the file to the end of the lookup table and chunks list and returns `true`. - * - * @param {StructuredFile} file - Used to represent a file that is being added to the - * content library. - * - * @returns {boolean} `true` if the file was successfully added to the content, and - * `false` otherwise. + * @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 - Required to add files. + * + * @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"); @@ -326,13 +321,15 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Updates a file in the store by checking if it exists, loading it if - * necessary, and storing it in the appropriate chunk and index position. - * - * @param {StructuredFile} file - Used to represent a file that needs to be updated - * or added to the content library. - * - * @returns {Promise} Whether the file was updated successfully or not. + * @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 {StructuredFile} file - Mandatory. + * + * @returns {Promise} 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 => { if (!this.status.chunks) @@ -362,10 +359,12 @@ class DocumentStore implements IDocumentStore { return true; }; /** - * @description Returns an object containing `meta` and `lookup` properties, which - * are presumably used to summarize or represent the contents of the document store. - * - * @returns {Summary} An object consisting of two properties: `meta` and `lookup`. + * @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 with two properties: meta and lookup. Both properties + * are references to existing objects, specifically this.meta and this.lookup. */ outputSummary(): Summary { return { @@ -374,12 +373,13 @@ class DocumentStore implements IDocumentStore { }; } /** - * @description Generates an object with chunk-related metadata and content for each - * chunk in the document. The method iterates through the document's content, slices - * it into chunks, and assigns a unique identifier to each chunk. - * - * @returns {Record} An object where each key is a chunk path and the - * corresponding value is the contents of that chunk. + * @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} 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 { const outputs: Record = {};