@infrascan/shared-types 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @infrascan/shared-types
 
+## 0.5.1
+
+### Patch Changes
+
+- [#84](https://github.com/infrascan/infrascan/pull/84) [`437026c`](https://github.com/infrascan/infrascan/commit/437026cc278ec4b380bcaf3a7a675f3762ce3bea) Thanks [@lfarrel6](https://github.com/lfarrel6)! - Bump aws client sdk versions to remove vulnerable dependency
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infrascan/shared-types",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Shared types for multiple infrascan packages",
   "main": "src/index.ts",
   "scripts": {
@@ -12,7 +12,7 @@
   "author": "Liam Farrelly <liam@l3f7.dev> (https://whoisli.am/)",
   "license": "MPL-2.0",
   "devDependencies": {
-    "@aws-sdk/types": "3.428.0",
+    "@aws-sdk/types": "3.609.0",
     "eslint-config-custom": "*",
     "tsconfig": "*",
     "typescript": "^5.1.6"

package/src/api.ts

@@ -1,4 +1,8 @@
-import type { AwsCredentialIdentityProvider, RetryStrategy, RetryStrategyV2 } from "@aws-sdk/types";
+import type {
+  AwsCredentialIdentityProvider,
+  RetryStrategy,
+  RetryStrategyV2,
+} from "@aws-sdk/types";
 
 import type { SelectedEdge, SelectedNode } from "./graph";
 import type { BaseEdgeResolver } from "./config";
@@ -73,7 +77,7 @@ export interface Connector {
 type ClientBuilder<T, P extends Provider> = (
   credentials: AwsCredentialIdentityProvider,
   context: ProviderContextMap[P],
-  retryStrategy?: RetryStrategy | RetryStrategyV2
+  retryStrategy?: RetryStrategy | RetryStrategyV2,
 ) => T;
 
 type GetterFn<T, P extends Provider> = (

package/src/config.ts

@@ -47,10 +47,8 @@ export type BaseScannerDefinition = {
 };
 
 type AsCommand<S extends string> = `${S}Command`;
-export type AvailableCommand<
-  Serv extends object,
-  Funcs extends string,
-> = AsCommand<Funcs> extends `${infer P}Command` & keyof Serv ? P : never;
+export type AvailableCommand<Serv extends object, Funcs extends string> =
+  AsCommand<Funcs> extends `${infer P}Command` & keyof Serv ? P : never;
 
 export type StateSelector<
   ServiceName extends string,

package/src/graph.ts

@@ -7,50 +7,83 @@ export interface SelectedNode {
   parent?: string;
   type?: string;
   rawState?: any;
-};
+}
 
 export interface SelectedEdgeTarget {
-  name: string,
-  target: string
+  name: string;
+  target: string;
 }
 
 export interface SelectedEdge {
   source: string;
   target: string;
-  metadata?: Record<string, unknown>
+  metadata?: Record<string, unknown>;
+}
+
+// Create Read/Write types inspired by kysely
+export type ElementType<ReadType, WriteType> = {
+  readonly _read: ReadType;
+  readonly _write: WriteType;
+};
+
+export type ElementRecord<K extends keyof any, R, W> = ElementType<
+  Record<K, Readable<R>>,
+  Record<K, Writable<W>>
+>;
+
+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

@@ -1,5 +1,5 @@
 export * from "./api";
 export * from "./config";
 export * from "./graph";
-export * from "./scan";
-export * from "./plugins";
+export * from "./plugins";
+export * from "./scan";

package/src/plugins.ts

@@ -2,25 +2,39 @@ import { Graph } from "./graph";
 import { AwsContext } from "./api";
 
 // All supported events to trigger a plugin
-export type GraphPluginEvents = "onServiceComplete" | "onRegionComplete" | "onAccountComplete" | "onGraphComplete";
+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>;
+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>;
+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>;
+export type OnAccountCompletePlugin = (
+  graph: Graph,
+  context: AwsContext,
+) => void | Promise<void>;
 
 /**
  * A plugin which is called when the entire graph has been generated.
@@ -29,14 +43,14 @@ export type OnAccountCompletePlugin = (graph: Graph, context: AwsContext) => voi
 export type OnGraphCompletePlugin = (graph: Graph) => void | Promise<void>;
 
 export type PluginEventHandlerTypes = {
-    "onServiceComplete": OnServiceCompletePlugin,
-    "onRegionComplete": OnRegionCompletePlugin,
-    "onAccountComplete": OnAccountCompletePlugin,
-    "onGraphComplete": OnGraphCompletePlugin,
+  onServiceComplete: OnServiceCompletePlugin;
+  onRegionComplete: OnRegionCompletePlugin;
+  onAccountComplete: OnAccountCompletePlugin;
+  onGraphComplete: OnGraphCompletePlugin;
 };
 
 export interface GraphPlugin<E extends GraphPluginEvents> {
-    id: string,
-    event: E,
-    handler: PluginEventHandlerTypes[E]
-}
+  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,