@griffin-app/griffin-ts 0.1.0

package/dist/assertions.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssertBuilder = exports.BinaryPredicateOperator = exports.UnaryPredicate = void 0;
+exports.createStateProxy = createStateProxy;
+exports.Assert = Assert;
+/**
+ * Unary predicates that check a property without comparing to a value
+ */
+var UnaryPredicate;
+(function (UnaryPredicate) {
+    UnaryPredicate["IS_NULL"] = "IS_NULL";
+    UnaryPredicate["IS_NOT_NULL"] = "IS_NOT_NULL";
+    UnaryPredicate["IS_TRUE"] = "IS_TRUE";
+    UnaryPredicate["IS_FALSE"] = "IS_FALSE";
+    UnaryPredicate["IS_EMPTY"] = "IS_EMPTY";
+    UnaryPredicate["IS_NOT_EMPTY"] = "IS_NOT_EMPTY";
+})(UnaryPredicate || (exports.UnaryPredicate = UnaryPredicate = {}));
+/**
+ * Binary predicate operators that compare against an expected value
+ */
+var BinaryPredicateOperator;
+(function (BinaryPredicateOperator) {
+    BinaryPredicateOperator["EQUAL"] = "EQUAL";
+    BinaryPredicateOperator["NOT_EQUAL"] = "NOT_EQUAL";
+    BinaryPredicateOperator["GREATER_THAN"] = "GREATER_THAN";
+    BinaryPredicateOperator["LESS_THAN"] = "LESS_THAN";
+    BinaryPredicateOperator["GREATER_THAN_OR_EQUAL"] = "GREATER_THAN_OR_EQUAL";
+    BinaryPredicateOperator["LESS_THAN_OR_EQUAL"] = "LESS_THAN_OR_EQUAL";
+    BinaryPredicateOperator["CONTAINS"] = "CONTAINS";
+    BinaryPredicateOperator["NOT_CONTAINS"] = "NOT_CONTAINS";
+    BinaryPredicateOperator["STARTS_WITH"] = "STARTS_WITH";
+    BinaryPredicateOperator["NOT_STARTS_WITH"] = "NOT_STARTS_WITH";
+    BinaryPredicateOperator["ENDS_WITH"] = "ENDS_WITH";
+    BinaryPredicateOperator["NOT_ENDS_WITH"] = "NOT_ENDS_WITH";
+})(BinaryPredicateOperator || (exports.BinaryPredicateOperator = BinaryPredicateOperator = {}));
+// ============================================================================
+// State Proxy
+// ============================================================================
+/**
+ * Symbol used to store path metadata in proxy objects
+ */
+const PATH_SYMBOL = Symbol("__path__");
+/**
+ * Creates a nested proxy that accumulates path segments
+ */
+function createNestedProxy(descriptor) {
+    return new Proxy({}, {
+        get(_, prop) {
+            if (prop === PATH_SYMBOL) {
+                return descriptor;
+            }
+            if (prop === "at") {
+                return (index) => {
+                    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) {
+    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
+ */
+function createStateProxy(nodeNames) {
+    const proxy = new Proxy({}, {
+        get(_, nodeName) {
+            if (typeof nodeName === "symbol") {
+                return undefined;
+            }
+            return createNodeResultProxy(nodeName);
+        },
+    });
+    return proxy;
+}
+// ============================================================================
+// Assert Builder
+// ============================================================================
+class AssertBuilder {
+    descriptor;
+    negated = false;
+    constructor(descriptor) {
+        this.descriptor = descriptor;
+    }
+    /**
+     * 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() {
+        const negatedBuilder = new AssertBuilder(this.descriptor);
+        negatedBuilder.negated = !this.negated;
+        return negatedBuilder;
+    }
+    // Unary predicates
+    isNull() {
+        return this.createAssertion(this.negated ? UnaryPredicate.IS_NOT_NULL : UnaryPredicate.IS_NULL);
+    }
+    isDefined() {
+        return this.createAssertion(this.negated ? UnaryPredicate.IS_NULL : UnaryPredicate.IS_NOT_NULL);
+    }
+    isTrue() {
+        return this.createAssertion(this.negated ? UnaryPredicate.IS_FALSE : UnaryPredicate.IS_TRUE);
+    }
+    isFalse() {
+        return this.createAssertion(this.negated ? UnaryPredicate.IS_TRUE : UnaryPredicate.IS_FALSE);
+    }
+    isEmpty() {
+        return this.createAssertion(this.negated ? UnaryPredicate.IS_NOT_EMPTY : UnaryPredicate.IS_EMPTY);
+    }
+    // Binary predicates
+    equals(expected) {
+        return this.createAssertion({
+            operator: this.negated
+                ? BinaryPredicateOperator.NOT_EQUAL
+                : BinaryPredicateOperator.EQUAL,
+            expected,
+        });
+    }
+    greaterThan(expected) {
+        return this.createAssertion({
+            operator: this.negated
+                ? BinaryPredicateOperator.LESS_THAN_OR_EQUAL
+                : BinaryPredicateOperator.GREATER_THAN,
+            expected,
+        });
+    }
+    lessThan(expected) {
+        return this.createAssertion({
+            operator: this.negated
+                ? BinaryPredicateOperator.GREATER_THAN_OR_EQUAL
+                : BinaryPredicateOperator.LESS_THAN,
+            expected,
+        });
+    }
+    greaterThanOrEqual(expected) {
+        return this.createAssertion({
+            operator: this.negated
+                ? BinaryPredicateOperator.LESS_THAN
+                : BinaryPredicateOperator.GREATER_THAN_OR_EQUAL,
+            expected,
+        });
+    }
+    lessThanOrEqual(expected) {
+        return this.createAssertion({
+            operator: this.negated
+                ? BinaryPredicateOperator.GREATER_THAN
+                : BinaryPredicateOperator.LESS_THAN_OR_EQUAL,
+            expected,
+        });
+    }
+    contains(expected) {
+        return this.createAssertion({
+            operator: this.negated
+                ? BinaryPredicateOperator.NOT_CONTAINS
+                : BinaryPredicateOperator.CONTAINS,
+            expected,
+        });
+    }
+    startsWith(expected) {
+        return this.createAssertion({
+            operator: this.negated
+                ? BinaryPredicateOperator.NOT_STARTS_WITH
+                : BinaryPredicateOperator.STARTS_WITH,
+            expected,
+        });
+    }
+    endsWith(expected) {
+        return this.createAssertion({
+            operator: this.negated
+                ? BinaryPredicateOperator.NOT_ENDS_WITH
+                : BinaryPredicateOperator.ENDS_WITH,
+            expected,
+        });
+    }
+    createAssertion(predicate) {
+        return {
+            nodeId: this.descriptor.nodeId,
+            accessor: this.descriptor.accessor,
+            path: this.descriptor.path,
+            predicate,
+        };
+    }
+}
+exports.AssertBuilder = AssertBuilder;
+/**
+ * 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")
+ */
+function Assert(proxyRef) {
+    const descriptor = proxyRef[PATH_SYMBOL];
+    if (!descriptor) {
+        throw new Error("Assert() must be called with a reference from the state proxy");
+    }
+    return new AssertBuilder(descriptor);
+}
+//# sourceMappingURL=assertions.js.map

package/dist/assertions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.js","sourceRoot":"","sources":["../src/assertions.ts"],"names":[],"mappings":"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"}

package/dist/builder.d.ts

@@ -0,0 +1,168 @@
+import { TestPlanV1, Node, Frequency, Endpoint, Wait, Assertions, JSONAssertion } from "./schema.js";
+import { type START as StartType, type END as EndType } from "./constants";
+/**
+ * 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>;
+    };
+}
+/**
+ * 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 declare function createGraphBuilder(config: {
+    name: string;
+    frequency?: Frequency;
+    locations?: string[];
+}): TestBuilder;
+/**
+ * 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 declare function Endpoint(config: EndpointConfig): Omit<Endpoint, "id">;
+/**
+ * Duration specification for Wait nodes.
+ * Accepts either milliseconds directly or an object with seconds/minutes.
+ */
+export type WaitDuration = number | {
+    seconds: number;
+} | {
+    minutes: number;
+};
+/**
+ * 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 declare function Wait(duration: WaitDuration): Omit<Wait, "id">;
+/**
+ * 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 declare function Assertion(assertions: JSONAssertion[]): Omit<Assertions, "id">;
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}

package/dist/builder.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGraphBuilder = createGraphBuilder;
+exports.Endpoint = Endpoint;
+exports.Wait = Wait;
+exports.Assertion = Assertion;
+const schema_js_1 = require("./schema.js");
+/**
+ * Internal implementation class for TestBuilder.
+ * Uses explicit type assertions at method boundaries to maintain phantom type tracking.
+ */
+class TestBuilderImpl {
+    config;
+    nodes = [];
+    edges = [];
+    constructor(config) {
+        this.config = config;
+    }
+    addNode(name, node) {
+        // 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 });
+        // Type assertion: we've added Name to NodeName union
+        return this;
+    }
+    addEdge(from, to) {
+        this.edges.push({ from, to });
+        // Type assertion: we've updated HasOutput and HasInput based on edge direction
+        return this;
+    }
+    get build() {
+        const { name, frequency, locations } = this.config;
+        const nodes = this.nodes;
+        const edges = this.edges;
+        const buildFn = () => {
+            return {
+                name,
+                version: schema_js_1.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;
+    }
+}
+/**
+ * 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();
+ * ```
+ */
+function createGraphBuilder(config) {
+    return new TestBuilderImpl(config);
+}
+/**
+ * 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
+ * }));
+ * ```
+ */
+function Endpoint(config) {
+    return {
+        type: schema_js_1.NodeType.ENDPOINT,
+        method: config.method,
+        path: config.path,
+        base: config.base,
+        response_format: config.response_format,
+        headers: config.headers,
+        body: config.body,
+    };
+}
+/**
+ * Converts a WaitDuration to milliseconds.
+ */
+function toMilliseconds(duration) {
+    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));
+ * ```
+ */
+function Wait(duration) {
+    return {
+        type: schema_js_1.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")
+ * ]));
+ * ```
+ */
+function Assertion(assertions) {
+    return {
+        type: schema_js_1.NodeType.ASSERTION,
+        assertions: assertions.map((assertion) => ({
+            assertionType: schema_js_1.ResponseFormat.JSON,
+            ...assertion,
+        })),
+    };
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const START: "__START__";
+export declare const END: "__END__";
+export type START = typeof START;
+export type END = typeof END;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,EAAG,WAAoB,CAAC;AAC1C,eAAO,MAAM,GAAG,EAAG,SAAkB,CAAC;AAEtC,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC;AACjC,MAAM,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC"}

package/dist/constants.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.END = exports.START = void 0;
+exports.START = "__START__";
+exports.END = "__END__";
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,KAAK,GAAG,WAAoB,CAAC;AAC7B,QAAA,GAAG,GAAG,SAAkB,CAAC"}

package/dist/example-sequential.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Example usage of the Sequential Test Builder
+ *
+ * This demonstrates the simplified createTestBuilder API for straightforward
+ * linear test flows. Use this when you don't need complex branching.
+ *
+ * For more complex graphs with parallel execution or conditional flows,
+ * see example.ts which uses createGraphBuilder.
+ */
+export {};
+//# sourceMappingURL=example-sequential.d.ts.map

package/dist/example-sequential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-sequential.d.ts","sourceRoot":"","sources":["../src/example-sequential.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}