@nicia-ai/typegraph 0.9.2 → 0.11.0

package/dist/index.cjs

@@ -3033,7 +3033,7 @@ function compileRecursiveCte(ast, traversal, graphId, ctx, requiredColumnsByAlia
     recursiveBaseWhereClauses.push(cycleCheck);
   }
   recursiveBaseWhereClauses.push(...edgePredicates, ...targetNodePredicates);
-  function compileRecursiveBranch(branch) {
+  function compileRecursiveBranch2(branch) {
     const recursiveFilterClauses = [
       ...recursiveBaseWhereClauses,
       compileKindFilter2(branch.edgeKinds, "e.kind"),
@@ -3088,7 +3088,7 @@ function compileRecursiveCte(ast, traversal, graphId, ctx, requiredColumnsByAlia
   const directTargetField = direction === "out" ? "to_id" : "from_id";
   const directJoinKindField = direction === "out" ? "from_kind" : "to_kind";
   const directTargetKindField = direction === "out" ? "to_kind" : "from_kind";
-  const directBranch = compileRecursiveBranch({
+  const directBranch = compileRecursiveBranch2({
     joinField: directJoinField,
     targetField: directTargetField,
     joinKindField: directJoinKindField,
@@ -3104,7 +3104,7 @@ function compileRecursiveCte(ast, traversal, graphId, ctx, requiredColumnsByAlia
       (kind) => directEdgeKinds.includes(kind)
     );
     const duplicateGuard = overlappingKinds.length > 0 ? drizzleOrm.sql`NOT (e.from_id = e.to_id AND ${compileKindFilter2(overlappingKinds, "e.kind")})` : void 0;
-    const inverseBranch = compileRecursiveBranch({
+    const inverseBranch = compileRecursiveBranch2({
       joinField: inverseJoinField,
       targetField: inverseTargetField,
       joinKindField: inverseJoinKindField,
@@ -8267,21 +8267,29 @@ function narrowEdge(edge) {
 function narrowEdges(edges) {
   return edges;
 }
+function buildCreateEdgeInput(kind, from, to, props, options) {
+  const input = {
+    kind,
+    fromKind: from.kind,
+    fromId: from.id,
+    toKind: to.kind,
+    toId: to.id,
+    props
+  };
+  if (options?.id !== void 0) input.id = options.id;
+  if (options?.validFrom !== void 0) input.validFrom = options.validFrom;
+  if (options?.validTo !== void 0) input.validTo = options.validTo;
+  return input;
+}
+function buildUpdateEdgeInput(id, props, options) {
+  const input = { id, props };
+  if (options?.validTo !== void 0) input.validTo = options.validTo;
+  return input;
+}
 function mapBulkEdgeInputs(kind, items) {
-  return items.map((item) => {
-    const input = {
-      kind,
-      fromKind: item.from.kind,
-      fromId: item.from.id,
-      toKind: item.to.kind,
-      toId: item.to.id,
-      props: item.props ?? {}
-    };
-    if (item.id !== void 0) input.id = item.id;
-    if (item.validFrom !== void 0) input.validFrom = item.validFrom;
-    if (item.validTo !== void 0) input.validTo = item.validTo;
-    return input;
-  });
+  return items.map(
+    (item) => buildCreateEdgeInput(kind, item.from, item.to, item.props ?? {}, item)
+  );
 }
 function createEdgeCollection(config) {
   const {
@@ -8301,18 +8309,16 @@ function createEdgeCollection(config) {
   } = config;
   return {
     async create(from, to, props, options) {
-      const input = {
-        kind,
-        fromKind: from.kind,
-        fromId: from.id,
-        toKind: to.kind,
-        toId: to.id,
-        props: props ?? {}
-      };
-      if (options?.id !== void 0) input.id = options.id;
-      if (options?.validFrom !== void 0) input.validFrom = options.validFrom;
-      if (options?.validTo !== void 0) input.validTo = options.validTo;
-      const result = await executeEdgeCreate2(input, backend);
+      const result = await executeEdgeCreate2(
+        buildCreateEdgeInput(
+          kind,
+          from,
+          to,
+          props ?? {},
+          options
+        ),
+        backend
+      );
       return narrowEdge(result);
     },
     async getById(id, options) {
@@ -8349,12 +8355,10 @@ function createEdgeCollection(config) {
       );
     },
     async update(id, props, options) {
-      const input = {
-        id,
-        props
-      };
-      if (options?.validTo !== void 0) input.validTo = options.validTo;
-      const result = await executeEdgeUpdate2(input, backend);
+      const result = await executeEdgeUpdate2(
+        buildUpdateEdgeInput(id, props, options),
+        backend
+      );
       return narrowEdge(result);
     },
     async findFrom(from) {
@@ -8467,29 +8471,26 @@ function createEdgeCollection(config) {
         for (const item of items) {
           const existing = existingMap.get(item.id);
           if (existing) {
-            const input = {
-              id: item.id,
-              props: item.props
-            };
-            if (item.validTo !== void 0) input.validTo = item.validTo;
             toUpdate.push({
               index: itemIndex,
-              input,
+              input: buildUpdateEdgeInput(
+                item.id,
+                item.props ?? {},
+                item
+              ),
               clearDeleted: existing.deleted_at !== void 0
             });
           } else {
-            const input = {
-              kind,
-              id: item.id,
-              fromKind: item.from.kind,
-              fromId: item.from.id,
-              toKind: item.to.kind,
-              toId: item.to.id,
-              props: item.props
-            };
-            if (item.validFrom !== void 0) input.validFrom = item.validFrom;
-            if (item.validTo !== void 0) input.validTo = item.validTo;
-            toCreate.push({ index: itemIndex, input });
+            toCreate.push({
+              index: itemIndex,
+              input: buildCreateEdgeInput(
+                kind,
+                item.from,
+                item.to,
+                item.props ?? {},
+                item
+              )
+            });
           }
           itemIndex++;
         }
@@ -8618,17 +8619,20 @@ function narrowNode(node) {
 function narrowNodes(nodes) {
   return nodes;
 }
+function buildCreateInput(kind, props, options) {
+  const input = { kind, props };
+  if (options?.id !== void 0) input.id = options.id;
+  if (options?.validFrom !== void 0) input.validFrom = options.validFrom;
+  if (options?.validTo !== void 0) input.validTo = options.validTo;
+  return input;
+}
+function buildUpdateInput(kind, id, props, options) {
+  const input = { kind, id, props };
+  if (options?.validTo !== void 0) input.validTo = options.validTo;
+  return input;
+}
 function mapBulkNodeInputs(kind, items) {
-  return items.map((item) => {
-    const input = {
-      kind,
-      props: item.props
-    };
-    if (item.id !== void 0) input.id = item.id;
-    if (item.validFrom !== void 0) input.validFrom = item.validFrom;
-    if (item.validTo !== void 0) input.validTo = item.validTo;
-    return input;
-  });
+  return items.map((item) => buildCreateInput(kind, item.props, item));
 }
 function createNodeCollection(config) {
   const {
@@ -8653,14 +8657,13 @@ function createNodeCollection(config) {
   } = config;
   return {
     async create(props, options) {
-      const input = {
-        kind,
-        props
-      };
-      if (options?.id !== void 0) input.id = options.id;
-      if (options?.validFrom !== void 0) input.validFrom = options.validFrom;
-      if (options?.validTo !== void 0) input.validTo = options.validTo;
-      const result = await executeNodeCreate2(input, backend);
+      return this.createFromRecord(props, options);
+    },
+    async createFromRecord(data, options) {
+      const result = await executeNodeCreate2(
+        buildCreateInput(kind, data, options),
+        backend
+      );
       return narrowNode(result);
     },
     async getById(id, options) {
@@ -8698,13 +8701,10 @@ function createNodeCollection(config) {
       );
     },
     async update(id, props, options) {
-      const input = {
-        kind,
-        id,
-        props
-      };
-      if (options?.validTo !== void 0) input.validTo = options.validTo;
-      const result = await executeNodeUpdate2(input, backend);
+      const result = await executeNodeUpdate2(
+        buildUpdateInput(kind, id, props, options),
+        backend
+      );
       return narrowNode(result);
     },
     async delete(id) {
@@ -8760,31 +8760,28 @@ function createNodeCollection(config) {
       return backend.countNodesByKind(params);
     },
     async upsertById(id, props, options) {
+      return this.upsertByIdFromRecord(
+        id,
+        props,
+        options
+      );
+    },
+    async upsertByIdFromRecord(id, data, options) {
       const existing = await backend.getNode(graphId, kind, id);
       if (existing) {
-        const input = {
-          kind,
-          id,
-          props
-        };
-        if (options?.validTo !== void 0) input.validTo = options.validTo;
         const clearDeleted = existing.deleted_at !== void 0;
-        const result = await executeNodeUpdate2(input, backend, {
-          clearDeleted
-        });
-        return narrowNode(result);
-      } else {
-        const input = {
-          kind,
-          id,
-          props
-        };
-        if (options?.validFrom !== void 0)
-          input.validFrom = options.validFrom;
-        if (options?.validTo !== void 0) input.validTo = options.validTo;
-        const result = await executeNodeCreate2(input, backend);
-        return narrowNode(result);
+        const result2 = await executeNodeUpdate2(
+          buildUpdateInput(kind, id, data, options),
+          backend,
+          { clearDeleted }
+        );
+        return narrowNode(result2);
       }
+      const result = await executeNodeCreate2(
+        buildCreateInput(kind, data, { ...options, id }),
+        backend
+      );
+      return narrowNode(result);
     },
     async bulkCreate(items) {
       const batchInputs = mapBulkNodeInputs(
@@ -8828,26 +8825,25 @@ function createNodeCollection(config) {
         for (const item of items) {
           const existing = existingMap.get(item.id);
           if (existing) {
-            const input = {
-              kind,
-              id: item.id,
-              props: item.props
-            };
-            if (item.validTo !== void 0) input.validTo = item.validTo;
             toUpdate.push({
               index: itemIndex,
-              input,
+              input: buildUpdateInput(
+                kind,
+                item.id,
+                item.props,
+                item
+              ),
               clearDeleted: existing.deleted_at !== void 0
             });
           } else {
-            const input = {
-              kind,
-              id: item.id,
-              props: item.props
-            };
-            if (item.validFrom !== void 0) input.validFrom = item.validFrom;
-            if (item.validTo !== void 0) input.validTo = item.validTo;
-            toCreate.push({ index: itemIndex, input });
+            toCreate.push({
+              index: itemIndex,
+              input: buildCreateInput(
+                kind,
+                item.props,
+                item
+              )
+            });
           }
           itemIndex++;
         }
@@ -11188,6 +11184,142 @@ async function executeNodeBulkGetOrCreateByConstraint(ctx, kind, constraintName,
   }
   return results;
 }
+var DEFAULT_SUBGRAPH_MAX_DEPTH = 10;
+function normalizeProps(value) {
+  return typeof value === "string" ? value : JSON.stringify(value ?? {});
+}
+async function executeSubgraph(params) {
+  const { options } = params;
+  if (options.edges.length === 0) {
+    return { nodes: [], edges: [] };
+  }
+  const maxDepth = Math.min(
+    options.maxDepth ?? DEFAULT_SUBGRAPH_MAX_DEPTH,
+    MAX_RECURSIVE_DEPTH
+  );
+  const ctx = {
+    graphId: params.graphId,
+    rootId: params.rootId,
+    edgeKinds: options.edges,
+    maxDepth,
+    includeKinds: options.includeKinds,
+    excludeRoot: options.excludeRoot ?? false,
+    direction: options.direction ?? "out",
+    cyclePolicy: options.cyclePolicy ?? "prevent",
+    dialect: params.dialect,
+    schema: params.schema ?? DEFAULT_SQL_SCHEMA,
+    backend: params.backend
+  };
+  const reachableCte = buildReachableCte(ctx);
+  const includedIdsCte = buildIncludedIdsCte(ctx);
+  const [nodeRows, edgeRows] = await Promise.all([
+    fetchSubgraphNodes(ctx, reachableCte, includedIdsCte),
+    fetchSubgraphEdges(ctx, reachableCte, includedIdsCte)
+  ]);
+  const nodes = nodeRows.map(
+    (row) => rowToNode({ ...row, props: normalizeProps(row.props) })
+  );
+  const edges = edgeRows.map(
+    (row) => rowToEdge({ ...row, props: normalizeProps(row.props) })
+  );
+  return {
+    nodes,
+    edges
+  };
+}
+function buildReachableCte(ctx) {
+  const shouldTrackPath = ctx.cyclePolicy === "prevent";
+  const edgeKindFilter = compileKindFilter(drizzleOrm.sql.raw("e.kind"), ctx.edgeKinds);
+  const initialPath = shouldTrackPath ? ctx.dialect.initializePath(drizzleOrm.sql.raw("n.id")) : void 0;
+  const pathExtension = shouldTrackPath ? ctx.dialect.extendPath(drizzleOrm.sql.raw("r.path"), drizzleOrm.sql.raw("n.id")) : void 0;
+  const cycleCheck = shouldTrackPath ? ctx.dialect.cycleCheck(drizzleOrm.sql.raw("n.id"), drizzleOrm.sql.raw("r.path")) : void 0;
+  const baseColumns = [drizzleOrm.sql`n.id`, drizzleOrm.sql`n.kind`, drizzleOrm.sql`0 AS depth`];
+  if (initialPath !== void 0) {
+    baseColumns.push(drizzleOrm.sql`${initialPath} AS path`);
+  }
+  const baseCase = drizzleOrm.sql`SELECT ${drizzleOrm.sql.join(baseColumns, drizzleOrm.sql`, `)} FROM ${ctx.schema.nodesTable} n WHERE n.graph_id = ${ctx.graphId} AND n.id = ${ctx.rootId} AND n.deleted_at IS NULL`;
+  const recursiveColumns = [
+    drizzleOrm.sql`n.id`,
+    drizzleOrm.sql`n.kind`,
+    drizzleOrm.sql`r.depth + 1 AS depth`
+  ];
+  if (pathExtension !== void 0) {
+    recursiveColumns.push(drizzleOrm.sql`${pathExtension} AS path`);
+  }
+  const recursiveWhereClauses = [
+    drizzleOrm.sql`e.graph_id = ${ctx.graphId}`,
+    edgeKindFilter,
+    drizzleOrm.sql`e.deleted_at IS NULL`,
+    drizzleOrm.sql`n.deleted_at IS NULL`,
+    drizzleOrm.sql`r.depth < ${ctx.maxDepth}`
+  ];
+  if (cycleCheck !== void 0) {
+    recursiveWhereClauses.push(cycleCheck);
+  }
+  const forceWorktableOuterJoinOrder = ctx.dialect.capabilities.forceRecursiveWorktableOuterJoinOrder;
+  const recursiveCase = ctx.direction === "both" ? compileBidirectionalBranch({
+    recursiveColumns,
+    whereClauses: recursiveWhereClauses,
+    forceWorktableOuterJoinOrder,
+    schema: ctx.schema
+  }) : compileRecursiveBranch({
+    recursiveColumns,
+    whereClauses: recursiveWhereClauses,
+    joinField: "from_id",
+    targetField: "to_id",
+    targetKindField: "to_kind",
+    forceWorktableOuterJoinOrder,
+    schema: ctx.schema
+  });
+  return drizzleOrm.sql`WITH RECURSIVE reachable AS (${baseCase} UNION ALL ${recursiveCase})`;
+}
+function compileRecursiveBranch(params) {
+  const columns = [...params.recursiveColumns];
+  const selectClause = drizzleOrm.sql`SELECT ${drizzleOrm.sql.join(columns, drizzleOrm.sql`, `)}`;
+  const nodeJoin = drizzleOrm.sql`JOIN ${params.schema.nodesTable} n ON n.graph_id = e.graph_id AND n.id = e.${drizzleOrm.sql.raw(params.targetField)} AND n.kind = e.${drizzleOrm.sql.raw(params.targetKindField)}`;
+  if (params.forceWorktableOuterJoinOrder) {
+    const allWhere = [
+      ...params.whereClauses,
+      drizzleOrm.sql`e.${drizzleOrm.sql.raw(params.joinField)} = r.id`
+    ];
+    return drizzleOrm.sql`${selectClause} FROM reachable r CROSS JOIN ${params.schema.edgesTable} e ${nodeJoin} WHERE ${drizzleOrm.sql.join(allWhere, drizzleOrm.sql` AND `)}`;
+  }
+  const where = [...params.whereClauses];
+  return drizzleOrm.sql`${selectClause} FROM reachable r JOIN ${params.schema.edgesTable} e ON e.${drizzleOrm.sql.raw(params.joinField)} = r.id ${nodeJoin} WHERE ${drizzleOrm.sql.join(where, drizzleOrm.sql` AND `)}`;
+}
+function compileBidirectionalBranch(params) {
+  const columns = [...params.recursiveColumns];
+  const selectClause = drizzleOrm.sql`SELECT ${drizzleOrm.sql.join(columns, drizzleOrm.sql`, `)}`;
+  const nodeJoin = drizzleOrm.sql`JOIN ${params.schema.nodesTable} n ON n.graph_id = e.graph_id AND ((e.to_id = r.id AND n.id = e.from_id AND n.kind = e.from_kind) OR (e.from_id = r.id AND n.id = e.to_id AND n.kind = e.to_kind))`;
+  if (params.forceWorktableOuterJoinOrder) {
+    const allWhere = [
+      ...params.whereClauses,
+      drizzleOrm.sql`(e.from_id = r.id OR e.to_id = r.id)`
+    ];
+    return drizzleOrm.sql`${selectClause} FROM reachable r CROSS JOIN ${params.schema.edgesTable} e ${nodeJoin} WHERE ${drizzleOrm.sql.join(allWhere, drizzleOrm.sql` AND `)}`;
+  }
+  return drizzleOrm.sql`${selectClause} FROM reachable r JOIN ${params.schema.edgesTable} e ON (e.from_id = r.id OR e.to_id = r.id) ${nodeJoin} WHERE ${drizzleOrm.sql.join([...params.whereClauses], drizzleOrm.sql` AND `)}`;
+}
+function buildIncludedIdsCte(ctx) {
+  const filters = [];
+  if (ctx.includeKinds !== void 0 && ctx.includeKinds.length > 0) {
+    filters.push(compileKindFilter(drizzleOrm.sql.raw("kind"), ctx.includeKinds));
+  }
+  if (ctx.excludeRoot) {
+    filters.push(drizzleOrm.sql`id != ${ctx.rootId}`);
+  }
+  const whereClause = filters.length > 0 ? drizzleOrm.sql` WHERE ${drizzleOrm.sql.join(filters, drizzleOrm.sql` AND `)}` : drizzleOrm.sql``;
+  return drizzleOrm.sql`, included_ids AS (SELECT DISTINCT id FROM reachable${whereClause})`;
+}
+async function fetchSubgraphNodes(ctx, reachableCte, includedIdsCte) {
+  const query = drizzleOrm.sql`${reachableCte}${includedIdsCte} SELECT n.kind, n.id, n.props, n.version, n.valid_from, n.valid_to, n.created_at, n.updated_at, n.deleted_at FROM ${ctx.schema.nodesTable} n WHERE n.graph_id = ${ctx.graphId} AND n.id IN (SELECT id FROM included_ids)`;
+  return ctx.backend.execute(query);
+}
+async function fetchSubgraphEdges(ctx, reachableCte, includedIdsCte) {
+  const edgeKindFilter = compileKindFilter(drizzleOrm.sql.raw("e.kind"), ctx.edgeKinds);
+  const query = drizzleOrm.sql`${reachableCte}${includedIdsCte} SELECT e.id, e.kind, e.from_kind, e.from_id, e.to_kind, e.to_id, e.props, e.valid_from, e.valid_to, e.created_at, e.updated_at, e.deleted_at FROM ${ctx.schema.edgesTable} e WHERE e.graph_id = ${ctx.graphId} AND ${edgeKindFilter} AND e.deleted_at IS NULL AND e.from_id IN (SELECT id FROM included_ids) AND e.to_id IN (SELECT id FROM included_ids)`;
+  return ctx.backend.execute(query);
+}
 
 // src/store/store.ts
 var Store = class {
@@ -11391,6 +11523,39 @@ var Store = class {
   query() {
     return this.#createQueryForBackend(this.#backend);
   }
+  // === Subgraph Extraction ===
+  /**
+   * Extracts a typed subgraph by traversing from a root node.
+   *
+   * Performs a BFS traversal from `rootId` following the specified edge kinds,
+   * then returns all reachable nodes and the edges connecting them.
+   *
+   * @example
+   * ```typescript
+   * const result = await store.subgraph(run.id, {
+   *   edges: ["has_task", "runs_agent", "uses_skill"],
+   *   maxDepth: 4,
+   *   includeKinds: ["Run", "Task", "Agent", "Skill"],
+   * });
+   *
+   * for (const node of result.nodes) {
+   *   switch (node.kind) {
+   *     case "Task": console.log(node.name); break;
+   *     case "Agent": console.log(node.model); break;
+   *   }
+   * }
+   * ```
+   */
+  async subgraph(rootId, options) {
+    return executeSubgraph({
+      graphId: this.graphId,
+      rootId,
+      backend: this.#backend,
+      dialect: chunk2WVFEIHR_cjs.getDialect(this.#backend.dialect),
+      schema: this.#schema,
+      options
+    });
+  }
   // === Transactions ===
   /**
    * Executes a function within a transaction.