@selvajs/compute 4.0.0-beta.1 → 4.0.0-beta.4

package/dist/handle-files-DcA24IkS.d.cts

@@ -1,478 +0,0 @@
-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';
-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 {
-    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;
-    headers?: Record<string, string>;
-    /** Enable debug logging to the console */
-    debug?: boolean;
-    /** Suppress browser security warnings in the console */
-    suppressBrowserWarning?: boolean;
-    /** @deprecated Renamed to `suppressBrowserWarning`. */
-    suppressClientSideWarning?: boolean;
-    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;
-    onServerTiming?: (timing: ServerTiming, requestId: string) => void;
-}
-interface ServerTiming {
-    decode?: number;
-    solve?: number;
-    encode?: number;
-    raw: string;
-}
-
-/**
- * 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;
-    /** Timeout (ms) for the fast read/monitoring endpoints. */
-    private static readonly DEFAULT_TIMEOUT_MS;
-    /** Timeout (ms) for child-lifecycle POSTs — a cold Windows child can take ~30s to spawn. */
-    private static readonly LIFECYCLE_TIMEOUT_MS;
-    /** Floor for `monitor()`'s `intervalMs` — anything lower hot-loops the server. */
-    private static readonly MIN_MONITOR_INTERVAL_MS;
-    /**
-     * @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;
-    /**
-     * `fetch` wrapper that aborts after `timeoutMs` so a hung connection can't stall
-     * a probe (or the `monitor()` loop) forever. Pass `0` to disable the timeout.
-     */
-    private fetchWithTimeout;
-    /**
-     * Check if the server is online.
-     *
-     * This is a single-sample probe: it returns `true` only on a 2xx from the
-     * proxy liveness root `/`, and `false` for every other outcome (non-2xx,
-     * network error, or timeout). A cold or briefly-busy-but-up server can therefore
-     * read as offline — callers that gate on this (e.g. client construction)
-     * should retry rather than treat a single `false` as authoritative.
-     *
-     * @param timeoutMs - Abort the probe after this many ms (default: 5000).
-     *   Pass `0` to disable the timeout. Prevents a hung connection from
-     *   stalling the caller indefinitely.
-     */
-    isServerOnline(timeoutMs?: number): Promise<boolean>;
-    /**
-     * Get the number of active child processes on the server.
-     *
-     * By default the proxy's `/activechildren` endpoint will *spawn* children up
-     * to the configured count if none are running, then report the count — which
-     * wakes (and bills) an idle server. Pass `{ initialize: false }` for a passive
-     * read that reports the current count without spawning; use this for
-     * monitoring or before a purge/probe where you must not wake the server.
-     *
-     * @param options.initialize - When `false`, append `?initialize=false` so the
-     *   server reports without spawning. Defaults to `true` (the server's default).
-     * @returns Number of active children, or null if unavailable
-     */
-    getActiveChildren(options?: {
-        initialize?: boolean;
-    }): 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 the plugins installed on the server.
-     *
-     * Returns a `name → version` map of non-core plugins the server has loaded,
-     * or `null` if the request failed. Pass `kind` to choose which inventory:
-     * `'gh'` (default) lists Grasshopper add-on assemblies via
-     * `/plugins/gh/installed`; `'rhino'` lists Rhino plugins via
-     * `/plugins/rhino/installed`. Plugins that ship with Rhino / are core
-     * libraries are excluded by the server.
-     *
-     * @param kind - `'gh'` for Grasshopper add-ons (default) or `'rhino'` for Rhino plugins.
-     * @returns Map of plugin name to version, or `null` on failure.
-     *
-     * @example
-     * ```ts
-     * const gh = await stats.getInstalledPlugins();        // Grasshopper add-ons
-     * const selvaVersion = gh?.['Selva'] ?? null;
-     * ```
-     */
-    getInstalledPlugins(kind?: 'gh' | 'rhino'): Promise<Record<string, string> | 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;
-    }>;
-    /**
-     * Purge the server's solve-results / URL-data cache.
-     *
-     * POSTs to `cache/purge` and returns the number of entries removed, or `null`
-     * if the request failed. This clears cached solve responses and fetched
-     * definition-URL data; it does NOT evict the definition cache (active
-     * `pointer` references stay valid).
-     *
-     * **Caveat:** `cache/purge` is forwarded by the rhino.compute proxy to a
-     * single round-robin-selected child, so in a multi-child deployment one call
-     * purges one child's cache. Call repeatedly (or size the pool to 1) if you
-     * need a fleet-wide purge.
-     *
-     * @returns Number of entries removed, or `null` on failure.
-     *
-     * @example
-     * ```ts
-     * const removed = await stats.purgeCache();
-     * if (removed !== null) console.log(`Purged ${removed} cached solves`);
-     * ```
-     */
-    purgeCache(): Promise<number | null>;
-    /**
-     * Best-effort fleet-wide cache purge across a multi-child deployment.
-     *
-     * A single {@link purgeCache} POST is forwarded by the rhino.compute proxy to
-     * just ONE round-robin-selected child, so the other children keep serving
-     * stale cached solves. There is no proxy endpoint that addresses children
-     * individually, so this method reads the active child count (passively, never
-     * spawning) and fires `2 × count` sequential purges, relying on the proxy's
-     * round-robin to spread the hits across the pool.
-     *
-     * **This is best-effort, not a guarantee.** Round-robin can revisit one child
-     * and skip another; under concurrent traffic the rotation drifts. The result's
-     * `confident` flag is `true` only when the server reports a single child (where
-     * one purge is exact) — surface it so callers don't over-promise. For a hard
-     * fleet-wide guarantee, run the deployment at `--childcount 1` or add a
-     * server-side fan-out endpoint.
-     *
-     * @returns `{ totalPurged, calls, children, confident }`, or `null` if the
-     *   child count couldn't be read (server unreachable). `totalPurged` sums the
-     *   per-call counts; `calls` is how many purges were issued; `children` is the
-     *   reported pool size; `confident` is `true` only at a single-child pool.
-     *
-     * @example
-     * ```ts
-     * const r = await stats.purgeAllChildren();
-     * if (r && !r.confident) {
-     *   console.warn(`Purged ~${r.totalPurged} across ${r.children} children (best-effort)`);
-     * }
-     * ```
-     */
-    purgeAllChildren(): Promise<{
-        totalPurged: number;
-        calls: number;
-        children: number;
-        confident: boolean;
-    } | null>;
-    /**
-     * Get the server's current UTC clock.
-     *
-     * GETs `/servertime`, which the server emits as a JSON-encoded ISO-8601
-     * timestamp (e.g. `"2026-06-18T08:30:00Z"`). Useful for detecting clock skew
-     * between caller and server. Returns `null` if the request failed or the body
-     * isn't a parseable date.
-     *
-     * @returns A `Date` for the server's UTC time, or `null` on failure.
-     */
-    getServerTime(): Promise<Date | null>;
-    /**
-     * Get how long the rhino.compute proxy has been idle.
-     *
-     * GETs `/idlespan` on the proxy, which returns the seconds elapsed since the
-     * last request was forwarded to a compute child. This is a proxy-level metric
-     * (not proxied to a child) used by autoscalers to decide when a node can be
-     * drained. Returns `null` if unavailable.
-     *
-     * @returns Idle time in seconds, or `null` on failure.
-     */
-    getIdleSpan(): Promise<number | null>;
-    /**
-     * Fill the compute child pool up to the server's configured baseline.
-     *
-     * POSTs `/launch-children`. No-op when the pool is already at or above the
-     * configured `--childcount`. Returns `{ spawned, active }` — how many children
-     * were started and the resulting child count — or `null` on failure.
-     *
-     * To raise capacity above the baseline use {@link launchChild}; the baseline
-     * itself can only be changed by restarting rhino.compute.
-     *
-     * @returns `{ spawned, active }`, or `null` on failure.
-     */
-    launchChildren(): Promise<{
-        spawned: number[];
-        active: number;
-    } | null>;
-    /**
-     * Add a single compute child to the pool, optionally on a specific port.
-     *
-     * POSTs `/launch-child` (with `?port=N` when `port` is given). Unlike
-     * {@link launchChildren}, this can push the pool above the baseline, up to the
-     * server's `MaxChildren` cap. Returns `{ spawned: [port] }` on success, or
-     * `null` on failure (server replies 400 for a bad port, 409 if the port is in
-     * use, 503 at the max-children cap).
-     *
-     * @param port - Optional specific port to launch on; otherwise the next free one.
-     * @returns `{ spawned }` listing the launched port, or `null` on failure.
-     */
-    launchChild(port?: number): Promise<{
-        spawned: number[];
-    } | null>;
-    /**
-     * Gracefully shut down compute children without respawning them.
-     *
-     * POSTs `/shutdown-children`. With no `port` it shuts down every child; with
-     * `port` it targets just that one. Children do not respawn, but the next
-     * `/grasshopper` request auto-spawns the pool back to the baseline. Returns
-     * `{ shutdown, active }` — how many were stopped and the remaining count — or
-     * `null` on failure.
-     *
-     * @param port - Optional port to target; omit to shut down all children.
-     * @returns `{ shutdown, active }`, or `null` on failure.
-     */
-    shutdownChildren(port?: number): Promise<{
-        shutdown: number;
-        active: number;
-    } | null>;
-    /**
-     * Shut down compute children and respawn replacements (rolling restart).
-     *
-     * POSTs `/recycle-children`. With no `port` it recycles every child; with
-     * `port` it recycles just that one. The server recycles sequentially (each
-     * replacement is serving before the next child is stopped) so the pool never
-     * drops to zero mid-recycle. Returns `{ shutdown, spawned, active }`, or
-     * `null` on failure.
-     *
-     * @param port - Optional port to target; omit to recycle all children.
-     * @returns `{ shutdown, spawned, active }`, or `null` on failure.
-     */
-    recycleChildren(port?: number): Promise<{
-        shutdown: number;
-        spawned: number[];
-        active: number;
-    } | null>;
-    /**
-     * POST a control endpoint that replies with a JSON object and return it,
-     * degrading to `null` on any non-2xx, non-JSON, or network failure. Shared by
-     * the child-lifecycle methods so their failure semantics stay identical. Uses
-     * the longer lifecycle timeout since a spawn/recycle can take ~30s.
-     */
-    private postJson;
-    /**
-     * Continuously monitor server stats at specified interval.
-     *
-     * @param callback - Function called with stats on each interval
-     * @param intervalMs - Milliseconds between checks (default: 5000). Must be a
-     *   finite number of at least 100 ms — lower values would hot-loop the server.
-     * @returns Function to stop monitoring
-     * @throws {RangeError} If `intervalMs` is not a finite number >= 100.
-     *
-     * @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;
-}
-
-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";
-    /** HTTP 404 — the endpoint path does not exist on the server (usually a typo'd route or wrong server). Never retried. */
-    readonly NOT_FOUND: "NOT_FOUND";
-    /** HTTP 429 — the server is rate-limiting requests. Retried by default (honors `Retry-After`); see `RetryPolicy.retryOn429`. */
-    readonly RATE_LIMIT: "RATE_LIMIT";
-    /**
-     * The server answered 2xx but the body is deterministically not JSON (the
-     * response declared a non-JSON `Content-Type`, e.g. an HTML captive-portal or
-     * proxy login page, or a misconfigured endpoint). Never retried — refetching
-     * returns the same page.
-     */
-    readonly INVALID_RESPONSE: "INVALID_RESPONSE";
-    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";
-    /** An input's `default` had a shape the normalizer didn't recognize (no innerTree key). */
-    readonly MALFORMED_DEFAULT: "MALFORMED_DEFAULT";
-    /** 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";
-    /**
-     * Scheduler backpressure: the queue was already at `maxQueueDepth` when this
-     * call arrived, so it was shed immediately rather than queued. Retryable — the
-     * caller (or an HTTP layer, as 503 + Retry-After) should back off and retry.
-     * The error `context` carries `{ queueDepth, maxQueueDepth }`.
-     */
-    readonly QUEUE_FULL: "QUEUE_FULL";
-    /**
-     * Scheduler backpressure: this call sat queued longer than `queueWaitMs`
-     * without starting, so it was shed before wasting compute on a stale request.
-     * Retryable. The error `context` carries `{ waitedMs, queueWaitMs }`.
-     */
-    readonly QUEUE_TIMEOUT: "QUEUE_TIMEOUT";
-    /**
-     * A solve referenced a definition by `pointer` (server-side cache key), but the
-     * server no longer holds that definition (evicted / GC'd / a different child in
-     * the pool / server restarted). The caller should retry with the full
-     * definition. Surfaced when the server tags its error body with
-     * `code: "definition_not_cached"`, so it survives production message-scrubbing.
-     */
-    readonly DEFINITION_NOT_CACHED: "DEFINITION_NOT_CACHED";
-};
-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: ErrorCode;
-    readonly statusCode?: number;
-    readonly context?: Record<string, unknown>;
-    readonly originalError?: Error;
-    constructor(message: string, code?: ErrorCode, 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;
-}
-
-/**
- * Raw file data from Grasshopper/Rhino Compute response, with metadata for processing.
- * Files are typically combined with additional files and packaged into a ZIP archive.
- * @see {@link extractFilesFromComputeResponse} for extraction from compute responses
- */
-type FileData = {
-    /** Base filename without extension (e.g., "model") */
-    fileName: string;
-    /** File content, base64-encoded or plain string depending on isBase64Encoded flag */
-    data: string;
-    /** File extension including the dot (e.g., ".3dm", ".json"). Appended to fileName to create the full filename */
-    fileType: string;
-    /** Whether data is base64-encoded. If true, must be decoded to binary before use */
-    isBase64Encoded: boolean;
-    /** Directory path for archive organization (e.g., "subfolder/nested"). Empty string for root-level files */
-    subFolder: string;
-    /** Arbitrary metadata attached in Grasshopper. Not interpreted by compute; passed through for downstream consumers. May be absent on older payloads */
-    metadata?: Record<string, string>;
-};
-/**
- * Normalized file ready for consumption or archival.
- * Unified intermediate format from FileData or FileBaseInfo, ready to be packaged into archives or returned to callers.
- */
-type ProcessedFile = {
-    /** Full filename including extension (e.g., "model.3dm") */
-    fileName: string;
-    /** File content as binary data (Uint8Array for decoded base64 or fetched binary) or text */
-    content: Uint8Array | string;
-    /** File path for archive organization (e.g., "subfolder/model.3dm") */
-    path: string;
-};
-/**
- * Reference to an external file to be fetched and included in file operations.
- * Specifies additional files (beyond compute response files) to fetch and process as ProcessedFile.
- * @see {@link fetchRemoteFiles} for how FileBaseInfo is fetched and converted
- */
-type FileBaseInfo = {
-    /** Destination filename for the file in the archive or result set (e.g., "additional-data.json") */
-    fileName: string;
-    /** URL to fetch the file from. Must be accessible from the runtime environment */
-    filePath: string;
-    /** Optional directory path for archive organization (e.g., "extras/docs"). When omitted, file lands at archive root */
-    subFolder?: string;
-};
-
-/** Extracts and processes files from compute response data without downloading them. */
-declare const extractFilesFromComputeResponse: (downloadableFiles: FileData[], additionalFiles?: FileBaseInfo[] | FileBaseInfo | null) => Promise<ProcessedFile[]>;
-/** Downloads files from a compute response as a ZIP archive. */
-declare const downloadFileData: (downloadableFiles: FileData[], fileFoldername: string, additionalFiles?: FileBaseInfo[] | FileBaseInfo | null) => Promise<void>;
-
-export { type ComputeConfig as C, type ErrorCode as E, type FileBaseInfo as F, type ProcessedFile as P, type RetryPolicy as R, type ServerTiming as S, ComputeServerStats as a, ErrorCodes as b, type FileData as c, RhinoComputeError as d, type RhinoModelUnit as e, downloadFileData as f, extractFilesFromComputeResponse as g };