@casoon/chartlet 0.1.0-alpha.5 → 0.1.0-alpha.6

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.
package/README.md CHANGED
@@ -3,12 +3,11 @@
3
3
  Build static, accessible SVG or HTML charts during an Astro build. The component runs only on
4
4
  the server and ships no chart JavaScript to the browser.
5
5
 
6
- The current alpha adapter calls the `chartlet` CLI, so install both the package and the CLI
7
- (Rust 1.88 or newer). The CLI must be on `PATH`, or set `CHARTLET_BIN` to its absolute path.
6
+ The package carries the renderer compiled to WebAssembly, so it is all you install. It needs
7
+ Node.js 22.12 or newer.
8
8
 
9
9
  ```sh
10
10
  npm install @casoon/chartlet@alpha
11
- cargo install chartlet --version 0.1.0-alpha.5
12
11
  ```
13
12
 
14
13
  ```astro
@@ -26,3 +25,47 @@ the same specification is embedded more than once.
26
25
  Use `format="svg"` for the graphic alone or `format="html"` for the default figure, caption,
27
26
  source, and data-table output. The HTML table uses a native disclosure by default; set
28
27
  `table="visible"` to show it permanently.
28
+
29
+ ## Render API
30
+
31
+ ```js
32
+ import { renderChart } from '@casoon/chartlet';
33
+
34
+ const { content, warnings } = renderChart(spec, { format: 'svg', idPrefix: 'revenue' });
35
+ ```
36
+
37
+ Options: `format`, `table`, `idPrefix`, `variant` (`mobile` renders the mobile variant alone as
38
+ SVG) and `strict`. `warnings` holds the lines the CLI would write; an invalid specification
39
+ throws with the CLI's message. The output is byte-identical to the `chartlet` CLI.
40
+
41
+ To render with an installed CLI instead of WebAssembly, set `CHARTLET_BIN` to its absolute path
42
+ or pass `binary`.
43
+
44
+ ## Cloudflare Workers and Vite
45
+
46
+ Runtimes that cannot compile WebAssembly from bytes, such as workerd, import the module and pass
47
+ it to `createRenderer` from `@casoon/chartlet/wasm`, which has no Node.js imports:
48
+
49
+ ```js
50
+ import wasm from '@casoon/chartlet/chartlet.wasm';
51
+ import { createRenderer } from '@casoon/chartlet/wasm';
52
+
53
+ const { renderChart } = createRenderer(wasm);
54
+ ```
55
+
56
+ In a Vite browser build, compile it from the emitted URL:
57
+
58
+ ```js
59
+ import wasmUrl from '@casoon/chartlet/chartlet.wasm?url';
60
+ import { createRenderer } from '@casoon/chartlet/wasm';
61
+
62
+ const { renderChart } = createRenderer(
63
+ await WebAssembly.compileStreaming(fetch(wasmUrl)),
64
+ );
65
+ ```
66
+
67
+ ## Development
68
+
69
+ `src/chartlet.wasm` is not committed. `npm run build:wasm` builds it from the `wasm/` crate of the
70
+ repository (target `wasm32-unknown-unknown`, optimized with `wasm-opt` when it is installed);
71
+ `npm pack` and `npm publish` run it first.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@casoon/chartlet",
3
- "version": "0.1.0-alpha.5",
3
+ "version": "0.1.0-alpha.6",
4
4
  "description": "Build-time SVG and HTML charts for static websites",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -19,6 +19,11 @@
19
19
  "types": "./src/index.d.ts",
20
20
  "import": "./src/render.mjs"
21
21
  },
22
+ "./wasm": {
23
+ "types": "./src/wasm.d.mts",
24
+ "import": "./src/wasm.mjs"
25
+ },
26
+ "./chartlet.wasm": "./src/chartlet.wasm",
22
27
  "./astro": "./src/Chart.astro"
23
28
  },
24
29
  "peerDependencies": {
@@ -33,6 +38,8 @@
33
38
  "astro": "^7.3.2"
34
39
  },
35
40
  "scripts": {
41
+ "build:wasm": "node scripts/build-wasm.mjs",
42
+ "prepack": "npm run build:wasm",
36
43
  "test": "node --test"
37
44
  },
38
45
  "engines": {
Binary file
package/src/render.d.mts CHANGED
@@ -1,11 +1,15 @@
1
1
  export type ChartFormat = "svg" | "html";
2
2
  export type TableMode = "details" | "visible";
3
+ /** Which layout the SVG profile renders; `mobile` needs a `mobile` field in the spec. */
4
+ export type ChartVariant = "desktop" | "mobile";
3
5
 
4
6
  export interface RenderChartOptions {
5
7
  format?: ChartFormat;
6
8
  table?: TableMode;
7
9
  idPrefix?: string;
10
+ variant?: ChartVariant;
8
11
  strict?: boolean;
12
+ /** A `chartlet` executable to render with instead of the bundled WebAssembly build. */
9
13
  binary?: string;
10
14
  }
11
15
 
package/src/render.mjs CHANGED
@@ -1,16 +1,50 @@
1
1
  import { spawnSync } from "node:child_process";
2
+ import { readFileSync } from "node:fs";
3
+
4
+ import { createRenderer } from "./wasm.mjs";
2
5
 
3
6
  const MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
4
7
 
8
+ let renderer;
9
+
10
+ // Renders with the bundled WebAssembly build, or with the CLI when `options.binary` or
11
+ // `CHARTLET_BIN` names one. Both produce the same bytes.
5
12
  export function renderChart(spec, options = {}) {
13
+ const binary = options.binary ?? process.env.CHARTLET_BIN;
14
+ if (!binary) {
15
+ renderer ??= createRenderer(new WebAssembly.Module(readWasm()));
16
+ return renderer.renderChart(spec, options);
17
+ }
18
+ return renderWithCli(binary, spec, options);
19
+ }
20
+
21
+ // Resolved by package name, not relative to this file: bundlers such as Vite copy this module
22
+ // into a server chunk elsewhere, but leave the package where Node can resolve it.
23
+ function readWasm() {
24
+ const url = new URL(import.meta.resolve("@casoon/chartlet/chartlet.wasm"));
25
+ try {
26
+ return readFileSync(url);
27
+ } catch (error) {
28
+ if (error.code === "ENOENT") {
29
+ throw new Error(
30
+ `chartlet.wasm is missing at ${url.pathname}. In a checkout, run \`npm run build:wasm\`; otherwise set CHARTLET_BIN to a chartlet executable.`,
31
+ );
32
+ }
33
+ throw error;
34
+ }
35
+ }
36
+
37
+ function renderWithCli(binary, spec, options) {
6
38
  const format = options.format ?? "html";
7
39
  const table = options.table ?? "details";
8
- const binary = options.binary ?? process.env.CHARTLET_BIN ?? "chartlet";
9
40
  const args = ["render", "-", "--format", format, "--table", table];
10
41
 
11
42
  if (options.idPrefix) {
12
43
  args.push("--id-prefix", options.idPrefix);
13
44
  }
45
+ if (options.variant) {
46
+ args.push("--variant", options.variant);
47
+ }
14
48
  if (options.strict) {
15
49
  args.push("--strict");
16
50
  }
@@ -24,7 +58,7 @@ export function renderChart(spec, options = {}) {
24
58
  if (result.error) {
25
59
  if (result.error.code === "ENOENT") {
26
60
  throw new Error(
27
- `chartlet executable not found at ${JSON.stringify(binary)}. Install the CLI or set CHARTLET_BIN.`,
61
+ `chartlet executable not found at ${JSON.stringify(binary)}. Install the CLI, or unset CHARTLET_BIN to use the bundled WebAssembly build.`,
28
62
  );
29
63
  }
30
64
  throw result.error;
package/src/wasm.d.mts ADDED
@@ -0,0 +1,9 @@
1
+ import type { RenderChartOptions, RenderChartResult } from "./render.mjs";
2
+
3
+ export interface ChartRenderer {
4
+ /** Renders in WebAssembly; `options.binary` is ignored. */
5
+ renderChart(spec: Record<string, unknown>, options?: RenderChartOptions): RenderChartResult;
6
+ }
7
+
8
+ /** Instantiates the renderer from the compiled `@casoon/chartlet/chartlet.wasm` module. */
9
+ export declare function createRenderer(module: WebAssembly.Module): ChartRenderer;
package/src/wasm.mjs ADDED
@@ -0,0 +1,46 @@
1
+ // The renderer compiled to WebAssembly. No Node.js imports: runtimes that cannot compile
2
+ // WebAssembly from bytes at run time (workerd, some bundlers) import `chartlet.wasm` as a module
3
+ // and pass it in.
4
+
5
+ const encoder = new TextEncoder();
6
+ const decoder = new TextDecoder();
7
+
8
+ export function createRenderer(module) {
9
+ const { memory, alloc, dealloc, render, result_len } = new WebAssembly.Instance(module, {})
10
+ .exports;
11
+
12
+ return {
13
+ renderChart(spec, options = {}) {
14
+ const request = encoder.encode(
15
+ JSON.stringify({
16
+ spec: JSON.stringify(spec),
17
+ options: {
18
+ format: options.format ?? "html",
19
+ table: options.table ?? "details",
20
+ idPrefix: options.idPrefix || undefined,
21
+ variant: options.variant,
22
+ strict: options.strict ?? false,
23
+ },
24
+ }),
25
+ );
26
+ const input = alloc(request.length);
27
+ new Uint8Array(memory.buffer, input, request.length).set(request);
28
+ const output = render(input, request.length);
29
+ const length = result_len();
30
+ const response = JSON.parse(decoder.decode(new Uint8Array(memory.buffer, output, length)));
31
+ dealloc(input, request.length);
32
+ dealloc(output, length);
33
+
34
+ // The same lines the CLI writes to stderr.
35
+ const warnings = response.warnings.map(
36
+ ({ code, path, message }) => `warning[${code}] at ${path}: ${message}`,
37
+ );
38
+ if (!response.ok) {
39
+ const { code, path, message } = response.error;
40
+ const failure = path == null ? `chartlet: ${message}` : `chartlet: ${code} at ${path}: ${message}`;
41
+ throw new Error([...warnings, failure].join("\n"));
42
+ }
43
+ return { content: response.content, warnings };
44
+ },
45
+ };
46
+ }