@hegeldev/hegel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antithesis, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+> [!IMPORTANT]
+> We're excited you're checking out Hegel! Hegel is in beta, and we'd love for you to try it and [report any feedback](https://github.com/hegeldev/hegel-typescript/issues/new).
+>
+> As part of our beta, we may make breaking changes if it makes Hegel a better property-based testing library. If that instability bothers you, please check back in a few months for a stable release!
+>
+> See https://hegel.dev/compatibility for more details.
+
+# Hegel for TypeScript
+
+- [Documentation](https://hegel.dev/typescript)
+- [Website](https://hegel.dev)
+
+Hegel is a property-based testing library for TypeScript. Hegel is based on [Hypothesis](https://github.com/hypothesisworks/hypothesis), using the [Hegel protocol](https://hegel.dev/).
+
+## Installation
+
+To install: `npm install --save-dev @hegeldev/hegel`.
+
+Hegel requires Node 16+. Bun and Deno are not currently supported.
+
+Hegel will use [uv](https://docs.astral.sh/uv/) to install the required [hegel-core](https://github.com/hegeldev/hegel-core) server component.
+If `uv` is already on your path, it will use that, otherwise it will download a private copy of it to ~/.cache/hegel and not put it on your path.
+See https://hegel.dev/reference/installation for details.
+
+## Quickstart
+
+Here's a quick example of how to write a Hegel test:
+
+```typescript
+import { test } from "vitest";
+import * as hegel from "@hegeldev/hegel";
+import * as gs from "@hegeldev/hegel/generators";
+
+function mySort(ls: number[]): number[] {
+  const result = [...ls].sort((a, b) => a - b);
+  return [...new Set(result)];
+}
+
+test(
+  "my_sort matches builtin",
+  hegel.test((tc) => {
+    const vec1 = tc.draw(gs.arrays(gs.integers()));
+    const vec2 = mySort(vec1);
+    const sorted = [...vec1].sort((a, b) => a - b);
+    if (JSON.stringify(sorted) !== JSON.stringify(vec2)) {
+      throw new Error(`sort mismatch: ${JSON.stringify(sorted)} != ${JSON.stringify(vec2)}`);
+    }
+  }),
+);
+```
+
+This test will fail when run with `vitest`! Hegel will produce a minimal failing test case for us:
+
+```
+Draw 1: [0, 0]
+Error: sort mismatch: [0,0] != [0]
+```
+
+Hegel reports the minimal example showing that our sort is incorrectly dropping duplicates. If we remove the `new Set(...)` deduplication from `mySort()`, this test will then pass (because it's just comparing the standard sort against itself).

package/dist/binary.d.ts

@@ -0,0 +1,27 @@
+import { Generator } from "./generator.js";
+/**
+ * Options for binary generator.
+ */
+export interface BinaryOptions {
+    /** Minimum size in bytes (default: 0) */
+    minSize?: number;
+    /** Maximum size in bytes (default: no limit) */
+    maxSize?: number;
+}
+/**
+ * Create a generator for binary data (byte sequences).
+ *
+ * @param options - Size constraints
+ * @returns Generator producing Uint8Array
+ *
+ * @example
+ * ```typescript
+ * // Generate any byte sequence
+ * const gen = binary();
+ *
+ * // Generate 16-32 bytes
+ * const bounded = binary({ minSize: 16, maxSize: 32 });
+ * ```
+ */
+export declare function binary(options?: BinaryOptions): Generator<Uint8Array>;
+//# sourceMappingURL=binary.d.ts.map

package/dist/binary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.d.ts","sourceRoot":"","sources":["../src/binary.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,SAAS,EAAc,MAAM,gBAAgB,CAAA;AAErE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAmCD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,SAAS,CAAC,UAAU,CAAC,CAEzE"}

package/dist/binary.js

@@ -0,0 +1,50 @@
+import { generateFromSchema } from "./connection.js";
+import { FuncGenerator } from "./generator.js";
+/**
+ * Generator for binary data (byte sequences).
+ */
+class BinaryGenerator extends FuncGenerator {
+    _binarySchema;
+    constructor(options = {}) {
+        const schema = {
+            type: "binary",
+            min_size: options.minSize ?? 0,
+        };
+        if (options.maxSize !== undefined) {
+            schema.max_size = options.maxSize;
+        }
+        super(() => {
+            const b64 = generateFromSchema(schema);
+            // Decode base64 to Uint8Array
+            const binaryString = atob(b64);
+            const bytes = new Uint8Array(binaryString.length);
+            for (let i = 0; i < binaryString.length; i++) {
+                bytes[i] = binaryString.charCodeAt(i);
+            }
+            return bytes;
+        }, schema);
+        this._binarySchema = schema;
+    }
+    schema() {
+        return this._binarySchema;
+    }
+}
+/**
+ * Create a generator for binary data (byte sequences).
+ *
+ * @param options - Size constraints
+ * @returns Generator producing Uint8Array
+ *
+ * @example
+ * ```typescript
+ * // Generate any byte sequence
+ * const gen = binary();
+ *
+ * // Generate 16-32 bytes
+ * const bounded = binary({ minSize: 16, maxSize: 32 });
+ * ```
+ */
+export function binary(options = {}) {
+    return new BinaryGenerator(options);
+}
+//# sourceMappingURL=binary.js.map

package/dist/binary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary.js","sourceRoot":"","sources":["../src/binary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACpD,OAAO,EAAE,aAAa,EAAyB,MAAM,gBAAgB,CAAA;AAYrE;;GAEG;AACH,MAAM,eAAgB,SAAQ,aAAyB;IACpC,aAAa,CAAY;IAE1C,YAAY,UAAyB,EAAE;QACrC,MAAM,MAAM,GAAe;YACzB,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,OAAO,CAAC,OAAO,IAAI,CAAC;SAC/B,CAAA;QACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAClC,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAA;QACnC,CAAC;QAED,KAAK,CAAC,GAAG,EAAE;YACT,MAAM,GAAG,GAAG,kBAAkB,CAAS,MAAM,CAAC,CAAA;YAC9C,8BAA8B;YAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;YAC9B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,MAAM,CAAC,CAAA;YACjD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7C,KAAK,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;YACvC,CAAC;YACD,OAAO,KAAK,CAAA;QACd,CAAC,EAAE,MAAM,CAAC,CAAA;QACV,IAAI,CAAC,aAAa,GAAG,MAAM,CAAA;IAC7B,CAAC;IAEQ,MAAM;QACb,OAAO,IAAI,CAAC,aAAa,CAAA;IAC3B,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,MAAM,CAAC,UAAyB,EAAE;IAChD,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC,CAAA;AACrC,CAAC"}

package/dist/collections.d.ts

@@ -0,0 +1,114 @@
+import { Generator, JsonSchema, BaseGenerator } from "./generator.js";
+/**
+ * Generator for arrays with builder pattern.
+ */
+export declare class ArrayGenerator<T> extends BaseGenerator<T[]> {
+    private readonly elements;
+    private readonly _minSize;
+    private readonly _maxSize?;
+    private readonly _unique;
+    private constructor();
+    static create<T>(elements: Generator<T>): ArrayGenerator<T>;
+    /**
+     * Set the minimum array size.
+     */
+    minSize(value: number): ArrayGenerator<T>;
+    /**
+     * Set the maximum array size.
+     */
+    maxSize(value: number): ArrayGenerator<T>;
+    /**
+     * Require all elements to be unique.
+     */
+    unique(): ArrayGenerator<T>;
+    generate(): T[];
+    schema(): JsonSchema | null;
+}
+/**
+ * Create a generator for arrays.
+ *
+ * @example
+ * ```typescript
+ * // Generate array of integers
+ * const gen = arrays(integers());
+ *
+ * // Generate array with size bounds
+ * const bounded = arrays(integers()).minSize(1).maxSize(10);
+ *
+ * // Generate array with unique elements
+ * const uniqueGen = arrays(integers()).unique();
+ * ```
+ */
+export declare function arrays<T>(elements: Generator<T>): ArrayGenerator<T>;
+/**
+ * Generator for Sets.
+ * Internally generates unique arrays and converts to Set.
+ */
+export declare class SetGenerator<T> extends BaseGenerator<Set<T>> {
+    private readonly elements;
+    private readonly _minSize;
+    private readonly _maxSize?;
+    private constructor();
+    static create<T>(elements: Generator<T>): SetGenerator<T>;
+    /**
+     * Set the minimum set size.
+     */
+    minSize(value: number): SetGenerator<T>;
+    /**
+     * Set the maximum set size.
+     */
+    maxSize(value: number): SetGenerator<T>;
+    generate(): Set<T>;
+    schema(): JsonSchema | null;
+}
+/**
+ * Create a generator for Sets.
+ */
+export declare function sets<T>(elements: Generator<T>): SetGenerator<T>;
+/**
+ * Generator for Maps (dictionaries) with configurable key and value types.
+ */
+export declare class MapGenerator<K, V> extends BaseGenerator<Map<K, V>> {
+    private readonly keys;
+    private readonly values;
+    private readonly _minSize;
+    private readonly _maxSize?;
+    private constructor();
+    static create<K, V>(keys: Generator<K>, values: Generator<V>): MapGenerator<K, V>;
+    /**
+     * Set the minimum map size.
+     */
+    minSize(value: number): MapGenerator<K, V>;
+    /**
+     * Set the maximum map size.
+     */
+    maxSize(value: number): MapGenerator<K, V>;
+    generate(): Map<K, V>;
+    schema(): JsonSchema | null;
+}
+/**
+ * Create a generator for Maps with configurable key and value types.
+ *
+ * @example
+ * ```typescript
+ * // String keys (common case)
+ * const strMap = maps(text(), integers());
+ *
+ * // Integer keys
+ * const intMap = maps(integers(), text());
+ * ```
+ */
+export declare function maps<K, V>(keys: Generator<K>, values: Generator<V>): MapGenerator<K, V>;
+/**
+ * Create a generator for tuples (fixed-length heterogeneous arrays).
+ *
+ * @example
+ * ```typescript
+ * const gen = tuples(integers(), text(), booleans());
+ * const [num, str, bool] = gen.generate();
+ * ```
+ */
+export declare function tuples<T extends unknown[]>(...generators: {
+    [K in keyof T]: Generator<T[K]>;
+}): Generator<T>;
+//# sourceMappingURL=collections.d.ts.map

package/dist/collections.d.ts.map

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

package/dist/collections.js

@@ -0,0 +1,313 @@
+import { generateFromSchema, assume } from "./connection.js";
+import { BaseGenerator } from "./generator.js";
+import { integers } from "./integers.js";
+import { LABELS } from "./labels.js";
+import { group } from "./spans.js";
+/**
+ * Generator for arrays with builder pattern.
+ */
+export class ArrayGenerator extends BaseGenerator {
+    elements;
+    _minSize;
+    _maxSize;
+    _unique;
+    constructor(elements, _minSize = 0, _maxSize, _unique = false) {
+        super();
+        this.elements = elements;
+        this._minSize = _minSize;
+        this._maxSize = _maxSize;
+        this._unique = _unique;
+    }
+    static create(elements) {
+        return new ArrayGenerator(elements);
+    }
+    /**
+     * Set the minimum array size.
+     */
+    minSize(value) {
+        return new ArrayGenerator(this.elements, value, this._maxSize, this._unique);
+    }
+    /**
+     * Set the maximum array size.
+     */
+    maxSize(value) {
+        return new ArrayGenerator(this.elements, this._minSize, value, this._unique);
+    }
+    /**
+     * Require all elements to be unique.
+     */
+    unique() {
+        return new ArrayGenerator(this.elements, this._minSize, this._maxSize, true);
+    }
+    generate() {
+        const schema = this.schema();
+        if (schema) {
+            // Schema composition: single socket round-trip
+            return generateFromSchema(schema);
+        }
+        // Compositional fallback: generate length, then each element
+        return group(LABELS.LIST, () => {
+            const maxSize = this._maxSize ?? 100;
+            const length = integers().min(this._minSize).max(maxSize).generate();
+            if (this._unique) {
+                // For unique arrays, track seen values
+                const seen = new Set();
+                const result = [];
+                const maxAttempts = length * 10;
+                let attempts = 0;
+                while (result.length < length && attempts < maxAttempts) {
+                    const value = group(LABELS.LIST_ELEMENT, () => this.elements.generate());
+                    const key = JSON.stringify(value);
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        result.push(value);
+                    }
+                    attempts++;
+                }
+                assume(result.length >= this._minSize);
+                return result;
+            }
+            const result = [];
+            for (let i = 0; i < length; i++) {
+                result.push(group(LABELS.LIST_ELEMENT, () => this.elements.generate()));
+            }
+            return result;
+        });
+    }
+    schema() {
+        const elementSchema = this.elements.schema();
+        if (!elementSchema) {
+            return null; // Fall back to compositional generation
+        }
+        const schema = {
+            type: this._unique ? "set" : "list",
+            elements: elementSchema,
+            min_size: this._minSize,
+        };
+        if (this._maxSize !== undefined) {
+            schema.max_size = this._maxSize;
+        }
+        return schema;
+    }
+}
+/**
+ * Create a generator for arrays.
+ *
+ * @example
+ * ```typescript
+ * // Generate array of integers
+ * const gen = arrays(integers());
+ *
+ * // Generate array with size bounds
+ * const bounded = arrays(integers()).minSize(1).maxSize(10);
+ *
+ * // Generate array with unique elements
+ * const uniqueGen = arrays(integers()).unique();
+ * ```
+ */
+export function arrays(elements) {
+    return ArrayGenerator.create(elements);
+}
+/**
+ * Generator for Sets.
+ * Internally generates unique arrays and converts to Set.
+ */
+export class SetGenerator extends BaseGenerator {
+    elements;
+    _minSize;
+    _maxSize;
+    constructor(elements, _minSize = 0, _maxSize) {
+        super();
+        this.elements = elements;
+        this._minSize = _minSize;
+        this._maxSize = _maxSize;
+    }
+    static create(elements) {
+        return new SetGenerator(elements);
+    }
+    /**
+     * Set the minimum set size.
+     */
+    minSize(value) {
+        return new SetGenerator(this.elements, value, this._maxSize);
+    }
+    /**
+     * Set the maximum set size.
+     */
+    maxSize(value) {
+        return new SetGenerator(this.elements, this._minSize, value);
+    }
+    generate() {
+        // Generate as unique array, then convert to Set
+        const arr = arrays(this.elements)
+            .minSize(this._minSize)
+            .maxSize(this._maxSize ?? 100)
+            .unique()
+            .generate();
+        return new Set(arr);
+    }
+    schema() {
+        const elementSchema = this.elements.schema();
+        if (!elementSchema) {
+            return null;
+        }
+        const schema = {
+            type: "set",
+            elements: elementSchema,
+            min_size: this._minSize,
+        };
+        if (this._maxSize !== undefined) {
+            schema.max_size = this._maxSize;
+        }
+        return schema;
+    }
+}
+/**
+ * Create a generator for Sets.
+ */
+export function sets(elements) {
+    return SetGenerator.create(elements);
+}
+/**
+ * Generator for Maps (dictionaries) with configurable key and value types.
+ */
+export class MapGenerator extends BaseGenerator {
+    keys;
+    values;
+    _minSize;
+    _maxSize;
+    constructor(keys, values, _minSize = 0, _maxSize) {
+        super();
+        this.keys = keys;
+        this.values = values;
+        this._minSize = _minSize;
+        this._maxSize = _maxSize;
+    }
+    static create(keys, values) {
+        return new MapGenerator(keys, values);
+    }
+    /**
+     * Set the minimum map size.
+     */
+    minSize(value) {
+        return new MapGenerator(this.keys, this.values, value, this._maxSize);
+    }
+    /**
+     * Set the maximum map size.
+     */
+    maxSize(value) {
+        return new MapGenerator(this.keys, this.values, this._minSize, value);
+    }
+    generate() {
+        const schema = this.schema();
+        if (schema) {
+            // Schema composition: single socket round-trip
+            // Wire format is [[key, value], ...]
+            const pairs = generateFromSchema(schema);
+            const result = new Map(pairs);
+            // Ensure size constraints are met (in case of duplicate keys)
+            assume(result.size >= this._minSize);
+            if (this._maxSize !== undefined) {
+                assume(result.size <= this._maxSize);
+            }
+            return result;
+        }
+        // Compositional fallback
+        return group(LABELS.MAP, () => {
+            const maxSize = this._maxSize ?? 100;
+            const targetSize = integers().min(this._minSize).max(maxSize).generate();
+            const result = new Map();
+            const maxAttempts = targetSize * 10;
+            let attempts = 0;
+            while (result.size < targetSize && attempts < maxAttempts) {
+                group(LABELS.MAP_ENTRY, () => {
+                    const key = this.keys.generate();
+                    if (!result.has(key)) {
+                        result.set(key, this.values.generate());
+                    }
+                });
+                attempts++;
+            }
+            assume(result.size >= this._minSize);
+            return result;
+        });
+    }
+    schema() {
+        const keySchema = this.keys.schema();
+        const valueSchema = this.values.schema();
+        if (!keySchema || !valueSchema) {
+            return null;
+        }
+        const schema = {
+            type: "dict",
+            keys: keySchema,
+            values: valueSchema,
+            min_size: this._minSize,
+        };
+        if (this._maxSize !== undefined) {
+            schema.max_size = this._maxSize;
+        }
+        return schema;
+    }
+}
+/**
+ * Create a generator for Maps with configurable key and value types.
+ *
+ * @example
+ * ```typescript
+ * // String keys (common case)
+ * const strMap = maps(text(), integers());
+ *
+ * // Integer keys
+ * const intMap = maps(integers(), text());
+ * ```
+ */
+export function maps(keys, values) {
+    return MapGenerator.create(keys, values);
+}
+/**
+ * Generator for tuples (fixed-length heterogeneous arrays).
+ */
+class TupleGenerator extends BaseGenerator {
+    generators;
+    constructor(generators) {
+        super();
+        this.generators = generators;
+    }
+    generate() {
+        const schema = this.schema();
+        if (schema) {
+            return generateFromSchema(schema);
+        }
+        // Compositional fallback
+        return group(LABELS.TUPLE, () => {
+            return this.generators.map(gen => gen.generate());
+        });
+    }
+    schema() {
+        const schemas = [];
+        for (const gen of this.generators) {
+            const s = gen.schema();
+            if (!s)
+                return null;
+            schemas.push(s);
+        }
+        return {
+            type: "tuple",
+            elements: schemas,
+        };
+    }
+}
+/**
+ * Create a generator for tuples (fixed-length heterogeneous arrays).
+ *
+ * @example
+ * ```typescript
+ * const gen = tuples(integers(), text(), booleans());
+ * const [num, str, bool] = gen.generate();
+ * ```
+ */
+export function tuples(...generators) {
+    return new TupleGenerator(generators);
+}
+//# sourceMappingURL=collections.js.map

package/dist/collections.js.map

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

package/dist/combinators.d.ts

@@ -0,0 +1,34 @@
+import { Generator } from "./generator.js";
+/**
+ * Create a generator that samples uniformly from a fixed collection.
+ *
+ * @example
+ * ```typescript
+ * const colors = sampledFrom(["red", "green", "blue"]);
+ * const color: string = colors.generate();
+ * ```
+ */
+export declare function sampledFrom<T>(elements: readonly T[]): Generator<T>;
+/**
+ * Create a generator that chooses from one of several generators.
+ *
+ * @example
+ * ```typescript
+ * const gen = oneOf(
+ *   integers().min(0).max(10),
+ *   integers().min(100).max(110)
+ * );
+ * ```
+ */
+export declare function oneOf<T>(...generators: Generator<T>[]): Generator<T>;
+/**
+ * Create a generator for optional values (T | null).
+ *
+ * @example
+ * ```typescript
+ * const gen = optional(integers());
+ * const value: number | null = gen.generate();
+ * ```
+ */
+export declare function optional<T>(inner: Generator<T>): Generator<T | null>;
+//# sourceMappingURL=combinators.d.ts.map

package/dist/combinators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"combinators.d.ts","sourceRoot":"","sources":["../src/combinators.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAA6B,MAAM,gBAAgB,CAAA;AAkDrE;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAEnE;AAwCD;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAEpE;AAiCD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAEpE"}