@blackcode_sa/metaestetics-api 1.6.13 → 1.6.15

package/src/utils/TIMESTAMPS.md

@@ -0,0 +1,176 @@
+# Timestamp Management Strategy
+
+## Problem Statement
+
+Firebase provides two different Timestamp implementations across its SDKs:
+
+1. **Client-side Timestamp**: `import { Timestamp } from 'firebase/firestore'`
+
+   - Used in client applications (web, mobile)
+   - Lives in the `firebase/firestore` package
+
+2. **Admin-side Timestamp**: `import * as admin from 'firebase-admin'; admin.firestore.Timestamp`
+   - Used in server-side code (Cloud Functions)
+   - Lives in the `firebase-admin` package
+
+These types are structurally similar but are different JavaScript classes, causing type conflicts when:
+
+- Data with client Timestamps is processed in admin code
+- Data with admin Timestamps is sent to client code
+- Shared type definitions across client and admin code
+
+## Solution: TimestampUtils
+
+We've created a central `TimestampUtils` class providing:
+
+1. Conversion utilities between admin and client Timestamps
+2. Best practices for timestamp handling
+3. Consistent patterns for timestamp operations
+
+## Usage Guidelines
+
+### 1. Type Definitions
+
+All shared type definitions (in `src/types/*`) should:
+
+- Import Timestamp from client SDK: `import { Timestamp } from 'firebase/firestore'`
+- Define fields using this client Timestamp: `timestamp: Timestamp`
+
+This ensures types are consumable by both client and admin code.
+
+### 2. Admin Code (Cloud Functions)
+
+When writing admin code that:
+
+- **Reads data from Firestore**: No conversion needed, as Firestore returns admin Timestamps
+- **Processes timestamps**: Use standard admin timestamp methods
+- **Writes data to shared types**: Convert admin → client using `TimestampUtils.adminToClient()`
+- **Creates server timestamps**: For fields created with `serverTimestamp()`, use Firebase Admin's version: `admin.firestore.FieldValue.serverTimestamp()`
+
+Example:
+
+```typescript
+import * as admin from "firebase-admin";
+import { TimestampUtils } from "../../utils/TimestampUtils";
+import { YourSharedType } from "../../types/shared";
+
+// In your admin service
+async function processAndUpdateData() {
+  const adminTsNow = admin.firestore.Timestamp.now();
+
+  // When populating a shared type that clients will use
+  const data: YourSharedType = {
+    // Convert admin timestamp to client timestamp
+    createdAt: TimestampUtils.adminToClient(adminTsNow),
+
+    // For server timestamps, use admin version
+    updatedAt: admin.firestore.FieldValue.serverTimestamp(),
+
+    // Other fields...
+  };
+
+  // When you need to process objects with nested timestamps
+  const objectWithNestedTimestamps = {
+    // Complex data from another source
+  };
+
+  // Convert all timestamps in the object from admin to client
+  const clientCompatible = TimestampUtils.convertObjectTimestampsAdminToClient(
+    objectWithNestedTimestamps
+  );
+}
+```
+
+### 3. Client Code (Web/Mobile Apps)
+
+Client code should:
+
+- Use `firebase/firestore` Timestamp when needed
+- No conversion is necessary for data returned by `getDocs()` or similar client SDK methods
+- For new timestamps, use `Timestamp.now()` or `Timestamp.fromDate()`
+
+### 4. Utility Functions
+
+The `TimestampUtils` class provides these key functions:
+
+- `adminToClient(adminTimestamp)`: Converts admin → client Timestamp
+- `clientToAdmin(clientTimestamp)`: Converts client → admin Timestamp
+- `nowAsClient()`: Creates current timestamp as client Timestamp
+- `dateToClientTimestamp(date)`: Converts Date → client Timestamp
+- `dateToAdminTimestamp(date)`: Converts Date → admin Timestamp
+- `convertObjectTimestampsAdminToClient(obj)`: Deep conversion of all timestamps in an object from admin → client
+- `convertObjectTimestampsClientToAdmin(obj)`: Deep conversion of all timestamps in an object from client → admin
+
+## Common Patterns
+
+### 1. Creating New Documents
+
+```typescript
+// In admin code
+const adminTimestamp = admin.firestore.Timestamp.now();
+const clientCompatibleTimestamp = TimestampUtils.adminToClient(adminTimestamp);
+
+const newDocument = {
+  id: "doc123",
+  createdAt: clientCompatibleTimestamp,
+  // For server-managed timestamps, use serverTimestamp()
+  updatedAt: admin.firestore.FieldValue.serverTimestamp(),
+};
+
+await docRef.set(newDocument);
+```
+
+### 2. Updating Fields in a Document
+
+```typescript
+// In admin code
+await docRef.update({
+  someField: "new value",
+  // For immediate timestamp, convert admin to client
+  processedAt: TimestampUtils.adminToClient(admin.firestore.Timestamp.now()),
+  // For server-managed timestamps, use serverTimestamp()
+  updatedAt: admin.firestore.FieldValue.serverTimestamp(),
+});
+```
+
+### 3. Processing Calendar Events
+
+Calendar events and date ranges should be consistently handled:
+
+```typescript
+// Calendar event time conversion
+const firestoreCompatibleEventTime = {
+  start: {
+    seconds: newEventTime.start.seconds,
+    nanoseconds: newEventTime.start.nanoseconds,
+  },
+  end: {
+    seconds: newEventTime.end.seconds,
+    nanoseconds: newEventTime.end.nanoseconds,
+  },
+};
+```
+
+## Edge Cases and Limitations
+
+1. **null/undefined Handling**: All utility methods handle null safely
+2. **Serialization**: If serializing for JSON, convert to ISO strings first
+3. **Performance**: The conversion is lightweight, but for large batches, process efficiently
+
+## Migration Strategy
+
+1. Identify timestamp usage in your code using static analysis or grep
+2. Replace direct timestamp conversions with TimestampUtils methods
+3. Update methods like:
+   - `adminTimestampToClientTimestamp` → `TimestampUtils.adminToClient`
+   - Direct creation of client timestamps → `TimestampUtils.nowAsClient`
+4. Test thoroughly after each change
+
+## Conclusion
+
+Following this strategy will:
+
+- Eliminate type errors between admin and client code
+- Provide consistent timestamp handling throughout the codebase
+- Minimize conversion bugs by centralizing conversion logic
+- Make it easier to onboard new developers to the codebase

package/src/utils/TimestampUtils.ts

@@ -0,0 +1,241 @@
+import * as admin from "firebase-admin";
+import { Timestamp as ClientTimestamp } from "firebase/firestore";
+
+/**
+ * Detect if we're running in a server environment (like Cloud Functions)
+ * or compiled for server usage
+ */
+const IS_SERVER_ENV =
+  process.env.NODE_ENV === "production" ||
+  process.env.FUNCTIONS_EMULATOR === "true" ||
+  process.env.FIREBASE_CONFIG !== undefined;
+
+/**
+ * Utilities for managing timestamps across client and server-side Firebase code.
+ * This module provides conversion functions to ensure timestamp compatibility
+ * between admin and client Firebase SDKs.
+ */
+export class TimestampUtils {
+  /**
+   * Flag to force server mode where admin timestamps are preserved
+   * This should be true in Cloud Functions environments
+   */
+  private static serverMode = IS_SERVER_ENV;
+
+  /**
+   * Enables server mode where admin timestamps are preserved when saving
+   * to Firestore via the admin SDK
+   */
+  static enableServerMode(): void {
+    this.serverMode = true;
+  }
+
+  /**
+   * Disables server mode - use this only for client-side or mixed environments
+   */
+  static disableServerMode(): void {
+    this.serverMode = false;
+  }
+
+  /**
+   * Converts an admin Firestore Timestamp to a client Firestore Timestamp
+   * In server mode, returns the original admin timestamp for storage consistency
+   *
+   * @param adminTimestamp - Admin SDK Timestamp (from firebase-admin)
+   * @returns A client SDK Timestamp (from firebase/firestore) with same seconds/nanoseconds,
+   *          or the original admin timestamp in server mode,
+   *          or null if input is null
+   */
+  static adminToClient(
+    adminTimestamp: admin.firestore.Timestamp | null
+  ): ClientTimestamp | admin.firestore.Timestamp | null {
+    if (!adminTimestamp) return null;
+
+    // In server mode (Cloud Functions), just return the admin timestamp
+    if (this.serverMode) {
+      return adminTimestamp;
+    }
+
+    // In client mode, convert to client timestamp
+    return new ClientTimestamp(
+      adminTimestamp.seconds,
+      adminTimestamp.nanoseconds
+    );
+  }
+
+  /**
+   * Converts a client Firestore Timestamp to an admin Firestore Timestamp
+   * @param clientTimestamp - Client SDK Timestamp (from firebase/firestore)
+   * @returns An admin SDK Timestamp (from firebase-admin) with same seconds/nanoseconds or null if input is null
+   */
+  static clientToAdmin(
+    clientTimestamp: ClientTimestamp | null
+  ): admin.firestore.Timestamp | null {
+    if (!clientTimestamp) return null;
+
+    return new admin.firestore.Timestamp(
+      clientTimestamp.seconds,
+      clientTimestamp.nanoseconds
+    );
+  }
+
+  /**
+   * Creates a timestamp for the current time in the appropriate format based on environment
+   * @returns A timestamp for the current time (admin timestamp in server mode, client in client mode)
+   */
+  static nowAsTimestamp(): admin.firestore.Timestamp | ClientTimestamp {
+    const now = admin.firestore.Timestamp.now();
+    // In server mode, return the admin timestamp directly
+    if (this.serverMode) {
+      return now;
+    }
+    // In client mode, convert to client timestamp
+    return this.adminToClient(now) as ClientTimestamp;
+  }
+
+  /**
+   * @deprecated Use nowAsTimestamp() instead for better cross-environment compatibility
+   */
+  static nowAsClient(): ClientTimestamp {
+    const now = admin.firestore.Timestamp.now();
+    return this.adminToClient(now) as ClientTimestamp;
+  }
+
+  /**
+   * Converts a Date object to a timestamp in the appropriate format based on environment
+   * @param date - JavaScript Date object
+   * @returns A timestamp (admin timestamp in server mode, client in client mode) or null if input is null
+   */
+  static dateToTimestamp(
+    date: Date | null
+  ): admin.firestore.Timestamp | ClientTimestamp | null {
+    if (!date) return null;
+
+    if (this.serverMode) {
+      return admin.firestore.Timestamp.fromDate(date);
+    }
+
+    return ClientTimestamp.fromDate(date);
+  }
+
+  /**
+   * @deprecated Use dateToTimestamp() instead for better cross-environment compatibility
+   */
+  static dateToClientTimestamp(date: Date | null): ClientTimestamp | null {
+    if (!date) return null;
+    return ClientTimestamp.fromDate(date);
+  }
+
+  /**
+   * @deprecated Use dateToTimestamp() instead for better cross-environment compatibility
+   */
+  static dateToAdminTimestamp(
+    date: Date | null
+  ): admin.firestore.Timestamp | null {
+    if (!date) return null;
+    return admin.firestore.Timestamp.fromDate(date);
+  }
+
+  /**
+   * Gets a server timestamp field value for use in create/update operations
+   * Works in both admin and client environments
+   */
+  static serverTimestamp(): admin.firestore.FieldValue | any {
+    if (this.serverMode) {
+      return admin.firestore.FieldValue.serverTimestamp();
+    }
+    // In client mode, we'd need to import from firebase/firestore
+    // This would be implemented for client environments
+    throw new Error("Server timestamp in client mode not implemented");
+  }
+
+  /**
+   * For objects with mixed timestamp types, ensures all timestamps are
+   * in the correct format for the current environment
+   */
+  static normalizeTimestamps<T>(obj: T): T {
+    if (!obj || typeof obj !== "object") {
+      return obj;
+    }
+
+    if (obj instanceof admin.firestore.Timestamp) {
+      return this.serverMode ? obj : (this.adminToClient(obj) as unknown as T);
+    }
+
+    if (obj instanceof ClientTimestamp && this.serverMode) {
+      return this.clientToAdmin(obj) as unknown as T;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.normalizeTimestamps(item)) as unknown as T;
+    }
+
+    const result = { ...obj } as any;
+
+    for (const key in result) {
+      if (Object.prototype.hasOwnProperty.call(result, key)) {
+        result[key] = this.normalizeTimestamps(result[key]);
+      }
+    }
+
+    return result as T;
+  }
+
+  /**
+   * @deprecated Use normalizeTimestamps() instead for better cross-environment compatibility
+   */
+  static convertObjectTimestampsAdminToClient<T>(obj: T): T {
+    if (!obj || typeof obj !== "object") {
+      return obj;
+    }
+
+    if (obj instanceof admin.firestore.Timestamp) {
+      return this.adminToClient(obj) as unknown as T;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) =>
+        this.convertObjectTimestampsAdminToClient(item)
+      ) as unknown as T;
+    }
+
+    const result = { ...obj } as any;
+
+    for (const key in result) {
+      if (Object.prototype.hasOwnProperty.call(result, key)) {
+        result[key] = this.convertObjectTimestampsAdminToClient(result[key]);
+      }
+    }
+
+    return result as T;
+  }
+
+  /**
+   * @deprecated Use normalizeTimestamps() instead for better cross-environment compatibility
+   */
+  static convertObjectTimestampsClientToAdmin<T>(obj: T): T {
+    if (!obj || typeof obj !== "object") {
+      return obj;
+    }
+
+    if (obj instanceof ClientTimestamp) {
+      return this.clientToAdmin(obj) as unknown as T;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) =>
+        this.convertObjectTimestampsClientToAdmin(item)
+      ) as unknown as T;
+    }
+
+    const result = { ...obj } as any;
+
+    for (const key in result) {
+      if (Object.prototype.hasOwnProperty.call(result, key)) {
+        result[key] = this.convertObjectTimestampsClientToAdmin(result[key]);
+      }
+    }
+
+    return result as T;
+  }
+}