@monstermann/graph 0.0.0 → 0.2.0

package/dist/Graph/removeEdge.mjs

@@ -0,0 +1,71 @@
+import { batch } from "./batch.mjs";
+import { parseNodeIdentifier } from "./internals/parseNodeIdentifier.mjs";
+import { unsetInGraph } from "./internals/core.mjs";
+
+//#region src/Graph/removeEdge.ts
+/**
+* # removeEdge
+*
+* ```ts
+* function Graph.removeEdge(
+*     graph: Graph,
+*     source: [NodeType, NodeId] | { type: NodeType, id: NodeId },
+*     target: [NodeType, NodeId] | { type: NodeType, id: NodeId },
+* ): Graph
+* ```
+*
+* Removes an edge between two nodes. The nodes remain in the graph. Returns a new graph instance without the edge.
+*
+* ## Example
+*
+* ```ts
+* import { Graph } from "@monstermann/graph";
+*
+* type Nodes =
+*     | { type: "Task"; id: string }
+*     | { type: "Section"; id: string }
+*     | { type: "Project"; id: string };
+*
+* type Edges = {
+*     Project: { Task: void };
+*     Section: { Task: void };
+* };
+*
+* const graph = Graph.create<Nodes, Edges>();
+* let g = Graph.setNode(graph, { type: "Project", id: "1" });
+* g = Graph.setNode(g, { type: "Task", id: "1" });
+* g = Graph.setEdge(g, ["Project", "1"], ["Task", "1"]);
+*
+* // Remove the edge
+* g = Graph.removeEdge(g, ["Project", "1"], ["Task", "1"]);
+*
+* Graph.hasNode(g, ["Project", "1"]); // true
+* Graph.hasNode(g, ["Task", "1"]); // true
+* Graph.hasEdge(g, ["Project", "1"], ["Task", "1"]); // false
+* ```
+*
+*/
+function removeEdge(graph, source, target) {
+	const [sourceType, sourceId] = parseNodeIdentifier(source);
+	const [targetType, targetId] = parseNodeIdentifier(target);
+	return batch(graph, (graph) => {
+		graph = unsetInGraph(graph, [
+			"edges",
+			sourceType,
+			sourceId,
+			targetType,
+			targetId
+		]);
+		graph = unsetInGraph(graph, [
+			"edges",
+			targetType,
+			targetId,
+			sourceType,
+			sourceId
+		]);
+		return graph;
+	});
+}
+
+//#endregion
+export { removeEdge };

package/dist/Graph/removeNode.d.mts

@@ -0,0 +1,46 @@
+import { Edges, Graph, Node, NodeIdentifier, NodeType } from "./types.mjs";
+
+//#region src/Graph/removeNode.d.ts
+/**
+ * # removeNode
+ *
+ * ```ts
+ * function Graph.removeNode(
+ *     graph: Graph,
+ *     node: [NodeType, NodeId] | { type: NodeType, id: NodeId },
+ * ): Graph
+ * ```
+ *
+ * Removes a node and all its associated edges from the graph. Returns a new graph instance without the node.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: void };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * let g = Graph.setNode(graph, { type: "Project", id: "1" });
+ * g = Graph.setNode(g, { type: "Task", id: "1" });
+ * g = Graph.setEdge(g, ["Project", "1"], ["Task", "1"]);
+ *
+ * // Remove the task (also removes the edge)
+ * g = Graph.removeNode(g, ["Task", "1"]);
+ *
+ * Graph.hasNode(g, ["Task", "1"]); // false
+ * Graph.hasEdge(g, ["Project", "1"], ["Task", "1"]); // false
+ * ```
+ *
+ */
+declare function removeNode<N extends Node, E extends Edges<N>, U extends NodeType<N>>(graph: Graph<N, E>, node: NodeIdentifier<N, U>): Graph<N, E>;
+//#endregion
+export { removeNode };

package/dist/Graph/removeNode.mjs

@@ -0,0 +1,71 @@
+import { batch } from "./batch.mjs";
+import { parseNodeIdentifier } from "./internals/parseNodeIdentifier.mjs";
+import { unsetInGraph } from "./internals/core.mjs";
+
+//#region src/Graph/removeNode.ts
+/**
+* # removeNode
+*
+* ```ts
+* function Graph.removeNode(
+*     graph: Graph,
+*     node: [NodeType, NodeId] | { type: NodeType, id: NodeId },
+* ): Graph
+* ```
+*
+* Removes a node and all its associated edges from the graph. Returns a new graph instance without the node.
+*
+* ## Example
+*
+* ```ts
+* import { Graph } from "@monstermann/graph";
+*
+* type Nodes =
+*     | { type: "Task"; id: string }
+*     | { type: "Section"; id: string }
+*     | { type: "Project"; id: string };
+*
+* type Edges = {
+*     Project: { Task: void };
+*     Section: { Task: void };
+* };
+*
+* const graph = Graph.create<Nodes, Edges>();
+* let g = Graph.setNode(graph, { type: "Project", id: "1" });
+* g = Graph.setNode(g, { type: "Task", id: "1" });
+* g = Graph.setEdge(g, ["Project", "1"], ["Task", "1"]);
+*
+* // Remove the task (also removes the edge)
+* g = Graph.removeNode(g, ["Task", "1"]);
+*
+* Graph.hasNode(g, ["Task", "1"]); // false
+* Graph.hasEdge(g, ["Project", "1"], ["Task", "1"]); // false
+* ```
+*
+*/
+function removeNode(graph, node) {
+	const [sourceType, sourceId] = parseNodeIdentifier(node);
+	return batch(graph, (graph) => {
+		for (const [targetType, targets] of graph.get("edges")?.get(sourceType)?.get(sourceId) ?? []) for (const targetId of targets.keys()) graph = unsetInGraph(graph, [
+			"edges",
+			targetType,
+			targetId,
+			sourceType,
+			sourceId
+		]);
+		graph = unsetInGraph(graph, [
+			"edges",
+			sourceType,
+			sourceId
+		]);
+		graph = unsetInGraph(graph, [
+			"nodes",
+			sourceType,
+			sourceId
+		]);
+		return graph;
+	});
+}
+
+//#endregion
+export { removeNode };

package/dist/Graph/setEdge.d.mts

@@ -0,0 +1,52 @@
+import { Bimap } from "./internals/types.mjs";
+import { Edges, Graph, Node, NodeIdentifier, NodeType } from "./types.mjs";
+
+//#region src/Graph/setEdge.d.ts
+/**
+ * # setEdge
+ *
+ * ```ts
+ * function Graph.setEdge(
+ *     graph: Graph,
+ *     source: [NodeType, NodeId] | { type: NodeType, id: NodeId },
+ *     target: [NodeType, NodeId] | { type: NodeType, id: NodeId },
+ *     data?: EdgeData,
+ * ): Graph
+ * ```
+ *
+ * Adds or updates an edge between two nodes. Both nodes must exist in the graph. Returns a new graph instance with the edge set. Edges are bidirectional.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: { assignedAt: Date } };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * let g = Graph.setNode(graph, { type: "Project", id: "1" });
+ * g = Graph.setNode(g, { type: "Task", id: "1" });
+ *
+ * // Add edge with data
+ * g = Graph.setEdge(g, ["Project", "1"], ["Task", "1"], {
+ *     assignedAt: new Date(),
+ * });
+ *
+ * // Add edge without data (void)
+ * let g2 = Graph.setNode(graph, { type: "Section", id: "1" });
+ * g2 = Graph.setNode(g2, { type: "Task", id: "1" });
+ * g2 = Graph.setEdge(g2, ["Section", "1"], ["Task", "1"]);
+ * ```
+ *
+ */
+declare function setEdge<N extends Node, E extends Edges<N>, N1 extends keyof Bimap<E> & NodeType<N>, N2 extends keyof Bimap<E>[N1] & NodeType<N>>(graph: Graph<N, E>, source: NodeIdentifier<N, N1>, target: NodeIdentifier<N, N2>, ...args: Bimap<E>[N1][N2] extends void ? [] | [data: void] : [data: Bimap<E>[N1][N2]]): Graph<N, E>;
+//#endregion
+export { setEdge };

package/dist/Graph/setEdge.mjs

@@ -0,0 +1,78 @@
+import { batch } from "./batch.mjs";
+import { parseNodeIdentifier } from "./internals/parseNodeIdentifier.mjs";
+import { hasNode } from "./hasNode.mjs";
+import { setInGraph } from "./internals/core.mjs";
+
+//#region src/Graph/setEdge.ts
+/**
+* # setEdge
+*
+* ```ts
+* function Graph.setEdge(
+*     graph: Graph,
+*     source: [NodeType, NodeId] | { type: NodeType, id: NodeId },
+*     target: [NodeType, NodeId] | { type: NodeType, id: NodeId },
+*     data?: EdgeData,
+* ): Graph
+* ```
+*
+* Adds or updates an edge between two nodes. Both nodes must exist in the graph. Returns a new graph instance with the edge set. Edges are bidirectional.
+*
+* ## Example
+*
+* ```ts
+* import { Graph } from "@monstermann/graph";
+*
+* type Nodes =
+*     | { type: "Task"; id: string }
+*     | { type: "Section"; id: string }
+*     | { type: "Project"; id: string };
+*
+* type Edges = {
+*     Project: { Task: { assignedAt: Date } };
+*     Section: { Task: void };
+* };
+*
+* const graph = Graph.create<Nodes, Edges>();
+* let g = Graph.setNode(graph, { type: "Project", id: "1" });
+* g = Graph.setNode(g, { type: "Task", id: "1" });
+*
+* // Add edge with data
+* g = Graph.setEdge(g, ["Project", "1"], ["Task", "1"], {
+*     assignedAt: new Date(),
+* });
+*
+* // Add edge without data (void)
+* let g2 = Graph.setNode(graph, { type: "Section", id: "1" });
+* g2 = Graph.setNode(g2, { type: "Task", id: "1" });
+* g2 = Graph.setEdge(g2, ["Section", "1"], ["Task", "1"]);
+* ```
+*
+*/
+function setEdge(graph, source, target, ...args) {
+	const edge = args[0];
+	const [sourceType, sourceId] = parseNodeIdentifier(source);
+	const [targetType, targetId] = parseNodeIdentifier(target);
+	if (!hasNode(graph, source)) return graph;
+	if (!hasNode(graph, target)) return graph;
+	return batch(graph, (graph) => {
+		graph = setInGraph(graph, [
+			"edges",
+			sourceType,
+			sourceId,
+			targetType,
+			targetId
+		], edge);
+		graph = setInGraph(graph, [
+			"edges",
+			targetType,
+			targetId,
+			sourceType,
+			sourceId
+		], edge);
+		return graph;
+	});
+}
+
+//#endregion
+export { setEdge };

package/dist/Graph/setNode.d.mts

@@ -0,0 +1,43 @@
+import { Edges, Graph, Node } from "./types.mjs";
+
+//#region src/Graph/setNode.d.ts
+/**
+ * # setNode
+ *
+ * ```ts
+ * function Graph.setNode(
+ *     graph: Graph,
+ *     node: Node,
+ * ): Graph
+ * ```
+ *
+ * Adds or updates a node in the graph. Returns a new graph instance with the node set.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string; title: string }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: void };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ *
+ * // Add a new node
+ * const g1 = Graph.setNode(graph, { type: "Task", id: "1", title: "My Task" });
+ *
+ * // Update existing node
+ * const g2 = Graph.setNode(g1, { type: "Task", id: "1", title: "Updated Task" });
+ * ```
+ *
+ */
+declare function setNode<N extends Node, E extends Edges<N>>(graph: Graph<N, E>, node: NoInfer<N>): Graph<N, E>;
+//#endregion
+export { setNode };

package/dist/Graph/setNode.mjs

@@ -0,0 +1,50 @@
+import { setInGraph } from "./internals/core.mjs";
+
+//#region src/Graph/setNode.ts
+/**
+* # setNode
+*
+* ```ts
+* function Graph.setNode(
+*     graph: Graph,
+*     node: Node,
+* ): Graph
+* ```
+*
+* Adds or updates a node in the graph. Returns a new graph instance with the node set.
+*
+* ## Example
+*
+* ```ts
+* import { Graph } from "@monstermann/graph";
+*
+* type Nodes =
+*     | { type: "Task"; id: string; title: string }
+*     | { type: "Section"; id: string }
+*     | { type: "Project"; id: string };
+*
+* type Edges = {
+*     Project: { Task: void };
+*     Section: { Task: void };
+* };
+*
+* const graph = Graph.create<Nodes, Edges>();
+*
+* // Add a new node
+* const g1 = Graph.setNode(graph, { type: "Task", id: "1", title: "My Task" });
+*
+* // Update existing node
+* const g2 = Graph.setNode(g1, { type: "Task", id: "1", title: "Updated Task" });
+* ```
+*
+*/
+function setNode(graph, node) {
+	return setInGraph(graph, [
+		"nodes",
+		node.type,
+		node.id
+	], node);
+}
+
+//#endregion
+export { setNode };

package/dist/Graph/toJS.d.mts

@@ -0,0 +1,59 @@
+import { Edge, Edges, Graph, Node, NodeId } from "./types.mjs";
+
+//#region src/Graph/toJS.d.ts
+/**
+ * # toJS
+ *
+ * ```ts
+ * function Graph.toJS(
+ *     graph: Graph,
+ * ): {
+ *     nodes: Node[];
+ *     edges: [NodeType, NodeId, NodeType, NodeId, EdgeData][];
+ * }
+ * ```
+ *
+ * Converts a graph to a plain JavaScript object representation. Useful for serializing graphs to JSON or other storage formats.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Graph } from "@monstermann/graph";
+ *
+ * type Nodes =
+ *     | { type: "Task"; id: string; title: string }
+ *     | { type: "Section"; id: string }
+ *     | { type: "Project"; id: string };
+ *
+ * type Edges = {
+ *     Project: { Task: void };
+ *     Section: { Task: void };
+ * };
+ *
+ * const graph = Graph.create<Nodes, Edges>();
+ * let g = Graph.setNode(graph, { type: "Project", id: "1" });
+ * g = Graph.setNode(g, { type: "Task", id: "1", title: "My Task" });
+ * g = Graph.setEdge(g, ["Project", "1"], ["Task", "1"]);
+ *
+ * const data = Graph.toJS(g);
+ * // data: {
+ * //   nodes: [
+ * //     { type: "Project", id: "1" },
+ * //     { type: "Task", id: "1", title: "My Task" }
+ * //   ],
+ * //   edges: [
+ * //     ["Project", "1", "Task", "1", undefined]
+ * //   ]
+ * // }
+ *
+ * // Can be serialized to JSON
+ * const json = JSON.stringify(data);
+ * ```
+ *
+ */
+declare function toJS<N extends Node, E extends Edges<N>>(graph: Graph<N, E>): {
+  edges: [string, NodeId, string, NodeId, Edge][];
+  nodes: Node[];
+};
+//#endregion
+export { toJS };

package/dist/Graph/toJS.mjs

@@ -0,0 +1,82 @@
+//#region src/Graph/toJS.ts
+/**
+* # toJS
+*
+* ```ts
+* function Graph.toJS(
+*     graph: Graph,
+* ): {
+*     nodes: Node[];
+*     edges: [NodeType, NodeId, NodeType, NodeId, EdgeData][];
+* }
+* ```
+*
+* Converts a graph to a plain JavaScript object representation. Useful for serializing graphs to JSON or other storage formats.
+*
+* ## Example
+*
+* ```ts
+* import { Graph } from "@monstermann/graph";
+*
+* type Nodes =
+*     | { type: "Task"; id: string; title: string }
+*     | { type: "Section"; id: string }
+*     | { type: "Project"; id: string };
+*
+* type Edges = {
+*     Project: { Task: void };
+*     Section: { Task: void };
+* };
+*
+* const graph = Graph.create<Nodes, Edges>();
+* let g = Graph.setNode(graph, { type: "Project", id: "1" });
+* g = Graph.setNode(g, { type: "Task", id: "1", title: "My Task" });
+* g = Graph.setEdge(g, ["Project", "1"], ["Task", "1"]);
+*
+* const data = Graph.toJS(g);
+* // data: {
+* //   nodes: [
+* //     { type: "Project", id: "1" },
+* //     { type: "Task", id: "1", title: "My Task" }
+* //   ],
+* //   edges: [
+* //     ["Project", "1", "Task", "1", undefined]
+* //   ]
+* // }
+*
+* // Can be serialized to JSON
+* const json = JSON.stringify(data);
+* ```
+*
+*/
+function toJS(graph) {
+	const nodes = [];
+	const edges = [];
+	const seenEdges = /* @__PURE__ */ new Set();
+	for (const ids of graph.get("nodes")?.values() ?? []) for (const node of ids.values()) nodes.push(node);
+	for (const [sourceType, sourceIds] of graph.get("edges") ?? []) for (const [sourceId, targetTypes] of sourceIds) for (const [targetType, targetIds] of targetTypes) for (const [targetId, edge] of targetIds) {
+		const key = createEdgeKey(sourceType, String(sourceId), targetType, String(targetId));
+		if (seenEdges.has(key)) continue;
+		seenEdges.add(key);
+		edges.push([
+			sourceType,
+			sourceId,
+			targetType,
+			targetId,
+			edge
+		]);
+	}
+	return {
+		edges,
+		nodes
+	};
+}
+function createEdgeKey(type1, id1, type2, id2) {
+	const cmp = type1.localeCompare(type2);
+	if (cmp < 0) return `${type1}\0${id1}\0${type2}\0${id2}`;
+	else if (cmp > 0) return `${type2}\0${id2}\0${type1}\0${id1}`;
+	else return id1 < id2 ? `${type1}\0${id1}\0${type2}\0${id2}` : `${type2}\0${id2}\0${type1}\0${id1}`;
+}
+
+//#endregion
+export { toJS };

package/dist/Graph/types.d.mts

@@ -0,0 +1,29 @@
+import { NodeTypesMap, SourceTypesMap } from "./internals/types.mjs";
+
+//#region src/Graph/types.d.ts
+type NodeId = PropertyKey;
+type Node = {
+  id: NodeId;
+  type: string;
+};
+type NodeType<T extends Node> = T["type"];
+type NodeOfType<T extends Node, U extends NodeType<T>> = Extract<T, {
+  type: U;
+}>;
+type NodeIdentifier<T extends Node, U extends NodeType<T>> = {
+  id: Extract<T, {
+    type: U;
+  }>["id"];
+  type: U;
+} | [U, id: Extract<T, {
+  type: U;
+}>["id"]];
+type Edge = Record<string, unknown> | void;
+type Edges<N extends Node> = Partial<Record<NodeType<N>, Partial<Record<NodeType<N>, Edge>>>>;
+interface Graph<N extends Node, _E extends Edges<N>> extends Map<"nodes" | "edges" | "clones", NodeTypesMap<N> | SourceTypesMap | Set<any>> {
+  delete: (key: "clones") => boolean;
+  get: ((key: "nodes") => NodeTypesMap<N> | undefined) & ((key: "edges") => SourceTypesMap | undefined) & ((key: "clones") => Set<any> | undefined);
+  set: (key: "clones", value: Set<any>) => this;
+}
+//#endregion
+export { Edge, Edges, Graph, Node, NodeId, NodeIdentifier, NodeOfType, NodeType };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { Edge, Edges, Graph, Node, NodeId, NodeIdentifier, NodeIdsMap, NodeOfType, NodeType, NodeTypesMap, SourceIdsMap, SourceTypesMap, TargetIdsMap, TargetTypesMap } from "./Graph/index.mjs";
+export { Edge, Edges, Graph, Node, NodeId, NodeIdentifier, NodeIdsMap, NodeOfType, NodeType, NodeTypesMap, SourceIdsMap, SourceTypesMap, TargetIdsMap, TargetTypesMap };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { Graph } from "./Graph/index.mjs";
+
+export { Graph };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@monstermann/graph",
     "type": "module",
-    "version": "0.0.0",
+    "version": "0.2.0",
     "description": "Functional graph data-structure.",
     "author": "Michael Ostermann <michaelostermann@me.com>",
     "license": "MIT",