update: release v2.4.0

dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@skeet-framework/firestore",
-    "version": "2.3.3",
+    "version": "2.4.0",
     "description": "Skeet Framework Plugin - Firestore",
     "main": "./dist/cjs/index.js",
     "module": "./dist/esm/index.js",

dist/cjs/src/index.d.ts

@@ -9,6 +9,7 @@ export {
   queryCollectionItems as query,
   updateCollectionItem as update,
   deleteCollectionItem as remove,
+  upsertCollectionItem as upsert,
 } from './lib'
 export type { QueryCondition } from './lib'
 export { Timestamp, FieldValue } from 'firebase/firestore'

dist/cjs/src/lib/getCollectionItem.d.ts

@@ -35,4 +35,4 @@ export declare const getCollectionItem: <T>(
   db: firestore.Firestore,
   collectionPath: string,
   docId: string
-) => Promise<T>
+) => Promise<T | null>

dist/cjs/src/lib/index.d.ts

@@ -8,3 +8,4 @@ export * from './addMultipleCollectionItems'
 export * from './queryCollectionItems'
 export * from './updateCollectionItem'
 export * from './deleteCollectionItem'
+export * from './upsertCollectionItem'

dist/cjs/src/lib/upsertCollectionItem.d.ts

@@ -0,0 +1,48 @@
+import { firestore } from 'firebase-admin'
+export type WithFieldValue<T> = {
+  [K in keyof T]: T[K] | firestore.FieldValue
+}
+/**
+ * Updates or inserts a document in the specified Firestore collection with the given data.
+ *
+ * @param db - The instance of the Firestore database to use.
+ * @param collectionPath - The path of the collection containing the document to be updated or inserted.
+ * @param docId - The ID of the document to be updated or inserted.
+ * @param params - The data to update or insert the document with.
+ *
+ * @returns A boolean indicating the success of the upsert operation.
+ *
+ * @throws Throws an exception with an error message if an error occurs.
+ *
+ * @example
+ * ```typescript
+ * import { firestore } from 'firebase-admin';
+ * import { upsert } from '@skeet-framework/firestore';
+ *
+ * const db = firestore();
+ * const upsertData: firestore.UpdateData<User> = {
+ *   age: 31
+ * };
+ *
+ * async function run() {
+ *   try {
+ *     const path = 'Users';
+ *     const docId = '123456'; // Assuming this ID exists in the Users collection.
+ *     const success = await upsert<User>(db, path, docId, upsertData);
+ *     if (success) {
+ *       console.log(`Document with ID ${docId} upserted successfully.`);
+ *     }
+ *   } catch (error) {
+ *     console.error(`Error upserting document: ${error}`);
+ *   }
+ * }
+ *
+ * run();
+ * ```
+ */
+export declare const upsertCollectionItem: <T extends firestore.DocumentData>(
+  db: firestore.Firestore,
+  collectionPath: string,
+  docId: string,
+  params: firestore.UpdateData<WithFieldValue<T>>
+) => Promise<boolean>

dist/cjs/src/lib/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = '2.3.3'
+export declare const VERSION = '2.4.0'