@typicalday/firegraph 0.12.0 → 0.13.0

package/dist/chunk-PAD7WFFU.js

@@ -0,0 +1,573 @@
+import {
+  NODE_RELATION,
+  computeEdgeDocId,
+  computeNodeDocId
+} from "./chunk-WRTFC5NG.js";
+import {
+  FiregraphError
+} from "./chunk-TK64DNVK.js";
+
+// src/bulk.ts
+var MAX_BATCH_SIZE = 500;
+var DEFAULT_MAX_RETRIES = 3;
+var BASE_DELAY_MS = 200;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function chunk(arr, size) {
+  const chunks = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+}
+async function bulkDeleteDocIds(db, collectionPath, docIds, options) {
+  if (docIds.length === 0) {
+    return { deleted: 0, batches: 0, errors: [] };
+  }
+  const batchSize = Math.min(options?.batchSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
+  const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const onProgress = options?.onProgress;
+  const chunks = chunk(docIds, batchSize);
+  const errors = [];
+  let deleted = 0;
+  let completedBatches = 0;
+  for (let i = 0; i < chunks.length; i++) {
+    const ids = chunks[i];
+    let committed = false;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const batch = db.batch();
+        const collectionRef = db.collection(collectionPath);
+        for (const id of ids) {
+          batch.delete(collectionRef.doc(id));
+        }
+        await batch.commit();
+        committed = true;
+        deleted += ids.length;
+        break;
+      } catch (err) {
+        if (attempt < maxRetries) {
+          const delay = BASE_DELAY_MS * Math.pow(2, attempt);
+          await sleep(delay);
+        } else {
+          errors.push({
+            batchIndex: i,
+            error: err instanceof Error ? err : new Error(String(err)),
+            operationCount: ids.length
+          });
+        }
+      }
+    }
+    if (committed) {
+      completedBatches++;
+    }
+    if (onProgress) {
+      onProgress({
+        completedBatches,
+        totalBatches: chunks.length,
+        deletedSoFar: deleted
+      });
+    }
+  }
+  return { deleted, batches: completedBatches, errors };
+}
+async function bulkRemoveEdges(db, collectionPath, reader, params, options) {
+  const effectiveParams = params.limit !== void 0 ? { ...params, allowCollectionScan: params.allowCollectionScan ?? true } : { ...params, limit: 0, allowCollectionScan: params.allowCollectionScan ?? true };
+  const edges = await reader.findEdges(effectiveParams);
+  const docIds = edges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
+  return bulkDeleteDocIds(db, collectionPath, docIds, options);
+}
+async function deleteSubcollectionsRecursive(db, collectionPath, docId, options) {
+  const docRef = db.collection(collectionPath).doc(docId);
+  const subcollections = await docRef.listCollections();
+  if (subcollections.length === 0) return { deleted: 0, errors: [] };
+  let totalDeleted = 0;
+  const allErrors = [];
+  const subOptions = options ? { batchSize: options.batchSize, maxRetries: options.maxRetries } : void 0;
+  for (const subCollRef of subcollections) {
+    const subCollPath = subCollRef.path;
+    const snapshot = await subCollRef.select().get();
+    const subDocIds = snapshot.docs.map((d) => d.id);
+    for (const subDocId of subDocIds) {
+      const subResult = await deleteSubcollectionsRecursive(db, subCollPath, subDocId, subOptions);
+      totalDeleted += subResult.deleted;
+      allErrors.push(...subResult.errors);
+    }
+    if (subDocIds.length > 0) {
+      const result = await bulkDeleteDocIds(db, subCollPath, subDocIds, subOptions);
+      totalDeleted += result.deleted;
+      allErrors.push(...result.errors);
+    }
+  }
+  return { deleted: totalDeleted, errors: allErrors };
+}
+async function removeNodeCascade(db, collectionPath, reader, uid, options) {
+  const [outgoingRaw, incomingRaw] = await Promise.all([
+    reader.findEdges({ aUid: uid, allowCollectionScan: true, limit: 0 }),
+    reader.findEdges({ bUid: uid, allowCollectionScan: true, limit: 0 })
+  ]);
+  const outgoing = outgoingRaw.filter((e) => e.axbType !== NODE_RELATION);
+  const incoming = incomingRaw.filter((e) => e.axbType !== NODE_RELATION);
+  const edgeDocIdSet = /* @__PURE__ */ new Set();
+  const allEdges = [];
+  for (const edge of [...outgoing, ...incoming]) {
+    const docId = computeEdgeDocId(edge.aUid, edge.axbType, edge.bUid);
+    if (!edgeDocIdSet.has(docId)) {
+      edgeDocIdSet.add(docId);
+      allEdges.push(edge);
+    }
+  }
+  const shouldDeleteSubcollections = options?.deleteSubcollections !== false;
+  const nodeDocId = computeNodeDocId(uid);
+  let subcollectionResult = { deleted: 0, errors: [] };
+  if (shouldDeleteSubcollections) {
+    subcollectionResult = await deleteSubcollectionsRecursive(
+      db,
+      collectionPath,
+      nodeDocId,
+      options
+    );
+  }
+  const edgeDocIds = allEdges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
+  const allDocIds = [...edgeDocIds, nodeDocId];
+  const batchSize = Math.min(options?.batchSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
+  const result = await bulkDeleteDocIds(db, collectionPath, allDocIds, {
+    ...options,
+    batchSize
+  });
+  const totalChunks = Math.ceil(allDocIds.length / batchSize);
+  const nodeChunkIndex = totalChunks - 1;
+  const nodeDeleted = !result.errors.some((e) => e.batchIndex === nodeChunkIndex);
+  const topLevelEdgesDeleted = nodeDeleted ? result.deleted - 1 : result.deleted;
+  return {
+    deleted: result.deleted + subcollectionResult.deleted,
+    batches: result.batches,
+    errors: [...result.errors, ...subcollectionResult.errors],
+    edgesDeleted: topLevelEdgesDeleted,
+    nodeDeleted
+  };
+}
+
+// src/internal/firestore-aggregate.ts
+import { AggregateField } from "@google-cloud/firestore";
+function applyFiltersToQuery(base, filters) {
+  let q = base;
+  for (const f of filters) {
+    q = q.where(f.field, f.op, f.value);
+  }
+  return q;
+}
+async function runFirestoreAggregate(base, spec, filters, { edition }) {
+  if (Object.keys(spec).length === 0) {
+    throw new FiregraphError(
+      "aggregate() requires at least one aggregation in the `aggregates` map.",
+      "INVALID_QUERY"
+    );
+  }
+  const filtered = applyFiltersToQuery(base, filters);
+  const aggregations = {};
+  for (const [alias, { op, field }] of Object.entries(spec)) {
+    if (op === "count") {
+      if (field !== void 0) {
+        throw new FiregraphError(
+          `Aggregate '${alias}' op 'count' must not specify a field \u2014 count operates on rows, not a column expression.`,
+          "INVALID_QUERY"
+        );
+      }
+      aggregations[alias] = AggregateField.count();
+      continue;
+    }
+    if (!field) {
+      throw new FiregraphError(
+        `Aggregate '${alias}' op '${op}' requires a field.`,
+        "INVALID_QUERY"
+      );
+    }
+    if (op === "sum") {
+      aggregations[alias] = AggregateField.sum(field);
+    } else if (op === "avg") {
+      aggregations[alias] = AggregateField.average(field);
+    } else {
+      const editionLabel = edition === "enterprise" ? "Firestore Enterprise" : "Firestore Standard";
+      throw new FiregraphError(
+        `Aggregate op '${op}' is not supported on ${editionLabel}. Both Firestore editions support count/sum/avg via the classic Query API; min/max requires a backend with SQL aggregation (SQLite or DO).`,
+        "UNSUPPORTED_AGGREGATE"
+      );
+    }
+  }
+  const snap = await filtered.aggregate(aggregations).get();
+  const data = snap.data();
+  const out = {};
+  for (const alias of Object.keys(spec)) {
+    const v = data[alias];
+    if (v === null || v === void 0) {
+      const op = spec[alias].op;
+      out[alias] = op === "avg" ? Number.NaN : 0;
+    } else {
+      out[alias] = v;
+    }
+  }
+  return out;
+}
+
+// src/internal/firestore-classic-adapter.ts
+function createFirestoreAdapter(db, collectionPath) {
+  const collectionRef = db.collection(collectionPath);
+  return {
+    collectionPath,
+    async getDoc(docId) {
+      const snap = await collectionRef.doc(docId).get();
+      if (!snap.exists) return null;
+      return snap.data();
+    },
+    async setDoc(docId, data, options) {
+      if (options?.merge) {
+        await collectionRef.doc(docId).set(data, { merge: true });
+      } else {
+        await collectionRef.doc(docId).set(data);
+      }
+    },
+    async updateDoc(docId, data) {
+      await collectionRef.doc(docId).update(data);
+    },
+    async deleteDoc(docId) {
+      await collectionRef.doc(docId).delete();
+    },
+    async query(filters, options) {
+      let q = collectionRef;
+      for (const f of filters) {
+        q = q.where(f.field, f.op, f.value);
+      }
+      if (options?.orderBy) {
+        q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
+      }
+      if (options?.limit !== void 0) {
+        q = q.limit(options.limit);
+      }
+      const snap = await q.get();
+      return snap.docs.map((doc) => doc.data());
+    }
+  };
+}
+function createTransactionAdapter(db, collectionPath, tx) {
+  const collectionRef = db.collection(collectionPath);
+  return {
+    async getDoc(docId) {
+      const snap = await tx.get(collectionRef.doc(docId));
+      if (!snap.exists) return null;
+      return snap.data();
+    },
+    setDoc(docId, data, options) {
+      if (options?.merge) {
+        tx.set(collectionRef.doc(docId), data, { merge: true });
+      } else {
+        tx.set(collectionRef.doc(docId), data);
+      }
+    },
+    updateDoc(docId, data) {
+      tx.update(collectionRef.doc(docId), data);
+    },
+    deleteDoc(docId) {
+      tx.delete(collectionRef.doc(docId));
+    },
+    async query(filters, options) {
+      let q = collectionRef;
+      for (const f of filters) {
+        q = q.where(f.field, f.op, f.value);
+      }
+      if (options?.orderBy) {
+        q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
+      }
+      if (options?.limit !== void 0) {
+        q = q.limit(options.limit);
+      }
+      const snap = await tx.get(q);
+      return snap.docs.map((doc) => doc.data());
+    }
+  };
+}
+function createBatchAdapter(db, collectionPath) {
+  const collectionRef = db.collection(collectionPath);
+  const batch = db.batch();
+  return {
+    setDoc(docId, data, options) {
+      if (options?.merge) {
+        batch.set(collectionRef.doc(docId), data, { merge: true });
+      } else {
+        batch.set(collectionRef.doc(docId), data);
+      }
+    },
+    updateDoc(docId, data) {
+      batch.update(collectionRef.doc(docId), data);
+    },
+    deleteDoc(docId) {
+      batch.delete(collectionRef.doc(docId));
+    },
+    async commit() {
+      await batch.commit();
+    }
+  };
+}
+
+// src/internal/firestore-classic-expand.ts
+var FIRESTORE_CLASSIC_IN_CHUNK_SIZE = 30;
+function readField(record, path) {
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  let cursor = record;
+  for (const seg of path.split(".")) {
+    if (cursor === null || typeof cursor !== "object") return void 0;
+    cursor = cursor[seg];
+  }
+  return cursor;
+}
+function compareFieldValues(a, b) {
+  if (a === b) return 0;
+  if (a === void 0 || a === null) return -1;
+  if (b === void 0 || b === null) return 1;
+  const ta = typeof a;
+  const tb = typeof b;
+  if (ta === tb) {
+    return a < b ? -1 : 1;
+  }
+  const sa = String(a);
+  const sb = String(b);
+  return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+async function runFirestoreClassicExpand(adapter, params) {
+  if (params.sources.length === 0) {
+    return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+  }
+  if (params.axbType.length === 0) {
+    throw new FiregraphError("expand(): axbType must be a non-empty string.", "INVALID_QUERY");
+  }
+  const direction = params.direction ?? "forward";
+  const sourceField = direction === "forward" ? "aUid" : "bUid";
+  const chunks = chunkUids(params.sources, FIRESTORE_CLASSIC_IN_CHUNK_SIZE);
+  const totalLimit = params.limitPerSource !== void 0 ? params.sources.length * params.limitPerSource : void 0;
+  const buildFilters = (chunk2) => {
+    const filters = [
+      { field: "axbType", op: "==", value: params.axbType },
+      { field: sourceField, op: "in", value: chunk2 }
+    ];
+    if (params.aType !== void 0) {
+      filters.push({ field: "aType", op: "==", value: params.aType });
+    }
+    if (params.bType !== void 0) {
+      filters.push({ field: "bType", op: "==", value: params.bType });
+    }
+    return filters;
+  };
+  const buildOptions = (chunk2) => {
+    const opts = {};
+    if (params.orderBy) opts.orderBy = params.orderBy;
+    if (params.limitPerSource !== void 0) {
+      opts.limit = chunk2.length * params.limitPerSource;
+    }
+    return opts;
+  };
+  const chunkResults = await Promise.all(
+    chunks.map((chunk2) => adapter.query(buildFilters(chunk2), buildOptions(chunk2)))
+  );
+  let edges = chunkResults.flat();
+  if (params.axbType === NODE_RELATION) {
+    edges = edges.filter((e) => e.aUid !== e.bUid);
+  }
+  if (params.orderBy) {
+    const sortField = params.orderBy.field;
+    const dir = params.orderBy.direction ?? "asc";
+    edges.sort((a, b) => {
+      const cmp = compareFieldValues(readField(a, sortField), readField(b, sortField));
+      return dir === "asc" ? cmp : -cmp;
+    });
+  }
+  if (totalLimit !== void 0 && edges.length > totalLimit) {
+    edges = edges.slice(0, totalLimit);
+  }
+  if (!params.hydrate) return { edges };
+  const targetUids = edges.map((e) => direction === "forward" ? e.bUid : e.aUid);
+  const uniqueTargets = [...new Set(targetUids)];
+  if (uniqueTargets.length === 0) {
+    return { edges, targets: [] };
+  }
+  const hydrateChunks = chunkUids(uniqueTargets, FIRESTORE_CLASSIC_IN_CHUNK_SIZE);
+  const hydrateResults = await Promise.all(
+    hydrateChunks.map(
+      (chunk2) => adapter.query([
+        { field: "axbType", op: "==", value: NODE_RELATION },
+        { field: "aUid", op: "in", value: chunk2 }
+      ])
+    )
+  );
+  const byUid = /* @__PURE__ */ new Map();
+  for (const row of hydrateResults.flat()) {
+    byUid.set(row.bUid, row);
+  }
+  const targets = targetUids.map((uid) => byUid.get(uid) ?? null);
+  return { edges, targets };
+}
+function chunkUids(uids, chunkSize) {
+  if (chunkSize <= 0) {
+    throw new FiregraphError(
+      `chunkUids: chunkSize must be positive (got ${chunkSize}).`,
+      "INVALID_QUERY"
+    );
+  }
+  const out = [];
+  for (let i = 0; i < uids.length; i += chunkSize) {
+    out.push(uids.slice(i, i + chunkSize));
+  }
+  return out;
+}
+
+// src/internal/projection.ts
+var PROJECTION_BUILTIN_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeFirestoreProjectionField(field) {
+  if (PROJECTION_BUILTIN_FIELDS.has(field)) return field;
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function readProjectionPath(obj, path) {
+  if (obj === void 0 || obj === null) return null;
+  const raw = !path.includes(".") ? obj[path] : (() => {
+    const parts = path.split(".");
+    let cur = obj;
+    for (const part of parts) {
+      if (cur === void 0 || cur === null) return void 0;
+      if (typeof cur !== "object") return void 0;
+      cur = cur[part];
+    }
+    return cur;
+  })();
+  return raw === void 0 ? null : raw;
+}
+
+// src/internal/firestore-projection.ts
+async function runFirestoreFindEdgesProjected(base, select, filters, options) {
+  if (select.length === 0) {
+    throw new FiregraphError(
+      "findEdgesProjected requires a non-empty select list \u2014 an empty projection has no representation distinct from `findEdges`.",
+      "INVALID_QUERY"
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const fields = [];
+  for (const f of select) {
+    if (!seen.has(f)) {
+      seen.add(f);
+      fields.push({ original: f, canonical: normalizeFirestoreProjectionField(f) });
+    }
+  }
+  let q = base;
+  for (const f of filters) {
+    q = q.where(f.field, f.op, f.value);
+  }
+  if (options?.orderBy) {
+    q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
+  }
+  if (options?.limit !== void 0) {
+    q = q.limit(options.limit);
+  }
+  q = q.select(...fields.map((p) => p.canonical));
+  const snap = await q.get();
+  return snap.docs.map((doc) => {
+    const data = doc.data();
+    const out = {};
+    for (const { original, canonical } of fields) {
+      out[original] = readProjectionPath(data, canonical);
+    }
+    return out;
+  });
+}
+
+// src/internal/firestore-vector.ts
+var ENVELOPE_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeVectorFieldPath(label, field) {
+  if (ENVELOPE_FIELDS.has(field)) {
+    throw new FiregraphError(
+      `findNearest(): ${label} '${field}' is a built-in envelope field \u2014 vectors must live under \`data.*\`. Use a path like 'data.${field}' if you really meant a nested data field.`,
+      "INVALID_QUERY"
+    );
+  }
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function buildVectorFilters(params) {
+  const filters = [];
+  if (params.aType) filters.push({ field: "aType", op: "==", value: params.aType });
+  if (params.axbType) filters.push({ field: "axbType", op: "==", value: params.axbType });
+  if (params.bType) filters.push({ field: "bType", op: "==", value: params.bType });
+  if (params.where) filters.push(...params.where);
+  return filters;
+}
+function toNumberArray(qv) {
+  if (Array.isArray(qv)) return qv;
+  if (typeof qv.toArray === "function") {
+    return qv.toArray();
+  }
+  throw new FiregraphError(
+    "findNearest(): queryVector must be a number[] or a Firestore VectorValue.",
+    "INVALID_QUERY"
+  );
+}
+async function runFirestoreFindNearest(base, params) {
+  const vec = toNumberArray(params.queryVector);
+  if (vec.length === 0) {
+    throw new FiregraphError(
+      "findNearest(): queryVector is empty \u2014 at least one dimension is required.",
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isInteger(params.limit) || params.limit <= 0 || params.limit > 1e3) {
+    throw new FiregraphError(
+      `findNearest(): limit must be a positive integer \u2264 1000 (got ${params.limit}).`,
+      "INVALID_QUERY"
+    );
+  }
+  const vectorField = normalizeVectorFieldPath("vectorField", params.vectorField);
+  const distanceResultField = params.distanceResultField !== void 0 ? normalizeVectorFieldPath("distanceResultField", params.distanceResultField) : void 0;
+  const filtered = applyFiltersToQuery(base, buildVectorFilters(params));
+  const opts = {
+    vectorField,
+    queryVector: vec,
+    limit: params.limit,
+    distanceMeasure: params.distanceMeasure
+  };
+  if (params.distanceThreshold !== void 0) opts.distanceThreshold = params.distanceThreshold;
+  if (distanceResultField !== void 0) opts.distanceResultField = distanceResultField;
+  const snap = await filtered.findNearest(opts).get();
+  return snap.docs.map((doc) => doc.data());
+}
+
+export {
+  bulkRemoveEdges,
+  removeNodeCascade,
+  runFirestoreAggregate,
+  createFirestoreAdapter,
+  createTransactionAdapter,
+  createBatchAdapter,
+  runFirestoreClassicExpand,
+  runFirestoreFindEdgesProjected,
+  runFirestoreFindNearest
+};
+//# sourceMappingURL=chunk-PAD7WFFU.js.map