@infrascan/shared-types 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @infrascan/shared-types
 
+## 0.5.0
+
+### Minor Changes
+
+- [#82](https://github.com/infrascan/infrascan/pull/82) [`e28a6d9`](https://github.com/infrascan/infrascan/commit/e28a6d91eb36fa83e9a40a667eb39a15b2a45ccb) Thanks [@lfarrel6](https://github.com/lfarrel6)! - Introduce new readable/writable interface for @infrascan/core graph interface to make types nicer to work with. Previously, the graph returned union types to bridge the Graph's internal model of the state with its exposed API for adding children/parents/edges. This resulted in a lot of properties with signatures like `parent?: Node | string`.
+
+  This has been updated to wrap the Node and Edge types in `Readable` and `Writable` types based on the context they're being used in. This is inspired by the Kysely `Selectable`/`Insertable` pattern. When a Node is `Readable` its edges, parent and children will resolve to other Node objects. When `Writable`, all other Nodes are expected to be referenced using a string type containing their ID.
+
+  Introduce @infrascan/node-reducer-plugin which reduces graph complexity for dynamicially provisioned infrastructure.
+
+## 0.4.0
+
+### Minor Changes
+
+- [#77](https://github.com/infrascan/infrascan/pull/77) [`21d4ecf`](https://github.com/infrascan/infrascan/commit/21d4ecf4b7fec31f4ac7b2cc5857aa5d2b725075) Thanks [@lfarrel6](https://github.com/lfarrel6)! - Add in-memory graph model to decouple the infrascan packages from a single graphing library, and to make graph manipulation easier
+
 ## 0.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infrascan/shared-types",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Shared types for multiple infrascan packages",
   "main": "src/index.ts",
   "scripts": {

package/src/api.ts

@@ -1,6 +1,6 @@
 import type { AwsCredentialIdentityProvider, RetryStrategy, RetryStrategyV2 } from "@aws-sdk/types";
 
-import type { GraphEdge, GraphNode } from "./graph";
+import type { SelectedEdge, SelectedNode } from "./graph";
 import type { BaseEdgeResolver } from "./config";
 
 /**
@@ -85,9 +85,9 @@ type GetterFn<T, P extends Provider> = (
 type GetNodeFn<T extends Provider> = (
   stateConnector: Connector,
   context: ProviderContextMap[T],
-) => Promise<GraphNode[]>;
+) => Promise<SelectedNode[]>;
 
-type GetEdgeFn = (stateConnector: Connector) => Promise<GraphEdge[]>;
+type GetEdgeFn = (stateConnector: Connector) => Promise<SelectedEdge[]>;
 
 export type Provider = "aws";
 
@@ -106,15 +106,6 @@ export type ProviderContext<T extends Provider> = {
   context: ProviderContextMap[T];
 };
 
-type FormatNodeFn<P extends Provider> = (
-  node: GraphNode,
-  context: ProviderContextMap[P],
-) => GraphNode;
-type FormatEdgeFn<P extends Provider> = (
-  node: GraphEdge,
-  context: ProviderContextMap[P],
-) => GraphEdge;
-
 export type EntityRoleData = {
   roleArn: string;
   executor: string;
@@ -131,9 +122,7 @@ export interface ServiceModule<T, P extends Provider> {
   getters: GetterFn<T, P>[];
   nodes?: string[];
   getNodes?: GetNodeFn<P>;
-  formatNode?: FormatNodeFn<P>;
   edges?: BaseEdgeResolver[];
   getEdges?: GetEdgeFn;
-  formatEdge?: FormatEdgeFn<P>;
   getIamRoles?: GetIamRoleFn;
 }

package/src/graph.ts

@@ -1,105 +1,89 @@
 /**
  * A node returned from a state selector before its been formatted for a graphing library
  */
-export type SelectedNode = {
+export interface SelectedNode {
   id: string;
   name?: string;
   parent?: string;
   type?: string;
   rawState?: any;
-};
+}
 
-/**
- * A node on the graph
- */
-export type GraphNode = {
-  group: "nodes";
-  id: string;
-  data: {
-    id: string;
-    type: string;
-    /**
-     * Parent node (account, region etc)
-     */
-    parent?: string;
-    name?: string;
-    service?: string;
-  };
-  /* eslint-disable @typescript-eslint/no-explicit-any */
-  metadata?: any;
-};
+export interface SelectedEdgeTarget {
+  name: string;
+  target: string;
+}
 
-/**
- * An edge connecting two nodes within a graph
- */
-export type GraphEdge = {
-  group: "edges";
-  /**
-   * Unique ID for the edge
-   */
-  id?: string;
-  data: {
-    id: string;
-    name: string;
-    /**
-     * Source Node
-     */
-    source: string;
-    /**
-     * Target Node
-     */
-    target: string;
-    type: string;
-  };
-  metadata?: {
-    label: string;
-    roleArn?: string;
-    /* eslint-disable @typescript-eslint/no-explicit-any */
-    statement?: any;
-  };
+export interface SelectedEdge {
+  source: string;
+  target: string;
+  metadata?: Record<string, unknown>;
+}
+
+// Create Read/Write types inspired by kysely
+export type ElementType<ReadType, WriteType> = {
+  readonly _read: ReadType;
+  readonly _write: WriteType;
 };
 
-/**
- * Generic type for elements in a graph
- */
-export type GraphElement = GraphNode | GraphEdge;
+export type ElementRecord<K extends keyof any, R, W> = ElementType<
+  Record<K, Readable<R>>,
+  Record<K, Writable<W>>
+>;
 
-export type EdgeTarget = {
-  name: string;
-  target: string;
+export type ReadType<T> = T extends ElementType<infer R, any> ? Readable<R> : T;
+export type Readable<T> = {
+  [K in keyof T]: ReadType<T[K]>;
+};
+
+export type WriteType<T> = T extends ElementType<any, infer W>
+  ? Writable<W>
+  : T;
+export type Writable<T> = {
+  [K in keyof T]: WriteType<T[K]>;
 };
 
 export interface Node {
-  id: string,
-  name: string,
+  id: string;
+  name: string;
   metadata: Record<string, unknown>;
-  service?: string,
-  type?: string,
-  parent?: string | Node,
-  children?: Record<string, Node>,
-  incomingEdges: Record<string, Edge<Node>>,
-  outgoingEdges: Record<string, Edge<Node>>,
+  service?: string;
+  type?: string;
+  parent?: ElementType<Node, string>;
+  children?: ElementRecord<string, Node, string>;
+  incomingEdges: ElementRecord<string, Edge, string>;
+  outgoingEdges: ElementRecord<string, Edge, string>;
 }
 
-export interface Edge<T extends string | Node> {
-  id: string,
-  name?: string,
-  metadata: Record<string, unknown>,
-  source: T,
-  target: T
+export interface Edge {
+  id: string;
+  name?: string;
+  metadata: Record<string, unknown>;
+  source: ElementType<Node, string>;
+  target: ElementType<Node, string>;
 }
 
 export interface Graph {
-  nodes: Node[],
-  edges: Edge<Node>[],
-  addNode: (node: Pick<Node, "id" | "name" | "metadata" | "parent" | "service" | "type">) => void,
-  addEdge: (edge: Pick<Edge<string>, "name" | "source" | "target" | "metadata">) => void,
-  addChild: (parent: string, child: string) => void,
-  getNode: (id: string) => Node | undefined,
-  mapNodesById: (id: string, mapperFn: (node: Node) => Node[]) => void,
-  removeEdge: (id: string) => Edge<Node>,
-  removeNode: (id: string) => Node,
-  serialize: () => string
-};
+  nodes: Readable<Node>[];
+  edges: Readable<Edge>[];
+  addNode: (
+    node: Pick<
+      Writable<Node>,
+      "id" | "name" | "metadata" | "parent" | "service" | "type"
+    >,
+  ) => void;
+  addEdge: (
+    edge: Pick<Writable<Edge>, "name" | "source" | "target" | "metadata">,
+  ) => void;
+  addChild: (parent: string, child: string) => void;
+  getNode: (id: string) => Readable<Node> | undefined;
+  mapNodesById: (
+    id: string,
+    mapperFn: (node: Readable<Node>) => Writable<Node>[],
+  ) => void;
+  removeEdge: (id: string) => Readable<Edge>;
+  removeNode: (id: string) => Readable<Node>;
+  serialize: () => string;
+}
 
-export type GraphSerializer<T> = (graph: Graph) => T;
+export type GraphSerializer<T> = (graph: Graph) => T;

package/src/index.ts

@@ -2,3 +2,4 @@ export * from "./api";
 export * from "./config";
 export * from "./graph";
 export * from "./scan";
+export * from "./plugins";

package/src/plugins.ts

@@ -0,0 +1,42 @@
+import { Graph } from "./graph";
+import { AwsContext } from "./api";
+
+// All supported events to trigger a plugin
+export type GraphPluginEvents = "onServiceComplete" | "onRegionComplete" | "onAccountComplete" | "onGraphComplete";
+
+/**
+ * A plugin which is called everytime a service's nodes have been added to the graph.
+ * Receives the current graph state, the service ID, and the current AWS Context.
+ */
+export type OnServiceCompletePlugin = (graph: Graph, service: string, context: AwsContext) => void | Promise<void>;
+
+/**
+ * A plugin which is called everytime a region's nodes have been added to the graph.
+ * Receives the current graph state, and the current AWS Context.
+ */
+export type OnRegionCompletePlugin = (graph: Graph, context: AwsContext) => void | Promise<void>;
+
+/**
+ * A plugin which is called everytime an account's nodes have been added to the graph.
+ * Receives the current graph state, and the current AWS Context.
+ */
+export type OnAccountCompletePlugin = (graph: Graph, context: AwsContext) => void | Promise<void>;
+
+/**
+ * A plugin which is called when the entire graph has been generated.
+ * Receives the entire graph state.
+ */
+export type OnGraphCompletePlugin = (graph: Graph) => void | Promise<void>;
+
+export type PluginEventHandlerTypes = {
+    "onServiceComplete": OnServiceCompletePlugin,
+    "onRegionComplete": OnRegionCompletePlugin,
+    "onAccountComplete": OnAccountCompletePlugin,
+    "onGraphComplete": OnGraphCompletePlugin,
+};
+
+export interface GraphPlugin<E extends GraphPluginEvents> {
+    id: string,
+    event: E,
+    handler: PluginEventHandlerTypes[E]
+}

package/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "tsconfig/base.json",
+  "extends": "@infrascan/tsconfig/base.json",
   "compilerOptions": {
     "baseUrl": "src",
     "noEmit": true,