@selvajs/compute 1.5.2-beta.0 → 1.5.2-beta.1

package/dist/errors-CiA83qw2.d.cts

@@ -0,0 +1,510 @@
+/**
+ * Rhino model unit types supported by Rhino.Compute
+ */
+type RhinoModelUnit = 'None' | 'Microns' | 'Millimeters' | 'Centimeters' | 'Meters' | 'Kilometers' | 'Microinches' | 'Mils' | 'Inches' | 'Feet' | 'Miles' | 'CustomUnits' | 'Angstroms' | 'Nanometers' | 'Decimeters' | 'Dekameters' | 'Hectometers' | 'Megameters' | 'Gigameters' | 'Yards' | 'PrinterPoints' | 'PrinterPicas' | 'NauticalMiles' | 'AstronomicalUnits' | 'LightYears' | 'Parsecs' | 'Unset';
+/**
+ * Retry policy for transient errors (network, 502, 503, 504, optionally 429).
+ *
+ * Retries use exponential backoff with jitter, capped at `maxDelayMs`.
+ * If the server returns `Retry-After`, that value is honored instead.
+ */
+interface RetryPolicy {
+    /** Maximum number of retry attempts after the initial request (default: 0). */
+    attempts?: number;
+    /** Base delay in milliseconds for exponential backoff (default: 500). */
+    baseDelayMs?: number;
+    /** Upper bound for backoff delay (default: 30_000). */
+    maxDelayMs?: number;
+    /** Whether to retry on 429 responses (default: true — honors Retry-After). */
+    retryOn429?: boolean;
+}
+interface ComputeConfig {
+    /** The base URL of the Rhino Compute server (e.g., http://localhost:6500) */
+    serverUrl: string;
+    /** Optional API key for authenticating with the server (RhinoComputeKey) */
+    apiKey?: string;
+    /** Optional Bearer token for authentication (e.g., when behind a proxy or API gateway) */
+    authToken?: string;
+    /** Enable debug logging to the console */
+    debug?: boolean;
+    /** Suppress browser security warnings in the console */
+    suppressBrowserWarning?: boolean;
+    /** @deprecated Renamed to `suppressBrowserWarning`. */
+    suppressClientSideWarning?: boolean;
+    /**
+     * Per-request timeout in milliseconds. Set to `0` to disable (useful for long
+     * solves where any timeout is the wrong answer). Default: no timeout.
+     *
+     * Uses `AbortSignal.timeout` so the timer is not throttled when the tab is hidden.
+     */
+    timeoutMs?: number;
+    /**
+     * Retry policy for transient errors. Default: no retries.
+     */
+    retry?: RetryPolicy;
+    /**
+     * Optional caller-supplied AbortSignal. Composes with the internal timeout —
+     * whichever fires first wins. Lets callers cancel in-flight requests
+     * (e.g. on component unmount or when superseding a stale solve).
+     */
+    signal?: AbortSignal;
+}
+
+/**
+ * Grasshopper types
+ */
+
+/**
+ * Grasshopper-style data tree branch path
+ * @example "{0}", "{0;0}", "{0;1;2}"
+ */
+type DataTreePath = `{${string}}`;
+/**
+ * Represents a data item in a data tree
+ */
+interface DataItem {
+    /** The type of the data, inferred from the Grasshopper GOO class */
+    type: string;
+    /** The actual returned data as a string that may need to be parsed */
+    data: string;
+    /** The grasshopper refrence id of the output */
+    id: string;
+}
+/**
+ * Grasshopper-style data tree for input defaults
+ * @example
+ * ```typescript
+ * const numericTree: DataTreeDefault<number> = {
+ *   "{0}": [1, 2, 3],
+ *   "{0;0}": [4, 5],
+ *   "{1}": [6]
+ * };
+ * ```
+ */
+type DataTreeDefault<T = any> = {
+    [K in DataTreePath]?: T[];
+};
+/**
+ * Data structure for InnerTreeData matching Rhino Compute responses
+ */
+type InnerTreeData = {
+    [path in DataTreePath]: DataItem[];
+};
+/**
+ * Tree with parameter metadata (used in compute responses)
+ */
+interface DataTree {
+    InnerTree: InnerTreeData;
+    ParamName: string;
+}
+/**
+ * Output types supported from Grasshopper/Rhino Compute
+ */
+type OutputType = 'System.String' | 'System.Double' | 'System.Int32' | 'System.Boolean' | 'Rhino.Geometry.Point3d' | 'Rhino.Geometry.Line' | 'Rhino.Geometry.Circle' | 'Rhino.Geometry.Arc' | 'Rhino.Geometry.NurbsCurve' | 'Rhino.Geometry.Brep' | 'Rhino.Geometry.Mesh' | 'Rhino.Geometry.Vector3d' | 'Rhino.Geometry.Plane' | 'Rhino.Geometry.Box' | string;
+/**
+ * Union type for all possible default value types
+ */
+type DefaultValue<T> = T | T[] | DataTreeDefault<T> | undefined | null;
+/**
+ * Base properties common to all processed input types.
+ * Note: `groupName` and `id` require the custom Rhino Compute branch.
+ */
+interface BaseInputType {
+    description: string;
+    name: string;
+    nickname: string | null;
+    treeAccess: boolean;
+    /**
+     * Name of the group this parameter belongs to.
+     * @requires Custom branch of compute.rhino3d
+     */
+    groupName?: string;
+    /**
+     * Unique identifier for the parameter.
+     * @requires Custom branch of compute.rhino3d
+     */
+    id?: string;
+}
+/**
+ * Numeric input type (Number or Integer)
+ */
+interface NumericInputType extends BaseInputType {
+    paramType: 'Number' | 'Integer';
+    minimum?: number | null;
+    maximum?: number | null;
+    atLeast?: number | null;
+    atMost?: number | null;
+    stepSize?: number | null;
+    default: DefaultValue<number>;
+}
+/**
+ * Text input type
+ */
+interface TextInputType extends BaseInputType {
+    paramType: 'Text';
+    default: DefaultValue<string>;
+}
+/**
+ * Boolean input type
+ */
+interface BooleanInputType extends BaseInputType {
+    paramType: 'Boolean';
+    default: DefaultValue<boolean>;
+}
+/**
+ * Geometry input type (generic geometry)
+ */
+interface GeometryInputType extends BaseInputType {
+    paramType: 'Geometry';
+    default: DefaultValue<object | string>;
+}
+/**
+ * ValueList input type (dropdown/select)
+ */
+interface ValueListInputType extends BaseInputType {
+    paramType: 'ValueList';
+    values: Record<string, string>;
+    default?: string;
+}
+/**
+ * File input type
+ */
+interface FileInputType extends BaseInputType {
+    paramType: 'File';
+    acceptedFormats?: string[];
+    default: DefaultValue<object | string>;
+}
+/**
+ * Color input type (stored as hex string)
+ */
+interface ColorInputType extends BaseInputType {
+    paramType: 'Color';
+    default: DefaultValue<string>;
+}
+/**
+ * Discriminated union of all input parameter types
+ */
+type InputParam = NumericInputType | BooleanInputType | TextInputType | ValueListInputType | GeometryInputType | FileInputType | ColorInputType;
+/**
+ * Base Grasshopper schema properties shared by config, args, and response
+ */
+interface GrasshopperBaseSchema {
+    /** Absolute tolerance used in computation */
+    absolutetolerance?: number | null;
+    /** Angular tolerance used in computation */
+    angletolerance?: number | null;
+    /** Model units used */
+    modelunits?: RhinoModelUnit | null;
+    /** Data version (7 or 8) */
+    dataversion?: 7 | 8 | null;
+    /** Whether to use cached solution */
+    cachesolve?: boolean | null;
+}
+/**
+ * Definition source (used in args and response)
+ */
+interface GrasshopperDefinitionSource {
+    /** Base64 encoded algorithm (if embedded) */
+    algo?: string | null;
+    /** URL pointer to definition file */
+    pointer?: string | null;
+    /** Filename of the definition */
+    filename?: string | null;
+}
+/**
+ * Configuration for Grasshopper compute operations
+ * Combines server config with optional Grasshopper-specific computation settings
+ *
+ * Note: The definition source (pointer/algo) is NOT part of config.
+ * Instead, pass the definition directly to methods like solve(), getIO(), etc.
+ */
+interface GrasshopperComputeConfig extends ComputeConfig {
+    /** Absolute tolerance used in computation */
+    absolutetolerance?: number | null;
+    /** Angular tolerance used in computation */
+    angletolerance?: number | null;
+    /** Model units used */
+    modelunits?: RhinoModelUnit | null;
+    /** Data version (7 or 8) */
+    dataversion?: 7 | 8 | null;
+    /** Whether to use cached solution */
+    cachesolve?: boolean | null;
+}
+/**
+ * Raw I/O response schema from API (PascalCase)
+ *
+ * This is the direct response format from the Rhino Compute server API.
+ * All property names are in PascalCase, which is typical for .NET APIs.
+ * This raw response is converted to camelCase by the camelcaseKeys() function
+ * in the fetchDefinitionIO() method.
+ */
+interface IoResponseSchema {
+    description: string;
+    filename: string;
+    cachekey: string;
+    inputnames: string[];
+    outputnames: string[];
+    icon: string | null;
+    inputs: InputParamSchema[];
+    outputs: OutputParamSchema[];
+    warnings: any[];
+    errors: any[];
+}
+/**
+ * Arguments sent to Grasshopper compute endpoint
+ * Includes config options + definition source + input values
+ */
+interface GrasshopperRequestSchema extends GrasshopperBaseSchema, GrasshopperDefinitionSource {
+    /** Input values organized by parameter */
+    values?: DataTree[];
+}
+/**
+ * Response from Grasshopper compute server
+ * Includes all schema fields + computed results
+ */
+interface GrasshopperComputeResponse extends GrasshopperBaseSchema, GrasshopperDefinitionSource {
+    /** Whether cache was used (always present in response) */
+    cachesolve: boolean;
+    /** Model units (always present in response) */
+    modelunits: RhinoModelUnit;
+    /** Base64 encoded algorithm (always present in response) */
+    algo: string;
+    /** Filename of the definition (always present in response) */
+    filename: string | null;
+    /** Data version */
+    dataversion: 7 | 8;
+    /** Recursion level used */
+    recursionlevel?: number;
+    /** Output values organized by parameter */
+    values: DataTree[];
+    /** Computation errors */
+    errors?: string[];
+    /** Computation warnings */
+    warnings?: string[];
+}
+/**
+ * Output parameter
+ */
+interface OutputParamSchema {
+    name: string;
+    nickname: string | null;
+    paramType: string;
+    /**
+     * Grasshopper parameter instance GUID
+     */
+    id: string;
+}
+/**
+ * Input parameter
+ */
+interface InputParamSchema {
+    /**
+     * Grasshopper parameter instance GUID
+     */
+    id: string;
+    name: string;
+    nickname: string | null;
+    description: string;
+    paramType: string;
+    treeAccess: boolean;
+    minimum: number | null;
+    maximum: number | null;
+    atLeast: number;
+    atMost: number;
+    stepSize?: number;
+    default: any;
+    /**
+     * Key-value pairs for dropdown options
+     */
+    values?: Record<string, string>;
+    /**
+     * Accepted file formats for File input
+     */
+    acceptedFormats?: string[];
+    groupName?: string | null;
+}
+/**
+ * Parsed input/output structure with raw schemas
+ */
+interface GrasshopperParsedIORaw {
+    inputs: InputParamSchema[];
+    outputs: OutputParamSchema[];
+}
+/**
+ * Per-input parse failure. The corresponding entry in `inputs` was filled
+ * with a safe default so the rest of the pipeline can keep going — but the
+ * caller should surface this so the user knows their definition has a
+ * misconfigured parameter.
+ */
+interface InputParseError {
+    /** The input's `name` (or `'unknown'` if the schema didn't have one). */
+    inputName: string;
+    /** The declared paramType from the raw schema. */
+    paramType: string;
+    /** Human-readable reason from the underlying RhinoComputeError. */
+    message: string;
+    /** Error code from the underlying RhinoComputeError, if available. */
+    code?: string;
+}
+/**
+ * Parsed input/output structure with processed types.
+ *
+ * `parseErrors` is populated when one or more inputs failed validation and
+ * fell back to a safe default. The result is still usable, but the UI should
+ * surface these so the user can fix their definition.
+ */
+interface GrasshopperParsedIO {
+    inputs: InputParam[];
+    outputs: OutputParamSchema[];
+    parseErrors?: InputParseError[];
+}
+
+/**
+ * ComputeServerStats provides methods to query Rhino Compute server statistics.
+ *
+ * @public Use this for server health monitoring and statistics.
+ *
+ * @example
+ * ```typescript
+ * const stats = new ComputeServerStats('http://localhost:6500', 'your-api-key');
+ *
+ * try {
+ *   const isOnline = await stats.isServerOnline();
+ *   const children = await stats.getActiveChildren();
+ *   const version = await stats.getVersion();
+ *
+ *   // Or get everything at once
+ *   const allStats = await stats.getServerStats();
+ * } finally {
+ *   await stats.dispose(); // Clean up resources
+ * }
+ * ```
+ */
+declare class ComputeServerStats {
+    private readonly serverUrl;
+    private readonly apiKey?;
+    private disposed;
+    private activeMonitors;
+    private activeTimeouts;
+    /**
+     * @param serverUrl - Base URL of the Rhino Compute server with http:// or https:// scheme (e.g., 'http://localhost:6500')
+     * @param apiKey - Optional API key for authentication
+     */
+    constructor(serverUrl: string, apiKey?: string);
+    /**
+     * Build request headers with optional API key.
+     */
+    private buildHeaders;
+    /**
+     * Check if the server is online.
+     */
+    isServerOnline(): Promise<boolean>;
+    /**
+     * Get the number of active child processes on the server.
+     *
+     * @returns Number of active children, or null if unavailable
+     */
+    getActiveChildren(): Promise<number | null>;
+    /**
+     * Get the server version information.
+     *
+     * @returns Version object with rhino, compute, and git_sha, or null if unavailable
+     */
+    getVersion(): Promise<{
+        rhino: string;
+        compute: string;
+        git_sha: string | null;
+    } | null>;
+    /**
+     * Get comprehensive server statistics.
+     * Fetches all available server information in parallel.
+     *
+     * @returns Object containing server status and available stats
+     */
+    getServerStats(): Promise<{
+        isOnline: boolean;
+        version?: {
+            rhino: string;
+            compute: string;
+            git_sha: string | null;
+        };
+        activeChildren?: number;
+    }>;
+    /**
+     * Continuously monitor server stats at specified interval.
+     *
+     * @param callback - Function called with stats on each interval
+     * @param intervalMs - Milliseconds between checks (default: 5000)
+     * @returns Function to stop monitoring
+     *
+     * @example
+     * ```typescript
+     * const stopMonitoring = stats.monitor((data) => {
+     *   console.log('Server stats:', data);
+     * }, 3000);
+     *
+     * // Later...
+     * stopMonitoring();
+     * ```
+     */
+    monitor(callback: (stats: Awaited<ReturnType<typeof this.getServerStats>>) => void, intervalMs?: number): () => void;
+    /**
+     * Disposes of all resources and stops all active monitors.
+     * Call this when you're done using the stats instance.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Ensures the instance hasn't been disposed.
+     */
+    private ensureNotDisposed;
+}
+
+/**
+ * Error types and codes for `@selvajs/compute`.
+ */
+declare const ErrorCodes: {
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly AUTH_ERROR: "AUTH_ERROR";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly COMPUTATION_ERROR: "COMPUTATION_ERROR";
+    readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
+    readonly CORS_ERROR: "CORS_ERROR";
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    readonly INVALID_STATE: "INVALID_STATE";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly INVALID_CONFIG: "INVALID_CONFIG";
+    readonly BROWSER_ONLY: "BROWSER_ONLY";
+    readonly ENVIRONMENT_ERROR: "ENVIRONMENT_ERROR";
+    readonly ENCODING_ERROR: "ENCODING_ERROR";
+    /** Scheduler latest-wins: this call was replaced by a newer one. */
+    readonly SUPERSEDED: "SUPERSEDED";
+    /** Scheduler / caller-supplied AbortSignal: this call was aborted. */
+    readonly ABORTED: "ABORTED";
+};
+type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Simplified error for Rhino Compute operations
+ *
+ * @public Use this for error handling with error codes and context.
+ */
+declare class RhinoComputeError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly context?: Record<string, unknown>;
+    readonly originalError?: Error;
+    constructor(message: string, code?: string, options?: {
+        statusCode?: number;
+        context?: Record<string, unknown>;
+        originalError?: Error;
+    });
+    /**
+     * Create an error for missing/empty values
+     */
+    static missingValues(inputName: string, expectedType?: string, context?: Record<string, unknown>): RhinoComputeError;
+    /**
+     * Create an error for unknown parameter type
+     */
+    static unknownParamType(paramType: string, paramName?: string, context?: Record<string, unknown>): RhinoComputeError;
+}
+
+export { type BooleanInputType as B, type ComputeConfig as C, type DataItem as D, type ErrorCode as E, type FileInputType as F, type GeometryInputType as G, type InnerTreeData as I, type NumericInputType as N, type OutputParamSchema as O, type RetryPolicy as R, type TextInputType as T, type ValueListInputType as V, ComputeServerStats as a, type DataTree as b, type DataTreeDefault as c, type DataTreePath as d, type DefaultValue as e, ErrorCodes as f, type GrasshopperComputeConfig as g, type GrasshopperComputeResponse as h, type GrasshopperParsedIO as i, type GrasshopperParsedIORaw as j, type GrasshopperRequestSchema as k, type InputParam as l, type InputParamSchema as m, type OutputType as n, RhinoComputeError as o, type RhinoModelUnit as p, type IoResponseSchema as q };