@casoon/chartlet 0.1.0-alpha.6 → 0.1.0-alpha.7
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 +24 -1
- package/package.json +2 -2
- package/src/chartlet.wasm +0 -0
- package/src/render.d.mts +70 -0
- package/src/render.mjs +95 -16
- package/src/wasm.d.mts +10 -1
- package/src/wasm.mjs +37 -20
package/README.md
CHANGED
|
@@ -35,12 +35,35 @@ const { content, warnings } = renderChart(spec, { format: 'svg', idPrefix: 'reve
|
|
|
35
35
|
```
|
|
36
36
|
|
|
37
37
|
Options: `format`, `table`, `idPrefix`, `variant` (`mobile` renders the mobile variant alone as
|
|
38
|
-
SVG) and `
|
|
38
|
+
SVG), `strict` and `manifest` (`true` adds a provenance `manifest` to the result: chartlet
|
|
39
|
+
version, SHA-256 of the canonical specification and of `content`, format, variant, ID prefix and
|
|
40
|
+
warnings, without a timestamp). `warnings` holds the lines the CLI would write; an invalid specification
|
|
39
41
|
throws with the CLI's message. The output is byte-identical to the `chartlet` CLI.
|
|
40
42
|
|
|
43
|
+
`renderChartDetailed(spec, options)` takes the same arguments but does not throw on an invalid
|
|
44
|
+
specification: it returns `{ ok, error?, warnings }` with `{ code, path, message }` diagnostics,
|
|
45
|
+
plus `content`, `styleHashes` and `manifest` when rendering succeeded. `spec` may also be JSON
|
|
46
|
+
text.
|
|
47
|
+
|
|
41
48
|
To render with an installed CLI instead of WebAssembly, set `CHARTLET_BIN` to its absolute path
|
|
42
49
|
or pass `binary`.
|
|
43
50
|
|
|
51
|
+
## Content Security Policy
|
|
52
|
+
|
|
53
|
+
A chart styles itself with inline `<style>` elements. `styleHashes` lists their CSP source
|
|
54
|
+
expressions (`'sha256-…'`), one per distinct element, in order of first appearance; a strict
|
|
55
|
+
`style-src` allows exactly those:
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
const { content, styleHashes } = renderChart(spec, { idPrefix: 'revenue' });
|
|
59
|
+
|
|
60
|
+
headers.set('Content-Security-Policy', `style-src 'self' ${styleHashes.join(' ')}`);
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Astro takes the hashes without quotes: per page through
|
|
64
|
+
`Astro.csp?.insertStyleHash(hash.slice(1, -1))`, or for all pages in
|
|
65
|
+
`security.csp.styleDirective.hashes`. `createRenderer` returns the same field.
|
|
66
|
+
|
|
44
67
|
## Cloudflare Workers and Vite
|
|
45
68
|
|
|
46
69
|
Runtimes that cannot compile WebAssembly from bytes, such as workerd, import the module and pass
|
package/package.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@casoon/chartlet",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.7",
|
|
4
4
|
"description": "Build-time SVG and HTML charts for static websites",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|
|
9
|
-
"url": "https://github.com/casoon/chartlet.git",
|
|
9
|
+
"url": "git+https://github.com/casoon/chartlet.git",
|
|
10
10
|
"directory": "packages/chartlet"
|
|
11
11
|
},
|
|
12
12
|
"files": [
|
package/src/chartlet.wasm
CHANGED
|
Binary file
|
package/src/render.d.mts
CHANGED
|
@@ -9,16 +9,86 @@ export interface RenderChartOptions {
|
|
|
9
9
|
idPrefix?: string;
|
|
10
10
|
variant?: ChartVariant;
|
|
11
11
|
strict?: boolean;
|
|
12
|
+
/** Also return a provenance manifest of the render in `manifest`. */
|
|
13
|
+
manifest?: boolean;
|
|
12
14
|
/** A `chartlet` executable to render with instead of the bundled WebAssembly build. */
|
|
13
15
|
binary?: string;
|
|
14
16
|
}
|
|
15
17
|
|
|
18
|
+
export interface ChartManifestWarning {
|
|
19
|
+
code: string;
|
|
20
|
+
path: string;
|
|
21
|
+
message: string;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* The provenance of one render. It carries no timestamp: the same render always yields the same
|
|
26
|
+
* manifest.
|
|
27
|
+
*/
|
|
28
|
+
export interface ChartManifest {
|
|
29
|
+
/** The version of the chartlet crate that rendered. */
|
|
30
|
+
chartlet: string;
|
|
31
|
+
schemaVersion: number;
|
|
32
|
+
/** `sha256:` and the hex SHA-256 of the canonical (parsed and re-serialized) specification. */
|
|
33
|
+
specHash: string;
|
|
34
|
+
/** `sha256:` and the hex SHA-256 of `content` as UTF-8. */
|
|
35
|
+
outputHash: string;
|
|
36
|
+
format: ChartFormat;
|
|
37
|
+
variant: ChartVariant;
|
|
38
|
+
/** The ID prefix passed in, or the one derived from the specification. */
|
|
39
|
+
idPrefix: string;
|
|
40
|
+
warnings: ChartManifestWarning[];
|
|
41
|
+
}
|
|
42
|
+
|
|
16
43
|
export interface RenderChartResult {
|
|
17
44
|
content: string;
|
|
45
|
+
/**
|
|
46
|
+
* The CSP source expressions (`'sha256-…'`) of every distinct inline `<style>` element in
|
|
47
|
+
* `content`, in order of first appearance — what a strict `style-src` has to allow.
|
|
48
|
+
*/
|
|
49
|
+
styleHashes: string[];
|
|
18
50
|
warnings: string[];
|
|
51
|
+
/** Present when `options.manifest` is set. */
|
|
52
|
+
manifest?: ChartManifest;
|
|
19
53
|
}
|
|
20
54
|
|
|
21
55
|
export declare function renderChart(
|
|
22
56
|
spec: Record<string, unknown>,
|
|
23
57
|
options?: RenderChartOptions,
|
|
24
58
|
): RenderChartResult;
|
|
59
|
+
|
|
60
|
+
/** An error or warning as the CLI reports it with `--diagnostics json`. */
|
|
61
|
+
export interface ChartDiagnostic {
|
|
62
|
+
code: string;
|
|
63
|
+
/** A JSON Pointer into the specification, or `null` for option errors and `strict_warnings`. */
|
|
64
|
+
path: string | null;
|
|
65
|
+
message: string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export interface RenderChartDetailedSuccess {
|
|
69
|
+
ok: true;
|
|
70
|
+
content: string;
|
|
71
|
+
styleHashes: string[];
|
|
72
|
+
warnings: ChartDiagnostic[];
|
|
73
|
+
/** Present when `options.manifest` is set. */
|
|
74
|
+
manifest?: ChartManifest;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export interface RenderChartDetailedFailure {
|
|
78
|
+
ok: false;
|
|
79
|
+
error: ChartDiagnostic;
|
|
80
|
+
warnings: ChartDiagnostic[];
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
export type RenderChartDetailedResult = RenderChartDetailedSuccess | RenderChartDetailedFailure;
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Renders like `renderChart`, but returns a failed render as `{ ok: false, error }` instead of
|
|
87
|
+
* throwing, and every warning as a structured diagnostic. A string `spec` is read as JSON text,
|
|
88
|
+
* so malformed JSON is reported as `invalid_json`. A missing WebAssembly build or CLI still
|
|
89
|
+
* throws.
|
|
90
|
+
*/
|
|
91
|
+
export declare function renderChartDetailed(
|
|
92
|
+
spec: Record<string, unknown> | string,
|
|
93
|
+
options?: RenderChartOptions,
|
|
94
|
+
): RenderChartDetailedResult;
|
package/src/render.mjs
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
import { spawnSync } from "node:child_process";
|
|
2
|
-
import {
|
|
2
|
+
import { createHash } from "node:crypto";
|
|
3
|
+
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
|
|
4
|
+
import { tmpdir } from "node:os";
|
|
5
|
+
import { join } from "node:path";
|
|
3
6
|
|
|
4
7
|
import { createRenderer } from "./wasm.mjs";
|
|
5
8
|
|
|
@@ -34,7 +37,60 @@ function readWasm() {
|
|
|
34
37
|
}
|
|
35
38
|
}
|
|
36
39
|
|
|
40
|
+
// Renders like `renderChart`, but reports the outcome as data instead of throwing: `ok`, the
|
|
41
|
+
// structured `error` of a failed render, and every warning as `{ code, path, message }`.
|
|
42
|
+
export function renderChartDetailed(spec, options = {}) {
|
|
43
|
+
const binary = options.binary ?? process.env.CHARTLET_BIN;
|
|
44
|
+
if (!binary) {
|
|
45
|
+
renderer ??= createRenderer(new WebAssembly.Module(readWasm()));
|
|
46
|
+
return renderer.renderChartDetailed(spec, options);
|
|
47
|
+
}
|
|
48
|
+
const { result, manifest } = runCli(
|
|
49
|
+
binary,
|
|
50
|
+
typeof spec === "string" ? spec : JSON.stringify(spec),
|
|
51
|
+
options,
|
|
52
|
+
["--diagnostics", "json"],
|
|
53
|
+
);
|
|
54
|
+
const diagnostics = JSON.parse(result.stderr);
|
|
55
|
+
if (!diagnostics.ok) {
|
|
56
|
+
return { ok: false, error: diagnostics.error, warnings: diagnostics.warnings };
|
|
57
|
+
}
|
|
58
|
+
const content = result.stdout.trimEnd();
|
|
59
|
+
const rendered = {
|
|
60
|
+
ok: true,
|
|
61
|
+
content,
|
|
62
|
+
styleHashes: styleHashes(content),
|
|
63
|
+
warnings: diagnostics.warnings,
|
|
64
|
+
};
|
|
65
|
+
if (manifest) {
|
|
66
|
+
rendered.manifest = manifest;
|
|
67
|
+
}
|
|
68
|
+
return rendered;
|
|
69
|
+
}
|
|
70
|
+
|
|
37
71
|
function renderWithCli(binary, spec, options) {
|
|
72
|
+
const { result, manifest } = runCli(binary, JSON.stringify(spec), options, []);
|
|
73
|
+
if (result.status !== 0) {
|
|
74
|
+
throw new Error(result.stderr.trim() || `chartlet exited with status ${result.status}`);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const content = result.stdout.trimEnd();
|
|
78
|
+
const rendered = {
|
|
79
|
+
content,
|
|
80
|
+
styleHashes: styleHashes(content),
|
|
81
|
+
warnings: result.stderr
|
|
82
|
+
.split("\n")
|
|
83
|
+
.map((warning) => warning.trim())
|
|
84
|
+
.filter(Boolean),
|
|
85
|
+
};
|
|
86
|
+
if (manifest) {
|
|
87
|
+
rendered.manifest = manifest;
|
|
88
|
+
}
|
|
89
|
+
return rendered;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
// Runs `chartlet render` on `input` and returns the process result with the manifest it wrote.
|
|
93
|
+
function runCli(binary, input, options, extraArgs) {
|
|
38
94
|
const format = options.format ?? "html";
|
|
39
95
|
const table = options.table ?? "details";
|
|
40
96
|
const args = ["render", "-", "--format", format, "--table", table];
|
|
@@ -48,12 +104,32 @@ function renderWithCli(binary, spec, options) {
|
|
|
48
104
|
if (options.strict) {
|
|
49
105
|
args.push("--strict");
|
|
50
106
|
}
|
|
107
|
+
args.push(...extraArgs);
|
|
108
|
+
// The CLI writes the manifest to a file; it is read back and removed with its directory.
|
|
109
|
+
const manifestDirectory = options.manifest
|
|
110
|
+
? mkdtempSync(join(tmpdir(), "chartlet-manifest-"))
|
|
111
|
+
: undefined;
|
|
112
|
+
const manifestPath = manifestDirectory && join(manifestDirectory, "manifest.json");
|
|
113
|
+
if (manifestPath) {
|
|
114
|
+
args.push("--manifest", manifestPath);
|
|
115
|
+
}
|
|
51
116
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
117
|
+
let result;
|
|
118
|
+
let manifest;
|
|
119
|
+
try {
|
|
120
|
+
result = spawnSync(binary, args, {
|
|
121
|
+
input,
|
|
122
|
+
encoding: "utf8",
|
|
123
|
+
maxBuffer: MAX_OUTPUT_BYTES,
|
|
124
|
+
});
|
|
125
|
+
if (manifestPath && result.status === 0) {
|
|
126
|
+
manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
|
|
127
|
+
}
|
|
128
|
+
} finally {
|
|
129
|
+
if (manifestDirectory) {
|
|
130
|
+
rmSync(manifestDirectory, { recursive: true, force: true });
|
|
131
|
+
}
|
|
132
|
+
}
|
|
57
133
|
|
|
58
134
|
if (result.error) {
|
|
59
135
|
if (result.error.code === "ENOENT") {
|
|
@@ -63,15 +139,18 @@ function renderWithCli(binary, spec, options) {
|
|
|
63
139
|
}
|
|
64
140
|
throw result.error;
|
|
65
141
|
}
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
}
|
|
142
|
+
return { result, manifest };
|
|
143
|
+
}
|
|
69
144
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
145
|
+
// The same CSP source expressions the WebAssembly build returns: one per distinct `<style>`
|
|
146
|
+
// element, in order of first appearance.
|
|
147
|
+
function styleHashes(content) {
|
|
148
|
+
const hashes = [];
|
|
149
|
+
for (const [, style] of content.matchAll(/<style>(.*?)<\/style>/gs)) {
|
|
150
|
+
const hash = `'sha256-${createHash("sha256").update(style).digest("base64")}'`;
|
|
151
|
+
if (!hashes.includes(hash)) {
|
|
152
|
+
hashes.push(hash);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
return hashes;
|
|
77
156
|
}
|
package/src/wasm.d.mts
CHANGED
|
@@ -1,8 +1,17 @@
|
|
|
1
|
-
import type {
|
|
1
|
+
import type {
|
|
2
|
+
RenderChartDetailedResult,
|
|
3
|
+
RenderChartOptions,
|
|
4
|
+
RenderChartResult,
|
|
5
|
+
} from "./render.mjs";
|
|
2
6
|
|
|
3
7
|
export interface ChartRenderer {
|
|
4
8
|
/** Renders in WebAssembly; `options.binary` is ignored. */
|
|
5
9
|
renderChart(spec: Record<string, unknown>, options?: RenderChartOptions): RenderChartResult;
|
|
10
|
+
/** Renders in WebAssembly and reports the outcome as data; see `renderChartDetailed`. */
|
|
11
|
+
renderChartDetailed(
|
|
12
|
+
spec: Record<string, unknown> | string,
|
|
13
|
+
options?: RenderChartOptions,
|
|
14
|
+
): RenderChartDetailedResult;
|
|
6
15
|
}
|
|
7
16
|
|
|
8
17
|
/** Instantiates the renderer from the compiled `@casoon/chartlet/chartlet.wasm` module. */
|
package/src/wasm.mjs
CHANGED
|
@@ -9,27 +9,34 @@ export function createRenderer(module) {
|
|
|
9
9
|
const { memory, alloc, dealloc, render, result_len } = new WebAssembly.Instance(module, {})
|
|
10
10
|
.exports;
|
|
11
11
|
|
|
12
|
+
// Sends one request to the renderer and returns its parsed JSON response.
|
|
13
|
+
function respond(spec, options) {
|
|
14
|
+
const request = encoder.encode(
|
|
15
|
+
JSON.stringify({
|
|
16
|
+
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
|
+
manifest: options.manifest ?? false,
|
|
24
|
+
},
|
|
25
|
+
}),
|
|
26
|
+
);
|
|
27
|
+
const input = alloc(request.length);
|
|
28
|
+
new Uint8Array(memory.buffer, input, request.length).set(request);
|
|
29
|
+
const output = render(input, request.length);
|
|
30
|
+
const length = result_len();
|
|
31
|
+
const response = JSON.parse(decoder.decode(new Uint8Array(memory.buffer, output, length)));
|
|
32
|
+
dealloc(input, request.length);
|
|
33
|
+
dealloc(output, length);
|
|
34
|
+
return response;
|
|
35
|
+
}
|
|
36
|
+
|
|
12
37
|
return {
|
|
13
38
|
renderChart(spec, options = {}) {
|
|
14
|
-
const
|
|
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);
|
|
39
|
+
const response = respond(JSON.stringify(spec), options);
|
|
33
40
|
|
|
34
41
|
// The same lines the CLI writes to stderr.
|
|
35
42
|
const warnings = response.warnings.map(
|
|
@@ -40,7 +47,17 @@ export function createRenderer(module) {
|
|
|
40
47
|
const failure = path == null ? `chartlet: ${message}` : `chartlet: ${code} at ${path}: ${message}`;
|
|
41
48
|
throw new Error([...warnings, failure].join("\n"));
|
|
42
49
|
}
|
|
43
|
-
|
|
50
|
+
const result = { content: response.content, styleHashes: response.styleHashes, warnings };
|
|
51
|
+
if (response.manifest) {
|
|
52
|
+
result.manifest = response.manifest;
|
|
53
|
+
}
|
|
54
|
+
return result;
|
|
55
|
+
},
|
|
56
|
+
|
|
57
|
+
// The renderer's response as it is: `ok`, `error` or `content`, `styleHashes` and
|
|
58
|
+
// `manifest`, and the warnings as `{ code, path, message }`. A string is taken as JSON text.
|
|
59
|
+
renderChartDetailed(spec, options = {}) {
|
|
60
|
+
return respond(typeof spec === "string" ? spec : JSON.stringify(spec), options);
|
|
44
61
|
},
|
|
45
62
|
};
|
|
46
63
|
}
|