@griffin-app/griffin-ts 0.1.0

package/src/assertions.ts

@@ -0,0 +1,327 @@
+/**
+ * Rich assertion DSL for constructing type-safe test assertions with JSONPath support.
+ *
+ * This module provides:
+ * - StateProxy: Tracks node access patterns and converts them to JSONPath
+ * - Assert: Builder for creating assertions with fluent API
+ * - Support for unary and binary predicates with negation
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Identifies which node and which part of its result we're asserting on
+ */
+export interface PathDescriptor {
+  nodeId: string;
+  accessor: "body" | "headers" | "status";
+  path: string[]; // JSONPath segments (e.g., ["data", "id"])
+}
+
+/**
+ * Unary predicates that check a property without comparing to a value
+ */
+export enum UnaryPredicate {
+  IS_NULL = "IS_NULL",
+  IS_NOT_NULL = "IS_NOT_NULL",
+  IS_TRUE = "IS_TRUE",
+  IS_FALSE = "IS_FALSE",
+  IS_EMPTY = "IS_EMPTY",
+  IS_NOT_EMPTY = "IS_NOT_EMPTY",
+}
+
+/**
+ * Binary predicate operators that compare against an expected value
+ */
+export enum BinaryPredicateOperator {
+  EQUAL = "EQUAL",
+  NOT_EQUAL = "NOT_EQUAL",
+  GREATER_THAN = "GREATER_THAN",
+  LESS_THAN = "LESS_THAN",
+  GREATER_THAN_OR_EQUAL = "GREATER_THAN_OR_EQUAL",
+  LESS_THAN_OR_EQUAL = "LESS_THAN_OR_EQUAL",
+  CONTAINS = "CONTAINS",
+  NOT_CONTAINS = "NOT_CONTAINS",
+  STARTS_WITH = "STARTS_WITH",
+  NOT_STARTS_WITH = "NOT_STARTS_WITH",
+  ENDS_WITH = "ENDS_WITH",
+  NOT_ENDS_WITH = "NOT_ENDS_WITH",
+}
+
+/**
+ * Binary predicate with operator and expected value
+ */
+export interface BinaryPredicate {
+  operator: BinaryPredicateOperator;
+  expected: unknown;
+}
+
+/**
+ * Serialized assertion ready for execution
+ */
+export interface SerializedAssertion {
+  nodeId: string;
+  accessor: "body" | "headers" | "status";
+  path: string[];
+  predicate: UnaryPredicate | BinaryPredicate;
+}
+
+// ============================================================================
+// State Proxy
+// ============================================================================
+
+/**
+ * Symbol used to store path metadata in proxy objects
+ */
+const PATH_SYMBOL = Symbol("__path__");
+
+/**
+ * Internal interface for proxy objects that carry path information
+ */
+interface ProxyWithPath {
+  [PATH_SYMBOL]: PathDescriptor;
+}
+
+/**
+ * Proxy for accessing nested properties within a node result accessor (body, headers, status)
+ * Note: The 'at' method is available at runtime but typed as NestedProxy for simplicity
+ */
+export type NestedProxy = ProxyWithPath & {
+  [key: string]: NestedProxy;
+};
+
+/**
+ * Proxy for a node result with body, headers, and status accessors
+ */
+export type NodeResultProxy = {
+  body: NestedProxy;
+  headers: NestedProxy;
+  status: NestedProxy;
+};
+
+/**
+ * State proxy that maps node names to their result proxies
+ */
+export type StateProxy<NodeNames extends string = string> = {
+  [K in NodeNames]: NodeResultProxy;
+};
+
+/**
+ * Creates a nested proxy that accumulates path segments
+ */
+function createNestedProxy(descriptor: PathDescriptor): NestedProxy {
+  return new Proxy({} as NestedProxy, {
+    get(_, prop: string | symbol) {
+      if (prop === PATH_SYMBOL) {
+        return descriptor;
+      }
+      if (prop === "at") {
+        return (index: number) => {
+          return createNestedProxy({
+            ...descriptor,
+            path: [...descriptor.path, String(index)],
+          });
+        };
+      }
+      // Accumulate string property access
+      return createNestedProxy({
+        ...descriptor,
+        path: [...descriptor.path, String(prop)],
+      });
+    },
+  });
+}
+
+/**
+ * Creates a proxy for a node result with body, headers, and status accessors
+ */
+function createNodeResultProxy(nodeId: string): NodeResultProxy {
+  return {
+    body: createNestedProxy({ nodeId, accessor: "body", path: [] }),
+    headers: createNestedProxy({ nodeId, accessor: "headers", path: [] }),
+    status: createNestedProxy({ nodeId, accessor: "status", path: [] }),
+  };
+}
+
+/**
+ * Creates a state proxy for the given node names
+ */
+export function createStateProxy<NodeNames extends string>(
+  nodeNames: NodeNames[],
+): StateProxy<NodeNames> {
+  const proxy = new Proxy(
+    {},
+    {
+      get(_, nodeName: string | symbol) {
+        if (typeof nodeName === "symbol") {
+          return undefined;
+        }
+        return createNodeResultProxy(nodeName);
+      },
+    },
+  );
+  return proxy as StateProxy<NodeNames>;
+}
+
+// ============================================================================
+// Assert Builder
+// ============================================================================
+
+export class AssertBuilder {
+  private negated = false;
+
+  constructor(private descriptor: PathDescriptor) {}
+
+  /**
+   * Negation modifier - flips the meaning of the subsequent predicate
+   *
+   * @example
+   * Assert(state["node"].body["id"]).not.isNull()  // IS_NOT_NULL
+   * Assert(state["node"].body["name"]).not.equals("") // NOT_EQUAL
+   */
+  get not(): this {
+    const negatedBuilder = new AssertBuilder(this.descriptor);
+    negatedBuilder.negated = !this.negated;
+    return negatedBuilder as this;
+  }
+
+  // Unary predicates
+
+  isNull(): SerializedAssertion {
+    return this.createAssertion(
+      this.negated ? UnaryPredicate.IS_NOT_NULL : UnaryPredicate.IS_NULL,
+    );
+  }
+
+  isDefined(): SerializedAssertion {
+    return this.createAssertion(
+      this.negated ? UnaryPredicate.IS_NULL : UnaryPredicate.IS_NOT_NULL,
+    );
+  }
+
+  isTrue(): SerializedAssertion {
+    return this.createAssertion(
+      this.negated ? UnaryPredicate.IS_FALSE : UnaryPredicate.IS_TRUE,
+    );
+  }
+
+  isFalse(): SerializedAssertion {
+    return this.createAssertion(
+      this.negated ? UnaryPredicate.IS_TRUE : UnaryPredicate.IS_FALSE,
+    );
+  }
+
+  isEmpty(): SerializedAssertion {
+    return this.createAssertion(
+      this.negated ? UnaryPredicate.IS_NOT_EMPTY : UnaryPredicate.IS_EMPTY,
+    );
+  }
+
+  // Binary predicates
+
+  equals(expected: unknown): SerializedAssertion {
+    return this.createAssertion({
+      operator: this.negated
+        ? BinaryPredicateOperator.NOT_EQUAL
+        : BinaryPredicateOperator.EQUAL,
+      expected,
+    });
+  }
+
+  greaterThan(expected: number): SerializedAssertion {
+    return this.createAssertion({
+      operator: this.negated
+        ? BinaryPredicateOperator.LESS_THAN_OR_EQUAL
+        : BinaryPredicateOperator.GREATER_THAN,
+      expected,
+    });
+  }
+
+  lessThan(expected: number): SerializedAssertion {
+    return this.createAssertion({
+      operator: this.negated
+        ? BinaryPredicateOperator.GREATER_THAN_OR_EQUAL
+        : BinaryPredicateOperator.LESS_THAN,
+      expected,
+    });
+  }
+
+  greaterThanOrEqual(expected: number): SerializedAssertion {
+    return this.createAssertion({
+      operator: this.negated
+        ? BinaryPredicateOperator.LESS_THAN
+        : BinaryPredicateOperator.GREATER_THAN_OR_EQUAL,
+      expected,
+    });
+  }
+
+  lessThanOrEqual(expected: number): SerializedAssertion {
+    return this.createAssertion({
+      operator: this.negated
+        ? BinaryPredicateOperator.GREATER_THAN
+        : BinaryPredicateOperator.LESS_THAN_OR_EQUAL,
+      expected,
+    });
+  }
+
+  contains(expected: string): SerializedAssertion {
+    return this.createAssertion({
+      operator: this.negated
+        ? BinaryPredicateOperator.NOT_CONTAINS
+        : BinaryPredicateOperator.CONTAINS,
+      expected,
+    });
+  }
+
+  startsWith(expected: string): SerializedAssertion {
+    return this.createAssertion({
+      operator: this.negated
+        ? BinaryPredicateOperator.NOT_STARTS_WITH
+        : BinaryPredicateOperator.STARTS_WITH,
+      expected,
+    });
+  }
+
+  endsWith(expected: string): SerializedAssertion {
+    return this.createAssertion({
+      operator: this.negated
+        ? BinaryPredicateOperator.NOT_ENDS_WITH
+        : BinaryPredicateOperator.ENDS_WITH,
+      expected,
+    });
+  }
+
+  private createAssertion(
+    predicate: UnaryPredicate | BinaryPredicate,
+  ): SerializedAssertion {
+    return {
+      nodeId: this.descriptor.nodeId,
+      accessor: this.descriptor.accessor,
+      path: this.descriptor.path,
+      predicate,
+    };
+  }
+}
+
+/**
+ * Creates an assertion builder from a state proxy reference
+ *
+ * @param proxyRef - A reference obtained from the state proxy (e.g., state["node"].body["id"])
+ * @returns An AssertBuilder for constructing the assertion
+ *
+ * @example
+ * Assert(state["create_user"].body["data"]["id"]).not.isNull()
+ * Assert(state["create_user"].status).equals(201)
+ * Assert(state["create_user"].headers["content-type"]).contains("application/json")
+ */
+export function Assert(proxyRef: NestedProxy): AssertBuilder {
+  const descriptor = (proxyRef as ProxyWithPath)[PATH_SYMBOL];
+  if (!descriptor) {
+    throw new Error(
+      "Assert() must be called with a reference from the state proxy",
+    );
+  }
+  return new AssertBuilder(descriptor);
+}

package/src/builder.ts

@@ -0,0 +1,336 @@
+import {
+  TestPlanV1,
+  Node,
+  Edge,
+  Frequency,
+  HttpMethod,
+  ResponseFormat,
+  Endpoint,
+  NodeType,
+  Wait,
+  Assertions,
+  TEST_PLAN_VERSION,
+  JSONAssertion,
+} from "./schema.js";
+import { type START as StartType, type END as EndType } from "./constants";
+
+type RawPlan = Omit<TestPlanV1, "id" | "environment">;
+
+/**
+ * A node definition without the id field.
+ * The id is provided separately to addNode for cleaner separation of concerns.
+ */
+export type NodeWithoutId = Omit<Node, "id">;
+
+/**
+ * TestBuilder provides a type-safe DSL for constructing test plans with compile-time graph validation.
+ *
+ * Type parameters track the state of the graph during construction:
+ * @template NodeName - Union of all registered node names
+ * @template HasOutput - Union of nodes that have outgoing edges
+ * @template HasInput - Union of nodes that have incoming edges
+ */
+export interface TestBuilder<
+  NodeName extends string = never,
+  HasOutput extends string = never,
+  HasInput extends string = never,
+> {
+  /**
+   * Adds a node to the test graph.
+   *
+   * @param name - Unique identifier for this node in the graph
+   * @param node - Node definition (Endpoint, WaitNode, Assertion)
+   * @returns Updated builder with the node registered in NodeName
+   *
+   * @example
+   * ```typescript
+   * builder.addNode("health", Endpoint({ method: GET, path: "/health", response_format: JSON }))
+   * ```
+   */
+  addNode<Name extends string>(
+    name: Name,
+    node: NodeWithoutId,
+  ): TestBuilder<NodeName | Name, HasOutput, HasInput>;
+
+  /**
+   * Adds a directed edge between two nodes in the graph.
+   *
+   * Compile-time constraints:
+   * - `from` must be START or a node that doesn't already have an outgoing edge
+   * - `to` must be END or a node that isn't the same as `from`
+   * - Both nodes must exist (be registered via addNode)
+   *
+   * @param from - Source node name or START constant
+   * @param to - Target node name or END constant
+   * @returns Updated builder with edge tracking updated
+   *
+   * @example
+   * ```typescript
+   * builder
+   *   .addEdge(START, "health")
+   *   .addEdge("health", "wait")
+   *   .addEdge("wait", END)
+   * ```
+   */
+  addEdge<
+    From extends StartType | Exclude<NodeName, HasOutput>,
+    To extends EndType | Exclude<NodeName, From>,
+  >(
+    from: From,
+    to: To,
+  ): TestBuilder<
+    NodeName,
+    From extends StartType ? HasOutput : HasOutput | From,
+    To extends EndType ? HasInput : HasInput | To
+  >;
+
+  /**
+   * Builds the final test plan.
+   *
+   * This method is only callable when all graph constraints are satisfied:
+   * - All nodes must have at least one outgoing edge
+   * - All nodes must have at least one incoming edge
+   *
+   * If constraints aren't met, the return type becomes `never`, causing a compile error.
+   */
+  build: [Exclude<NodeName, HasOutput>] extends [never]
+    ? [Exclude<NodeName, HasInput>] extends [never]
+      ? () => TestPlanV1
+      : {
+          error: "Some nodes have no incoming edges";
+          unconnected: Exclude<NodeName, HasInput>;
+        }
+    : {
+        error: "Some nodes have no outgoing edges";
+        unconnected: Exclude<NodeName, HasOutput>;
+      };
+}
+
+/**
+ * Internal implementation class for TestBuilder.
+ * Uses explicit type assertions at method boundaries to maintain phantom type tracking.
+ */
+class TestBuilderImpl<
+  NodeName extends string = never,
+  HasOutput extends string = never,
+  HasInput extends string = never,
+> {
+  private nodes: Node[] = [];
+  private edges: Edge[] = [];
+
+  constructor(
+    private config: {
+      name: string;
+      frequency?: Frequency;
+      locations?: string[];
+    },
+  ) {}
+
+  addNode<Name extends string>(
+    name: Name,
+    node: NodeWithoutId,
+  ): TestBuilder<NodeName | Name, HasOutput, HasInput> {
+    // Merge the name into the node to create a complete Node
+    // Type assertion required: spreading Omit<Node, 'id'> + id produces a valid Node at runtime
+    this.nodes.push({ ...node, id: name } as unknown as Node);
+    // Type assertion: we've added Name to NodeName union
+    return this as unknown as TestBuilder<NodeName | Name, HasOutput, HasInput>;
+  }
+
+  addEdge<
+    From extends StartType | Exclude<NodeName, HasOutput>,
+    To extends EndType | Exclude<NodeName, From>,
+  >(
+    from: From,
+    to: To,
+  ): TestBuilder<
+    NodeName,
+    From extends StartType ? HasOutput : HasOutput | From,
+    To extends EndType ? HasInput : HasInput | To
+  > {
+    this.edges.push({ from, to });
+    // Type assertion: we've updated HasOutput and HasInput based on edge direction
+    return this as unknown as TestBuilder<
+      NodeName,
+      From extends StartType ? HasOutput : HasOutput | From,
+      To extends EndType ? HasInput : HasInput | To
+    >;
+  }
+
+  get build(): TestBuilder<NodeName, HasOutput, HasInput>["build"] {
+    const { name, frequency, locations } = this.config;
+    const nodes = this.nodes;
+    const edges = this.edges;
+
+    const buildFn = (): RawPlan => {
+      return {
+        name,
+        version: TEST_PLAN_VERSION,
+        frequency,
+        locations,
+        nodes,
+        edges,
+      };
+    };
+
+    // Type assertion: build is only callable when graph constraints are satisfied
+    // The conditional type in TestBuilder['build'] enforces this at the call site
+    return buildFn as TestBuilder<NodeName, HasOutput, HasInput>["build"];
+  }
+}
+
+/**
+ * Creates a new test builder for constructing a test plan.
+ *
+ * @param config - Configuration for the test plan
+ * @param config.name - Name of the test
+ * @param config.frequency - Optional frequency for scheduled execution
+ * @param config.locations - Optional array of location identifiers where this test should run
+ * @returns A new TestBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const plan = createGraphBuilder({
+ *   name: "health-check",
+ *   frequency: Frequency.every(5).minute(),
+ *   locations: ["us-east-1", "eu-west-1"]
+ * })
+ *   .addNode("health", Endpoint({ method: GET, path: "/health", response_format: JSON }))
+ *   .addEdge(START, "health")
+ *   .addEdge("health", END)
+ *   .build();
+ * ```
+ */
+export function createGraphBuilder(config: {
+  name: string;
+  frequency?: Frequency;
+  locations?: string[];
+}): TestBuilder {
+  return new TestBuilderImpl(config);
+}
+
+// ============================================================================
+// Node Factory Functions
+// ============================================================================
+
+/**
+ * Configuration for an Endpoint node
+ * Accepts DSL-friendly literal types which are converted to schema enums internally
+ */
+export interface EndpointConfig {
+  method:
+    | "GET"
+    | "POST"
+    | "PUT"
+    | "DELETE"
+    | "PATCH"
+    | "HEAD"
+    | "OPTIONS"
+    | "CONNECT"
+    | "TRACE";
+  path: string;
+  base: Endpoint["base"];
+  response_format: "JSON" | "XML" | "TEXT";
+  headers?: Record<string, any>;
+  body?: any;
+}
+
+/**
+ * Creates an Endpoint node for making HTTP requests.
+ *
+ * @param config - Endpoint configuration (method, path, base, headers, etc.)
+ * @returns An Endpoint node (without id) ready to be added to a TestBuilder
+ *
+ * @example
+ * ```typescript
+ * import { target } from './target';
+ *
+ * builder.addNode("health", Endpoint({
+ *   method: GET,
+ *   path: "/health",
+ *   base: target("api-gateway"),
+ *   response_format: JSON
+ * }));
+ * ```
+ */
+export function Endpoint(config: EndpointConfig): Omit<Endpoint, "id"> {
+  return {
+    type: NodeType.ENDPOINT,
+    method: config.method as HttpMethod,
+    path: config.path,
+    base: config.base,
+    response_format: config.response_format as ResponseFormat,
+    headers: config.headers,
+    body: config.body,
+  };
+}
+
+/**
+ * Duration specification for Wait nodes.
+ * Accepts either milliseconds directly or an object with seconds/minutes.
+ */
+export type WaitDuration = number | { seconds: number } | { minutes: number };
+
+/**
+ * Converts a WaitDuration to milliseconds.
+ */
+function toMilliseconds(duration: WaitDuration): number {
+  if (typeof duration === "number") {
+    return duration;
+  }
+  if ("seconds" in duration) {
+    return duration.seconds * 1000;
+  }
+  if ("minutes" in duration) {
+    return duration.minutes * 60 * 1000;
+  }
+  throw new Error("Invalid duration format");
+}
+
+/**
+ * Creates a Wait node that pauses execution for a specified duration.
+ *
+ * @param duration - Duration to wait (milliseconds, or {seconds: n}, or {minutes: n})
+ * @returns A Wait node (without id) ready to be added to a TestBuilder
+ *
+ * @example
+ * ```typescript
+ * import { Wait, WaitDuration } from './index';
+ *
+ * builder.addNode("pause", Wait(WaitDuration.seconds(2)));
+ * // or with raw milliseconds:
+ * builder.addNode("pause", Wait(2000));
+ * ```
+ */
+export function Wait(duration: WaitDuration): Omit<Wait, "id"> {
+  return {
+    type: NodeType.WAIT,
+    duration_ms: toMilliseconds(duration),
+  };
+}
+
+/**
+ * Creates an Assertion node that validates test conditions.
+ *
+ * @param assertions - Array of SerializedAssertions to evaluate
+ * @returns An Assertion node (without id) ready to be added to a TestBuilder
+ *
+ * @example
+ * ```typescript
+ * import { Assert } from './assertions';
+ *
+ * builder.addNode("checks", Assertion([
+ *   Assert(state["node"].status).equals(200),
+ *   Assert(state["node"].body["status"]).equals("ok")
+ * ]));
+ * ```
+ */
+export function Assertion(assertions: JSONAssertion[]): Omit<Assertions, "id"> {
+  return {
+    type: NodeType.ASSERTION,
+    assertions: assertions.map((assertion) => ({
+      assertionType: ResponseFormat.JSON,
+      ...assertion,
+    })),
+  };
+}

package/src/constants.ts

@@ -0,0 +1,5 @@
+export const START = "__START__" as const;
+export const END = "__END__" as const;
+
+export type START = typeof START;
+export type END = typeof END;