@typicalday/firegraph 0.7.1 → 0.8.0

package/dist/chunk-6OQW5OKO.js

@@ -0,0 +1,110 @@
+// src/serialization.ts
+import { Timestamp, GeoPoint, FieldValue } from "@google-cloud/firestore";
+var SERIALIZATION_TAG = "__firegraph_ser__";
+var KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+var _docRefWarned = false;
+function isTaggedValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const tag = value[SERIALIZATION_TAG];
+  return typeof tag === "string" && KNOWN_TYPES.has(tag);
+}
+function isTimestamp(value) {
+  return value instanceof Timestamp;
+}
+function isGeoPoint(value) {
+  return value instanceof GeoPoint;
+}
+function isDocumentReference(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.path === "string" && v.firestore !== void 0 && typeof v.id === "string" && v.constructor?.name === "DocumentReference";
+}
+function isVectorValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return v.constructor?.name === "VectorValue" && Array.isArray(v._values);
+}
+function serializeFirestoreTypes(data) {
+  return serializeValue(data);
+}
+function serializeValue(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (isTimestamp(value)) {
+    return { [SERIALIZATION_TAG]: "Timestamp", seconds: value.seconds, nanoseconds: value.nanoseconds };
+  }
+  if (isGeoPoint(value)) {
+    return { [SERIALIZATION_TAG]: "GeoPoint", latitude: value.latitude, longitude: value.longitude };
+  }
+  if (isDocumentReference(value)) {
+    return { [SERIALIZATION_TAG]: "DocumentReference", path: value.path };
+  }
+  if (isVectorValue(value)) {
+    const v = value;
+    const values = typeof v.toArray === "function" ? v.toArray() : v._values;
+    return { [SERIALIZATION_TAG]: "VectorValue", values: [...values] };
+  }
+  if (Array.isArray(value)) {
+    return value.map(serializeValue);
+  }
+  const result = {};
+  for (const key of Object.keys(value)) {
+    result[key] = serializeValue(value[key]);
+  }
+  return result;
+}
+function deserializeFirestoreTypes(data, db) {
+  return deserializeValue(data, db);
+}
+function deserializeValue(value, db) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (isTimestamp(value) || isGeoPoint(value) || isDocumentReference(value) || isVectorValue(value)) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => deserializeValue(v, db));
+  }
+  const obj = value;
+  if (isTaggedValue(obj)) {
+    const tag = obj[SERIALIZATION_TAG];
+    switch (tag) {
+      case "Timestamp":
+        if (typeof obj.seconds !== "number" || typeof obj.nanoseconds !== "number") return obj;
+        return new Timestamp(obj.seconds, obj.nanoseconds);
+      case "GeoPoint":
+        if (typeof obj.latitude !== "number" || typeof obj.longitude !== "number") return obj;
+        return new GeoPoint(obj.latitude, obj.longitude);
+      case "VectorValue":
+        if (!Array.isArray(obj.values)) return obj;
+        return FieldValue.vector(obj.values);
+      case "DocumentReference":
+        if (typeof obj.path !== "string") return obj;
+        if (db) {
+          return db.doc(obj.path);
+        }
+        if (!_docRefWarned) {
+          _docRefWarned = true;
+          console.warn(
+            "[firegraph] DocumentReference encountered during migration deserialization but no Firestore instance available. The reference will remain as a tagged object with its path. Enable write-back for full reconstruction."
+          );
+        }
+        return obj;
+      default:
+        return obj;
+    }
+  }
+  const result = {};
+  for (const key of Object.keys(obj)) {
+    result[key] = deserializeValue(obj[key], db);
+  }
+  return result;
+}
+
+export {
+  SERIALIZATION_TAG,
+  isTaggedValue,
+  serializeFirestoreTypes,
+  deserializeFirestoreTypes
+};
+//# sourceMappingURL=chunk-6OQW5OKO.js.map

package/dist/chunk-6OQW5OKO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/serialization.ts"],"sourcesContent":["/**\n * Firestore-aware serialization for the sandbox migration pipeline.\n *\n * Firestore documents can contain special types (Timestamp, GeoPoint,\n * VectorValue, DocumentReference) that don't survive plain JSON\n * round-tripping. This module provides tagged serialization: Firestore\n * types are wrapped in tagged plain objects before JSON marshaling and\n * reconstructed after.\n *\n * Only used by the `defaultExecutor` sandbox path. Static migrations\n * (in-memory functions) receive raw Firestore objects directly.\n */\n\nimport { Timestamp, GeoPoint, FieldValue } from '@google-cloud/firestore';\nimport type { Firestore, DocumentReference } from '@google-cloud/firestore';\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/** Sentinel key used to tag serialized Firestore types. */\nexport const SERIALIZATION_TAG = '__firegraph_ser__' as const;\n\n/** Known discriminator values for tagged types. */\nconst KNOWN_TYPES = new Set(['Timestamp', 'GeoPoint', 'VectorValue', 'DocumentReference']);\n\n// One-time warning for DocumentReference deserialization without db\nlet _docRefWarned = false;\n\n// ---------------------------------------------------------------------------\n// Type guard\n// ---------------------------------------------------------------------------\n\n/** Check if a value is a tagged serialized Firestore type. */\nexport function isTaggedValue(value: unknown): boolean {\n  if (value === null || typeof value !== 'object') return false;\n  const tag = (value as Record<string, unknown>)[SERIALIZATION_TAG];\n  return typeof tag === 'string' && KNOWN_TYPES.has(tag);\n}\n\n// ---------------------------------------------------------------------------\n// Detection helpers\n// ---------------------------------------------------------------------------\n\nfunction isTimestamp(value: unknown): value is Timestamp {\n  return value instanceof Timestamp;\n}\n\nfunction isGeoPoint(value: unknown): value is GeoPoint {\n  return value instanceof GeoPoint;\n}\n\nfunction isDocumentReference(value: unknown): value is DocumentReference {\n  // Duck-type check: DocumentReference has path (string) and firestore properties\n  if (value === null || typeof value !== 'object') return false;\n  const v = value as Record<string, unknown>;\n  return (\n    typeof v.path === 'string' &&\n    v.firestore !== undefined &&\n    typeof v.id === 'string' &&\n    v.constructor?.name === 'DocumentReference'\n  );\n}\n\nfunction isVectorValue(value: unknown): boolean {\n  if (value === null || typeof value !== 'object') return false;\n  const v = value as Record<string, unknown>;\n  return (\n    v.constructor?.name === 'VectorValue' &&\n    Array.isArray((v as Record<string, unknown>)._values)\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Serialize\n// ---------------------------------------------------------------------------\n\n/**\n * Recursively walk a data object and replace Firestore types with tagged\n * plain objects suitable for JSON serialization.\n *\n * Returns a new object tree — the input is never mutated.\n */\nexport function serializeFirestoreTypes(\n  data: Record<string, unknown>,\n): Record<string, unknown> {\n  return serializeValue(data) as Record<string, unknown>;\n}\n\nfunction serializeValue(value: unknown): unknown {\n  // Primitives\n  if (value === null || value === undefined) return value;\n  if (typeof value !== 'object') return value;\n\n  // Firestore types (check before generic object/array)\n  if (isTimestamp(value)) {\n    return { [SERIALIZATION_TAG]: 'Timestamp', seconds: value.seconds, nanoseconds: value.nanoseconds };\n  }\n  if (isGeoPoint(value)) {\n    return { [SERIALIZATION_TAG]: 'GeoPoint', latitude: value.latitude, longitude: value.longitude };\n  }\n  if (isDocumentReference(value)) {\n    return { [SERIALIZATION_TAG]: 'DocumentReference', path: (value as DocumentReference).path };\n  }\n  if (isVectorValue(value)) {\n    // Prefer toArray() (public API) over _values (private internal property)\n    const v = value as Record<string, unknown>;\n    const values = typeof v.toArray === 'function'\n      ? (v.toArray as () => number[])()\n      : (v._values as number[]);\n    return { [SERIALIZATION_TAG]: 'VectorValue', values: [...values] };\n  }\n\n  // Arrays\n  if (Array.isArray(value)) {\n    return value.map(serializeValue);\n  }\n\n  // Plain objects — recurse\n  const result: Record<string, unknown> = {};\n  for (const key of Object.keys(value as Record<string, unknown>)) {\n    result[key] = serializeValue((value as Record<string, unknown>)[key]);\n  }\n  return result;\n}\n\n// ---------------------------------------------------------------------------\n// Deserialize\n// ---------------------------------------------------------------------------\n\n/**\n * Recursively walk a data object and reconstruct Firestore types from\n * tagged plain objects.\n *\n * @param data - The data to deserialize (typically from JSON.parse)\n * @param db - Optional Firestore instance for DocumentReference reconstruction.\n *   If not provided, tagged DocumentReferences are left as-is with a one-time warning.\n *\n * Returns a new object tree — the input is never mutated.\n */\nexport function deserializeFirestoreTypes(\n  data: Record<string, unknown>,\n  db?: Firestore,\n): Record<string, unknown> {\n  return deserializeValue(data, db) as Record<string, unknown>;\n}\n\nfunction deserializeValue(value: unknown, db?: Firestore): unknown {\n  if (value === null || value === undefined) return value;\n  if (typeof value !== 'object') return value;\n\n  // Short-circuit for values that are already real Firestore types.\n  // This makes deserializeFirestoreTypes idempotent — safe to call on data\n  // that has already been deserialized (e.g., write-back after defaultExecutor\n  // already reconstructed types, or static migrations that return raw types).\n  if (isTimestamp(value) || isGeoPoint(value) || isDocumentReference(value) || isVectorValue(value)) {\n    return value;\n  }\n\n  // Arrays\n  if (Array.isArray(value)) {\n    return value.map((v) => deserializeValue(v, db));\n  }\n\n  const obj = value as Record<string, unknown>;\n\n  // Check for tagged Firestore type\n  if (isTaggedValue(obj)) {\n    const tag = obj[SERIALIZATION_TAG] as string;\n\n    switch (tag) {\n      case 'Timestamp':\n        // Validate expected fields before reconstruction\n        if (typeof obj.seconds !== 'number' || typeof obj.nanoseconds !== 'number') return obj;\n        return new Timestamp(obj.seconds, obj.nanoseconds);\n\n      case 'GeoPoint':\n        if (typeof obj.latitude !== 'number' || typeof obj.longitude !== 'number') return obj;\n        return new GeoPoint(obj.latitude, obj.longitude);\n\n      case 'VectorValue':\n        if (!Array.isArray(obj.values)) return obj;\n        return FieldValue.vector(obj.values as number[]);\n\n      case 'DocumentReference':\n        if (typeof obj.path !== 'string') return obj;\n        if (db) {\n          return db.doc(obj.path);\n        }\n        // No db available — leave as tagged object with one-time warning\n        if (!_docRefWarned) {\n          _docRefWarned = true;\n          console.warn(\n            '[firegraph] DocumentReference encountered during migration deserialization ' +\n            'but no Firestore instance available. The reference will remain as a tagged ' +\n            'object with its path. Enable write-back for full reconstruction.',\n          );\n        }\n        return obj;\n\n      default:\n        // Unknown tag — leave as-is (forward compatibility)\n        return obj;\n    }\n  }\n\n  // Plain object — recurse\n  const result: Record<string, unknown> = {};\n  for (const key of Object.keys(obj)) {\n    result[key] = deserializeValue(obj[key], db);\n  }\n  return result;\n}\n"],"mappings":"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","names":[]}