@perspective-dev/client 5.4.0 → 5.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -19,9 +19,10 @@ export type TypedArrayWindow = {
19
19
  */
20
20
  formatted?: boolean;
21
21
  /**
22
- * Only impacts [`View::to_arrow`]
22
+ * Arrow IPC body compression for [`View::to_arrow`], `"lz4"` or `"zstd"`
23
+ * (uncompressed when omitted).
23
24
  */
24
- compression?: string;
25
+ compression?: "lz4" | "zstd";
25
26
  /**
26
27
  * When `true`, group-by columns use legacy `"colname (Group by N)"`
27
28
  * naming. When `false`, they use `__ROW_PATH_N__` naming consistent
@@ -16,9 +16,10 @@ export type ViewWindow = {
16
16
  */
17
17
  formatted?: boolean;
18
18
  /**
19
- * Only impacts [`View::to_arrow`]
19
+ * Arrow IPC body compression for [`View::to_arrow`], `"lz4"` or `"zstd"`
20
+ * (uncompressed when omitted).
20
21
  */
21
- compression?: string;
22
+ compression?: "lz4" | "zstd";
22
23
  /**
23
24
  * When `true`, group-by columns use legacy `"colname (Group by N)"`
24
25
  * naming. When `false`, they use `__ROW_PATH_N__` naming consistent
@@ -5,7 +5,7 @@ import type * as psp from "../../../dist/wasm/perspective-js.d.ts";
5
5
  * @param module
6
6
  * @returns
7
7
  */
8
- export declare function worker(module: Promise<typeof psp>, server_wasm: Promise<WebAssembly.Module> | undefined, perspective_wasm_worker: Promise<SharedWorker | ServiceWorker | Worker | MessagePort>): Promise<psp.Client>;
8
+ export declare function worker(module: Promise<typeof psp>, server_wasm: Promise<WebAssembly.Module> | undefined, perspective_wasm_worker: Promise<SharedWorker | Worker | MessagePort>): Promise<psp.Client>;
9
9
  /**
10
10
  * Create a new client connected via WebSocket to a server implemnting the
11
11
  * Perspective Protocol.
@@ -8,6 +8,7 @@ export interface DiskBridgeHelpers {
8
8
  readCString: (p: number | bigint) => string;
9
9
  }
10
10
  export interface CompileOptions {
11
+ env?: Record<string, string | undefined>;
11
12
  make_disk_bridge?: (helpers: DiskBridgeHelpers) => {
12
13
  store(namePtr: number | bigint, dataPtr: number | bigint, len: number): number;
13
14
  load(namePtr: number | bigint, dataPtr: number | bigint, len: number): number;
@@ -827,6 +827,17 @@ export class View {
827
827
  set_depth(depth: number): Promise<void>;
828
828
  /**
829
829
  * Serializes a [`View`] to the Apache Arrow data format.
830
+ *
831
+ * # Arguments
832
+ *
833
+ * - `window` - a [`ViewWindow`]; its `compression` key selects Arrow IPC
834
+ * body compression, `"lz4"` or `"zstd"` (uncompressed when omitted).
835
+ *
836
+ * # JavaScript Examples
837
+ *
838
+ * ```javascript
839
+ * const arrow = await view.to_arrow({ compression: "zstd" });
840
+ * ```
830
841
  */
831
842
  to_arrow(window?: ViewWindow | null): Promise<ArrayBuffer>;
832
843
  /**
@@ -1397,6 +1397,17 @@ export class View {
1397
1397
  }
1398
1398
  /**
1399
1399
  * Serializes a [`View`] to the Apache Arrow data format.
1400
+ *
1401
+ * # Arguments
1402
+ *
1403
+ * - `window` - a [`ViewWindow`]; its `compression` key selects Arrow IPC
1404
+ * body compression, `"lz4"` or `"zstd"` (uncompressed when omitted).
1405
+ *
1406
+ * # JavaScript Examples
1407
+ *
1408
+ * ```javascript
1409
+ * const arrow = await view.to_arrow({ compression: "zstd" });
1410
+ * ```
1400
1411
  * @param {ViewWindow | null} [window]
1401
1412
  * @returns {Promise<ArrayBuffer>}
1402
1413
  */
@@ -2127,7 +2138,7 @@ function __wbg_get_imports() {
2127
2138
  const ret = Promise.resolve(getObject(arg0));
2128
2139
  return addHeapObject(ret);
2129
2140
  },
2130
- __wbg_run_a7d22113de2ff7d8: function() { return handleError(function (arg0, arg1) {
2141
+ __wbg_run_556972011e45ec00: function() { return handleError(function (arg0, arg1) {
2131
2142
  const ret = getObject(arg0).run(getObject(arg1));
2132
2143
  return addHeapObject(ret);
2133
2144
  }, arguments); },
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@perspective-dev/client",
3
- "version": "5.4.0",
3
+ "version": "5.5.1",
4
4
  "description": "Client for Perspective, a high-performance WASM engine with reactive Tables, Views, and joins.",
5
5
  "keywords": [
6
6
  "perspective",
@@ -66,13 +66,13 @@
66
66
  "pro_self_extracting_wasm": "0.0.9",
67
67
  "stoppable": "=1.1.0",
68
68
  "ws": "^8.17.0",
69
- "@perspective-dev/server": "^5.4.0"
69
+ "@perspective-dev/server": "^5.5.1"
70
70
  },
71
71
  "devDependencies": {
72
72
  "@clickhouse/client-web": "^1.12.0",
73
73
  "@duckdb/duckdb-wasm": "1.33.1-dev18.0",
74
- "@playwright/experimental-ct-react": "=1.58.0",
75
- "@playwright/test": "=1.58.0",
74
+ "@playwright/experimental-ct-react": "=1.62.0",
75
+ "@playwright/test": "=1.62.0",
76
76
  "@types/node": ">=22",
77
77
  "@types/ws": ">=8",
78
78
  "@types/stoppable": ">=1",
@@ -84,9 +84,9 @@
84
84
  "typescript": ">=5 <6",
85
85
  "web-worker": "1.4.1",
86
86
  "zx": ">=8 <9",
87
- "@perspective-dev/esbuild-plugin": "^5.4.0",
88
- "@perspective-dev/test": "^5.4.0",
89
- "@perspective-dev/metadata": "^5.4.0"
87
+ "@perspective-dev/esbuild-plugin": "^5.5.1",
88
+ "@perspective-dev/metadata": "^5.5.1",
89
+ "@perspective-dev/test": "^5.5.1"
90
90
  },
91
91
  "scripts": {
92
92
  "build": "node ./build.mjs",
@@ -108,6 +108,14 @@ where
108
108
  pub fn new_throttled<U: Future<Output = ApiResult<T>> + 'static>(x: U) -> ApiFuture<()> {
109
109
  ApiFuture::<()>::new(async move { x.await.ignore_view_delete().map(|_| ()) })
110
110
  }
111
+
112
+ pub fn new_pure(t: T) -> ApiFuture<T> {
113
+ ApiFuture::<T>::new(async move { Ok(t) })
114
+ }
115
+
116
+ pub fn new_err<E: Into<ApiError> + 'static>(err: E) -> ApiFuture<T> {
117
+ ApiFuture::<T>::new(async move { Err(err.into()) })
118
+ }
111
119
  }
112
120
 
113
121
  impl<T> ApiFuture<T>
package/src/rust/view.rs CHANGED
@@ -195,6 +195,17 @@ impl View {
195
195
  }
196
196
 
197
197
  /// Serializes a [`View`] to the Apache Arrow data format.
198
+ ///
199
+ /// # Arguments
200
+ ///
201
+ /// - `window` - a [`ViewWindow`]; its `compression` key selects Arrow IPC
202
+ /// body compression, `"lz4"` or `"zstd"` (uncompressed when omitted).
203
+ ///
204
+ /// # JavaScript Examples
205
+ ///
206
+ /// ```javascript
207
+ /// const arrow = await view.to_arrow({ compression: "zstd" });
208
+ /// ```
198
209
  #[wasm_bindgen]
199
210
  pub async fn to_arrow(&self, window: Option<JsViewWindow>) -> ApiResult<ArrayBuffer> {
200
211
  let window = window.into_serde_ext::<Option<ViewWindow>>()?;
@@ -56,6 +56,16 @@ function bindPortSharedWorker(msg: MessageEvent) {
56
56
  port.start();
57
57
  }
58
58
 
59
+ /**
60
+ * Provided by `@perspective-dev/esbuild-plugin/worker`, which replaces this
61
+ * module with a stub when it is imported (rather than built as an entry
62
+ * point). Constructs a `Worker` from the bundled source, or falls back to
63
+ * running it on the main thread and returns a `MessagePort` to it.
64
+ */
65
+ export declare function initialize(
66
+ opts?: WorkerOptions,
67
+ ): Promise<Worker | MessagePort>;
68
+
59
69
  // @ts-expect-error wrong scope
60
70
  self.addEventListener("connect", bindPortSharedWorker);
61
71
  self.addEventListener(
@@ -235,10 +235,6 @@ async function compilerize(
235
235
  disable_stage_0: boolean = false,
236
236
  ) {
237
237
  const wasm_buff = disable_stage_0 ? wasm : await load_wasm_stage_0(wasm);
238
- // Compile to a `WebAssembly.Module` once so it can be both instantiated
239
- // locally and forwarded to other workers via `getCompiledClientWasm()`.
240
- // `WebAssembly.Module` is structured-cloneable across workers, so the
241
- // recipient can instantiate without re-fetching or re-compiling.
242
238
  const compiled = await compile_module(wasm_buff);
243
239
  GLOBAL_CLIENT_MODULE = Promise.resolve(compiled);
244
240
  await wasm_module.default({ module_or_path: compiled });
@@ -342,24 +338,10 @@ function get_server() {
342
338
  let GLOBAL_WORKER: undefined | (() => Promise<Worker>) = undefined;
343
339
 
344
340
  // `WorkerPlugin` resolves this import to a stub that exports
345
- // `getPerspectiveWorkerURL(): Promise<string>`. The URL is either a
346
- // Blob URL (inline mode — production builds) or a real file path
347
- // resolved against `import.meta.url` (file mode — debug builds).
348
- // Constructing the `Worker` lives here in the consumer rather than
349
- // inside the plugin so the same module text can also be loaded
350
- // in-process via dynamic `import(url)` when a future caller wants
351
- // it; the plugin no longer owns Worker lifecycle.
352
- //
353
- // `initialize()` constructs `new Worker(blobUrl)` and falls back to
354
- // running the worker source on the main thread via `new Function(...)`
355
- // when Worker construction is unavailable (e.g. `file://` origins where
356
- // module-Worker support is gated). The shim it returns is
357
- // MessagePort-shaped so downstream code can treat it like a real
358
- // Worker.
359
- // @ts-ignore — resolved at build time by `@perspective-dev/esbuild-plugin/worker`
341
+ // `getPerspectiveWorkerURL(): Promise<string>`.
360
342
  import { initialize as initializePerspectiveWorker } from "../../src/ts/perspective-server.worker.js";
361
343
 
362
- async function get_worker(): Promise<Worker> {
344
+ async function get_worker(): Promise<Worker | MessagePort> {
363
345
  if (GLOBAL_WORKER === undefined) {
364
346
  return await initializePerspectiveWorker({
365
347
  type: "module",
@@ -375,7 +357,7 @@ export async function websocket(url: string | URL) {
375
357
  }
376
358
 
377
359
  export async function worker(
378
- worker?: Promise<SharedWorker | ServiceWorker | Worker | MessagePort>,
360
+ worker?: Promise<SharedWorker | Worker | MessagePort>,
379
361
  ) {
380
362
  if (typeof worker === "undefined") {
381
363
  worker = get_worker();
@@ -181,6 +181,7 @@ async function compile_server_module(wasm_path: string) {
181
181
  const bytes = await load_wasm_stage_0(buffer.buffer as ArrayBuffer);
182
182
  return await compile_perspective(bytes.buffer as ArrayBuffer, {
183
183
  make_disk_bridge: make_node_disk_bridge,
184
+ env: process.env,
184
185
  });
185
186
  }
186
187
 
@@ -15,9 +15,10 @@ float32: boolean, start_row?: number, start_col?: number, end_row?: number, end_
15
15
  */
16
16
  formatted?: boolean,
17
17
  /**
18
- * Only impacts [`View::to_arrow`]
18
+ * Arrow IPC body compression for [`View::to_arrow`], `"lz4"` or `"zstd"`
19
+ * (uncompressed when omitted).
19
20
  */
20
- compression?: string,
21
+ compression?: "lz4" | "zstd",
21
22
  /**
22
23
  * When `true`, group-by columns use legacy `"colname (Group by N)"`
23
24
  * naming. When `false`, they use `__ROW_PATH_N__` naming consistent
@@ -12,9 +12,10 @@ export type ViewWindow = { start_row?: number, start_col?: number, end_row?: num
12
12
  */
13
13
  formatted?: boolean,
14
14
  /**
15
- * Only impacts [`View::to_arrow`]
15
+ * Arrow IPC body compression for [`View::to_arrow`], `"lz4"` or `"zstd"`
16
+ * (uncompressed when omitted).
16
17
  */
17
- compression?: string,
18
+ compression?: "lz4" | "zstd",
18
19
  /**
19
20
  * When `true`, group-by columns use legacy `"colname (Group by N)"`
20
21
  * naming. When `false`, they use `__ROW_PATH_N__` naming consistent
@@ -70,25 +70,31 @@ async function _init(
70
70
  export async function worker(
71
71
  module: Promise<typeof psp>,
72
72
  server_wasm: Promise<WebAssembly.Module> | undefined,
73
- perspective_wasm_worker: Promise<
74
- SharedWorker | ServiceWorker | Worker | MessagePort
75
- >,
73
+ perspective_wasm_worker: Promise<SharedWorker | Worker | MessagePort>,
76
74
  ) {
77
- let [wasm, webworker]: [
75
+ const [wasm, webworker]: [
78
76
  WebAssembly.Module | undefined,
79
- SharedWorker | ServiceWorker | Worker | MessagePort,
77
+ SharedWorker | Worker | MessagePort,
80
78
  ] = await Promise.all([server_wasm, perspective_wasm_worker]);
81
79
 
82
80
  const { Client } = await module;
83
- let port: MessagePort;
81
+ let port: MessagePort | Worker;
82
+ let close: () => void;
84
83
  if (
85
84
  typeof SharedWorker !== "undefined" &&
86
85
  webworker instanceof SharedWorker
87
86
  ) {
88
- port = webworker.port;
87
+ const shared_port = webworker.port;
88
+ port = shared_port;
89
+ close = () => shared_port.close();
90
+ } else if (typeof Worker !== "undefined" && webworker instanceof Worker) {
91
+ port = webworker;
92
+ close = () => webworker.terminate();
93
+ } else if (webworker instanceof MessagePort) {
94
+ port = webworker;
95
+ close = () => webworker.close();
89
96
  } else {
90
- // Assume `MessagePort`
91
- port = webworker as MessagePort;
97
+ throw new Error("Unsupported worker type");
92
98
  }
93
99
 
94
100
  const client = new Client(
@@ -98,17 +104,14 @@ export async function worker(
98
104
  },
99
105
  async () => {
100
106
  console.debug("Closing WebWorker");
101
- port.close();
102
- if (webworker instanceof Worker) {
103
- webworker.terminate();
104
- }
107
+ close();
105
108
  },
106
109
  );
107
110
 
108
111
  await _init(port, wasm);
109
- port.addEventListener("message", (json: MessageEvent<Uint8Array>) => {
112
+ port.onmessage = (json: MessageEvent<Uint8Array>) => {
110
113
  client.handle_response(json.data);
111
- });
114
+ };
112
115
 
113
116
  return client;
114
117
  }
@@ -24,6 +24,8 @@ export interface DiskBridgeHelpers {
24
24
  }
25
25
 
26
26
  export interface CompileOptions {
27
+ env?: Record<string, string | undefined>;
28
+
27
29
  make_disk_bridge?: (helpers: DiskBridgeHelpers) => {
28
30
  store(
29
31
  namePtr: number | bigint,
@@ -49,6 +51,7 @@ export async function compile_perspective(
49
51
  return x;
50
52
  },
51
53
  make_disk_bridge: opts?.make_disk_bridge,
54
+ env: opts?.env,
52
55
  instantiateWasm: async (
53
56
  imports: any,
54
57
  receive: (_: WebAssembly.Instance) => void,
@@ -71,6 +71,10 @@ export default async function (obj: any) {
71
71
  // receives a resolved file name string (from `victim_fname`).
72
72
  const disk_helpers = { heap, toAddr, readCString };
73
73
 
74
+ const environ_entries: Uint8Array[] = Object.entries(obj.env ?? {})
75
+ .filter(([, value]) => typeof value === "string")
76
+ .map(([key, value]) => new TextEncoder().encode(`${key}=${value}\0`));
77
+
74
78
  function makeOpfsBridge() {
75
79
  async function opfsOpenFile(name: string, create: boolean) {
76
80
  const parts = name.split("/").filter((s) => s.length > 0);
@@ -281,10 +285,51 @@ export default async function (obj: any) {
281
285
  console.error("abort");
282
286
  }
283
287
  },
284
- environ_get(...args: any[]) {
288
+ environ_get(environ: number | bigint, environ_buf: number | bigint) {
289
+ const view = new DataView(wasm_memory.buffer);
290
+ let entry = toAddr(environ);
291
+ let cursor = toAddr(environ_buf);
292
+ for (const bytes of environ_entries) {
293
+ if (is_memory64) {
294
+ view.setBigUint64(entry, BigInt(cursor), true);
295
+ entry += 8;
296
+ } else {
297
+ view.setUint32(entry, cursor, true);
298
+ entry += 4;
299
+ }
300
+
301
+ heap().set(bytes, cursor);
302
+ cursor += bytes.length;
303
+ }
304
+
285
305
  return 0;
286
306
  },
287
- environ_sizes_get(...args: any[]) {
307
+ environ_sizes_get(
308
+ environ_count: number | bigint,
309
+ environ_buf_size: number | bigint,
310
+ ) {
311
+ const view = new DataView(wasm_memory.buffer);
312
+ const total = environ_entries.reduce((n, x) => n + x.length, 0);
313
+ if (is_memory64) {
314
+ view.setBigUint64(
315
+ toAddr(environ_count),
316
+ BigInt(environ_entries.length),
317
+ true,
318
+ );
319
+ view.setBigUint64(
320
+ toAddr(environ_buf_size),
321
+ BigInt(total),
322
+ true,
323
+ );
324
+ } else {
325
+ view.setUint32(
326
+ toAddr(environ_count),
327
+ environ_entries.length,
328
+ true,
329
+ );
330
+ view.setUint32(toAddr(environ_buf_size), total, true);
331
+ }
332
+
288
333
  return 0;
289
334
  },
290
335
  fd_close(...args: any[]) {
@@ -392,8 +437,9 @@ export default async function (obj: any) {
392
437
  }
393
438
  const n = Number(mod.psp_residency_prepare(server));
394
439
  for (let i = 0; i < n; i++) {
440
+ const index = is_memory64 ? BigInt(i) : i;
395
441
  const fname = readCString(
396
- mod.psp_residency_victim_fname(server, i),
442
+ mod.psp_residency_victim_fname(server, index),
397
443
  );
398
444
  if (fname) {
399
445
  await disk.ensureOpen(fname);