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 "mozilla/Utf8.h"  // mozilla::Utf8Unit
  13
  14 #include <stdint.h>  // uint32_t
  15
  16 #include "jstypes.h"  // JS_PUBLIC_API
  17
  18 #include "js/CompileOptions.h"  // JS::ReadOnlyCompileOptions
  19 #include "js/RootingAPI.h"      // JS::{Mutable,}Handle
  20 #include "js/Value.h"           // JS::Value
  21
  22 struct JSContext;
  23 class JSObject;
  24 struct JSRuntime;
  25 class JSString;
  26
  27 namespace JS {
  28 template <typename UnitT>
  29 class SourceText;
  30 }  // namespace JS
  31
  32 namespace JS {
  33
  34 using ModuleResolveHook = JSObject* (*)(JSContext*, Handle<Value>,
  35                                         Handle<JSString*>);
  36
  37 /**
  38  * Get the HostResolveImportedModule hook for the runtime.
  39  */
  40 extern JS_PUBLIC_API ModuleResolveHook GetModuleResolveHook(JSRuntime* rt);
  41
  42 /**
  43  * Set the HostResolveImportedModule hook for the runtime to the given function.
  44  */
  45 extern JS_PUBLIC_API void SetModuleResolveHook(JSRuntime* rt,
  46                                                ModuleResolveHook func);
  47
  48 using ModuleMetadataHook = bool (*)(JSContext*, Handle<Value>,
  49                                     Handle<JSObject*>);
  50
  51 /**
  52  * Get the hook for populating the import.meta metadata object.
  53  */
  54 extern JS_PUBLIC_API ModuleMetadataHook GetModuleMetadataHook(JSRuntime* rt);
  55
  56 /**
  57  * Set the hook for populating the import.meta metadata object to the given
  58  * function.
  59  */
  60 extern JS_PUBLIC_API void SetModuleMetadataHook(JSRuntime* rt,
  61                                                 ModuleMetadataHook func);
  62
  63 using ModuleDynamicImportHook = bool (*)(JSContext* cx,
  64                                          Handle<Value> referencingPrivate,
  65                                          Handle<JSString*> specifier,
  66                                          Handle<JSObject*> promise);
  67
  68 /**
  69  * Get the HostImportModuleDynamically hook for the runtime.
  70  */
  71 extern JS_PUBLIC_API ModuleDynamicImportHook
  72 GetModuleDynamicImportHook(JSRuntime* rt);
  73
  74 /**
  75  * Set the HostImportModuleDynamically hook for the runtime to the given
  76  * function.
  77  *
  78  * If this hook is not set (or set to nullptr) then the JS engine will throw an
  79  * exception if dynamic module import is attempted.
  80  */
  81 extern JS_PUBLIC_API void SetModuleDynamicImportHook(
  82     JSRuntime* rt, ModuleDynamicImportHook func);
  83
  84 extern JS_PUBLIC_API bool FinishDynamicModuleImport(
  85     JSContext* cx, Handle<Value> referencingPrivate,
  86     Handle<JSString*> specifier, Handle<JSObject*> promise);
  87
  88 /**
  89  * Parse the given source buffer as a module in the scope of the current global
  90  * of cx and return a source text module record.
  91  */
  92 extern JS_PUBLIC_API JSObject* CompileModule(
  93     JSContext* cx, const ReadOnlyCompileOptions& options,
  94     SourceText<char16_t>& srcBuf);
  95
  96 /**
  97  * Parse the given source buffer as a module in the scope of the current global
  98  * of cx and return a source text module record.
  99  *
 100  * The "DontInflate" suffix and (semantically unobservable) don't-inflate
 101  * characteristic are temporary while bugs in UTF-8 compilation are ironed out.
 102  * In the long term this function will be renamed |JS::CompileModule| and will
 103  * just never inflate.
 104  *
 105  * NOTE: UTF-8 compilation is currently experimental, and it's possible it has
 106  *       as-yet-undiscovered bugs that the UTF-16 compilation functions do not
 107  *       have.  Use only if you're willing to take a risk!
 108  */
 109 extern JS_PUBLIC_API JSObject* CompileModuleDontInflate(
 110     JSContext* cx, const ReadOnlyCompileOptions& options,
 111     SourceText<mozilla::Utf8Unit>& srcBuf);
 112
 113 /**
 114  * Set a private value associated with a source text module record.
 115  */
 116 extern JS_PUBLIC_API void SetModulePrivate(JSObject* module,
 117                                            const Value& value);
 118
 119 /**
 120  * Get the private value associated with a source text module record.
 121  */
 122 extern JS_PUBLIC_API Value GetModulePrivate(JSObject* module);
 123
 124 /*
 125  * Perform the ModuleInstantiate operation on the given source text module
 126  * record.
 127  *
 128  * This transitively resolves all module dependencies (calling the
 129  * HostResolveImportedModule hook) and initializes the environment record for
 130  * the module.
 131  */
 132 extern JS_PUBLIC_API bool ModuleInstantiate(JSContext* cx,
 133                                             Handle<JSObject*> moduleRecord);
 134
 135 /*
 136  * Perform the ModuleEvaluate operation on the given source text module record.
 137  *
 138  * This does nothing if this module has already been evaluated. Otherwise, it
 139  * transitively evaluates all dependences of this module and then evaluates this
 140  * module.
 141  *
 142  * ModuleInstantiate must have completed prior to calling this.
 143  */
 144 extern JS_PUBLIC_API bool ModuleEvaluate(JSContext* cx,
 145                                          Handle<JSObject*> moduleRecord);
 146
 147 /*
 148  * Get a list of the module specifiers used by a source text module
 149  * record to request importation of modules.
 150  *
 151  * The result is a JavaScript array of object values.  To extract the individual
 152  * values use only JS_GetArrayLength and JS_GetElement with indices 0 to length
 153  * - 1.
 154  *
 155  * The element values are objects with the following properties:
 156  *  - moduleSpecifier: the module specifier string
 157  *  - lineNumber: the line number of the import in the source text
 158  *  - columnNumber: the column number of the import in the source text
 159  *
 160  * These property values can be extracted with GetRequestedModuleSpecifier() and
 161  * GetRequestedModuleSourcePos()
 162  */
 163 extern JS_PUBLIC_API JSObject* GetRequestedModules(
 164     JSContext* cx, Handle<JSObject*> moduleRecord);
 165
 166 extern JS_PUBLIC_API JSString* GetRequestedModuleSpecifier(
 167     JSContext* cx, Handle<Value> requestedModuleObject);
 168
 169 extern JS_PUBLIC_API void GetRequestedModuleSourcePos(
 170     JSContext* cx, Handle<Value> requestedModuleObject, uint32_t* lineNumber,
 171     uint32_t* columnNumber);
 172
 173 /*
 174  * Get the top-level script for a module which has not yet been executed.
 175  */
 176 extern JS_PUBLIC_API JSScript* GetModuleScript(Handle<JSObject*> moduleRecord);
 177
 178 }  // namespace JS
 179
 180 #endif  // js_Modules_h