@basthon/kernel-javascript 0.86.0 → 0.88.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.
package/lib/kernel.d.ts CHANGED
@@ -1,11 +1,39 @@
1
1
  import { KernelMainBase } from "@basthon/kernel-base/worker";
2
+ import type { KernelOptions } from "@basthon/kernel-base";
2
3
  import { JavaScriptKernelWorker } from "./worker";
4
+ /**
5
+ * The JavaScript kernel (main thread side): the code runs in its worker
6
+ * (see `JavaScriptKernelWorker`).
7
+ */
3
8
  export declare class JavaScriptKernel extends KernelMainBase<JavaScriptKernelWorker> {
4
- constructor(options: any);
9
+ /**
10
+ * @param options - The kernel's options.
11
+ */
12
+ constructor(options: KernelOptions);
13
+ /**
14
+ * Create the kernel's worker (an opaque origin worker, see
15
+ * `KernelMainBase.newWorker`).
16
+ */
5
17
  protected newWorker(): Worker;
18
+ /**
19
+ * The kernel's language (see `KernelBase.language`).
20
+ */
6
21
  language(): string;
22
+ /**
23
+ * The language's name, as displayed (see `KernelBase.languageName`).
24
+ */
7
25
  languageName(): string;
26
+ /**
27
+ * The extensions of the files installed as modules (see
28
+ * `KernelBase.moduleExts`).
29
+ */
8
30
  moduleExts(): string[];
31
+ /**
32
+ * The console's prompt (see `KernelBase.ps1`).
33
+ */
9
34
  ps1(): string;
35
+ /**
36
+ * The console's continuation prompt (see `KernelBase.ps2`).
37
+ */
10
38
  ps2(): string;
11
39
  }
package/lib/kernel.js CHANGED
@@ -1,26 +1,53 @@
1
1
  import { KernelMainBase } from "@basthon/kernel-base/worker";
2
+ /**
3
+ * The JavaScript kernel (main thread side): the code runs in its worker
4
+ * (see `JavaScriptKernelWorker`).
5
+ */
2
6
  export class JavaScriptKernel extends KernelMainBase {
7
+ /**
8
+ * @param options - The kernel's options.
9
+ */
3
10
  constructor(options) {
4
11
  super(options);
5
12
  }
13
+ /**
14
+ * Create the kernel's worker (an opaque origin worker, see
15
+ * `KernelMainBase.newWorker`).
16
+ */
6
17
  newWorker() {
7
18
  return new Worker(new URL("./comlink-worker.js", import.meta.url), {
8
19
  //@ts-ignore
9
20
  sandboxed: true, // removing this line will cause security issues
10
21
  });
11
22
  }
23
+ /**
24
+ * The kernel's language (see `KernelBase.language`).
25
+ */
12
26
  language() {
13
27
  return "javascript";
14
28
  }
29
+ /**
30
+ * The language's name, as displayed (see `KernelBase.languageName`).
31
+ */
15
32
  languageName() {
16
33
  return "Javascript";
17
34
  }
35
+ /**
36
+ * The extensions of the files installed as modules (see
37
+ * `KernelBase.moduleExts`).
38
+ */
18
39
  moduleExts() {
19
40
  return ["js"];
20
41
  }
42
+ /**
43
+ * The console's prompt (see `KernelBase.ps1`).
44
+ */
21
45
  ps1() {
22
46
  return " js> ";
23
47
  }
48
+ /**
49
+ * The console's continuation prompt (see `KernelBase.ps2`).
50
+ */
24
51
  ps2() {
25
52
  return "...> ";
26
53
  }
package/lib/worker.d.ts CHANGED
@@ -1,24 +1,82 @@
1
1
  import { KernelWorkerBase } from "@basthon/kernel-base/worker";
2
+ /**
3
+ * The JavaScript kernel's worker: the code is evaluated in the worker's
4
+ * global scope (no page: no `document`); `console.log` and
5
+ * `console.error` print, `prompt` asks for an input, and the global
6
+ * `basthon` object gives the kernel's functions (`sleep`, `display`,
7
+ * `createCanvas`, `displayLiveCanvas`, `download`...).
8
+ */
2
9
  export declare class JavaScriptKernelWorker extends KernelWorkerBase {
10
+ /**
11
+ * @param options - The kernel's options (see `KernelWorkerBase`).
12
+ */
3
13
  constructor(options?: any);
14
+ /**
15
+ * The kernel's language (see `KernelWorkerBase.language`).
16
+ */
4
17
  language(): string;
18
+ /**
19
+ * Redirect `console.info` and `console.warn` to the outputs and print the
20
+ * uncaught errors.
21
+ */
5
22
  protected _init(): Promise<void>;
23
+ /**
24
+ * Evaluate code in the global scope (see `KernelWorkerBase._eval`):
25
+ * `console.log` and `console.error` print on stdout and stderr, a returned
26
+ * promise is awaited.
27
+ *
28
+ * @param data - The evaluation's data.
29
+ * @param code - The code.
30
+ * @returns The value of the code (inspected, `text/plain`), or `undefined`.
31
+ */
6
32
  protected _eval(data: any, code: string): Promise<any>;
7
33
  /**
8
- * Display a canvas created with basthon.createCanvas(width, height) (to
9
- * be called by the user's code as basthon.displayLiveCanvas(canvas)).
10
- * The canvas is live: its drawings are displayed and it receives mouse
11
- * events (keyboard ones on canvas.ownerDocument), as a canvas of a page
12
- * (see kernel-base's canvas/worker/live-canvas.ts).
34
+ * Display a canvas created with `basthon.createCanvas(width, height)` (to
35
+ * be called by the user's code as `basthon.displayLiveCanvas(canvas)`).
36
+ * The canvas is live: its drawings are displayed and it receives the mouse
37
+ * events (and the keyboard ones on `canvas.ownerDocument`), as a canvas of
38
+ * a page (see kernel-base's `canvas/worker/live-canvas.ts`).
39
+ *
40
+ * @param canvas - The canvas.
13
41
  */
14
42
  displayLiveCanvas(canvas: OffscreenCanvas | HTMLCanvasElement): Promise<void>;
43
+ /**
44
+ * Download a file (`basthon.download(content, filename)` in the user's
45
+ * code): a string is the text of the file (encoded in UTF-8), as the main
46
+ * thread only accepts bytes or data URLs.
47
+ *
48
+ * @param content - The file's content: text or bytes.
49
+ * @param filename - The name of the saved file.
50
+ */
51
+ download(content: Uint8Array | string, filename: string): void;
52
+ /**
53
+ * No filesystem: the file is ignored (an error is printed).
54
+ *
55
+ * @param filename - The file's name.
56
+ * @param content - The file's content.
57
+ */
15
58
  putFile(filename: string, content: ArrayBuffer): void;
59
+ /**
60
+ * Run a `.js` module in the global scope.
61
+ *
62
+ * @param filename - The module's file name.
63
+ * @param content - The module's content.
64
+ * @throws If it is not a `.js` file.
65
+ */
16
66
  putModule(filename: string, content: ArrayBuffer): Promise<void>;
67
+ /**
68
+ * Complete the last word with the names of the global scope.
69
+ *
70
+ * @param code - The code before the cursor.
71
+ * @returns `[completions, start]`.
72
+ */
17
73
  complete(code: string): Promise<[string[], number] | []>;
18
74
  /**
19
- * Is the source ready to be evaluated or want we more? It wants more
20
- * when it does not parse because it ends too early (e.g. an unclosed
21
- * block): as Python's codeop.
75
+ * Does the code need more lines? Yes when it doesn't parse because it
76
+ * ends too early (e.g. an unclosed block), as Python's `codeop`.
77
+ *
78
+ * @param code - The lines typed so far.
79
+ * @returns `true` if the code is incomplete.
22
80
  */
23
81
  more(code: string): Promise<boolean>;
24
82
  }
package/lib/worker.js CHANGED
@@ -3,11 +3,14 @@ import objectInspect from "object-inspect";
3
3
  import { KernelWorkerBase } from "@basthon/kernel-base/worker";
4
4
  const PARSE_OPTIONS = { ecmaVersion: "latest", sourceType: "script" };
5
5
  /**
6
- * Code where the top-level declarations (let, const and class) are global
7
- * variables (var), as in a browser's console: they persist from an
8
- * evaluation to the next (the code is evaluated by an indirect eval where
9
- * they would be local to the evaluation). Unchanged if it does not parse
10
- * (the evaluation reports the error).
6
+ * The code where the top-level declarations (`let`, `const` and `class`)
7
+ * are global variables (`var`), as in a browser's console: they persist
8
+ * from an evaluation to the next (the code is evaluated by an indirect
9
+ * `eval`, where they would be local to the evaluation).
10
+ *
11
+ * @param code - The code.
12
+ * @returns The changed code (unchanged if it doesn't parse: the
13
+ * evaluation reports the error).
11
14
  */
12
15
  const persistentDeclarations = (code) => {
13
16
  let program;
@@ -36,22 +39,45 @@ const persistentDeclarations = (code) => {
36
39
  result = result.slice(0, start) + replacement + result.slice(end);
37
40
  return result;
38
41
  };
42
+ /**
43
+ * The JavaScript kernel's worker: the code is evaluated in the worker's
44
+ * global scope (no page: no `document`); `console.log` and
45
+ * `console.error` print, `prompt` asks for an input, and the global
46
+ * `basthon` object gives the kernel's functions (`sleep`, `display`,
47
+ * `createCanvas`, `displayLiveCanvas`, `download`...).
48
+ */
39
49
  export class JavaScriptKernelWorker extends KernelWorkerBase {
50
+ /**
51
+ * @param options - The kernel's options (see `KernelWorkerBase`).
52
+ */
40
53
  constructor(options) {
41
54
  // do not forget to call the parent constructor
42
55
  super(options);
43
56
  }
57
+ /**
58
+ * The kernel's language (see `KernelWorkerBase.language`).
59
+ */
44
60
  language() {
45
61
  return "javascript";
46
62
  }
47
- /*
48
- * Initialize the kernel.
63
+ /**
64
+ * Redirect `console.info` and `console.warn` to the outputs and print the
65
+ * uncaught errors.
49
66
  */
50
67
  async _init() {
51
68
  console.info = (...args) => console.log(...args);
52
69
  console.warn = (...args) => console.error(...args);
53
70
  globalThis.addEventListener("error", (e) => console.error(e.toString()));
54
71
  }
72
+ /**
73
+ * Evaluate code in the global scope (see `KernelWorkerBase._eval`):
74
+ * `console.log` and `console.error` print on stdout and stderr, a returned
75
+ * promise is awaited.
76
+ *
77
+ * @param data - The evaluation's data.
78
+ * @param code - The code.
79
+ * @returns The value of the code (inspected, `text/plain`), or `undefined`.
80
+ */
55
81
  async _eval(data, code) {
56
82
  console.log = (...args) => {
57
83
  this.sendStdoutStream(data, args.join(" ") + "\n");
@@ -66,20 +92,48 @@ export class JavaScriptKernelWorker extends KernelWorkerBase {
66
92
  : { "text/plain": objectInspect(result) };
67
93
  }
68
94
  /**
69
- * Display a canvas created with basthon.createCanvas(width, height) (to
70
- * be called by the user's code as basthon.displayLiveCanvas(canvas)).
71
- * The canvas is live: its drawings are displayed and it receives mouse
72
- * events (keyboard ones on canvas.ownerDocument), as a canvas of a page
73
- * (see kernel-base's canvas/worker/live-canvas.ts).
95
+ * Display a canvas created with `basthon.createCanvas(width, height)` (to
96
+ * be called by the user's code as `basthon.displayLiveCanvas(canvas)`).
97
+ * The canvas is live: its drawings are displayed and it receives the mouse
98
+ * events (and the keyboard ones on `canvas.ownerDocument`), as a canvas of
99
+ * a page (see kernel-base's `canvas/worker/live-canvas.ts`).
100
+ *
101
+ * @param canvas - The canvas.
74
102
  */
75
103
  displayLiveCanvas(canvas) {
76
104
  const promise = super.displayLiveCanvas(canvas);
77
105
  this.addEvalPromise(promise);
78
106
  return promise;
79
107
  }
108
+ /**
109
+ * Download a file (`basthon.download(content, filename)` in the user's
110
+ * code): a string is the text of the file (encoded in UTF-8), as the main
111
+ * thread only accepts bytes or data URLs.
112
+ *
113
+ * @param content - The file's content: text or bytes.
114
+ * @param filename - The name of the saved file.
115
+ */
116
+ download(content, filename) {
117
+ if (typeof content === "string")
118
+ content = new TextEncoder().encode(content);
119
+ super.download(content, filename);
120
+ }
121
+ /**
122
+ * No filesystem: the file is ignored (an error is printed).
123
+ *
124
+ * @param filename - The file's name.
125
+ * @param content - The file's content.
126
+ */
80
127
  putFile(filename, content) {
81
128
  console.error(`File ${filename} not added since putFile has no mean in the JS context.`);
82
129
  }
130
+ /**
131
+ * Run a `.js` module in the global scope.
132
+ *
133
+ * @param filename - The module's file name.
134
+ * @param content - The module's content.
135
+ * @throws If it is not a `.js` file.
136
+ */
83
137
  async putModule(filename, content) {
84
138
  const ext = filename.split(".").pop();
85
139
  switch (ext) {
@@ -93,6 +147,12 @@ export class JavaScriptKernelWorker extends KernelWorkerBase {
93
147
  throw { message: "Only '.js' files supported." };
94
148
  }
95
149
  }
150
+ /**
151
+ * Complete the last word with the names of the global scope.
152
+ *
153
+ * @param code - The code before the cursor.
154
+ * @returns `[completions, start]`.
155
+ */
96
156
  async complete(code) {
97
157
  // basic completion based on global object
98
158
  const vars = Object.getOwnPropertyNames(self);
@@ -102,9 +162,11 @@ export class JavaScriptKernelWorker extends KernelWorkerBase {
102
162
  return [matches, code.length - word.length];
103
163
  }
104
164
  /**
105
- * Is the source ready to be evaluated or want we more? It wants more
106
- * when it does not parse because it ends too early (e.g. an unclosed
107
- * block): as Python's codeop.
165
+ * Does the code need more lines? Yes when it doesn't parse because it
166
+ * ends too early (e.g. an unclosed block), as Python's `codeop`.
167
+ *
168
+ * @param code - The lines typed so far.
169
+ * @returns `true` if the code is incomplete.
108
170
  */
109
171
  async more(code) {
110
172
  try {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@basthon/kernel-javascript",
3
- "version": "0.86.0",
3
+ "version": "0.88.0",
4
4
  "description": "Basthon - JavaScript Kernel",
5
5
  "homepage": "https://basthon.fr",
6
6
  "bugs": {
@@ -25,7 +25,7 @@
25
25
  "clean": "rimraf lib/"
26
26
  },
27
27
  "dependencies": {
28
- "@basthon/kernel-base": "0.86.0",
28
+ "@basthon/kernel-base": "0.88.0",
29
29
  "acorn": "^8.19.0",
30
30
  "comlink": "^4.4.2",
31
31
  "object-inspect": "^1.13.4"