@donotdev/firebase 0.0.1

package/dist/shared/transform.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Firebase data transformation utilities
+ * @description Functions for converting data between Firebase and application formats. Handles timestamp conversion, data preparation, and transformation for Firestore operations.
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+import type { DateValue, FirestoreTimestamp } from '@donotdev/core';
+/**
+ * Create a client-safe version of the Timestamp creation
+ * This is a browser-compatible replacement for the Timestamp.fromDate() method
+ * @param date - The Date object to convert
+ * @returns A representation of the timestamp
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function createTimestamp(date: Date): FirestoreTimestamp;
+/**
+ * Converts a Date or ISO string to a Firestore Timestamp.
+ * @param date - The date to convert (string or Date)
+ * @returns The Firestore Timestamp
+ * @throws Error if the date is invalid
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function toTimestamp(date: string | Date): FirestoreTimestamp;
+/**
+ * Converts a DateValue to an ISO string.
+ * @param date - The date value to convert (Date, Timestamp, or ISO string)
+ * @returns The ISO string representation
+ * @throws Error if the date is invalid
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function firestoreToISOString(date: DateValue): string;
+/**
+ * Type guard to check if an object is a Firestore Timestamp
+ * @param value - The value to check
+ * @returns True if the value is a Firestore Timestamp
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function isTimestamp(value: any): value is FirestoreTimestamp;
+/**
+ * Recursively converts ISO date strings to Date objects for schema validation.
+ * Schema validation expects Date objects for timestamp fields, not ISO strings.
+ * @param data - The data to convert
+ * @returns The data with ISO strings converted to Date objects
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function convertISOStringsToDates<T = any>(data: T): T;
+/**
+ * Recursively transforms Firestore data by converting Timestamps to ISO strings.
+ * @param data - The data to transform
+ * @param includeDocumentIds - Whether to include document IDs from doc.id
+ * @returns The transformed data
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function transformFirestoreData<T = any>(data: T, includeDocumentIds?: boolean): T;
+/**
+ * Recursively prepares data for Firestore by converting ISO strings or Date objects to Timestamps.
+ * @param data - The data to prepare
+ * @param removeFields - Optional array of field names to remove
+ * @returns The prepared data
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function prepareForFirestore<T = any>(data: T, removeFields?: string[]): T;
+/**
+ * Creates a data diff between original and updated data for partial updates
+ * @param original - Original data
+ * @param updated - Updated data
+ * @returns Object containing only the changed fields and their new values
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function createFirestorePartialUpdate<T extends Record<string, any>>(original: T, updated: Partial<T>): Partial<T>;
+//# sourceMappingURL=transform.d.ts.map

package/dist/shared/transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../../src/shared/transform.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAKpE;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,kBAAkB,CAY9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,kBAAkB,CAyBnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAoC5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,kBAAkB,CASnE;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAoB5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,GAAG,EAC5C,IAAI,EAAE,CAAC,EACP,kBAAkB,GAAE,OAAe,GAClC,CAAC,CA0CH;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,GAAG,EACzC,IAAI,EAAE,CAAC,EACP,YAAY,GAAE,MAAM,EAAO,GAC1B,CAAC,CAiDH;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACxE,QAAQ,EAAE,CAAC,EACX,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAClB,OAAO,CAAC,CAAC,CAAC,CAsBZ"}

package/dist/shared/transform.js

@@ -0,0 +1 @@
+import{handleError as o}from"@donotdev/core";function s(e){return{seconds:Math.floor(e.getTime()/1e3),nanoseconds:e.getTime()%1e3*1e6,toDate:()=>new Date(e),toMillis:()=>e.getTime(),isEqual:t=>t.seconds===Math.floor(e.getTime()/1e3)&&t.nanoseconds===e.getTime()%1e3*1e6,valueOf:()=>`Timestamp(seconds=${Math.floor(e.getTime()/1e3)}, nanoseconds=${e.getTime()%1e3*1e6})`}}function c(e){try{if(typeof e=="string"){const t=new Date(e);if(isNaN(t.getTime()))throw o("Invalid date string format",{context:{value:e}});return s(t)}if(e instanceof Date){if(isNaN(e.getTime()))throw o("Invalid Date object",{context:{value:e}});return s(e)}throw o("Invalid date value type",{context:{valueType:typeof e}})}catch(t){throw o(t,"Failed to convert to Timestamp")}}function l(e){try{if(e instanceof Date){if(isNaN(e.getTime()))throw o("Invalid Date object",{context:{value:e}});return e.toISOString()}if(typeof e=="object"&&e!==null&&"toDate"in e&&typeof e.toDate=="function")return e.toDate().toISOString();if(typeof e=="string"){const t=new Date(e);if(isNaN(t.getTime()))throw o("Invalid date string format",{context:{value:e}});return t.toISOString()}throw o("Invalid date value type",{context:{valueType:typeof e}})}catch(t){throw o(t,"Failed to convert to ISO string")}}function y(e){return typeof e=="object"&&e!==null&&"toDate"in e&&typeof e.toDate=="function"&&"seconds"in e&&"nanoseconds"in e}function m(e){if(typeof e!="string"||!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(e))return!1;const r=new Date(e);return!isNaN(r.getTime())}function u(e){if(!e)return e;if(Array.isArray(e))return e.map(t=>u(t));if(typeof e=="string"&&m(e))return new Date(e);if(typeof e=="object"&&e!==null){const t={};for(const[r,n]of Object.entries(e))t[r]=u(n);return t}return e}function f(e,t=!1){if(!e)return e;if(t&&typeof e=="object"&&e!==null&&"id"in e&&"ref"in e&&"data"in e&&typeof e.data=="function"){const r=e,n=r.data();return{id:r.id,...f(n)}}if(Array.isArray(e))return e.map(r=>f(r));if(y(e))return l(e);if(typeof e=="object"&&e!==null){const r={};for(const[n,i]of Object.entries(e))r[n]=f(i);return r}return e}function p(e,t=[]){if(!e)return e;if(Array.isArray(e))return e.map(r=>p(r,t));if(typeof e=="string"&&/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/.test(e))try{return c(e)}catch{return e}if(e instanceof Date)try{return c(e)}catch{return e}if(typeof e=="object"&&e!==null){const r={};for(const[n,i]of Object.entries(e))t.includes(n)||(r[n]=p(i,t));return r}return e}function D(e,t){const r={};for(const[n,i]of Object.entries(t)){if(!(n in e)){r[n]=i;continue}JSON.stringify(e[n])!==JSON.stringify(i)&&(r[n]=i)}return{...r,updatedAt:new Date().toISOString()}}export{u as convertISOStringsToDates,D as createFirestorePartialUpdate,s as createTimestamp,l as firestoreToISOString,y as isTimestamp,p as prepareForFirestore,c as toTimestamp,f as transformFirestoreData};

package/dist/shared/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Firebase shared types
+ * @description Common type definitions for Firebase operations. Defines interfaces and types used across both client and server Firebase implementations for consistency and type safety.
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+/**
+ * Firebase configuration interface
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export interface FirebaseConfig {
+    apiKey: string;
+    authDomain: string;
+    projectId: string;
+    storageBucket?: string;
+    messagingSenderId?: string;
+    appId?: string;
+}
+/**
+ * Firebase services interface
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export interface FirebaseServices {
+    app: any | null;
+    auth: any | null;
+    firestore: any | null;
+    functions: any | null;
+    isDemoMode: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC;IAChB,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;IACjB,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;CACrB"}

package/dist/shared/utils.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Firebase utility functions
+ * @description Core utility functions for Firebase integration
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+import type { FirebaseCallOptions } from '@donotdev/core';
+/**
+ * Firebase Admin instance (not available in browser)
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare const admin: (() => never) | null;
+/**
+ * Get Firebase Admin Firestore instance (not available in browser)
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare const getAdminFirestore: () => never;
+/**
+ * Generate Firestore document ID (not available in browser)
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare const generateId: () => never;
+/**
+ * Creates an abort controller with timeout
+ * @param options Timeout and related options
+ * @returns AbortController with appropriate timeout
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function createAbortController(options?: FirebaseCallOptions): AbortController;
+/**
+ * Handles Firebase errors consistently using the central error handler
+ * @param error The original Firebase error
+ * @param context Optional context about the operation
+ * @returns An error handled through the central system
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function handleFirebaseError(error: any, context?: string): Error;
+/**
+ * Executes a Firebase operation with automatic retry for retryable errors
+ * @param operation Name of the operation for logging
+ * @param fn Function to execute
+ * @param options Options for retry behavior
+ * @returns Result of the operation
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+export declare function executeFirebaseOperation<T>(operation: string, fn: () => Promise<T>, options?: {
+    retry?: boolean;
+    maxRetries?: number;
+    retryDelay?: number;
+}): Promise<T>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/shared/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/shared/utils.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAsB1D;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,sBAAmD,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,aAEgB,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,aAEgB,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,eAAe,CAoCjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,KAAK,CAUvE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CAChB,GACL,OAAO,CAAC,CAAC,CAAC,CAoCZ"}

package/dist/shared/utils.js

@@ -0,0 +1 @@
+import{handleError as i}from"@donotdev/core";const s=typeof window<"u",a=e=>()=>{throw i(new Error(`Firebase Admin function '${e}' is not available in browser environments`),{userMessage:"This operation requires server-side Firebase access and cannot be used in the browser",severity:"error"})},w=s?null:a("admin"),y=a("getAdminFirestore"),x=a("generateId");function h(e){const t=new AbortController;let r;return e?.timeout&&(r=setTimeout(()=>{const n=new Error("Request timeout exceeded");t.abort(i(n,{userMessage:"The operation timed out",context:{timeoutMs:e.timeout,abortKey:e.abortKey},severity:"warning"}))},e.timeout)),e?.externalSignal&&e.externalSignal.addEventListener("abort",()=>{t.abort(e.externalSignal?.reason||"External abort")}),t.signal.addEventListener("abort",()=>{r!==void 0&&clearTimeout(r)}),t}function v(e,t){return i(e,{userMessage:t?`Error during ${t}: ${e.message||"An error occurred"}`:void 0,context:{operation:t}})}async function E(e,t,r={}){const{retry:n=!1,maxRetries:d=3,retryDelay:l=300}=r;let o=0;for(;;)try{return await t()}catch(u){if(o++,b(u)&&n&&o<=d){const c=l*Math.pow(2,o-1);await new Promise(m=>setTimeout(m,c));continue}throw i(u,{userMessage:`Firebase operation "${e}" failed`,context:{operation:e,attempt:o,maxRetries:d,options:r}})}}function b(e){const t=["permission-denied","invalid-argument","already-exists","not-found","unauthenticated"];return e&&e.name==="DoNotDevError"&&t.includes(e.code)?!1:e&&e.code?["unavailable","deadline","cancel","network","timeout","internal","resource","exhausted"].some(n=>e.code.toLowerCase().includes(n)):!0}export{w as admin,h as createAbortController,E as executeFirebaseOperation,x as generateId,y as getAdminFirestore,v as handleFirebaseError};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@donotdev/firebase",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "description": "Firebase utilities for DoNotDev",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    }
+  },
+  "scripts": {
+    "dev": "tsc --noEmit --watch --listFiles false --listEmittedFiles false",
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "valibot": "^1.2.0"
+  },
+  "peerDependencies": {
+    "@donotdev/core": "0.0.1",
+    "firebase": "^12.5.0",
+    "firebase-admin": "^13.6.0"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/donotdev/firebase.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "peerDependenciesMeta": {}
+}