@typicalday/firegraph 0.8.0 → 0.10.0

package/dist/index.cjs

@@ -66,10 +66,18 @@ 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 };
+    return {
+      [SERIALIZATION_TAG]: "Timestamp",
+      seconds: value.seconds,
+      nanoseconds: value.nanoseconds
+    };
   }
   if (isGeoPoint(value)) {
-    return { [SERIALIZATION_TAG]: "GeoPoint", latitude: value.latitude, longitude: value.longitude };
+    return {
+      [SERIALIZATION_TAG]: "GeoPoint",
+      latitude: value.latitude,
+      longitude: value.longitude
+    };
   }
   if (isDocumentReference(value)) {
     return { [SERIALIZATION_TAG]: "DocumentReference", path: value.path };
@@ -150,6 +158,7 @@ var init_serialization = __esm({
 var index_exports = {};
 __export(index_exports, {
   BOOTSTRAP_ENTRIES: () => BOOTSTRAP_ENTRIES,
+  CrossBackendTransactionError: () => CrossBackendTransactionError,
   DEFAULT_QUERY_LIMIT: () => DEFAULT_QUERY_LIMIT,
   DiscoveryError: () => DiscoveryError,
   DynamicRegistryError: () => DynamicRegistryError,
@@ -171,6 +180,7 @@ __export(index_exports, {
   TraversalError: () => TraversalError,
   ValidationError: () => ValidationError,
   analyzeQuerySafety: () => analyzeQuerySafety,
+  appendStorageScope: () => appendStorageScope,
   applyMigrationChain: () => applyMigrationChain,
   buildEdgeQueryPlan: () => buildEdgeQueryPlan,
   buildEdgeRecord: () => buildEdgeRecord,
@@ -198,6 +208,7 @@ __export(index_exports, {
   generateId: () => generateId,
   generateIndexConfig: () => generateIndexConfig,
   generateTypes: () => generateTypes,
+  isAncestorScopeUid: () => isAncestorScopeUid,
   isAncestorUid: () => isAncestorUid,
   isTaggedValue: () => isTaggedValue,
   jsonSchemaToFieldMeta: () => jsonSchemaToFieldMeta,
@@ -205,8 +216,10 @@ __export(index_exports, {
   matchScopeAny: () => matchScopeAny,
   migrateRecord: () => migrateRecord,
   migrateRecords: () => migrateRecords,
+  parseStorageScope: () => parseStorageScope,
   precompileSource: () => precompileSource,
   resolveAncestorCollection: () => resolveAncestorCollection,
+  resolveAncestorScope: () => resolveAncestorScope,
   resolveView: () => resolveView,
   serializeFirestoreTypes: () => serializeFirestoreTypes,
   validateMigrationChain: () => validateMigrationChain
@@ -331,10 +344,7 @@ var ValidationError = class extends FiregraphError {
 };
 var RegistryViolationError = class extends FiregraphError {
   constructor(aType, axbType, bType) {
-    super(
-      `Unregistered triple: (${aType}) -[${axbType}]-> (${bType})`,
-      "REGISTRY_VIOLATION"
-    );
+    super(`Unregistered triple: (${aType}) -[${axbType}]-> (${bType})`, "REGISTRY_VIOLATION");
     this.name = "RegistryViolationError";
   }
 };
@@ -377,6 +387,12 @@ var MigrationError = class extends FiregraphError {
     this.name = "MigrationError";
   }
 };
+var CrossBackendTransactionError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "CROSS_BACKEND_TRANSACTION");
+    this.name = "CrossBackendTransactionError";
+  }
+};
 
 // src/json-schema.ts
 var import_ajv = __toESM(require("ajv"), 1);
@@ -398,9 +414,7 @@ function compileSchema(schema, label) {
 }
 function jsonSchemaToFieldMeta(schema) {
   if (!schema || schema.type !== "object" || !schema.properties) return [];
-  const requiredSet = new Set(
-    Array.isArray(schema.required) ? schema.required : []
-  );
+  const requiredSet = new Set(Array.isArray(schema.required) ? schema.required : []);
   return Object.entries(schema.properties).map(
     ([name, prop]) => propertyToFieldMeta(name, prop, requiredSet.has(name))
   );
@@ -643,6 +657,28 @@ function createRegistry(input) {
   for (const [key, arr] of axbBuild) {
     axbIndex.set(key, Object.freeze(arr));
   }
+  const topologyIndex = /* @__PURE__ */ new Map();
+  const topologyBuild = /* @__PURE__ */ new Map();
+  const topologySeen = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!entry.targetGraph) continue;
+    let seen = topologySeen.get(entry.aType);
+    if (!seen) {
+      seen = /* @__PURE__ */ new Set();
+      topologySeen.set(entry.aType, seen);
+    }
+    if (seen.has(entry.targetGraph)) continue;
+    seen.add(entry.targetGraph);
+    const existing = topologyBuild.get(entry.aType);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      topologyBuild.set(entry.aType, [entry]);
+    }
+  }
+  for (const [key, arr] of topologyBuild) {
+    topologyIndex.set(key, Object.freeze(arr));
+  }
   return {
     lookup(aType, axbType, bType) {
       return map.get(tripleKey(aType, axbType, bType))?.entry;
@@ -650,6 +686,9 @@ function createRegistry(input) {
     lookupByAxbType(axbType) {
       return axbIndex.get(axbType) ?? [];
     },
+    getSubgraphTopology(aType) {
+      return topologyIndex.get(aType) ?? [];
+    },
     validate(aType, axbType, bType, data, scopePath) {
       const rec = map.get(tripleKey(aType, axbType, bType));
       if (!rec) {
@@ -697,6 +736,21 @@ function createMergedRegistry(base, extension) {
       }
       return Object.freeze(merged);
     },
+    getSubgraphTopology(aType) {
+      const baseResults = base.getSubgraphTopology(aType);
+      const extResults = extension.getSubgraphTopology(aType);
+      if (extResults.length === 0) return baseResults;
+      if (baseResults.length === 0) return extResults;
+      const seen = new Set(baseResults.map((e) => e.targetGraph));
+      const merged = [...baseResults];
+      for (const entry of extResults) {
+        if (!seen.has(entry.targetGraph)) {
+          seen.add(entry.targetGraph);
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    },
     validate(aType, axbType, bType, data, scopePath) {
       if (baseKeys.has(tripleKey(aType, axbType, bType))) {
         return base.validate(aType, axbType, bType, data, scopePath);
@@ -1429,6 +1483,21 @@ var GraphClientImpl = class _GraphClientImpl {
   getBackend() {
     return this.backend;
   }
+  /**
+   * Snapshot of the currently-effective registry. Returns the merged view
+   * used for domain-type validation and migration — in dynamic mode this is
+   * `dynamicRegistry ?? staticRegistry ?? bootstrapRegistry`, so callers see
+   * updates after `reloadRegistry()` without having to re-resolve anything.
+   *
+   * Exposed for backends that need topology access during bulk operations
+   * (e.g. the Cloudflare DO backend's cross-DO cascade). Not part of the
+   * public `GraphClient` surface.
+   *
+   * @internal
+   */
+  getRegistrySnapshot() {
+    return this.getCombinedRegistry();
+  }
   // ---------------------------------------------------------------------------
   // Registry routing
   // ---------------------------------------------------------------------------
@@ -2035,14 +2104,10 @@ function loadEdgeEntity(dir, name) {
   }
   const topology = readJson(edgePath);
   if (!topology.from) {
-    throw new DiscoveryError(
-      `edge.json for "${name}" is missing required "from" field`
-    );
+    throw new DiscoveryError(`edge.json for "${name}" is missing required "from" field`);
   }
   if (!topology.to) {
-    throw new DiscoveryError(
-      `edge.json for "${name}" is missing required "to" field`
-    );
+    throw new DiscoveryError(`edge.json for "${name}" is missing required "to" field`);
   }
   const meta = readJsonIfExists((0, import_node_path.join)(dir, "meta.json"));
   const sampleData = readJsonIfExists((0, import_node_path.join)(dir, "sample.json"));
@@ -2719,6 +2784,26 @@ function generateIndexConfig(collection, entities, registryEntries) {
 // src/query-client/client.ts
 var import_node_http = __toESM(require("http"), 1);
 
+// src/query-client/config.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var CONFIG_FILES = ["firegraph.config.ts", "firegraph.config.js", "firegraph.config.mjs"];
+var DEFAULT_PORT = 3884;
+function readEditorPort(cwd) {
+  const dir = cwd ?? process.cwd();
+  for (const name of CONFIG_FILES) {
+    try {
+      const content = (0, import_node_fs2.readFileSync)((0, import_node_path2.join)(dir, name), "utf8");
+      const editorBlock = content.match(/editor\s*:\s*\{[^}]*\}/s)?.[0] ?? "";
+      const portMatch = editorBlock.match(/port\s*:\s*(\d+)/);
+      if (portMatch) return parseInt(portMatch[1], 10);
+    } catch {
+      continue;
+    }
+  }
+  return DEFAULT_PORT;
+}
+
 // src/query-client/shaping.ts
 function summarizeRecord(r) {
   if (!r) return null;
@@ -2745,26 +2830,6 @@ function summarizeEdge(r) {
   return out;
 }
 
-// src/query-client/config.ts
-var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
-var CONFIG_FILES = ["firegraph.config.ts", "firegraph.config.js", "firegraph.config.mjs"];
-var DEFAULT_PORT = 3884;
-function readEditorPort(cwd) {
-  const dir = cwd ?? process.cwd();
-  for (const name of CONFIG_FILES) {
-    try {
-      const content = (0, import_node_fs2.readFileSync)((0, import_node_path2.join)(dir, name), "utf8");
-      const editorBlock = content.match(/editor\s*:\s*\{[^}]*\}/s)?.[0] ?? "";
-      const portMatch = editorBlock.match(/port\s*:\s*(\d+)/);
-      if (portMatch) return parseInt(portMatch[1], 10);
-    } catch {
-      continue;
-    }
-  }
-  return DEFAULT_PORT;
-}
-
 // src/query-client/client.ts
 var QueryClientError = class extends Error {
   constructor(message, code) {
@@ -2963,14 +3028,16 @@ var QueryClient = class {
     }
     const data = await this.mutate("traverse", input);
     return {
-      hops: (data.hops ?? []).map((h) => ({
-        relation: h.axbType,
-        direction: h.direction,
-        depth: h.depth,
-        edgeCount: (h.edges ?? []).length,
-        edges: (h.edges ?? []).map(summarizeEdge).filter(Boolean),
-        truncated: h.truncated ?? false
-      })),
+      hops: (data.hops ?? []).map(
+        (h) => ({
+          relation: h.axbType,
+          direction: h.direction,
+          depth: h.depth,
+          edgeCount: (h.edges ?? []).length,
+          edges: (h.edges ?? []).map(summarizeEdge).filter(Boolean),
+          truncated: h.truncated ?? false
+        })
+      ),
       totalReads: data.totalReads ?? 0,
       truncated: data.truncated ?? false
     };
@@ -3021,6 +3088,56 @@ function buildEdgeRecord(aType, aUid, axbType, bType, bUid, data) {
   };
 }
 
+// src/scope-path.ts
+function parseStorageScope(scope) {
+  if (scope === "") return [];
+  const parts = scope.split("/");
+  if (parts.length % 2 !== 0) {
+    throw new Error(
+      `INVALID_SCOPE_PATH: storage-scope "${scope}" has an odd number of segments; expected interleaved <uid>/<name> pairs.`
+    );
+  }
+  const out = [];
+  for (let i = 0; i < parts.length; i += 2) {
+    const uid = parts[i];
+    const name = parts[i + 1];
+    if (!uid || !name) {
+      throw new Error(
+        `INVALID_SCOPE_PATH: storage-scope "${scope}" contains an empty segment at position ${i}.`
+      );
+    }
+    out.push({ uid, name });
+  }
+  return out;
+}
+function resolveAncestorScope(storageScope, uid) {
+  if (!uid) return null;
+  if (storageScope === "") return null;
+  const parts = storageScope.split("/");
+  for (let i = 0; i < parts.length; i += 2) {
+    if (parts[i] === uid) {
+      return i === 0 ? "" : parts.slice(0, i).join("/");
+    }
+  }
+  return null;
+}
+function isAncestorScopeUid(storageScope, uid) {
+  return resolveAncestorScope(storageScope, uid) !== null;
+}
+function appendStorageScope(parentScope, uid, name) {
+  if (!uid || uid.includes("/")) {
+    throw new Error(
+      `INVALID_SCOPE_PATH: uid must be non-empty and must not contain "/": got "${uid}".`
+    );
+  }
+  if (!name || name.includes("/")) {
+    throw new Error(
+      `INVALID_SCOPE_PATH: name must be non-empty and must not contain "/": got "${name}".`
+    );
+  }
+  return parentScope ? `${parentScope}/${uid}/${name}` : `${uid}/${name}`;
+}
+
 // src/index.ts
 init_serialization();
 
@@ -3228,7 +3345,6 @@ function getCustomElements() {
 function resilientView(ViewClass, tagName) {
   const g = globalThis;
   if (!g.HTMLElement) return ViewClass;
-  const Base = g.HTMLElement;
   const Wrapped = class extends ViewClass {
     connectedCallback() {
       try {
@@ -3316,6 +3432,7 @@ function defineViews(input) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BOOTSTRAP_ENTRIES,
+  CrossBackendTransactionError,
   DEFAULT_QUERY_LIMIT,
   DiscoveryError,
   DynamicRegistryError,
@@ -3337,6 +3454,7 @@ function defineViews(input) {
   TraversalError,
   ValidationError,
   analyzeQuerySafety,
+  appendStorageScope,
   applyMigrationChain,
   buildEdgeQueryPlan,
   buildEdgeRecord,
@@ -3364,6 +3482,7 @@ function defineViews(input) {
   generateId,
   generateIndexConfig,
   generateTypes,
+  isAncestorScopeUid,
   isAncestorUid,
   isTaggedValue,
   jsonSchemaToFieldMeta,
@@ -3371,8 +3490,10 @@ function defineViews(input) {
   matchScopeAny,
   migrateRecord,
   migrateRecords,
+  parseStorageScope,
   precompileSource,
   resolveAncestorCollection,
+  resolveAncestorScope,
   resolveView,
   serializeFirestoreTypes,
   validateMigrationChain