js/public/Modules.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: set ts=8 sts=2 et sw=2 tw=80:
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /* JavaScript module (as in, the syntactic construct) operations. */
   8
   9 #ifndef js_Modules_h
  10 #define js_Modules_h
  11
  12 #include <stdint.h>  // uint32_t
  13
  14 #include "jstypes.h"  // JS_PUBLIC_API
  15
  16 #include "js/AllocPolicy.h"     // js::SystemAllocPolicy
  17 #include "js/ColumnNumber.h"    // JS::ColumnNumberOneOrigin
  18 #include "js/CompileOptions.h"  // JS::ReadOnlyCompileOptions
  19 #include "js/RootingAPI.h"      // JS::{Mutable,}Handle
  20 #include "js/Value.h"           // JS::Value
  21 #include "js/Vector.h"          // js::Vector
  22
  23 struct JS_PUBLIC_API JSContext;
  24 class JS_PUBLIC_API JSObject;
  25 struct JS_PUBLIC_API JSRuntime;
  26 class JS_PUBLIC_API JSString;
  27
  28 namespace JS {
  29 template <typename UnitT>
  30 class SourceText;
  31 }  // namespace JS
  32
  33 namespace mozilla {
  34 union Utf8Unit;
  35 }
  36
  37 namespace JS {
  38
  39 /**
  40  * The HostResolveImportedModule hook.
  41  *
  42  * See: https://tc39.es/ecma262/#sec-hostresolveimportedmodule
  43  *
  44  * This embedding-defined hook is used to implement module loading. It is called
  45  * to get or create a module object corresponding to |moduleRequest| occurring
  46  * in the context of the script or module with private value
  47  * |referencingPrivate|.
  48  *
  49  * The module specifier string for the request can be obtained by calling
  50  * JS::GetModuleRequestSpecifier.
  51  *
  52  * The private value for a script or module is set with JS::SetScriptPrivate or
  53  * JS::SetModulePrivate. It's assumed that the embedding can handle receiving
  54  * either here.
  55  *
  56  * This hook must obey the restrictions defined in the spec:
  57  *  - Each time the hook is called with the same arguemnts, the same module must
  58  *    be returned.
  59  *  - If a module cannot be created for the given arguments, an exception must
  60  *    be thrown.
  61  *
  62  * This is a synchronous operation.
  63  */
  64 using ModuleResolveHook = JSObject* (*)(JSContext* cx,
  65                                         Handle<Value> referencingPrivate,
  66                                         Handle<JSObject*> moduleRequest);
  67
  68 /**
  69  * Get the HostResolveImportedModule hook for the runtime.
  70  */
  71 extern JS_PUBLIC_API ModuleResolveHook GetModuleResolveHook(JSRuntime* rt);
  72
  73 /**
  74  * Set the HostResolveImportedModule hook for the runtime to the given function.
  75  */
  76 extern JS_PUBLIC_API void SetModuleResolveHook(JSRuntime* rt,
  77                                                ModuleResolveHook func);
  78
  79 /**
  80  * The module metadata hook.
  81  *
  82  * See: https://tc39.es/ecma262/#sec-hostgetimportmetaproperties
  83  *
  84  * Populate the |metaObject| object returned when import.meta is evaluated in
  85  * the context of the script or module with private value |privateValue|.
  86  *
  87  * This is based on the spec's HostGetImportMetaProperties hook but defines
  88  * properties on the meta object directly rather than returning a list.
  89  */
  90 using ModuleMetadataHook = bool (*)(JSContext* cx, Handle<Value> privateValue,
  91                                     Handle<JSObject*> metaObject);
  92
  93 /**
  94  * Get the hook for populating the import.meta metadata object.
  95  */
  96 extern JS_PUBLIC_API ModuleMetadataHook GetModuleMetadataHook(JSRuntime* rt);
  97
  98 /**
  99  * Set the hook for populating the import.meta metadata object to the given
 100  * function.
 101  */
 102 extern JS_PUBLIC_API void SetModuleMetadataHook(JSRuntime* rt,
 103                                                 ModuleMetadataHook func);
 104
 105 /**
 106  * The HostImportModuleDynamically hook.
 107  *
 108  * See https://tc39.es/ecma262/#sec-hostimportmoduledynamically
 109  *
 110  * Used to implement dynamic module import. Called when evaluating import()
 111  * expressions.
 112  *
 113  * This starts an asynchronous operation. Some time after this hook is called
 114  * the embedding must call JS::FinishDynamicModuleImport() passing the
 115  * |referencingPrivate|, |moduleRequest| and |promise| arguments from the
 116  * call. This must happen for both success and failure cases.
 117  *
 118  * In the meantime the embedding can take whatever steps it needs to make the
 119  * module available. If successful, after calling FinishDynamicModuleImport()
 120  * the module should be returned by the resolve hook when passed
 121  * |referencingPrivate| and |moduleRequest|.
 122  */
 123 using ModuleDynamicImportHook = bool (*)(JSContext* cx,
 124                                          Handle<Value> referencingPrivate,
 125                                          Handle<JSObject*> moduleRequest,
 126                                          Handle<JSObject*> promise);
 127
 128 /**
 129  * Get the HostImportModuleDynamically hook for the runtime.
 130  */
 131 extern JS_PUBLIC_API ModuleDynamicImportHook
 132 GetModuleDynamicImportHook(JSRuntime* rt);
 133
 134 /**
 135  * Set the HostImportModuleDynamically hook for the runtime to the given
 136  * function.
 137  *
 138  * If this hook is not set (or set to nullptr) then the JS engine will throw an
 139  * exception if dynamic module import is attempted.
 140  */
 141 extern JS_PUBLIC_API void SetModuleDynamicImportHook(
 142     JSRuntime* rt, ModuleDynamicImportHook func);
 143
 144 /**
 145  * This must be called after a dynamic import operation is complete.
 146  *
 147  * If |evaluationPromise| is rejected, the rejection reason will be used to
 148  * complete the user's promise.
 149  */
 150 extern JS_PUBLIC_API bool FinishDynamicModuleImport(
 151     JSContext* cx, Handle<JSObject*> evaluationPromise,
 152     Handle<Value> referencingPrivate, Handle<JSObject*> moduleRequest,
 153     Handle<JSObject*> promise);
 154
 155 /**
 156  * Parse the given source buffer as a module in the scope of the current global
 157  * of cx and return a source text module record.
 158  */
 159 extern JS_PUBLIC_API JSObject* CompileModule(
 160     JSContext* cx, const ReadOnlyCompileOptions& options,
 161     SourceText<char16_t>& srcBuf);
 162
 163 /**
 164  * Parse the given source buffer as a module in the scope of the current global
 165  * of cx and return a source text module record.  An error is reported if a
 166  * UTF-8 encoding error is encountered.
 167  */
 168 extern JS_PUBLIC_API JSObject* CompileModule(
 169     JSContext* cx, const ReadOnlyCompileOptions& options,
 170     SourceText<mozilla::Utf8Unit>& srcBuf);
 171
 172 /**
 173  * Set a private value associated with a source text module record.
 174  */
 175 extern JS_PUBLIC_API void SetModulePrivate(JSObject* module,
 176                                            const Value& value);
 177 /**
 178  * Clear the private value associated with a source text module record.
 179  *
 180  * This is used during unlinking and can be called on a gray module, skipping
 181  * the usual checks.
 182  */
 183 extern JS_PUBLIC_API void ClearModulePrivate(JSObject* module);
 184
 185 /**
 186  * Get the private value associated with a source text module record.
 187  */
 188 extern JS_PUBLIC_API Value GetModulePrivate(JSObject* module);
 189
 190 /*
 191  * Perform the ModuleLink operation on the given source text module record.
 192  *
 193  * This transitively resolves all module dependencies (calling the
 194  * HostResolveImportedModule hook) and initializes the environment record for
 195  * the module.
 196  */
 197 extern JS_PUBLIC_API bool ModuleLink(JSContext* cx,
 198                                      Handle<JSObject*> moduleRecord);
 199
 200 /*
 201  * Perform the ModuleEvaluate operation on the given source text module record
 202  * and returns a bool. A result value is returned in result and is either
 203  * undefined (and ignored) or a promise (if Top Level Await is enabled).
 204  *
 205  * If this module has already been evaluated, it returns the evaluation
 206  * promise. Otherwise, it transitively evaluates all dependences of this module
 207  * and then evaluates this module.
 208  *
 209  * ModuleLink must have completed prior to calling this.
 210  */
 211 extern JS_PUBLIC_API bool ModuleEvaluate(JSContext* cx,
 212                                          Handle<JSObject*> moduleRecord,
 213                                          MutableHandleValue rval);
 214
 215 enum ModuleErrorBehaviour {
 216   // Report module evaluation errors asynchronously when the evaluation promise
 217   // is rejected. This is used for web content.
 218   ReportModuleErrorsAsync,
 219
 220   // Throw module evaluation errors synchronously by setting an exception on the
 221   // context. Does not support modules that use top-level await.
 222   ThrowModuleErrorsSync
 223 };
 224
 225 /*
 226  * If a module evaluation fails, unwrap the resulting evaluation promise
 227  * and rethrow.
 228  *
 229  * This does nothing if this module succeeds in evaluation. Otherwise, it
 230  * takes the reason for the module throwing, unwraps it and throws it as a
 231  * regular error rather than as an uncaught promise.
 232  *
 233  * ModuleEvaluate must have completed prior to calling this.
 234  */
 235 extern JS_PUBLIC_API bool ThrowOnModuleEvaluationFailure(
 236     JSContext* cx, Handle<JSObject*> evaluationPromise,
 237     ModuleErrorBehaviour errorBehaviour = ReportModuleErrorsAsync);
 238
 239 /*
 240  * Functions to access the module specifiers of a source text module record used
 241  * to request module imports.
 242  *
 243  * Clients can use GetRequestedModulesCount() to get the number of specifiers
 244  * and GetRequestedModuleSpecifier() / GetRequestedModuleSourcePos() to get the
 245  * individual elements.
 246  */
 247 extern JS_PUBLIC_API uint32_t
 248 GetRequestedModulesCount(JSContext* cx, Handle<JSObject*> moduleRecord);
 249
 250 extern JS_PUBLIC_API JSString* GetRequestedModuleSpecifier(
 251     JSContext* cx, Handle<JSObject*> moduleRecord, uint32_t index);
 252
 253 /*
 254  * Get the position of a requested module's name in the source.
 255  */
 256 extern JS_PUBLIC_API void GetRequestedModuleSourcePos(
 257     JSContext* cx, Handle<JSObject*> moduleRecord, uint32_t index,
 258     uint32_t* lineNumber, JS::ColumnNumberOneOrigin* columnNumber);
 259
 260 /*
 261  * Get the top-level script for a module which has not yet been executed.
 262  */
 263 extern JS_PUBLIC_API JSScript* GetModuleScript(Handle<JSObject*> moduleRecord);
 264
 265 extern JS_PUBLIC_API JSObject* CreateModuleRequest(
 266     JSContext* cx, Handle<JSString*> specifierArg);
 267 extern JS_PUBLIC_API JSString* GetModuleRequestSpecifier(
 268     JSContext* cx, Handle<JSObject*> moduleRequestArg);
 269
 270 /*
 271  * Get the module record for a module script.
 272  */
 273 extern JS_PUBLIC_API JSObject* GetModuleObject(Handle<JSScript*> moduleScript);
 274
 275 /*
 276  * Get the namespace object for a module.
 277  */
 278 extern JS_PUBLIC_API JSObject* GetModuleNamespace(
 279     JSContext* cx, Handle<JSObject*> moduleRecord);
 280
 281 extern JS_PUBLIC_API JSObject* GetModuleForNamespace(
 282     JSContext* cx, Handle<JSObject*> moduleNamespace);
 283
 284 extern JS_PUBLIC_API JSObject* GetModuleEnvironment(
 285     JSContext* cx, Handle<JSObject*> moduleObj);
 286
 287 /*
 288  * Clear all bindings in a module's environment. Used during shutdown.
 289  */
 290 extern JS_PUBLIC_API void ClearModuleEnvironment(JSObject* moduleObj);
 291
 292 }  // namespace JS
 293
 294 #endif  // js_Modules_h