@nicia-ai/typegraph 0.1.0

package/dist/interchange/index.js

@@ -0,0 +1,598 @@
+import { getNodeTypeNames, getEdgeTypeNames, nowIso } from '../chunk-L642L24T.js';
+import '../chunk-JKTO7TW3.js';
+import '../chunk-DGUM43GV.js';
+import { z } from 'zod';
+
+var FORMAT_VERSION = "1.0";
+var InterchangeNodeSchema = z.object({
+  kind: z.string().min(1),
+  id: z.string().min(1),
+  properties: z.record(z.string(), z.unknown()),
+  validFrom: z.iso.datetime().optional(),
+  validTo: z.iso.datetime().optional(),
+  meta: z.object({
+    version: z.number().int().positive().optional(),
+    createdAt: z.iso.datetime().optional(),
+    updatedAt: z.iso.datetime().optional()
+  }).optional()
+});
+var InterchangeEdgeSchema = z.object({
+  kind: z.string().min(1),
+  id: z.string().min(1),
+  from: z.object({
+    kind: z.string().min(1),
+    id: z.string().min(1)
+  }),
+  to: z.object({
+    kind: z.string().min(1),
+    id: z.string().min(1)
+  }),
+  properties: z.record(z.string(), z.unknown()).default({}),
+  validFrom: z.iso.datetime().optional(),
+  validTo: z.iso.datetime().optional(),
+  meta: z.object({
+    createdAt: z.iso.datetime().optional(),
+    updatedAt: z.iso.datetime().optional()
+  }).optional()
+});
+var ConflictStrategySchema = z.enum(["skip", "update", "error"]);
+var UnknownPropertyStrategySchema = z.enum([
+  "error",
+  "strip",
+  "allow"
+]);
+var ImportOptionsSchema = z.object({
+  /** How to handle existing nodes/edges with the same ID */
+  onConflict: ConflictStrategySchema,
+  /** How to handle properties not in the schema */
+  onUnknownProperty: UnknownPropertyStrategySchema.default("error"),
+  /** Whether to validate that edge endpoints exist */
+  validateReferences: z.boolean().default(true),
+  /** Number of items to process in each batch */
+  batchSize: z.number().int().positive().default(100)
+});
+var GraphDataSourceSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("typegraph-cloud"),
+    extractionId: z.string(),
+    schemaId: z.string(),
+    schemaVersion: z.number().int().positive().optional()
+  }),
+  z.object({
+    type: z.literal("typegraph-export"),
+    graphId: z.string(),
+    schemaVersion: z.number().int().positive()
+  }),
+  z.object({
+    type: z.literal("external"),
+    description: z.string().optional()
+  })
+]);
+var GraphDataSchema = z.object({
+  formatVersion: z.literal(FORMAT_VERSION),
+  exportedAt: z.iso.datetime(),
+  source: GraphDataSourceSchema,
+  nodes: z.array(InterchangeNodeSchema),
+  edges: z.array(InterchangeEdgeSchema)
+});
+var ImportErrorSchema = z.object({
+  entityType: z.enum(["node", "edge"]),
+  kind: z.string(),
+  id: z.string(),
+  error: z.string()
+});
+var ImportResultSchema = z.object({
+  success: z.boolean(),
+  nodes: z.object({
+    created: z.number().int().nonnegative(),
+    updated: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative()
+  }),
+  edges: z.object({
+    created: z.number().int().nonnegative(),
+    updated: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative()
+  }),
+  errors: z.array(ImportErrorSchema)
+});
+var ExportOptionsSchema = z.object({
+  /** Filter to specific node kinds (undefined = all) */
+  nodeKinds: z.array(z.string()).optional(),
+  /** Filter to specific edge kinds (undefined = all) */
+  edgeKinds: z.array(z.string()).optional(),
+  /** Include temporal fields (validFrom, validTo) */
+  includeTemporal: z.boolean().default(false),
+  /** Include metadata (version, timestamps) */
+  includeMeta: z.boolean().default(false),
+  /** Include soft-deleted records */
+  includeDeleted: z.boolean().default(false)
+});
+
+// src/interchange/export.ts
+async function exportGraph(store, options) {
+  const options_ = {
+    nodeKinds: options?.nodeKinds,
+    edgeKinds: options?.edgeKinds,
+    includeTemporal: options?.includeTemporal ?? false,
+    includeMeta: options?.includeMeta ?? false,
+    includeDeleted: options?.includeDeleted ?? false
+  };
+  const graph = store.graph;
+  const graphId = store.graphId;
+  const backend = store.backend;
+  const nodeKindsToExport = options_.nodeKinds ?? getNodeTypeNames(graph);
+  const edgeKindsToExport = options_.edgeKinds ?? getEdgeTypeNames(graph);
+  const nodes = [];
+  for (const kind of nodeKindsToExport) {
+    const kindNodes = await exportNodesOfKind(backend, graphId, kind, options_);
+    nodes.push(...kindNodes);
+  }
+  const edges = [];
+  for (const kind of edgeKindsToExport) {
+    const kindEdges = await exportEdgesOfKind(backend, graphId, kind, options_);
+    edges.push(...kindEdges);
+  }
+  const schemaVersion = await backend.getActiveSchema(graphId);
+  return {
+    formatVersion: FORMAT_VERSION,
+    exportedAt: nowIso(),
+    source: {
+      type: "typegraph-export",
+      graphId,
+      schemaVersion: schemaVersion?.version ?? 1
+    },
+    nodes,
+    edges
+  };
+}
+async function exportNodesOfKind(backend, graphId, kind, options) {
+  const rows = await backend.findNodesByKind({
+    graphId,
+    kind,
+    excludeDeleted: !options.includeDeleted
+  });
+  return rows.map((row) => {
+    const node = {
+      kind: row.kind,
+      id: row.id,
+      properties: JSON.parse(row.props)
+    };
+    if (options.includeTemporal) {
+      if (row.valid_from) {
+        node.validFrom = row.valid_from;
+      }
+      if (row.valid_to) {
+        node.validTo = row.valid_to;
+      }
+    }
+    if (options.includeMeta) {
+      node.meta = {
+        version: row.version,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+      };
+    }
+    return node;
+  });
+}
+async function exportEdgesOfKind(backend, graphId, kind, options) {
+  const rows = await backend.findEdgesByKind({
+    graphId,
+    kind,
+    excludeDeleted: !options.includeDeleted
+  });
+  return rows.map((row) => {
+    const edge = {
+      kind: row.kind,
+      id: row.id,
+      from: {
+        kind: row.from_kind,
+        id: row.from_id
+      },
+      to: {
+        kind: row.to_kind,
+        id: row.to_id
+      },
+      properties: JSON.parse(row.props)
+    };
+    if (options.includeTemporal) {
+      if (row.valid_from) {
+        edge.validFrom = row.valid_from;
+      }
+      if (row.valid_to) {
+        edge.validTo = row.valid_to;
+      }
+    }
+    if (options.includeMeta) {
+      edge.meta = {
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+      };
+    }
+    return edge;
+  });
+}
+
+// src/interchange/import.ts
+async function importGraph(store, data, options) {
+  const result = {
+    success: true,
+    nodes: { created: 0, updated: 0, skipped: 0 },
+    edges: { created: 0, updated: 0, skipped: 0 },
+    errors: []
+  };
+  const errors = [];
+  const graph = store.graph;
+  const graphId = store.graphId;
+  const backend = store.backend;
+  const nodeSchemas = buildNodeSchemaMap(graph);
+  const edgeSchemas = buildEdgeSchemaMap(graph);
+  const importedNodeIds = /* @__PURE__ */ new Set();
+  if (backend.capabilities.transactions) {
+    await backend.transaction(async (tx) => {
+      await processNodes(
+        tx,
+        graphId,
+        data.nodes,
+        nodeSchemas,
+        options,
+        result,
+        errors,
+        importedNodeIds
+      );
+      await processEdges(
+        tx,
+        graphId,
+        data.edges,
+        edgeSchemas,
+        nodeSchemas,
+        options,
+        result,
+        errors,
+        importedNodeIds
+      );
+    });
+  } else {
+    await processNodes(
+      backend,
+      graphId,
+      data.nodes,
+      nodeSchemas,
+      options,
+      result,
+      errors,
+      importedNodeIds
+    );
+    await processEdges(
+      backend,
+      graphId,
+      data.edges,
+      edgeSchemas,
+      nodeSchemas,
+      options,
+      result,
+      errors,
+      importedNodeIds
+    );
+  }
+  return {
+    ...result,
+    success: errors.length === 0,
+    errors
+  };
+}
+function buildNodeSchemaMap(graph) {
+  const map = /* @__PURE__ */ new Map();
+  for (const kindName of getNodeTypeNames(graph)) {
+    const registration = graph.nodes[kindName];
+    map.set(kindName, {
+      registration,
+      schema: registration.type.schema
+    });
+  }
+  return map;
+}
+function buildEdgeSchemaMap(graph) {
+  const map = /* @__PURE__ */ new Map();
+  for (const kindName of getEdgeTypeNames(graph)) {
+    const registration = graph.edges[kindName];
+    map.set(kindName, {
+      registration,
+      schema: registration.type.schema,
+      fromKinds: new Set(registration.from.map((node) => node.name)),
+      toKinds: new Set(registration.to.map((node) => node.name))
+    });
+  }
+  return map;
+}
+async function processNodes(backend, graphId, nodes, schemas, options, result, errors, importedNodeIds) {
+  const batchSize = options.batchSize;
+  for (let index = 0; index < nodes.length; index += batchSize) {
+    const batch = nodes.slice(index, index + batchSize);
+    for (const node of batch) {
+      const importResult = await processNode(
+        backend,
+        graphId,
+        node,
+        schemas,
+        options
+      );
+      switch (importResult.status) {
+        case "created": {
+          result.nodes.created++;
+          importedNodeIds.add(makeNodeKey(node.kind, node.id));
+          break;
+        }
+        case "updated": {
+          result.nodes.updated++;
+          importedNodeIds.add(makeNodeKey(node.kind, node.id));
+          break;
+        }
+        case "skipped": {
+          result.nodes.skipped++;
+          importedNodeIds.add(makeNodeKey(node.kind, node.id));
+          break;
+        }
+        case "error": {
+          errors.push({
+            entityType: "node",
+            kind: node.kind,
+            id: node.id,
+            error: importResult.error
+          });
+          break;
+        }
+      }
+    }
+  }
+}
+async function processNode(backend, graphId, node, schemas, options) {
+  const schemaEntry = schemas.get(node.kind);
+  if (!schemaEntry) {
+    return { status: "error", error: `Unknown node kind: ${node.kind}` };
+  }
+  const propsResult = validateProperties(
+    node.properties,
+    schemaEntry.schema,
+    options.onUnknownProperty
+  );
+  if (!propsResult.success) {
+    return { status: "error", error: propsResult.error };
+  }
+  const existing = await backend.getNode(graphId, node.kind, node.id);
+  if (existing) {
+    switch (options.onConflict) {
+      case "skip": {
+        return { status: "skipped" };
+      }
+      case "error": {
+        return {
+          status: "error",
+          error: `Node already exists: ${node.kind}:${node.id}`
+        };
+      }
+      case "update": {
+        await backend.updateNode({
+          graphId,
+          kind: node.kind,
+          id: node.id,
+          props: propsResult.data,
+          incrementVersion: true,
+          ...node.validTo !== void 0 && { validTo: node.validTo }
+        });
+        return { status: "updated" };
+      }
+    }
+  }
+  await backend.insertNode({
+    graphId,
+    kind: node.kind,
+    id: node.id,
+    props: propsResult.data,
+    ...node.validFrom !== void 0 && { validFrom: node.validFrom },
+    ...node.validTo !== void 0 && { validTo: node.validTo }
+  });
+  return { status: "created" };
+}
+async function processEdges(backend, graphId, edges, edgeSchemas, nodeSchemas, options, result, errors, importedNodeIds) {
+  const batchSize = options.batchSize;
+  for (let index = 0; index < edges.length; index += batchSize) {
+    const batch = edges.slice(index, index + batchSize);
+    for (const edge of batch) {
+      const importResult = await processEdge(
+        backend,
+        graphId,
+        edge,
+        edgeSchemas,
+        nodeSchemas,
+        options,
+        importedNodeIds
+      );
+      switch (importResult.status) {
+        case "created": {
+          result.edges.created++;
+          break;
+        }
+        case "updated": {
+          result.edges.updated++;
+          break;
+        }
+        case "skipped": {
+          result.edges.skipped++;
+          break;
+        }
+        case "error": {
+          errors.push({
+            entityType: "edge",
+            kind: edge.kind,
+            id: edge.id,
+            error: importResult.error
+          });
+          break;
+        }
+      }
+    }
+  }
+}
+async function processEdge(backend, graphId, edge, edgeSchemas, nodeSchemas, options, importedNodeIds) {
+  const schemaEntry = edgeSchemas.get(edge.kind);
+  if (!schemaEntry) {
+    return { status: "error", error: `Unknown edge kind: ${edge.kind}` };
+  }
+  if (!nodeSchemas.has(edge.from.kind)) {
+    return {
+      status: "error",
+      error: `Unknown from node kind: ${edge.from.kind}`
+    };
+  }
+  if (!nodeSchemas.has(edge.to.kind)) {
+    return { status: "error", error: `Unknown to node kind: ${edge.to.kind}` };
+  }
+  if (!schemaEntry.fromKinds.has(edge.from.kind)) {
+    return {
+      status: "error",
+      error: `Edge ${edge.kind} does not allow from kind: ${edge.from.kind}`
+    };
+  }
+  if (!schemaEntry.toKinds.has(edge.to.kind)) {
+    return {
+      status: "error",
+      error: `Edge ${edge.kind} does not allow to kind: ${edge.to.kind}`
+    };
+  }
+  if (options.validateReferences) {
+    const fromKey = makeNodeKey(edge.from.kind, edge.from.id);
+    const toKey = makeNodeKey(edge.to.kind, edge.to.id);
+    if (!importedNodeIds.has(fromKey)) {
+      const fromExists = await backend.getNode(
+        graphId,
+        edge.from.kind,
+        edge.from.id
+      );
+      if (!fromExists) {
+        return {
+          status: "error",
+          error: `From node not found: ${edge.from.kind}:${edge.from.id}`
+        };
+      }
+    }
+    if (!importedNodeIds.has(toKey)) {
+      const toExists = await backend.getNode(graphId, edge.to.kind, edge.to.id);
+      if (!toExists) {
+        return {
+          status: "error",
+          error: `To node not found: ${edge.to.kind}:${edge.to.id}`
+        };
+      }
+    }
+  }
+  const propsResult = validateProperties(
+    edge.properties,
+    schemaEntry.schema,
+    options.onUnknownProperty
+  );
+  if (!propsResult.success) {
+    return { status: "error", error: propsResult.error };
+  }
+  const existing = await backend.getEdge(graphId, edge.id);
+  if (existing) {
+    switch (options.onConflict) {
+      case "skip": {
+        return { status: "skipped" };
+      }
+      case "error": {
+        return { status: "error", error: `Edge already exists: ${edge.id}` };
+      }
+      case "update": {
+        await backend.updateEdge({
+          graphId,
+          id: edge.id,
+          props: propsResult.data,
+          ...edge.validTo !== void 0 && { validTo: edge.validTo }
+        });
+        return { status: "updated" };
+      }
+    }
+  }
+  await backend.insertEdge({
+    graphId,
+    id: edge.id,
+    kind: edge.kind,
+    fromKind: edge.from.kind,
+    fromId: edge.from.id,
+    toKind: edge.to.kind,
+    toId: edge.to.id,
+    props: propsResult.data,
+    ...edge.validFrom !== void 0 && { validFrom: edge.validFrom },
+    ...edge.validTo !== void 0 && { validTo: edge.validTo }
+  });
+  return { status: "created" };
+}
+function validateProperties(properties, schema, unknownStrategy) {
+  try {
+    const knownKeys = new Set(Object.keys(schema.shape));
+    const unknownKeys = Object.keys(properties).filter(
+      (key) => !knownKeys.has(key)
+    );
+    if (unknownKeys.length > 0) {
+      switch (unknownStrategy) {
+        case "error": {
+          return {
+            success: false,
+            error: `Unknown properties: ${unknownKeys.join(", ")}`
+          };
+        }
+        case "strip": {
+          const stripped = {};
+          for (const key of knownKeys) {
+            if (key in properties) {
+              stripped[key] = properties[key];
+            }
+          }
+          const result2 = schema.safeParse(stripped);
+          if (!result2.success) {
+            return {
+              success: false,
+              error: formatZodError(result2.error)
+            };
+          }
+          return {
+            success: true,
+            data: result2.data
+          };
+        }
+        case "allow": {
+          const result2 = schema.safeParse(properties);
+          if (!result2.success) {
+            return {
+              success: false,
+              error: formatZodError(result2.error)
+            };
+          }
+          return { success: true, data: properties };
+        }
+      }
+    }
+    const result = schema.safeParse(properties);
+    if (!result.success) {
+      return { success: false, error: formatZodError(result.error) };
+    }
+    return { success: true, data: result.data };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { success: false, error: `Validation error: ${message}` };
+  }
+}
+function formatZodError(error) {
+  return error.issues.map((issue) => {
+    const path = issue.path.join(".");
+    return path ? `${path}: ${issue.message}` : issue.message;
+  }).join("; ");
+}
+function makeNodeKey(kind, id) {
+  return `${kind}:${id}`;
+}
+
+export { ConflictStrategySchema, ExportOptionsSchema, FORMAT_VERSION, GraphDataSchema, GraphDataSourceSchema, ImportErrorSchema, ImportOptionsSchema, ImportResultSchema, InterchangeEdgeSchema, InterchangeNodeSchema, UnknownPropertyStrategySchema, exportGraph, importGraph };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map