@davidsouther/agathon 0.0.0-stage → 0.0.0

package/src/types.ts

@@ -0,0 +1,424 @@
+/** An ID for a node. */
+export type NodeId = string;
+/** An nominal ID type for an Edge. */
+export type EdgeId = string;
+/** An nominal ID type for a Segment. */
+export type SegmentId = string;
+
+/** The height/width of the currently displayed graph area */
+export interface Bounds {
+  width: number;
+  height: number;
+}
+
+/** An x/y position in 2d space. */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * A point object that is just a tuple of 2 numbers. Used throughout graph_utils
+ * (which thinks about points as vectors)
+ */
+export type PointTuple = [number, number];
+
+/**
+ * A circle has a center <x, y> and a radius <r>.
+ */
+export interface Circle extends Point {
+  r: number;
+}
+
+/**
+ * A stripped-down version of NodeCircle, used for calculations that require a
+ * map of node id's to their radii.
+ */
+export interface NodeRadius {
+  id: NodeId;
+  r: number;
+}
+
+/**
+ * A circle that has an ID of the node it represents
+ */
+export interface NodeCircle extends Circle {
+  id: NodeId;
+}
+
+/**
+ * An axis-aligned box is a point in 2d space with an associated height and
+ * width of area to cover.
+ */
+export interface Box extends Point, Bounds {}
+
+/**
+ * An incoming set of data to be expanded into a Graph.
+ */
+export interface GraphData<N extends Node, E extends Edge> {
+  nodes: Iterable<N>;
+  edges: Iterable<E>;
+}
+
+/**
+ * A graph specifically using Node and Edge, rather than {} {}.
+ */
+export type FullGraph = SmartGraph<Node, Edge>;
+
+/**
+ * A graph contains a set of Nodes and Edges, as well as providing a variety of
+ * convenient accessors. Graphs are directed, are allowed multiple edges, and
+ * are compound. Implicitly, then, undirected graphs should set both edges;
+ * non-compound graphs simply don't use the `parent` functionality, and simple
+ * graphs don't use the `name` field of edges. SmartGraphs track Topology
+ * segments, which are bundles of edges following the nested graph hierarchy.
+ *
+ * For definitions of descendants, ancestors, parents, siblings, etc, see
+ * https://sebastian.expert/ancestor-descendant-sibling-parent-child-explained/
+ * https://en.wikipedia.org/wiki/Tree_(data_structure)#Terminology_used_in_trees
+ */
+export interface ReadonlySmartGraph<NodeValue, EdgeValue> {
+  readonly nodeCount: number;
+  readonly edgeCount: number;
+  readonly segmentCount: number;
+
+  readonly nodes: Set<NodeId>;
+  readonly allNodes: Iterable<NodeValue>;
+  readonly allEdges: Iterable<EdgeValue>;
+  readonly allSegments: Iterable<Segment<EdgeValue>>;
+  readonly topSegments: Iterable<Segment<EdgeValue>>;
+  readonly sinks: Set<NodeId>;
+  readonly sources: Set<NodeId>;
+
+  node(id?: NodeId): NodeValue | undefined;
+  hasNode(id?: NodeId): boolean;
+
+  edge(edge: Edge): EdgeValue | undefined;
+  hasEdge(edge: Edge): boolean;
+  hasSegment(segment: Segment): boolean;
+
+  /**
+   * Return all edges for a given node to a given neighbor. If no neighbor is
+   * specified, returns all edges for the given node. If no node specified,
+   * returns all edges in the graph.
+   */
+  edges(id?: NodeId, neighbor?: NodeId): Iterable<Edge>;
+  inEdges(id: NodeId, source?: NodeId): Iterable<Edge>;
+  outEdges(id: NodeId, target?: NodeId): Iterable<Edge>;
+
+  /**
+   * Returns the ID of the parent node. Graph implementations should include a
+   * root parent node ID that is not a member of the node set. To validate that
+   * a parent is part of the graph, callers can use `hasParent` on a node, or
+   * `hasNode` on the id returned from `parent`.
+   */
+  parent(id: NodeId): NodeId;
+
+  /**
+   * Returns children of the given node. If no node ID is given, returns all top
+   * level nodes (nodes without a parent).
+   */
+  children(id?: NodeId): Set<NodeId>;
+  hasChildren(id?: NodeId): boolean;
+  hasParent(id: NodeId): boolean;
+
+  /**
+   * Returns all descendants of the given node. If no ID specified, will return
+   * all nodes in the entire graph.
+   *
+   * This will not include the starting node, to avoid double counting the ID
+   * when combining ancestors and descendants.
+   */
+  descendants(id?: NodeId): Set<NodeId>;
+
+  /**
+   * A list of NodeIds from the given ID to the root, starting from the node.
+   * If no node is given, returns an empty array.
+   */
+  ancestors(id?: NodeId): NodeId[];
+
+  /**
+   * The predecessors of a node are all nodes which are the source of an edge
+   * with that node as a target. That is, the nodes at the other end of inEdges.
+   */
+  predecessors(id: NodeId): Set<NodeId>;
+
+  /**
+   * The successors of a node are all nodes which are the target of an edge
+   * with that node as a source. That is, the nodes at the other end of
+   * outEdges.
+   */
+  successors(id: NodeId): Set<NodeId>;
+  neighbors(id: NodeId): Set<NodeId>;
+  isLeaf(id: NodeId): boolean;
+
+  /**
+   * Find the top-level segment between a and b, if it exists. If there is no
+   * segment between a and b, or if a or be are not top-level nodes, this
+   * returns undefined.
+   */
+  topSegment(a: NodeId, b: NodeId): Segment<EdgeValue> | undefined;
+
+  /**
+   * Returns true if the segment exists in the graph and if it is between two
+   * top-level nodes.
+   */
+  isTopSegment(s: Segment<EdgeValue>): boolean;
+
+  /**
+   * All segments with id as either their source or target.
+   */
+  nodeSegments(id: NodeId): Iterable<Segment<EdgeValue>>;
+
+  /**
+   * Returns all segments with the given edge in their bundle.
+   */
+  edgeSegments(edge: Edge): Iterable<Segment<EdgeValue>>;
+
+  /**
+   * Returns segments for successor edges from this node.
+   * If no edges start from this node itself (as opposed to its children), this
+   * will be empty. This is equivalent to calling edgeSegments on every outgoing
+   * edge from a node.
+   */
+  successorSegments(id?: NodeId): Iterable<Segment<EdgeValue>>;
+
+  /**
+   * Returns all sibling segments between children of the given node.
+   */
+  childSegments(id?: NodeId): Iterable<Segment<EdgeValue>>;
+
+  /**
+   * Returns segments for predecessor edges from this node.
+   * If no edges point to this node itself (as opposed to its children), this
+   * will be empty. This is equivalent to calling edgeSegments on every incoming
+   * edge to a node.
+   */
+  predecessorSegments(id?: NodeId): Iterable<Segment<EdgeValue>>;
+
+  /**
+   * Returns the combination of predecessor and successor segments. This
+   * includes all segments for all edges on this node.
+   */
+  segmentNeighborhood(id?: NodeId): Iterable<Segment<EdgeValue>>;
+
+  /**
+   * Return all segments that either point from a child to that node, or point
+   * between two children of that node. If no nodeId is provided, find segments
+   * between top level nodes only.
+   */
+  segmentsUnderNode(nodeId?: NodeId): Iterable<Segment<EdgeValue>>;
+
+  /**
+   * Given an edge and a segment, return the direction the edge follows along
+   * the segment. Because segments are stored in a normalized fashion, it is
+   * necessary to recover the underlying edge direction(s) when computing
+   * display values for edges. See discussion in EdgeDirectionAlongSegment for
+   * further details.
+   */
+  edgeDirectionAlongSegment(edge: Edge, segment: Segment<EdgeValue>): EdgeDirectionAlongSegment;
+}
+
+/**
+ * A graph contains a set of Nodes and Edges, as well as providing a variety of
+ * convenient accessors. Graphs are directed, are allowed multiple edges, and
+ * are compound. Implicitly, then, undirected graphs should set both edges;
+ * non-compound graphs simply don't use the `parent` functionality, and simple
+ * graphs don't use the `name` field of edges. SmartGraphs track Topology
+ * segments, which are bundles of edges following the nested graph hierarchy.
+ */
+export interface SmartGraph<NodeValue, EdgeValue> extends ReadonlySmartGraph<NodeValue, EdgeValue> {
+  readonly violations: ReadonlyArray<GraphViolation>;
+
+  setNode(id: NodeId, value: NodeValue): this;
+  removeNode(id: NodeId): this;
+  setParent(id: NodeId, parent: NodeId | undefined): this;
+
+  setEdge(edge: Edge, value: EdgeValue): this;
+  removeEdge(edge: Edge): this;
+}
+
+/**
+ * A node is required to have an ID, and may optionally have a parent to
+ * specify hierarchies aside from edge connections.
+ */
+export type Node<T = unknown> = T & {
+  id: NodeId;
+  parent?: NodeId;
+};
+
+/**
+ * An edge connects two nodes. Pairs of nodes may be connected by multiple
+ * edges by naming them uniquely.
+ */
+export type Edge<T = unknown> = T & {
+  source: NodeId;
+  target: NodeId;
+  name?: string;
+};
+
+/**
+ * Segments are bundles of graph edges along parent hierarchies. For any given
+ * edge, the source and target nodes may not share a parent. In this case, the
+ * graph creates `segments` up the source parent hierarchy, across to the
+ * sibling ancestor of the target node, and back down. Segments are always
+ * directed up the tree, except when crossing siblings, in which case source
+ * and target are set consistently. Segments contain a set of all edges which
+ * pass through them, as well as a link to the next segment up the chain (except
+ * segments between sibling nodes) as well as a set of all segments which
+ * contain it as their `next` link.
+ */
+export interface Segment<TEdge = unknown> extends DiffableGraphElement {
+  source: NodeId;
+  target: NodeId;
+  next?: Segment<TEdge>;
+  previous: Set<Segment<TEdge>>;
+  edges: Set<TEdge>;
+}
+
+/**
+ * An edge can cross a segment Source to Target or Target to Source (from the
+ * segment's perspective).
+ *
+ * ```
+ * digraph {
+ *   A { A_A; }
+ *   B { B_B; }
+ *   B_B -> A_A;
+ *   A -> B;
+ * }
+ * ```
+ *
+ * The edge `A -> B` crosses segment `A ~ B` S to T, while `B_B -> A_A` crosses
+ * `A ~ B` T to S. Similarly, `B_B -> A_A` crosses `A_A ~ A` T to S and `B_B ~
+ * B` S to T.
+ */
+export const EdgeDirectionAlongSegment = {
+  NOT_CROSSING: "NOT_CROSSING",
+  SOURCE_TARGET: "SOURCE_TARGET",
+  TARGET_SOURCE: "TARGET_SOURCE",
+} as const;
+export type EdgeDirectionAlongSegment =
+  (typeof EdgeDirectionAlongSegment)[keyof typeof EdgeDirectionAlongSegment];
+
+/**
+ * When mutating a graph, many operations result in invalid states. Adding an
+ * edge with a non-existent neighbor, setting a parent to a missing node, or
+ * removing a node that hasn't been added are all "errors", but might happen
+ * from unexpected data integrity issues. Rather than throwing an error and
+ * possibly failing the entire batch operation for a missing edge, SmartGraph
+ * instead will perform a noop and log the constraint which was violated.
+ */
+export type GraphViolation = NodeViolation | ParentViolation | EdgeViolation;
+
+/**
+ * The types of possible graph constraint violations.
+ */
+export const GraphViolationType = {
+  /** Violation when attempting to remove a node that isn't present. */
+  REMOVE_NODE_VIOLATION: "REMOVE_NODE_VIOLATION",
+  /**
+   * Violation when attempting to set the parent of a node that isn't present.
+   */
+  CHILD_NODE_VIOLATION: "CHILD_NODE_VIOLATION",
+  /**
+   * Violation when attempting to set a node as a child of a node that isn't
+   * present.
+   */
+  PARENT_NODE_VIOLATION: "PARENT_NODE_VIOLATION",
+  /**
+   * Violation when attempting to create an edge where either the source or the
+   * target isn't present.
+   */
+  EDGE_VIOLATION: "EDGE_VIOLATION",
+  /** Violation when attempting to create an edge that isn't present. */
+  REMOVE_EDGE_VIOLATION: "REMOVE_EDGE_VIOLATION",
+} as const;
+export type GraphViolationType = (typeof GraphViolationType)[keyof typeof GraphViolationType];
+
+/**
+ * A violation of a single node constraint.
+ */
+export interface NodeViolation {
+  violation:
+    | typeof GraphViolationType.CHILD_NODE_VIOLATION
+    | typeof GraphViolationType.REMOVE_NODE_VIOLATION;
+  node: NodeId;
+}
+
+/**
+ * A violation of a node / parent constraint.
+ */
+export interface ParentViolation {
+  violation: typeof GraphViolationType.PARENT_NODE_VIOLATION;
+  node: NodeId;
+  parent: NodeId;
+}
+
+/**
+ * A violation of an edge constraint.
+ */
+export interface EdgeViolation {
+  violation:
+    | typeof GraphViolationType.EDGE_VIOLATION
+    | typeof GraphViolationType.REMOVE_EDGE_VIOLATION;
+  source: NodeId;
+  target: NodeId;
+  name?: string;
+}
+
+/**
+ * An attribute set maintains a map of name -> value, with utilities to get
+ * values as strings, numbers, and boolean. Attribute names are case
+ * insensitive.
+ */
+export interface AttributeSet {
+  hasAttribute(attribute: string): boolean;
+  asNumber(attribute: string): number;
+  asNumber(attribute: string, defaultValue: number): number;
+  asBoolean(attribute: string): boolean;
+  asBoolean(attribute: string, defaultValue: boolean): boolean;
+  asString(attribute: string): string;
+  asString(attribute: string, defaultValue: string): string;
+  asJson<T>(attribute: string): T | undefined;
+  asJson<T>(attribute: string, defaultValue: T): T;
+}
+
+/**
+ * Simple enum to identify which time interval an element is from (left, right,
+ * or both).
+ */
+export const ElementDiffPresence = {
+  LEFT: "left",
+  RIGHT: "right",
+  BOTH: "both",
+} as const;
+export type ElementDiffPresence = (typeof ElementDiffPresence)[keyof typeof ElementDiffPresence];
+
+/**
+ * Basic interface describing graph elements that can have a left/right diff
+ * state.
+ */
+export interface DiffableGraphElement {
+  presence?: ElementDiffPresence;
+}
+
+/**
+ * Any additional link related data we should take into consideration when
+ * fetching metrics for that link.
+ */
+export interface EdgeContext<T = {}, TEdge = {}> {
+  scopeNode: Node<T>;
+  sourceNode: Node<T>;
+  targetNode: Node<T>;
+  segments?: Array<Segment<TEdge>>;
+}
+
+/**
+ * Object that specifies a metric value to be added to an edge between 2 nodes
+ */
+export interface EdgeAnnotation<V, T = {}> {
+  source: Node<T>;
+  target: Node<T>;
+  value?: V;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.