@nicia-ai/typegraph 0.1.0

package/dist/interchange/index.d.ts

@@ -0,0 +1,288 @@
+import { z } from 'zod';
+import { G as GraphDef, S as Store } from '../store-60Lcfi0w.js';
+import '../types-CjZ7g_7v.js';
+import 'drizzle-orm';
+import '../types-BRzHlhKC.js';
+import '../ast-BVyihVbP.js';
+
+/**
+ * Graph interchange format types.
+ *
+ * Defines Zod schemas for importing and exporting graph data.
+ * The format is designed to be:
+ * - JSON-serializable for API transport
+ * - Validated via Zod at runtime
+ * - Exportable as JSON Schema for LLM/API documentation
+ */
+
+/**
+ * Current interchange format version.
+ * Increment for breaking changes to the format.
+ */
+declare const FORMAT_VERSION: "1.0";
+/**
+ * Interchange format for a node.
+ *
+ * Properties are stored as a record to allow schema-agnostic transport.
+ * Validation against the actual schema happens during import.
+ */
+declare const InterchangeNodeSchema: z.ZodObject<{
+    kind: z.ZodString;
+    id: z.ZodString;
+    properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    validFrom: z.ZodOptional<z.ZodISODateTime>;
+    validTo: z.ZodOptional<z.ZodISODateTime>;
+    meta: z.ZodOptional<z.ZodObject<{
+        version: z.ZodOptional<z.ZodNumber>;
+        createdAt: z.ZodOptional<z.ZodISODateTime>;
+        updatedAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type InterchangeNode = z.infer<typeof InterchangeNodeSchema>;
+/**
+ * Interchange format for an edge.
+ *
+ * Endpoint references are objects with kind and id, rather than
+ * composite strings, for clarity and type safety.
+ */
+declare const InterchangeEdgeSchema: z.ZodObject<{
+    kind: z.ZodString;
+    id: z.ZodString;
+    from: z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    to: z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    properties: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    validFrom: z.ZodOptional<z.ZodISODateTime>;
+    validTo: z.ZodOptional<z.ZodISODateTime>;
+    meta: z.ZodOptional<z.ZodObject<{
+        createdAt: z.ZodOptional<z.ZodISODateTime>;
+        updatedAt: z.ZodOptional<z.ZodISODateTime>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type InterchangeEdge = z.infer<typeof InterchangeEdgeSchema>;
+/**
+ * Strategy for handling conflicts when a node/edge ID already exists.
+ *
+ * - `skip`: Keep existing, ignore incoming
+ * - `update`: Merge incoming properties into existing
+ * - `error`: Throw an error on conflict
+ */
+declare const ConflictStrategySchema: z.ZodEnum<{
+    error: "error";
+    skip: "skip";
+    update: "update";
+}>;
+type ConflictStrategy = z.infer<typeof ConflictStrategySchema>;
+/**
+ * Strategy for handling properties not defined in the schema.
+ *
+ * - `error`: Throw a validation error
+ * - `strip`: Remove unknown properties silently
+ * - `allow`: Pass through to storage (relies on backend behavior)
+ */
+declare const UnknownPropertyStrategySchema: z.ZodEnum<{
+    error: "error";
+    strip: "strip";
+    allow: "allow";
+}>;
+type UnknownPropertyStrategy = z.infer<typeof UnknownPropertyStrategySchema>;
+/**
+ * Options for importing graph data.
+ */
+declare const ImportOptionsSchema: z.ZodObject<{
+    onConflict: z.ZodEnum<{
+        error: "error";
+        skip: "skip";
+        update: "update";
+    }>;
+    onUnknownProperty: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        strip: "strip";
+        allow: "allow";
+    }>>;
+    validateReferences: z.ZodDefault<z.ZodBoolean>;
+    batchSize: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+type ImportOptions = z.infer<typeof ImportOptionsSchema>;
+/**
+ * Source metadata for graph data.
+ *
+ * Uses discriminated union to capture different origin types:
+ * - `typegraph-cloud`: Extracted by TypeGraph Cloud
+ * - `typegraph-export`: Exported from a TypeGraph store
+ * - `external`: From a third-party system
+ */
+declare const GraphDataSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"typegraph-cloud">;
+    extractionId: z.ZodString;
+    schemaId: z.ZodString;
+    schemaVersion: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"typegraph-export">;
+    graphId: z.ZodString;
+    schemaVersion: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"external">;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+type GraphDataSource = z.infer<typeof GraphDataSourceSchema>;
+/**
+ * Complete graph data interchange format.
+ *
+ * The envelope contains metadata about the data source and format version,
+ * plus arrays of nodes and edges to import.
+ */
+declare const GraphDataSchema: z.ZodObject<{
+    formatVersion: z.ZodLiteral<"1.0">;
+    exportedAt: z.ZodISODateTime;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"typegraph-cloud">;
+        extractionId: z.ZodString;
+        schemaId: z.ZodString;
+        schemaVersion: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"typegraph-export">;
+        graphId: z.ZodString;
+        schemaVersion: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"external">;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">;
+    nodes: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        validFrom: z.ZodOptional<z.ZodISODateTime>;
+        validTo: z.ZodOptional<z.ZodISODateTime>;
+        meta: z.ZodOptional<z.ZodObject<{
+            version: z.ZodOptional<z.ZodNumber>;
+            createdAt: z.ZodOptional<z.ZodISODateTime>;
+            updatedAt: z.ZodOptional<z.ZodISODateTime>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+        from: z.ZodObject<{
+            kind: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>;
+        to: z.ZodObject<{
+            kind: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>;
+        properties: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        validFrom: z.ZodOptional<z.ZodISODateTime>;
+        validTo: z.ZodOptional<z.ZodISODateTime>;
+        meta: z.ZodOptional<z.ZodObject<{
+            createdAt: z.ZodOptional<z.ZodISODateTime>;
+            updatedAt: z.ZodOptional<z.ZodISODateTime>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type GraphData = z.infer<typeof GraphDataSchema>;
+/**
+ * An error that occurred during import.
+ */
+declare const ImportErrorSchema: z.ZodObject<{
+    entityType: z.ZodEnum<{
+        node: "node";
+        edge: "edge";
+    }>;
+    kind: z.ZodString;
+    id: z.ZodString;
+    error: z.ZodString;
+}, z.core.$strip>;
+type ImportError = z.infer<typeof ImportErrorSchema>;
+/**
+ * Result of an import operation.
+ *
+ * Contains counts of created/updated/skipped entities and any errors.
+ */
+declare const ImportResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    nodes: z.ZodObject<{
+        created: z.ZodNumber;
+        updated: z.ZodNumber;
+        skipped: z.ZodNumber;
+    }, z.core.$strip>;
+    edges: z.ZodObject<{
+        created: z.ZodNumber;
+        updated: z.ZodNumber;
+        skipped: z.ZodNumber;
+    }, z.core.$strip>;
+    errors: z.ZodArray<z.ZodObject<{
+        entityType: z.ZodEnum<{
+            node: "node";
+            edge: "edge";
+        }>;
+        kind: z.ZodString;
+        id: z.ZodString;
+        error: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type ImportResult = z.infer<typeof ImportResultSchema>;
+/**
+ * Options for exporting graph data.
+ */
+declare const ExportOptionsSchema: z.ZodObject<{
+    nodeKinds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    edgeKinds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    includeTemporal: z.ZodDefault<z.ZodBoolean>;
+    includeMeta: z.ZodDefault<z.ZodBoolean>;
+    includeDeleted: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Export options with defaults applied (output type) */
+type ExportOptions = z.infer<typeof ExportOptionsSchema>;
+/** Export options as accepted by exportGraph (input type with optional defaults) */
+type ExportOptionsInput = z.input<typeof ExportOptionsSchema>;
+
+/**
+ * Export graph data from a store.
+ *
+ * @param store - The graph store to export from
+ * @param options - Export configuration
+ * @returns Graph data in interchange format
+ *
+ * @example
+ * ```typescript
+ * const data = await exportGraph(store, {
+ *   nodeKinds: ["Person", "Organization"],
+ *   includeMeta: true,
+ * });
+ *
+ * // Write to file
+ * await fs.writeFile("backup.json", JSON.stringify(data, null, 2));
+ * ```
+ */
+declare function exportGraph<G extends GraphDef>(store: Store<G>, options?: ExportOptionsInput): Promise<GraphData>;
+
+/**
+ * Import graph data into a store.
+ *
+ * Nodes are imported first to satisfy edge reference validation.
+ * The import runs within a transaction for atomicity when supported.
+ *
+ * @param store - The graph store to import into
+ * @param data - Graph data in interchange format
+ * @param options - Import configuration
+ * @returns Import statistics and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = await importGraph(store, data, {
+ *   onConflict: "update",
+ *   onUnknownProperty: "strip",
+ * });
+ *
+ * console.log(`Created ${result.nodes.created} nodes`);
+ * ```
+ */
+declare function importGraph<G extends GraphDef>(store: Store<G>, data: GraphData, options: ImportOptions): Promise<ImportResult>;
+
+export { type ConflictStrategy, ConflictStrategySchema, type ExportOptions, type ExportOptionsInput, ExportOptionsSchema, FORMAT_VERSION, type GraphData, GraphDataSchema, type GraphDataSource, GraphDataSourceSchema, type ImportError, ImportErrorSchema, type ImportOptions, ImportOptionsSchema, type ImportResult, ImportResultSchema, type InterchangeEdge, InterchangeEdgeSchema, type InterchangeNode, InterchangeNodeSchema, type UnknownPropertyStrategy, UnknownPropertyStrategySchema, exportGraph, importGraph };