@perspective-dev/client 4.5.2 → 5.0.0

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.
@@ -17,6 +17,8 @@ import * as psp_virtual from "./virtual_server.ts";
17
17
  import * as wasm_module from "../../dist/wasm/perspective-js.js";
18
18
  import * as api from "./wasm/browser.ts";
19
19
  import { load_wasm_stage_0 } from "./wasm/decompress.ts";
20
+ import { host_supports_memory64 } from "./wasm/features.ts";
21
+ export { host_supports_memory64 } from "./wasm/features.ts";
20
22
 
21
23
  export {
22
24
  GenericSQLVirtualServerModel,
@@ -30,7 +32,40 @@ import {
30
32
  VirtualServer,
31
33
  } from "../../dist/wasm/perspective-js.js";
32
34
 
33
- let GLOBAL_SERVER_WASM: Promise<ArrayBuffer | WebAssembly.Module>;
35
+ /**
36
+ * A single Perspective engine binary, in any form `init_server` accepts.
37
+ * Thunk sources are only invoked if selected — register both bitnesses as
38
+ * `() => fetch(...)` and only the winning binary is ever downloaded.
39
+ */
40
+ export type ServerWasmSource =
41
+ | Uint8Array
42
+ | ArrayBuffer
43
+ | Response
44
+ | WebAssembly.Module
45
+ | Promise<ArrayBuffer | Response | WebAssembly.Module>
46
+ | (() => Promise<ArrayBuffer | Response | WebAssembly.Module>);
47
+
48
+ /**
49
+ * Engine binaries by bitness. Registering `wasm64` is the opt-in for the
50
+ * Memory64 engine (4GB heap ceiling raised to 16GB, at some engine
51
+ * performance cost) — it is selected whenever the host supports Memory64.
52
+ */
53
+ export interface ServerWasmRegistration {
54
+ wasm32?: ServerWasmSource;
55
+ wasm64?: ServerWasmSource;
56
+ }
57
+
58
+ export interface InitServerOptions {
59
+ disable_stage_0?: boolean;
60
+ }
61
+
62
+ interface ServerWasmRegistry extends ServerWasmRegistration {
63
+ sole?: ServerWasmSource;
64
+ disable_stage_0: boolean;
65
+ }
66
+
67
+ let SERVER_REGISTRY: ServerWasmRegistry | undefined;
68
+ let GLOBAL_SERVER_WASM: Promise<ArrayBuffer | WebAssembly.Module> | undefined;
34
69
 
35
70
  export async function createMessageHandler(
36
71
  handler: psp_virtual.VirtualServerHandler,
@@ -38,28 +73,144 @@ export async function createMessageHandler(
38
73
  return psp_virtual.createMessageHandler(await get_client(), handler);
39
74
  }
40
75
 
76
+ function is_wasm_source(
77
+ wasm: ServerWasmSource | ServerWasmRegistration,
78
+ ): wasm is ServerWasmSource {
79
+ return (
80
+ wasm instanceof Uint8Array ||
81
+ wasm instanceof ArrayBuffer ||
82
+ (typeof Response !== "undefined" && wasm instanceof Response) ||
83
+ wasm instanceof Promise ||
84
+ wasm instanceof WebAssembly.Module ||
85
+ typeof wasm === "function"
86
+ );
87
+ }
88
+
89
+ async function materialize_server_wasm(
90
+ source: ServerWasmSource,
91
+ disable_stage_0: boolean,
92
+ ): Promise<ArrayBuffer | WebAssembly.Module> {
93
+ let wasm = typeof source === "function" ? await source() : await source;
94
+ if (wasm instanceof Uint8Array) {
95
+ wasm = wasm.buffer as ArrayBuffer;
96
+ }
97
+
98
+ if (typeof Response !== "undefined" && wasm instanceof Response) {
99
+ if (!wasm.ok) {
100
+ throw new Error(
101
+ `Failed to fetch perspective server wasm (HTTP ${wasm.status} "${wasm.url}")`,
102
+ );
103
+ }
104
+
105
+ if (disable_stage_0) {
106
+ return await wasm.arrayBuffer();
107
+ }
108
+ }
109
+
110
+ if (disable_stage_0) {
111
+ return wasm as ArrayBuffer | WebAssembly.Module;
112
+ }
113
+
114
+ const bytes = await load_wasm_stage_0(wasm);
115
+ return bytes.buffer as ArrayBuffer;
116
+ }
117
+
118
+ async function select_server_wasm(
119
+ registry: ServerWasmRegistry,
120
+ ): Promise<ArrayBuffer | WebAssembly.Module> {
121
+ if (registry.sole !== undefined) {
122
+ return await materialize_server_wasm(
123
+ registry.sole,
124
+ registry.disable_stage_0,
125
+ );
126
+ }
127
+
128
+ // A lone `wasm64` registration is an explicit opt-in and is used as-is
129
+ // regardless of the probe (an unsupporting host fails at instantiation,
130
+ // which is the correct error).
131
+ if (
132
+ registry.wasm64 !== undefined &&
133
+ (registry.wasm32 === undefined || host_supports_memory64())
134
+ ) {
135
+ try {
136
+ return await materialize_server_wasm(
137
+ registry.wasm64,
138
+ registry.disable_stage_0,
139
+ );
140
+ } catch (e) {
141
+ if (registry.wasm32 === undefined) {
142
+ throw e;
143
+ }
144
+
145
+ console.warn(
146
+ "Memory64 perspective server wasm failed to load, falling back to wasm32",
147
+ e,
148
+ );
149
+ }
150
+ }
151
+
152
+ return await materialize_server_wasm(
153
+ registry.wasm32!,
154
+ registry.disable_stage_0,
155
+ );
156
+ }
157
+
158
+ /**
159
+ * Register the Perspective engine ("server") WebAssembly binary that backs
160
+ * `worker()`.
161
+ *
162
+ * The single-argument form registers one binary of either bitness. The
163
+ * object form registers a wasm32 and/or wasm64 (Memory64) binary; the wasm64
164
+ * binary is preferred whenever the host supports Memory64, raising the
165
+ * engine's heap ceiling from 4GB to 16GB (at some engine performance cost —
166
+ * register only `wasm32` to opt out). Sources registered as thunks are only
167
+ * invoked if selected, so the losing binary is never downloaded; if the
168
+ * selected wasm64 source fails to load and a wasm32 source is also
169
+ * registered, selection falls back to wasm32 with a console warning.
170
+ *
171
+ * Selection and download are deferred to the first `worker()` call.
172
+ *
173
+ * # Examples
174
+ *
175
+ * ```javascript
176
+ * perspective.init_server(
177
+ * fetch("perspective-server.wasm"),
178
+ * );
179
+ *
180
+ * perspective.init_server({
181
+ * wasm32: () => fetch("perspective-server.wasm"),
182
+ * wasm64: () => fetch("perspective-server.memory64.wasm"),
183
+ * });
184
+ * ```
185
+ */
41
186
  export function init_server(
42
- wasm:
43
- | Uint8Array
44
- | Promise<ArrayBuffer | Response | WebAssembly.Module>
45
- | ArrayBuffer
46
- | Response
47
- | WebAssembly.Module,
48
- disable_stage_0: boolean = false,
187
+ wasm: ServerWasmSource | ServerWasmRegistration,
188
+ options: boolean | InitServerOptions = false,
49
189
  ) {
50
- if (wasm instanceof Uint8Array) {
51
- GLOBAL_SERVER_WASM = Promise.resolve(wasm.buffer);
52
- } else if (wasm instanceof Response) {
53
- GLOBAL_SERVER_WASM = Promise.resolve(wasm);
54
- } else if (wasm instanceof Promise) {
55
- GLOBAL_SERVER_WASM = wasm;
56
- } else {
57
- GLOBAL_SERVER_WASM = Promise.resolve(wasm);
190
+ const disable_stage_0 =
191
+ typeof options === "boolean" ? options : !!options.disable_stage_0;
192
+
193
+ GLOBAL_SERVER_WASM = undefined;
194
+ if (is_wasm_source(wasm)) {
195
+ SERVER_REGISTRY = { sole: wasm, disable_stage_0 };
196
+ return;
58
197
  }
59
198
 
60
- if (!disable_stage_0) {
61
- GLOBAL_SERVER_WASM = GLOBAL_SERVER_WASM.then((x) =>
62
- load_wasm_stage_0(x).then((x) => x.buffer as ArrayBuffer),
199
+ // `WebAssembly.Module`'s lib type is structurally empty, so TypeScript
200
+ // can't negatively narrow this branch itself.
201
+ const registration = wasm as ServerWasmRegistration;
202
+ if (
203
+ registration.wasm32 !== undefined ||
204
+ registration.wasm64 !== undefined
205
+ ) {
206
+ SERVER_REGISTRY = {
207
+ wasm32: registration.wasm32,
208
+ wasm64: registration.wasm64,
209
+ disable_stage_0,
210
+ };
211
+ } else {
212
+ throw new Error(
213
+ "init_server requires a wasm source or a {wasm32, wasm64} registration",
63
214
  );
64
215
  }
65
216
  }
@@ -175,10 +326,14 @@ export async function getCompiledClientWasm(): Promise<WebAssembly.Module> {
175
326
  }
176
327
 
177
328
  function get_server() {
178
- if (GLOBAL_SERVER_WASM === undefined) {
329
+ if (SERVER_REGISTRY === undefined) {
179
330
  throw new Error("Missing perspective-server.wasm");
180
331
  }
181
332
 
333
+ if (GLOBAL_SERVER_WASM === undefined) {
334
+ GLOBAL_SERVER_WASM = select_server_wasm(SERVER_REGISTRY);
335
+ }
336
+
182
337
  return GLOBAL_SERVER_WASM.then((x) =>
183
338
  x instanceof WebAssembly.Module ? x : x.slice(0),
184
339
  );
@@ -234,6 +389,7 @@ export default {
234
389
  worker,
235
390
  init_client,
236
391
  init_server,
392
+ host_supports_memory64,
237
393
  createMessageHandler,
238
394
  getCompiledClientWasm,
239
395
  GenericSQLVirtualServerModel,
@@ -12,11 +12,17 @@
12
12
 
13
13
  import perspective from "./perspective.browser.ts";
14
14
  export * from "./perspective.browser.ts";
15
+ import { resolve_server_wasm_url } from "./wasm/cdn.ts";
15
16
 
16
- const url = new URL(
17
- "../../../server/dist/wasm/perspective-server.wasm",
18
- import.meta.url,
19
- );
17
+ perspective.init_server({
18
+ wasm32: () => fetch(resolve_server_wasm_url(import.meta.url)),
19
+ wasm64: () =>
20
+ fetch(
21
+ resolve_server_wasm_url(
22
+ import.meta.url,
23
+ "perspective-server.memory64.wasm",
24
+ ),
25
+ ),
26
+ });
20
27
 
21
- perspective.init_server(fetch(url));
22
28
  export default perspective;
@@ -35,7 +35,10 @@ import { createRequire } from "node:module";
35
35
 
36
36
  import * as perspective_client from "../../dist/wasm/perspective-js.js";
37
37
  import { load_wasm_stage_0 } from "./wasm/decompress.js";
38
+ import { host_supports_memory64 } from "./wasm/features.ts";
38
39
  import * as engine from "./wasm/engine.ts";
40
+
41
+ export { host_supports_memory64 } from "./wasm/features.ts";
39
42
  import { compile_perspective } from "./wasm/emscripten_api.ts";
40
43
  import * as psp_websocket from "./websocket.ts";
41
44
  import * as api from "./wasm/browser.ts";
@@ -173,16 +176,43 @@ function make_node_disk_bridge({
173
176
  };
174
177
  }
175
178
 
176
- const SYNC_MODULE = await fs
177
- .readFile(
179
+ async function compile_server_module(wasm_path: string) {
180
+ const buffer = await fs.readFile(wasm_path);
181
+ const bytes = await load_wasm_stage_0(buffer.buffer as ArrayBuffer);
182
+ return await compile_perspective(bytes.buffer as ArrayBuffer, {
183
+ make_disk_bridge: make_node_disk_bridge,
184
+ });
185
+ }
186
+
187
+ async function load_server_module() {
188
+ if (host_supports_memory64()) {
189
+ let wasm_path;
190
+ try {
191
+ wasm_path = resolve(
192
+ "@perspective-dev/server/dist/wasm/perspective-server.memory64.wasm",
193
+ );
194
+ } catch (e) {
195
+ wasm_path = undefined;
196
+ }
197
+
198
+ if (wasm_path !== undefined) {
199
+ try {
200
+ return await compile_server_module(wasm_path);
201
+ } catch (e) {
202
+ console.warn(
203
+ "Memory64 perspective server wasm failed to load, falling back to wasm32",
204
+ e,
205
+ );
206
+ }
207
+ }
208
+ }
209
+
210
+ return await compile_server_module(
178
211
  resolve("@perspective-dev/server/dist/wasm/perspective-server.wasm"),
179
- )
180
- .then((buffer) => load_wasm_stage_0(buffer.buffer as ArrayBuffer))
181
- .then((buffer) =>
182
- compile_perspective(buffer.buffer as ArrayBuffer, {
183
- make_disk_bridge: make_node_disk_bridge,
184
- }),
185
212
  );
213
+ }
214
+
215
+ const SYNC_MODULE = await load_server_module();
186
216
 
187
217
  let SYNC_CLIENT: perspective_client.Client;
188
218
 
@@ -512,6 +542,7 @@ export default {
512
542
  join,
513
543
  websocket,
514
544
  worker,
545
+ host_supports_memory64,
515
546
  get_hosted_table_names,
516
547
  on_hosted_tables_update,
517
548
  remove_hosted_tables_update,
@@ -214,6 +214,7 @@ export class ClickhouseHandler implements perspective.VirtualServerHandler {
214
214
  this.sqlBuilder = new mod!.GenericSQLVirtualServerModel({
215
215
  create_entity: "VIEW",
216
216
  grouping_fn: "GROUPING",
217
+ column_separator: "|",
217
218
  });
218
219
  }
219
220
 
@@ -184,7 +184,9 @@ export class DuckDBHandler implements perspective.VirtualServerHandler {
184
184
  }
185
185
 
186
186
  this.db = db;
187
- this.sqlBuilder = new mod!.GenericSQLVirtualServerModel();
187
+ this.sqlBuilder = new mod!.GenericSQLVirtualServerModel({
188
+ column_separator: "|",
189
+ });
188
190
  }
189
191
 
190
192
  getFeatures() {
@@ -0,0 +1,32 @@
1
+ // ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
2
+ // ┃ ██████ ██████ ██████ █ █ █ █ █ █▄ ▀███ █ ┃
3
+ // ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█ ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄ ▀█ █ ▀▀▀▀▀ ┃
4
+ // ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄ █ ▄▄▄▄▄ ┃
5
+ // ┃ █ ██████ █ ▀█▄ █ ██████ █ ███▌▐███ ███████▄ █ ┃
6
+ // ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
7
+ // ┃ Copyright (c) 2017, the Perspective Authors. ┃
8
+ // ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
9
+ // ┃ This file is part of the Perspective library, distributed under the terms ┃
10
+ // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
11
+ // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
12
+
13
+ /**
14
+ * Resolve the URL of one of `@perspective-dev/server`'s engine WASM binaries
15
+ * relative to the URL of the `@perspective-dev/client` CDN bundle which loads
16
+ * it.
17
+ */
18
+ export function resolve_server_wasm_url(
19
+ client_url: string,
20
+ filename: string = "perspective-server.wasm",
21
+ ): string {
22
+ const rewritten = client_url.replace(
23
+ /\/client(@[^/]+)?\/dist\/cdn\/[^/?#]*([?#].*)?$/,
24
+ (_, tag) => `/server${tag ?? ""}/dist/wasm/${filename}`,
25
+ );
26
+
27
+ if (rewritten !== client_url) {
28
+ return rewritten;
29
+ }
30
+
31
+ return new URL(`../../../server/dist/wasm/${filename}`, client_url).href;
32
+ }
@@ -211,15 +211,17 @@ async function convert_typed_array_to_pointer(
211
211
  array: Uint8Array,
212
212
  callback: (_: PspPtr) => Promise<PspPtr>,
213
213
  ): Promise<PspPtr> {
214
+ const is_64 = core._psp_is_memory64();
214
215
  const ptr = core._psp_alloc(
215
- core._psp_is_memory64()
216
+ is_64
216
217
  ? (BigInt(array.byteLength) as any as number)
217
218
  : (array.byteLength as any),
218
219
  );
219
220
 
220
- core.HEAPU8.set(array, Number(ptr) >>> 0);
221
- const msg = await callback(Number(ptr) >>> 0);
222
- core._psp_free(Number(ptr) >>> 0);
221
+ const addr = is_64 ? Number(ptr) : Number(ptr) >>> 0;
222
+ core.HEAPU8.set(array, addr);
223
+ const msg = await callback(ptr);
224
+ core._psp_free(ptr);
223
225
  return msg;
224
226
  }
225
227
 
@@ -255,7 +257,7 @@ async function decode_api_responses(
255
257
  const is_64 = core._psp_is_memory64();
256
258
  const response = new DataView(
257
259
  core.HEAPU8.buffer,
258
- Number(ptr) >>> 0,
260
+ is_64 ? Number(ptr) : Number(ptr) >>> 0,
259
261
  is_64 ? 12 : 8,
260
262
  );
261
263
 
@@ -0,0 +1,31 @@
1
+ // ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
2
+ // ┃ ██████ ██████ ██████ █ █ █ █ █ █▄ ▀███ █ ┃
3
+ // ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█ ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄ ▀█ █ ▀▀▀▀▀ ┃
4
+ // ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄ █ ▄▄▄▄▄ ┃
5
+ // ┃ █ ██████ █ ▀█▄ █ ██████ █ ███▌▐███ ███████▄ █ ┃
6
+ // ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
7
+ // ┃ Copyright (c) 2017, the Perspective Authors. ┃
8
+ // ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
9
+ // ┃ This file is part of the Perspective library, distributed under the terms ┃
10
+ // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
11
+ // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
12
+
13
+ // The encoding of `(module (memory i64 1))` — validates only on hosts with
14
+ // WebAssembly Memory64 support (the same probe `wasm-feature-detect` uses).
15
+ const MEMORY64_PROBE = new Uint8Array([
16
+ 0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x05, 0x03, 0x01, 0x04,
17
+ 0x01,
18
+ ]);
19
+
20
+ let MEMORY64_SUPPORTED: boolean | undefined;
21
+
22
+ /**
23
+ * Does this JavaScript host support WebAssembly Memory64 (wasm64)?
24
+ */
25
+ export function host_supports_memory64(): boolean {
26
+ if (MEMORY64_SUPPORTED === undefined) {
27
+ MEMORY64_SUPPORTED = WebAssembly.validate(MEMORY64_PROBE);
28
+ }
29
+
30
+ return MEMORY64_SUPPORTED;
31
+ }