WebAssembly/DOM: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		Accessing JS Objects from [[WebAssembly/Compiler\|WebAssembly]].
2	2
3	3		# What is JOB?
4	4
5	5		JS Object Bridge - JOB
6	6
7	7		JOB provides:
8	8
9	9		- Units to communicate between fpc wasm and pas2js browser to call JS functions, get and set JS properties and set callbacks.
10	10		- Units for fpc wasm with common browser classes.
11	11		- A tool webidl2pas to help generating new units for JS classes from webidls.
12	12
13	13		# Using JOB
14	14
15	15		A JOB program has a webassembly program (fpc wasi) and a browser (pas2js) program.
16	16
17	17		The browser side contains the html and registers all global JS variables needed by the webassembly side.
18	18
19	19		See the pas2js demo/wasienv/button/BrowserButton1.lpi
20	20
21	21		<https://gitlab.com/freepascal.org/fpc/pas2js/-/tree/main/demo/wasienv/button>
22	22
23	23		## JS Classes
24	24
25	25		Each JS class like HTMLButtonElement have a FPC class (TJSHTMLButtonElement) with a reference counted interface (IJSHTMLButtonElement).
26	26
27	27		Normally functions return an interface and expect interfaces as arguments.
28	28
29	29		## Callbacks
30	30
31	31		An event handler in WebAssembly can be called from Javascript.
32	32
33	33		At the moment only methods (of object) are supported.
34	34
35	35		``` pascal
36	36		TWasmApp = class
37	37		...
38	38		function OnButtonClick(Event: IJSEvent): boolean;
39	39		...
40	40		end;
41	41
42	42		function TWasmApp.OnButtonClick(Event: IJSEvent): boolean;
43	43		begin
44	44		JSWindow.Alert('You triggered TWasmApp.OnButtonClick');
45	45		Result:=true;
46	46		end;
47	47		...
48	48		JSButton.addEventListener('click',@OnButtonClick);
49	49		...
50	50		```
51	51
52	52		## Type casts
53	53
54	54		Often a low level interface needs to be type casted to a descendant (or another type). For example JSDocument.getElementById returns a IJSElement, which is type casted to IJSHTMLElement:
55	55
56	56		``` pascal
57	57		var
58	58		Elem: IJSElement;
59	59		HTMLElem: IJSHTMLElement;
60	60		begin
61	61		Elem := JSDocument.getElementById('button');
62	62		// type casting to IJSHTMLElement requires creating a new bridge object using TJSHTMLElement.Cast:
63	63		HTMLElem := TJSHTMLElement.Cast(Elem);
64	64		// Note: since Elem and HTMLElem are reference counted interfaces, the compiler automatically frees temporary objects.
65	65		end;
66	66		```
67	67
68	68		This HTMLElement has the same ObjectId as Elem, but it does not own it. It merely keeps a reference to the Elem. When all references are released, the JS object is released,
69	69
70	70		## Typeof
71	71
72	72		InvokeJSTypeOf
73	73
74	74		See the JOBResult_* constants in unit JOB_Shared.
75	75
76	76		## Register a JS object/function
77	77
78	78		By default the TJSObjectBridge registers only some basic JS objects/functions like Object, Function, Date, String, Array, JSON, Promise, ArrayBuffer, Int8Array, Uint8Array, etc.
79	79
80	80		For example if you have the pas2js external class TJSBird for the JS object/function Bird, register it in JOB:
81	81
82	82		``` pascal
83	83		type
84	84		TJSBird = class external name 'Bird'
85	85		...
86	86		end;
87	87		...
88	88		if WADomBridge.RegisterGlobalObject(TJSBird,'Bird')=0 then
89	89		raise Exception.Create('failed to register TJSBird');
90	90		```
91	91
92	92		In the fpc/webassembly code create an interface:
93	93
94	94		``` pascal
95	95		type
96	96		IJSBird = interface
97	97		[{guid}]
98	98		end;
99	99
100	100		TJSBird = class(TJSObject,IJSBird)
101	101		...
102	102		end;
103	103
104	104		var JSBird: IJSBird; // this is the JS variable 'Bird'
105	105
106	106		JSBird := TJSBird.JOBCreateGlobal('Bird') as IJSBird;
107	107		```
108	108
109	109		If the above Bird is a JS function you can create a new descendant with parameter 123 (in Javascript: new Bird(123); ) by calling:
110	110
111	111		``` pascal
112	112		var MyBird: IJSBird;
113	113
114	114		MyBird := JSBird.NewJSObject([123]) as IJSBird; // in JS: new Bird(123)
115	115		```
116	116
117	117		For a full example see demo/wasienv/dom/WasiDomTest1.lpi and BrowserDomTest1.lpi
118	118
119	119		# Create JOB units using webidl2pas
120	120
121	121		Compile the latest and greatest webidl2pas utility from fpc main:
122	122
123	123		utils/pas2js/webidl2pas.lpi
124	124
125	125		Download some webidls for example from <https://hg.mozilla.org/mozilla-central/raw-file/tip/dom/webidl/>\<JSClassName\>
126	126
127	127		Concatenate them into one file Foo.webidl.
128	128
129	129		Create a text file FooAlias.txt containing the used classes from other units:
130	130
131	131		Object=IJSObject
132	132		Set=IJSSet
133	133		Map=IJSMap
134	134		Function=IJSFunction
135	135		Date=IJSDate
136	136		RegExp=IJSRegExp
137	137		String=IJSString
138	138		Array=IJSArray
139	139		ArrayBuffer=IJSArrayBuffer
140	140		TypedArray=IJSTypedArray
141	141		BufferSource=IJSBufferSource
142	142		DataView=IJSDataView
143	143		JSON=IJSJSON
144	144		Error=IJSError
145	145		TextEncoder=IJSTextEncode
146	146		TextDecoder=IJSTextDecoder
147	147
148	148		Create a text file FooGlobals.txt containing all the global JS variables in form Pascal variable name=JS class name,registered name:
149	149
150	150		JSFoo=Foo,foo
151	151
152	152		Run the tool:
153	153
154		-	~~`webidl2pas -f wasmjob -i Foo.webidl --typealiases=@FooAlias.txt --globals=@FooGlobals.txt`~~
	154	+	```text
	155	+	webidl2pas -f wasmjob -i Foo.webidl --typealiases=@FooAlias.txt --globals=@FooGlobals.txt
	156	+	```
155	157
156	158		If the tool stops, because it can not find an identifier or something is not yet supported, you can add another webidl or comment the problematic definition. Then run the tool again.
157	159
158	160		In the browser side you must register the global JS variables:
159	161
160	162		``` pascal
161	163		FWADomBridge.RegisterGlobalObject(foo,'foo');
162	164		```
163	165
164	166		## Not yet supported webidl elements
165	167
166	168		### Elements from other Pascal units
167	169
168	170		At the moment you can only provide a list of type aliases for classes. This does not work for callbacks, arrays, sequences, etc. It would be better to give used units and parse them.
169	171
170	172		### callback interfaces
171	173
172	174		"callback interfaces" are a legacy definition. Remedy: Replace them manually with a callback
173	175
174	176		### function returning a Dictionary
175	177
176	178		ToDo: Define dictionary as class and interface and return an interface reference.
177	179
178	180		### function returning a typed sequence
179	181
180	182		At the moment it returns an untyped IJSArray.
181	183
182	184		ToDo: returned a typed array.
183	185
184	186		### function returning a callback
185	187
186	188		### passing an array as argument
187	189
188	190		### varargs
189	191
190	192		Functions allowing to pass an arbitrary number of arguments.
191	193
192	194		Workaround: User can call the InvokeX function directly.
193	195
194	196		### constructor
195	197
196	198		### getter
197	199
198	200		### callback property
199	201
200	202		A property with a callback, e.g. onAbort
201	203
202	204		At the moment it is only added as a comment. Reading callbacks is not yet supported. Theoretically it could be added as a write only property.
203	205
204	206		# JOB architecture
205	207
206	208		Pascal units containing ‘proxy’ classes: calling a method on a proxy class will call the corresponding class in JS. The proxy classes can be generated by the existing webidl2pas tool with -f wasmjob flag.
207	209
208	210		## Data transfer between JS/WebAssembly
209	211
210	212		JS/Webassembly interface only supports passing atomic types like boolean, integers and floats, not objects or strings.
211	213
212	214		Solution:
213	215
214	216		- Global objects like document and window are registered and queried by name.
215	217		- Every object is stored in an array with ID: TJOBObjectID
216	218		- ID is used to pass references to object between JS and Webassembly
217	219		- Lifetime is controlled from WebAssembly.
218	220		- By using interfaces, the lifetime of objects are controlled by the compiler.
219	221		- Methods can be called using an invoke mechanism.
220	222		- Due to limited type support in Javascript, only a handful of types must be supported by invoke, e.g. undefined, null, boolean, number, unicodestring, Object, callbacks and the union JSValue.
221	223
222	224		## Function Arguments
223	225
224	226		When calling a JS function from wasm, you can pass the following types/constants:
225	227
226	228		- boolean
227	229		- integers (limited to double, because all numbers in JS are double, so up to 54 bits)
228	230		- double
229	231		- nil or Variants.Null
230	232		- string (utf8 converted to utf16, either use UTF8Encode/UTF8Decode or install a widestringmanager by using the units unicodeducet, unicodedata, fpwidestring)
231	233		- unicodestring
232	234		- widestring
233	235		- PChar - using strlen to get the size and utf8 converted to utf16
234	236		- PWideChar - using strlen to get the size
235	237		- TJSObject and IJSObject - its ObjectID is passed to the JS side, where the corresponding JS object is used
236	238		- Variant
237	239		- Variants.UnAssigned or JSUndefined
238	240		- TJOB_JSValue - at the moment needed for TJOB_Method.
239	241
240	242		## Function Result
241	243
242	244		Calling a JS function is done via the InvokeJSResult* functions, e.g. aJSDate.InvokeJSUnicodeStringResult('toLocaleDateString',\[\]) which returns a UnicodeString.
243	245
244	246		If the function does not exist, an EJSInvoke exception is raised.
245	247
246	248		If the function returns the JS undefined value, JOB returns the default value, e.g. InvokeJSUnicodeStringResult returns the empty string, InvokeJSDoubleResult returns NaN, InvokeJSObjectResult returns nil, InvokeJSBooleanResult returns false.
247	249
248	250		If the function returns an incompatible type, e.g. InvokeJSUnicodeStringResult returns a number, an EJSInvoke exception is raised.
249	251
250	252		To retrieve any kind of JS value, use InvokeJSVariantResult.
251	253
252	254		## Variants
253	255
254	256		When an argument or result type does not have a simple type, webidl2pas uses Variant. Variants have a few newbie traps:
255	257
256	258		For JS undefined you can use Variants.Unassigned and VarIsEmpty(v).
257	259
258	260		For JS null you cannot use nil, you can use Variants.Null or VarIsNull(v). nil cannot be used, because fpc treats nil with variants like an empty Unicodestring. E.g. "if aVariant=nil then" is wrong, use "if aVariant=Variants.Null then" instead.
259	261
260	262		Variants do not support 8bit strings, only 16bit Unicodestrings. For example: ansistring:=aVariant works only for ascii strings, but for unicodestrings you must either use UTF8Encode or a proper widestringmanager.
261	263
262	264		Interfaces: When a function returns a Variant containing an object, the variant will contain a IJSObject or Variants.Null. Note that SomeIntf:=aVariant will compile, but does no type check, so SomeIntf might only be a IJSObject instead of IJSSomeIntf. If you know that aVariant has a IJSSomeIntf you can use a type cast: SomeIntf:=TJSSomeIntf.Cast(aVariant);. There is no general way in JS to check what "class" a JS object is.
263	265
264	266		## Callbacks
265	267
266	268		An event handler in WebAssembly can be called from Javascript.
267	269
268	270		At the moment only methods (of object) are supported.
269	271
270	272		Every function type needs a callback, which decodes the arguments and encode the result.
271	273
272	274		For example TJSEventHandler:
273	275
274	276		``` pascal
275	277		type
276	278		TJSEventHandler = function(Event: IJSEventListenerEvent): boolean of object;
277	279		...
278	280		function JOBCallTJSEventHandler(const aMethod: TMethod; var H: TJOBCallbackHelper): PByte;
279	281		var
280	282		Event: IJSEventListenerEvent;
281	283		begin
282	284		// get arguments. First as IJSEventListenerEvent
283	285		Event:=H.GetObject(TJSEventListenerEvent) as IJSEventListenerEvent;
284	286		// call the method and encode the result
285	287		Result:=H.AllocBool(TJSEventHandler(aMethod)(Event));
286	288		end;
287	289		```
288	290
289	291		TJOBCallbackHelper provides functions to decode arguments and encode the result.
290	292
291	293		Passing a method as argument works like this:
292	294
293	295		``` pascal
294	296		type
295	297		IJSEventTarget = interface
296	298		['{1883145B-C826-47D1-9C63-47546BA536BD}']
297	299		procedure addEventListener(const aName: UnicodeString; const aListener: TJSEventHandler);
298	300		end;
299	301
300	302		TJSEventTarget = class(TJSObject,IJSEventTarget)
301	303		procedure addEventListener(const aName: UnicodeString; const aListener: TJSEventHandler);
302	304		end;
303	305		...
304	306		procedure TJSEventTarget.addEventListener(const aName: UnicodeString; const aListener: TJSEventHandler);
305	307		var
306	308		m: TJOB_JSValueMethod;
307	309		begin
308	310		// combine the users method and the callback into one argument m
309	311		m:=TJOB_JSValueMethod.Create(TMethod(aListener),@JOBCallTJSEventHandler);
310	312		try
311	313		// call the JS function addEventListener(aName,m)
312	314		InvokeJSNoResult('addEventListener',[aName,m]);
313	315		finally
314	316		m.Free;
315	317		end;
316	318		end;
317	319		```
318	320
319	321		See units job_js and job_web for more examples.
320	322
321	323		# Implementation details
322	324
323	325		Here are some technical notes describing the various architectural decisions.
324	326
325	327		The webidl2pas tool was extended to generate an interface from the .webidl files (-f wasmjob). These files for example exist in the mozilla firefox repo on github: [WebIDL](https://github.com/mozilla/gecko-dev/tree/master/dom/webidl)
326	328
327	329		``` pascal
328	330		IJSElement = interface(IJSObject)
329	331		['someawfulGUID']
330	332		function childElementCount : Integer;
331	333		function firstElementChild : IJSElement;
332	334		// all other
333	335		end;
334	336		```
335	337
336	338		In implementation, the following kind of code can be found:
337	339
338	340		``` pascal
339	341		// Hand crafted in e.g. JSObject unit
340	342		TJSObject = class(TInterfacedObject,IJSObject)
341	343		public
342	344		constructor JOBCast(Intf: IJSObject); overload;
343	345		constructor JOBCreateFromID(aID: TJOBObjectID); virtual; // use this only for the owner (it will release it on free)
344	346		constructor JOBCreateGlobal(const aID: UnicodeString); virtual;
345	347		class function Cast(Intf: IJSObject): IJSObject; overload;
346	348		destructor Destroy; override;
347	349		property JOBObjectID: TJOBObjectID read FJOBObjectID;
348	350		property JOBObjectIDOwner: boolean read FJOBObjectIDOwner write FJOBObjectIDOwner;
349	351		property JOBCastSrc: IJSObject read FJOBCastSrc; // nil means it is the original, otherwise it is a typecast
350	352		property ObjectID: TJOBObjectID read FObjectID;
351	353		// call a function
352	354		procedure InvokeJSNoResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeType = jiCall); virtual;
353	355		function InvokeJSBooleanResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeType = jiCall): Boolean; virtual;
354	356		function InvokeJSDoubleResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeType = jiCall): Double; virtual;
355	357		function InvokeJSUnicodeStringResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeType = jiCall): UnicodeString; virtual;
356	358		function InvokeJSObjectResult(const aName: string; Const Args: Array of const; aResultClass: TJSObjectClass; Invoke: TJOBInvokeType = jiCall): TJSObject; virtual;
357	359		function InvokeJSVariantResult(const aName: string; Const Args: Array of const; Invoke: TJOBInvokeType = jiCall): Variant; virtual;
358	360		function InvokeJSUtf8StringResult(const aName: string; Const args: Array of const; Invoke: TJOBInvokeType = jiCall): String; virtual;
359	361		function InvokeJSLongIntResult(const aName: string; Const args: Array of const; Invoke: TJOBInvokeType = jiCall): LongInt; virtual;
360	362		function InvokeJSMaxIntResult(const aName: string; Const args: Array of const; Invoke: TJOBInvokeType = jiCall): int64; virtual;
361	363		function InvokeJSTypeOf(const aName: string; Const Args: Array of const): TJOBResult; virtual;
362	364		// read a property
363	365		function ReadJSPropertyBoolean(const aName: string): boolean; virtual;
364	366		function ReadJSPropertyDouble(const aName: string): double; virtual;
365	367		function ReadJSPropertyUnicodeString(const aName: string): UnicodeString; virtual;
366	368		function ReadJSPropertyObject(const aName: string; aResultClass: TJSObjectClass): TJSObject; virtual;
367	369		function ReadJSPropertyUtf8String(const aName: string): string; virtual;
368	370		function ReadJSPropertyLongInt(const aName: string): LongInt; virtual;
369	371		function ReadJSPropertyInt64(const aName: string): Int64; virtual;
370	372		function ReadJSPropertyVariant(const aName: string): Variant; virtual;
371	373		// write a property
372	374		procedure WriteJSPropertyBoolean(const aName: string; Value: Boolean); virtual;
373	375		procedure WriteJSPropertyDouble(const aName: string; Value: Double); virtual;
374	376		procedure WriteJSPropertyUnicodeString(const aName: string; const Value: UnicodeString); virtual;
375	377		procedure WriteJSPropertyUtf8String(const aName: string; const Value: String); virtual;
376	378		procedure WriteJSPropertyObject(const aName: string; Value: IJSObject); virtual;
377	379		procedure WriteJSPropertyLongInt(const aName: string; Value: LongInt); virtual;
378	380		procedure WriteJSPropertyInt64(const aName: string; Value: Int64); virtual;
379	381		procedure WriteJSPropertyVariant(const aName: string; const Value: Variant); virtual;
380	382		// create a new object using the new-operator
381	383		function NewJSObject(Const Args: Array of const; aResultClass: TJSObjectClass): TJSObject; virtual;
382	384		end;
383	385		```
384	386
385	387		The various Invoke* functions encode the arguments in a memory block so they can be read on the JS side, then calls a *Invoke_Result** function which lives in Javascript, and which is imported from the browser.
386	388
387	389		That function does the actual call: it uses ObjectID to look for the Self object in an array:
388	390
389	391		- Negative IDs are special: window, document.
390	392		- positive IDs are temporary objects created via the InvokeJSObjectResult, see below.
391	393
392	394		The *Invoke_Result pas2js function decodes the arguments and uses TJSFunction.apply** to execute the requested function. The result is checked for the requested type and then returned to the wasm.
393	395
394	396		If the result is an object, an ID is generated (simple counter), the result value is stored in an array FLocalObjects.
395	397
396	398		The ID is returned to the webassembly, which will use the ID to create a TJSObject descendent.
397	399
398	400		The destructor of TJSObject calls a __job_release_object function in javascript if the ObjectID is positive. The ReleaseObject function simply sets FLocalObjects\[id\] to null, so the browser also releases it.
399	401
400	402		The above is a basic invoke mechanism for Javascript code.
401	403
402	404		This basic mechanism is then used by a modified version of the webidl program to generate proxy definitions. For each object in Javascript, 2 definitions are generated:
403	405
404	406		- The interface (see above for an example)
405	407		- An implementation object as below, descendant of TJSObject
406	408
407	409		``` pascal
408	410		// Generated from webIDL in jsweb/jsdom unit.
409	411
410	412		IJSElement = interface(IJSNode)
411	413		function childElementCount : Integer;
412	414		function firstElementChild : IJSElement;
413	415		end;
414	416
415	417		TJSElementImpl = class(TJSObject,IJSElement)
416	418		function childElementCount : Integer;
417	419		function firstElementChild : IJSElement;
418	420		// all other
419	421		end;
420	422
421	423		function TJSElementImpl.childElementCount : Integer;
422	424		begin
423	425		Result:=ReadJSPropertyLongInt('childElementCount');
424	426		end;
425	427
426	428		function TJSElementImpl.firstElementChild : IJSElement;
427	429		begin
428	430		Result:=ReadJSPropertyObject('firstElementChild',TJSElementImpl) as IJSElement;
429	431		end;
430	432		```
431	433
432	434		# ToDos
433	435
434	436		- read/write array elements
435	437		- store/cache callbacks to support removeEventListener
436	438		- move job_web+job_js units to fpc
437	439		- webidl2pas:
438	440		- stringifier
439	441		- check Getter+Setter name conflicts
440	442		- argument of sequence\<something\>
441	443		- overloaded version for dictionary args
442	444		- varargs
443	445		- js getter
444	446		- js constructor
445	447		- pas2jsdsgn: new wasmjob browser project
446	448
447	449		---
448	450		From the Free Pascal wiki, page "WebAssembly/DOM", as it stood on 2024-04-12 after a change by Mattias2, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
449	451		Category: WebAssembly

Back to history