@selvajs/compute 5.0.0-beta.7 → 5.0.0-beta.9

package/dist/index-DDmprCht.d.ts

@@ -1,421 +0,0 @@
-declare const ErrorCodes: {
-  /** Connection failure, a gateway status (502/503/504), or a 2xx body cut off mid-stream. */
-  readonly NETWORK_ERROR: "NETWORK_ERROR";
-  /** HTTP 401 or 403: the server rejected the credentials. */
-  readonly AUTH_ERROR: "AUTH_ERROR";
-  /** The server rejected the request (HTTP 400, 413), or an input failed a client-side check. */
-  readonly VALIDATION_ERROR: "VALIDATION_ERROR";
-  /** The server failed the solve (HTTP 500), or the solve reported errors. */
-  readonly COMPUTATION_ERROR: "COMPUTATION_ERROR";
-  /** No response within `ComputeConfig.timeoutMs`. */
-  readonly TIMEOUT_ERROR: "TIMEOUT_ERROR";
-  /** A browser fetch failed with no response: most often CORS, which the browser hides. */
-  readonly CORS_ERROR: "CORS_ERROR";
-  /** HTTP 404: the endpoint doesn't exist on this server. Never retried. */
-  readonly NOT_FOUND: "NOT_FOUND";
-  /** HTTP 429. Retried, honouring `Retry-After`, when the policy allows (`RetryPolicy.retryOn429`). */
-  readonly RATE_LIMIT: "RATE_LIMIT";
-  /** A 2xx that declared a non-JSON body, e.g. a captive portal or proxy login page. Never retried. */
-  readonly INVALID_RESPONSE: "INVALID_RESPONSE";
-  /**
-   * The response body passed `ComputeConfig.maxResponseBytes`; the download was cancelled there.
-   * Never retried. `context` carries `{ maxResponseBytes }`.
-   */
-  readonly RESPONSE_TOO_LARGE: "RESPONSE_TOO_LARGE";
-  /** Any failure not classified by another code. */
-  readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
-  /** An object was used after `dispose()`, or a file download failed part-way. */
-  readonly INVALID_STATE: "INVALID_STATE";
-  /** A caller-supplied argument is unusable: an empty definition, an unserializable body. */
-  readonly INVALID_INPUT: "INVALID_INPUT";
-  /**
-   * Bad configuration: an invalid `serverUrl`, a server that answers with a redirect, an
-   * incomplete logger, an interval out of range.
-   */
-  readonly INVALID_CONFIG: "INVALID_CONFIG";
-  /** A browser-only API (file download) was called outside a browser. */
-  readonly BROWSER_ONLY: "BROWSER_ONLY";
-  /** The runtime has no base64 codec: neither `Buffer` nor `atob`/`btoa`. */
-  readonly ENVIRONMENT_ERROR: "ENVIRONMENT_ERROR";
-  /** A string that should be base64 isn't. */
-  readonly ENCODING_ERROR: "ENCODING_ERROR";
-  /** An input's `default` had a shape the normalizer didn't recognize. */
-  readonly MALFORMED_DEFAULT: "MALFORMED_DEFAULT";
-  /** Latest-wins scheduling: a newer call replaced this one. */
-  readonly SUPERSEDED: "SUPERSEDED";
-  /** The scheduler or a caller-supplied `AbortSignal` aborted this call. */
-  readonly ABORTED: "ABORTED";
-  /**
-   * The queue was at `maxQueueDepth`, so the call was rejected without queueing. Retryable after a
-   * back-off. `context` carries `{ queueDepth, maxQueueDepth }`.
-   */
-  readonly QUEUE_FULL: "QUEUE_FULL";
-  /**
-   * The call waited longer than `queueWaitMs` without starting, and was rejected rather than run
-   * stale. Retryable. `context` carries `{ waitedMs, queueWaitMs }`.
-   */
-  readonly QUEUE_TIMEOUT: "QUEUE_TIMEOUT";
-  /**
-   * The server no longer holds the definition a `pointer` named (evicted, restarted, another
-   * child). Retry with the full definition. Read from the error body's
-   * `code: "definition_not_cached"`.
-   */
-  readonly DEFINITION_NOT_CACHED: "DEFINITION_NOT_CACHED";
-};
-type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
-/** Error with a typed `code`: switch on it rather than on the message. */
-declare class ComputeError 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?: unknown;
-  });
-}
-/** A backend's error-body `code` → one of our {@link ErrorCodes}. */
-type ServerErrorCodeMap = Record<string, ErrorCode>;
-/**
- * Exponential backoff with jitter; a server `Retry-After` replaces the backoff for that attempt.
- *
- * Requests are POSTs: a connection lost after the body was sent may already have run on the
- * server, and the retry runs it again. A solve is deterministic, so that wastes work but corrupts
- * nothing; a non-idempotent endpoint should keep `attempts: 0`.
- */
-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. Sent as {@link apiKeyHeader}. */
-  apiKey?: string;
-  /**
-   * Header name carrying `apiKey`. Defaults to `'RhinoComputeKey'` — the name
-   * rhino.compute expects. A different backend sets its own.
-   */
-  apiKeyHeader?: string;
-  /** Sent verbatim as the `Authorization` header, so include the scheme (`Bearer …`). */
-  authToken?: string;
-  /**
-   * Extra request headers, e.g. routing hints a reverse proxy reads. A header the transport sets
-   * (credentials, `X-Request-ID`, `Content-Type`) wins over a caller header of any casing.
-   */
-  headers?: Record<string, string>;
-  /** Log each request at debug level through the configured logger (see `setLogger`). */
-  debug?: boolean;
-  /** Silence the warning logged when a call that carries the API key runs in a browser. */
-  suppressBrowserWarning?: boolean;
-  /**
-   * Per-attempt timeout, re-armed on every retry: the worst case is `(attempts + 1) × timeoutMs`
-   * plus backoff. Pass `signal` for an overall deadline.
-   */
-  timeoutMs?: number;
-  /** Retry policy for transient errors. Default: no retries. */
-  retry?: RetryPolicy;
-  /**
-   * Cancels the request, including during a retry backoff. Composes with `timeoutMs`: whichever
-   * fires first wins.
-   */
-  signal?: AbortSignal;
-  /**
-   * Largest response body, in UTF-8 bytes, read before the download is cancelled with
-   * `RESPONSE_TOO_LARGE`. A Grasshopper solve leaves out the uploaded definition the server echoes
-   * back. Default: no limit.
-   */
-  maxResponseBytes?: number;
-  /**
-   * Maps the `code` field of this backend's JSON error bodies to our {@link ErrorCodes}. A listed
-   * code outranks the status-based mapping: the server's production mode scrubs the human message
-   * but not the code. Core knows no backend's codes; the client supplies its own table.
-   */
-  serverErrorCodes?: ServerErrorCodeMap;
-  /**
-   * Called with the server's `Server-Timing` breakdown when the response carries a recognised
-   * metric, including on a 500 partial success. `requestId` matches the `X-Request-ID` header.
-   * A throwing callback doesn't fail the request.
-   */
-  onServerTiming?: (timing: ServerTiming, requestId: string) => void;
-}
-/** The config fields that decide how a request authenticates. */
-type ComputeAuth = Pick<ComputeConfig, 'apiKey' | 'apiKeyHeader' | 'authToken' | 'headers'>;
-/** The solve endpoint's `Server-Timing`, durations in ms. `raw` keeps the whole header, unrecognised metrics included. */
-interface ServerTiming {
-  decode?: number;
-  solve?: number;
-  encode?: number;
-  /** The part of `solve` spent inside Grasshopper; the rest collects the outputs. */
-  gh?: number;
-  /** Objects the solve ran out of all it holds. Few ran when only a downstream input changed. */
-  recomputed?: {
-    ran: number;
-    total: number;
-  };
-  /** The server answered from its result cache and solved nothing. */
-  cacheHit?: boolean;
-  raw: string;
-}
-/**
- * POST `args` as JSON to `<serverUrl>/<endpoint>` with retry, timeout and abort handling, and
- * return the parsed response. Most callers want a higher-level API.
- *
- * `R` names the expected response shape; nothing checks it, so the default `unknown` forces a
- * narrowing.
- *
- * @example
- * const response = await fetchCompute('grasshopper', args, {
- *   serverUrl: 'https://my-server.com',
- *   timeoutMs: 30_000,
- *   retry: { attempts: 2 },
- *   signal: controller.signal
- * });
- */
-declare function fetchCompute<R = unknown>(endpoint: string, args: Record<string, any>, config: ComputeConfig): Promise<R>;
-interface Logger {
-  debug(message: string, ...args: unknown[]): void;
-  info(message: string, ...args: unknown[]): void;
-  warn(message: string, ...args: unknown[]): void;
-  error(message: string, ...args: unknown[]): void;
-}
-declare function getLogger(): Logger;
-/**
- * Route the package's logs to `logger`; `null` silences them (the default).
- *
- * @throws {ComputeError} `INVALID_CONFIG` if the logger lacks one of the four methods, rather
- *   than a "debug is not a function" later at an unrelated call site.
- *
- * @example
- * ```typescript
- * import { setLogger } from '@selvajs/compute/core';
- *
- * setLogger(console);
- * setLogger({
- *   debug: (msg, ...args) => myLogger.debug(msg, ...args),
- *   info: (msg, ...args) => myLogger.info(msg, ...args),
- *   warn: (msg, ...args) => myLogger.warn(msg, ...args),
- *   error: (msg, ...args) => myLogger.error(msg, ...args)
- * });
- * setLogger(null);
- * ```
- */
-declare function setLogger(logger: Logger | Console | null): void;
-/** Shorthand for `setLogger(console)`. */
-declare function enableDebugLogging(): void;
-/**
- * Case-insensitive field reads for wire payloads.
- *
- * Rhino Compute branches serialize the same field in different casings. mcneel 8.x/9.x send the IO
- * schema PascalCase (`ParamType`, `Default`, `InnerTree`): those C# classes carry no
- * `[JsonProperty]`. The VektorNode fork sends camelCase, except inside the `default` DataTree
- * (`ParamName`, `InnerTree`), an external type it can't attribute. So one response can mix casings.
- * Read the fields you need through here and leave the rest verbatim: rewriting every key corrupts
- * user-authored ones such as value-list labels.
- */
-/**
- * Read `name` in any casing, preferring an exact-case match. `undefined` when no own key matches or
- * `obj` isn't an object.
- */
-declare function readField<T = unknown>(obj: unknown, name: string): T | undefined;
-/** Whether `name` is present in any casing, even with a null or undefined value. */
-declare function hasField(obj: unknown, name: string): boolean;
-/**
- * Decode base64 to bytes, normalizing and validating the same way in Node and browsers.
- * `packages/visualization/src/shared/encoding.ts` keeps a copy that throws its own error class;
- * change both together.
- *
- * @throws {ComputeError} `ENCODING_ERROR` if invalid, or `ENVIRONMENT_ERROR` if the runtime has no decoder
- */
-declare function decodeBase64ToBinary(base64File: string): Uint8Array;
-/** A definition identified by a stable key, with its bytes loaded only when an upload is unavoidable. */
-interface DefinitionRef {
-  /**
-   * Identity of immutable bytes, such as a version UUID; never a mutable name or path. Every
-   * cache trusts the key without looking at the bytes, so two contents sharing a key are served
-   * each other's solves, with no diagnostic.
-   */
-  key: string;
-  /** Called when the solve runs, not when it is scheduled: a solve aborted while queued never loads. */
-  load: () => Promise<Uint8Array>;
-}
-/**
- * A URL is sent as a pointer, a string is uploaded as base64 (or encoded text), bytes are
- * uploaded as-is. Strings and bytes are content-hashed for caching; a `DefinitionRef` is keyed
- * by its `key`.
- */
-type SolveDefinition = string | Uint8Array | DefinitionRef;
-declare function isDefinitionRef(definition: SolveDefinition): definition is DefinitionRef;
-/**
- * The public McNeel endpoint, blocked by default: users must point at their own server. Its raw IP
- * isn't blocked: it sits behind a load balancer with no stable address to pin.
- */
-declare const DEFAULT_BLOCKED_HOST = "compute.rhino3d.com";
-interface ValidateServerUrlOptions {
-  /**
-   * Hostnames rejected as a `serverUrl` — a backend's shared public endpoint,
-   * which callers must not point at. Defaults to `[DEFAULT_BLOCKED_HOST]`; pass
-   * `[]` to block nothing. Compared lowercased with any trailing dot stripped.
-   */
-  blockedHosts?: readonly string[];
-}
-/**
- * Validate a compute `serverUrl` and return it trimmed, without trailing slashes. Every entry point
- * that takes a server URL calls this, so a URL is accepted or rejected the same way everywhere.
- *
- * @throws {ComputeError} `INVALID_CONFIG` when the URL is empty, isn't http(s), doesn't parse,
- *   embeds credentials, has a query or fragment, or names a blocked host.
- */
-declare function validateServerUrl(raw: string, options?: ValidateServerUrlOptions): string;
-/**
- * Why a liveness probe failed, and whether waiting can change the answer.
- *
- * `retryable` is the whole point: a powered-off VM and a booting one both read
- * as "offline" from a single probe, but only one of them will ever come up. A
- * caller that can't tell them apart has to assume the optimistic case and burn
- * its full retry window on a machine that is simply off.
- */
-type ProbeVerdict =
-/** Nothing is listening on the port — the host answered, and said no. */
-'refused' |
-/** The hostname does not resolve. */
-'dns' |
-/** No answer within the timeout: a booting host swallows packets rather than refusing them. */
-'timeout' |
-/** The server answered, but rejected the probe's credentials (401/403). */
-'unauthorized' |
-/** The server answered with a non-2xx that isn't an auth rejection. */
-'http_error' |
-/** Connection failed in a way we can't attribute. */
-'unknown';
-interface ProbeFailure {
-  verdict: ProbeVerdict;
-  /** Whether retrying the same probe could plausibly succeed later. */
-  retryable: boolean;
-  /** Operator-facing sentence. Never includes the API key. */
-  summary: string;
-}
-/**
- * Classify a {@link ComputeServerStats.probeServer} result.
- *
- * A DNS failure is treated as retryable even though a missing record won't fix
- * itself: `EAI_AGAIN` is a *timeout* talking to the resolver, and the two are
- * not distinguishable from the error alone. Retrying a genuinely-wrong hostname
- * costs one window; giving up on a resolver hiccup breaks a server that is fine.
- *
- * @param probe - The `{ online, status?, error? }` a probe returned. An `online`
- *   probe is not a failure and yields `null`.
- */
-declare function classifyProbeFailure(probe: {
-  online: boolean;
-  status?: number;
-  error?: string;
-}): ProbeFailure | null;
-/** A file as a compute response carries it; {@link extractFilesFromComputeResponse} decodes it. */
-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>;
-};
-/** A decoded or fetched file, ready to archive or hand to a caller. */
-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;
-  /**
-   * The sanitized `subFolder`, kept apart from `path` because re-splitting a renamed duplicate
-   * path is ambiguous. `''` is the archive root; absent on a hand-built `ProcessedFile`.
-   */
-  subFolder?: string;
-  /** Carried through from {@link FileData}; absent when it had none, and on fetched files. */
-  metadata?: Record<string, string>;
-};
-/** An external file to fetch over HTTP and package alongside the response's own files. */
-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;
-};
-type DownloadOptions = {
-  /**
-   * Saves each finished archive instead of the default `<a download>` click. For hosts where an
-   * anchor download doesn't work, such as an embedded WebView that hands saves to native code.
-   * Awaited when it returns a promise, so archives still save one at a time.
-   */
-  saveBlob?: (blob: Blob, fileName: string) => unknown;
-};
-/**
- * Decode the files in a compute response, plus any external `additionalFiles`, without
- * downloading them. Never throws: an unnamed or undecodable item and a failed external fetch are
- * logged and dropped, the rest still resolve. Colliding archive paths are renamed
- * (`model.txt` → `model-2.txt`), so a consumer keying by `path` loses nothing.
- */
-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, options?: DownloadOptions) => Promise<void>;
-/**
- * Download one archive per `Sub Folder` root (see {@link groupFilesByRoot}). Files with no root go
- * into `fallbackName`, so a definition that never sets `Sub Folder` downloads as one archive.
- *
- * Archives are saved one at a time: browsers discard concurrent downloads issued in the same tick.
- * More than one save per gesture may prompt the user for permission.
- *
- * @param downloadableFiles - `FileData` items from the compute response.
- * @param fallbackName - Archive name for files with no `Sub Folder` root.
- * @param additionalFiles - Extra files to package; they carry no root and join the fallback archive.
- * @param options - `saveBlob` replaces the anchor download for every archive.
- */
-declare const downloadFileDataByRoot: (downloadableFiles: FileData[], fallbackName: string, additionalFiles?: FileBaseInfo[] | FileBaseInfo | null, options?: DownloadOptions) => Promise<void>;
-/**
- * The `Sub Folder` convention, as authored on Selva's Grasshopper file components.
- *
- * `::` nests, matching Rhino's layer separator (`ROOT::Panels`), and `/` and `\` are accepted
- * because people type them out of habit. The plugin normalizes to `/` before sending, so these
- * helpers also cover payloads from an older plugin that still emit `::`.
- *
- * The first segment is the **root**, which names the archive rather than becoming a folder inside
- * it: `ROOT::Panels` downloads as `ROOT.zip` containing `Panels/…`. Files sharing a root travel
- * together; distinct roots produce separate archives.
- */
-/**
- * Split a `Sub Folder` value into folder segments; `/`, `\` and `::` all separate.
- *
- * Exported because anything rendering a folder tree has to agree with the archive on where the
- * boundaries are — splitting on `/` alone leaves `Main::Panels` as one literal segment and shows
- * a folder named after the separator.
- */
-declare const subFolderSegments: (subFolder: string | undefined) => string[];
-/**
- * Group files by their `Sub Folder` root, preserving encounter order.
- *
- * Rootless files group under `''` — a caller naming archives supplies its own fallback for that
- * bucket. Useful beyond downloading: a consumer writing to disk gets the same grouping without
- * touching the DOM.
- */
-declare const groupFilesByRoot: <T extends Pick<FileData, "subFolder">>(files: readonly T[]) => Array<{
-  root: string;
-  files: T[];
-}>;
-export { ServerErrorCodeMap as A, enableDebugLogging as C, ComputeAuth as D, fetchCompute as E, ComputeError as M, ErrorCode as N, ComputeConfig as O, ErrorCodes as P, Logger as S, setLogger as T, SolveDefinition as _, extractFilesFromComputeResponse as a, hasField as b, FileData as c, ProbeVerdict as d, classifyProbeFailure as f, DefinitionRef as g, validateServerUrl as h, downloadFileDataByRoot as i, ServerTiming as j, RetryPolicy as k, ProcessedFile as l, ValidateServerUrlOptions as m, subFolderSegments as n, DownloadOptions as o, DEFAULT_BLOCKED_HOST as p, downloadFileData as r, FileBaseInfo as s, groupFilesByRoot as t, ProbeFailure as u, isDefinitionRef as v, getLogger as w, readField as x, decodeBase64ToBinary as y };
-//# sourceMappingURL=index-DDmprCht.d.ts.map