@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 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 `strict`. `warnings` holds the lines the CLI would write; an invalid specification
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.6",
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 { readFileSync } from "node:fs";
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
- const result = spawnSync(binary, args, {
53
- input: JSON.stringify(spec),
54
- encoding: "utf8",
55
- maxBuffer: MAX_OUTPUT_BYTES,
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
- if (result.status !== 0) {
67
- throw new Error(result.stderr.trim() || `chartlet exited with status ${result.status}`);
68
- }
142
+ return { result, manifest };
143
+ }
69
144
 
70
- return {
71
- content: result.stdout.trimEnd(),
72
- warnings: result.stderr
73
- .split("\n")
74
- .map((warning) => warning.trim())
75
- .filter(Boolean),
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 { RenderChartOptions, RenderChartResult } from "./render.mjs";
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 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);
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
- return { content: response.content, warnings };
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
  }