1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
* vim: set ts=8 sts=2 et sw=2 tw=80:
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
/* JavaScript module (as in, the syntactic construct) operations. */
#ifndef js_Modules_h
#define js_Modules_h
#include "mozilla/Utf8.h" // mozilla::Utf8Unit
#include <stdint.h> // uint32_t
#include "jstypes.h" // JS_PUBLIC_API
#include "js/CompileOptions.h" // JS::ReadOnlyCompileOptions
#include "js/RootingAPI.h" // JS::{Mutable,}Handle
#include "js/Value.h" // JS::Value
struct JS_PUBLIC_API JSContext;
class JS_PUBLIC_API JSObject;
struct JS_PUBLIC_API JSRuntime;
class JS_PUBLIC_API JSString;
namespace JS {
template <typename UnitT>
class SourceText;
} // namespace JS
namespace JS {
using ModuleResolveHook = JSObject* (*)(JSContext*, Handle<Value>,
Handle<JSString*>);
/**
* Get the HostResolveImportedModule hook for the runtime.
*/
extern JS_PUBLIC_API ModuleResolveHook GetModuleResolveHook(JSRuntime* rt);
/**
* Set the HostResolveImportedModule hook for the runtime to the given function.
*/
extern JS_PUBLIC_API void SetModuleResolveHook(JSRuntime* rt,
ModuleResolveHook func);
using ModuleMetadataHook = bool (*)(JSContext*, Handle<Value>,
Handle<JSObject*>);
/**
* Get the hook for populating the import.meta metadata object.
*/
extern JS_PUBLIC_API ModuleMetadataHook GetModuleMetadataHook(JSRuntime* rt);
/**
* Set the hook for populating the import.meta metadata object to the given
* function.
*/
extern JS_PUBLIC_API void SetModuleMetadataHook(JSRuntime* rt,
ModuleMetadataHook func);
using ModuleDynamicImportHook = bool (*)(JSContext* cx,
Handle<Value> referencingPrivate,
Handle<JSString*> specifier,
Handle<JSObject*> promise);
/**
* Get the HostImportModuleDynamically hook for the runtime.
*/
extern JS_PUBLIC_API ModuleDynamicImportHook
GetModuleDynamicImportHook(JSRuntime* rt);
/**
* Set the HostImportModuleDynamically hook for the runtime to the given
* function.
*
* If this hook is not set (or set to nullptr) then the JS engine will throw an
* exception if dynamic module import is attempted.
*/
extern JS_PUBLIC_API void SetModuleDynamicImportHook(
JSRuntime* rt, ModuleDynamicImportHook func);
/**
* Passed to FinishDynamicModuleImport to indicate the result of the dynamic
* import operation.
*/
enum class DynamicImportStatus { Failed = 0, Ok };
/**
* This must be called after a dynamic import operation is complete.
*
* If |evaluationPromise| is rejected, the rejection reason will be used to
* complete the user's promise.
*/
extern JS_PUBLIC_API bool FinishDynamicModuleImport(
JSContext* cx, Handle<JSObject*> evaluationPromise,
Handle<Value> referencingPrivate, Handle<JSString*> specifier,
Handle<JSObject*> promise);
/**
* This must be called after a dynamic import operation is complete.
*
* This is used so that Top Level Await functionality can be turned off
* entirely. It will be removed in bug#1676612.
*
* If |status| is Failed, any pending exception on the context will be used to
* complete the user's promise.
*/
extern JS_PUBLIC_API bool FinishDynamicModuleImport_NoTLA(
JSContext* cx, DynamicImportStatus status, Handle<Value> referencingPrivate,
Handle<JSString*> specifier, Handle<JSObject*> promise);
/**
* Parse the given source buffer as a module in the scope of the current global
* of cx and return a source text module record.
*/
extern JS_PUBLIC_API JSObject* CompileModule(
JSContext* cx, const ReadOnlyCompileOptions& options,
SourceText<char16_t>& srcBuf);
/**
* Parse the given source buffer as a module in the scope of the current global
* of cx and return a source text module record. An error is reported if a
* UTF-8 encoding error is encountered.
*/
extern JS_PUBLIC_API JSObject* CompileModule(
JSContext* cx, const ReadOnlyCompileOptions& options,
SourceText<mozilla::Utf8Unit>& srcBuf);
/**
* Set a private value associated with a source text module record.
*/
extern JS_PUBLIC_API void SetModulePrivate(JSObject* module,
const Value& value);
/**
* Get the private value associated with a source text module record.
*/
extern JS_PUBLIC_API Value GetModulePrivate(JSObject* module);
/*
* Perform the ModuleInstantiate operation on the given source text module
* record.
*
* This transitively resolves all module dependencies (calling the
* HostResolveImportedModule hook) and initializes the environment record for
* the module.
*/
extern JS_PUBLIC_API bool ModuleInstantiate(JSContext* cx,
Handle<JSObject*> moduleRecord);
/*
* Perform the ModuleEvaluate operation on the given source text module record
* and returns a bool. A result value is returned in result and is either
* undefined (and ignored) or a promise (if Top Level Await is enabled).
*
* If this module has already been evaluated, it returns the evaluation
* promise. Otherwise, it transitively evaluates all dependences of this module
* and then evaluates this module.
*
* ModuleInstantiate must have completed prior to calling this.
*/
extern JS_PUBLIC_API bool ModuleEvaluate(JSContext* cx,
Handle<JSObject*> moduleRecord,
MutableHandleValue rval);
/*
* If a module evaluation fails, unwrap the resulting evaluation promise
* and rethrow.
*
* This does nothing if this module succeeds in evaluation. Otherwise, it
* takes the reason for the module throwing, unwraps it and throws it as a
* regular error rather than as an uncaught promise.
*
* ModuleEvaluate must have completed prior to calling this.
*/
extern JS_PUBLIC_API bool ThrowOnModuleEvaluationFailure(
JSContext* cx, Handle<JSObject*> evaluationPromise);
/*
* Get a list of the module specifiers used by a source text module
* record to request importation of modules.
*
* The result is a JavaScript array of object values. To extract the individual
* values use only JS::GetArrayLength and JS_GetElement with indices 0 to length
* - 1.
*
* The element values are objects with the following properties:
* - moduleSpecifier: the module specifier string
* - lineNumber: the line number of the import in the source text
* - columnNumber: the column number of the import in the source text
*
* These property values can be extracted with GetRequestedModuleSpecifier() and
* GetRequestedModuleSourcePos()
*/
extern JS_PUBLIC_API JSObject* GetRequestedModules(
JSContext* cx, Handle<JSObject*> moduleRecord);
extern JS_PUBLIC_API JSString* GetRequestedModuleSpecifier(
JSContext* cx, Handle<Value> requestedModuleObject);
extern JS_PUBLIC_API void GetRequestedModuleSourcePos(
JSContext* cx, Handle<Value> requestedModuleObject, uint32_t* lineNumber,
uint32_t* columnNumber);
/*
* Get the top-level script for a module which has not yet been executed.
*/
extern JS_PUBLIC_API JSScript* GetModuleScript(Handle<JSObject*> moduleRecord);
} // namespace JS
#endif // js_Modules_h
|
