@t-req/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,297 @@
+import type { CookieJar } from 'tough-cookie';
+import type { EventSink, IO, Transport } from './runtime/types';
+/**
+ * Represents a file reference in request body using `< ./path` syntax.
+ *
+ * @example
+ * ```typescript
+ * const fileRef: FileReference = {
+ *   path: './fixtures/payload.json'
+ * };
+ * ```
+ */
+export interface FileReference {
+    /** Relative path to the file */
+    path: string;
+}
+/**
+ * Represents a field in form data body.
+ *
+ * @example
+ * ```typescript
+ * // Text field
+ * const textField: FormField = {
+ *   name: 'title',
+ *   value: 'My Document',
+ *   isFile: false,
+ * };
+ *
+ * // File field
+ * const fileField: FormField = {
+ *   name: 'document',
+ *   value: '',
+ *   isFile: true,
+ *   path: './uploads/doc.pdf',
+ *   filename: 'report.pdf', // optional custom filename
+ * };
+ * ```
+ */
+export interface FormField {
+    /** Field name */
+    name: string;
+    /** Text value (for non-file fields) */
+    value: string;
+    /** Whether this field is a file upload */
+    isFile: boolean;
+    /** File path if isFile is true (from @./path syntax) */
+    path?: string;
+    /** Custom filename for file upload (from | syntax) */
+    filename?: string;
+}
+/**
+ * Represents a parsed HTTP request from a .http file.
+ *
+ * @example
+ * ```typescript
+ * const request: ParsedRequest = {
+ *   name: 'getUsers',
+ *   method: 'GET',
+ *   url: 'https://api.example.com/users',
+ *   headers: { 'Authorization': 'Bearer token' },
+ *   body: undefined,
+ *   raw: 'GET https://api.example.com/users\nAuthorization: Bearer token',
+ *   meta: { timeout: '5000' }
+ * };
+ * ```
+ */
+export interface ParsedRequest {
+    /** Optional name for the request, from `### Name` or `# @name name` */
+    name?: string;
+    /** HTTP method (GET, POST, PUT, DELETE, PATCH, etc.) */
+    method: string;
+    /** Full URL including any query parameters */
+    url: string;
+    /** Request headers as key-value pairs */
+    headers: Record<string, string>;
+    /** Request body content (for POST, PUT, PATCH requests) */
+    body?: string;
+    /** File reference if body uses `< ./path` syntax */
+    bodyFile?: FileReference;
+    /** Form fields if body uses form data syntax (field = value) */
+    formData?: FormField[];
+    /** Original raw content of the request block */
+    raw: string;
+    /** Meta directives from comments like `# @directive value` */
+    meta: Record<string, string>;
+}
+/**
+ * A function that resolves dynamic values during interpolation.
+ * Receives zero or more string arguments from the template.
+ *
+ * @example
+ * ```typescript
+ * const envResolver: Resolver = (key) => process.env[key] || '';
+ * const randomResolver: Resolver = (min = '0', max = '100') =>
+ *   String(Math.floor(Math.random() * (Number(max) - Number(min) + 1)) + Number(min));
+ * ```
+ */
+export type Resolver = (...args: string[]) => string | Promise<string>;
+/**
+ * Configuration options for variable interpolation.
+ */
+export interface InterpolateOptions {
+    /**
+     * Custom resolvers for dynamic values like `{{$env(KEY)}}`.
+     * Resolver names must start with `$`.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   resolvers: {
+     *     $env: (key) => process.env[key] || '',
+     *     $timestamp: () => String(Date.now()),
+     *   }
+     * }
+     * ```
+     */
+    resolvers?: Record<string, Resolver>;
+    /**
+     * How to handle undefined variables.
+     * - `'throw'`: Throw an error (default)
+     * - `'keep'`: Keep the `{{variable}}` placeholder
+     * - `'empty'`: Replace with empty string
+     */
+    undefinedBehavior?: 'throw' | 'keep' | 'empty';
+}
+/**
+ * A reusable interpolator instance with async support.
+ * Created using `createInterpolator()`.
+ */
+export interface Interpolator {
+    /**
+     * Interpolate variables in a target string or object.
+     * Supports async resolvers.
+     */
+    interpolate<T>(target: T, variables: Record<string, unknown>): Promise<T>;
+}
+/**
+ * Request object for HTTP execution.
+ * This is the minimal representation needed to execute a request.
+ */
+export interface ExecuteRequest {
+    /** HTTP method */
+    method: string;
+    /** Full URL to request */
+    url: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Request body (string, ArrayBuffer, FormData, or URLSearchParams) */
+    body?: string | ArrayBuffer | FormData | URLSearchParams;
+}
+/**
+ * Options for HTTP request execution (internal use).
+ */
+export interface ExecuteOptions {
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * AbortSignal for cancellation. Takes precedence over timeout.
+     */
+    signal?: AbortSignal;
+    /**
+     * Whether to automatically follow redirects.
+     * @default true
+     */
+    followRedirects?: boolean;
+    /**
+     * Whether to validate SSL certificates.
+     * Set to false for self-signed certificates.
+     * @default true
+     */
+    validateSSL?: boolean;
+    /**
+     * Proxy URL to use for requests.
+     * @example 'http://proxy.example.com:8080'
+     */
+    proxy?: string;
+}
+/**
+ * Configuration for creating an HTTP client.
+ */
+export interface ClientConfig {
+    /**
+     * Variables available to all requests.
+     * Can be overridden per-request.
+     */
+    variables?: Record<string, unknown>;
+    /**
+     * Custom resolvers for dynamic values.
+     * @see InterpolateOptions.resolvers
+     */
+    resolvers?: Record<string, Resolver>;
+    /**
+     * Cookie jar for automatic cookie handling.
+     * Create with `createCookieJar()`.
+     */
+    cookieJar?: CookieJar;
+    /**
+     * Optional IO adapter for filesystem access (Node/Bun/Tauri).
+     * Required for `client.run(path)` in runtimes without Bun filesystem APIs.
+     */
+    io?: IO;
+    /**
+     * Optional transport adapter to control how requests are executed.
+     */
+    transport?: Transport;
+    /**
+     * Optional event sink for engine-style observability (useful for TUI/agent UX).
+     */
+    onEvent?: EventSink;
+    /**
+     * Default timeout in milliseconds for all requests.
+     * Can be overridden per-request.
+     * @default 30000
+     */
+    timeout?: number;
+    /**
+     * Default settings for all requests.
+     */
+    defaults?: {
+        /** Default headers to include */
+        headers?: Record<string, string>;
+        /** Whether to follow redirects */
+        followRedirects?: boolean;
+        /** Whether to validate SSL certificates */
+        validateSSL?: boolean;
+        /** Proxy URL */
+        proxy?: string;
+    };
+}
+/**
+ * Options for running a request.
+ */
+export interface RunOptions {
+    /** Additional variables for this request */
+    variables?: Record<string, unknown>;
+    /**
+     * Timeout in milliseconds for this request.
+     * Converted to AbortSignal internally.
+     */
+    timeout?: number;
+    /**
+     * AbortSignal for cancellation.
+     * Takes precedence over timeout if both provided.
+     */
+    signal?: AbortSignal;
+    /**
+     * Base path for resolving file references when using `runString`.
+     * Ignored by `run(path)`, which derives base path from the .http file location.
+     */
+    basePath?: string;
+}
+/**
+ * High-level HTTP client with variable interpolation and cookies.
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({
+ *   variables: { baseUrl: 'https://api.example.com' },
+ *   cookieJar: createCookieJar(),
+ * });
+ *
+ * // Run a request from a .http file
+ * const res = await client.run('./auth/login.http');
+ * const { token } = await res.json();
+ *
+ * // Set variable for subsequent requests
+ * client.setVariable('token', token);
+ *
+ * // Run another request
+ * const profile = await client.run('./users/profile.http');
+ * ```
+ */
+export interface Client {
+    /**
+     * Parse and execute a request from a .http file.
+     * Returns a native fetch Response.
+     *
+     * @param path Path to the .http file
+     * @param options Optional variables, timeout, or abort signal
+     */
+    run(path: string, options?: RunOptions): Promise<Response>;
+    /**
+     * Parse and execute a request from in-memory `.http` content.
+     * Useful for editors, TUI previews, and Tauri renderer execution.
+     */
+    runString(content: string, options?: RunOptions): Promise<Response>;
+    /** Merge new variables with existing ones */
+    setVariables(vars: Record<string, unknown>): void;
+    /** Set a single variable */
+    setVariable(key: string, value: unknown): void;
+    /** Get a copy of all current variables */
+    getVariables(): Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/utils/optional.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A fluent builder for constructing objects with optional properties.
+ * Eliminates verbose conditional spread patterns.
+ */
+export interface OptionalBuilder<T extends object> {
+    /**
+     * Add properties when a condition is true.
+     */
+    when<K extends keyof T>(condition: boolean, props: Pick<Required<T>, K>): OptionalBuilder<T>;
+    /**
+     * Add a property if its value is defined (not undefined).
+     */
+    ifDefined<K extends keyof T>(key: K, value: T[K] | undefined): OptionalBuilder<T>;
+    /**
+     * Return the built object.
+     */
+    build(): T;
+}
+/**
+ * Create a fluent builder for constructing objects with optional properties.
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * const obj = {
+ *   method,
+ *   url,
+ *   ...(body !== undefined && { body }),
+ *   ...(timeout !== undefined && { timeout })
+ * };
+ *
+ * // Use:
+ * const obj = setOptional<Request>({ method, url })
+ *   .ifDefined('body', body)
+ *   .ifDefined('timeout', timeout)
+ *   .build();
+ * ```
+ */
+export declare function setOptional<T extends object>(base: T): OptionalBuilder<T>;
+//# sourceMappingURL=optional.d.ts.map

package/dist/utils/optional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional.d.ts","sourceRoot":"","sources":["../../src/utils/optional.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,MAAM;IAC/C;;OAEG;IACH,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;IAE7F;;OAEG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;IAElF;;OAEG;IACH,KAAK,IAAI,CAAC,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAwBzE"}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@t-req/core",
+  "version": "0.1.0",
+  "description": "HTTP request parsing, execution, and testing. Define requests in .http files, test them in isolation.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tensorix-labs/t-req",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/tensorix-labs/t-req#readme",
+  "bugs": {
+    "url": "https://github.com/tensorix-labs/t-req/issues"
+  },
+  "keywords": [
+    "http",
+    "api",
+    "testing",
+    "requests",
+    "bun",
+    "rest",
+    "http-client",
+    "api-testing",
+    "http-file",
+    "rest-client"
+  ],
+  "author": "tensorix labs",
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0.0"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./engine": {
+      "types": "./dist/engine/index.d.ts",
+      "import": "./dist/engine/index.js",
+      "default": "./dist/engine/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "default": "./dist/runtime/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js",
+      "default": "./dist/config/index.js"
+    },
+    "./cookies": {
+      "types": "./dist/cookies.d.ts",
+      "import": "./dist/cookies.js",
+      "default": "./dist/cookies.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build --target node --minify --sourcemap --outdir ./dist --root ./src ./src/index.ts ./src/engine/index.ts ./src/runtime/index.ts ./src/config/index.ts ./src/cookies.ts",
+    "build:types": "tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "test:e2e": "bun test test/e2e.test.ts",
+    "test:unit": "bun test --ignore test/e2e.test.ts",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "check-types": "tsc -p tsconfig.build.json --noEmit",
+    "prepublishOnly": "bun run build && bun run test:unit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/tough-cookie": "^4.0.5"
+  },
+  "dependencies": {
+    "tough-cookie": "^6.0.0"
+  }
+}