- if self.is_open { { items.collect::() } }
+ if self.is_open {
+
{ items.collect::() }
+ }
}
diff --git a/rust/perspective/Cargo.toml b/rust/perspective/Cargo.toml
index b7a8e64450..4eea9d49be 100644
--- a/rust/perspective/Cargo.toml
+++ b/rust/perspective/Cargo.toml
@@ -38,10 +38,10 @@ external-cpp = [
[dependencies]
async-lock = "2.5.0"
-perspective-client = { version = "3.2.1", path = "../perspective-client" }
-perspective-server = { version = "3.2.1", path = "../perspective-server" }
+perspective-client = { version = "3.2.1" }
+perspective-server = { version = "3.2.1" }
tracing = { version = ">=0.1.36" }
-axum = { version = ">=0.7,<2", features = ["ws"], optional = true }
+axum = { version = ">=0.7,<0.8", features = ["ws"], optional = true }
tokio = { version = "~1", features = ["full"], optional = true }
futures = { version = "~0", optional = true }
diff --git a/tools/perspective-bench/package.json b/tools/perspective-bench/package.json
index cf0242cda1..59fda93293 100644
--- a/tools/perspective-bench/package.json
+++ b/tools/perspective-bench/package.json
@@ -53,11 +53,6 @@
"perspective-1-1-0": "npm:@finos/perspective@1.1.0",
"perspective-1-0-0": "npm:@finos/perspective@1.0.0",
"perspective-0-10-0": "npm:@finos/perspective@0.10.0",
- "perspective-0-9-0": "npm:@finos/perspective@0.9.0",
- "perspective-0-8-0": "npm:@finos/perspective@0.8.0",
- "perspective-0-7-0": "npm:@finos/perspective@0.7.0",
- "perspective-0-6-0": "npm:@finos/perspective@0.6.0",
- "perspective-0-5-0": "npm:@finos/perspective@0.5.0",
- "perspective-0-4-0": "npm:@finos/perspective@0.4.0"
+ "perspective-0-9-0": "npm:@finos/perspective@0.9.0"
}
}
diff --git a/packages/perspective-esbuild-plugin/README.md b/tools/perspective-esbuild-plugin/README.md
similarity index 77%
rename from packages/perspective-esbuild-plugin/README.md
rename to tools/perspective-esbuild-plugin/README.md
index 290a4f1706..4e4fc88c40 100644
--- a/packages/perspective-esbuild-plugin/README.md
+++ b/tools/perspective-esbuild-plugin/README.md
@@ -2,11 +2,14 @@
Applications bundled with `esbuild` can make use of the
`@finos/perspective-esbuild-plugin` module. A full example can be found in the
-repo under [`examples/esbuild-example`](https://github.com/finos/perspective/tree/master/examples/esbuild-example).
+repo under
+[`examples/esbuild-example`](https://github.com/finos/perspective/tree/master/examples/esbuild-example).
```javascript
const esbuild = require("esbuild");
-const {PerspectiveEsbuildPlugin} = require("@finos/perspective-esbuild-plugin");
+const {
+ PerspectiveEsbuildPlugin,
+} = require("@finos/perspective-esbuild-plugin");
esbuild.build({
entryPoints: ["src/index.js"],
@@ -15,6 +18,7 @@ esbuild.build({
bundle: true,
loader: {
".ttf": "file",
+ ".wasm": "file",
},
});
```
diff --git a/packages/perspective-esbuild-plugin/amd.js b/tools/perspective-esbuild-plugin/amd.js
similarity index 100%
rename from packages/perspective-esbuild-plugin/amd.js
rename to tools/perspective-esbuild-plugin/amd.js
diff --git a/packages/perspective-esbuild-plugin/build.js b/tools/perspective-esbuild-plugin/build.js
similarity index 100%
rename from packages/perspective-esbuild-plugin/build.js
rename to tools/perspective-esbuild-plugin/build.js
diff --git a/packages/perspective-esbuild-plugin/external.js b/tools/perspective-esbuild-plugin/external.js
similarity index 100%
rename from packages/perspective-esbuild-plugin/external.js
rename to tools/perspective-esbuild-plugin/external.js
diff --git a/packages/perspective-esbuild-plugin/index.js b/tools/perspective-esbuild-plugin/index.js
similarity index 88%
rename from packages/perspective-esbuild-plugin/index.js
rename to tools/perspective-esbuild-plugin/index.js
index 5328ada8a2..d15d51c6bc 100644
--- a/packages/perspective-esbuild-plugin/index.js
+++ b/tools/perspective-esbuild-plugin/index.js
@@ -16,18 +16,23 @@ const { WorkerPlugin } = require("./worker.js");
exports.PerspectiveEsbuildPlugin = function PerspectiveEsbuildPlugin(
options = {}
) {
- const wasm_plugin = WasmPlugin(
- !!options.wasm?.inline,
- !options.wasm?.webpack_hack
- );
+ // const wasm_plugin = WasmPlugin(
+ // !!options.wasm?.inline,
+ // !options.wasm?.webpack_hack
+ // );
const worker_plugin = WorkerPlugin({
targetdir: options.worker?.targetdir,
});
function setup(build) {
- wasm_plugin.setup(build);
- worker_plugin.setup(build);
+ // if (options.wasm !== false) {
+ // wasm_plugin.setup(build);
+ // }
+
+ if (options.worker !== false) {
+ worker_plugin.setup(build);
+ }
}
return {
diff --git a/packages/perspective-esbuild-plugin/package.json b/tools/perspective-esbuild-plugin/package.json
similarity index 100%
rename from packages/perspective-esbuild-plugin/package.json
rename to tools/perspective-esbuild-plugin/package.json
diff --git a/packages/perspective-esbuild-plugin/resolve.js b/tools/perspective-esbuild-plugin/resolve.js
similarity index 100%
rename from packages/perspective-esbuild-plugin/resolve.js
rename to tools/perspective-esbuild-plugin/resolve.js
diff --git a/packages/perspective-esbuild-plugin/wasm.js b/tools/perspective-esbuild-plugin/wasm.js
similarity index 95%
rename from packages/perspective-esbuild-plugin/wasm.js
rename to tools/perspective-esbuild-plugin/wasm.js
index e55a107292..7276048076 100644
--- a/packages/perspective-esbuild-plugin/wasm.js
+++ b/tools/perspective-esbuild-plugin/wasm.js
@@ -24,10 +24,13 @@ exports.WasmPlugin = function WasmPlugin(inline, webpack_hack) {
args.namespace === "wasm-stub" ||
args.namespace === "wasm-inline"
) {
- const entryPoint = path.join(
- args.pluginData.resolveDir,
- args.path
- );
+ let entryPoint = args.path;
+ if (args.path.startsWith(".")) {
+ entryPoint = path.join(
+ args.pluginData.resolveDir,
+ entryPoint
+ );
+ }
return {
path: entryPoint,
diff --git a/packages/perspective-esbuild-plugin/worker.js b/tools/perspective-esbuild-plugin/worker.js
similarity index 100%
rename from packages/perspective-esbuild-plugin/worker.js
rename to tools/perspective-esbuild-plugin/worker.js
diff --git a/tools/perspective-test/playwright.config.ts b/tools/perspective-test/playwright.config.ts
index 1f42a4cdb1..6d0d430807 100644
--- a/tools/perspective-test/playwright.config.ts
+++ b/tools/perspective-test/playwright.config.ts
@@ -199,9 +199,9 @@ const GLOBAL_TEARDOWN_PATH = __require.resolve(
// See https://playwright.dev/docs/test-configuration.
export default defineConfig({
- timeout: 360_000,
+ timeout: 30_000,
expect: {
- timeout: 360_000,
+ timeout: 30_000,
},
forbidOnly: !!process.env.CI,
retries: 0,
+
+
+
diff --git a/rust/perspective-server/docs/architecture.dot b/docs/md/explanation/architecture/architecture.dot
similarity index 100%
rename from rust/perspective-server/docs/architecture.dot
rename to docs/md/explanation/architecture/architecture.dot
diff --git a/rust/perspective-server/docs/architecture.sub1.dot b/docs/md/explanation/architecture/architecture.sub1.dot
similarity index 100%
rename from rust/perspective-server/docs/architecture.sub1.dot
rename to docs/md/explanation/architecture/architecture.sub1.dot
diff --git a/rust/perspective-server/docs/architecture.sub1.svg b/docs/md/explanation/architecture/architecture.sub1.svg
similarity index 100%
rename from rust/perspective-server/docs/architecture.sub1.svg
rename to docs/md/explanation/architecture/architecture.sub1.svg
diff --git a/rust/perspective-server/docs/architecture.sub2.dot b/docs/md/explanation/architecture/architecture.sub2.dot
similarity index 100%
rename from rust/perspective-server/docs/architecture.sub2.dot
rename to docs/md/explanation/architecture/architecture.sub2.dot
diff --git a/rust/perspective-server/docs/architecture.sub2.svg b/docs/md/explanation/architecture/architecture.sub2.svg
similarity index 100%
rename from rust/perspective-server/docs/architecture.sub2.svg
rename to docs/md/explanation/architecture/architecture.sub2.svg
diff --git a/rust/perspective-server/docs/architecture.sub3.dot b/docs/md/explanation/architecture/architecture.sub3.dot
similarity index 100%
rename from rust/perspective-server/docs/architecture.sub3.dot
rename to docs/md/explanation/architecture/architecture.sub3.dot
diff --git a/rust/perspective-server/docs/architecture.sub3.svg b/docs/md/explanation/architecture/architecture.sub3.svg
similarity index 100%
rename from rust/perspective-server/docs/architecture.sub3.svg
rename to docs/md/explanation/architecture/architecture.sub3.svg
diff --git a/rust/perspective-server/docs/architecture.svg b/docs/md/explanation/architecture/architecture.svg
similarity index 100%
rename from rust/perspective-server/docs/architecture.svg
rename to docs/md/explanation/architecture/architecture.svg
diff --git a/docs/md/explanation/architecture/client_only.md b/docs/md/explanation/architecture/client_only.md
new file mode 100644
index 0000000000..7db35eca0e
--- /dev/null
+++ b/docs/md/explanation/architecture/client_only.md
@@ -0,0 +1,39 @@
+# Client-only
+
+
+
+_For static datasets, datasets provided by the user, and simple server-less and
+read-only web applications._
+
+In this design, Perspective is run as a client Browser WebAssembly library, the
+dataset is downloaded entirely to the client and all calculations and UI
+interactions are performed locally. Interactive performance is very good, using
+WebAssembly engine for near-native runtime plus WebWorker isolation for parallel
+rendering within the browser. Operations like scrolling and creating new views
+are responsive. However, the entire dataset must be downloaded to the client.
+Perspective is not a typical browser component, and datset sizes of 1gb+ in
+Apache Arrow format will load fine with good interactive performance!
+
+Horizontal scaling is a non-issue, since here is no concurrent state to scale,
+and only uses client-side computation via WebAssembly client. Client-only
+perspective can support as many concurrent users as can download the web
+application itself. Once the data is loaded, no server connection is needed and
+all operations occur in the client browser, imparting no additional runtime cost
+on the server beyond initial load. This also means updates and edits are local
+to the browser client and will be lost when the page is refreshed, unless
+otherwise persisted by your application.
+
+As the client-only design starts with creating a client-side Perspective
+`Table`, data can be provided by any standard web service in any Perspective
+compatible format (JSON, CSV or Apache Arrow).
+
+#### Javascript client
+
+```javascript
+const worker = await perspective.worker();
+const table = await worker.table(csv);
+
+const viewer = document.createElement("perspective-viewer");
+document.body.appendChild(viewer);
+await viewer.load(table);
+```
diff --git a/docs/md/explanation/architecture/client_server.md b/docs/md/explanation/architecture/client_server.md
new file mode 100644
index 0000000000..f6df4408eb
--- /dev/null
+++ b/docs/md/explanation/architecture/client_server.md
@@ -0,0 +1,58 @@
+# Client/Server replicated
+
+
+
+_For medium-sized, real-time, synchronized and/or editable data sets with many
+concurrent users._
+
+The dataset is instantiated in-memory with a Python or Node.js Perspective
+server, and web applications create duplicates of these tables in a local
+WebAssembly client in the browser, synchonized efficiently to the server via
+Apache Arrow. This design scales well with additional concurrent users, as
+browsers only need to download the initial data set and subsequent update
+deltas, while operations like scrolling, pivots, sorting, etc. are performed on
+the client.
+
+Python servers can make especially good use of additional threads, as
+Perspective will release the GIL for almost all operations. Interactive
+performance on the client is very good and identical to client-only
+architecture. Updates and edits are seamlessly synchonized across clients via
+their virtual server counterparts using websockets and Apache Arrow.
+
+#### Python and Tornado server
+
+```python
+from perspective import Server, PerspectiveTornadoHandler
+
+server = Server()
+client = server.new_local_client()
+client.table(csv, name="my_table")
+routes = [(
+ r"/websocket",
+ perspective.handlers.tornado.PerspectiveTornadoHandler,
+ {"perspective_server": server},
+)]
+
+app = tornado.web.Application(routes)
+app.listen(8080)
+loop = tornado.ioloop.IOLoop.current()
+loop.start()
+```
+
+#### Javascript client
+
+Perspective's websocket client interfaces with the Python server. then
+_replicates_ the server-side Table.
+
+```javascript
+const websocket = await perspective.websocket("ws://localhost:8080");
+const server_table = await websocket.open_table("my_table");
+const server_view = await server_table.view();
+
+const worker = await perspective.worker();
+const client_table = await worker.table(server_view);
+
+const viewer = document.createElement("perspective-viewer");
+document.body.appendChild(viewer);
+await viewer.load(client_table);
+```
diff --git a/docs/md/explanation/architecture/server_only.md b/docs/md/explanation/architecture/server_only.md
new file mode 100644
index 0000000000..09084c4b70
--- /dev/null
+++ b/docs/md/explanation/architecture/server_only.md
@@ -0,0 +1,33 @@
+# Server-only
+
+
+
+_For extremely large datasets with a small number of concurrent users._
+
+The dataset is instantiated in-memory with a Python or Node.js server, and web
+applications connect virtually. Has very good initial load performance, since no
+data is downloaded. Group-by and other operations will run column-parallel if
+configured.
+
+But interactive performance is poor, as every user interaction must page the
+server to render. Operations like scrolling are not as responsive and can be
+impacted by network latency. Web applications must be "always connected" to the
+server via WebSocket. Disconnecting will prevent any interaction, scrolling,
+etc. of the UI. Does not use WebAssembly.
+
+Each connected browser will impact server performance as long as the connection
+is open, which in turn impacts interactive performance of every client. This
+ultimately limits the horizontal scalabity of this architecture. Since each
+client reads the perspective `Table` virtually, changes like edits and updates
+are automatically reflected to all clients and persist across browser refresh.
+Using the same Python server as the previous design, we can simply skip the
+intermediate WebAssembly `Table` and pass the virtual table directly to `load()`
+
+```javascript
+const websocket = await perspective.websocket("ws://localhost:8080");
+const server_table = await websocket.open_table("my_table");
+
+const viewer = document.createElement("perspective-viewer");
+document.body.appendChild(viewer);
+await viewer.load(server_table);
+```
diff --git a/docs/md/explanation/javascript.md b/docs/md/explanation/javascript.md
new file mode 100644
index 0000000000..ffea687dde
--- /dev/null
+++ b/docs/md/explanation/javascript.md
@@ -0,0 +1,15 @@
+Perspective's JavaScript library offers a configurable UI powered by the same
+fast streaming data engine, just re-compiled to WebAssembly. A simple example
+which loads an [Apache Arrow](https://arrow.apache.org/) and computes a "Group
+By" operation, returning a new Arrow:
+
+```javascript
+import perspective from "@finos/perspective";
+
+const table = await perspective.table(apache_arrow_data);
+const view = await table.view({ group_by: ["CounterParty", "Security"] });
+const arrow = await view.to_arrow();
+```
+
+[More Examples](https://github.com/finos/perspective/tree/master/examples) are
+available on GitHub.
diff --git a/docs/md/explanation/javascript_builds.md b/docs/md/explanation/javascript_builds.md
new file mode 100644
index 0000000000..26efe0ae4c
--- /dev/null
+++ b/docs/md/explanation/javascript_builds.md
@@ -0,0 +1,42 @@
+# JavaScript Builds
+
+Perspective requires the browser to have access to Perspective's `.wasm`
+binaries _in addition_ to the bundled `.js` files, and as a result the build
+process requires a few extra steps. To ease integration, Perspective's NPM
+releases come with multiple prebuilt configurations.
+
+## Browser
+
+### ESM Builds
+
+The recommended builds for production use are packaged as ES Modules and require
+a _bootstrapping_ step in order to acquire the `.wasm` binaries and initialize
+Perspective's JavaScript with them. However, because they have no hard-coded
+dependencies on the `.wasm` paths, they are ideal for use with JavaScript
+bundlers such as ESBuild, Rollup, Vite or Webpack.
+
+### CDN Builds
+
+Perspective's CDN builds are good for non-bundled scenarios, such as importing
+directly from a `
+```
+
+## Node.js builds
+
+The Node.js runtime for the `@finos/perspective` module runs in-process by
+default and does not implement a `child_process` interface. Hence, there is no
+`worker()` method, and the module object itself directly exports the full
+`perspective` API.
+
+```javascript
+const perspective = require("@finos/perspective");
+```
+
+In Node.js, perspective does not run in a WebWorker (as this API does not exist
+in Node.js), so no need to call the `.worker()` factory function - the
+`perspective` library exports the functions directly and run synchronously in
+the main process.
diff --git a/docs/md/how_to/javascript/installation.md b/docs/md/how_to/javascript/installation.md
new file mode 100644
index 0000000000..0083fecc9d
--- /dev/null
+++ b/docs/md/how_to/javascript/installation.md
@@ -0,0 +1,31 @@
+# JavaScript NPM Installation
+
+Perspective releases contain several different builds for use in most
+environments.
+
+## Browser
+
+Perspective's WebAssembly data engine is available via NPM in the same package
+as its Node.js counterpart, `@finos/perspective`. The Perspective Viewer UI
+(which has no Node.js component) must be installed separately:
+
+```bash
+$ npm add @finos/perspective @finos/perspective-viewer
+```
+
+By itself, `@finos/perspective-viewer` does not provide any visualizations, only
+the UI framework. Perspective _Plugins_ provide visualizations and must be
+installed separately. All Plugins are optional - but a `
-
-Application developers can choose from [Client (WebAssembly)](#client-only),
-[Server (Python/Node)](#server-only) or
-[Client/Server Replicated](#clientserver-replicated) designs to bind data, and a
-web application can use one or a mix of these designs as needed. By serializing
-to Apache Arrow, tables are duplicated and synchronized across runtimes
-efficiently.
-
-Perspective is a multi-language platform. The examples in this section use
-Python and JavaScript as an example, but the same general principles apply to
-any `Client`/`Server` combination.
-
-## Client-only
-
-