Set method

__test__/unit/base/Naro.test.ts

@@ -304,3 +304,36 @@ test("writeToDisk, should write multiple collections to disk", async () => {
   });
 });
 
+test("set, should set a document in the users collection", async () => {
+  const db = new Naro(dbName);
+  const newDoc = await db.set(`users/999`, { name: "Jane Doe" });
+
+  expect(newDoc.id).toBe("999");
+  expect(newDoc.name).toBe("Jane Doe");
+  expect(newDoc.path).toBe("users/999");
+})
+
+test("set, should overwrite a document in the users collection", async () => {
+  const db = new Naro(dbName);
+  await db.set(`users/999`, { name: "Jane Doe" });
+  await db.set(`users/999`, { name: "John", age: 30 });
+
+  const doc = await db.get(`users/999`);
+
+  expect(doc.id).toBe("999");
+  expect(doc.name).toBe("John");
+  expect(doc.age).toBe(30);
+})
+
+test("set, should throw an error if trying to set a document with an invalid ID", async () => {
+  const db = new Naro(dbName);
+  await expect(async () => await db.set(`users/invalid/id`, { name: "Jane Doe" })).rejects.toThrowError();
+});
+
+test("set, should throw an error if trying to set a document with an invalid ID", async () => {
+  const db = new Naro(dbName);
+  await expect(async () => await db.set(`users/invalid/id/fake`, { name: "Jane Doe" })).rejects.toThrowError();
+});
+
+
+

docs/.vitepress/config.mts

@@ -48,6 +48,7 @@ export default defineConfig({
           { text: 'get', link: '/api-reference/get' },
           { text: 'getAll', link: '/api-reference/getAll' },
           { text: 'add', link: '/api-reference/add' },
+          { text: 'set', link: '/api-reference/set' },
           { text: 'update', link: '/api-reference/update' },
           { text: 'delete', link: '/api-reference/delete' },
           { text: 'populate', link: '/api-reference/populate' },

docs/api-reference/set.md

@@ -0,0 +1,32 @@
+# API reference
+
+## set
+
+Overwrite a document in the specified collection using the provided data.
+
+> [!IMPORTANT]
+> This method is particularly useful for customizing default NaroDB IDs. However, it should be used with caution as it
+> can be risky.
+
+### Parameters
+
+| Prop   | Type      | Description                                                                                |
+|--------|-----------|--------------------------------------------------------------------------------------------|
+| `path` | `string`  | The collection name where the data will be set.                                            |
+| `data` | `DocData` | The document data to set. <br/> Note: The `id` property is mandatory in the provided data. |
+
+### Returns
+
+- Returns a promise that resolves to the newly document: [NaroDocument](../types-reference/naro-document.md).
+
+## Example
+
+```js{17}
+const newDoc = await db.set("users", { 
+  id: "123",
+  name: "Jane Doe", age: 28 
+});
+
+console.log(newDoc);
+// Output: { id: "123", createdAt: 1696872345000, name: "Jane Doe", age: 28 }
+```

src/base/Naro.ts

@@ -78,6 +78,34 @@ export class Naro {
     return _.cloneDeep(newItem);
   }
 
+  /**
+   * Overwrite a document in the specified collection using the provided data.
+   *
+   * @param {string} path - The name of the collection to set the data in.
+   * @param {DocData} data - The data to be set as a document.
+   * @return {Promise<NaroDocument>} A promise that resolves to the newly set document.
+   *
+   * @example
+   * const db = new Naro("myDatabase");
+   *
+   * const updatedUser = await db.set("users", { id: "123", createdAt: Date.now(), name: "Jane Doe", age: 28 });
+   * console.log(updatedUser);
+   * // Output: { id: "123", createdAt: 1696872345000, name: "Jane Doe", age: 28 }
+   */
+  async set(path: string, data: DocData): Promise<NaroDocument> {
+    const { collectionName, collectionId, subCollectionName, subCollectionId } = NaroPath.validate(path);
+    if (!collectionId) throw new Error("Collection ID is required");
+    if (subCollectionName) throw new Error("Sub-collection is not supported in set method");
+    if (subCollectionId) throw new Error("Sub-collection ID is not supported in set method");
+    const collection = this.core.getCollection(collectionName);
+    const source = { path: `${collectionName}/${collectionId}`, createdAt: Date.now(), id: collectionId };
+    const newItem: NaroDocument = Object.assign(data, source);
+    const existingIndex = _.findIndex(collection, (item) => item.id === collectionId);
+    existingIndex !== -1 ? collection[existingIndex] = newItem : collection.push(newItem);
+    this.core.updateCollection(collectionName, collection);
+    return _.cloneDeep(newItem);
+  }
+
   /**
    * Retrieves all documents from a specified collection, optionally applying filters and limits,
    * and populates specified fields with referenced documents from other collections.