@elaraai/e3-ui-components 1.0.83 → 1.0.85

package/dist/hooks/index.d.ts

@@ -10,7 +10,7 @@ export * from './datasets.js';
 export * from './tasks.js';
 export * from './executions.js';
 export { useDatasetStatus, type DatasetStatus, type UseDatasetStatusOptions } from './useDatasetStatus.js';
-export { useDatasetValue, useDatasetDownload, type DatasetValueResult, type UseDatasetValueOptions } from './useDatasetValue.js';
+export { useDatasetValue, useDatasetDownload, downloadDataset, type DatasetValueResult, type UseDatasetValueOptions } from './useDatasetValue.js';
 export { useDatasetPage, type DatasetPageResult, type UseDatasetPageOptions, type DatasetPageWindow } from './useDatasetPage.js';
 export { useTaskDetails, type UseTaskDetailsOptions } from './useTaskDetails.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAC3G,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACjI,OAAO,EAAE,cAAc,EAAE,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACjI,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAC3G,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,eAAe,EAAE,KAAK,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAClJ,OAAO,EAAE,cAAc,EAAE,KAAK,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACjI,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/hooks/useDatasetValue.d.ts

@@ -41,6 +41,24 @@ export interface DatasetValueResult {
  * entry that holds another hash's value is never shown as this hash's.
  */
 export declare function useDatasetValue(apiUrl: string, repo: string, workspace: string | null, datasetPath: string | null, options: UseDatasetValueOptions): UseQueryResult<DatasetValueResult | undefined, Error>;
-/** Trigger a binary download of a dataset value. */
+/**
+ * Downloads a dataset's value: its beast2 bytes, which the browser saves as
+ * `<path>.beast2`, the path's dots as underscores. What a preview's Download
+ * does, for a host that draws Download itself (#1120).
+ *
+ * @param apiUrl - The e3 API's base URL
+ * @param repo - The repository
+ * @param workspace - The workspace
+ * @param path - The dataset's dotted path, e.g. `"inputs.rows"`
+ * @param requestOptions - The token, and the fetch the request goes through
+ * @returns Once the browser has the file
+ *
+ * @example
+ * ```tsx
+ * <Button onClick={() => downloadDataset(apiUrl, 'default', 'main', 'tasks.report.output')}>Download</Button>
+ * ```
+ */
+export declare function downloadDataset(apiUrl: string, repo: string, workspace: string, path: string, requestOptions?: RequestOptions): Promise<void>;
+/** Trigger a binary download of a dataset value: {@link downloadDataset}, once the workspace and path are known. */
 export declare function useDatasetDownload(apiUrl: string, repo: string, workspace: string | null, datasetPath: string | null, requestOptions?: RequestOptions): () => Promise<void>;
 //# sourceMappingURL=useDatasetValue.d.ts.map

package/dist/hooks/useDatasetValue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDatasetValue.d.ts","sourceRoot":"","sources":["../../src/hooks/useDatasetValue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAA4B,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAW7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAajD,MAAM,WAAW,sBAAsB;IACnC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,6CAA6C;IAC7C,IAAI,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,OAAO,EAAE,sBAAsB,GAChC,cAAc,CAAC,kBAAkB,GAAG,SAAS,EAAE,KAAK,CAAC,CA2BvD;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,cAAc,CAAC,EAAE,cAAc,uBAyBlC"}
+{"version":3,"file":"useDatasetValue.d.ts","sourceRoot":"","sources":["../../src/hooks/useDatasetValue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAA4B,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAW7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAajD,MAAM,WAAW,sBAAsB;IACnC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,6CAA6C;IAC7C,IAAI,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,OAAO,EAAE,sBAAsB,GAChC,cAAc,CAAC,kBAAkB,GAAG,SAAS,EAAE,KAAK,CAAC,CA2BvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,eAAe,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,cAAc,GAChC,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,oHAAoH;AACpH,wBAAgB,kBAAkB,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,cAAc,CAAC,EAAE,cAAc,uBAMlC"}

package/dist/hooks/useTaskLogsHook.d.ts

@@ -1,10 +1,74 @@
 import { QueryOverrides } from './types.js';
-import { RequestOptions } from '@elaraai/e3-api-client';
-export declare function useTaskLogs(apiUrl: string, repo: string, workspace: string | null, taskName: string | null, stream?: 'stdout' | 'stderr', requestOptions?: RequestOptions, queryOptions?: QueryOverrides): import('@tanstack/react-query').UseQueryResult<{
+import { LogOptions, RequestOptions, TaskLogChunk } from '@elaraai/e3-api-client';
+/** How often a task's log is polled while it changes: every second. */
+export declare const LOG_POLL_MS = 1000;
+/** The longest a task's log waits between polls: 5 s, which it backs off to
+ *  while nothing changes, and waits once its execution has ended and its log
+ *  is read. */
+export declare const LOG_POLL_BACKOFF_MS = 5000;
+/**
+ * A task's log as far as it has been read: one execution's, from its first
+ * byte, at most 10 MB of it.
+ */
+export interface TaskLogRead {
+    /** The log's text, as far as it has been read */
+    data: string;
+    /** The inputs hash of the execution it is the log of */
+    inputsHash: string;
+    /** The id of the execution it is the log of */
+    executionId: string;
+    /** The byte the next read starts at */
+    offset: number;
+    /** The log's size when it was last read */
+    totalSize: number;
+    /** Whether the last read reached the log's end */
+    complete: boolean;
+    /** Whether the execution has ended: its log grows no more */
+    ended: boolean;
+}
+/**
+ * Reads a task's log on from where the last read stopped: only what is new,
+ * a 64 KB chunk at a time, up to 10 MB in all. Each poll's first read names no
+ * execution, so it finds the task's current one: when that is another
+ * execution than the one read so far, the log starts over from its first
+ * byte, every read after naming it. Past 10 MB, a poll reads no bytes, and
+ * only finds whether the execution has changed or ended.
+ *
+ * @param read - Reads a chunk of the task's log (the client's `taskLogs`,
+ *   bound to the task)
+ * @param stream - The stream
+ * @param held - The log as far as the last poll read it; none for the first
+ * @returns The log as far as it is read now, and whether the poll found
+ *   anything new: bytes, another execution, or the execution's end
+ */
+export declare function readTaskLogOn(read: (options: LogOptions) => Promise<TaskLogChunk>, stream: 'stdout' | 'stderr', held: TaskLogRead | undefined): Promise<{
+    log: TaskLogRead;
+    changed: boolean;
+}>;
+/**
+ * How long a task's log waits before its next poll: a second after a poll
+ * that found something new, doubling toward {@link LOG_POLL_BACKOFF_MS} after
+ * each that found nothing, and the longest once the execution has ended and
+ * its log is read, when a poll only checks for a new execution.
+ *
+ * @param previous - How long the last poll waited
+ * @param log - The log as the poll left it
+ * @param changed - Whether the poll found anything new
+ * @returns How long the next waits, in milliseconds
+ */
+export declare function nextLogPollMs(previous: number, log: TaskLogRead, changed: boolean): number;
+/** What the hook answers: the log's text as far as it is read. */
+export interface TaskLogsData {
     data: string;
     offset: bigint;
     size: bigint;
     totalSize: bigint;
     complete: boolean;
-}, Error>;
+}
+/**
+ * Polls a task's log: only what is new each time, starting over when the
+ * task's current execution changes, and backing off while nothing does
+ * ({@link readTaskLogOn}, {@link nextLogPollMs}).
+ */
+export declare function useTaskLogs(apiUrl: string, repo: string, workspace: string | null, taskName: string | null, stream?: 'stdout' | 'stderr', requestOptions?: RequestOptions, queryOptions?: QueryOverrides): import('@tanstack/react-query').UseQueryResult<TaskLogsData, Error>;
 //# sourceMappingURL=useTaskLogsHook.d.ts.map

package/dist/hooks/useTaskLogsHook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTaskLogsHook.d.ts","sourceRoot":"","sources":["../../src/hooks/useTaskLogsHook.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA2D7D,wBAAgB,WAAW,CACvB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,GAAE,QAAQ,GAAG,QAAmB,EACtC,cAAc,CAAC,EAAE,cAAc,EAC/B,YAAY,CAAC,EAAE,cAAc;UArDd,MAAM;YAAU,MAAM;UAAQ,MAAM;eAAa,MAAM;cAAY,OAAO;UA8D5F"}
+{"version":3,"file":"useTaskLogsHook.d.ts","sourceRoot":"","sources":["../../src/hooks/useTaskLogsHook.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAMvF,uEAAuE;AACvE,eAAO,MAAM,WAAW,OAAO,CAAC;AAEhC;;eAEe;AACf,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;GAGG;AACH,MAAM,WAAW,WAAW;IACxB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;IAClB,6DAA6D;IAC7D,KAAK,EAAE,OAAO,CAAC;CAClB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CAC/B,IAAI,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,YAAY,CAAC,EACpD,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAC3B,IAAI,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CA+BjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAG1F;AAED,kEAAkE;AAClE,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACrB;AAID;;;;GAIG;AACH,wBAAgB,WAAW,CACvB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,EACvB,MAAM,GAAE,QAAQ,GAAG,QAAmB,EACtC,cAAc,CAAC,EAAE,cAAc,EAC/B,YAAY,CAAC,EAAE,cAAc,uEAkChC"}