@cocreate/firestore 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.2.0](https://github.com/CoCreate-app/CoCreate-firestore/compare/v1.1.0...v1.2.0) (2026-07-18)
+
+
+### Features
+
+* Update package.json description and keywords; refactor index.js to use ES modules ([1764e13](https://github.com/CoCreate-app/CoCreate-firestore/commit/1764e13f050671a8d2b55609bf118bcf9c510e17))
+
+# [1.1.0](https://github.com/CoCreate-app/CoCreate-firestore/compare/v1.0.0...v1.1.0) (2026-07-18)
+
+
+### Features
+
+* Enhance Firestore client connection handling and normalize storage URL usage ([a97f76b](https://github.com/CoCreate-app/CoCreate-firestore/commit/a97f76b0dde45697e24875af2436e3b53c3b5b8f))
+
 # 1.0.0 (2026-07-18)
 
 

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@cocreate/firestore",
-  "version": "1.0.0",
-  "description": "A simple firestore component in vanilla javascript. Easily configured using HTML5 data-attributes and/or JavaScript API.",
+  "version": "1.2.0",
+  "description": "Lightweight Google Cloud Firestore CRUD wrapper and multi-tenant state routing client for the CoCreate ecosystem.",
   "keywords": [
     "firestore",
-    "low-code",
-    "realtime",
-    "realtime-framework",
-    "collaboration",
-    "shared-editing",
-    "html5-framework",
-    "javascript-framework"
+    "firebase",
+    "google-cloud-firestore",
+    "nosql",
+    "crud-api",
+    "abstract-crud",
+    "database-abstraction",
+    "multi-tenant",
+    "multi-tenant-routing",
+    "realtime-sync",
+    "state-synchronization"
   ],
   "publishConfig": {
     "access": "public"
@@ -38,6 +41,6 @@
   "main": "./src/index.js",
   "dependencies": {
     "@cocreate/utils": "^1.44.0",
-    "firestore": "^7.5.0"
+    "@google-cloud/firestore": "^7.5.0"
   }
 }

package/src/index.js

@@ -1,37 +1,70 @@
-const { Firestore } = require("@google-cloud/firestore");
-const {
+/********************************************************************************
+ * Copyright (C) 2026 CoCreate and Contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ ********************************************************************************/
+
+import { Firestore } from "@google-cloud/firestore";
+import {
 	dotNotationToObject,
 	queryData,
 	searchData,
 	sortData,
 	isValidDate
-} = require("@cocreate/utils");
+} from "@cocreate/utils";
 
 const organizations = {};
 
 /**
  * Dynamically resolves or caches a long-lived Firestore database client connection.
  * Caches the connection promise to prevent duplicate authentication handshakes.
- * Normalizes custom credential protocols directly out of standard CoCreate storageUrls.
+ * Normalizes custom credential protocols directly out of standard CoCreate storageUrls or urls.
  */
 async function dbClient(data) {
-	if (data.storageUrl) {
+	const storageUrl = data.storageUrl || data.url;
+
+	if (storageUrl) {
 		if (!organizations[data.organization_id]) {
 			organizations[data.organization_id] = {};
 		}
 		try {
-			if (!organizations[data.organization_id][data.storageUrl]) {
+			if (!organizations[data.organization_id][storageUrl]) {
 				const connectionPromise = (async () => {
 					let config = {};
 
-					// Option A: The Credentials Path URL (e.g. firestore:///path/to/credentials.json)
-					if (data.storageUrl.startsWith("firestore:///")) {
-						const filePath = data.storageUrl.replace("firestore://", "");
+					// Option A: The Structured Credentials Object (Highly recommended)
+					if (typeof storageUrl === "object" && storageUrl !== null) {
+						const projectId = storageUrl.projectId || storageUrl.project_id;
+						const clientEmail = storageUrl.clientEmail || storageUrl.client_email;
+						const privateKey = storageUrl.privateKey || storageUrl.private_key;
+
+						config = {
+							projectId,
+							credentials: {
+								client_email: clientEmail,
+								private_key: privateKey ? privateKey.replace(/\\n/g, "\n") : undefined
+							}
+						};
+					}
+					// Option B: The Credentials Path URL (e.g. firestore:///path/to/credentials.json)
+					else if (typeof storageUrl === "string" && storageUrl.startsWith("firestore:///")) {
+						const filePath = storageUrl.replace("firestore://", "");
 						config = { keyFilename: filePath };
 					}
-					// Option B: Query Params Encoded URI (e.g. firestore://project-id?client_email=...&private_key=...)
-					else if (data.storageUrl.startsWith("firestore://")) {
-						const urlParsed = new URL(data.storageUrl);
+					// Option C: Query Params Encoded URI (e.g. firestore://project-id?client_email=...&private_key=...)
+					else if (typeof storageUrl === "string" && storageUrl.startsWith("firestore://")) {
+						const urlParsed = new URL(storageUrl);
 						const projectId = urlParsed.host || urlParsed.hostname;
 						const clientEmail = urlParsed.searchParams.get("client_email");
 						const privateKey = urlParsed.searchParams.get("private_key");
@@ -57,21 +90,21 @@ async function dbClient(data) {
 					return client;
 				})();
 
-				organizations[data.organization_id][data.storageUrl] = connectionPromise;
+				organizations[data.organization_id][storageUrl] = connectionPromise;
 			}
 
 			// Await connection resolution safely
-			return await organizations[data.organization_id][data.storageUrl];
+			return await organizations[data.organization_id][storageUrl];
 		} catch (error) {
 			console.error(
-				`${data.organization_id}: storageUrl ${data.storageUrl} failed to connect to Firestore`
+				`${data.organization_id}: Firestore failed to connect`
 			);
 			errorHandler(data, error);
 			return { status: false };
 		}
 	}
 
-	errorHandler(data, "missing StorageUrl");
+	errorHandler(data, "missing Firestore Connection URL/Credentials");
 	return;
 }
 
@@ -110,7 +143,7 @@ process.on("orgDeleted", (organization_id) => {
 /**
  * Universal router matching the standard CoCreate pipeline signature.
  */
-function send(data) {
+export function send(data) {
 	let [type, method] = data.method.split(".");
 	if (type === "database") return database(method, data);
 	if (type === "array") return array(method, data);
@@ -121,6 +154,7 @@ function send(data) {
  * "database" operations mapped to Firestore Databases.
  */
 function database(method, data) {
+	const storageName = data.storageName || data.provider || "firestore";
 	return new Promise(
 		async (resolve, reject) => {
 			let type = "database";
@@ -128,7 +162,7 @@ function database(method, data) {
 
 			try {
 				const db = await dbClient(data);
-				if (!db || db.status === false) return data;
+				if (!db || db.status === false) return resolve(data);
 
 				if (method === "read") {
 					// Firestore is serverless and generally operates on a single default schema database per context.
@@ -147,13 +181,13 @@ function database(method, data) {
 						if (isFilter) {
 							databaseArray.push({
 								database: dbObj,
-								storage: data.storageName
+								storage: storageName
 							});
 						}
 					} else {
 						databaseArray.push({
 							database: dbObj,
-							storage: data.storageName
+							storage: storageName
 						});
 					}
 					resolve(createData(data, databaseArray, type));
@@ -187,6 +221,7 @@ function database(method, data) {
  * "array" operations mapped to Firestore Collections.
  */
 function array(method, data) {
+	const storageName = data.storageName || data.provider || "firestore";
 	return new Promise(
 		async (resolve, reject) => {
 			let type = "array";
@@ -194,7 +229,7 @@ function array(method, data) {
 
 			try {
 				const db = await dbClient(data);
-				if (!db || db.status === false) return data;
+				if (!db || db.status === false) return resolve(data);
 
 				if (data.request) data.array = data.request;
 
@@ -220,14 +255,14 @@ function array(method, data) {
 									arrayArray.push({
 										name: col.id,
 										database,
-										storage: data.storageName
+										storage: storageName
 									});
 								}
 							} else {
 								arrayArray.push({
 									name: col.id,
 									database,
-									storage: data.storageName
+									storage: storageName
 								});
 							}
 						}
@@ -260,7 +295,7 @@ function array(method, data) {
 								arrayArray.push({
 									name: array,
 									database,
-									storage: data.storageName
+									storage: storageName
 								});
 
 								arraysLength -= 1;
@@ -295,7 +330,7 @@ function array(method, data) {
 										name: newName,
 										oldName: oldName,
 										database,
-										storage: data.storageName
+										storage: storageName
 									});
 
 									arraysLength -= 1;
@@ -319,7 +354,7 @@ function array(method, data) {
 									arrayArray.push({
 										name: array,
 										database,
-										storage: data.storageName
+										storage: storageName
 									});
 
 									arraysLength -= 1;
@@ -349,11 +384,12 @@ function array(method, data) {
  * "object" operations mapped to Firestore Documents.
  */
 function object(method, data) {
+	const storageName = data.storageName || data.provider || "firestore";
 	return new Promise(
 		async (resolve, reject) => {
 			try {
 				const db = await dbClient(data);
-				if (!db || db.status === false) return data;
+				if (!db || db.status === false) return resolve(data);
 
 				let type = "object";
 				let documents = [];
@@ -371,7 +407,7 @@ function object(method, data) {
 
 					for (let array of arrays) {
 						const reference = {
-							$storage: data.storageName,
+							$storage: storageName,
 							$database: database,
 							$array: array
 						};
@@ -396,7 +432,7 @@ function object(method, data) {
 							if (!Array.isArray($database)) $database = [data[type][i].$database];
 							if (!Array.isArray($array)) $array = [data[type][i].$array];
 
-							if (!$storage.includes(data.storageName)) $storage.push(data.storageName);
+							if (!$storage.includes(storageName)) $storage.push(storageName);
 							if (!$database.includes(database)) $database.push(database);
 							if (!$array.includes(array)) $array.push(array);
 
@@ -456,7 +492,6 @@ function object(method, data) {
 									queryRef = queryRef.limit(data.$filter.limit);
 								}
 								if (data.$filter && typeof data.$filter.index === "number") {
-									// Standard offset queries are supported but startAt is normally preferred in production
 									queryRef = queryRef.offset(data.$filter.index);
 								}
 
@@ -844,4 +879,4 @@ function errorHandler(data, error, database, array) {
 	}
 }
 
-module.exports = { send };
+export default { send };